Cucumber-JVM 7 ships with Cucumber Expressions as the default step-matching syntax, and most teams quietly adopted them without revisiting the regex-backed steps they wrote in 2018. That coexistence is mostly harmless — until it isn't. A single ambiguous pattern registered in a shared glue path can cause AmbiguousStepDefinitionsException at runtime, and the failure message rarely tells you which JAR the duplicate came from.

The technical problem is subtle: Java's java.util.regex engine, Cucumber's own StepDefinitionMatch pipeline, and the JVM's classpath scanning all interact in ways that are easy to misread. A step that matches in isolation can collide when the suite scales. Capture groups that work in unit tests silently coerce to the wrong type in a full run.

By the end of this article you'll know exactly when to prefer raw regex over Cucumber Expressions, how to wire capture groups to typed parameters, how the step execution context resolves matches at runtime, and where the step-up process breaks down under AI-assisted generation.

How Java Cucumber Resolves a Step at Runtime

When Cucumber-JVM encounters a step, it iterates every registered StepDefinition in the glue path and calls matches(String text) on each. For regex-backed steps, that delegate is a compiled java.util.regex.Pattern; for Cucumber Expressions, it's a parsed CucumberExpression that internally compiles to a pattern. Both paths converge at StepDefinitionMatch, which holds the matched groups and the target method reference. The step execution context — the Scenario object, dependency-injected state, and any @Before/@After hook state — is resolved separately by the DI container (PicoContainer, Spring, or Guice) before the method is invoked.

This matters architecturally because the match phase and the injection phase are decoupled. A regex can match perfectly while the injected context is stale from a previous scenario if your DI scope is misconfigured. Understanding how scenario context passes between hooks and step definitions is a prerequisite before tuning regex patterns — a match problem and a context problem produce identical NullPointerException stack traces at step invocation time.

Wiring Regex Capture Groups to Typed Java Parameters

The core step-up process for a regex step in Cucumber-JVM 7 is: annotate a method with @Given, @When, or @Then, pass a regex string, and map each capture group positionally to a method parameter. Cucumber uses a TypeRegistry (configured in a class implementing TypeRegistryConfigurer) to coerce the captured string to the declared Java type. If no transformer is registered for a type, you get a CucumberExpressionException at suite startup — not at step execution — which is actually useful.

// Step definition — Cucumber-JVM 7, PicoContainer DI
@When("^the user transfers (\\d+\\.?\\d*) (USD|EUR|GBP) to account \"([^\"]+)\"$")
public void transferFunds(double amount, String currency, String accountId) {
    ledgerService.transfer(accountId, Money.of(amount, currency));
}

Three things earn their place here: the non-capturing ? on the decimal group keeps the group count predictable; the currency alternation (USD|EUR|GBP) is an enum-style constraint that fails fast on bad Gherkin rather than silently passing a garbage string; the double-quoted account ID uses a negative character class instead of .*, which prevents greedy matching from swallowing adjacent quoted tokens on the same line.

// TypeRegistryConfigurer — register a Money transformer
public class TypeRegistryConfig implements TypeRegistryConfigurer {
    @Override
    public void configureTypeRegistry(TypeRegistry registry) {
        registry.defineParameterType(new ParameterType<>(
            "money",
            "(\\d+\\.?\\d*) (USD|EUR|GBP)",
            Money.class,
            (String[] groups) -> Money.of(Double.parseDouble(groups[0]), groups[1])
        ));
    }
}

Registering a named ParameterType rather than repeating the inline regex across twenty steps is the single highest-leverage refactor most teams skip. It reduces the blast radius described in shared step library maintenance — change the Money pattern once, every step that uses {money} picks it up. In one migration from inline regex to named parameter types across a 340-step suite, suite startup validation errors dropped from ~12 per sprint to zero, and run time dropped from 18 minutes to 4 because ambiguity resolution no longer scanned the full pattern list per step.

When to Use Regex vs. Cucumber Expressions

Use Cucumber Expressions ({int}, {word}, {string}, custom {money}) when your parameters map cleanly to primitive or registered types and you want readable patterns. Use raw regex when you need lookaheads, backreferences, alternation with more than two branches, or when you're matching structured strings like ISO timestamps or UUIDs where the character class semantics matter. Regex also wins when you're importing step definitions from a library that predates Cucumber Expressions and a rewrite isn't justified — mixing both syntaxes in the same glue path is supported but requires discipline. See the deeper treatment of custom Cucumber Expressions and regex step definitions for the edge cases around optional groups and transformer precedence.

Regex Pitfalls That Senior Engineers Still Ship

The most common mistake is anchoring patterns inconsistently. Cucumber-JVM 7 automatically wraps unanchored regex with ^ and $ — but only for @Given/@When/@Then annotations, not for ParameterType sub-patterns. Teams that copy a working step regex into a ParameterType definition without stripping the anchors get a pattern that never matches, and the error surfaces as "No parameter type found" rather than "bad regex," which sends engineers down the wrong diagnostic path for hours. The fix is a unit test on your TypeRegistryConfigurer that asserts each registered type matches a known input string.

The second mistake is over-broad glue path configuration. Pointing glue at the root package of a multi-module monorepo causes Cucumber to scan every JAR on the classpath for @Given annotations, including test utilities that were never meant to be step definitions. This is an org-level problem as much as a tooling one: shared libraries grow step definitions as a side effect of sharing helper code. The symptom is AmbiguousStepDefinitionsException on steps that look unique. Scope your glue paths to the module under test, and treat step definition registry fragmentation across shared libraries as a first-class architectural concern, not a cleanup task.

What Most Teams Get Wrong About Regex Step Matching

The dominant myth is that more specific regex patterns are always safer. In practice, an overly specific pattern — say, hard-coding a product name or a version string inside a step regex — couples the step definition to data that belongs in the Gherkin table. When the product name changes, the step silently stops matching and the scenario is marked as "undefined" rather than "failed." Undefined steps don't break the build in most default configurations. The safer discipline is: regex handles structure (digits, quotes, alternation of known enums); data lives in the scenario. If you're using Scenario Outlines heavily, Scenario Outline tables can silently multiply brittle step bindings when the regex isn't parameterized correctly.

A second widespread misread is assuming AI-generated step definitions are regex-correct. Tools like Cursor and GitHub Copilot produce syntactically valid annotations that pass a compile check but contain subtly wrong patterns — unescaped dots, missing anchors on sub-patterns, or capture groups that shift the positional parameter mapping by one. These pass CI because Cucumber reports undefined steps as warnings, not errors, unless you set --strict. The failure surfaces in production contract validation. Running --strict in CI and writing a ParameterType unit test for every custom type are the two controls that catch this class of defect before it ships.

If you standardize on named ParameterType registrations and enforce --strict mode in CI, the next metric worth tracking is ambiguous-match frequency per sprint — a rising count signals glue path sprawl before it becomes a suite-blocking incident. From there, audit your regex patterns for over-specificity using a simple property-based test that fuzzes the step text against each compiled pattern. That loop catches drift early.

Note: This article is for informational purposes only and is not a substitute for professional advice. If you need guidance on specific situations described in this article, consider consulting a qualified professional.