Cucumber Expression matching ambiguity with overlapping step definitions

In Cucumber 7.x and later, the engine does not prioritize one expression over another based on specificity or custom types. If a Gherkin step matches multiple Cucumber Expressions, the engine throws an AmbiguousStepDefinitionsException rather than making a non-deterministic choice.

The non-determinism often observed usually stems from the order in which the engine scans the glue code, but the execution itself is designed to fail if multiple matches are valid. There is no configuration setting or priority annotation to rank a generic type (like {string}) against a specific custom parameter type.

How to resolve step matching conflicts

To fix ambiguity errors, you must ensure that your step definitions are mutually exclusive. Use the following strategies:

• Tighten the generic expression: Replace a broad type with literal text where possible. For example, instead of using Given I have a {string} status, use Given I have an "active" status if only one status is relevant.
• Use custom parameter types with constraints: If you use a @ParameterType, ensure its underlying regex is restrictive enough not to overlap with {int} or {string}.
• Merge definitions: If two steps are logically similar, combine them into a single method using an optional parameter or handle the logic within the code.

Verification

To verify if your expressions are causing conflicts, create a test case with two overlapping definitions:

// Step Definition A (Generic)
@Given("the user is {string}")
public void stepA(String name) { ... }

// Step Definition B (Custom Type)
@Given("the user is {username}")
public void stepB(User user) { ... }

Running a step like Given the user is "jdoe" should result in an AmbiguousStepDefinitionsException listing both stepA and stepB.

Are you using a custom @ParameterType with a regex that overlaps with the standard built-in Cucumber Expressions?