chakram

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. The library is built on node.js, mocha and chai.

More information is available in the library's documentation and its own tests which demonstrate all of Chakram's capabilities. Example API tests of publically accessable APIs are available in the examples directory.

Install Chakram

Chakram requires nodejs and NPM to be installed, it is available as an NPM module. Ideally, Chakram should be added to your testing project's devDependancies. This can be achieved with the following command:

npm install chakram --save-dev

Introduction

Chakram builds on top of the mocha testing framework, as such, the tests follow the BDD style. As this library focuses on testing REST APIs, the tests are naturally asynchronous. Mocha has native support for promises which Chakram exploits. All requests and expectations return promises which fulfill to Chakram response objects.

The example below demonstrates a GET request and an assertion of the returned status code. The assertion of the status code returns a promise which is fulfilled once the status code has been checked.

var chakram = require('chakram'),
    expect = chakram.expect;

describe("Minimal example", function() {    
    it("should provide a simple async testing framework", function () {
        var response = chakram.get("http://httpbin.org/get");
        return expect(response).to.have.status(200);
    });
});

Below is a larger example testing the Random User Generator API.

var chakram = require('chakram'),
    expect = chakram.expect;

describe("Random User API", function() {
    var apiResponse;
    
    before(function () {
        apiResponse = chakram.get("http://api.randomuser.me/?gender=female");
    });
    
    it("should return 200 on success", function () {
        return expect(apiResponse).to.have.status(200);
    });
    
    it("should return content type and server headers", function () {
        expect(apiResponse).to.have.header("server");
        expect(apiResponse).to.have.header("content-type", /json/);
        return chakram.wait();
    });
    
    it("should include email, username, password and phone number", function () {
        return expect(apiResponse).to.have.schema('results[0].user', {
            "required": [
                "email", 
                "username", 
                "password", 
                "phone"
            ]
        });
    });
    
    it("should return a female user", function () {
        return expect(apiResponse).to.have.json('results[0].user.gender', 'female');
    });
    
    it("should return a valid email address", function () {
        return expect(apiResponse).to.have.json(function(json) {
            var email = json.results[0].user.email;
            expect(/\S+@\S+\.\S+/.test(email)).to.be.true;
        });
    });
    
    it("should return a single random user", function () {
        return expect(apiResponse).to.have.schema('results', {minItems: 1, maxItems: 1});
    }); 
    
    it("should not be gzip compressed", function () {
        return expect(apiResponse).not.to.be.encoded.with.gzip;
    });
    
    it("should return a different username on each request", function () {
        this.timeout(10000);
        var multipleResponses = [];
        for(var ct = 0; ct < 5; ct++) {
            multipleResponses.push(chakram.get("http://api.randomuser.me/?gender=female"));
        }
        return chakram.all(multipleResponses).then(function(responses) {
            var returnedUsernames = responses.map(function(response) {
                return response.body.results[0].user.username;
            });
            while (returnedUsernames.length > 0) {
                var username = returnedUsernames.pop();
                expect(returnedUsernames.indexOf(username)).to.equal(-1);
            }
        });
    });
});

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. In addition, 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("Minimal example", 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();
    });
});

Run Tests

To run Chakram tests, install the Mocha testing framework globally (or as a dev dependancy):

npm install -g mocha

Once installed, run the tests using the Mocha command line, which in its simplest form is:

mocha path/to/tests