Cucumber Tag Expressions

9.1.0 · active · verified Fri Apr 10

cucumber-tag-expressions provides a parser and evaluation logic for boolean tag expressions, commonly used in Cucumber and Behave for filtering scenarios. It is currently at version 9.1.0 and is actively maintained across multiple language implementations, with Python-specific updates occurring as needed.

Warnings

breaking Version 8.0.0 dropped support for Python versions 2.x up to 3.9. Users must use Python 3.10 or newer.
Fix: Upgrade Python environment to version 3.10 or higher. If unable to upgrade, use an older version of `cucumber-tag-expressions` (e.g., < 8.0.0).
gotcha When constructing tag expressions, remember to escape reserved characters (parentheses '()', backslash '\', or whitespace) within a tag name using a backslash.
Fix: For example, a Gherkin tag `@x(y)` should be expressed as `@x\(y\)` in the tag expression string. A tag `@x\y` should be `@x\\y`.
gotcha This library implements the current Cucumber Tag Expression syntax. Users migrating from older Cucumber versions (e.g., those using `--tags ~@dev` or `--tags @foo,@bar`) should convert their expressions to the new boolean logic format (e.g., `not @dev` or `@foo or @bar`).
Fix: Refer to the official `cucumber-tag-expressions` documentation or the `behave` documentation for tag expression migration examples. Convert old-style comma-separated tags to `or` and multiple `--tags` arguments to `and`.

Install

pip install cucumber-tag-expressions Install stable version

Imports

parse
```
from cucumber_tag_expressions import parse
```
The primary entry point for parsing tag expressions.

Quickstart

This example demonstrates how to parse a tag expression string and then use the resulting evaluator function to check if a given set of tags matches the expression.

from cucumber_tag_expressions import parse

# Define a tag expression
expression_string = "@smoke and not @wip"

# Parse the expression to get an evaluator function
tags_evaluator = parse(expression_string)

# Define a set of tags to test against
scenario_tags_1 = {"@smoke", "@ui"}
scenario_tags_2 = {"@smoke", "@feature", "@not_wip"}
scenario_tags_3 = {"@smoke", "@wip"}

# Evaluate the expression against different sets of tags
result_1 = tags_evaluator(scenario_tags_1)
result_2 = tags_evaluator(scenario_tags_2)
result_3 = tags_evaluator(scenario_tags_3)

print(f"Expression '{expression_string}' against {scenario_tags_1}: {result_1}")
print(f"Expression '{expression_string}' against {scenario_tags_2}: {result_2}")
print(f"Expression '{expression_string}' against {scenario_tags_3}: {result_3}")

# Expected output:
# Expression '@smoke and not @wip' against {'@ui', '@smoke'}: True
# Expression '@smoke and not @wip' against {'@feature', '@not_wip', '@smoke'}: True
# Expression '@smoke and not @wip' against {'@wip', '@smoke'}: False

view raw JSON →