Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fluent (i.e. chainable) syntax for generating vows tests against RESTful APIs.
tag: v0.1.0

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


A fluent (i.e. chainable) syntax for generating vows tests against RESTful APIs.


Installing npm (node package manager)

  curl | sh

Installing RESTeasy

  [sudo] npm install rest-easy


RESTeasy is designed to be a simple way to test RESTful APIs in node.js and Javascript. The primary design goal was to reduce the number of lines of test code required to fully cover all primary and edge use cases of a given API over HTTP.

Getting Started

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.

If you're going to use RESTeasy (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 (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 RESTeasy suite and a vows suite; RESTeasy is essentially a simpler syntax to manage a particular set of vows-based tests that conform to this pattern:

  1. Tests are performed by making HTTP requests against an API server
  2. Assertions are made against the HTTP response and JSON response body
  3. Rinse. Repeat.

Here's a sample of the boilerplate code that RESTeasy eliminates:

  var request = require('request'),
      vows = require('vows'),
      assert = require('assert');
    "When using your awesome api": {
      "and your awesome resource": {
        "A POST to /awesome": {
          topic: function () {
              uri: 'http://localhost:8080/awesome',
              method: 'POST',
              body: JSON.stringify({ test: 'data' }),
              headers: {
                'Content-Type': 'application/json'
            }, this.callback)
          "should respond with 200": function (err, res, body) {
            assert.equal(res.statusCode, 200);
          "should respond with ok": function (err, res, body) {
            var result = JSON.parse(body);
            assert.equal(result.ok, true);
          "should respond with x-test-header": function (err, res, body) {
            assert.include(res.headers, 'x-test-header');

This same code can be implemented like this using RESTeasy:

  var RESTeasy = require('rest-easy'),
      assert = require('assert');
  var suite = RESTeasy.describe('your/awesome/api');
  suite.discuss('When using your awesome API')
       .discuss('and your awesome resource')
       .use('localhost', 8080)
       .setHeader('Content-Type', 'application/json')
       .post({ test: 'data' })
         .expect(200, { ok: true })
         .expect('should respond with x-test-header', function (err, res, body) {
           assert.include(res.headers, 'x-test-header');


  1. Get feedback on what else could be exposed through this library.
  2. Improve it.
  3. Repeat (1) + (2).

Run Tests

  vows test/*-test.js --spec

Author: Charlie Robbins

Something went wrong with that request. Please try again.