Variables

The variable page lets you configure, in one place, predefined variables.

To open the variables page, simply click on the Configuration > Variables button in the Virtual User page.

The left part of the page lists all the variables for the current project. Variables declared in ths list are common to all the VUs of a project. You can use the headers of this list to filter or sort it.

The right part displays the selected variable configuration. It is only editable if a variable is selected.

Three types of variables are available:

• Constant Variables that associate a single value to the variable name,
• Random Variables that associate a single random value to the variable name,
• CSV Variables that uses a CSV formatted file for the values of the variable.

Add Variable

The following procedure explains how to add a variable configuration:

1. Click on the Add button,
2. A dropdown appears,
3. Select the type of variable to add: Constant, Random or CSV,
4. A new variable name variable_n is added to the list and selected.
5. Edit the input fields on the right,
6. Close the variable panel by clicking on the Close button positioned at the top right corner.

Remove Variable

The following procedure explains how to remove a variable configuration:

1. Click on the variable to remove in the variables list,
2. Click on the Delete button.

Info

You can use SHIFT + click or CTRL + click to select multiple variables and delete them all at once.

Warning

As variable are commons to all VUs of a project, variable removal and update may affect VUs that you are note currently editing.

Constant Variable Configuration

The constant variable is used to provide the same value to every virtual user running. The value is not shared between virtual users which means they are free to change it. Any value placed in a constant variable remains there until changed or the test ends. Which makes it a poor choice for instance for a counter variable.

The following procedure explains how to change a Constant variable configuration:

1. Click on the variable to update in the variables list,
2. Edit the input fields on the right,
3. Close the variable panel by clicking on the Close button positioned at the top right corner.

For each Constant Variable, you can edit:

Property name	Description
Name	The variable name. To inject it, use the ${...} syntax. E.g. in the above screenshot, you could inject constant_value using the ${constant_variable} syntax.
Description	The variable description
Value	The constant value of the variable

Note

Edited variables are all updated when you close the variable modal. But variable addition / removal is done immediately.

Random Variable Configuration

The Random Variable is used to generate random numeric strings. It is only randomised at creation, so it's a good choice for a random value that needs to be used several times without changing. If you need a value that changes all the time, try with the ${__random(...)} function.

The following procedure explains how to change a Random variable configuration:

1. Click on the variable to update in the variables list,
2. Edit the input fields on the right,
3. Close the variable panel by clicking on the Close button positioned at the right left corner.

For each Random Variable, you can edit:

Property name	Description
Name	The variable name. To inject it, use the ${...} syntax.
Description	The variable description
Minimum Value	The Random Variable range lower bound.
Maximum Value	The Random Variable range upper bound.
Output Format	The output format of the generated value. Leave blank for a simple number output. It uses the java.text.DecimalFormat. For example 000 generates numbers with at least 3 digits, and USER_000 generates output of the form USER_nnn.

Counter Variable Configuration

The Counter Variable is used to generate numeric counters. It is set to Start value at initialization, incremented by Increment on each new iteration until it reaches End. The value is shared between all virtual users running on the same load generator by default.

The following procedure explains how to change a Counter variable configuration:

1. Click on the variable to update in the variables list,
2. Edit the input fields on the right,
3. Close the variable panel by clicking on the Close button positioned at the right left corner.

For each Counter Variable, you can edit:

Property name	Description
Name	The variable name. To inject it, use the ${...} syntax.
Description	The variable description
Start Value	The Counter Variable starting value.
End Value	The Counter Variable ending value.
Increment Value	The Counter Variable increment, applied on each iteration.
Output Format	The output format of the generated value. Leave blank for a simple number output. It uses the java.text.DecimalFormat. For example 000 generates numbers with at least 3 digits, and USER_000 generates output of the form USER_nnn.
Track counter	The Counter Variable can be local to each user if this is activated.
Reset counter	The Counter Variable can be reset at each user iteration. This will effectively reset the counter to Start value every iteration, which can be useful if you edit it through scripts during the iteration.

CSV Variable Configuration

A CSV file consists of any number of records, separated by line breaks of some kind; each record consists of fields, separated by some other character or string, most commonly a literal comma or tab.

