@appveen/rat

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
   • Folder structure
4. Writing test cases
   • Test Suit
   • Test Case
   • Request object
   • Response object
5. Smart substituitions
   • Globals
   • Data-pipes

Installation

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.

N.B.

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.

e.g.

{
  "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

e.g.

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

Smart substituitions

Smart substituitions allows you to specify dynamic payload.

Globals

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

Data-pipes

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