Steps deprecation procedure

VIVIDUS supports the special step deprecation mechanism that allows to log deprecated steps with replacement using current step context and automatically replace them using replaceDeprecatedSteps command.

This mechanism cannot be applied if the new logic of deprecated step consists of several steps or the actual step has a table with different header/headers.

Deprecate code steps

For deprecation of Java code steps use annotation @Replacement with the following mandatory parameters:

versionToRemoveStep - The version which the deprecated step is planned to be removed in.
replacementFormatPattern - The Formatter pattern for the actual step.

Example 1. /src/main/java/com/mycompany/steps/MySteps.java

    @Deprecated(since = "0.5.0", forRemoval = true)
    @Replacement(versionToRemoveStep = "0.6.0", replacementFormatPattern = "Given the step with parameters `%2$s` and `%1$s`")
    @Given(value = "the step with parameters '$parameter1' and '$parameter2'", priority = 1)
    public void givenStep(String parameter1, String parameter2)
    {
        // ... step logic
    }

Example 2. Deprecated step in story

Given the step with parameters 'parameter1' and 'parameter2'

Example 3. Output log

org.vividus.replacement.DeprecatedCodeStepsReporter - The step: "Given the step with parameters 'parameter1' and 'parameter2'" is deprecated and will be removed in VIVIDUS 0.6.0. Use step: "Given the step with parameters `parameter2` and `parameter1`"

Deprecate composite steps

For deprecation of composite steps use the comment with the special pattern: !--\s+DEPRECATED:\s+(.),\s+(.)$ where the first group is version to remove, the second one is formatter pattern for the actual step.

Example 4. Deprecated composite step in composite.steps file

Composite: Given the step with parameters '$parameter1' and '$parameter2'
!-- DEPRECATED: 0.6.0, Given the step with parameter `%2$s` and `%1$s`
Given the step with parameters `<parameter2>` and `<parameter1>`

Example 5. Output log

org.vividus.log.LoggingStoryReporter - The step: "Given the step with parameters 'parameter1' and 'parameter2'" is deprecated and will be removed in VIVIDUS 0.6.0. Use step: "Given the step with parameters `parameter2` and `parameter1`"

If composite step cannot be deprecated using formatter pattern it still must have the comment with the certain pattern for user notification in step replacer: !--\s+DEPRECATED: The step .* is deprecated and will be removed in .*.

Example 6. Example:

Composite: When I send HTTP $httpMethod to the relative URL '$relativeURL'
!-- DEPRECATED: The step "When I send HTTP $httpMethod to the relative URL '$relativeURL'" is deprecated and will be removed in VIVIDUS 0.6.0
When I execute HTTP <httpMethod> request for resource with relative URL `<relativeURL>`

Find deprecated steps

In the log during/after tests execution

2023-06-12 11:18:31,719 [batch-1-thread-3] INFO  org.vividus.log.LoggingStoryReporter - The step: "When I find greater than `1` JSON elements by `$.store.book` and for each element do
|step                                                       |
|Then number of JSON elements by JSON path `$.author` is = 1|" is deprecated and will be removed in VIVIDUS 0.6.0. Use step: "When I find greater than `1` JSON elements from `${json-context}` by `$.store.book` and for each element do
|step                                                       |
|Then number of JSON elements by JSON path `$.author` is = 1|"

In the report generated after tests execution

deprecated code step

deprecated composite step

Using print steps command

The printSteps command prints all available steps and mark deprecated ones:

...
vividus-plugin-rest-api              Then server `$hostname` supports secure protocols that $rule `$protocols`
vividus-plugin-rest-api              Then size of decompressed response body is $comparisonRule `$sizeInBytes`
vividus-plugin-rest-api  DEPRECATED  Then the connection is secured using $securityProtocol protocol
vividus-plugin-rest-api  DEPRECATED  Then the number of the response headers with the name '$headerName' is $comparisonRule $value
vividus-plugin-rest-api  DEPRECATED  Then the response body $comparisonRule '$content'
COMPOSITE IN STEPS FILE  DEPRECATED  When I perform right click on an element by the xpath '$xpath'
COMPOSITE IN STEPS FILE  DEPRECATED  When I refresh the page
...

In the documentation

Deprecated steps and their replacements can be found in the documentation using search (example).

Remove deprecated steps from tests

Steps can only be removed from VIVIDUS in a release with breaking changes. Usually MAJOR version is incremented on breaking changes releases according to the Semantic Versioning. But if project in initial development phase (has 0.y.z version) incremented only MINOR version.

Also, breaking changes releases usually have the Removed section with changes in the release history.

In case of update to version with breaking changes it is necessary to check presence of all removed steps in test project and replace them manually if this cannot be done automatically.