HTTP and REST API

Testerum comes with a new and easy way to test your REST API.
With Testerum, you’ll be able to send HTTP Requests and verify HTTP Responses from an intuitive UI, without having to write any line of code.

HTTP Request

Create a new Feature

Let's start by creating a new test and add the HTTP Request Step (img 1):

First of all hover your mouse cursor over a feature file and press the Create Test button
Set a test name
Click the Add Step button
Click the Select Step button

img 1

After you click on the "+" button in the Steps section, a new window will pop up. Go to Basic Steps -> http -> request and select the step When I execute the HTTP request <<httpRequest>> (img 2).

img 2

Now, click the "Edit" button to define the HTTP Request parameter (img 3).

img 3

In the opened popup, you can define all your HTTP Request details (img 4):

Set a Name that describes what is this request about
Set the Request Method: GET, POST, PUT, DELETE, etc.
Set the Request URL.
In this example the Request URL is composed of the value of the variable URL and the suffix /api/auth/login
In the Headers tab you can define the Request Headers.
All the Request Methods beside GET allow you to define the Request Body.
In case you are testing a REST API set the Request Body as raw and the content type as JSON
. Setting the content type as JSON you will have syntax highlight and validation plus the Format JSON option.
Using the Params button will reveal the Query Param panel that allows you to define query parameters that will be automatically be encoded for you.
When you have your request defined you can use the Execute Request button to check if is what you want and to see the server response.
When your HTTP Request is defined press the OK button.

img 4

Save the test.

Data extraction

In this section you’ll learn how to extract data from an HTTP request and store this value into a variable. Next we will use this value in a different request. Let's execute the request defined in the previous chapter to see the response (img 5):

After the test is saved the Run Test button will be displayed. Click this button to execute the test.
After clicking the Run Test button the Test Execution Panel will be displayed.
- on the left side there is the Execution Overview Panel
- on the right side there is the Console where all the logs generated during current execution are shown.
In the console you can see the executed HTTP Request and HTTP Response details.
In this example we see that the HTTP Response Body is:
```
{
    "authToken": "YWRtaW46YWRtaW4="
}
```
Let's extract the value of the "authToken" and store it in a variable.

img 5

In order to extract the "authToken" value from the HTTP Response we need to use the following step (img 6):
We will set the step parameter name to AUTH_TOKEN
To extract the value from the response we are going to use the following expression: {{httpResponse.jsonBody.authToken}} After each HTTP Request two variables are created: httpResponse and httpRequest.
Let me explain you the above expression, {{httpResponse.jsonBody.authToken}}:
- httpResponse is accessible after an HTTP Request is made and gives you access to all the HTTP Response details.
- jsonBody returns the HTTP Response Body as a JSON object. This will allow you to access the JSON as an JavaScript Object.
- authToken returns the value of the authToken property from the HTTP Response.

img 6

Now, in the context of our test there is a variable AUTH_TOKEN defined with the value "YWRtaW46YWRtaW4="

Let's add a new step that executes another HTTP Request and which uses the AUTH_TOKEN variable (img 7):

Added a new HTTP Request step "add customer"
This request requires the Header Authorization that uses the variable AUTH_TOKEN.
To access the value of this variable we use the expression: {{AUTH_TOKEN}}
At runtime the expression {{AUTH_TOKEN}} will be evaluated and replaced with the variable's value.
We are going to use this request later on to show you how we can do an HTTP Response Validation.

img 7

HTTP Expressions

In the previous section you learned how to extract parts of a JSON response by using an expression like {{httpResponse.jsonBody.authToken}}.
This section describes other expressions which are available.

After making an HTTP request, two variables are created: httpResponse and httpRequest. In the following section, we describe the models for these variables.

Response

protocol         : String,  // HTTP/1.1
statusCode       : int,     // 200
headers          : List<HttpResponseHeader>,
body             : byte[],  // body, exactly as received
bodyAsUtf8String : String,
jsonBody         : Map<String, String | int | boolean | null | Map}>  // httpResponse.jsonBody.person.name
durationInMillis : Long
getHeaderValue(key: String) : String   // returns the first header value for the provided key or null

HttpResponseHeader

key    : String,      // Content-Type
values : List<String> // we use a list to capture all values (HTTP allows a header to be specified multiple times)

Request

method          : HttpRequestMethod,
url             : String
headers         : Map<String, String>,
body            : HttpRequestBody | null,
followRedirects : boolean

HttpRequestMethod

enum {
    GET,
    POST,
    PUT,
    DELETE,
    HEAD,
    OPTIONS,
    TRACE,
    PATCH
}

