Cross-Language Test Suite for Dredd Hooks Handlers

Dredd is a tool for testing web APIs. It supports hooks written in many languages. To support a particular language, it needs an adapter, so-called hooks handler. This BDD test suite ensures that the public interface of each hooks handler works as Dredd expects. The test suite is written in Gherkin and uses Cucumber as a test runner.

To use the test suite, first read the docs about how to create a new hooks handler for Dredd. Implement your hooks handler and then continue with the following guide.

Installation

1. Make sure you have Node.js (ideally version 10 or higher) and npm available.

2. Create a package.json file in the root of your project. This is where your JavaScript dependencies are going to be specified:

   {
     "scripts": { "test": "dredd-hooks-template test" },
     "private": true
   }

3. Run npm install dredd-hooks-template --save-dev --save-exact to install and declare this test suite as your development dependency.

4. Run npx dredd-hooks-template init to get a copy of the test suite in the ./features directory.

5. Open the feature files in ./features/*.feature and in all of them

   • replace {{my-executable-path}} with a path to your hooks handler executable which you want to get tested (e.g. ./bin/dredd_hooks)
   • replace {{my-extension}} by the extension of the hooks handler language (e.g. .py),
   • uncomment the code blocks and rewrite them to the hooks handler language.

Now you have the test suite ready.

Usage

Every time you run npx dredd-hooks-template test (or npm test), you should see the test suite running. The end goal is that all the tests pass:

You should add the package.json file to Git. When starting from scratch, you can run npm install to install the JavaScript dependencies.

Upgrading

Watch for newer versions of the dredd-hooks-template package and upgrade regularly to keep up with development of Dredd and the test suite itself. To upgrade, run:

$ npx dredd-hooks-template upgrade

It upgrades the package to the latest version and copies the latest feature files to the project's ./features/ directory. It won't overwrite the existing files as the names of the new files get suffixed with version. Then it's up to you to compare the old and new files, spot changes, and update the project's test suite.

Reference Implementations

The Python hooks and the Ruby hooks can be used as examples of how to use this cross-language test suite.

Keep Tests Running with CI

To make sure the hooks handler will always work correctly with Dredd and the expectations won't get accidentally broken, put the tests into Travis CI, which runs the tests for each change on your repository. See existing configuration files for inspiration:

• Python: .travis.yml
• Ruby: .travis.yml