Quickstart

In following tutorial you can quickly learn how to test a simple HTTP API application with Dredd. The tested application will be very simple backend written in Express.js.

Install Dredd

$ npm install -g @stacklych/dredd

If you’re not familiar with the Node.js ecosystem or you bump into any issues, follow the installation guide.

Document Your API

First, let’s design the API we are about to build and test. That means you will need to create an API description file, which will document how your API should look like. Dredd supports OpenAPI 3.0, 3.1, and 3.2 (API Blueprint and OpenAPI 2 are no longer supported).

Create a file called api-description.yaml with the following content:

openapi: 3.1.0
info:
  version: '1.0'
  title: Example API
  license:
    name: MIT
paths:
  /:
    get:
      responses:
        '200':
          description: ''
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message

Note

The same description works as OpenAPI 3.0 — set openapi: 3.0.3 instead. Dredd validates response data types for both versions.

Implement Your API

As we mentioned in the beginning, we’ll use Express.js to implement the API. Install the framework by npm:

$ npm init
$ npm install express --save

Now let’s code the thing! Create a file called app.js with following contents:

var app = require('express')();

app.get('/', function(req, res) {
  res.json({message: 'Hello World!'});
})

app.listen(3000);

Test Your API

At this moment, the implementation is ready to be tested. Let’s run the server as a background process and let’s test it:

$ node app.js &

Finally, let Dredd validate whether your freshly implemented API complies with the description you have:

$ dredd api-description.yaml http://127.0.0.1:3000

Configure Dredd

Dredd can be configured by many CLI options. It’s recommended to save your Dredd configuration alongside your project, so it’s easier to repeatedly execute always the same test run. Use interactive configuration wizard to create dredd.yml file in the root of your project:

$ dredd init
? Location of the API description document: api-description.yaml
? Command to start API backend server e.g. (bundle exec rails server)
? URL of tested API endpoint: http://127.0.0.1:3000
? Dredd is best served with Continuous Integration. Create CircleCI config for Dredd? Yes

Now you can start test run just by typing dredd!

$ dredd

Use Hooks

Dredd’s hooks enable you to write some glue code in JavaScript to support enhanced scenarios in your API tests. Read the documentation about hooks to learn more on how to write them.