Exit course
Chapter 4 of 12 Intermediate 8 min read 2 quick checks Updated

Cucumber with Java and Selenium: First Scenario

On this page
  1. Project layout
  2. pom.xml
  3. The runner
  4. The feature file
  5. A driver factory
  6. Step definitions
  7. Run it locally
  8. Run it on TestingBot

Time to make a scenario run. This chapter builds the smallest useful Cucumber-JVM project: one feature file, one class of step definitions driving Selenium, and a runner that Maven picks up. It runs in your local Chrome first and then, by changing one system property, on the TestingBot grid.

Project layout#

cucumber-bdd/
  pom.xml
  src/test/java/com/example/
    RunCucumberTest.java          runner: tells JUnit where the features are
    DriverFactory.java            local Chrome or a TestingBot browser
    steps/SignInSteps.java        step definitions
  src/test/resources/features/
    sign_in.feature               the Gherkin

Feature files live under src/test/resources, so Maven puts them on the test classpath. The features directory there becomes the classpath package features, which is how the runner finds them.

pom.xml#

Cucumber-JVM 8 runs on the JUnit Platform (the engine behind JUnit 5 and 6). The older cucumber-junit (JUnit 4) and cucumber-testng runners are deprecated for removal in 8.0, so new projects should use cucumber-junit-platform-engine. The cucumber-bom keeps all Cucumber modules on the same version.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>cucumber-bdd</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-bom</artifactId>
        <version>8.0.4</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <dependency>
        <groupId>org.junit</groupId>
        <artifactId>junit-bom</artifactId>
        <version>6.1.3</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>io.cucumber</groupId>
      <artifactId>cucumber-java</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>io.cucumber</groupId>
      <artifactId>cucumber-junit-platform-engine</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.junit.platform</groupId>
      <artifactId>junit-platform-suite</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>tools.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>3.3.0</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.seleniumhq.selenium</groupId>
      <artifactId>selenium-java</artifactId>
      <version>4.52.0</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.6.1</version>
        <configuration>
          <properties>
            <configurationParameters>
              cucumber.junit-platform.naming-strategy=long
            </configurationParameters>
          </properties>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Three lines in there save you an afternoon:

  • jackson-databind. Since Cucumber-JVM 8.0, Jackson is an opt-in dependency. Without it, any report plugin that writes JSON-based output (including the HTML report used below) stops the run with "Cucumber needs a JSON library to write reports". Either Jackson 3 (tools.jackson.core, as here) or Jackson 2 works.
  • junit-jupiter-api is only there for its assertions (assertEquals, assertTrue). Any assertion library works; Cucumber treats any thrown exception as a failed step.
  • cucumber.junit-platform.naming-strategy=long makes Surefire report "Signing in to the secure area - Tom signs in with his own password" instead of a bare scenario name.

The runner#

Maven Surefire cannot discover .feature files on its own, so a small suite class tells the JUnit Platform to hand the features package to the Cucumber engine:

package com.example;

import static io.cucumber.junit.platform.engine.Constants.GLUE_PROPERTY_NAME;
import static io.cucumber.junit.platform.engine.Constants.PLUGIN_PROPERTY_NAME;

import org.junit.platform.suite.api.ConfigurationParameter;
import org.junit.platform.suite.api.IncludeEngines;
import org.junit.platform.suite.api.SelectPackages;
import org.junit.platform.suite.api.Suite;

@Suite
@IncludeEngines("cucumber")
@SelectPackages("features")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "com.example")
@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME,
        value = "pretty, html:target/cucumber.html, junit:target/cucumber.xml")
public class RunCucumberTest {
}
  • @SelectPackages("features") selects the feature files. Older examples use @SelectClasspathResource("features"); Cucumber 8 still runs that, but warns that a package selector should be used for a directory.
  • The glue is the package Cucumber scans for step definitions and hooks. Everything under com.example is found.
  • Plugins produce output: pretty prints the scenarios as they run, html writes a single-file report, junit writes XML that CI servers understand.

The feature file#

src/test/resources/features/sign_in.feature, the scenario from chapter 1:

Feature: Signing in to the secure area
  Members sign in with a username and password to reach the secure area.
  Wrong credentials are rejected with a message that says which part was wrong.

  Scenario: Tom signs in with his own password
    Given Tom has an account
    When Tom signs in with his password
    Then he is in the secure area

A driver factory#

Creating the browser goes in its own class, so the switch between local and cloud happens in one place. With no system property it starts local Chrome; -Dgrid=testingbot requests a browser from the TestingBot grid:

package com.example;

import java.net.MalformedURLException;
import java.net.URI;
import java.util.HashMap;
import java.util.Map;
import org.openqa.selenium.MutableCapabilities;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.edge.EdgeOptions;
import org.openqa.selenium.firefox.FirefoxOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.safari.SafariOptions;

public final class DriverFactory {

    private DriverFactory() {}

    public static boolean onTestingBot() {
        return "testingbot".equals(System.getProperty("grid"));
    }

    public static WebDriver create(String scenarioName) {
        if (!onTestingBot()) {
            ChromeOptions options = chromeWithoutPasswordManager();
            if (Boolean.getBoolean("headless")) {
                options.addArguments("--headless=new", "--window-size=1280,900");
            }
            return new ChromeDriver(options);
        }

        MutableCapabilities options = switch (System.getProperty("browser", "chrome")) {
            case "firefox" -> new FirefoxOptions();
            case "edge" -> new EdgeOptions();
            case "safari" -> new SafariOptions();
            default -> chromeWithoutPasswordManager();
        };
        options.setCapability("browserVersion", "latest");
        options.setCapability("platformName", System.getProperty("platform", "WIN11"));

        Map<String, Object> tbOptions = new HashMap<>();
        tbOptions.put("name", scenarioName);
        tbOptions.put("build", System.getProperty("build", "local"));
        options.setCapability("tb:options", tbOptions);

        String hub = "https://" + System.getenv("TB_KEY") + ":" + System.getenv("TB_SECRET")
                + "@hub.testingbot.com/wd/hub";
        try {
            return new RemoteWebDriver(URI.create(hub).toURL(), options);
        } catch (MalformedURLException e) {
            throw new IllegalStateException("Bad hub URL", e);
        }
    }

