APIeasy

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

Installation

Installing npm (node package manager)

  curl http://npmjs.org/install.sh | sh

Installing APIeasy

  [sudo] npm install api-easy

Purpose

APIeasy 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 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');
  
  vows.describe('your/awesome/api').addBatch({
    "When using your awesome api": {
      "and your awesome resource": {
        "A POST to /awesome": {
          topic: function () {
            request({
              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');
          }
        }
      }
    }
  }).export(module);

This same code can be implemented like this using APIeasy:

  var APIeasy = require('api-easy'),
      assert = require('assert');
      
  var suite = APIeasy.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');
         })
       .export(module);

Roadmap

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

Run Tests

  vows test/*-test.js --spec

ress/api-easy