CLI

In scope of this article the task term is a piece of work that is done on stories, scenarios, steps and other entities and that produces some output based on the work done.

Example 1. The format of a task

./gradlew <task to perform>

Example 2. The format of a task with arguments

./gradlew <task to perform> --args='<arguments to pass into the task>'

The tasks are available only through the gradlew command.

Run stories

The task runs test stories based on current tests configuration and tests state on the file system:

macOS / Linux
Windows

./gradlew runStories

gradlew runStories

Treat known issues only as a positive result

Any known issues detected during stories run fail the overall execution with the corresponding exit code. The following command-line option can be used to not treat known issues as failures:

macOS / Linux
Windows

./gradlew runStories --treat-known-issues-only-as-passed

gradlew runStories --treat-known-issues-only-as-passed

The treating of known issues as a positive result can be enabled globally at the project level by adding the following line into the build.gradle file of the tests project:

runStories.treatKnownIssuesOnlyAsPassed = true

Make sure to put the configuration below the line configuring the project tasks, namely:

apply from: "${buildSystemPath}/vividus-test-project.gradle"
...

Write exit code to a file

The following command-line option can be used to write an exit code to a file:

macOS / Linux
Windows

./gradlew runStories -PfileToSaveExitCode='/user/dir/exitCode.txt'

gradlew runStories -PfileToSaveExitCode='/user/dir/exitCode.txt'

Also, it is possible to specify option to resolve a file path to write an exit code against the project build directory:

macOS / Linux
Windows

./gradlew runStories -PfileToSaveExitCode='/exitCode.txt' -PresolvePathAgainstProjectBuildDir=true

gradlew runStories -PfileToSaveExitCode='/exitCode.txt' -PresolvePathAgainstProjectBuildDir=true

Writing of the exit code can be enabled globally for the project by adding the following lines into the build.gradle file of the test project:

Example 3. Write the exit code to a file by an absolute path via the project property

runStories.fileToSaveExitCode ='/user/dir/exitCode.txt'

Example 4. Write an exit code to file with a path related to the project build directory via project property

runStories.fileToSaveExitCode = '/exitCode.txt'
runStories.resolvePathAgainstProjectBuildDir = true

Debug stories

The task runs test stories omitting VIVIDUS initialization check based on current tests configuration and tests state on the file system.

macOS / Linux
Windows

./gradlew debugStories

gradlew debugStories

Treat known issues only as a positive result

Any known issues detected during stories run fail the overall execution with the corresponding exit code. The following command-line option can be used to not treat known issues as failures:

macOS / Linux
Windows

./gradlew debugStories --treat-known-issues-only-as-passed

gradlew debugStories --treat-known-issues-only-as-passed

The treating of known issues as a positive result can be enabled globally at the project level by adding the following line into the build.gradle file of the tests project:

debugStories.treatKnownIssuesOnlyAsPassed = true

Make sure to put the configuration below the line configuring the project tasks, namely:

apply from: "${buildSystemPath}/vividus-test-project.gradle"
...

Write exit code to a file

The following command-line option can be used to write an exit code to a file:

macOS / Linux
Windows

./gradlew debugStories -PfileToSaveExitCode='/user/dir/exitCode.txt'

gradlew debugStories -PfileToSaveExitCode='/user/dir/exitCode.txt'

Also, it is possible to specify option to resolve a file path to write an exit code against the project build directory:

macOS / Linux
Windows

./gradlew debugStories -PfileToSaveExitCode='/exitCode.txt' -PresolvePathAgainstProjectBuildDir=true

gradlew debugStories -PfileToSaveExitCode='/exitCode.txt' -PresolvePathAgainstProjectBuildDir=true

Writing of the exit code can be enabled globally for the project by adding the following lines into the build.gradle file of the test project:

Example 5. Write the exit code to a file by an absolute path via the project property

debugStories.fileToSaveExitCode ='/user/dir/exitCode.txt'

Example 6. Write an exit code to file with a path related to the project build directory via project property

debugStories.fileToSaveExitCode = '/exitCode.txt'
debugStories.resolvePathAgainstProjectBuildDir = true

Print available steps

The task prints all the steps that are available for the configured profiles, environments and suites in the alphabetical order.

Table 1. Options
Description	Short notation	Full notation	Default value
Path to a file to save the list of the available steps	f	file	by default steps are printed into the console

macOS / Linux
Windows

./gradlew printSteps --args='-f my-steps.txt'

gradlew printSteps --args='-f my-steps.txt'

Example 7. Output

vividus                                             Then `$value` matches `$regex`
vividus-plugin-web-app                              When I switch back to page
vividus-plugin-web-app                              When I press $keys on keyboard
                            COMPOSITE IN STEPS FILE Then an element with the name '$elementName' exists
                            COMPOSITE IN STEPS FILE When I click on an image with the name '$imageName'

Count steps

The task counts steps in the specified tests folder and prints them in the descending order.

Table 2. Options
Description	Short notation	Full notation	Default value
Directory to count steps	d	dir	story
Number of steps to print	t	top	<no limits by default>

macOS / Linux
Windows

./gradlew countSteps --args='-t 5 -d story/uat'

gradlew countSteps --args='-t 5 -d story/uat'

Example 8. Output

Top of the most used steps:                                                                  occurrence(s)
Then `$variable1` is $comparisonRule `$variable2`                                                      330
Given I am on page with URL `$pageURL`                                                                 127
Then number of elements found by `$locator` is $comparisonRule `$quantity`                             110
Given I initialize $scopes variable `$variableName` with value `$variableValue`                         83
When I change context to element located `$locator`                                                     59

Count scenario

