Selective Test Execution in Cucumber: Harnessing Tags for Efficient Suites

Desired Outcome

Reduce test run time and keep your CI pipeline fast by executing only the scenarios that match a specific set of tags. This guide shows how to apply tags, configure the Cucumber runner, and verify that the correct tests run.

Prerequisites

• Java 11+ and Maven 3.6+ installed.
• Project already configured with cucumber-junit 7.x and cucumber-java.
• Feature files located under src/test/resources/features.
• Basic understanding of Cucumber Gherkin syntax.

Applying Tags in Feature Files

Tags are simple annotations prefixed with @ that you attach to a scenario or a whole feature. They are stored as metadata in the generated test reports and can be queried later.

@smoke
Feature: User login
  Scenario: Successful login
    Given the user is on the login page
    When the user enters valid credentials
    Then the user should see the dashboard

@wip @regression
Scenario: Password reset
  Given the user is on the login page
  When the user clicks "Forgot password"
  Then a reset email should be sent

Key points:

• Scenario‑level tags override feature‑level tags.
• Use short, descriptive names (e.g., @smoke, @regression, @wip).
• Avoid overly granular tags that proliferate without clear purpose.

Configuring the Cucumber Runner

There are two common ways to instruct Cucumber to include or exclude tags: via the Maven cucumber.options system property or directly in the test runner class.

Maven Command‑Line

Run only smoke tests:

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

Exclude work‑in‑progress scenarios:

mvn test -Dcucumber.options="--tags 'not @wip'"

Combine inclusion and exclusion:

mvn test -Dcucumber.options="--tags @smoke --tags 'not @wip'"

JUnit 5 Test Runner

With JUnit 5, you can embed the tag expression directly:

@Cucumber
@CucumberOptions(
  features = "src/test/resources/features",
  glue = {"com.example.stepdefs"},
  tags = "@smoke and not @wip"
)
public class SmokeTestRunner {
}

When using JUnit 5, the runner will automatically parse the tags attribute.

Validating the Tag Expression

After configuring, you must confirm that only the intended scenarios run:

• Console output – The Maven console shows each executed scenario name. Verify that excluded scenarios are absent.
• HTML report – Open target/cucumber-reports/cucumber.html and check the list of executed scenarios. Tags should appear next to each scenario.
• Test count – Use the test report summary to ensure the number of executed scenarios matches your expectation.

Example check: If you run --tags @smoke and only one scenario is tagged @smoke, the report should list exactly one scenario.

Common Pitfalls and How to Avoid Them

• Tag syntax errors – Cucumber 7.x requires quotes around complex expressions (e.g., not @wip). Forgetting quotes will cause a parse error.
• Tag name collisions – Using the same tag on multiple unrelated scenarios can lead to accidental test inclusion.
• Over‑granular tags – Creating tags for every minor change increases maintenance overhead and can clutter feature files.
• Ignoring setup/teardown – Relying solely on tags for isolation is insufficient. Ensure @Before / @After hooks reset shared state.

Recovery and Maintenance Strategies

If a tag expression fails or produces unexpected results:

1. Check the expression syntax – Ensure logical operators (and, or, not) are correctly spaced and quoted.
2. Run with verbose output – Add --plugin pretty to see step‑by‑step execution in the console.
3. Inspect the feature file – Verify that tags are correctly placed on the intended scenarios.
4. Re‑run without tags – Execute mvn test to confirm the entire suite passes, isolating the issue to the tag filtering.

For long‑running tests that become flaky, consider moving the tag to a higher level (feature) or creating a dedicated @slow tag to exclude them from quick runs.

Practical Example: Smoke Test Run

Assume you have three scenarios: two tagged @smoke and one @wip. Running:

mvn test -Dcucumber.options="--tags @smoke and not @wip"

Will execute only the two smoke scenarios. The console will list:

Running: CucumberTestRunner
[INFO] Running CucumberTestRunner
[INFO] Cucumber 7.0.0
[INFO] Features: 1
[INFO] Scenarios: 2
[INFO] Steps: 6
[INFO] Successful: 2
[INFO] Failed: 0
[INFO] Skipped: 0
[INFO] Passed: 2

Open the HTML report to verify that the @wip scenario is absent.

Summary

Tags in Cucumber provide a lightweight, declarative way to control which scenarios run. By applying tags thoughtfully, configuring the runner correctly, and validating results through console output and reports, you can keep your test suite fast and maintainable. Remember to pair tags with proper setup/teardown hooks and avoid an explosion of tag names that make feature files hard to read.