Cucumber Expressions

Cucumber Expressions is a simpler, more readable alternative to regular expressions for matching the step text in Gherkin-style BDD scenarios (e.g. I have {int} cucumbers in my belly). This package is the official Python implementation, part of a polyglot repository that also ships Java, JavaScript, Ruby, Go, and .NET implementations kept behaviorally consistent via a shared cross-language test suite (testdata/).

It parses expression syntax into an AST, generates matching regular expressions with named parameter groups, and supports built-in parameter types ({int}, {float}, {word}, {string}) as well as custom parameter types registered by the test framework using it. It underlies step definition matching in Cucumber-family BDD tools.

What You Get

• An expression parser and AST for Cucumber Expression syntax with optional groups and alternation
• Built-in parameter types ({int}, {float}, {word}, {string}, {} anonymous) with automatic type coercion
• A ParameterTypeRegistry for registering custom parameter types with their own regex and transformer function
• An expression generator that suggests matching Cucumber Expressions for a given piece of step text
• Cross-language behavioral consistency validated against a shared testdata/ suite used by all six language implementations

Common Use Cases

• Writing readable Gherkin step definitions in Python (e.g. via behave or pytest-bdd style tooling) without hand-rolled regex
• Registering a custom parameter type to parse domain-specific step arguments, like currency amounts or dates
• Migrating existing regex-based step definitions to more maintainable Cucumber Expressions
• Building or extending a BDD test framework that needs a step-matching engine consistent with other Cucumber implementations

Under The Hood

Architecture The Python implementation (python/src/cucumber_expressions/) follows the same pipeline as the other five language ports: expression_tokenizer.py and expression_parser.py turn expression text into an AST (ast.py), expression.py compiles that AST into a TreeRegexp (tree_regexp.py) with named groups, and parameter_type_registry.py/parameter_type.py manage built-in and custom parameter types used during matching and argument extraction (argument.py). Tech Stack Pure Python 3.10+ with no runtime dependencies, built and packaged with uv_build; the wider repository is a Bazel-free polyglot monorepo with parallel Java, JavaScript, Ruby, Go, and .NET implementations validated against shared testdata/ fixtures in CI. Code Quality The Python port has a comprehensive test suite covering tokenization, parsing, argument extraction, expression generation, and custom parameter types (tests/test_*.py), and cross-language conformance testing against testdata/ keeps the Python behavior aligned with the canonical Java/JavaScript implementations rather than drifting independently. API Design The core entry points — constructing an Expression and calling .match(text) — require minimal setup, and registering a custom parameter type is a single ParameterTypeRegistry.define_parameter_type() call, keeping the learning curve low for anyone writing Gherkin step definitions.