Steps available out of the box

Here one could find description of the steps that are delivered with Vividus itself without any plugins required.

Variables initialization

Initialize variable

Initializes a variable with the specified value.

Given I initialize $scopes variable `$variableName` with value `$variableValue`

$scopes - The comma-separated set of the variables scopes.
$variableName - The variable name to refer to the variable value.
$variableValue - The variable value to store.

Example 1. Initializes variable with a simple value

Given I initialize scenario variable `message` with value `Hello World!`

Example 2. Initializes variable with an expression result

Given I initialize scenario variable `date` with value `#{generateDate(P1DT2h)}`

Initialize variable using template

Initializes a variable with a result of the processed Freemarker template

Set the template-processor.resolve-bdd-variables property to true value to be able to use global, next batches, scenario and story variables within templates. The variables can be referred using the variable reference notation. Note that the parameters passed to the step take precedence over the variables.

The vividus expressions can be used within templates by using ${execVividusExpression('expression name', args)} syntax. It’s also allowed to use nested expressions by using the following syntax ${execVividusExpression('expression name', arg1, execVividusExpression('expression name', args))}.

Given I initialize $scopes variable `$variableName` using template `$templatePath` with parameters:$templateParameters

$scopes - The comma-separated set of the variables scopes.
$variableName - The variable name to store a result.
$templatePath - The relative to src/main/resources path to a template.
$templateParameters - The template parameters.

Example 3. Personal info template at templates/person.ftl

{
  "id": ${execVividusExpression('randomInt', 1, 10)},
  "postalCode": ${execVividusExpression('generate', "Number.digits '6'")},
  "hash": "${execVividusExpression('encodeToBase64', execVividusExpression('randomInt', 100, 1000))}",
  "name": "${name[0]}",
  "race": "${race[0]}",
  "age": ${age}
}

Example 4. Generate JSON from the personal info template

Given I initialize scenario variable `age` with value `4510`
Given I initialize scenario variable `personalInfo` using template `templates/person.ftl` with parameters:
|name     |race  |
|Dagoth Ur|Dunmer|

Simple validations

Compare value against expected one

Compare the actual value against the expected value in accordance with the comparison rule. Could compare Maps and Lists of maps using EQUAL_TO comparison rule. Other rules will fallback to strings comparison.

The step prints the comparison results in the unified diff format for the strings with the legth more than specified in the property report.text-length-diff-threshold.

If the values are valid numbers than they will be converted into BigInteger and compared as numbers.

Then `$actualValue` is $comaprisonRule `$expectedValue`

$actualValue - The actual value.
$comparisonRule - The comparison rule.
$expectedValue - The expected value.

Example 5. Compare Strings

Then `Duke` is != `Leto`

Example 6. Compare numbers

Then `10` is = `10.0`

Example 7. Compare list of maps

When I execute SQL query `SELECT * FROM test.launch_rockets WHERE name='Proton'` against `preprod` and save result to scenario variable `preprod-date`
When I execute SQL query `SELECT * FROM test.launch_rockets WHERE name='Proton'` against `prod` and save result to scenario variable `prod-data`
Then `${preprod-data}` is = `${prod-data}`

Assert the value matches regex

Asserts that the given value matches the specified regular expression. The dotall mode is enabled by default: the expression . matches any character, including a line terminator.

Then `$value` matches `$regex`

$value - The value to assert.
$regex - The regular expression.

Sub-steps execution

Execute steps

Executes the steps located in the table.

When I execute steps:$stepsToExecute

$stepsToExecute - The ExamplesTable with a single column containing the steps to execute.

Example 8. Check and increment the value of a variable

Given I initialize story variable `var` with value `0`
When I execute steps:
|step                                                                     |
|Then `${var}` is = `0`                                                   |
|Given I initialize story variable `var` with value `#{eval(${var} + 1)}` |
Then `${var}` is = `1`

Execute steps N times

Step is designed to execute specified steps while counter with a certain limit matches a comparison rule. On each iteration the counter is increased on specified value, which is allowed to be either positive or negative. The seed value is used as a starting point for iteration. Current iteration index is available within steps to execute as ${iterationVariable}.

When I execute steps while counter is $comparisonRule `$limit` with increment `$increment` starting from `$seed`:$stepsToExecute

Alias:

When I execute steps while counter is $comparisonRule '$limit' with increment '$increment' starting from '$seed':$stepsToExecute

$comparisonRule - The comparison rule.
$limit - The counter limit.
$increment - The number to add to the counter on each iteration.
$seed - The initial counter value.
$stepsToExecute - The ExamplesTable with a single column step containing the steps to execute.

Example 9. Press the button four times

When I execute steps while counter is less than or equal to `10` with increment `3` starting from `1`:
|step                                                                         |
|When I click on element located by `caseSensitiveText(CLICK ME FOUR TIMES!)` |

