Chakram is an API testing framework designed to test JSON REST endpoints. The library offers a BDD testing style and fully exploits javascript promises
npm install chakram-beinformeddocs folder of this project.
statusCode property on HTTP responses is now available under the status property;
_jar property but directly available on the root jar property of HTTP responses.
chakram.startDebug() and chakram.stopDebug()) no longer uses request-debug but instead now depend on a NodeJs EventEmitter.
startDebug() is now accepting a callback function with a single event argument.
js
npm install chakram --save-dev
`
$3
Chakram builds on top of the mocha testing framework. As such, the tests follow mocha's BDD style. The following sections introduce the various aspects of writing a Chakram test.
#### Making Requests
Chakram makes use of the request library and as such boasts a comprehensive request capability. Chakram exposes helper methods for the most common HTTP request verbs. The methods typically require the URL as the first parameter, the request body (if applicable) as the second parameter and any request options as an optional last parameter. For full documentation of the request methods see here. The request methods return a promise which resolves to a Chakram response object.
Below is an example of making a HTTP GET request:
`js
var chakram = require("chakram");
describe("Chakram", function () {
it("should offer simple HTTP request capabilities", function () {
return chakram.get("http://httpbin.org/get");
});
});
`
#### Testing Responses
Chakram offers a range of HTTP specific assertions which can test the information returned from API requests. Chakram offers a BDD testing style through Chakram's expect interface.
When testing API responses, pass the request promise as an argument into chakram.expect. This will return an object which exposes the Chakram and Chai assertions. Perform an assertion by calling the desired Chakram assertion method. Chai properties can be used as a prefix to the assertion, improving the test's readability.
The assertion is performed once the response is received (i.e. the request promise is fulfilled). Chakram assertions return a promise which resolve to a Chakram response object once the test has been performed.
Below is an example of testing the status code of a HTTP GET request:
`js
var chakram = require("chakram"),
expect = chakram.expect;
describe("Chakram", function () {
it("should provide HTTP specific assertions", function () {
var response = chakram.get("http://httpbin.org/get");
return expect(response).to.have.status(200);
});
});
`
In addition to the HTTP specific assertions, chakram.expect exposes all of Chai's BDD properties and methods. Documentation for the HTTP specific assertions can be seen here.
#### Waiting
As this library focuses on testing REST APIs, the tests are naturally asynchronous. Mocha has native support for promises, which Chakram exploits. Returning a promise from an it callback will cause the test to wait until the promise resolves before continuing. Chakram's requests and expectations return promises which fulfill to Chakram response objects. These promises can be returned to ensure the test waits for them to complete (as can be seen in the previous two examples).
It is important that tests wait for all requests and assertions to be completed. To help, chakram includes a wait method. This returns a promise which will be fulfilled once all assertions have been performed. Furthermore, Chakram will fail any tests which do not wait for assertions to complete. Below is a test using the wait method.
`js
var chakram = require("chakram"),
expect = chakram.expect;
describe("Chakram", function () {
it("should provide a simple async testing framework", function () {
var response = chakram.get("http://httpbin.org/get");
expect(response).to.have.status(200);
expect(response).not.to.have.header("non-existing-header");
return chakram.wait();
});
});
`
#### Complex Promise Use
Due to the use of promises, complex tests can be written requiring chains of requests and assertions. An example can be seen below:
`js
describe("Chakram", function () {
it("should support sequential API interaction", function () {
var artist = "Notorious B.I.G.";
return chakram
.get("https://api.spotify.com/v1/search?q=" + artist + "&type=artist")
.then(function (searchResponse) {
var bigID = searchResponse.body.artists.items[0].id;
return chakram.get(
"https://api.spotify.com/v1/artists/" + bigID + "/top-tracks?country=GB"
);
})
.then(function (topTrackResponse) {
var topTrack = topTrackResponse.body.tracks[0];
expect(topTrack.name).to.contain("Old Thing Back");
});
});
});
`
Chakram exposes three promise related methods:
- all, which takes an array of promises and returns a promise which is fulfilled once all promises in the provided array are fulfilled. The fulfillment value of the returned promise is an array of the fulfillment values of the promises which were passed to the function.
- wait, which returns a promise which is fulfilled once all Chakram expectations are fulfilled.
- waitFor, which takes an array of promises and returns a promise which is fulfilled once all promises in the provided array are fulfilled. This is similar to chakram.all, except it is fulfilled with the fulfillment value of the last promise in the provided array.
$3
To run Chakram tests, install the Mocha testing framework globally (or as a dev dependency):
`
npm install -g mocha
`
Once installed, run the tests using the Mocha command line, which in its simplest form is:
`
mocha path/to/tests
`
Test results can be exported in multiple formats, Mocha's builtin formats are described here and export plugins for Mocha are available on NPM.
$3
New assertions can be easily added to Chakram. The plugin tests demonstrate how properties and methods can be added. Further information is available in Chai's plugin documentation.
Contributing
Issues, pull requests and questions are welcomed.
$3
- Fork the repository
- Make changes
- If required, write tests covering the new functionality (tests are normally written against httpbin.org)
- Ensure all tests pass and 100% code coverage is achieved (run npm test`)