Variables
Variables allow you to capture and reuse dynamic values within a single API test. This is particularly useful for scenarios where unique or runtime-specific data is required.
Testing Unique API Payloads: When testing an API endpoint that creates new records, such as registering a new user, you often need unique identifiers (e.g., email addresses or usernames) for each test run. By assigning dynamically generated values to variables, you can ensure that your tests run successfully without encountering duplicate data errors.
Validating Dynamic API Responses: Consider testing an API that returns time-sensitive data or variable prices for products. By extracting these response values into variables, you can assert on calculated outcomes (e.g., totals or discounts) without needing static values.
Define a Variable
After executing an API request, you can extract the data from a response body and assign value to it.
Execute API request.
Receive the response and select and copy a value from the response body.
Select the context menu option, and give the variable a unique name.
Parameters
Parameters are similar to Variables and work in much the same way after they are assigned. However, while Variables are typically for dynamic values captured during a test or defined globally as Account Variables, Parameters are values passed directly into the test.
Here are a few example usages of Parameters in API testing:
Testing Role-based access controls. Use Parameters when you need to verify that an API endpoint works correctly for all user roles in your application. You can create a single test that verifies the endpoint functionality and parameterize the user credentials or tokens used in the test. This approach allows you to execute data-driven tests across all roles without duplicating tests.
Testing internationalized API Responses. To validate internationalized (i18n) API responses, you might start with a test that checks the response content using a default locale. To extend this test for other locales, you can parameterize the Accept-Language header and the expected response content. By passing the desired locale as a Parameter, you can validate API behavior across various languages.
Testing Environment-specific Configurations. When running automated tests across multiple environments (e.g., development, staging, production), some configurations may differ. For example, API keys or base URLs may vary per environment. You can create a reusable "Authentication" Segment that takes API keys or tokens as Parameters and pass in the correct credentials for the target environment.
When defining a Parameter, you can optionally assign a default value. A Parameter’s default value will appear on the Test definition page, along with a link to all of the steps that reference the Parameter within the Test. Additional Parameters can also be added to the Test by clicking ‘Add Parameter’ on the Test definition page.
In order to delete a Parameter, you must first delete all of its references within the Test.
Use Parameters in Segments
In addition to defining Parameters for a Test, Parameters can also be defined for a Segment. When a Segment is added to a Test, any Parameters associated with the Segment are now associated with the Test.
Let’s consider a test that logs into an application, uses that application’s search function to search for an existing record, and finishes by doing some assertions on the data displayed for that record. If you were building out other tests for this application, probably a lot of those tests would start by logging in, and maybe a fair number of them would use the search box to search for a record (such as tests to find and delete a record, or find and edit a record).
When the same set of actions appear in multiple tests, that’s a good indication that those actions should be refactored into a reusable composition. So in the case of this test, we’d extract two sets of test steps into Segments: one segment for logging in, and another segment for searching for a record.
Now let’s consider what we might want to change about these Segments if we wanted to use them in other tests:
For the “Login” segment, we might have tests that require logging in as a different user than what we originally recorded.
For the “Search” segment, we might have tests that require searching for a different search term than the exact search term we originally recorded.
If there is data within a Segment that should change depending on what test is using it, that’s a good indication that that data should be turned into a Parameter:
For the “Login” segment, we’ll create two Parameters: “username” and “password”. We’ll keep the default test user’s credentials as the default values for this Segment, since most tests are going to be logging in as this user.
For the “Search” segment, we’ll create one Parameter: “search term”, which is the input that’s passed into the search box before the search button is clicked. We might elect to not save a default value for this Parameter, since so many different kinds of search terms could be used, and we want to ensure whoever uses this Segment knows they have to define the proper search term for their test.
When inserting a Segment containing a Parameter into a Test, you will be prompted to define the Segment’s Parameter values.
Populating a Segment’s Parameters using Variables
In the example above, we described a test for an authenticated application that includes a Segment which uses the application’s search functionality. This Segment contains a single Parameter called “search term”, which has no default value.
Because this Parameter has no default value, if we want to use it in another test then we’re going to need to define its value somehow. Normally you would define some static value and save it as the Parameter’s default value for that Test, but an alternative would be to use some value that’s extracted earlier on in the test itself.
A good example would be a test that creates a new record, and then immediately searches for that record in the app. In this scenario, we’d want to extract the ID of the new record that was created, and search for that dynamic ID in the search box. We can do this by assigning the record ID to a variable called “search term”, and then inserting the Segment somewhere after we extracted the search term.
When inserting the Segment, you’ll notice that the “search term” parameter is shown as already populated with the value extracted earlier in the test, and the Parameter’s default value is not editable. Whenever this test runs, the “search term” parameter will be populated with whatever new record ID was generated by the application.
On the Test definition page, Segment Parameters will also appear with its default value disabled, indicating that the value is defined as part of the test. The location where the Parameter’s value is defined can be found by finding the Variable of the same name on the Test definition page, and clicking the ‘Assigned in Step X’ link.
Functions
To generate a dynamic value for a given variable, you can use one of several supported Functions. Support for generating random letters and digits comes from the following functions: alpha(len), num(len), and alphanum(len). Each of these functions takes a value that specifies how many random characters to generate. The range(min,max) function generates a random number between min and max, inclusive. Support for generating timestamps and dates comes from the following functions:
time(offsetMs)- returns an epoch timestamp after addingoffsetMsmilliseconds to the timestamp,datetime(offsetMs)- returns a date time string of the form “Wed Oct 07 11:19:04 EDT 2020” after addingoffsetMsmilliseconds to the date,date(format,offsetDays)- returns a formatted date string after addingoffsetDaysdays to the date. The supported formats include only the characters:dDmMyY/, and are parsed using Java’s SimpleDateFormat.
Examples
Definition | Example Value |
|---|---|
| user+akfboaqbop@example.com |
| passboiqg |
| oq2ki16n |
| Call me, 0149783430 |
| Day: 23 |
| Today: 1602084695965 |
| Today: Wed Oct 07 11:19:04 EDT 2020 |
| Meeting: Wednesday 10/7/20 |
| value1 and value2 |
| abcd1234 |
In the var examples, varOne is defined as value1 and varTwo is defined as value2. In the sec example, the account’s Secret, my-password, has the value abcd1234.