REST API testing
Note | For this tutorial we will assume you are running Windows, but the steps are almost identical for macOS or Linux. |
If you haven’t done it already, please follow the instructions in the installation page, including the quick start section to install OpenTest and create the default configuration files.
You should now have the OpenTest server and actor up and running from a directory structure similar to this:
C:\opentest ├── server │ └── server.yaml ├── actor1 │ └── actor.yaml └── test-repo └── ...
Open the server’s web UI at http://localhost:3000.
From the menu, select Session > Create Test Session. Select the test named GitHub API test and click Create session. Wait a few seconds for the test to complete.
Here’s the full source of the test we just ran:
description: Get repo branches from the GitHub API
actors:
- actor: ACTOR1
segments:
- segment: 1
actions:
- description: Perform the API call
action: org.getopentest.actions.HttpRequest
args:
url: https://api.github.com/repos/facebook/react/branches
verb: GET
- description: Verify that the branches array exists and is not empty
script: |
var branches = $output.body;
if (!branches || (branches.length == 0)) {
$fail("Response body invalid or contains no branch elements.");
} else {
$log($format(
"The GitHub API returned {0} branches",
branches.length));
}
The test above consists of two test actions:
The first action calls the
/repos/facebook/react/branches
API onapi.github.com
The second test action performs a validation step making sure that:
some payload was returned;
the response payload is an array with at least one element (we’re not being very thorough, just checking that the
length
property of the array is greater than 0).
As opposed to most UI tests, in order to do proper validation of the API response payloads, you do need to have some familiarity with the basic syntax of the JavaScript language:
How to build an
if
statement.How to compare two values using the
==
and!=
operators.How to access an object property using the
.
operator.How to perform a function call.
API tests are usually much easier to build than UI tests. The formula you’re going to apply over and over (with small variations) is:
Call an API using the the HttpRequest keyword and save the
statusCode
and/orbody
output values into a variable.Add one or more script actions to validate the response payload and/or status code.
Here’s one more example of an API test. This one calls the JSONPlaceholder fake REST API:
description: Creates a new BLOG post and validates the response
actors:
- actor: ACTOR1
segments:
- segment: 1
actions:
- description: Create a random post ID
script: var postId = $random(1000, 99999);
- description: Send a request to create a new blog post
action: org.getopentest.actions.HttpRequest
args:
url: https://jsonplaceholder.typicode.com/posts
headers:
Content-Type: application/json
verb: POST
body: |
$json(
{
id: postId,
title: "My fist post"
}
)
- description: Extract the response's status code and body
script: |
var statusCode = $output.statusCode;
var postInfo = $output.body;
- description: Validate the response status code
script: |
if (statusCode != 201) {
$fail($format(
"We expected the status code to be {0} but it was {1}",
201,
statusCode));
}
- description: Validate the post ID
script: |
if (postInfo.id != postId) {
$fail($format(
"We expected the post ID to be {0} but it was {1}",
postId,
postInfo.id));
}
- description: Validate the post title
script: |
if (postInfo.title != "My fist post") {
$fail($format(
"We expected the post title to be '{0}' but it was '{1}'",
"My fist post",
postInfo.title));
}
What next?
Let’s create and run your first API test. Create a new file named
My API test.yaml
in thetests
directory of the test repo, then copy & paste in it the full contents of this last test we looked at. In the OpenTest web UI, create a new test session to run the test namedMy API test
. When the test is finished, click on the test session link in the UI to examine the test results and look at the session log to understand the type of information available to you for troubleshooting. For extra points, modify one of the validation steps so that the test fails and run the session again. Then look at the log, to understand how the error information is displayed.Read the documentation for the HttpRequest action to get a general idea of its arguments and capabilities.
Create a new issue on GitHub and ask a silly question. We don’t care, we answer all of them.