Contents ▼

Variables & Expressions

Speedway's variables and expressions allow you to inject dynamic values in your monitor steps. For most APIs, this is better than testing with the same canned data each time.

Using Variables

Variables can be used in many parts of your HTTP steps, including:

  • URL
  • Custom Headers
  • Basic Authentication (username and password)
  • Request Body (if it is a POST or PUT request)

Variables are denoted by the ${var} syntax, where “var” is the variable name. Variables can have any name you want, as long as it is alphanumeric text with no spaces.

Variable Scope

Each monitor cycle receives a fresh variable scope. Other monitors, or other cycles of the same monitor, will not see any of the variables that you set in a monitor cycle. However, subsequent steps in the same cycle will.

Setting Variables

There are two ways to set a variable in a Speedway monitor: via a Capturer on a regular HTTP step, or in a Code Block.

To set a variable with a Capturer, create any capturer from the Add... menu, and specify the variable name where the value should be saved.

To set a variable in a Code Block, use the user.setVariable(name, value) method on the ubiquitous user object.

Using Expressions

Expressions allow you to perform simple operations on the value of a variable as it is interpolated. They do not affect the variable itself; only the substituted value. They are basically simple function calls within an escaped variable syntax.

The expression syntax is ${func(var)}, where var is the name of a parameter and func is the function that is applied. Some functions don't require a parameter at all. Speedway supports several functions out of the box, and functions can be nested to apply multiple transformations to the same value.

Example #1: URL Encoding a Query Parameter

HTTP requires that special characters in a URL be “URL encoded”. Let's say we have a variable called email which contains an email address. Normally, you could reference it like this:

https://garage-example.speedway.app/vehicles?ownerEmail=${email}

However, the email address has an @ character in it which is not allowed in HTTP query strings. To encode it, use the urlencode() function:

https://garage-example.speedway.app/vehicles?ownerEmail=${urlencode(email)}

The urlencode() function in your expression will apply URL encoding to the value of the email variable.

Example #2: Escaping Characters in a JSON Request

Let's say you are testing a RESTful JSON endpoint. The request is supposed to be a POST request with a payload like this:

{ "fullName": "Buford \"Mad Dog\" Tanner", "age": 26 }

Instead of submitting the same name each time, you decide to use a Dynamic Dataset to pre-populate a list of names and ages, and then parameterize the request body with variables:

{ "fullName": "${FullName}", "age": ${Age} }

But what if your data set contains double quote characters or other characters that are illegal in JSON? To be safe, you should escape them with the jsescape() function:

{ "fullName": "${jsescape(FullName)}", "age": ${Age} }

The jsescape() function guarantees that the interpolated value is safe to use in a JavaScript or JSON string.

Example #3: Chaining Multiple Expressions Together

There may be occasions (hopefully not too often) that require performing multiple functions on a single value. It is quite straightforward:

http://www.example.com/users?funkyCapitalizedEmail=${urlencode(uppercase(Email))}

Operations will be applied in order, starting with the innermost function and proceeding outwards. In the example above, a username like *user@company.com* would become *USER%40COMPANY.COM*.

Example #4: Using a Timestamp in a Request

Sometimes you need to send a current date or timestamp when making a request.

{ "name": "Biff Tanner", "age": 26, "dateCreated": "${timestamp("yyyy-MM-dd'T'HH:mm:ss.S'Z'")}" }

This example formats the timestamp with the current date/time in JavaScript's built-in ISO8601 format. You can specify a different format in the expression (see below).

Expression Reference

The following functions are supported in Speedway expressions:

function description
urlencode(str) Applies URL encoding to the value.
urldecode(str) Decodes a URL-encoded value.
jsescape(str) Escapes a value so it is safe to use in a JavaScript string.
jsunescape(str) Removes JavaScript escape characters from an escaped string, so it can be displayed literally.
htmlescape(str) Escapes a string so it can be used safely in HTML, applying escape sequences like < and >.
htmlunescape(str) Removes HTML escape sequences and turns them back to their literal characters.
xmlescape(str) Essentially the same as htmlescape() but for XML.
xmlunescape(str) Essentially the same as htmlunescape() but for XML.
uppercase(str) Turn all letters in a string to uppercase.
lowercase(str) Turn all letters in a string to lowercase.
timestamp() Outputs a current Unix timestamp in seconds since the epoch, e.g. 1404432584.
timestamp("yyyy-MM-dd") Outputs a current timestamp, in a format you specify. The format is based on Java’s SimpleDateFormat.
uuid() Generates a UUID/GUID, like 1e06863a-6118-426d-bf46-35858c7d797.
randomalpha(len) Generates a random string of alpha characters, of the specified length.
randomnumeric(len) Generates a random string of numbers, of the specified length.
randomalphanumeric(len) Generates a random string of mixed alpha characters and numbers, of the specified length.