Each time a Virtual User is executed, it uses a line of the CSV file and gets one variable for each column. E.g. if you run a scenario for one hour, with a VU that takes 5 minutes to execute, you would need 12 lines in your CSV file to allow each VU ran to have its unique set of variables.

The CSV file parsing is configured in the Configuration tab. And the variables naming is done in the Column tab. The Column tab also shows a preview of the extracted values.

The following procedure explains how to change a CSV variable configuration:

1. Click on the variable to update in the variables list,
2. Enter a name and description,
3. In the Configuration tab, select a CSV file to upload,
4. Select encoding, delimiter and other options (explained bellow),
5. Switch to Columns tab,
6. For each column, type the name of the corresponding variable,
7. Close the variable panel by clicking on the Close button positioned at the right left corner.

Property name	Description
Name	The variable name. To inject it, use the ${...} syntax.
Description	The variable description
File	The CSV file of the variable
Shuffle Rows	Shuffles the CSV file lines before executing the test
Encoding	The CSV file encoding, leave blank if UTF-8
Delimiter	The character or string used to separate the fields in the uploaded CSV file. Usually a comma
Allow quoted data	A value may be enclosed in double-quotes if this option is selected
Sharing mode	Private or Shared, if private each VU instance will use its own data set
Recycle values on EOF	Should the file be re-read from the beginning when reaching its end? If set to false the value is set to <EOF> when the end of the file is reached
Stop VU on EOF	Should the Virtual User be stopped when the end of the file is reached. Can only be activated if the Recycle values on EOF option is not

Note

If Allow quoted data is enabled, values in the CSV file may be enclosed in double-quotes. These are removed. E.g. you use a comma delimiter but one of your values contains a comma character. You can escape this value by placing it between quotes.

To include double-quotes within a quoted field, use two double-quotes. For example, with the CSV content (comma character used as a delimiter and quoted data allowed):

first,"second",last
1,2,3
1,"2,5","4""5"

Column one	Column two	Column three
first	second	last
1	2	3
1	2,5	4"5

Sharing mode

Private

Selecting private means that each user will read the file sequentially on its own. If you have 2 values in your file login1 and login2 and set it on Recycle, the result would be:

Iteration	Virtual user 1	Virtual user 2
1	login1	login1
2	login2	login2
3	login1	login1

Warning

If you use Shuffle rows before test execution?, we will only shuffle the file before the test. Which means that every user will still be using the same values in the same order. If that's not what you're looking for, you should try with Shared instead.

Shared

Shared means that the load generator will distribute a different value to each user when they ask for one. Of course that remains true as long as there are unique values left in the file. See end of file policy for more details. If you have 2 values in your file login1 and login2 and set it on Recycle, the result would be:

Iteration	Virtual user 1	Virtual user 2
1	login1	login2
2	login1	login2
3	login2	login1

Since unique values are only guaranteed at the load generator level, we also split the CSV between load generators so that each one gets a unique list of values. More information on that topic is available on the CSV splitting page.

End of file policy

Upon reaching the last line of the file you can set the CSV variable to behave in two ways:

• Recycle and loop back at the beginning of the file,
• Stop VU meaning the number of users running during your test might drop down. If this happens, a message will be visible in the JMeter logs.

Columns

The column tab gives a preview of the extracted values:

You can use it to check if your configuration gives the expected output.

Each column header is editable. It lets you name each of the variables. E.g. in the above screenshot, you could inject id using the ${id} syntax and value using ${value}.

Tip

You can leave empty column names. In this case the first row of the CSV file is used as variables names.

Skip to next line

CSV files in OctoPerf are parsed once every iteration. If you need to skip a line or just want to parse the whole CSV in one iteration, you can use the __CSVRead function.

Example for a file named credential.csv:

• ${__CSVRead(resources/credentials.csv,0)} will be replaced with the first column of the current line,
• ${__CSVRead(resources/credentials.csv,1)} will be replaced with the second column of the current line,
• ${__CSVRead(resources/credentials.csv,next())} will skip to the next line.

Info

Value distribution is not configurable, it will always be equivalent to shared. Meaning that it can skip lines because another thread/user might already have taken the next one.

Warning

This function does not use the CSV variables at all, it works on an earlier version of CSV variables. Because of that you do not need to create a CSV variable to use it, just provide the file.