Tabular Variables

Define your own variables and values by setting up Tabular Variables, a perfect use case for login credentials in Sign-In tests.


Tabular Variables are a simple way to inject dynamic data into your test steps. Simply define your own variable values within a CSV file and upload them to Rainforest. Then, within a test step, these variables act as placeholders which are replaced with data when a tester executes one of your tests.

In this article, you’ll learn:

  • How to create your own tabular variables and upload them to Rainforest
  • How many values must be defined when uploading your tabular variables
  • How tabular variables are assigned
  • How to add tabular variables into a test step
  • Common use cases for tabular variables

Adding new tabular variables

To add new tabular variables:

  1. Define the tabular variables you’d like to add to Rainforest and save them as a CSV file (see image below) - read on to the “How many values you need to define when uploading your tabular variables” section below to learn how many rows you will need in your CSV file.

In the example below, we are creating two new tabular variables; {{}} and {{logins.password}}.

  1. Open the Step Variables settings page and click on the "Add New" button in the "Tabular Variables" section.
  1. Enter a name for your variable group, consisting of letters, numbers, and underscores. Spaces and special characters are not supported at this time.

  2. Enter a description for your tabular variable so that all members of your team can understand at a glance the purpose and intent of this variable.

  3. Last, select "Choose a file'' under the 'File' row to select the CSV file* for the tabular variable. Each row will be converted into a new tabular variable, named in the pattern {{variable_group_name.header_name}}.

  4. Once created, you can edit or remove tabular variables as needed by clicking Edit or Delete on the right-hand side of each variable in the list.

Note: To avoid disrupting your test runs, you must provide sufficient variables for each tester to have a unique variable. You can calculate the number of variables needed according to the instructions in the following section.

How many values you need to define when uploading your tabular variables

When a test is initiated, each tester will be assigned one unique row of variable values. To ensure that you will have sufficient variables for multiple testers, we use the following equation:

Required minimum number of variable rows:

Tests x Browsers/Platforms x 6 Testers

  • Tests = number of tests that will use this variable in a single run
  • Browsers/Platforms = number of browsers or platforms you will run the tests against
  • Testers = the maximum number of testers we will send to each test

For example, to successfully run 2 login tests against 3 browsers the minimum number of step variables required would be 36 (2 Tests 3 browsers/platforms 6 testers). If you do not have the minimum number of required rows of values, your run may not complete and result in an error.

How tabular variables are assigned

Variables are randomly assigned and will not repeat per run unless they have been marked as reusable.

Note: marking variables as “Reusable” when uploading your CSV file can have a significant impact on your test result time. Reusing variables causes a sort of gate system of "One out, one in" for your testers.

For example: if you have only two login variables, but three testers, the third tester will not be able to proceed with the test until one of the first two has finished. In terms of speed, it is always best practice to add more rows of variables rather than listing something as reusable.

How to add tabular variables into a test step

Within the step editor, click '{} step variables' to bring up the step variables menu:

Click on any of the step variable groups to reveal all the step variables within it.

Last, click the variable you wish to insert.

Common use cases

The most common use-case for tabular variables is assigning unique login credentials to each tester a unique login to avoid any shared state** issues arising from the different testers' actions.

Once you're familiar with how step variables work, you can use them for any set of data that you wish to test against. A few ideas:

  • Login credentials
  • Unique account information
  • Product category codes
  • Educational course names

There are endless use-cases, so please get in touch if you're not sure how to begin taking advantage of tabular variables!

Rainforest assumes that all tabular variable files are encoded in UTF-8. As such, please ensure that the files provided are encoded in UTF-8.

Shared state refers to when two people—testers in our case—are trying to use the same account at the same time. For example, imagine two testers trying to update a Facebook profile picture at the same, one may very likely overwrite the other. This causes intermittent and unexpected failures and can be avoided.

If you have any questions, please feel free to reach out to us at [email protected] or through Intercom!

Updated 3 months ago

Tabular Variables

Define your own variables and values by setting up Tabular Variables, a perfect use case for login credentials in Sign-In tests.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.