README.md

stresst

A lightweight yet powerful functionnal test tool for REST APIs and more

Get started

Ultra quick start

npm install stresst

Write a minimalist test suite like below in a file named suite.js

var test = require("stresst");

exports.suite = {
  base_uri: "https://api.mousses.org/v1",
  tests: [{
    method: "GET",
    uri: "/answers/meaningOfLife",
    asserts: [ {test: test.if.httpStatusIs(200)} ]
  }]
}

run the following command

node stresst suite.js

Stresst needs at least one test suite file to run tests.

Test suite

A test suite is a module that returns a plain object containing one or severals tests, themselfs containings one or several assertions. The suite POJO has the following structure:

• baseUri string Base Url of the API to test
• tests array An array of tests
• [name] string A fancy name to display
• [prepare] function A function to be executed before running tests
• [clean] function A function to be executed after running tests

Test

Note Some of the properties below accepts a function as value, when so, the function will be executed a the time of the test, and it's return will be used as real value of the property. This is particullary handy when injecting data from previous response

• uri string||function Endpoint URI, relative to baseUri
• method string HTTP method to use (GET, POST, etc.)
• asserts array An array of assertions to test against the HTTP response
• [title] string A fancy string to name your test
• [body] object||string||function content of HTTP request body ** POJO will be transformed in an HTTP key/value pair liste like would do an HTML form ** String will be send as is. So you should use JSON.stringify() to send a full JSON object without any property name
• [multipart] string||function TODO: Document upload
• [headers] object||function key/value pair of headers
• [store] array An array of storage instruction
• [waitBefore] int Wait an arbitrary amout of time before executing the test delay in seconds
• [waitAfter] int Wait an arbitrary amout of time after executing the test delay in seconds

Assertion

• test assertion function
• [name] string What is your test about. a default string should be generated by assertion function if you don't provide one

Storage instruction

• src Path of source the data in the response object
• dest NAme of the key to use to store the data in the local storage

Here is a more elaborate exemple of a test suite file:

// Include the lib
var test = require("stresst");

// Export as `suite`
exports.suite = {

  base_uri: "https://api.mousses.org/v1",
  name: "My test suite",
  tests: [
  {
    title: "My first test",
    method: "GET",
    uri: "/answers/meaningOfLife",

    asserts: [
      {test: test.if.httpStatusIs(200)},
      {test: test.if.isJSON()},
      {
        name: "Response has a key named value", 
        test: test.if.hasKey("value")
      },
      {
        name: "Value is a number", 
        test: test.if.isOfType('value', 'number')
      },
      {
        name: "Value is 42", 
        test: test.if.isEqual('value', 42)
      }
    ]
  }
}

Testing nested properies

Stresst can test deep properties of the received data, via a simple dot syntax. Considering the following JSON response:

{
  "status": "ok"
  "items":[
    {
      "id": 1,
      "value": "foo"
    },
    {
      "id": 2,
      "value": "bar"
    }
  ]
}

one can test the content of response.items[1].value with

test.if.isEqual("items.0.value", "foo") // true
test.if.isEqual("items.1.id", 2) // true

Storing and reusing response data

You can store data from received response and re use it allong with others tests or assertions

Storing data

The instruction to store some data happens at the test level, with the store property. The saved data is later available with the getData() method of the stresst object.

To use stored data to build a property value of a test, you need to generate this value inside of a closure, which will be automatically evaluated at the time of running the test. Using getData() directly for a property declaration will fail as the data has not been fetched at the time of parsing the test suite.

Example

var test = require("stresst");

exports.suite = {
  base_uri: "https://api.mousses.org/v1",
  tests: [{
    method: "GET",
    uri: "/answers",
    store: [
    {
      src: "0.id",
      dest: "answer_id"
    }
    ],
    asserts: [ {test: test.if.httpStatusIs(200)} ]
  },
  {
    method: "GET",
    uri: function(){ 
      return "/answers/"+ test.getData("answer_id")
    },
    asserts: []
  }
  ]
}

Advanced data storage

You may want to store data from something else than the response body, for example from the response headers or to transform the data before storing it.

For those cases, you need to delare a function as value of the src key of the store object. The function receives the response as parameter.

Example

store: {
  dest: "foo",
  src: function(response){
    var data = JSON.parse(response.body);
    return data.someProperty.toLowerCase() + response.headers["X-Why-Would-You-Do-that"];
  }
}

Instalation

npm install tresst

...or git clone this repo

Assertions

For now tresst does not support / rely on an external assertions library, but rather include its own.

httpStatusIs

Checks status code

• @param int expected A HTTP status code

isJSON

isEqual

Checks a given key path value against an expectation

• path string String representation of how you would acces the property eg: myobject.property.sub_property
• expected mixed Excpected value

isNotEqual

Checks a given key path value is NOT equal to an (un)expectation

• path string String representation of how you would acces the property eg: myobject.property.sub_property
• unexpected Mixed Unexpected value or value excpected to not be present

hasKey

Checks if response JSON contains the given key path (even if the value is null or false)

• path string String representation of how you would acces the property

isOfType

Checks if given path is of expected type

• path string String representation of how you would acces the property
• type string Name of the excepted type

arrayLengthIs

Checks array length...

• path string String representation of how you would acces the property
• length int Excepcted length

arrayHasValue

Checks if an array at path contains execpted value

• path string String representation of how you would acces the property
• expected mixed Excpected value

arrayDontHaveValue

Checks if an array at path does NOT contain (un)execpted value

• path string String representation of how you would acces the property
• expected mixed Unexcpected value