Variables & Expressions

Loadster’s variables and expressions allow you to use dynamic values in your scripts.

They make it possible to do things like:

  • Log in with a different username and password each time.
  • Capture a CSRF token and reuse it when submitting a secure web form.
  • Submit a search with a different search phrase each time.

While load testing a static website may not require any special variables or expressions, you’ll probably need them if you want to test a dynamic web application or API.

Variables and expressions work in both protocol scripts and browser-scripts.

Using Variables

Loadster 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.

Using Variables in Protocol Scripts

In protocol scripts, you can use variables in many parts of your HTTP steps, such as:

  • The Primary URL
  • One or More Page Resource URLs
  • Custom Headers
  • Basic Authentication (username and password)
  • Request Body (if it is a POST or PUT request)

Request URL

Variables can be used to modify the primary URL for a request, or to set dynamic query string parameters.

Using a variable in the URL
Using a variable in the URL

When your script runs, ${UserID} will be substituted with the actual value of the UserID variable.

Page Resources

In the example below, a page resource with the ${CoverImage} variable has been added to the selected HTTP command.

Using a variable to load a dynamic page resource
Using a variable to load a dynamic page resource

Request Headers

You can enter a Request Header and then insert the variable as the value. This example shows an Authorization header with ${AuthToken} as the value.

Setting a dynamic request header based on a variable
Setting a dynamic request header based on a variable

Basic Authentication

When setting up Basic Authentication for a HTTP Command, you can enter a variable for the HTTP Basic Username and Password.

Using variables for HTTP Basic Authentication
Using variables for HTTP Basic Authentication

Request Body

In the example below, several values are set as variables in the request body. This makes it possible to submit a request with different data for each bot. This also works for other body types, not just JSON.

Using variables in a request body
Using variables in a request body

Important: When using variables in a request body, the “Interpolate variables in request body” option must be selected. Otherwise, they will be sent as literal strings instead of interpolated variables.

Using Variables in Browser Scripts

In browser scripts, you can use variables or expressions in the DOM selector field or any other primary field. For example, you could use a variable to supply the text to be entered in a username or password field.

Variable Scope

Each bot keeps its own separate variable registry. This means that each bot has their own value for a given variable at any given time, and setting a variable for one bot will have no effect on other bots.

Setting Variables

There are three primary ways to set a variable in a Loadster script: from a Dynamic Dataset or with a Capturing Rule.

Dynamic Datasets allow you to seed data for your test ahead of time. For example, you might create a data set that contains a list of usernames and passwords. Each bot would then pull a unique value from the data set and use it when they run the script. Dynamic data sets are a great way to set variables when you know ahead of time what values you want to use.

Capturing Rules let you extract values on the fly from the actual HTTP responses coming back from your web application. They are a powerful way to parameterize your scripts when you do not know ahead of time the exact values your application will be returning. For example, you could capture a unique registration code that your application generates after you submit a registration form.

Code Blocks can set and retrieve variables programmatically, with user.getVariable(name) and user.setVariable(name, value). When you do this, the variable value is always cast to a string.

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.

The expression syntax is ${func(var)}, where var is the name of your variable and func is the function that is applied. Loadster supports several functions out of the box, and functions can be nested to apply multiple transformations to the same variable.

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 SearchPhrase which contains the email address of the current bot. Normally, you could reference it like this:

Substituting a literal value in the URL
Substituting a literal value in the URL

However, the email address has an @ character in it which is not always safe in URLs. To encode it, use the urlencode() function:

Substituting a safe URL-encoded value in the URL
Substituting a safe URL-encoded value in the URL

The urlencode() function in your expression will apply URL encoding to whatever value the SearchPhrase variable currently has. So if your search query is “Transfer Coin”, Loadster will substitute the correct URL encoded equivalent of “Transfer%20Coin”.

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 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 Function Reference

The following functions are supported in Loadster 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.
vuser() Returns the number of the current bot in the group, starting with `0`.
population() Returns the unique identifier of the current bot's group.
engine() Returns the identifier of the currently running engine or cloud region.

Next Steps

Read more about setting variables ahead of time with Dynamic Datasets, or setting them on the fly with Capturing Rules.