    /** The demo password is in breach lists; Chrome's "change your password" dialog would cover the page. */
    private static ChromeOptions chromeWithoutPasswordManager() {
        ChromeOptions options = new ChromeOptions();
        options.setExperimentalOption("prefs", Map.of(
                "credentials_enable_service", false,
                "profile.password_manager_enabled", false,
                "profile.password_manager_leak_detection", false));
        return options;
    }
}

tb:options carries TestingBot-specific settings: name labels the session in the dashboard (here, the scenario name) and build groups the sessions of one run. The capabilities generator gives the exact browser and platformName values, such as WIN11 or SEQUOIA. Selenium Manager, built into Selenium since 4.6, finds a matching chromedriver for the local branch, so there is nothing to download.

The prefs in chromeWithoutPasswordManager() are not a TestingBot setting. The demo site's well-known password appears in breach lists, so after signing in, Chrome on the grid opened its own "change your password" dialog. That dialog is part of the browser, not the page: it does not show up in the DOM, but it swallowed the next click. An early version of this course lost a sign-out scenario to it (chapter 10 tells the story). Turning off the password manager and its leak check keeps the browser out of the way.

Step definitions#

A step definition is a method with an annotation whose text matches a step. {string}-style placeholders come in chapter 4; for now the steps match literally:

package com.example.steps;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

import com.example.DriverFactory;
import io.cucumber.java.After;
import io.cucumber.java.Before;
import io.cucumber.java.Scenario;
import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import java.time.Duration;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;

public class SignInSteps {

    private static final String SIGN_IN_PAGE = "https://the-internet.herokuapp.com/login";

    private WebDriver driver;
    private String username;
    private String password;

    @Before
    public void openBrowser(Scenario scenario) {
        driver = DriverFactory.create(scenario.getName());
    }

    @After
    public void closeBrowser() {
        if (driver != null) {
            driver.quit();
        }
    }

    @Given("Tom has an account")
    public void tomHasAnAccount() {
        username = "tomsmith";
        password = "SuperSecretPassword!";
    }

    @When("Tom signs in with his password")
    public void tomSignsIn() {
        driver.get(SIGN_IN_PAGE);
        driver.findElement(By.id("username")).sendKeys(username);
        driver.findElement(By.id("password")).sendKeys(password);
        driver.findElement(By.cssSelector("button[type=submit]")).click();
    }

    @Then("he is in the secure area")
    public void heIsInTheSecureArea() {
        new WebDriverWait(driver, Duration.ofSeconds(10))
                .until(ExpectedConditions.urlContains("/secure"));
        assertTrue(driver.findElement(By.id("flash")).getText()
                .contains("You logged into a secure area!"));
        assertEquals("Secure Area", driver.findElement(By.tagName("h2")).getText());
    }
}

Two things to notice. The username and password are in the code, not in the scenario: the scenario only needs to know that Tom has an account. And @Before and @After are Cucumber hooks (from io.cucumber.java, not JUnit's annotations of the same name): they run around every scenario, so each scenario gets a fresh browser. Chapter 5 moves them out of this class.

You add a report plugin to a new Cucumber-JVM 8 project and the run stops with "Cucumber needs a JSON library to write reports". What fixes it?

Cucumber-JVM 8 made Jackson opt-in. Reports that serialise Cucumber's messages need it on the classpath. The JUnit 4 runner is deprecated and would not help.

Run it locally#

mvn test

Chrome opens, signs in and closes. The output shows each step with a tick:

Scenario: Tom signs in with his own password # classpath:features/sign_in.feature:5
  ✔ Given Tom has an account                 # com.example.steps.SignInSteps.tomHasAnAccount()
  ✔ When Tom signs in with his password      # com.example.steps.SignInSteps.tomSignsIn()
  ✔ Then he is in the secure area            # com.example.steps.SignInSteps.heIsInTheSecureArea()

target/cucumber.html is a report you can open in a browser. Add -Dheadless=true to run without a visible window.

Run it on TestingBot#

Export your key and secret (from the TestingBot member area) and switch the grid on:

export TB_KEY=your-key
export TB_SECRET=your-secret
mvn test -Dgrid=testingbot -Dbuild=cucumber-first-run

The same scenario now runs in Chrome on Windows 11 in the cloud. In the dashboard you will find a session named "Tom signs in with his own password" in the build cucumber-first-run, with a video and the list of WebDriver commands. When this chapter's project ran on the grid, that session was f5f0ab93dabc-7e25a1a68a9a-b1f2b96c05e7-179455629291-5585761.

One thing will look wrong: Maven says the scenario passed, but the dashboard does not show it as passed. The grid only sees WebDriver commands; it has no idea that your assertions succeeded. Chapter 5 adds a hook that reports the result, and the TestNG and Cucumber docs show the same idea with the REST API.

A scenario passes in Maven and its TestingBot session has a video, but the dashboard does not mark it as passed. Why?

From the grid's point of view the session just ran some commands and quit. Only your code knows whether the scenario passed, so it has to say so before the browser is closed.