ReST API Tester
Last updated a year ago by appveen .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @appveen/rat 
SYNC missed versions from official npm registry.

ReST API Tester - R.A.T

Writing test cases and automating them are fairly time consuming activities. RAT aims to eliminate the pain of automating REST API test cases.

In itself, RAT is not a new framework. It's a simple code generator that generates mocha test cases from a simple JSON file. RAT uses request for API calls and chai-expect as the assertion library

Current version of RAT ONLY supports JSON request and response vaidations.

Table of contents

  1. Installation
  2. CLI Options
  3. Setting up
  4. Writing test cases
  5. Smart substituitions


npm i -g @appveen/rat

CLI Options

rat [options] [file ...]

The available options are,

  • -i, --init: Initialize the currect folder as a RAT test case location.
  • --ui: Start RAT in interactive mode on the CLI. This is the default behavior.
  • -u,--upgrade: Upgrades the RAT setup in the current folder.
  • -g, --generate [file ...]: Generates mocha scripts for all the files under the tests folder or for the files specified.
  • -r, --run [file ...]: Run all the tests under the generatedTests folder or the tests specified.
  • --stopOnError: Stop at the first failure while running tests
  • --har [file]: Generates RAT test case from a HAR file.
  • --clean: Displays the instructions to clean RAT setup from a folder.
  • --demo: Starts the demo server. This is primarily used for demoing RAT.
  • -v, --version: Displays the version of RAT

Setting up

To set up a folder for running RAT tests, run the following commands from the command line.

rat -i

When rat is initialized for the first time, a set of sample test cases are provided under the tests folder.

Folder structure

Once initialised the following folders are created.

Name Description
generatedTests Contains the generated test cases.
lib JSON Files that are referenced by the test cases.
modules Files that define JS methods
tests Testcase JSON files which are used to generate the testcase under generatedTests.

Writing test cases

Test cases are bundles as a test suite and each test suite is written as a JSON file.

Test Suit

  • Each file is treated as a test suite or a collection of tests.
Option Type Desctiprion
testName String Required. Name of the test case
url List Required. A list of URLs that will be used in this test suite
modules List The list of module files from modules directory that is being used in the test cases.
globals List A list of global variables that would be used in the test cases. Global varaibles are used to pass data between test cases.
tests Array Tests is an array of objects. Each object in the array is test case.

Sample test casefile,

    "testName": "Sample API Tests",
    "url": [ "http://localhost:8080" ],
    "modules": [ "sampleFunction" ],
    "globals": [ "loginResponse", "data" ],
    "tests": []

Test Case

Attribute Type Desctiprion
endpoint Number Required. This denotes the URL in the list of url that was defined in the test suite section. The list starts with 1. Example, if url was defined as url:["http://localhost:8080", "http://localhost:8081"], then endpoint:1 points to the first URL, http://localhost:8080
name String Name of the test case. This would appear in the summary.
delimiters List The delimiters that should be used for patten substituitions. The default delimiters are {{ and }}
wait Number The number of seconds to wait before continuing to the next text.
continueOnError Boolean Default: false. If set to true, then the test execution will not stop if this step fails.
request Object Required. The request definition.
response Object The response data that would be used to validate the API response.

Sample test case

    "endpoint": "1",
    "name": "Login - Valid",
    "delimiters": ["{{", "}}"],
    "continueOnError": false,
    "wait": 2,
    "request": {},
    "response": {}

Request object

Attribute Type Desctiprion
method String Required. One of the HTTP methods - POST, PUT, GET, DELETE, PATCH
url String Required. A uri under test.
headers JSON A set of headers that should be sent along with the request.
qs JSON A set of query strings that should be set on the URL.
responseCode Number The HTTP status code that is expected from the response.
payload JSON The JSON payload that should be sent with the request.
payloadFile String The name of the JSON file under lib folder to be used as payload.
saveResponse String One of the entries from globals. This will be used to save the output of the request so that it can used in any of the subsequent test cases. If the value is not in globals, then no error is raised, but might cause downstream test cases to fail.


If the JSON payload is big, then it is a good practice to save the file under lib and reference the file in the test.

If both payload and payloadFile is provided, then payload takes precedence.


  "method": "GET",
  "url": "/api/a/sm/service",
  "qs": {
    "select": "name domain port",
    "filter": {
      "app": "jerry",
      "name": {
          "$in": ["Test-Relation-Root","Test-Relation-Child" ]
  "headers": {
    "Authorization": "JWT <% loginResponse.token %>"
  "responseCode": 200,
  "saveResponse": "fetchAllEntity"

Response object

An optional response object can be defined for a testcase. This response object is used to validate the response from the API. If no response object is provided, then no response validation is done.

Attribute Type Desctiprion
headers JSON Response headers to be validated
body JSON or Array Response body will be validated against this. Arrays are order sensitive for comparison.
bodyFile String A file from lib that can be used to validate the response body


  "body": {
      "message": "Login error!"

Smart substituitions

Smart substituitions allows you to specify dynamic payload.


The value from a global variable can be used in the test case by enclosing it with in the delimiters.

"headers": {"token": "<% loginResponse.token %>"}

The delimiters for the above example are <% and %>.


This allows you to use the output data of a previously run test case in the current test case.

"url": "/data/{{dataPipe['sampleTest01.json'].data._id}}",

Current Tags

  • 1.5.2                                ...           latest (5 months ago)

16 Versions

  • 1.5.2                                ...           5 months ago
  • 1.5.1                                ...           5 months ago
  • 1.5.0                                ...           5 months ago
  • 1.4.0                                ...           6 months ago
  • 1.3.3                                ...           a year ago
  • 1.3.2                                ...           a year ago
  • 1.3.1                                ...           a year ago
  • 1.3.0                                ...           a year ago
  • 1.2.2                                ...           a year ago
  • 1.2.1                                ...           a year ago
  • 1.2.0                                ...           a year ago
  • 1.1.0                                ...           a year ago
  • 1.0.3                                ...           a year ago
  • 1.0.2                                ...           a year ago
  • 1.0.1                                ...           a year ago
  • 1.0.0                                ...           2 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 2
Dependencies (4)
Dev Dependencies (0)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |