Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Setting Up a Cucumber Project (Maven and Gradle)

Set up a Cucumber-JVM project with Maven or Gradle and JUnit 5: dependencies, folder layout, the runner suite, configuration properties and a first command to run it.

A Cucumber project is a normal Java project with three additions: the Cucumber libraries, a folder of feature files and a runner that tells JUnit to hand control to Cucumber. This lesson gives you a complete, working layout for Maven and Gradle, explains every line, and ends with a runnable stand-in of the one piece of setup that causes the most confusion: how glue and feature locations are resolved.

Setup files such as pom.xml and build.gradle cannot run on this site, so they are shown read-only. Version numbers move quickly; check the Cucumber release notes and use a recent version rather than copying the numbers below blindly. The structure is what matters.

Prerequisites

  • A current JDK (17 or newer is fine for Cucumber-JVM; modern projects use 21 or 25).
  • Maven 3.9+ or Gradle 8+.
  • An IDE with Cucumber support is helpful (IntelliJ IDEA and VS Code both have plugins that highlight steps and jump from a sentence to its definition).

Folder layout

TEXT
shop-bdd/
  pom.xml  (or build.gradle)
  src/
    test/
      java/
        shop/
          RunCucumberTest.java   <- JUnit Platform suite
          CartSteps.java         <- step definitions
      resources/
        features/
          free_shipping.feature  <- scenarios
        junit-platform.properties  <- settings

Everything lives under src/test, because Cucumber scenarios are tests. Application code stays under src/main.

Maven setup

XML
<properties>
  <maven.compiler.release>21</maven.compiler.release>
  <cucumber.version>7.x.y</cucumber.version> <!-- use the latest release -->
  <junit.version>5.x.y</junit.version>
</properties>

<dependencies>
  <dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>${cucumber.version}</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit-platform-engine</artifactId>
    <version>${cucumber.version}</version>
    <scope>test</scope>
  </dependency>
  <dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-suite</artifactId>
    <version>1.x.y</version>
    <scope>test</scope>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.x.y</version>
    </plugin>
  </plugins>
</build>

The dependencies, in plain words:

Artifact What it gives you
cucumber-java The annotations @Given, @When, @Then, @Before, @After and the Java DSL
cucumber-junit-platform-engine A JUnit Platform test engine that discovers and runs .feature files
junit-platform-suite The @Suite and @SelectClasspathResource annotations used by the runner

A very common mistake is to add cucumber-junit (the old JUnit 4 integration) to a JUnit 5 project. Choose the platform engine for new work.

Run everything with mvn test. To run a subset by tag (tags get their own chapter later in the course), pass a property: mvn test -Dcucumber.filter.tags="@smoke".

Gradle setup (Kotlin DSL)

Kotlin
plugins {
    java
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("io.cucumber:cucumber-java:7.x.y")
    testImplementation("io.cucumber:cucumber-junit-platform-engine:7.x.y")
    testImplementation("org.junit.platform:junit-platform-suite:1.x.y")
}

tasks.test {
    useJUnitPlatform()
    systemProperty("cucumber.junit-platform.naming-strategy", "long")
}

useJUnitPlatform() is essential; without it Gradle does not start the JUnit Platform and silently finds zero tests. Run with gradle test.

The runner

Java
package shop;

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

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

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "shop")
@ConfigurationParameter(key = PLUGIN_PROPERTY_NAME, value = "pretty")
public class RunCucumberTest {
}
  • @SelectClasspathResource("features") selects the features folder from src/test/resources.
  • GLUE_PROPERTY_NAME names the package whose classes (and sub-packages) Cucumber scans for step definitions. It uses dots, like a Java package.
  • PLUGIN_PROPERTY_NAME picks the reporters; pretty prints colored scenario output to the console.

The same settings can live in src/test/resources/junit-platform.properties, which keeps the runner class empty:

PROPERTIES
cucumber.glue=shop
cucumber.plugin=pretty, html:target/cucumber-report.html
cucumber.publish.quiet=true
cucumber.execution.dry-run=false

Put settings that rarely change into junit-platform.properties, and override one-off values on the command line, for example -Dcucumber.filter.tags="not @slow". Command-line values win over the file.

How locations are resolved

Two path styles trip up beginners:

  • Feature locations are resource paths with slashes: features, com/example/features.
  • Glue is a package name with dots: shop, com.example.shop.

If the glue package is wrong, the run does not fail; every step is reported undefined, which looks like a missing implementation but is really a misconfiguration. If the feature path is wrong, Cucumber reports zero scenarios.

The stand-in below mimics the glue scan. It receives a list of "class names" with the sentences they define, scans only those whose name starts with the configured glue package, and then tries to match one scenario. Change GLUE to the wrong package and watch every step become undefined.

Java Stand-in: glue package scanning

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The billing.InvoiceSteps class is never loaded, because it is outside the glue package. That is exactly why a separate module's steps must be added to the glue (cucumber.glue=shop,billing) before they are usable.

Checking the setup

A good first check is a feature with one scenario and an intentionally undefined step. Run it; Cucumber should print the scenario, mark the step undefined and show a snippet to paste. If you see that, the features path, the glue and the engine are all wired up correctly. You will do exactly this in your first feature, end to end.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which artifact provides the @Given, @When and @Then annotations?

    cucumber-java contains the step and hook annotations; the others provide the runner and the build integration.
  2. 2. Every step is reported undefined although the definitions exist. What is the most likely cause?

    If the glue path is wrong Cucumber does not load your classes, so no step can be matched.
  3. 3. In Gradle, what happens if you forget useJUnitPlatform()?

    Gradle defaults to JUnit 4 style discovery, so the Cucumber engine is never started.
  4. 4. How is the glue setting written?

    Glue is a package name such as com.example.shop; feature locations use resource paths.

Summary

  • A Cucumber-JVM project needs cucumber-java, the JUnit Platform engine and the suite API, all as test dependencies.
  • Features live under src/test/resources; step classes under src/test/java.
  • A small @Suite runner (or junit-platform.properties) names the features path, the glue package and the plugins.
  • Wrong glue means undefined steps; wrong feature path means zero scenarios.
  • Prefer the JUnit Platform engine to the legacy JUnit 4 integration in new projects.

Next: Your First Feature, End to End