Cucumber JVM Filtering scenarios by using tags, name or line options

Introduction

This article looks at filtering options to execute specific scenarios. These can be set on the runner class through the CucumberOptions annotation. The most common method is to use the tags option. One can also specify regular expression in the name option to match the description at the scenario and scenariooutline level. The last one works on a specified feature file by adding the line number(s) to the features option.

Complex filters can be specified individually, especially for the tag and name options. A combination of these filter methods can also be used.

Feature File

The sample feature file that will be used for running the test scenarios contains one scenario and one scenario outline. Each component of the feature file is tagged. This tagging is optional and may be left out as per requirements. The tagging is inherited from the containing component.

The scenario will have the “@Scen” and “@Feat” tags. Similarly the scenariooutline will have the “@Out” and “@Feat” tags. The first example table will have the “@ExTop”, “@Out” and “@Feat” tags. Similarly the second table will have the “@ExBot”, “@Out” and “@Feat” tags.

Multiple tags can also be applied at each level.

Filtering by Tags Option

This option will filter the scenarios based on the tags applicable at that level. The technique to determine the applicable tags is detailed in the section above. The tags option for CucumberOptions annotation need to be specified on the runner class.

To run all feature files with the “@Feat” tag one needs to mention the tag value in the tags option.

@CucumberOptions(tags = { "@Feat" })

Similarly to run all scenarios with tag “@Scen” across all available feature files just use “@Scen” in the tags option. When a scenario outline is run with a specific tag then all the rows of the examples table are run. To run rows from a specific example table one needs to mention the tag referring to it, “@ExTop” will run the rows of the first table.

Complex tag filters can be created by using logical operators like ‘or’, ‘and’, ‘not’. The top example table can also be specified by using “@Feat and @Out and @ExTop”, though it is a bit of an overkill. To run the scenario and the bottom example table one can use “@Scen or @ExBot”. The scenario outline can also be run by using the ‘not’ operator, like “not @Scen”. A combination of these three logical operators can be used for creating complex filters.

The tag filters can also be used on hook methods in the @After, @Before, @AfterStep, @BeforeStep annotations to determine when they are executed.

In versions before 2.0.0, the syntax for these logical operator was different. Though they still work they are assigned to be deprecated. The “@Tag1 and @Tag2” will be written as {“@Tag1” , “@Tag2”}. For “@Tag1 or @Tag2” will be written as {“@Tag1 , @Tag2”}. The negative operator “not @Tag” will be written as “~@Tag”.

Filtering by Name Option

This option will filter the scenarios by matching the description at the Scenario and Scenario Outline keyword level. The name option of the CucumberOptions annotation needs to be specified. This also allows regular expressions to be used for matching to the description.

The value to be used so that only the scenario with the description “Scenario” runs is shown below.

@CucumberOptions(name = { "Scenario" })

To run the scenariooutline with the description “Outline” use the “Outline” text for the name option.

The value to be used for running both the scenario and scenarioutline can be specified using regular expression as below.

@CucumberOptions(name = { "Scenario|Outline" })

One can also accomplish the same by using the value below. When more than one text is specified to be matched then the “OR” logical operator is used.

@CucumberOptions(name = { "Scenario","Outline" })

For matching a scenario or scenariooutline without any description, one needs to use an empty string value ie. “”.

Filtering by Line Number

This option will filter out the scenarios based on the line number for a single or multiple feature file. The line number is appended to the feature file name, delimited by a colon for the features option of the CucumberOptions annotation. Multiple line numbers can also be specified for a feature file by separating them with a colon.

@CucumberOptions(features = "src/test/resources/feature/scenarios.feature:5")

In case of a scenario the line number should refer to the line which contains the “Scenario” keyword, as above. This will run the scenario with the tag “@Scen”

There are two options available for a scenario outline. If the line number refers to the line containing the “Scenario Outline” keyword all rows of all Example tables are run. Or to run a specific row of a Example table the line number of that row needs to be mentioned.

To run multiple scenarios from a single feature file delimit the line numbers by a colon.

@CucumberOptions(features = "src/test/resources/feature/scenarios.feature:5:11")

To run scenarios from multiple feature files, one needs to pass the feature files with line numbers as an  array.

@CucumberOptions(features = {".../feature/scenarios1.feature:5", ".../feature/scenarios2.feature:10"})

If the line number does not match the criterion above, no scenarios will be run.

This is not the most robust solution as changes in the feature file line ordering will affect the running of the scenario.

Combination Filtering

Complex selections can be created by combining all or any two of the above filter options. The different options are joined with the ‘AND’ logical operator.

To run the first row of the second Examples table one can use the filter combination below.

@CucumberOptions(tags = { "@Out and @ExBot" }, name = {"Outline"}, features = {"src/test/resources/feature/scenarios.feature:25"})