Registry / testing / cucumber-expressions

cucumber-expressions

JSON →
library20.1.0pypypi✓ verified 25d ago

Cucumber Expressions is an alternative to Regular Expressions with a more intuitive syntax, designed for defining step definitions in a human-readable format. This Python library provides the parsing and matching capabilities for these expressions. The current version is 19.0.0, and it maintains an active development status with regular updates, including recent Python-specific changes.

pip install cucumber-expressions
INSTALL
IMPORT
SIG · CUCUMBER-EXPRESSIO
C
cucumber-expressions
testingpythonv20.1.0
Install
1.5s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v20.1.0 · 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.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

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

Expression
import cucumber_expressions
from cucumber_expressions import Expression

This quickstart demonstrates how to create basic Cucumber Expressions using built-in parameter types like `{int}` and how to define and register your own custom parameter types (`{color}` in this example) to extend the expression matching capabilities. It shows how to initialize `Expression` objects with a `ParameterTypeRegistry` and use the `match` method to extract values.

from cucumber_expressions.expression import Expression from cucumber_expressions.parameter_type import ParameterType, ParameterTypeRegistry # --- Basic Expression Matching --- # Create a registry (required even for built-in types) registry = ParameterTypeRegistry() # Define an expression with a built-in parameter type expression_int = Expression("I have {int} cucumbers in my belly", registry) match_int = expression_int.match("I have 42 cucumbers in my belly") print(f"Match for 'I have 42 cucumbers': {match_int.group_values if match_int else None}") match_float = expression_int.match("I have 3.14 cucumbers in my belly") print(f"Match for 'I have 3.14 cucumbers' (expects int): {match_float.group_values if match_float else None}") # --- Custom Parameter Type --- class Color: def __init__(self, name): self.name = name def __repr__(self): return f"Color('{self.name}')" # Define a custom parameter type and add to the registry color_parameter_type = ParameterType( name="color", regexp="red|blue|yellow", type=Color, transformer=lambda s: Color(s) ) registry.define_parameter_type(color_parameter_type) # Use the custom parameter type in an expression expression_color = Expression("I have a {color} ball", registry) match_color = expression_color.match("I have a red ball") print(f"Match for 'I have a red ball': {match_color.group_values if match_color else None}") match_color_fail = expression_color.match("I have a green ball") print(f"Match for 'I have a green ball': {match_color_fail.group_values if match_color_fail else None}")
Debug
Known issues
breakingSupport for Python 3.7, 3.8, and 3.9 has been removed in versions 17.0.0 and 18.0.0 respectively. Users on these older Python versions must upgrade their Python environment to 3.10 or newer to use `cucumber-expressions` version 19.0.0 and above.
fix
Upgrade Python to version 3.10 or higher.
affects: >=17.0.0
gotchaMixing Cucumber Expression syntax with Regular Expression syntax within a single expression string is not supported. Cucumber Expressions use their own intuitive syntax (e.g., `{int}`, `(s)`, `belly/stomach`) and interpret characters like `(`, `)`, `{`, `}` differently from regular expressions.
fix
Use either pure Cucumber Expression syntax or pure Regular Expression syntax (if supported by your test runner, like `behave`), but do not combine them in one expression string parsed by this library.
affects: All
gotchaIn Cucumber Expressions, parentheses `()` denote optional text, not capture groups as they do in regular expressions (e.g., `cucumber(s)` matches 'cucumber' or 'cucumbers', but 's' is not extracted as a separate value). Use explicit parameter types like `{word}` or `{string}` for value extraction.
fix
If you need to extract values, define them as a parameter type (e.g., `{word}` or `{string}`). If a part of the text is optional, simply enclose it in parentheses.
affects: All
gotchaTo match literal `(`, `{`, or `\` characters within a Cucumber Expression, they must be escaped with a backslash (`\`) (e.g., `\{text}` will match `{text}`). Depending on the Python string literal definition, you might need to use a double backslash (`\\`) in your code to ensure a single backslash is passed to the expression parser.
fix
Escape special characters `(`, `{`, `\` with a preceding backslash. Consider raw strings (`r'...'`) or double backslashes in Python string literals to simplify escaping.
affects: All
gotchaAlternative text using the `/` character (e.g., `belly/stomach`) only works when there is no whitespace between the alternative parts. `belly / stomach` would be treated as literal text, not alternatives.
fix
Ensure no whitespace exists immediately before or after the `/` character when defining alternative text within a Cucumber Expression (e.g., `I have {int} cucumber(s) in my belly/tummy`).
affects: All
Upgrade
Version history
20.1.0latest on PyPI · released Aug 5, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
22 hits · last 30 days
node
20
Resources
cucumber-expressions — pip install cucumber-expressions · libregistry