# API testing

Most modern applications rely on API(s) to interact with a webserver, here at Virtuoso we know that API testing can be tedious and, sometimes, hard to implement. Our API testing features simplifies these tasks with Virtuoso's API test builder. Use the builder to define tests and execute them in journeys as test steps.

# Creating the first API test

For the purpose of this introduction, we are creating a basic request, named listUsers, and we want it to do a GET request against https://reqres.in/api/users.

Start by opening the API manager by clicking on the API testing icon on the side-bar.

Virtuoso groups API tests into folders so let's start by creating our first folder. Click on the New folder button, give it a name, staging in our example, and click on Save.

Now we can add our very first API test to the folder we've just created. Click on New request and the API test builder will appear on the right side:

Create API test

Fill in the name, listUsers in our example, and the URL, https://reqres.in/api/users in our example, then click on the Create button to create your first API test.

Now, click on the Send button next to the URL field to execute the request and see the response from the API in the Response box at the bottom:

API test response

This is the most basic way of creating an API test with the API manager, in the next section we explain how to use it as a test step inside a journey.

Project and organization API tests

As you may notice there are two main groups of API tests: Project and Organization. API tests defined at the project level are available to the current project only. API tests defined at the organization level are available for all your organization members.

# About API test folders

As outlined previously, an API test will always live inside a folder. You may create as many folders as needed, and you may also create nested folders with multiple depth levels.

As an example, here is a possible structure for your API tests:

  |     |__listUsers
  |     |__createUser
  |     |__deleteUser

# Searching for API tests or folders

On the left side of the API manager there is a search box that can be used to quickly find API tests or folders by name.

The list will be filtered, showing only folders or tests that contain the specified search term, or folders that contain other matching items.

API test search

# API test builder reference

This section explains all the settings that you may use to configure an API test through the API test builder.

Don't forget to save your changes

The API test builder lets you iterate your API tests definitions and execute those tests in quick succession.

Don't forget to save changes to the test settings as you make them to ensure that the changes are recorded for future use. Click the Save button at the top or press Ctrl + S on your keyboard.

# Input mapping

Think of API tests as a function with the specific purpose of sending an HTTP request and retrieving a response. Just like functions, they may have inputs which can then be used in other request settings like the URL or the body.

These may have a constant value or a variable based one, which is only computed at the time the API test is run from environment variables or values passed explicitly during execution. To denote a variable input, prefix its value with a $.

Using variables as input

Variable based input mappings are always prefixed with $.

In our previous example, if we mapped two inputs to our API test, a constant input index with value 3 and a variable input departmentId that derives its value from the variable $department, we would get the following input mapping table:

API test input mapping

To use input mappings in the remaining request settings enclose their name in double braces {{...}}, e.g., {{departmentId}}.

# Method and URL

The method for the request is the HTTP method that will be used by your API test: GET, POST, PUT or DELETE. By default, it is set to GET.

The URL is the endpoint of the API that you want to test, e.g., https://reqres.in/api/users.

# Request settings

The request may need additional settings to work properly such as authorization token, specific headers, or a body (e.g., POST requests usually use some value for the body of the request).

In all the following sections, the previously defined input mappings may be used. To do so, simply use the key of the desired input enclosed in double braces, e.g., {{departmentId}}.

Using input mappings in settings

To use input mappings, always enclose their respective key in double braces, e.g., {{<key>}}.

Escaped input mapping values

The values of inputs wrapped by double braces will be HTML escaped. For most cases this is OK.

However, there may be situations where this is not the desired behavior, and you want the full unescaped value. For example, let's assume the URL we're configuring in our test comes from an input mapping target. We could easily do that by typing {{target}} as our request's URL.

Assuming target is mapping to an environment variable with value https://reqres.in/api/users, we would expect this request to have the same result as before. However, it would fail because the request would actually be sent to the escaped version of the url, https:&#x2F;&#x2F;reqres.in&#x2F;api&#x2F;users.

To prevent these situations, encase the input mapping key in triple braces, e.g., {{{target}}}

# Authorization

By default, there is no authorization set, but you can use the dropdown to select an authorization type, e.g., Bearer token. After selecting an authorization type, you have to fill in the required information (e.g., the bearer token value).

API test authorization

# Params

You can configure the query parameters using a table-like interface to better organize what your request will use.

For example, if we want to add a parameter named id with value 123, the key would be id and the value would be 123. Similarly, if we want to pass the input mapping departmentId as parameter department, the key and value would be, respectively, department and {{departmentId}}. Type those into the respective fields and press ENTER or click on the plus icon to the right to get the params added to the URL.

API test params

Edit query parameters inline

Just like the URL field gets updated as you edit the query parameters on the table, the table will get updated if you edit the URL field inline.

# Headers

