Cucumber 7.x: Determining Step Matching Priority Between Cucumber Expressions and Regular Expressions

Answer

Cucumber 7.x does not assign a priority to Cucumber Expressions versus regular expressions. If a Gherkin step can be matched by both patterns, Cucumber treats the situation as ambiguous and throws an AmbiguousStepDefinitionException.

Confirmed facts

• The exception is raised irrespective of the order in which the step definitions are discovered or loaded.
• There is no configuration option, system property, or annotation attribute that can influence or override this matching behavior.
• The only reliable way to avoid the exception is to guarantee that no two step definitions overlap in the text they can match.

Steps to resolve ambiguity in a mixed‑annotation codebase

1. Identify overlapping pairs: search for step definitions where a Cucumber Expression (e.g., @Given("I have a {int}")) and a regular expression (e.g., @Given("^I have a (\\d+)$")) could match the same Gherkin line.
2. Choose one representation for each step and remove or refactor the other.
3. If you must keep both forms, make the patterns mutually exclusive—for example, tighten the regular expression to exclude the cases covered by the Cucumber Expression, or add a non‑capturing guard such as a word boundary that the expression does not satisfy.
4. Run the feature again; the AmbiguousStepDefinitionException should disappear and the step will bind to the remaining definition.

Verification (optional)

# Example step definitions
@Given("I have a {int}")
public void cucumberExpr(int n) { ... }

@Given("^I have a (\\d+)$")
public void regexExpr(int n) { ... }

Running a feature with the step I have a 5 yields AmbiguousStepDefinitionException. Changing the regex to ^I have a (\\d+) apples$ removes the overlap and the step executes without error.