Dredd — HTTP API Validation Tool

Dredd is a command-line tool for validating API documentation written in API Blueprint format against its backend implementation. With Dredd you can easily plug your API documentation into the Continous Integration system like Travis CI or Jenkins and have API documentation up-to-date, all the time. Dredd uses the Gavel for judging if a particular API response is valid or if is not. If you are curious about how decisions are made, please refer to Gavel's behavior specification.

Installation

Node.js and NPM is required.

$ npm install -g dredd

Get Started Testing Your API

$ dredd blueprint.md http://api.myservice.tld

See dredd-example repo for real-life example.

Writing validatable blueprints

If you are using URI templates in your blueprint, you have to provide example values in the blueprint's URI parameter syntax to provide values for each URI parameter substitution. Every resource in the blueprint defined by URI template without specifying example values is not validatable, it's considered as an ambigous transaction and skipped. In case of any ambigous transaction Dredd will throw a warning and let you know which parameter example value is not defined in the blueprint.

Hooks

Dredd can be configured to use hookfiles to do basic setup/teardown between each validation (specified with the --hookfiles flag). Hookfiles can be in javascript or coffeescript, and must import the hook methods.

Requests are identified by their name, which is derived from the structure of the blueprint. You can print a list of the generated names with --names.

Example

Get Names:

$ dredd single_get.md http://machines.apiary.io --names
info: Machines > Machines collection > Get Machines

Write a hookfile:

{before, after} = require 'hooks'

before "Machines > Machines collection > Get Machines", (transaction) ->
  console.log "before"

after "Machines > Machines collection > Get Machines", (transaction) ->
  console.log "after"

Skipping a validation with hooks:

before "Machines > Machines collection > Get Machines", (transaction) ->
  transaction.skip = true

Run validation:

dredd single_get.md http://machines.apiary.io --hookfiles=*_hooks.*

Dredd also supports callbacks before and after all tests:

{beforeAll, afterAll} = require 'hooks'

beforeAll (done) ->
  # do setup
  done()

afterAll (done) ->
  # do teardown
  done()

If beforeAll and afterAll are called multiple times, the callbacks are executed serially in the order they were called.

Command Line Options

$ dredd --help
Usage:
  dredd <path to blueprint> <api_endpoint> [OPTIONS]

Example:
  dredd ./apiary.md http://localhost:3000 --dry-run

Options:
  --hookfiles, -f      Specifes a pattern to match files with before/after
                       hooks for running tests                   [default: null]
  --names, -n          Only list names of requests (for use in a hookfile). No
                       requests are made.                       [default: false]
  --reporter, -r       Output additional report format. This option can be used
                       multiple times to add multiple reporters. Options:
                       junit, nyan, dot, markdown, html.
                                                                   [default: []]
  --output, -o         Specifies output file when using additional file-based
                       reporter. This option can be used multiple times if
                       multiple file-based reporters are used.
                                                                   [default: []]
  --header, -h         Extra header to include in every request. This option
                       can be used multiple times to add multiple headers.
                                                                   [default: []]
  --sorted, -s         Sorts requests in a sensible way so that objects are not
                       modified before they are created. Order: CONNECT,
                       OPTIONS, POST, GET, HEAD, PUT, PATCH, DELETE, TRACE.
                                                                [default: false]
  --user, -u           Basic Auth credentials in the form username:password.
                                                                 [default: null]
  --inline-errors, -e  Determines whether failures and errors are displayed as
                       they occur (true) or agregated and displayed at the end
                       (false).
                                                                [default: false]
  --details, -d        Determines whether request/response details are included
                       in passing validations.
                                                                [default: false]
  --method, -m         Restrict tests to a particular HTTP method (GET, PUT,
                       POST, DELETE, PATCH). This option can be used multiple
                       times to allow multiple methods.
                                                                   [default: []]
  --color, -c          Determines whether console output should include colors.
                                                                 [default: true]
  --level, -l          The level of logging to output. Options: silly, debug,
                       verbose, info, warn, error.
                                                               [default: "info"]
  --timestamp, -t      Determines whether console output should include
                       timestamps.
                                                                [default: false]
  --help               Show usage information.
  --version            Show version number.

Additionally, boolean flags can be negated by prefixing no-, for example: --no-color --no-inline-errors.

Contribution

Any contribution is more then welcome! Let's start with creating your own virtual development environment, then fork, write tests, write clean, readable code which communicate, use scripts/bdd, keep the test coverage and create a pull request. :)

Make sure to follow Dredd issues page.

To learn more about the future of API Blueprint & Testing visit apiaryio/api-blueprint#21.