pua

pua.js

An unit test library for RESTful API. The main goals of this library are to make unit test script simple and intuitive. It makes your test code easy to create, read and maintaince.

All the test cases are running in the order they are added. New test cases can be added dynamically.

The result from a test case can be set to a collection in stead of passing to next test case by parameters to make handler funciton simple.

FAQ

Examples for version 2.0.x

The version 1 is still not so convenient. I revised it to version 2. It use a better way to add test case. One test case is an array of parameters. All the usage are shown in the following example. It will stop when any test case with bad syntax.

/*********************************
Terms used in examples:
 - actor: object, user object including { "id": "[e-mail]", "auth": "authorization_string" }
 - action: string, request description, for example "get my contact".
 - reqUrl: string, request method and URL, for example "GET /my/contact".
 - expect: number, expect response status code as 200. The default value is 200
 - payload: JSON, text or Buffer. 
 - handler: a function with prototype function(err, res, t). This function MUST be a synchronous function.
 - headers: object, extra request headers other than Authorization, for example {"content-type": "image/jpeg"}.
*/

// test.js
var options = {
  mode: 'interactive', // 'interactive' or 'auto'. 'auto' is the default mode
  api_url: 'https://abc.xyz.com/api/v2', // base URL of the RESTful-API server.
  response_time_threshold: 500 // expected respionse time in miliseconds
};

require('pua')
.setup(options)
.add(require('./example'))
.run();

// example.js
var pua = require('pua');
var user1 = {id: '[e-mail]', auth: 'Authorization'};
var user2 = {id: '[e-mail]', auth: 'Authorization'};

exports.subject = 'Pua Examples';
exports.tasks = [ //Test cases begin from here

// Get groups and expect 200
[user1, 'get all groups', 'GET /groups'],

// Get groups and expect 404
[user1, 'get all groups', 'GET /groups', 404],

// Get groups and expect 200 and set result to context
[user1, 'get all groups', 'GET /groups', 200, function(err, res, t){ 
  // t is the context object for app.
  // The value set here can be used by next test case.
  t.my_groups = res.body;
}],

// Create groups and expect 201 with payload
[user1, 'create group', 'POST /groups', 201, 
  { name: 'test', 
    id: '1001'}
],

// Create groups and expect 201 with payload and save group id to context
[user1, 'create group', 'POST /groups', 201, 
  { name: 'test', 
    id: '1001' 
  }, 
  function(err, res, t){ 
    t.group_id = res.body.group_id;
  }
],

// Set reqeust header except authorization
// Now the engine use JSON as default content-type.
// TODO: detect payload type except JSON.
[user1, 'upload file', 'POST /files', 201, image_file_data, null, 
  {"content-type": "image/jpeg"}
],

// None REST-API action
// Test case can be any function except REST-API request in pua. 
// The actor and action can be null when confirmation is unwanted.
[user1, 'read local file ', function(done, t){
  var err = null;
  // synchronous or asynchronous handler here
  // invoke done with err after the handler is completed.
  done(err);
}]

// test case which use context in actor, action, reqUrl or payload
(t)=>{return [user1, 'get group details', 'GET /groups/' + t.group_id];},
(t)=>{return [user1, 'set group details', 'PUT /groups/' + t.group_id, { name: 'new name'}];},


// test case generated by your own function without context
// The function prototype is 
// function generateMyTestCase(myParms) {
//   // generate the array by parameters
//   // values in t can be used here
//   return [...]
// }
generateMyTestCase(t, myParms),


// test case generated by your own function with context
// The function prototype is 
// function generateMyTestCase(t, myParms) {
//   // generate the array by parameters
//   // values in t can be used here
//   return [...]
// }
(t)=>{return generateMyTestCase(t, myParms);},

// insert more test case by the result of current test case.
// the inserted test cases will be exec subsequently
[user1, 'get all groups', 'GET /groups', 200, function(err, res, t){
  // the response payload is array of groups
  var actions = [];
  for (var i = 0; i < res.body.length; i++) {
    // delete groups and expect 204
    actions.push([user1, 'delete group', 'DELETE /groups/' + res.body[i].group_id, 204]);
  }
  pua.insert(actions);
}],

To begin

1. Install it:

   $ npm install pua

2. Require it and use:

   var pua = require('pua');

API docs

TODO:

Usage examples

TODO:

License

MIT. See LICENSE for details.

Bug Report and feedback

[e-mail]