Example 10. Press one button four times and press the second button from the nested step eight times

When I execute steps while counter is less than or equal to `10` with increment `3` starting from `1`:
{headerSeparator=!, valueSeparator=!}
!step                                                                                      !
!When I click on element located by `caseSensitiveText(CLICK ME FOUR TIMES)`               !
!When I execute steps while counter is less than '2' with increment '1' starting from '0': !
!|step                                                                                    |!
!|When I click on element located by `caseSensitiveText(CLICK ME EIGHT TIMES)`            |!

Execute while-like loop

Executes the steps while variable matches the comparison rule or until the maximum number of iterations is reached.

If the maximum number of iterations is reached no failure or exception will occur.

When I execute steps at most $max times while variable `$variableName` is $comparisonRule `$expectedValue`:$stepsToExecute

Alias:

When I execute steps at most $max times while variable '$variableName' is $comparisonRule '$expectedValue':$stepsToExecute

$max - The maximum number of iterations
$variableName - The name of the variable to check

Exactly variable name (e.g. myVaraible) is expected here, not variable reference: ~~${myVariable}~~
$comparisonRule - The comparison rule
$expectedValue - The expected value of the variable
$stepsToExecute - The ExamplesTable with a single column containing the steps to execute

Example 11. Click button 5 times

When I execute steps at most 5 times while variable `var` is less than `3`:
|step                                                                                                                   |
|When I click on element located by `id(counter)`                                                                       |
|When I find <= `1` elements by `xpath(//div[@id='clickResult' and (text()='3' or text()='4')])` and for each element do|
|{headerSeparator=!,valueSeparator=!}                                                                                   |
|!step!                                                                                                                 |
|!When I set the text found in search context to the 'scenario' variable 'var'!                                         |
Then `${var}` is = `3`

Execute while-like loop with delays

Executes the steps while variable matches the comparison rule or until the maximum number of iterations is reached. The delay is used to define the amount of time to wait between iterations.

If the maximum number of iterations is reached no failure or exception will occur.

When I execute steps with delay `$delay` at most $max times while variable variable `$variableName` is $comparisonRule `$expectedValue`:$stepsToExecute

Alias:

When I execute steps with delay '$delay' at most $max times while variable '$variableName' is $comparisonRule '$expectedValue':$stepsToExecute

$delay - The delay between iterations
$max - The maximum number of iterations
$variableName - The name of the variable to check

Exactly variable name (e.g. myVaraible) is expected here, not variable reference: ~~${myVariable}~~
$comparisonRule - The comparison rule
$expectedValue - The expected value of the variable
$stepsToExecute - The ExamplesTable with a single column containing the steps to execute

Example 12. Click button 5 times with 1 second delay

When I execute steps with delay `PT1S` at most 5 times while variable `var` is less than `3`:
|step                                                                                                                   |
|When I click on element located by `id(counter)`                                                                       |
|When I find <= `1` elements by `xpath(//div[@id='clickResult' and (text()='3' or text()='4')])` and for each element do|
|{headerSeparator=!,valueSeparator=!}                                                                                   |
|!step!                                                                                                                 |
|!When I set the text found in search context to the 'scenario' variable 'var'!                                         |
Then `${var}` is = `3`

Execute steps if a condition is "true"

Steps designed to execute specified steps if result of a condition is "true".

When the condition `$condition` is true I do$stepsToExecute

Alias:

When the condition '$condition' is true I do$stepsToExecute

$condition - The verifiable condition (Case-insensitive).

|==

|Steps are performed|Steps are not performed

|1|0

|true|false

|t|f

|on|off

|yes|no

|y|n

|== * $stepsToExecute - The ExamplesTable with a single column step containing the steps to execute if the result of the $condition is true.

The error will stop steps execution in case if unsupported condition value is provided.

Example 13. Click on the element if parent element is found

When I save number of elements located `By.xpath(//*[@class='outerElement'])` to SCENARIO variable `numberOfOuterElements`
When the condition `#{eval(${numberOfOuterElements} == 1)}` is true I do
|step                                                                   |
|When I click on element located by `xpath(//*[@class='innerElement'])` |

Example 14. Click on the element if parent element is found and the element itself is presented on the page

When I save number of elements located `By.xpath(//*[@class='outerElement'])` to SCENARIO variable `numberOfOuterElements`
When the condition `#{eval(${numberOfOuterElements} == 1)}` is true I do
{headerSeparator=!, valueSeparator=!}
!step                                                                                                                       !
!When I save number of elements located `By.xpath(//*[@class='innerElement'])` to SCENARIO variable `numberOfInnerElements` !
!When the condition '#{eval(${numberOfInnerElements} == 1)}' is true I do                                                   !
!|step                                                                                                                     |!
!|When I click on element located by `xpath(//*[@class='innerElement'])`                                                   |!

