Organising Scenarios With Tags

Learn how to organise your scenarios into smaller groups and run them

Alan Parkinson avatar
Written by Alan Parkinson
Updated over a week ago

As your repository of scenarios grow, they can become unwieldy or slow you down. You might fine you have so many to run that it takes a long time to get feedback from the scenarios you are actively working on. Or it becomes hard to track which scenario is an artefact from which user story your team worked on.

All of this can make managing scenarios difficult. However, with the use of tags we can break down our scenarios into smaller sub-groups that are easier to manage, run and trace.

This is very useful when it comes to executing scenarios. Tools like Cucumber can take tags as arguments to determine which scenarios to run and which to ignore.

Creating tags

Tags take the form of an @ sign followed by the name of the tag, for example:


When creating tags you have two options. Add them to a feature or to a scenario:

Feature: Demonstrating tags

  Scenario: Demonstrating scenario tags
    Given I have the tag @scenario above the scenario line
    When I run the @scenario tag
    Then only this scenario will be run

  Scenario: Demonstrating feature tags
    Given I have the tag @feature above the feature line
    When I run the @feature tag
    Then all scenarios in this feature will be run

As described in the feature file, if you add a tag above the Feature  keyword it means that the tag is applied to all the scenarios. However, if you add it above a Scenario keyword it means that the tag is applied to that specific scenario.

Strategies for organising tags

Tags are very simple to use and add to scenarios, but they can be a very powerful to organise scenarios if you choose the right way to organise. Here are a few ways in which you can use them:

Current state

The most common way in which tags are used is to determine the current state of a scenario. Tags such as @wip and @pending are used as a way to identify which scenarios are still to be worked on and which are being actively worked on.

@wip is also useful for when you are the person developing a scenario as it allows you to quickly execute specific scenarios and ignore the others until you are ready to run them all together.


Sometimes because of an application's testability or dependencies it's hard or not possible to automate specific scenarios. In this context marking scenarios as either @manual or @automated. This can help teams ensure that only @automated scenarios are executed and make it easy to detect scenarios that should be executed by the team.


Sometimes teams are organised in a way so that specific developers are responsible for specific parts of the tech stack resulting in 'back-end developers' and 'front-end developers'. This can sometimes cause confusions around who is responsible for working with automated acceptance tests to guide their development which results in teams creating multiple frameworks to work with different interfaces. This means duplicate suites of scenarios, which is a nightmare to maintain!

However, a single source of feature files can be connected to multiple packages of step definitions that interact with different interfaces such as UI or HTTP API. Therefore, we can then use tags such as @ui @api or @unit to indicate which interfaces a feature file interacts with. You can even tie a specific package of step definitions to a specific tag.


The previous examples demonstrate how to use tags to set rules around execution of scenarios. However, we can use tags to give us additional information on our scenarios that aren't necessarily used for execution. 

For example we can add tags such as @JIRAID-101 to make it clear which user story the team was working on when the scenario was created or updated. If you are working in a regulated industry we can also use tags to trace a scenario back to a specific legal rule or requirement, such as @1.2.0 

Behave Pro tags

Behave Pro has advanced tag features. As well as offering functionality to add your own custom tags, Behave Pro adds in useful tags for you to help with traceability and organisation of your tags. Behave Pro automatically adds in tags for:

  • Story id - The ID of the Jira user story is added for traceability

  • Story status - The status of the story, for example if it's open, is added to allow you track the status of a scenario

  • Manual/Automated - If the scenario is expected to be executed manually, then selecting manual in Behave Pro adds a manual tag

Executing tags

When you run Cucumber in your command line, you can provide an additional --tags  argument to the cucumber command to select which tagged scenarios and features you want to run and which you don't.


By default, adding a tag to the --tags argument sets Cucumber to run those scenarios with those tags only. For example this will run only scenarios that are tagged as @tag1

mvn test -Dcucumber.options="--tags @tag1"


cucumber --tags @tag1


cucumber-js --tags @tag1


We can also tell Cucumber to ignore scenarios with specific tags. For example this will run any scenarios that do not have the @tag1 tag.


mvn test -Dcucumber.options="--tags ~@tag1"


cucumber --tags ~@tag1


cucumber-js --tags ~@tag1


In certain contexts, we might want to only run scenarios that fall into two or more groups of tags. For example only run scenarios that are tagged @wip and @automated. We can do this by comma separating the tags we want to include. For example this will run scenarios that only have @tag1 and @tag2 :


mvn test -Dcucumber.options="--tags @tag1 --tags @tag2"


cucumber --tags @tag1 --tags @tag2


cucumber-js --tags @tag1 --tags @tag2


Finally, you have the option to combine groups of tags from different sets into one run. For example this will run scenarios that are tagged @tag1  or tagged @tag2 


mvn test -Dcucumber.options="--tags @tag1, @tag2"


cucumber --tags @tag1, @tag2


cucumber-js --tags @tag1, @tag2

Did this answer your question?