HttpRequestBody

bodyType : HttpRequestBodyType
content  : String

HttpRequestBodyType

enum {
    RAW,
    FORM_DATA,
    X-WWW-FORM-URLENCODED,
    BINARY
}

HTTP Verify

Let's see how we can verify the previous executed HTTP Request (img 7).
For this we are going to add the following step to our test:

Let's edit the httpResponseVerify parameter and set the HTTP Response Verify details (img 8):

Set a name for this Http Response Verify
Set the expected Status Code
Set the expected headers. There are multiple ways to compare the headers value:
- EXACT MATCH - the actual value must be exactly equal to the expected value specified here
- CONTAINS - the actual value must contain the expected value
- MATCH REGEX - the actual value must match the expected regular expression. See the documentation on the exact syntax of the regular expression.
Testerum provides different Body Matching options:
- JSON Verify: makes JSON Comparison very easy, more about this in the JSON Verify section
- Exact Match: the actual response body must be exactly the same as the expected body
- Contains: the actual response body must contain the expected body
- Match Regex: the actual response body must match the expected regular expression. See the documentation on the exact syntax of the regular expression.
- Is Empty: the actual response body must not contain any characters, not even whitespace
Comparison Mode allows you to set on each JSON Node how to be compared with the actual response.
Comparison Mode has three possible options: exact, unorderExact and contains. More about this option in the JSON Verify chapter.
To verify the JSON Body Response, just copy - paste the response or type it from scratch and use the following rules:
- You can use Assertion functions to check the value: @isNotEmpty(), @isNotNull(), @isNullOrEmpty(), @isBlank(), @isNullOrBlank(), @isNotBlank(), @matchesRegex("[0-9]") and many more here.
  For example: normally the ID fields of an object are generated and for checking their value we can use the function @isNotEmpty().
- If there are fields or objects that you are not interested in checking if they exist or which value they have, just remove them from the expected JSON.
  In this example in the expected JSON we have removed the fields address.postCode and address.houseNumber.

img 8

JSON Verify

One of the innovations in Testerum is how easy is to compare two JSONs. This functionality can be accessed using one of the following steps:

You have to define the parameter expectedJSON to set the expected JSON.
Edit the only parameter httpResponseVerify and set the Body Matching to JSON Verify

Simple verification

The simplest verification is to put in the expected body as-is:

Actual JSON

{
    "id": 3476,
    "firstName": "John",
    "lastName": "Doe"
}

Expected JSON

{
    "id": 3476,
    "firstName": "John",
    "lastName": "Doe"
}

Assertion functions

Instead of expecting a particular value, you can use comparison functions:

Actual JSON

{
    "id": 3476,
    "firstName": "John",
    "lastName": "Doe"
}

Expected JSON

{
    "id": "@isNotEmpty()",
    "firstName": "John",
    "lastName": "Doe"
}

In this case the actual JSON will match because 3476 satisfies the @isNotEmpty() function.

img 9

In the picture above(img 9) we have on the left side a simple HTTP Response verification which works fine, and on the right side we validate the JSON using some of the Testerum assertion functions "@isNotEmpty()", "@isArray()", "@isBoolean()". In this case the actual JSON will match because:

The ID value 101 satisfies the @isNotEmpty() expression.
The visit array satisfies the @isArray() expression.
The isMember value satisfies the @isBoolean() expression.

If you want to compare against a text that begins with @, you will have to escape it: "\\@alex says thanks". Available Testerum assertion functions to validate the JSON:

@isNotNull()

Checks if a particular value is not null.

In case it's null, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "monthly-check",
             "isMember": true
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "@isNotNull()",
             "isMember": "@isNotNull()"
            }
         }

@isNullOrEmpty()

Checks if a particular value is null or empty.

In case it's not null or empty, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "",
             "isMember": null
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "@isNullOrEmpty()",
             "isMember": "@isNullOrEmpty()"
            }
         }

@isNotEmpty()

Checks if a particular value is not-empty.

In case it's null, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "monthly-check"
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "@isNotEmpty()"
            }
         }

@isBlank()

Checks if a particular value is blank.

In case it's null, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "        "
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "@isBlank()"
            }
         }

@isNullOrBlank()

Checks if a particular value is blank or null.

In case it's not blank or null, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "        ",
             "isMember": null
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "@isBlank()",
             "isMember": "@isNullOrBlank()
            }
         }

@isNotBlank()

Checks if a particular value is not blank.

In case it's null, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "monthly-check"
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "@isNotBlank()"
            }
         }