Execute steps if a variable is not set

Execute steps if the variable with specified name is not set into context.

When variable `$name` is not set I do:$stepsToExecute

Alias:

When variable '$name' is not set I do:$stepsToExecute

$name - The variable name to check.
$stepsToExecute - The ExamplesTable with a single column step containing the steps to execute if variable $name is not set.

Example 15. Initialize variable token if it is not already initialized

When variable `token` is not set I do:
|step                                                                                             |
|Given I initialize story variable `token` with value `eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSIiwiq46g`|

Example 16. Initialize variable token if it is not already initialized and additionally api-key in the nested step

When variable `token` is not set I do:
{headerSeparator=!, valueSeparator=!}
!step                                                                                                 !
!Given I initialize story variable `token` with value `eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSIiwiq46g`    !
!When variable 'api-key' is not set I do:                                                             !
!|step                                                                                               |!
!|Given I initialize story variable `api-key` with value `as38der4535fdERAnA443mIlb`                 |!

Files

Create a file

Saves the provided content to a file with the specified file path.

When I create file with content `$fileContent` at path `$filePath`

$fileContent - The content to be saved to the creating file.
$filePath - The fully qualified file name including parent folders and extension (e.g. temp/some_file.txt).

Create a temporary file

Creates a temporary file with the provided content and puts its path to a variable with the specified name. The created file will be removed upon test run completion.

When I create temporary file with name `$name` and content `$content` and put path to $scopes variable `$variableName`

$name - The logical name of the creating temporary file. For example, when $name is equal to my-file.txt, then my-file will be used as a prefix in the temporary file name and .txt - as a suffix.
$content - The content to be saved to the creating temporary file.
$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to store the full path of the created temporary file.

If you want to use the created temporary file in further batches of the test suite as an input data, you should use URL with file protocol

Example 17. Batch 1 - Create a temporary local file

When I create temporary file with name `.table` and content `
|column|
|value |
` and put path to NEXT_BATCHES variable `examples-table-temporary-file`

Example 18. Batch 2 - Use the temporary file as ExamplesTable

Then `<column>` is equal to `value`
Examples:
file:///${examples-table-temporary-file}

ZIP archives

Save ZIP archive entries

Saves the specified archive entries into variables.

When I save content of `$archiveData` archive entries to variables:$parameters

$archiveData - The archive data to parse.
$parameters - The ExamplesTable containing the following columns:
- path - The path to the archive entry.
- variable - The name of variable to save the data.
- scopes - The comma-separated set of the variables scopes.
- outputFormat - Defines output format of the entry, either TEXT or BASE64.

The following example requires vividus-plugin-rest-api in order to execute HTTP requests.

Example 19. Save archive entries

When I execute HTTP GET request for resource with URL `https://example.com/get-zip-archive`
When I save content of `${response-as-bytes}` archive entries to variables:
|path                     |variableName|scopes  |outputFormat|
|txtFileFromZipArchive.txt|text        |SCENARIO|TEXT        |
|txtFileFromZipArchive.txt|base64      |SCENARIO|BASE64      |
Then `${text}` is = `Response text from ZIP archive`
Then `${base64}` is = `UmVzcG9uc2UgdGV4dCBmcm9tIFpJUCBhcmNoaXZl`

Validate ZIP archive

Validates that at least one (or none) entry in the archive matches the specified string comparison rule. If comparison rule column does not exist, the validation that archive entries have the specified names is performed.

Then `$archiveData` archive contains entries with names:$parameters

$archiveData - The archive data to verify.
$parameters - The ExamplesTable containing the following columns:
- rule - The string comparison rule.
- name - Desired entry name pattern used with current rule.
  
  Entry name in archive is not always the same as file name. Entry name reflects the full relative path from archive root.

The following examples require vividus-plugin-rest-api in order to execute HTTP requests.

Example 20. Submit a GET request and check the response archive has file with extension 'data' in 'data' folder, but don’t contain any data file with name 'restrictedData'

When I execute HTTP GET request for resource with URL `https://example.com/get-zip-archive`
Then `${response-as-bytes}` archive contains entries with names:
|rule             |name                |
|matches          |data/.+\.data       |
|does not contain |restrictedData.data |

Example 21. Submit a GET request and check that response archive has file with name responseTextFromZipArchive.txt

When I execute HTTP GET request for resource with URL `https://example.com/get-zip-archive`
Then `${response-as-bytes}` archive contains entries with names:
|name                           |
|responseTextFromZipArchive.txt |

Debug

Wait for period

Waits during specified period for debug purposes

The step is for debugging purpose only

When I wait `$period` for debug

$period - total duration to wait in ISO-8601 Durations format.

Example 22. Wait 30 seconds for debug

When I wait `PT30S` for debug