Variables & Expressions

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

They make it possible to do things like:

  • Make each v-user log in with a different username and password.
  • 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.

Using Variables

You can use variables in many parts of your HTTP commands, including:

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

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.

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 different data for each v-user. 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.

Variable Scope

Each v-user has a separate variable registry. This means that each v-user has their own value for a given variable, and setting a variable for one v-user will have no effect on other v-users.

Setting Variables

There are two 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 v-user 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.

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 v-user. 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:${urlencode(uppercase(Email))}

Operations will be applied in order, starting with the innermost function and proceeding outwards. In the example above, a username like 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 v-user in the group, starting with `0`.
population() Returns the unique identifier of the current v-user's group.
engine() Returns the identifier of the currently running load 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.