Variables

Variables are names used to store one or more values. Instead of repeating these values in multiple places in tests, the variable will keep the results of a calculation, step execution, expression evaluation, or any other user-defined data.

VIVIDUS provides the following syntax to access variable value:

${variableName}

There are 2 types of variables:

  • regular - such variables are initialized and controlled by users;

  • dynamic - these variables are available out of the box and provided by VIVIDUS core and plugins, the values of such variables are calculated at the runtime (i.e. the same variables in different parts of tests may result in different values).

    Dynamic variables support both lower camel case (e.g. ${dynamicVariableName}) and lower hyphen case (e.g. ${dynamic-variable-name}) name formats.

Resolution

Whenever the variable placeholder is found in tests, VIVIDUS attempts to resolve it using the chain having the following order:

  • regular variables,

  • default value if it’s specified in the variable placeholder,

  • system properties,

  • OS environment variables,

  • dynamic variables (keep in mind, if dynamic variable is available, but couldn’t be resolved due to errors or conditions mismatch, the error message will be logged and variable will be kept unresolved).

If the end of chain is reached and the variable is not resolved, the variable placeholder will be kept as is: ${variableName}.

Regular variables

Scopes

Regular variables can have one of the following scopes.

The scopes names are case-insensitive.
Name Description

step

The scope is used within nested steps and the variables are invalidated after the nested steps are executed.

scenario

Variables are available in the rest of the scenario after variable declaration. scenario-scoped variables are invalidated once the scenario is completed.

story

Variables are available in the rest of the story after variable declaration. story-scoped variables declared inside given stories are available in the parent story. Variables are invalidated once the story is completed.

next_batches

Variables are available in the next batches. next_batches-scoped variable is not available in batch it’s declared within.

batch

Such variables are declared only with batch-<batch-number>.variables. prefix and available throughout the execution of the batch in the suite. An attempt to create the batch-scoped variables during test execution leads to an error.

Example 1. Declaring batch variable locale
batch-1.variables.locale=/us/en/
batch-2.variables.locale=/uk/en/
Example 2. Using batch variable locale
Given I am on main application page
When I go to the relative URL '${locale}'

global

Such variables are declared only via properties with variables. prefix and available throughout the entire execution. An attempt to create the globally scoped variables during test execution leads to an error.

Example 3. Declaring global variable login-endpoint
variables.login-endpoint=https://my-auth-server.com/api/login
Example 4. Using global variable login-endpoint
Given request body:
{
    "username":"user",
    "password":"pass"
}
When I set request headers:
|name        |value           |
|Content-Type|application/json|
When I execute HTTP POST request for resource with URL `${login-endpoint}`
Then the response code is equal to '200'
It is possible to reuse repeatable VIVIDUS expressions placeholders via global variables storage mechanism. Please mind that expression will be executed lazily at the runtime and randomizing/generating expressions may produce different results per usage.
Example 5. Declaring global variable with expression random-user
variables.random-user=#{anyOf(superadmin,admin)}
Example 6. Using global variable random-user
Given request body:
{
    "username":"${random-user}",
    "password":"pass"
}
When I set request headers:
|name        |value           |
|Content-Type|application/json|
When I execute HTTP POST request for resource with URL `/authenticate`
Then the response code is equal to '200'

Resolution

Regular variables are resolved using the chain having the following order:

  • step-scoped variables,

  • scenario-scoped variables,

  • story-scoped variables,

  • next_batches-scoped variables,

  • batch-scoped variables,

  • global-scoped variables.

If variable is resolved, the resolution process is stopped, it means the narrower-scoped variables may override the wider-scoped variables in narrow scope lifetime. For example:

Example 7. Variables override mechanism
Scenario: First scenario
Given I initialize scenario variable `var` with value `scenario`
Given I initialize story variable `var` with value `story`
Then `${var}` is equal to `scenario`

Scenario: Second scenario
Then `${var}` is equal to `story`

var variable will be resolved to value scenario at the validation point in the first scenario, but it will be resolved to value story in the second scenario.

Default values

Reference to uninitialized variable can be resolved to default value using the operator : (colon).

Table 1. Examples of using default values
Reference to resolve Variable value Output

${var:default}

value

value

${var:default}

<uninitialized>

default

${var:}

<uninitialized>

<empty string>

${var:default:with:colons}

<uninitialized>

default:with:colons

${var[0]:default}

<uninitialized>

default

${var[0].key:default}

<uninitialized>

default

${var:#{generate(DungeonsAndDragons.alignments)}}

<uninitialized>

Chaotic Evil

${var:${var1}}

var - <uninitialized>, var1 - value

value

${var:${var1:}}

var - <uninitialized>, var1 - <uninitialized>

<empty string>
Example 8. Open either user specified page or default page
Scenario: Open page to be checked
Given I am on main application page
When the condition `#{eval(`${optionalPathToCheck:/defaultPath}` != `/forbiddenPath`)}` is true I do
|step                                                                |
|When I go to the relative URL '${optionalPathToCheck:/defaultPath}' |

Complex types variables

VIVIDUS provides the ability to work with not only primitive variables like numbers and strings but also supports complex types such as lists and maps.

Accessing values

  • Values from list variables can be accessed by index. For example, ${listVar[0]} returns the first value.

  • Values from map variables can be accessed by key. For instance, ${mapVar.key} returns the value associated with 'key'.

Working with tables

VIVIDUS provides the ability to store tables in variables. Tables should have a header and at least one row with values.

Table 2. Assuming we have the table below stored in the variable 'tableVar':
A B

A1

B1

A2

B2

To access specific cell values, specify the row and header key. Rows indexing starts from 0. * ${tableVar[0].A} returns the value from the first row of column A: A1. * ${tableVar[1].B} returns the value from the second row of column B: B2.