Testing a RESTful API using Supertest

Standard

This post explains how to test a RESTful API using Supertest.

There are many great blog posts that explain how to test NodeJS Express API’s using Supertest. For example:

This post explains how Supertest can be used to test any RESTful API even those that don’t run through express.

Setup

You will need a couple of node packages to get going including:

  • Supertest – “High-level abstraction module for testing HTTP”
  • Mocha – “Mocha is a simple, flexible, fun JavaScript test framework for node.js and the browser”
  • chai – “Chai is a BDD / TDD assertion library for node and the browser that can be delightfully paired with any javascript testing framework.”

Once installed your package.json should look something like this:

{
"name": "supertester",
"version": "1.0.0",
"description": "example project to demonstrate super test library for integration tests",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "TobyTheTester",
"license": "ISC",
"devDependencies": {
"supertest": "^1.2.0"
"chai": "^3.5.0",
},
"directories": {
},
"dependencies": {
}
}

view raw
package.json
hosted with ❤ by GitHub

Testing API

To try out Supertest i tested http://postcodes.io/ – Postcode & Geolocation API for the UK

Searching for a single Post Code (GET Method)

APIhttp://api.postcodes.io/postcodes/SW1A1AA

In this method the user can query the Post Code data for a single post code. If valid, the API returns further detail.

In the tests below you can see a basic example that calls the API with a given Post Code and then performs assertions on the response. You can see in all three cases i’m checking the Status Code of the response and also inspecting the JSON response to ensure the correct data has been returned.

var request = require('supertest')("http://api.postcodes.io");
var expect = require('chai').expect;
describe("Look up a specific post code", function () {
it("locates correct post code when given valid post code", function (done) {
request
.get('/postcodes/' + "SW1A 1AA")
.expect(200)
.end(function (err, res) {
expect(res.body.result.postcode).to.equal("SW1A 1AA");
done();
});
})
it("returns 400 when no post code is provided", function (done) {
request
.get('/postcodes/')
.expect(200)
.end(function (err, res) {
expect(res.body.status).to.equal(400);
done();
});
})
it("returns 404 when no post code is provided", function (done) {
request
.get('/postcodes/' + 'AB123')
.expect(200)
.end(function (err, res) {
expect(res.body.status).to.equal(404);
expect(res.body.error).to.equal("Postcode not found")
done();
});
})
});

view raw
test.js
hosted with ❤ by GitHub

Searching for multiple Post Codes (POST Method)

To search for multiple Post Codes we need to POST an array of Post Codes to the API. To do this we pass in a JSON object to the service, in this example three post codes.

You can see we are again checking the status code of the response. In addition as multiple post codes are returned we iterate through the response to ensure the results match our search.

var request = require('supertest')("http://api.postcodes.io");
var expect = require('chai').expect;
describe("Bulk post Code lookup", function () {
it("returns an array of post codes", function (done) {
request
.post('/postcodes')
.send({
"postcodes": ["SW1A 0AA", "SW1A 0PW", "SW1A 1AA"]
})
.expect(200)
.end(function (err, res) {
for (i = 0; i < res.body.result.length; i++) {
console.log(res.body.result[i].query)
expect(res.body.result[i].query).to.equal(res.body.result[i].result.postcode)
}
done();
});
});
it("returns null when an invalid post code is submitted", function (done) {
request
.post('/postcodes')
.send({
"postcodes": ["AB123"]
})
.expect(200)
.end(function (err, res) {
expect(res.body.result[0].result).to.equal(null)
done();
});
});
it("returns 400 when invalid json is submitted", function (done) {
request
.post('/postcodes')
.send({
})
.expect(400)
.end(function (err, res) {
expect(res.body.status).to.equal(400);
expect(res.body.error).to.equal("Invalid JSON submitted. You need to submit a JSON object with an array of postcodes or geolocation objects")
done();
});
})
});

view raw
test.js
hosted with ❤ by GitHub

Summary

Supertest is really easy to use. You can very quickly write a series of tests for your API. Posting data and inspecting responses is very easy.

At this point i haven’t tried with a secure API that requires authentication but the documentation suggests that this shouldn’t be a problem.

2 thoughts on “Testing a RESTful API using Supertest

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s