# Cucumber Expressions: a step-definition syntax that replaces regex with typed parameters

> Cucumber Expressions is the parameter-matching layer Cucumber uses instead of regular expressions in step definitions. It is a small library with implementations in Java, JavaScript, Python, Ruby, Go and .NET, and its value is narrow but real.

**cucumber/cucumber-expressions** — Human friendly alternative to Regular Expressions

- Repository: https://github.com/cucumber/cucumber-expressions
- Website: https://cucumber.io/docs/cucumber/cucumber-expressions/
- Stars: 200 · Forks: 67
- Language: Java
- License: MIT
- Published: 2026-08-27 · Updated: 2026-08-27 · Language: en
- Canonical page: https://hysenlabs.com/projects/cucumber-cucumber-expressions

## The problem: regex capture groups in step definitions

A Cucumber step definition has to match a Gherkin step and pull values out of it. The conventional way is a regular expression with capture groups, and the conventional result is a line like ^I have (\d+) (.*) in my (.*)$ followed by three positional arguments. Every one of those groups is untyped, so the step body receives strings and converts them by hand. When the step text changes, the regex has to change with it, and a misplaced backslash produces a mismatch that surfaces as an undefined step rather than a compile error.

Cucumber Expressions is the alternative syntax that the Cucumber project ships for this job. The README describes it as "an alternative to Regular Expressions with a more intuitive syntax". The intended audience is people writing step definitions in a BDD suite, not people writing parsers. If you are not using Cucumber or a compatible BDD runner, the library has no role in your stack.

## How the expression parser and parameter types fit together

An expression such as I have {int} cucumbers in my {string} is compiled into a regular expression by the library at definition time, and the resulting matcher is what runs against the step text. The braces are the whole idea: each {name} is a named parameter slot, and the name selects a parameter type rather than a raw capture group. The parameter type carries the regular expression fragment used to match, plus a transform function that converts the matched text into a value for the step method.

The repository layout reflects that design. The top level holds one directory per language implementation (java/, javascript/, python/, ruby/, go/, dotnet/) plus a testdata/ directory, which suggests the implementations are checked against shared fixtures rather than each defining its own behaviour. ARCHITECTURE.md sits at the root and the README defers to it with a single link, so the internal design is documented separately from the user-facing syntax. The parser design is credited in the README to the Tiny-Compiler-Parser tutorial by Yehonathan Sharvit, which is a useful signal about the size and shape of the code you would be reading if you needed to extend it.

## Getting the Java implementation and matching a first step

The README does not list install commands for any language. It points to cucumber.io/docs/cucumber/cucumber-expressions for syntax and usage, and the repository ships one directory per language, with java/ being the Java implementation. The RELATED SEARCHES include the phrase "cucumber-expressions maven", which is the artifact coordinate people look for. The README gives no dependency snippet, so check the java/ directory and the Maven Central entry for io.cucumber:cucumber-expressions before adding it to a build file.

Equally, the README gives no code sample for constructing an expression. What it does document, through the link to the documentation site, is that the expression syntax uses parameter slots in braces and that the site includes an interactive playground. The playground is the practical first stop: type an expression such as I have {int} cucumbers in my {string}, type a step text, and see which parts of the text the slots consume. That tells you whether your expression matches before you write any step code.

Once the expression matches in the playground, the API you are looking for in the Java implementation is the one that takes an expression string and a step text and returns the matched arguments. The documentation site is where the exact class and method names are given; the repository's java/ directory and its tests are the second source. Confirm in your own editor that a {int} slot yields an integer rather than the string "42", because that typed conversion is the concrete difference from a capture-group regex.

## Where Cucumber Expressions stops being the right tool

The syntax is deliberately smaller than regular expression syntax, and that is a constraint, not an oversight. Anything a regex can express that the expression grammar does not cover has to be handled by defining a custom parameter type, which means writing the regular expression anyway, just wrapped. Teams that reach for Cucumber Expressions expecting full regex power will spend their time on parameter types instead of step definitions.

