What Is a Step Definition?

A Step Definition is code that maps Gherkin steps in feature files to actual automation logic — bridging plain-English steps and executable code.

Gherkin steps (Given/When/Then) are human-readable but can't execute directly; step definitions are Java/Python/JS methods that implement the action for each step.

  • Each Gherkin step is annotated with @Given, @When, or @Then.
  • Step text can contain parameters for dynamic data.
  • Step definitions are stored in separate packages for reusability.

Analogy from your notes: Reading a recipe step ("Add sugar") and actually performing the action in the kitchen.

Advertisement

Real project: In a banking project, When user enters valid username and password was mapped to Selenium code in a common LoginSteps class.

Cucumber links steps to methods using annotations and matching the step text.

Feature File

Contains Gherkin steps in plain English.

Step Definition

Code annotated with @Given, @When, and @Then implementing the logic.

How Linking Works

Cucumber reads the feature file at runtime, matches each Gherkin step textually with the regex or exact string in the step-definition annotation, and executes the matching method.

If no match is found, Cucumber reports it as an undefined step.

Real project: Then user sees the dashboard was linked to a method in the DashboardSteps class.

Annotations Used in Step Definitions

Step definitions use Cucumber annotations:

  • @Given
  • @When
  • @Then
  • @And
  • @But

These annotations map Gherkin steps to code, helping Cucumber identify which method to execute for each step.

Given vs When vs Then

  • Given sets the precondition or initial state.
  • When describes the action or event performed by the user.
  • Then verifies the expected outcome or result.

Analogy from your notes:

  • Given — you are on the road.
  • When — you press the accelerator.
  • Then — the car moves forward.

Login example:

 
Given user is on login page
When user enters valid credentials
Then user is redirected to the dashboard
 

Using And / But

Yes — And and But can be used to make scenarios more readable.

They are contextual keywords that inherit the type (Given, When, or Then) from the previous step.

So, step definitions for And/But do not need separate annotations — you annotate the method with the inherited type.

Examples:

  • And user has entered username
  • But password field is empty

Analogy:

"You press the button and check the light, but it doesn't turn on" — showing continuation or exception.

Missing Step Definitions (Undefined)

If a step definition is missing, Cucumber marks the step as "undefined" and the scenario fails to execute.

It also provides a snippet template for the missing step to implement.

Missing steps often occur during new feature creation.

Developers/QA must implement them before the scenario can run.

Real project: Then user sees the account summary was missing, so Cucumber generated a snippet for implementation.

Multiple Matches (Ambiguous Step)

If multiple step definitions match the same Gherkin step, Cucumber throws an AmbiguousStepException and fails the scenario.

Causes

  • Duplicate step definitions in different packages.
  • Overlapping Regular Expressions.

Fixes

  • Avoid duplicate or overlapping regex.
  • Remove the duplicate step definition.
  • Use parameterized steps for dynamic data.

Real project: A login page step existed in both LoginSteps and HomeSteps — Cucumber threw an ambiguous-step error; the duplicate was identified and removed, making step definitions unique.

Handling Common Steps

Common steps across scenarios are handled using Background.

Define the steps common to all scenarios once in the Background block.

This avoids duplication, keeps scenarios clean, and improves maintainability.

Example:

Launching the browser and navigating to the login page before every scenario goes into Background.

(For conditional setup, hooks like @Before are the alternative — see the Feature Files pillar.)

Parameters in Step Definitions

Yes — parameters make steps dynamic and reusable, passing values from the feature file to the automation logic.

Placeholders in Gherkin steps (like "value", <value>, or regex captures) supply the data, which supports reusability and reduces duplicate step definitions.

Example:

Username and password passed as parameters to a single login step instead of writing a separate step per credential set.

Regular Expressions vs Cucumber Expressions

Regular Expressions

Regular Expressions define patterns for dynamic steps, capturing values from the step text.

 
@When("^user logs in with username \"([^\"]*)\" and password \"([^\"]*)\"$")
public void login(String username, String password) { ... }
 

Cucumber Expressions

Cucumber Expressions are a simpler, more readable alternative to Regular Expressions, introduced to replace complex regex.

 
@When("user logs in with username {string} and password {string}")
public void login(String username, String password) { ... }
 

Supported Placeholders

  • {string}
  • {int}
  • {float}
  • {word}

Difference Between Regular Expressions and Cucumber Expressions

Instead of writing complicated regex like:

 
^user logs in with username "([^"]*)" and password "([^"]*)"...$
 

You use readable placeholders such as:

 
{string}
{int}
 

This makes step definitions easier for new team members to understand without regex knowledge.

FAQs

What Is a Step Definition?

Code that maps a Gherkin step to automation logic — an annotated method (@Given, @When, @Then) implementing the action.

It matches each Gherkin step's text against the regex/string in the step-definition annotations at runtime and runs the matching method.

If no match is found, the step becomes an undefined step.

What Happens If a Step Definition Is Missing?

Cucumber marks the step as undefined, fails the scenario, and generates a snippet template to implement.

What Happens If Multiple Step Definitions Match?

An AmbiguousStepException fails the scenario.

Remove duplicates or refine the regex/parameters.

Can You Use Parameters in Step Definitions?

Yes — placeholders pass dynamic values from the feature file, making steps reusable across multiple data sets.

What's the Difference Between Regex and Cucumber Expressions?

Regex uses capture-group patterns like:

 
([^"]*)
 

Cucumber Expressions use readable placeholders like:

 
{string}
{int}
 

making them simpler and more approachable.