Automation Testing Cucumber Guide
PDF Downloads

What is Cucumber and BDD?

Behaviour-driven development, or BDD, is a way of working in which business people, developers and testers agree on examples of behaviour before building a feature, and write those examples in a shared, structured language. Cucumber is a tool that reads these examples, written in a language called Gherkin, and runs them against the application by calling automation code. The value is mostly in the conversation: the examples force the team to agree on what the feature should do. A side benefit is living documentation that stays accurate because it is executed. Cucumber is not a replacement for good test design, and for purely technical tests a plain framework is often simpler.

Gherkin keywords

A feature file

A readable specification in Gherkin. Business and technical people can both understand it.

@login
Feature: Login
  As a registered user
  I want to sign in
  So that I can see my dashboard

  Background:
    Given the user is on the login page

  @smoke
  Scenario: Successful login
    When the user enters email "test.user@example.com" and a valid password
    And clicks the login button
    Then the dashboard page is displayed

  Scenario Outline: Failed login messages
    When the user enters email "<email>" and password "<password>"
    And clicks the login button
    Then the error message "<message>" is displayed

    Examples:
      | email                  | password    | message               |
      | test.user@example.com  | wrong-pass  | Invalid credentials   |
      |                        |             | Email is required     |

Step definitions in Java

Each Gherkin step matches a method through an expression. Illustrative structure; the page object is assumed to exist.

import io.cucumber.java.en.*;
import org.junit.Assert;

public class LoginSteps {
    private final LoginPage loginPage = new LoginPage(Hooks.driver);

    @Given("the user is on the login page")
    public void userIsLoginPage() {
        loginPage.open();
    }

    @When("the user enters email {string} and password {string}")
    public void userEnterCredentials(String email, String password) {
        loginPage.enterEmail(email);
        loginPage.enterPassword(password);
    }

    @When("the user clicks the login button")
    public void clicksLogin() {
        loginPage.submit();
    }

    @Then("the error message {string} is displayed")
    public void errorIsDisplayed(String expected) {
        Assert.assertEquals(expected, loginPage.errorText());
    }
}

Project structure

Hooks and tags

• → @Before and @After hooks run around each scenario, ideal for starting and closing the browser or capturing a screenshot on failure.
• → Tags let you run subsets, such as smoke or regression, and attach hooks to specific scenarios.
• → Background removes repeated Given steps, but keep it short.

Writing good Gherkin

Good scenarios describe behaviour from the user's point of view, not implementation. A step such as the user clicks the button with id submit-bttn ties the example to the interface and breaks whenever the design changes. A step such as the user submits the login form expresses intent and leaves the detail to the step definition. Keep scenarios short, with one clear outcome, and use concrete examples rather than abstract statements. Avoid long lists of steps that read like a manual script; if a scenario needs fifteen steps, it is probably testing too much.

Good and weak step wording

When Cucumber helps and when it does not

• ✓ Helps when business stakeholders will actually read and contribute to the scenarios.
• ✓ Helps to build shared understanding through example workshops.
• ✗ Adds overhead when only testers read the files; plain code may then be simpler.
• ✗ Needs discipline to avoid duplicated or overly detailed steps.

Common mistakes

Cucumber versus plain test frameworks

Tips for step definition reuse

• → Write steps in business language so they can be reused across features.
• → Use parameters such as {string} and {int} rather than hard-coded values.
• → Keep step classes grouped by area, such as login or checkout.