Registry / testing / cucumber-tag-expressions

cucumber-tag-expressions

library11.0.1pypypi✓ verified 25d ago

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.

testing

pip install cucumber-tag-expressions

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · CUCUMBER-TAG-EXPRE

cucumber-tag-expressions

testingpythonv11.0.1

Install

1.6s avg

Import

14ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v11.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.010s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.012s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ from cucumber_tag_expressions import parse

The primary entry point for parsing tag expressions.

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

Debug

Known issues

breakingVersion 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).

affects: 8.0.0 and later

gotchaWhen 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`.

affects: All versions

gotchaThis 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`.

affects: All versions (for users migrating from old Cucumber CLI tag syntax)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cucumber_tag_expressions'

The `cucumber-tag-expressions` library has not been installed or is not accessible in the current Python environment.

fix

Install the library using pip: `pip install cucumber-tag-expressions`

cucumber_tag_expressions.parser.TagExpressionParserException: Tag expression "invalid (" could not be parsed because of syntax error: Unmatched (`

The provided tag expression string contains a syntax error, such as unmatched parentheses, illegal escape characters, or incorrect operator usage.

fix

Correct the syntax of the tag expression string. Ensure all parentheses are matched and operators (`and`, `or`, `not`) are used correctly. For example, `parse('(@wip or @bug) and not @slow')`.

behave --tags '@tag1 and @tag2' does not work

Older versions of `behave` (e.g., 1.2.6) do not natively support the advanced boolean tag expression syntax (like `and`, `or`) that `cucumber-tag-expressions` provides, even if the library is installed. They use a comma-separated syntax for OR and separate `--tags` options for AND.

fix

Update `behave` to a version that supports Tag-Expressions v2 (e.g., behave 1.2.7.dev0 or later), or use the older `behave` tag syntax. For `OR`, use `behave --tags @tag1,@tag2`. For `AND`, use `behave --tags @tag1 --tags @tag2`.

Upgrade

Version history

11.0.1latest on PyPI · released Aug 5, 2026

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/cucumber/tag-expressions ↗

packagehttps://pypi.org/project/cucumber-tag-expressions/ ↗

changeloghttps://github.com/cucumber/tag-expressions/releases ↗