The REST Library

The REST library helps testing systems that support RESTful API (often referred to as "REST API" or even just "API"). Effectively methods in this library perform HTTP calls and validate the responses, so it is also possible to use this library for testing raw HTTP interactions with web-based user interfaces, or SOAP services.

In order to make the usage easier and less repetitive, the library uses a session object that manages common data and default options, such as the base URL for the REST endpoint. This way, when calling the endpoints of the service under test, users only need to add data that is unique to the call.

Currently, Provengo supports the following HTTP methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, and TRACE.

Example

In the example below, we use the REST library to test a customer list application. We post a new customer, and validate that said customer was successfully added.

// @provengo summon rtv   (1)
// @provengo summon rest

const svc = new RESTSession(SERVER_ENDPOINT, "client", {                    (2)
    headers: {"Content-Type":"application/json"}
});

bthread("Main", function(){
    // Generate customer data
    const fName = select("first_name").from("Joe", "Jane", "John", "Jill"); (3)
    const lName = select("last_name").from("Smith", "Doe", "Johnson");
    const age = select("age").from("15", "30", "45", "75");

    // Create new customer
    svc.post("/customers", {                                                (4)
        body: JSON.stringify({
                "first_name":fName,
                "last_name":lName,
                "age": age
            }),
        callback: function(response, rtv){                                  (5)
            const respObj = JSON.parse(response.body);
            if ( ! respObj.success ) return false;
            rtv.set("customer_id", respObj.response.ID);                    (6)
            return true;
        }
    });

    // Validate new customer exists
    svc.get("/customers", {                                                  (7)
        parameters:{"id":"@{customer_id}"},
        expectedResponseCodes: [200]
    });
});

Importing the REST and Runtime Variables libraries.
Defining a REST session with default headers.
Generating customer data
Performing a HTTP POST request to the server. Client data is wrapped in the body as JSON.
Callback function is used parse the server response, validate that the request was successful and to and extract the new customer id.
Storing the new customer id in the variable runtime system.
Performing a HTTP GET request with the new customer id, and validating that the response is 200 OK.

Classes

`RESTSession(baseURL, sessionName, defaultOptions)`

Constructs a new REST session. All calls from this session will be sent to endpoints under baseURL. For example, a server at https://api.fruits.org can have endpoints such as http://api.fruits.org/apples and http://api.fruits.org/bananas. In this case, the base URL should be http://api.fruits.org, and /apples and /bananas are the relative URLs or the service endpoints.

baseURL

The URL of the server exposing the endpoints.

sessionName

Optional. Name of the session.

defaultOptions

Optional. Object containing default options for RESTful API calls. Actual API calls will use these parameters unless they are invokes with other parameters.

headers: Object. HTTP headers.
parameters: Object. Parameters added to the URL.
expectedResponseCodes: Integer Array. Expected response status codes.
callback: Function. Used to validate the response and update runtime values as needed. See Options for more details.

Example

Constructing a new REST session for later use.

const recipeSvc = new RESTSession("https://api.recipes.com/", {
    headers: {
        "Content-Type":"application/json",
        "Api-Key":"my-secret-api-key-so"
        },
    parameters: {
        "lang":"en"
    }
});

bthread("API User", function(){
    recipeSvc.get("/cake/chocolate", {...})
});

Methods

The REST/HTTP methods share many parameters. They are explained in further detail in the Options section.

`session.post(url, options)`

Sends a POST http request to the specified endpoint, and inspects the response.

url: String. RESTful API endpoint relative to the session’s baseURL.
options: Object. HTTP call parameters, including headers, body, expected return codes, etc. See Options.

`session.get(url, options)`

Sends a GET http request to the specified endpoint, and inspects the response.

url: String. RESTful API endpoint relative to the session’s baseURL.
options: Object. HTTP call parameters, including headers, expected return codes, etc. See Options. Note that GET methods have no body, so if a params contains a body field, that field is ignored.

`session.put(url, options)`

Sends a PUT http request to the specified endpoint, and inspects the response.

url: String. RESTful API endpoint relative to the session’s baseURL.
options: Object. HTTP call parameters, including headers, expected return codes, etc. See Options.

`session.patch(url, options)`

Sends a PATCH http request to the specified endpoint, and inspects the response.

url: String. RESTful API endpoint relative to the session’s baseURL.
options: Object. HTTP call parameters, including headers, expected return codes, etc. See Options.

`session.head(url, options)`

Sends a HEAD http request to the specified endpoint, and inspects the response.

url: String. RESTful API endpoint relative to the session’s baseURL.
options: Object. HTTP call parameters, including headers, expected return codes, etc. See Options. Note that the HTTP HEAD method does not have a body, so if a params contains a body field, that field is ignored.

`session.delete(url, options)`

Sends a DELETE http request to the specified endpoint, and inspects the response.

url: String. RESTful API endpoint relative to the session’s baseURL.
options: Object. HTTP call parameters, including headers, expected return codes, etc. See Options. Note that the HTTP DELETE method does not have a body, so if a options contains a body field, that field is ignored.

`session.options(url, options)`

Sends an OPTIONS http request to the specified endpoint, and inspects the response.

url: String. RESTful API endpoint relative to the session’s baseURL.
options: Object. HTTP call parameters, including headers, expected return codes, etc. See Options. Note that the HTTP OPTIONS method does not have a body, so if a options contains a body field, that field is ignored.

`session.trace(url, options)`

Sends a TRACE http request to the specified endpoint, and inspects the response.

url: String. RESTful API endpoint relative to the session’s baseURL.
options: Object. HTTP call parameters, including headers, expected return codes, etc. See Options. Note that the HTTP TRACE method does not have a body, so if a options contains a body field, that field is ignored.

Options

A set of options that affect HTTP requests are sent, and how HTTP responses are validated. All fields are optional.

headers

Object containing the headers fields, where the keys hold the headers name, and the values hold headers contents. To duplicate a header, use an array of values instead of a single value. See [_examples] for more info.

parameters

Object containing request parameters. These parameters will be appended to the URL, in the parameter part (i.e. after the ?).

body

Body of the HTTP request. NOTE: When passed to HTTP methods that do not have a body, namely GET, HEAD, DELETE, OPTIONS, and TRACE, this field is ignored.

expectedResponseCodes

An array expected HTTP response status codes. If omitted, Provengo will accept any response status code in the what the HTTP standard protocol defines as the "successful range": 200-299, inclusive.

validateResponseFunction

A function for validating the response. This function accepts two parameters: response object and rtv object. It should return true if the response is valid, and false otherwise. See [_examples] for more info.

response

Object. The HTTP response. Fields: headers, body, code and version.

response.code:      int
response.headers:   Map<String, String>
response.version:   String
response.body:      String

rtv

Object. Provides access to the runtime variable system, using its get(key) and set(key, value) methods. See Runtime Variables.

rtv.get(key):  object // get value of run time variable.
rtv.set(key, value): void // sets the value of `key` to the passed `value`.

Properties

`session.baseURL`

The URL prefix for all service endpoints. Often this is the URL of the server running the service.

`session.name`

Name of the REST session.