Step Definitions

A Step Definition is a with an expression that links it to one or more Gherkin steps. When Cucumber executes a Gherkin step in a scenario, it will look for a matching step definition to execute.

To illustrate how this works, look at the following Gherkin Scenario:

Scenario: Some cukes
  Given I have 48 cukes in my belly

The I have 48 cukes in my belly part of the step (the text following the Given keyword) will match the following step definition:


A step definition’s expression can either be a Regular Expression or a Cucumber Expression. If you prefer to use Regular Expressions, each capture group from the match will be passed as arguments to the step definition’s .

If the capture group expression is identical to one of the registered parameter types’s regexp, the captured string will be transformed before it is passed to the step definition’s . In the example above, the cukes argument will be an integer, because the built-in int parameter type’s regexp is \d+ .

State management

A step definition can transfer state to a subsequent step definition by storing state in instance variables.


Step definitions aren’t linked to a particular feature file or scenario. The file, class or package name of a step definition does not affect what Gherkin steps it will match. The only thing that matters is the step definition’s expression.


When Cucumber encounters a Gherkin step without a matching step definition, it will print a step definition snippet with a matching Cucumber Expression. You can use this as a starting point for new step definitions.

Consider this Gherkin step:

Given I have 3 red balls

If you don’t have a matching step definition, Cucumber will suggest the following snippet:

Suggested snippets will use your own parameter types if they match parts of your undefined step. If a color parameter type exists, Cucumber would use that in the suggested expression:

You can help us improve this documentation. Edit this page.