Steps available out of the box

Description

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

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)}`

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 3. 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 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
$comparisonRule - The comparison rule
$expectedValue - The expected value of the variable
$stepsToExecute - The ExamplesTable with a single column containing the steps to execute

Example 4. 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
$comparisonRule - The comparison rule
$expectedValue - The expected value of the variable
$stepsToExecute - The ExamplesTable with a single column containing the steps to execute

Example 5. 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`

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 format

Example 6. Wait 30 seconds for debug

When I wait `PT30S` for debug

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 7. 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 8. 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|

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.

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 9. 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 10. Batch 2 - Use the temporary file as ExamplesTable

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

Compare variables

Compare the value from the first variable with the value from the second variable in accordance with the condition. Could compare Maps and Lists of maps using EQUAL_TO comparison rule. Other rules will fallback to strings comparison.

INFO: 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 variables contain valid numbers than they will be converted into BigInteger and compared as numbers.

Then `$variable1` is $comaprisonRule `$variable2`

$variable1 - The first variable.
$comparisonRule - The comparison rule.
$variable1 - The second variable.

Example 11. Compare Strings

Then `Duke` is != `Leto`

Example 12. Compare numbers

Then `10` is = `10.0`

Example 13. 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}`

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 14. 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 15. 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 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.

Steps are performed	Steps are not performed
1	0
true	false
t	f
on	off
yes	no
y	n

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

Example 16. 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 17. 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 18. 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 19. 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`                 |!