Cucumber BDD Guide for Java Devs | Generated by AI

Home 2025.09

Here’s a practical, end-to-end introduction to Cucumber—what it is, why teams use it, and how to get productive with it in Java (plus quick notes for JS/Python users).

What Cucumber is (and isn’t)

Core pieces

1) Gherkin (plain-text specs)

2) Step Definitions (code)

3) Runner

4) Reports

Minimal example (Java, Maven)

pom.xml (key bits)

<dependencies>
  <!-- JUnit 5 -->
  <dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>5.10.2</version>
    <scope>test</scope>
  </dependency>

  <!-- Cucumber JVM + JUnit Platform -->
  <dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>7.18.1</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit-platform-engine</artifactId>
    <version>7.18.1</version>
    <scope>test</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.2.5</version>
      <configuration>
        <!-- run by tag, parallel, etc., if needed -->
      </configuration>
    </plugin>
  </plugins>
</build>

Project layout

src
 └─ test
     ├─ java
     │   └─ com/example/steps/...
     └─ resources
         └─ features/...

A feature file (src/test/resources/features/login.feature)

Feature: Login
  As a registered user
  I want to sign in
  So that I can access my account

  Background:
    Given the application is running

  @smoke
  Scenario: Successful login
    Given I am on the login page
    When I sign in with username "alice" and password "secret"
    Then I should see "Welcome, alice"

  Scenario Outline: Failed login
    Given I am on the login page
    When I sign in with username "<user>" and password "<pass>"
    Then I should see "Invalid credentials"
    Examples:
      | user  | pass     |
      | alice | wrong    |
      | bob   | invalid  |

Step definitions (Java, Cucumber Expressions)

package com.example.steps;

import io.cucumber.java.en.*;
import static org.junit.jupiter.api.Assertions.*;

public class LoginSteps {
  private String page;
  private String message;

  @Given("the application is running")
  public void app_running() {
    // bootstrap test app / start server / reset state
  }

  @Given("I am on the login page")
  public void i_am_on_the_login_page() {
    page = "login";
  }

  @When("I sign in with username {string} and password {string}")
  public void i_sign_in(String user, String pass) {
    // call UI or API; here fake it:
    if ("alice".equals(user) && "secret".equals(pass)) {
      message = "Welcome, alice";
    } else {
      message = "Invalid credentials";
    }
  }

  @Then("I should see {string}")
  public void i_should_see(String expected) {
    assertEquals(expected, message);
  }
}

JUnit 5 runner (discovery by engine)

// No explicit runner class needed with JUnit Platform.
// Create a test suite if you want tag filtering:
import org.junit.platform.suite.api.*;

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = "cucumber.glue", value = "com.example.steps")
@ConfigurationParameter(key = "cucumber.plugin", value = "pretty, html:target/cucumber.html, json:target/cucumber.json")
@ExcludeTags("wip") // example
public class RunCucumberTest {}

Run:

mvn -q -Dtest=RunCucumberTest test

Gherkin essentials you’ll use daily

Cucumber Expressions (friendlier than regex)

import io.cucumber.java.ParameterType;

public class ParameterTypes {
  @ParameterType("USD|CNY|EUR")
  public Currency currency(String code) { return Currency.getInstance(code); }
}

Then use: When I pay 100 {currency}.

Hooks & test lifecycle

Integrations you’ll likely want

CI/CD & scaling

Good practices (battle-tested)

Anti-patterns to avoid

Quick notes for other languages

JavaScript/TypeScript

Python

Ruby

When to choose Cucumber

Skip it (or use sparingly) if the team won’t maintain Gherkin, or if tests are purely technical where unit/integration tests already deliver clarity.

If you tell me your stack (Spring/Quarkus? REST/UI? how you deploy/CI?), I can sketch a ready-to-run Cucumber skeleton with Maven/Gradle, recommended plugins, and a sample pipeline that fits your setup.

Back Donate