Installation

There are several options how to run Dredd on your machine or in your Continuous Integration.

Docker

If you are familiar with Docker, you can get started with Dredd quickly by using the ready-made apiaryio/dredd image. Specifics of running Dredd inside Docker are:

Following line runs the dredd command using the apiaryio/dredd Docker image:

$ docker run -it -v $PWD:/api -w /api apiaryio/dredd dredd

As an example of how to pass arguments, following line runs the dredd init command:

$ docker run -it -v $PWD:/api -w /api apiaryio/dredd dredd init

When testing a service running on host (e.g. localhost:8080), you need to use --network host parameter in Docker command. If you are using Docker for Mac, you should use host.docker.internal instead of 127.0.0.1/localhost.

Following line runs the dredd command using the apiaryio/dredd Docker image:

C:\Users\Susan> docker run -it -v ${pwd}:/api -w /api apiaryio/dredd dredd

As an example of how to pass arguments, following line runs the dredd init command:

C:\Users\Susan> docker run -it -v ${pwd}:/api -w /api apiaryio/dredd dredd init

Docker Compose

Inside Docker it’s impossible for Dredd to manage child processes, so the --server and --language options won’t work properly.

Instead, you should have separate containers for each process and run them together with Dredd using Docker Compose. You can use --abort-on-container-exit and --exit-code-from with Docker Compose to manage the tear down of all the other containers when the Dredd tests finish.

npm

Dredd is a command-line application written in JavaScript (to be more precise, in Node.js) and as such can be installed using npm.

Installing Node.js and npm

  • If you’re using Homebrew, run brew install node

  • Otherwise download Node.js from the official website and install it using the downloaded installer

  • Make sure both node --version and npm --version work in your Terminal

  • Node.js needs to be at least version 8

  • Download Node.js from the official website and install it using the downloaded installer

  • Make sure both node --version and npm --version work in your Command Prompt

  • Node.js needs to be at least version 8

Note

If your internet connection is restricted (VPN, firewall, proxy), you need to configure npm:

npm config set proxy "http://proxy.example.com:8080"
npm config set https-proxy "https://proxy.example.com:8080"

Otherwise you’ll get similar errors during Dredd installation:

npmERR! Cannot read property 'path' of null
npmERR!code ECONNRESET
npmERR!network socket hang up

Later be sure to read how to set up Dredd to correctly work with proxies.

Installing Dredd

Now that you have everything prepared, you can finally run npm to install Dredd:

npm install dredd --global

Note

If you get EACCES permissions errors, try one of the officially recommended solutions. In the worst case, you can run the command again with sudo.

You can verify Dredd is correctly installed by printing its version number:

dredd --version

Now you can start using Dredd!

Adding Dredd as a dev dependency

If your API project is also an npm package, you may want to add Dredd as a dev dependency instead of installing it globally.

  • Make sure your project is an npm package with a package.json file

  • In the root of the project run npm install dredd --save-dev

  • Once the installation is complete, you can run Dredd from the root of the project as npx dredd

This is how Dredd is installed in the dredd-example repository, so you may want to see it for inspiration.