|
Testing and Documenting Node.js APIs with Mocha and Acquit
By: Valeri Karpov
When people build REST APIs with Express, testing and documentation are often an afterthought. The situation with testing your documentation is often even worse. When’s the last time you built an automated testing system for your documentation’s examples? When I sat down to write acquit, I wanted a simple tool to generate documentation from mocha tests for mongoose. But, the paradigm of generating documentation from tests is even more useful for API-level integration tests. In this article, I’ll explain what API-level integration tests are and how to use acquit to parse integration tests into documentation.
API-Level Integration Tests
You may have seen the testing pyramid before:
pyramid
The components of the testing pyramid are described below.
“Unit tests” test individual units of code in isolation (for instance, individual functions). They are fast and you usually have a lot of them.
“Integration tests” test the integrations between different units, for example the interaction between one module and its dependencies.
“E2E (or end-to-end) tests” test the system as a whole, from the UI down to the data store, and back.
The concept of an “integration test” is flexible depending on your application and choice of testing paradigm. In this article, you will be primarily concerned with integration tests that test your REST API as a whole. If your entire product is a REST API then you may consider this an E2E test. But, for the purposes of this article, these tests will be called “API-level integration tests.”
How are you going to write API-level integration tests for Express? The NodeJS concurrency model makes writing API-level integration tests simple. The key idea is that your mocha tests can start and stop an Express server. Once your mocha tests start a server, the same process can use an HTTP client (for example, request or superagent) to send requests to your Express server. No need for any messy multithreading.
For this article, you’ll be using the acquit-example repo as an example. This repo defines a trivial REST API in the server.js file. There’s one route: the GET /user/:user route, which returns a user object if the username is in the list, and an HTTP 404 otherwise.
var express = require('express');
var status = require('http-status');
var users = require('./users');
var createServer = function(port) {
var app = express();
app.get('/user/:user', function(req, res) {
if (users.list.indexOf(req.params.user) === -1) {
return res.status(status.NOT_FOUND).
json({ error: 'Not Found' });
}
res.json({ user: req.params.user });
});
return app.listen(port);
};
module.exports = createServer;
http-status defines a map from readable HTTP status names to numeric codes. For instance, NOT_FOUND === 404. This module, while simple, is a module that I’d never write a web server without.
The users.js file included in the above code example is a stub for a real database. In a real application you’d probably want to install MongoDB and Mongoose, but the extra setup would just add extra overhead to this example. The users.js file is shown below.
exports.list = [
'user1',
'user2'
];
Nothing too fancy, but, as you’ll see, enough to enable tests to manipulate the list of users. Another key advantage of API-level integration tests in NodeJS is that you can re-use the same database interface you already use in your code. In other words, you can use Mongoose or whatever your database interface of choice is to insert data for each test within mocha’s elegant flow control. In this case, tests can require() the same users.js file and manipulate the underlying list of users as shown in the test/api-integration.test.js file below.
Generating Documentation from Tests
API-level integration tests are a cool concept that might not be obvious to people from Java or C++ backgrounds (myself included), but there’s nothing new there. The application of API-level integration tests to documentation, though, is much more novel.
In this section, you’ll learn about the acquit module, a lightweight tool to generate documentation from mocha tests. Acquit started out as a tool to generate docs for Mongoose’s browser component: I wanted documentation with examples that I knew would work as advertised in IE9. Dusting off my Windows laptop and hitting F12 repeatedly was not a viable approach. Since then, I’ve used it to generate documentation for numerous npm modules, including mongoose-autopopulate, kareem, and even acquit itself. When connected to API-level integration tests, you have a mechanism to generate well-tested documentation for your REST API.
All the work necessary to integrate acquit for docs generation is in this GitHub commit. The key work is in the docs.js file:
Full article...
Other Resource
... to read more articles, visit http://sqa.fyicenter.com/art/
| 