@isArray()

Checks if a particular value is an array.

In case it's not an array, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            }, {
             "date": "2020/12/09",
             "description": "monthly-check"
            } ]
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": "@isArray()"
         }

@isArrayOrNull()

Checks if a particular value is an array or null.

In case it's not an array, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            }, {
             "date": "2020/12/09",
             "description": "monthly-check"
            } ]
          }

Expected HTTP Response


 {
   "id": 101,
   "visit": "@isArrayOrNull()"
 }

@isNonEmptyArray()

Checks if a particular value is a non empty array.

In case it's not an array, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            }, {
             "date": "2020/12/09",
             "description": "monthly-check"
            } ]
          }

Expected HTTP Response


{
"id": 101,
"visit": "@isNonEmptyArray()"
}

@isArrayWithSize()

Checks if a particular value is an array with a given number of objects.

In case it's not an array, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            }, {
             "date": "2020/12/09",
             "description": "monthly-check"
            } ]
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": "@isArrayWithSize(2)"
         }

@isArrayWithSizeGreaterThan()

Checks if a particular value is an array with a number of elements greater than the given number.

In case it's not an array, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            }, {
             "date": "2020/12/09",
             "description": "monthly-check"
            } ]
          }

Expected HTTP Response


        {
        "id": 101,
        "visit": "@isArrayWithSizeGreaterThan(1)"
        }

@isArrayWithSizeLessThan()

Checks if a particular value is an array with a number of elements less than the given number.

In case it's not an array, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            }, {
             "date": "2020/12/09",
             "description": "monthly-check"
            } ]
          }

Expected HTTP Response


        {
        "id": 101,
        "visit": "@isArrayWithSizeLessThan(3)"
        }

@isBoolean()

Checks if a particular value is of type boolean.

In case it's not a boolean, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            }, {
             "date": "2020/12/09",
             "description": "monthly-check"
            } ],
           "isMember": true
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": "@isArray()",
           "isMember": "@isBoolean()"
         }

@isBooleanOrNull()

Checks if a particular value is of type boolean or null.

In case it's not a boolean, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            }, {
             "date": "2020/12/09",
             "description": "monthly-check"
            } ],
           "isMember": true,
           "hasMembership": null
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": "@isArray()",
           "isMember": "@isBooleanOrNull()",
           "hasMembership": "@isBooleanOrNull()"
         }

@isNumber()

Checks if a particular value is of type number.

In case it's not a number, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": 1234
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": "@isNumber()"
          }

@isNumberOrNull()

Checks if a particular value is of type number or null.

In case it's not a number, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": 1234,
           "sessionsNumber": null
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": "@isNumber()",
           "sessionsNumber": "@isNumberOrNull()"
          }

@isNumberLessThan()

Checks if a particular value is of type number and the number is less than the given number.

In case it's not a number, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": 1234
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": "@isNumberLessThan(1250)"
          }

@isNumberGreaterThan()

Checks if a particular value is of type number and the number is greater than the given number.

In case it's not a number, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": 1234
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": "@isNumberGreaterThan(1000)"
          }

@isNumberEqualOrGreaterThan()

Checks if a particular value is of type number and the number is equal or greater than the given number.

In case it's not a number, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": 1234
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": "@isNumberEqualOrGreaterThan(1234)"
          }

@isInteger()

Checks if a particular value is of type integer.

In case it's not an integer, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": 1234
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": "@isInteger()"
          }

@isIntegerOrNull()

Checks if a particular value is of type integer or null.

In case it's not a integer, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": 1234,
           "sessionsNumber": null
          }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "registrationNumber": "@isIntegerOrNull()",
           "sessionsNumber": "@isIntegerOrNull()"
          }

@isObject()

Checks if a particular value is an object.

In case it's not an object, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "address": {
             "streetAddress": "1st Street",
             "city": "Seoul",
             "postalCode": 1122
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "address": "@isObject()"
         }

@isObjectOrNull()

Checks if a particular value is an object or null.

In case it's not an object, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "address": {
             "streetAddress": "1st Street",
             "city": "Seoul",
             "postalCode": 1122
            },
           "profile": null
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "address": "@isObject()",
           "profile": "@isObjectOrNull"
         }

@isString()

Checks if a particular value is a String.

In case it's not a String, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "monthly-check"
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "@isString()"
            }
         }

@isStringOrNull()

Checks if a particular value is a String or null.

In case it's not a String, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "monthly-check",
             "comment": null
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": {
             "date": "2020/11/09",
             "description": "@isStringOrNull()",
             "comment": "@isStringOrNull()"
            }
         }

