Cucumber Expressions for Python

Warnings

• breaking Support 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.
• gotcha Mixing 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.
• gotcha In 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.
• gotcha To 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.
• gotcha Alternative 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`).

Install

• pip install cucumber-expressions Install with pip

Imports

• Expression

  from cucumber_expressions.expression import Expression

• ParameterType

  from cucumber_expressions.parameter_type import ParameterType

• ParameterTypeRegistry

  from cucumber_expressions.parameter_type import ParameterTypeRegistry

Quickstart

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}")