Beautiful test suite & runner for api tests.
Last updated 2 years ago by leichtgewicht .
ISC · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install api-supertest 
SYNC missed versions from official npm registry.

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.


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


$ 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.



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

Property Content
base The base url, if missing will be built using https, server and prefix
https If true then https will be used (default: false)
server Server base url (eg. github.com)
prefix Prefix prepended to all api calls (eg. /api)
defaults (Object, optional) Additional configuration for tests. Will be used as fallback
output Output implementation. console or none is supported. (defaults to console in the command line and to none when used as a library)
tests A list of tests that should be run.
before A function will be called before all the tests are run (syntax: !!js/function)
after A function will be called after all the tests are run (syntax: !!js/function)
beforeEach A function will be called before each test is run (syntax: !!js/function)
afterEach A function will be called before each test is run (syntax: !!js/function)

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

Property Content
path Path to be loaded (eg. path: /test would result to http://github.com/api/test)
priority Optional number (default 1). Entries with higher priority will be executed first.
method Optional http method, will default to get
context (Object, optional) Data context to be used to resolve ${} blocks (will be merged with the runtime context and during the derivision)
data Data to be passed to a post/put/head/push request
requestHeader (Object, optional) A set of headers to be when requesting the resource (will be merged during derive)
responseHeader (Object, optional) A set of headers to check the response against (will be merged during derive)
push, put, post, head Shortcuts to define a request as (eg.) post & with the given data (eg. post: "foo=bar&baz=boz" is the same as method: post and data: "foo=bar&baz=boz")
username Username to be used for basic auth
password Password to be used for basic auth
get Adds a query string to the path. (replaces the query string if its already there). Add it without the leading "?": eg. foo=bar&baz=qux this will also set the method to get.
json Joi based json validator to be used for validating files
result Result as a string to validate the content against. (Does not work in combination with json). Can also be a !!js/function to perform your own tests.
maxRedirects Number of redirects to follow. (default: none)
before A function will be called before this test is run (syntax: !!js/function)
after A function will be called after this test is run (syntax: !!js/function)

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

    - path: /search
          - post: q=hello
            json: !!type SEARCH_RESULT

          - method: get
            code: 404

This results in the same tests as:

    - 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:

  - path: ${my_var}
     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:

  - path: /user
    json: !!type USER
    priority: 2
    after: !!js/function
      function(item, global, cb) {
        global.context.user_id = item.json.id;
  - 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.


  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.


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:


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.


   - path: /foo
     json: !!type MY_OBJECT


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"),

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


Please, please contribute :smiley: 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.

Current Tags

  • 0.4.0                                ...           latest (2 years ago)

12 Versions

  • 0.4.0                                ...           2 years ago
  • 0.3.0                                ...           3 years ago
  • 0.2.3                                ...           6 years ago
  • 0.2.2                                ...           6 years ago
  • 0.2.1                                ...           6 years ago
  • 0.2.0                                ...           6 years ago
  • 0.1.1                                ...           6 years ago
  • 0.1.0                                ...           6 years ago
  • 0.0.4                                ...           6 years ago
  • 0.0.3                                ...           6 years ago
  • 0.0.2                                ...           6 years ago
  • 0.0.1                                ...           6 years ago
Maintainers (1)
Today 0
This Week 0
This Month 6
Last Day 0
Last Week 3
Last Month 7
Dependencies (10)
Dev Dependencies (1)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |