Chakram

Chakram is an API testing framework designed to perform end to end tests on JSON REST endpoints.

The library offers a BDD testing style and fully exploits javascript promises - the resulting tests are simple, clear and expressive. Chakram is built on node.js, mocha, chai and request.

This readme offers an introduction to the library. For more information, visit Chakram's documentation and tests which demonstrate all of Chakram's capabilities. In addition, example tests of publicly accessible APIs are available in the examples directory. If required, assistance can be found in the project's gitter chat room.

Features

HTTP specific assertions. Allows testing of:

Status codes
Cookie presence and value
Header presence and value
JSON values
JSON structure (using the JSON schema specification)
Compression
Response times

BDD formatting and hooks (e.g. beforeEach, afterEach)
Promise based
Plugin support
Custom assertions
Exports results in a variety of formats
Debugging support

Plugins

Awesome plugins from the community:

Joi Schema Assertion

We would love to see more plugins! If you have a plugin, please add it to the list.

Getting Started

Install Chakram

Chakram requires Node.js and npm to be installed. It is available as an npm module. Ideally, Chakram should be added to your testing project's devDependencies. This can be achieved with the following command:

npm install chakram --save-dev

Writing Tests

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:

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:

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.

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:

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.

Running Tests

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.

Adding Assertions

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.

Pull Requests

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)
Raise pull request

dfmaloney/chakram