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:


There are 2 types of variables:

  • regaular - 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.


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


Regular variables can have one of the following scopes.

The scopes names are case-insensitive.
Name Description


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


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


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.


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


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

Example 1. Declaring global variable login-endpoint
Example 2. Using global variable login-endpoint
Given request body:
When I set request headers:
|name        |value           |
When I issue a HTTP POST request for a resource with the 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 3. Declaring global variable with expression random-user{anyOf(superadmin,admin)}
Example 4. Using global variable random-user
Given request body:
When I set request headers:
|name        |value           |
When I issue a HTTP POST request for a resource with the URL '/authenticate'
Then the response code is equal to '200'


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

  • step-scoped variables,

  • scenario-scoped variables,

  • story-scoped variables,

  • next_batches-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 5. Variables override mechanism
Scenario: First scenario
When I initialize the scenario variable `var` with value `scenario`
When I initialize the 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.