README

About

This package contains a PHP Dredd hook handler which provides a bridge between the Dredd API Testing Framework and PHP environment to ease implementation of testing hooks provided by Dredd. Write Dredd hooks in PHP to glue together API Blueprint with your PHP project

Not sure what these Dredd Hooks are? Read the Dredd documentation on them

The following are a few examples of what hooks can be used for:

• loading db fixtures
• cleanup after test step or steps
• handling authentication and sessions
• passing data between transactions (saving state from responses to stash)
• modifying request generated from blueprint
• changing generated expectations
• setting custom expectations
• debugging via logging stuff

Example

<?php

use Dredd\Hooks;

Hooks::beforeAll(function(&$transaction) {

    // do any necessary setup
});

Installing

Composer

Requirements

• Must have php version 7.2 or greater. Older versions of php may work but they are untested.

dredd-hooks-php can be easily installed through the use of Composer.

composer require ddelnano/dredd-hooks-php --dev

Usage

1. Create a hook file in hooks.php

use Dredd\Hooks;

Hooks::before("/test > GET", function(&$transaction) {

    // do any before setup necessary
});

Very Important Please make sure the closure passed to any Dredd\Hooks method uses a reference for the $transaction variable!! This is necessary so that the $transaction variable does not need to be returned from the closure in order to persist changes to the variable in the closure's local scope.

1. Run it with dredd

dredd apiary.apib localhost:3000 --language php --hookfiles ./hooks.php

API

The Dredd\Hooks class provides the following methods before, after, before_all, after_all, before_each, after_each, before_validation, and before_each_validation. These methods correspond to the events that Dredd will run as it makes requests to the API endpoints defined in the blueprint/apiary.apib file. The before, before_validation and after hooks are identified by transaction name

Wildcards

Must be using version 1.1 or higher

When writing hooks for different api endpoints its very common to need the same hook for similar endpoints. For instance when testing Admin features the request must be authenticated with a user that has admin privileges. For all hooks needing this instead of writing a hook for each one the following can be used.

Hooks::before('Admin > *', function(&$transaction) {

    // This will be executed for any transaction with name starting with 'Admin > '
});

This would execute for any transactions "nested" underneath 'Admin'. For example the following transaction names would execute the callback: 'Admin > Login', 'Admin > Test', etc.

How to Contribute

1. Fork it
2. Create your feature branch (git checkout -b my-newfeature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push (git push origin my-new-feature)
5. Create a new Pull Request

Tests

When making a contribution it is very important to not break existing functionality. This project uses PHPUnit for unit testing and uses nodejs for Cucumber tests.

Dependencies

• Docker. This takes care of the php and nodejs dependencies.

The test suite can be run by following these steps:

1. Run the phpunit and Cucumber tests

make test

More details about the integration test can be found in the dredd-hooks-template repo

Further Details

For examples and more information please visit the wiki