Tags and Filtering

Tags are labels attached to features, scenarios, or steps using the @ prefix. They are the primary way to group tests by purpose (smoke, regression, payment), by environment, or by status (work-in-progress, flaky). The behave runner can then include or exclude whole groups from a run with the --tags option.

Adding Tags

@payment @smoke
Scenario: Pay with a card
  Given a card with 50 USD
  When I pay 20 USD
  Then the card shows 30 USD

@slow
Scenario: Export the full statement
  Given an account with 100 USD
  When I export the statement
  Then the export finishes in 30 seconds

Filtering with Tags

# run only smoke tests
behave --tags=@smoke

# run payment AND smoke tests (boolean expressions)
behave --tags="@payment and @smoke"

# run payment or slow tests
behave --tags="@payment or @slow"

# run everything except work-in-progress
behave --tags="not @wip"

The expression supports and, or, not, and parentheses, so you can build precise selectors such as "(not @wip) and (@smoke or @payment)".

The Special @wip Tag

Behave gives @wip a special meaning: scenarios tagged with it are reported as skipped, but the overall run still ends with a failure. That makes WIP scenarios visible in CI without blocking the rest of the suite. Remove the tag when the scenario is ready.

Tagging Steps

Tags can also sit on individual steps. Tag filtering still applies at scenario granularity, so a tagged step is mainly useful as documentation, but the common practice is to tag features and scenarios.

Summary

Tags label features and scenarios; --tags evaluates boolean expressions over them to select or exclude tests. Use @wip to park unfinished scenarios while keeping CI honest.