The task counts and prints stories, scenarios and scenarios containing examples found in the specified tests folder.

Table 3. Options
Description	Short notation	Full notation	Default value
Directory to count stories and scenarios	d	dir	story

macOS / Linux
Windows

./gradlew countScenarios --args='-d story/uat'

gradlew countScenarios --args='-d story/uat'

Example 9. Output

5  | Stories
13 | Scenarios
6  | Scenarios with Examples

Validate known issues configuration

The task validates known issues format and prints the validated known issues into the console.

macOS / Linux
Windows

./gradlew validateKnownIssues

gradlew validateKnownIssues

Example 10. Output

Known issues found:
VVD-5
VVD-6
VVD-7
VVD-8

Find known issues by assertion pattern

The task used to find known issues contained in the test project by one or more assertion patterns.

Table 4. Options
Description	Short notation	Full notation	Default value
Required path to a file that contains new-line-separated list of assertion patterns	f	file	<no default value>

If you miss the file argument into the task it will behave as described per Validate known issues configuration

Example 11. assertion-patterns.txt

.*Doctor Who.*

macOS / Linux
Windows

./gradlew validateKnownIssues --args='-f ./assertion-failures.txt'

gradlew validateKnownIssues --args='-f assertion-failures.txt'

Example 12. Output

Known Issue | Assertion Error
VVD-6       | .*Doctor Who.*

Replace deprecated steps

The task replaces deprecated steps with actual ones in all stories(*.story files) and composite steps (*.steps files) along the path <project-name>/src/main/resources. Please note that some deprecated steps (for example which should be replaced with two steps) cannot be replaced automatically and must be refactored manually.

macOS / Linux
Windows

./gradlew replaceDeprecatedSteps

gradlew replaceDeprecatedSteps

Example 13. Output (for cases when found steps which cannot be replaced automatically)

The step "When I check all checkboxes located by `xpath(.//input)`" from "CheckboxStepsTests.story - Scenario: Validation of step 'When I $checkboxState all checkboxes located by `$checkboxesLocator`'" is deprecated but cannot be replaced automatically, please replace it manually.
The step "When I check all checkboxes located by `xpath(.//input)`" from "composite.steps - Composite: When I run composite step with table:$table" is deprecated but cannot be replaced automatically, please replace it manually.

Replace deprecated properties

The task replaces deprecated properties with actual ones in all properties files along the path <project-name>/src/main/resources/properties.

macOS / Linux
Windows

./gradlew replaceDeprecatedProperties

gradlew replaceDeprecatedProperties

The examples below demonstrate property file with deprecated properties before and after applying the replaceDeprecatedProperties task.

Example 14. Property file with deprecated entries before running the task replaceDeprecatedProperties

ui.visual.applitools.server-uri=https://eyes.applitools.com/
ui.visual.applitools.app-name=name
web.driver.CHROME.experimental-options={"prefs": {"profile": {"cookie_controls_mode": 0}}}
batch-6.story-execution-timeout=PT15M

Example 15. Property file with replaced entries after running the task replaceDeprecatedProperties

applitools.server-uri=https://eyes.applitools.com/
applitools.app-name=name
web.driver.chrome.experimental-options={"prefs": {"profile": {"cookie_controls_mode": 0}}}
batch-6.story.execution-timeout=PT15M

Find and fix formatting issues

Spotless checks refer to formatting and linting validations to enforce consistent code quality standards. Spotless automates the formatting of files based on predefined rules and integrates with linting tools. It offers a number of generic formatters (indentation correction, normalize line endings, enforce consistent EOF files, enforce file encoding, etc.) that help keep test files clean, readable, and consistent, reducing noise in version control and making collaboration easier.

For files like .story, .steps, *.table, commonly used in VIVIDUS, the following Spotless rules are applied by default:

Table 5. Spotless rules
Rule	Description
Trimming Trailing Whitespace	Removes any spaces or tabs at the end of lines.
Ensuring Newline at End of File	Guarantees that each file ends with a single newline.
Consistent Indentation	Enforces 4 spaces for indentation.
Normalizing Line Endings	Converts all line endings to LF (\n) for consistency across platforms.

Spotless tasks

The task validates that all files comply with the specified formatting rules.

This task is executed automatically during the build process and does not require manual invocation.

macOS / Linux
Windows

./gradlew spotlessCheck

gradlew spotlessCheck

The task automatically formats files to conform to the defined rules.

macOS / Linux
Windows

./gradlew spotlessApply

gradlew spotlessApply

Fixing Spotless violations

If the build task is failed and the result like the following is shown in the console output, it means that some files do not comply with the Spotless rules.

> Task :spotlessVividusCheck FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':spotlessVividusCheck'.
> The following files had format violations:
      src/main/resources/story/web_app/Google Search.story
          @@ -13,8 +13,6 @@
           |·step··········································|
           |·When·I·click·on·element·located·by·`xpath(.)`·|
           When·I·enter·`VIVIDUS·test·automation`·in·field·located·by·`<search-input-field>`
          -When·I·wait·until·element·located·by·`<search-button>`·appears·
          -When·I·click·on·element·located·by·`<search-button>`\t
          +When·I·wait·until·element·located·by·`<search-button>`·appears
          +When·I·click·on·element·located·by·`<search-button>`
           Then·number·of·elements·found·by·`linkUrlPart(https://docs.vividus.dev/vividus/)->filter.textPart(What·is·VIVIDUS·::·VIVIDUS)`·is·equal·to·`1`
          -
          -
  Run './gradlew :spotlessApply' to fix these violations.

You can fix the violations manually or automatically by running the spotlessApply task. After fixing, review the changes and commit them to your repository. Following these steps will help keep your build stable and successful.