This section provides another table-like interface, similar to the query parameters interface, where you can add as many headers as needed to your API test request.

For example, if our API test request needs the header x-powered-by with the value VIRTUOSO, you have to type those respectively as key and value and then press ENTER or click the plus icon on the right.

API test headers

Automatically added headers

If the selected authorization type is Bearer token, the header with key Authorization and value Bearer <token> will be automatically added to the table.

# Body

Use the body section to add a payload to the request, e.g., the user details when creating a new user with an API.

API test body

Message about HTTP method being used

Depending on the HTTP method you have selected, the interface might show a warning message telling you that the body might not work as expected. A body is commonly used with POST requests as explained here. However, this will depend on the specific API you're using, so read its documentation to be sure of how it works.

# Output mapping

Just like you can define input mappings to the API test, you can also add pre-defined output values to it.

Whatever the response to the API test request may be, it will come wrapped in Virtuoso's own response (exposed as the variable $response) which contains 3 components:

  • status - the HTTP status code of the response to the API test request;
  • headers - an object containing key/value pairs for the response headers;
  • data - the actual data returned by the API test request;

With output mappings, you can apply simple transformations to any of these elements, as needed for the specific test, that will also be available in the output context of the API test. This is especially useful when you use API tests in your journeys and want to quickly access information snippets of the whole API response.

Using variables as output

Variable based output mappings are always prefixed with $.

For example, if you want to use the test we created before in one of your journeys to check if the API is successfully returning a response with the correct number of users, you can add two output mappings to make your tests simpler:

  • Add key status with value $response.status, to map directly to the HTTP status code of the API response;
  • Add key userCount with value $response.data.data.length, to map directly to the number of users returned by the API;

API test output mapping

Then, it is just a matter of creating assertion steps to validate these two numeric values against the expected ones.

# Manually testing an API

Even without integrating API testing with your journeys, the API manager is a powerful tool on its own. Each API test that you define may be run manually, with the response immediately shown to you at the bottom of the API test builder.

The response section is divided into four tabs:


This tab will display the payload of the response to the API test request. Virtuoso will try to display it as a JSON, so that property names and values are correctly highlighted, and objects and arrays can be collapsed and expanded.

API test response json


This tab is similar to the previous one as it will also display the response payload. However, in this tab, the value will be displayed as raw, unformatted text. This tab may be better suited for responses which are not expected to be in a JSON format.

API test response raw

# Headers

The headers tab will display a table of key/value pairs corresponding to the response headers.

API test response headers

# Context data

The last tab will display the request input and output context. This lets you know exactly what values were available to the request through the input mapping, as well as what values were exposed, when the request completed, through the output mapping.

API test response context

# Running tests with different settings

We have already mentioned input mappings and how these let you pass variables into the request. But how do these apply when running tests manually from the API test builder?

Virtuoso will try to match the input mapping variable based values to the variables defined in your environment. Looking back to our example, we could define the variable department in our environments and have it automatically passed to our request through the departmentId input.

Furthermore, we can have different values for the same variable in different environments, making it easy to test different scenarios. If there is a default environment, Virtuoso will use it unless specified otherwise. To switch environments, open the Send options menu, nex to the Send button, and select Send advanced.

This will bring up the send advanced modal, where you can select any of the environments available to you. Once you confirm your choice by clicking Send advanced, the request will automatically be sent with the selected environment being taken into account.

API test send advanced

Test local / private API using a bridge

If you want to send an API test request to a local or private API, you can use Virtuoso Bridge.

In the send advanced modal you may also select one of the available bridges to send your requests through.

# Using API tests in your journeys

Once you have built your API tests on the API manager, it's time to use them inside a journey as test steps. The syntax to be used for our NLP parser is:

API call "folder1.(...).folderN.apiTest"

Following our example in the previous section, if you want to use the API test named listUsers in folder staging, you have to use the NLP API call "staging.listUsers. As usual, Virtuoso provides NLP alternatives for the same action, you can use api "staging.listUsers" and it will produce the same command. Of course, the step editor will show you suggestions as you type so, if you have many API tests, you do not need to remember all of them.


At this point, you can execute your journey and see the results of the API test:

API test execution

# API tests and journey context

An API test's input and output mappings may be used in the context of a journey. Through Virtuoso's natural language syntax you may pass variables from the journey context into the API test and the test's output variables will be made available to take into the journey context as return values.

In our example, a more complete test step could look as follows: API test complete NLP

A complete analysis of this step reveals that:

  • We're executing the API test listUsers, inside folder staging;
  • The value 10 and context variable $department are being passed, respectively, to the API test inputs id and department;
  • The test is returning outputs status and userCount, which are being added into the journey context, respectively as $testStatus and count;
Last Updated: 11/19/2021, 12:07:56 PM