---
title: 'Cucumber with Java and Selenium: First Scenario | TestingBot'
description: '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,…'
source_url:
  html: https://testingbot.com/resources/courses/cucumber-bdd/cucumber-java-selenium
  md: https://testingbot.com/resources/courses/cucumber-bdd/cucumber-java-selenium.md
---

Course

[BDD with Cucumber: Gherkin to CI](https://testingbot.com/resources/courses/cucumber-bdd)

Chapter 4 of 12

1. [1 Cucumber BDD Tutorial: From Gherkin to CI](https://testingbot.com/resources/courses/cucumber-bdd)
2. [2 BDD Testing Starts Before the Code: Three Amigos](https://testingbot.com/resources/courses/cucumber-bdd/bdd-collaboration)
3. [3 Writing Good Gherkin: Declarative Scenarios](https://testingbot.com/resources/courses/cucumber-bdd/writing-good-gherkin)
4. [4 Cucumber with Java and Selenium: First Scenario](https://testingbot.com/resources/courses/cucumber-bdd/cucumber-java-selenium)
5. [5 Step Definitions, Cucumber Expressions, Parameter Types](https://testingbot.com/resources/courses/cucumber-bdd/step-definitions)
6. [6 Hooks and Sharing State with PicoContainer](https://testingbot.com/resources/courses/cucumber-bdd/hooks-and-shared-state)
7. [7 Scenario Outlines, Tags and Background](https://testingbot.com/resources/courses/cucumber-bdd/outlines-tags-background)
8. [8 Cucumber-JS with Playwright](https://testingbot.com/resources/courses/cucumber-bdd/cucumber-js-playwright)
9. [9 Parallel Runs, Reports and CI on TestingBot](https://testingbot.com/resources/courses/cucumber-bdd/parallel-reports-ci)
10. [10 Other BDD Frameworks: Behave and Reqnroll](https://testingbot.com/resources/courses/cucumber-bdd/behave-and-reqnroll)
11. [11 BDD Anti-Patterns and How to Fix Them](https://testingbot.com/resources/courses/cucumber-bdd/bdd-anti-patterns)
12. [12 Knowledge check](https://testingbot.com/resources/courses/cucumber-bdd/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 4 of 12 Intermediate 8 min read 2 quick checks Updated Nov 2026 

# Cucumber with Java and Selenium: First Scenario
On this page
1. [Project layout](https://testingbot.com#project-layout)
2. [pom.xml](https://testingbot.com#pom-xml)
3. [The runner](https://testingbot.com#the-runner)
4. [The feature file](https://testingbot.com#the-feature-file)
5. [A driver factory](https://testingbot.com#a-driver-factory)
6. [Step definitions](https://testingbot.com#step-definitions)
7. [Run it locally](https://testingbot.com#run-it-locally)
8. [Run it on TestingBot](https://testingbot.com#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[#](https://testingbot.com#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[#](https://testingbot.com#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
<?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[#](https://testingbot.com#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:

```java
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[#](https://testingbot.com#the-feature-file)

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

```gherkin
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[#](https://testingbot.com#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:

```java
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](https://testingbot.com/support/web-automate/selenium/capabilities) 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[#](https://testingbot.com#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:

```java
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?

 Downgrading to `cucumber-junit` Adding `jackson-databind` (Jackson 3 or Jackson 2) as a test dependency Removing the `pretty` plugin

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[#](https://testingbot.com#run-it-locally)

```bash
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[#](https://testingbot.com#run-it-on-testingbot)

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

```bash
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](https://testingbot.com/support/web-automate/selenium/java/testng-cucumber) 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?

 The build name was missing from `tb:options` Cucumber reports results only for scenarios with tags The grid cannot see your assertions; the test has to report its result, for example with `tb:test-result=passed` The session ended before the video was uploaded

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.

[Previous · Chapter 3 Writing Good Gherkin: Declarative Scenarios](https://testingbot.com/resources/courses/cucumber-bdd/writing-good-gherkin) [Next · Chapter 5 Step Definitions, Cucumber Expressions, Parameter Types](https://testingbot.com/resources/courses/cucumber-bdd/step-definitions)

On this page

1. [Project layout](https://testingbot.com#project-layout)
2. [pom.xml](https://testingbot.com#pom-xml)
3. [The runner](https://testingbot.com#the-runner)
4. [The feature file](https://testingbot.com#the-feature-file)
5. [A driver factory](https://testingbot.com#a-driver-factory)
6. [Step definitions](https://testingbot.com#step-definitions)
7. [Run it locally](https://testingbot.com#run-it-locally)
8. [Run it on TestingBot](https://testingbot.com#run-it-on-testingbot)

Certification

Earn the free, resume-worthy TestingBot Cucumber BDD Certification for this course.

[How it works](https://testingbot.com/resources/courses/cucumber-bdd/certification)
