API Supertest

API testing tool derived from Supertest - thus the name.

This tool allows to specify api tests in a folder structure using yaml for fast API tests.

Note: I wrote this tool mostly to make the communication with my colleagues easier.

Installation

Note: This tool requires Node to be installed!

Local (per project)

$ npm i api-supertest --save

and then add the test case to the package.json

{
    ...
    "scripts": {
        "api": "api-supertest"
    }
    ...
}

Then you can run the api tests using

$ npm run api

Global

$ npm i api-supertest -g

Now the command api-supertest should be available in your command line. You can access the help for the command-line flags through api-supertest --help.

Folder Structure

This test system expects that your tests are in the /spec folder. Typically it looks something like this.

/spec
   options.yml
   type.js
   /tests
       route.yml

options.yml

Theoretically you should be able to set all spec using only the options.yml.

Tests is a list of urls that will be tested for accuracy

Test can also contain a (recursive!) derive statement that allows you to specify multiple tests in a faster fashion:

tests:
    - path: /search
      derive:
          - post: q=hello
            json: !!type SEARCH_RESULT
 
          - method: get
            code: 404

This results in the same tests as:

tests:
    - path: /search
      post: q=hello
      json: !!type SEARCH_RESULT
 
    - path: /search
      method: get
      code: 404

Note: There are more options if you use it as a library.

Context Variables

It is possible to use context variables in the definitions. The simplest example would look like:

tests:
  - path: ${my_var}
    context:
     my_var: /my_path

This, by itself, is not really useful but it can be helpful if you combine it with after, json and priority:

tests: 
  - path: /user
    json: !!type USER
    priority: 2
    after: !!js/function
      function(item, global, cb) {
        global.context.user_id = item.json.id;
        cb();
      }
  - path: /avatar
    get: id=${user_id}
 

The example above loads the user first (because of the higher priority). After the data was found it stores the result id in the global context's user_id field. Using the new context variable it is possible to load the avatar for a user.

Environment variables

In any yaml file you can use the !!env prefix to load an environment variable.

options.yml

context:
  password: !!env TEST_PASSWORD

api-supertest comes with support for .env variables. If you pass the command-line option --dotEnv=true it will load the .env-file in the current working directory.

type.js

Yaml doesn't offer regular javascript functionality and Joi is a really comfortable json definition format. type.js offers you to define types to be used in yaml files using javascript. For example:

type.js

var joi = require("joi")
 
module.exports = {
    MY_OBJECT: joi.object({
        id: joi.string().regexp(/^[A-Z]+$/),
        title: joi.string(),
        age: joi.date()
    })
}

Then you can refer to this new type MY_OBJECT in the yaml file.

options.js

tests:
   - path: /foo
     json: !!type MY_OBJECT

tests/*.yaml

Any yaml file that you put in the tests folder will be merged and added to options.yaml's tests property.

As a library

You can also use api-supertest with JavaScript after installing it with npm i api-supertest --save in a Node script:

var test = require("api-supertest"),
    joi;
 
test({
    https: false,
    server: "github.com",
    prefix: "/api",
    tests: [
       {path: "/search", code: 404}
    ],
    output: require("api-supertest/output/console")
});

Contribute!

Please, please contribute 😃 I wrote this tool to be comfortable when communicating in the company but its far from perfect. Even though I took care when structuring it. Open a pull request to fix an issue, add an issue. I will make sure to respond as fast as I can.