Fluent (i.e. chainable) syntax for generating vows tests against RESTful APIs.
A fluent (i.e. chainable) syntax for generating vows tests against RESTful APIs.
$ curl | sh
$ [sudo] npm install api-easy
Most of the documentation for this library is available through the annotated source code, available here thanks to jashkenas and docco. If you're not feeling up for that, just keep reading here. tldr;? Read how to use APIeasy in your own projects
If you're going to use APIeasy (and I hope you do), it's worth taking a moment to understand the way that vows manages flow control. Read up here on vowsjs.org (Under "Structure of a test suite"), or just remember vows uses this grammatical structure:
Suite → Batch*Batch → Context*Context → Topic? Vow* Context*
Got it? Good. There is a 1-to-1 relationship between a APIeasy suite and a vows suite; APIeasy is essentially a simpler syntax to manage a particular set of vows-based tests that conform to this pattern:
- Tests are performed by making HTTP requests against an API server
- Assertions are made against the HTTP response and JSON response body
- Rinse. Repeat.
Here's a sample of the boilerplate code that APIeasy eliminates:
var request = require'request'vows = require'vows'assert = require'assert';vowsdescribe'your/awesome/api'addBatch"When using your awesome api":"and your awesome resource":"A POST to /awesome":requesturi: ''method: 'POST'body: JSONstringify test: 'data'headers:'Content-Type': 'application/json'thiscallbackassertequalresstatusCode 200;var result = JSONparsebody;assertequalresultok true;assertincluderesheaders 'x-test-header';exportmodule;
This same code can be implemented like this using APIeasy:
var APIeasy = require'api-easy'assert = require'assert';var suite = APIeasydescribe'your/awesome/api';suitediscuss'When using your awesome API'discuss'and your awesome resource'use'localhost' 8080setHeader'Content-Type' 'application/json'post'/awesome' test: 'data'expect200 ok: trueexpect'should respond with x-test-header'assertincluderesheaders 'x-test-header';exportmodule;
There are two ways to use APIeasy in your own project:
- Using npm
- Using vows directly
"dependencies":"api-easy": "0.2.x""scripts":"test": "vows test/*-test.js"
test/*-test.js is at your discretion. It's just an expression for all test files in your project.
After adding this to your
package.json file you can run the following to execute your tests:
$ cd path/to/your/project$ npm install$ npm test
There is also a full working sample of how to use this approach here.
When you install APIeasy or take it as a dependency in your
package.json file it will not install vows globally, so to use vows you must install it globally.
$ [sudo] npm install vows -g
After installing vows you can simply run it from inside your project:
$ cd /path/to/your/project$ vows
- Get feedback on what else could be exposed through this library.
- Improve it.
- Repeat (1) + (2).