Chakram is an API testing framework designed to perform end to end tests on JSON REST endpoints.
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.
- 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)
- 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
Awesome plugins from the community:
We would love to see more plugins! If you have a plugin, please add it to the list.
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
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.
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 = ;;
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
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 =expect = chakramexpect;;
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 =expect = chakramexpect;;
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:
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.
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:
Test results can be exported in multiple formats, Mocha's builtin formats are described here and export plugins for Mocha are available on NPM.
Issues, pull requests and questions are welcomed.
- 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
- Raise pull request