@matchesRegex()

Checks if a particular value meets a sequence of characters using a Regex (regular expression).

In case it's not a value matching regex, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "address": {
             "streetAddress": "1st Street",
             "city": "Seoul",
             "postalCode": 1122
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "address": {
             "streetAddress": "1st Street",
             "city": "@matchesRegex('\\\\w+')",
             "postalCode": 1122
            }
         }

@isNullOrMatchesRegex()

Checks if a particular value meets a sequence of characters using a Regex (regular expression) or it's null.

In case it's not a value matching regex or null, the test will fail.

Actual HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "address": {
             "streetAddress": "1st Street",
             "city": "Seoul",
             "postalCode": null
            }
         }

Expected HTTP Response


         {
           "id": 101,
           "visit": [ {
             "date": "2020/11/09",
             "description": "monthly-check"
            } ],
           "address": {
             "streetAddress": "1st Street",
             "city": "@isNullOrMatchesRegex('\\\\w+')",
             "postalCode": "@isNullOrMatchesRegex('\\\\w+')"
            }
         }

Compare Modes

Using the Compare Mode you can test any JSON in the smallest details.
In the Expected JSON you can specify on each node how to be compare with the equivalent node in the Actual JSON.
Let's see a complex scenario and understand how it works (img 10):

img 10

this comparison will pass

to set a compare mode on a node you need to:
- set the cursor inside the node you want to set or change the compare mode
- choose from the drop-down element one of the 3 options: exact, unorderExact, contains
- press the Insert button
Setting "=compareMode": "exact" to an object node means that all the properties in the Actual JSON needs to be present in the Expected JSON.
Setting "=compareMode": "contains" to an object node means that not all the properties in the Actual JSON needs to be present in the Expected JSON.
In our example we are interested to compare only the "address/city" and "address/street", so the fields "address/postCode" and "address/houseNumber" will be ignored in the comparison.
Setting "=compareMode: unorderedExact" on the array will check that all the nodes from the Actual JSON are present in the Expected JSON but the order is not important.
As you see =compareMode property format is different on the array than on a object node.
The option unorderedExact makes sens only on an array node. In an object node, the order of the properties is always ignored.
Because the compare mode is "contains" will have the effect that the node "favFoods" will be ignored in comparion.

NOTES:

The default comparison mode is contains.
The comparison mode is inheritable from the parent node.

Compare modes - Contains

The actual comparison is done according to a compare mode. The default compare mode is contains:

Actual JSON

{
    "id": 3476,
    "firstName": "John",
    "lastName": "Doe"
}

Expected JSON

{
    "firstName": "John",
    "lastName": "Doe"
}

Actual JSON

{
    "id": 3476,
    "firstName": "John",
    "lastName": "Doe"
}

Expected JSON

{"=compareMode": "contains"
    "firstName": "John"
}

Because the compare mode is contains, the actual JSONs above will match the expected JSONs, even though it has extra fields.

Compare modes - Exact

If you want the actual to have exactly the same fields as the expected, you need to use the exact compare mode:

Actual JSON

{
    "id": 3476,
    "firstName": "John",
    "lastName": "Doe"
}

Expected JSON

{"=compareMode": "exact"
    "firstName": "John",
    "lastName": "Doe"
}

This will not match, because the compare mode is exact, but the Actual JSON has an extra field (id).

Compare modes - Unordered exact

The compare mode unorderedExact is like exact, but ignores the order of items in an array:

Actual JSON

[
    "Bari",
    "Messina",
    "Siena"
]

Expected JSON

["=compareMode: unorderedExact",
    "Messina",
    "Siena",
    "Bari"
]

This will match.
The compare mode unorderedExact makes sens to be used only on arrays.

Compare modes per JSON node

The comparison can be done for the entire verification, as well as for each node in the JSON:

Actual JSON

[
    {
        "id": 14,
        "firstName": "Alex",
        "lastName": "Thompson"
    },
    {
        "id": 27,
        "firstName": "John",
        "lastName": "Doe"
    }
]

Expected JSON

["=compareMode: contains",
    {"=compareMode": "exact",
        "id": "@isNotEmpty()",
        "firstName": "John",
        "lastName" : "Doe",
    }
]

This will match.

How different compare modes interact

A compare mode is inherited by all sub-nodes of the JSON node that sets it.
For example, if you set the compare mode to exact on the root of the JSON, all sub-nodes will be compared in exact mode.
A compare mode can be overridden on a sub-node, like we do in the example above.