A REST API unit testing framework
Wrestle enables you to unit test and automatically document your API from the command line or the browser by specifying intuitive, unit tests for each route.
- Simple unit test defintion.
- Run tests in the browser or from the command line.
- Generate documentation (with themes) from the test spec.
Install Wrestle with npm.
$ npm install wrestle -g
Defining tests with Wrestle is as simple as defining the route, the HTTP method and the expected JSON response.
Wrestle tests can be executed from the command line by simple supplying the file to the
wrestle test command then run the tests.
$ wrestle test path/to/tests.js
Wrestle tests can also be run in the browser. Define your tests and include
browser/interface.js and the test file.
There are a couple of caveats however due to the Cross-Origin Resource Sharing (CORS) policy which doesn't allow cross-domain requests (or in fact any requests from a static page) so the following options to enable testing in the browser.
- Host and run the tests under the same domain as the API.
- Start Chrome with the
--disable-web-securityflag to disable the CORS security.
- Enable CORS in your API's headers.
wrestle -- Simple REST API testing help Shows this help. test <file> Run a test file. --simple Simple output report --report Just output report --i x..y Run tests numbers x through to y --i x, y, z Run tests x, y, z only doc <file> Output API documentation --theme <theme> Output documentation with theme from doc/theme/ --output <path> Specify output path for documentation. Defaults to test file directory.
Test defintion API
wrestle.describe( <string> )
Describe a test case. This is the
description variable in the documentation generator
wrestle.method( <path>, <data> )
Create a test case for a GET, PUT, POST or DELETE HTTP method.
path can contain variables expanded by
data is the request data to be passed along to the server. Data specified alongside the GET method will be converted to URL parameters.
<test>.expect( <code>, <responseSchema>, <callback> )
Define the response schema for a test.
code is the expected HTTP status code.
responseSchema is the schema for the JSON response, see
wrestle.schema for a full description on defining schemas.
wrestle.<request|response>.schema( <method>, <code>, <responseSchema> )
Define a schema for request data or JSON response that matches either the request method, HTTP status code or both. A schema is an object that defines a set of rules another a request or response object must conform to. Wrestle loops over the object and tests if the property exists in the schema and that the property's value is of the same type as the schema or matches a regular expression. Schemas can contain variables which will be replaced by values when the request is executed (variables are defined using
wrestle.define( <name>, <value> )
Define a variable for use within schemas or paths which can be accessed using the
wrestle.on( <event>, <callback> )
Add an event listener to the test suite using
.addEventListener. Below is a list of events and the details sent to them.
|test||A new test has begun testing.||test|
|begin||Testing has begun.|
|end||All tests have been completed.||report|
|paused||Testing has been paused|
|error||An error has occured.|
Below is the list of events sent to a test. These can be binded to the test sent when the
test event above is called.
|start||A new test has started.|
|pass||A test has passed.||status, response|
|fail||A test has failed.||err, status, response|
|finish||A test has been completed.||err, status, response|
wrestle.begin( [x, y, x] | [upper, lower] )
Begin testing. Optionally pass in array of test indexs or bound to only run selected tests.
Wrestle can compile your API spec into some pretty informative documentation. It does this with a Mustache templating system. As is matures, more complex data will be passed into the documentation and maybe even a selection of templating engines but for now, it's fairly basic. Below is a table of all the variables passed into the theme. See the Mustache.js documentation for some help in theme formatting.
|rules||Array of API rules.|
|rule.method||API rule HTTP method.|
|rule.path||Path with emphasis on variables.|
|rule.description||Description of the API rule.|
|rule.parameters||Parameters sent along with request to the server.|
|rule.response||Respone recieved from request.|
|version||The current version of wrestle|
- Create a GUI for the browser