There is also a versioning cost. The project has shipped v20.0.0 and v20.1.0 within roughly two months, and the major version bump implies breaking changes for anyone on v19. The CHANGELOG.md at the repository root is where those are recorded, and the README does not summarise them. A second limitation is that the library only matches step text. It does not validate a document, parse arbitrary input, or replace a schema validator. If your problem is not "bind this sentence to this function with typed arguments", the library is the wrong shape.

## Compared with plain regular expressions and with Gherkin itself

The nearest alternative is the regular expression you would otherwise write by hand. The difference is not expressiveness but where the work happens: a regex puts the type conversion inside the step body, while a Cucumber Expression puts it in the parameter type, so the conversion is declared once and reused across every step that names it. The cost is a second syntax to learn and a library to keep current.

A second comparison worth drawing is with Gherkin, which is a separate concern. Gherkin is the feature-file language that describes scenarios; Cucumber Expressions is what a step definition uses to match a line of that language. The two are often confused because they appear in the same repository of documentation. The README also credits Turnip, Behat and Behave as the inspiration for the syntax, which is a reminder that this style of expression predates the library and exists in other BDD tools under other names.

## Maintenance, releases and what the MIT licence covers

The repository is not archived, and the last push was on 2026-08-05, the same date as the v20.1.0 release. That is recent activity, but it is one data point; the release history shows v19.0.1, v20.0.0 and v20.1.0 spaced across roughly three months, so the project does move. Upgrade cost is concentrated in major versions, and the CHANGELOG.md is the file to read before bumping a dependency. Because the library compiles expressions into matchers at definition time, a behaviour change in the parser can alter which steps match, so a version bump is worth exercising against your existing feature files rather than assuming compatibility.

The licence is MIT, which is permissive and places few obligations on how you redistribute the library. That is a factual statement about the licence identifier in the repository, not legal advice; if your organisation has a policy on dependency licences, the LICENSE file at the repository root is the document to review.

## Conclusion

Adopt Cucumber Expressions if you write step definitions in any of the six supported languages and want parameters typed without writing capture groups. Do not adopt it as a general-purpose parsing or validation library; it exists to bind Gherkin steps to code, and the README points to the Cucumber documentation for everything beyond that. Before committing, verify that a published artifact exists for your language and version, read the parameter type documentation at cucumber.io/docs/cucumber/cucumber-expressions, and check the CHANGELOG for the v20.0.0 breaking changes if you are upgrading from v19.

## FAQ

### What is the difference between Cucumber Expressions and regular expressions?

Cucumber Expressions uses a more intuitive syntax than regular expressions, as the README puts it, and its {name} slots select parameter types instead of raw capture groups, so matched values can arrive typed. A regular expression gives you the full pattern language but leaves conversion to the step body.

### Which languages have a Cucumber Expressions implementation?

The repository contains a directory for each of Java, JavaScript, Python, Ruby, Go and .NET, and the README's build badges list test workflows for Go, Java, JavaScript, Python, Ruby and .NET. The primary language of the repository is Java.

### How do I add cucumber-expressions to a Java project?

The README does not give install commands; it points to cucumber.io/docs/cucumber/cucumber-expressions for usage, and the java/ directory holds the Java implementation. Check that directory and the published artifact for io.cucumber:cucumber-expressions before adding it to a build file.

### Is Cucumber Expressions the same thing as Gherkin?

No. Gherkin is the feature-file language used to describe scenarios, while Cucumber Expressions is the syntax a step definition uses to match a step line and extract typed arguments from it.

### What licence does cucumber/cucumber-expressions use?

The repository is MIT licensed, and the LICENSE file sits at the top level alongside README.md and CHANGELOG.md.

## Sources

- [Official documentation](https://cucumber.io/docs/cucumber/cucumber-expressions/)
- [Official README](https://github.com/cucumber/cucumber-expressions#readme)
- [Project repository](https://github.com/cucumber/cucumber-expressions)
- [Release notes](https://github.com/cucumber/cucumber-expressions/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cucumber-cucumber-expressions