Cucumber Tags

Advertisement

What Are Tags in BDD?

Tags are labels starting with @ — such as @smoke or @regression — that you put on features and scenarios to group, filter and control execution. Instead of running the whole suite, you run exactly the scenarios you need.

Analogy: like labeling files "Urgent", "Optional" or "Finance" and then opening only one label — or running only @smoke tests after a deployment.

What Tags Are Used For

  • Selective execution — smoke, sanity, regression.
  • Modules and features — @login, @checkout, @payments.
  • Environments and roles — @qa-only, @admin, @guest.
  • Work in progress and known issues — @wip, @bug-1234, excluded from CI runs.
  • Hook control — run setup only for scenarios that need it, such as @Before("@db").

"In our retail project, we used @smoke for deployment checks and @regression for full suite execution."

Tagging Levels and Inheritance

Tags can be placed on a Feature, a Rule, a Scenario, a Scenario Outline and individual Examples tables.

Tags are inherited: a feature's tags apply to every scenario inside it.

 
@login
Feature: Login Functionality

  @smoke
  Scenario: Valid login
    Given the user is on the login page
    When the user logs in with valid credentials
    Then the dashboard should be displayed

  @regression
  Scenario Outline: Invalid login shows an error
    When the user logs in with "<email>" and "<password>"
    Then the error "<message>" should be displayed

    @smoke
    Examples: Most common mistake
      | email             | password | message                   |
      | asha@example.com  | wrong    | Invalid email or password |

    Examples: Other invalid inputs
      | email | password | message           |
      |       | x        | Email is required |
 

Effective Tags

Scenario Effective Tags
Valid login @login @smoke
Invalid login — first Examples row @login @regression @smoke
Invalid login — second Examples row @login @regression

Feature-level tags drive module-wide runs, while scenario and Examples tags target specific cases.

Tag Expressions

Filters use boolean tag expressions:

Expression Runs
@smoke Scenarios tagged @smoke
@smoke or @sanity Either tag
@regression and @payments Both tags
not @wip Everything except @wip
@regression and not (@wip or @flaky) Regression scenarios, excluding unfinished or quarantined scenarios

Cucumber has no built-in "ignore" tag. @ignore only works if your filter includes not @ignore.

Running Scenarios by Tag

1. In the Runner

 
@CucumberOptions(
    features = "src/test/resources/features",
    glue     = "stepDefinitions",
    tags     = "@smoke and not @wip"
)
public class TestRunner extends AbstractTestNGCucumberTests {}
 

On the JUnit 5 platform, set:

 
@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "@smoke"
)
 

instead.

2. From the Command Line

Command-line filtering can be used to select the required scenarios:

 
mvn test -Dcucumber.filter.tags="@regression and not @wip"
 

You can also set a default in src/test/resources/cucumber.properties:

 
cucumber.filter.tags=@smoke
 

3. In Jenkins

A Jenkins pipeline can expose the tag as a parameter:

 
parameters {
    choice(
        name: 'TAGS',
        choices: ['@smoke', '@regression', '@sanity'],
        description: 'Which scenarios to run'
    )
}

stages {
    stage('BDD tests') {
        steps {
            sh "mvn test -Dcucumber.filter.tags='${params.TAGS} and not @wip'"
        }
    }
}
 

"In our banking project, we ran @smoke tests after every deployment and @regression nightly — execution time dropped and feedback came much faster."

More: The Complete Jenkins Tutorial.

Tagged Hooks

Hooks can be limited to scenarios with certain tags, so expensive setup only runs where it's needed.

 
public class Hooks {

    @Before(value = "@db", order = 1)
    public void seedDatabase() {
        // insert test data only for @db scenarios
    }

    @Before("@ui")
    public void openBrowser() {
        /* start WebDriver */
    }

    @After("@ui")
    public void closeBrowser(Scenario scenario) {
        // screenshot on failure, then quit the browser
    }
}
 

@Before hooks with a lower order run first.

More on hooks and step definitions: Step Definitions & Cucumber Expressions.

Tagging Conventions That Scale

  • Suite tags: @smoke, @sanity, @regression — every scenario gets exactly one.
  • Module tags at feature level: @login, @checkout.
  • Status tags: @wip, @flaky, @bug-1234 — excluded in CI and reviewed regularly so they don't pile up.
  • Use lowercase and hyphenated tags, document them in the README, and review them in pull requests.
  • Don't over-tag — five tags on every scenario is noise.

See how tags, features and step definitions fit together in the Cucumber BDD Visualizer.

Common Tag Mistakes

Using the Old Syntax

Cucumber 1–3 used:

 
--tags @smoke,@sanity
 

for OR and repeated --tags for AND.

Modern Cucumber uses tag expressions:

 
"@smoke or @sanity"
 

Forgetting Inheritance

A feature-level @wip excludes every scenario in the file when you filter with:

 
not @wip
 

Expecting @ignore to Work on Its Own

The @ignore tag doesn't automatically skip a scenario. The filter needs to explicitly exclude it:

 
not @ignore
 

Quoting Problems on the Command Line

Wrap the whole expression in quotes so the shell passes it as one value:

 
-Dcucumber.filter.tags="@smoke and not @wip"
 

Tags That Pile Up

@wip and @flaky scenarios that are never revisited can silently shrink your effective coverage. Review these tags regularly.

Hard-Coding Tags Only in the Runner

Let CI pass tags as a parameter so one runner can serve smoke, regression and sanity runs.

FAQs

What Are Tags in BDD?

Tags are labels starting with @ that group and filter features and scenarios so you can run specific sets, such as @smoke, instead of the whole suite.

What Are Tags Used For?

Tags are used for selective execution such as smoke, regression and sanity testing, module and environment runs, excluding work in progress, and controlling hooks.

How Do You Run Scenarios by Tag?

Set tags in the runner's @CucumberOptions, or pass -Dcucumber.filter.tags="…" on the command line or in a CI pipeline. Only matching scenarios run.

Can You Tag Features, Scenarios and Scenario Outlines?

Yes. You can also tag Rules and individual Examples tables. Feature tags are inherited by every scenario in the feature.

How Do You Combine Tags?

Use and, or, not and parentheses.

For example:

@regression and not (@wip or @flaky)

How Are Tags Used in CI/CD?

Tags control which suite each pipeline runs — for example, @smoke after every deployment and @regression nightly.

From Real Projects

I've worked with BDD and TDD approaches alongside a hybrid Selenium framework. The lesson that carries over to Cucumber: scenarios should describe business behavior in plain language, and the automation underneath — page classes and reusable business steps — should stay out of the feature file. Testing Testsigma — a platform where users write automated tests in plain English — meant thinking like its users, who are testers themselves. Agree on a small set of tags — smoke, regression, and module names — and use them consistently.

📖 Related tutorials

📚 Official documentation: Cucumber documentation · ISTQB Glossary of testing terms