Variables allow you to dynamically insert data into a request using built-in functions (timestamps, random strings, hashes), configuration data from environments and data extracted from a previous response in a test run. Data is inserted into requests using a simple template format.
- Using Variables to Pass Data Between Steps (Chained Requests)
- Environment Variables
- Use Built-in Variables and Functions
- Use Variables in Requests
- Evaluation Order of Initial Variables
Use Variables to Pass Data Between Steps (Chained Requests)
Request steps can define variables that extract data from HTTP responses returned when running the test.
To create a variable, follow these steps:
- Expand a request within your test.
- Click Variables.
- Specify the location of the data you want to extract from the response.
- Choose a variable name to reference it in a subsequent request.
The location of the data to extract. Data can be extracted from HTTP header values, JSON body, response size or time, response status code, text body, or XML body.
The property of the source data to retrieve. For HTTP headers this is the name of the header. For XML and JSON content, see below. This field is unused for Text Body and Status Code.
The name of the variable to assign the extracted value to. In subsequent requests you can retrieve the value of the variable by this name. See Using Variables in Requests.
You can extract data through the following methods:
- Extract data from JSON Body Content
- Extract data from XML Body Content
Data from an XML response body can be extracted by specifying the path of the target data using XPath. In the 'Property' box of a variable definition that uses 'XML Body' as the source, enter an XPath expression to locate the data to extract and assign to the variable.
- Extract data from Text Body
Saves the entire text of the response to a variable.
- Extract data from Text Body using Post-response Scripts
You can specify the start and end boundaries of data to be extracted by running an extractor script through Post-response Scripts.
Environments allow you to manage configuration on a per-test or per-bucket level. Common values (base URLs, API tokens, etc.) that are shared across requests within a test, or tests within a bucket, should be stored in an Initial Variable or Initial Script within an environment. Once defined, the variable is available to all requests within the test.
Initial Variables specify data available to all requests in a test, including the first request. This can be useful for storing values that are common to all requests (like API keys) or other data required to set up the test run. Each test run will use the initial variables specified by the selected environment. To override variables on a per-run basis, use a Trigger URL with Custom Initial Variables.
Initial Scripts are executed before the first request in a test is made, but after the Initial Variables have been evaluated.
variables.set() can be used to read and write variable values to be used by requests in the test. See: Scripts: Initial Script and Evaluation Order of Initial Variables.
Use Built-in Variables and Functions
In addition to the variables you define yourself, you can use these built-in variables and functions to generate common types of data.
||Integer Unix timestamp (seconds elapsed since January 1, 1970 00:00 UTC)||1384035195|
||UTC datetime string in ISO 8601 format.||2013-11-07T19:24:41.418968|
||Timestamp of the specified value in the specified
be used in the
of any of the following date/time format
options. Also accepts variables. E.g.
||Integer Unix timestamp offset by the specified
||Random integer between 0 and 18446744073709551615.||407370955|
||Random integer value between
||Random alphanumeric string of the specified
||Random universally unique identifier (UUID).||99386c08-6da7-4833-bb31-e70ce747c921|
||Generate an MD5 hash based on
||Generate an SHA-1 hash based on
||Generate an SHA-256 hash based on
||Generate an HMAC using the SHA-1 hashing algorithm based on
||Generate an HMAC using the SHA-256 hashing algorithm based on
||Create a percent-encoded string suitable for URL querystrings. This is not required for URL or form parameters defined in the request editor which are automatically encoded. Only use this if you need to double encode a value in a URL or include a URL encoded string in a header value.||This%20is%20100%25%20URL%20encoded.|
||The name of the environment used for this test run.||prod|
||The unique ID of the environment used for this test run.||ab34b187-bcde-4f41-9ec1-ff77e99aa2d6|
||The bucket key for the Runscope Bucket the executing test is contained within.||y0z5xkr1oa3m|
||The name of the Runscope Bucket the executing test is contained within.||Jumping Rabbit|
||The unique identifier for the Runscope test.||a8ea3ddd-73bb-435c-bc44-7c4bc8d99647|
||The name of the Runscope test.||Sample Test|
||The region code indicating the location in which this test run was initiated.||eu1|
||The unique identifier for the agent which is running the agent. Blank if run from a Runscope location.||83a24630-323d-501a-74a1-a7e51485ca12|
Note: these built-in functions are only available in the web-based variable editor and not Scripts.
Request an additional built-in variable or function by contacting support.
When using a built-in variable in the value of an initial variable, the value will be generated once and remain constant across all the requests in a test (unless later overridden by another variable definition).
Override Built-in Variables
You can define a variable that uses the same name as a built-in variable or function. This will override the built-in value with the value extracted from the test response.
Use Variables in Requests
Once a variable has been defined, you can use it in any subsequent request. The test steps editor will display the 'Available Variables' that have been defined prior to the selected request. Variables can be used in any request data field including the method, URL, header values, parameter values and request bodies.
To include the value of a variable in a request, enter the name of the variable surrounded by double braces e.g.
If a variable is undefined when a request using that variable is executed, the test will fail.
Evaluation Order of Initial Variables
Variables can be set at various points in the setup of a test run. At each step of the setup, a variable value specified in an earlier step can be overridden. Variables defined via Trigger URLs, Initial Scripts and Initial Variables will be evaluated in the following order:
- Variables defined in a shared environment (if the selected environment for a test run inherits from one).
- Variables defined in an individual test environment.
- Variables set via an environment-specific or a bucket-wide Trigger URL.
- Variables set using
variables.set()in a shared environment's Initial Script.
- Variables set using
variables.set()in an individual test environment's Initial Script.