API requests and response validation

The mabl trainer has the ability to send API requests and interact with the responses via the "API request" step, also called an API step. Use these steps to expand your test coverage beneath the UI without directly interacting with it. Currently, the API steps feature supports APIs exposed over HTTP or HTTPS.

Enterprise feature

This feature is available to customers on the Enterprise plan, as well as all mabl trials.

Creating an API request step

You'll need to use the mabl trainer to add API steps. You can also add these steps via the "Quick Edit" trainer used to edit existing tests.

With the mabl trainer open, click the ellipsis icon in the bottom right to view the "API request" button. Click the button to start adding a new step.

Using the API request step

The Basics

At the top of the modal that appears you'll find the following:

  • An API request method dropdown
  • A URL field
  • A "SEND" button

Clicking on the request method dropdown allows you to select the specific API request method you'd like to perform against the specified URL. There are a number of request methods to choose from, and you can find more information about each of them at this helpful resource. Finally, there's the "SEND" button. Clicking this will send the request to the desired URL. If you'd like, you can use variables in the URL using the regular {{@variableName}} syntax that you would use regularly to reference a variable made in a previous step.

Modifying the Request

In the lower left, you'll find a large module with the sections "Header," "Authorization," as well as "Body." With these optional sections, you're able to modify each of the parts of your initial API request to fit your exact needs. The headers section, for example, the actual API response headers in JSON form and not the JSON formatted response body. Additionally, you can use variables in the request body using the same {{@variableName}} syntax, similar to regular JavaScript steps.

Sending the Request

Once you've selected the proper request method, populated the URL field, and filled out the optional information mentioned above, it's time to send the request. To do so, simply click the "SEND" button in the top right of the modal.

After you've done the above, the "Request" module in the lower left has changed to "Response," populated with the results of your request.

The response is presented as a JSON object containing the following fields:

  • headers: An array of HTTP response headers, each containing a name and value field
  • status: The HTTP response status

The response may also contain:

  • body: The response body converted to a string
  • json: If the HTTP response body contained a JSON object, this is the parsed JSON

Using the result

Now that you've received a result from your request, you can interact with the request in a couple of ways:

Make assertions

The module on the right of the modal is set to "Assertions" by default. From here you're able to assert on the Status, Header, and Body (JSON or text) of the result. For example, you can assert that the response code was 200 or the Content-Type header in the response was application/json.

Extract the response into a variable

You can use parts of the response to form variables that can be used later in your tests. Additionally, you can also save the entire response as a variable by selecting the "Response" option from the dropdown and giving it a name. You can use this variable later on for multiple purposes, such as using it in a JavaScript Step. A path can also be specified to retrieve a particular value from the response.

Another use case might be that you get a JSON body back in the response such as { "mail": "Bab.Jensen@acme.com" }. From there, you could then extract the json.mail field and assign it to a variable called emailAddress, then input that into a text field in the app in a later step using the standard "Use Variable" step.

Syntax

Retrieving data from the response is the same as extracting JSON values from a hierarchical JSON document. If you wanted to extract the value of 1010 Park Street from the response below, you would reference it using attribute people[1].address when the Assertion or Variable is set to JSON (Body). To extract the value Juneau, use the attribute capitals.Alaska or capitals["Alaska"].

{
  "headers": [
    {
      "name": "content-type",
      "value": "application/json"
    }
  ],
  "json": {
    "people": [
      {
        name : "Ada",
        address: "1 Main Street"
      },
      {
        name : "Charles",
        address: "1010 Park Street"
      }
    ],
    "capitals": {
      "Alabama": "Montgomery",
      "Alaska": "Juneau"
    }
  },
  "status": 200
}

When you've done the above, simply click "Save" to add the step to your test.

API requests and response validation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.