Document the APIs with Swagger (4/4) — Testing the API

In this series of articles, I will introduce the different Swagger tools. Swagger is a very handy tool for API documentation. It allows you to generate “living” documentation, so that the documentation is always up to date, which is very difficult to do without this kind of tool. It also allows to generate code automatically, allowing the developer to focus on his core business. Finally, it is based on an open source specification format.

These articles focus on Swagger 2.0, while the 3.0 version (“OpenAPI 3.0.0”) is available.

This article is thus broken down into four parts :

  • Introduction,
  • The Swagger framework,
  • Setting up the set,
  • The API test.

Basic API testing

To test the implementation of the Swagger specifications, you can use Dredd (

To install Dredd:

sudo npm install -g dredd --allow-root --unsafe-perm=true

Let’s run Dredd on our specification file:

dredd swagger.yaml --reporter html --reporter xunit

Creating a Mock Server

You can easily create a realistic Mock server with Prism.

Install Prism:

sudo npm install -g @stoplight/prism-cli

Let’s launch the Mock server:

prism mock swagger.yaml

Advanced API testing

To perform advanced testing of the API, we will use:

  • Mocha: it is a Javascript testing framework that facilitates asynchronous testing,
  • Chai: is an assertion library providing assert, expect and should methods,
  • SuperTest: is a library providing a high level abstraction for testing NodeJS API endpoint responses.

Let’s install these three libraries :

npm install chai
npm install supertest
sudo npm install -g mocha

In the project directory, let’s create a test file:

cd out
cat <<EOF> test.js
var should = require('chai').should(),
expect = require('chai').expect,
supertest = require('supertest'),
api = supertest('');
describe('Contact', function() {
  it('should return a 200 response', function(done) {
      .set('Accept', 'application/json')
  it('should return at least an id and a name', function(done) {
      .set('Accept', 'application/json')
      .end(function(err, res) {
  it('should return a 201 response', function(done) {'/contact')
      .set('Accept', 'application/json')

Now let’s run the tests:


Creating a Docker Image

Since we are now going to connect to the API web server from the container and not from the host, you need to change the API IP address in the Swagger specification file replacing the line:

api = supertest('');


api = supertest('http://XX.XX.XX.XX:8080');

XX.XX.XX.XX being the IP address of your host.

Create the Dockerfile file which allows you to generate a Docker:

cat <<EOF> Dockerfile
FROM node
RUN npm update
RUN npm install chai
RUN npm install supertest
RUN npm install -g mocha

Add an entry point shell:

cat <<EOF>
mocha test.js --reporter spec
cp report.xml /report
cp report.html /report

Generate the Docker image:

docker build -t supertest-api .

To use the Docker image, simply proceed as follows:

docker run --rm -v $PWD/app:/app -v $PWD/report:/report supertest-api

We have now discussed several approaches to testing Swagger specifications and their implementation.


Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now