{"id":13624826,"url":"https://github.com/dareid/chakram","last_synced_at":"2025-05-15T06:06:29.233Z","repository":{"id":28063432,"uuid":"31560276","full_name":"dareid/chakram","owner":"dareid","description":"REST API test framework. BDD and exploits promises","archived":false,"fork":false,"pushed_at":"2022-02-03T10:04:53.000Z","size":2339,"stargazers_count":907,"open_issues_count":36,"forks_count":93,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-05-04T12:38:59.475Z","etag":null,"topics":["api-test","bdd","chai","javascript","mocha","promise-support","rest","test"],"latest_commit_sha":null,"homepage":"http://dareid.github.io/chakram/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dareid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-02T20:03:54.000Z","updated_at":"2025-04-11T05:56:26.000Z","dependencies_parsed_at":"2022-09-16T10:50:40.150Z","dependency_job_id":null,"html_url":"https://github.com/dareid/chakram","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dareid%2Fchakram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dareid%2Fchakram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dareid%2Fchakram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dareid%2Fchakram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dareid","download_url":"https://codeload.github.com/dareid/chakram/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283339,"owners_count":22045140,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-test","bdd","chai","javascript","mocha","promise-support","rest","test"],"created_at":"2024-08-01T21:01:46.891Z","updated_at":"2025-05-15T06:06:29.216Z","avatar_url":"https://github.com/dareid.png","language":"JavaScript","readme":"# Chakram\n\n[![Build Status](https://travis-ci.org/dareid/chakram.svg?branch=master)](https://travis-ci.org/dareid/chakram) [![Test Coverage](https://codeclimate.com/github/dareid/chakram/badges/coverage.svg)](https://codeclimate.com/github/dareid/chakram) [![Code Climate](https://codeclimate.com/github/dareid/chakram/badges/gpa.svg)](https://codeclimate.com/github/dareid/chakram) [![Gitter](https://img.shields.io/badge/gitter-join%20chat-brightgreen.svg)](https://gitter.im/dareid/chakram)\n\n**Chakram is no longer actively maintained, PRs are welcomed**\n\nChakram is an API testing framework designed to perform end to end tests on JSON REST endpoints.\n\nThe 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](https://nodejs.org/), [mocha](http://mochajs.org/), [chai](http://chaijs.com/) and [request](https://github.com/request/request).\n\nThis readme offers an introduction to the library. For more information, visit Chakram's [documentation](http://dareid.github.io/chakram/) and [tests](https://github.com/dareid/chakram/tree/master/test) which demonstrate all of Chakram's capabilities. In addition, example tests of publicly accessible APIs are available in the [examples directory](https://github.com/dareid/chakram/tree/master/examples). If required, assistance can be found in the project's [gitter chat room](https://gitter.im/dareid/chakram).\n\n## Features\n * HTTP specific assertions. Allows testing of:\n   * Status codes\n   * Cookie presence and value\n   * Header presence and value\n   * JSON values\n   * JSON structure (using the [JSON schema specification](http://json-schema.org/documentation.html))\n   * Compression\n   * Response times\n* BDD formatting and hooks (e.g. beforeEach, afterEach)\n* Promise based\n* Plugin support\n* Custom assertions\n* Exports results in a variety of formats\n* Debugging support\n\n## Plugins\nAwesome plugins from the community:\n - [Joi Schema Assertion](https://github.com/roberto/chakram-joi)\n\nWe would love to see more plugins! If you have a plugin, please add it to the list.\n\n## Getting Started\n\n### Install Chakram\nChakram 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:\n```js\nnpm install chakram --save-dev\n```\n\n### Writing Tests\n\nChakram builds on top of the mocha testing framework.  As such, the tests follow mocha's [BDD style](http://mochajs.org/#getting-started). The following sections introduce the various aspects of writing a Chakram test.\n\n#### Making Requests\n\nChakram makes use of the [request library](https://github.com/request/request) 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](http://dareid.github.io/chakram/jsdoc/module-chakram.html). The request methods return a promise which resolves to a [Chakram response object](http://dareid.github.io/chakram/jsdoc/global.html#ChakramResponse).\n\nBelow is an example of making a HTTP GET request:\n```js\nvar chakram = require('chakram');\n\ndescribe(\"Chakram\", function() {\n    it(\"should offer simple HTTP request capabilities\", function () {\n        return chakram.get(\"http://httpbin.org/get\");\n    });\n});\n```\n\n#### Testing Responses\n\nChakram 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.\n\nWhen 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](http://dareid.github.io/chakram/jsdoc/module-chakram-expectation.html). [Chai properties](http://chaijs.com/api/bdd/) can be used as a prefix to the assertion, improving the test's readability.\n\nThe 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](http://dareid.github.io/chakram/jsdoc/global.html#ChakramResponse) once the test has been performed.\n\nBelow is an example of testing the status code of a HTTP GET request:\n```js\nvar chakram = require('chakram'),\n    expect = chakram.expect;\n\ndescribe(\"Chakram\", function() {\n    it(\"should provide HTTP specific assertions\", function () {\n        var response = chakram.get(\"http://httpbin.org/get\");\n        return expect(response).to.have.status(200);\n    });\n});\n```\n\nIn addition to the HTTP specific assertions, chakram.expect exposes all of [Chai's BDD properties and methods](http://chaijs.com/api/bdd/). Documentation for the HTTP specific assertions can be seen [here](http://dareid.github.io/chakram/jsdoc/module-chakram-expectation.html).\n\n#### Waiting\n\nAs this library focuses on testing REST APIs, the tests are naturally asynchronous. Mocha has [native support for promises](http://mochajs.org/#asynchronous-code), 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](http://dareid.github.io/chakram/jsdoc/global.html#ChakramResponse). These promises can be returned to ensure the test waits for them to complete (as can be seen in the previous two examples).\n\nIt 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.\n\n```js\nvar chakram = require('chakram'),\n    expect = chakram.expect;\n\ndescribe(\"Chakram\", function() {\n    it(\"should provide a simple async testing framework\", function () {\n        var response = chakram.get(\"http://httpbin.org/get\");\n        expect(response).to.have.status(200);\n        expect(response).not.to.have.header('non-existing-header');\n        return chakram.wait();\n    });\n});\n```\n\n#### Complex Promise Use\n\nDue to the use of promises, complex tests can be written requiring chains of requests and assertions. An example can be seen below:\n\n```js\ndescribe(\"Chakram\", function () {\n  it(\"should support sequential API interaction\", function () {\n    var artist = \"Notorious B.I.G.\";\n    return chakram.get(\"https://api.spotify.com/v1/search?q=\"+artist+\"\u0026type=artist\")\n    .then(function (searchResponse) {\n      var bigID = searchResponse.body.artists.items[0].id;\n      return chakram.get(\"https://api.spotify.com/v1/artists/\"+bigID+\"/top-tracks?country=GB\");\n    })\n    .then(function (topTrackResponse) {\n      var topTrack = topTrackResponse.body.tracks[0];\n      expect(topTrack.name).to.contain(\"Old Thing Back\");\n    });\n  });\n});\n```\n\nChakram exposes three promise related methods:\n - [all](http://dareid.github.io/chakram/jsdoc/module-chakram.html#.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.\n - [wait](http://dareid.github.io/chakram/jsdoc/module-chakram.html#.wait), which returns a promise which is fulfilled once all Chakram expectations are fulfilled.\n - [waitFor](http://dareid.github.io/chakram/jsdoc/module-chakram.html#.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.\n\n### Running Tests\nTo run Chakram tests, install the Mocha testing framework globally (or as a dev dependency):\n```\nnpm install -g mocha\n```\nOnce installed, run the tests using the [Mocha command line](http://mochajs.org/#usage), which in its simplest form is:\n```\nmocha path/to/tests\n```\nTest results can be exported in multiple formats, Mocha's builtin formats are described [here](http://mochajs.org/#reporters) and export plugins for Mocha are available on NPM.\n\n### Adding Assertions\n\nNew assertions can be easily added to Chakram. The [plugin tests](https://github.com/dareid/chakram/blob/master/test/core/plugins.js) demonstrate how properties and methods can be added. Further information is available in [Chai's plugin documentation](http://chaijs.com/guide/plugins/).\n\n## Contributing\nIssues, pull requests and questions are welcomed.\n\n### Pull Requests\n\n - Fork the repository\n - Make changes\n - If required, write tests covering the new functionality (tests are normally written against [httpbin.org](http://httpbin.org/))\n - Ensure all tests pass and 100% code coverage is achieved (run `npm test`)\n - Raise pull request\n","funding_links":[],"categories":["javascript","JavaScript","Language-Specific API Testing Libraries","API Testing with Doc Features"],"sub_categories":["72. [Chakram](https://github.com/dareid/chakram)"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdareid%2Fchakram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdareid%2Fchakram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdareid%2Fchakram/lists"}