Cucumber JUnit 5 Test Runner Migration

Cucumber is widely used for Behavior Driven Development (BDD) testing, allowing teams to write tests using natural language with Gherkin feature files. Here we will learn Cucumber JUnit 5 Test Runner Migration.

Earlier versions of Cucumber commonly used JUnit 4 with the @RunWith annotation:

@RunWith(Cucumber.class)
@CucumberOptions(
    features = "src/test/resources/features",
    glue = "com.bdd"
)
public class TestRunner {
}

With Cucumber 7 and JUnit 5, the test execution approach has changed. JUnit 5 does not use @RunWith, and Cucumber now integrates with the JUnit Platform through the Cucumber JUnit Platform Engine.

In this article, we will migrate a Cucumber project to a JUnit 5 test runner using Java and Maven.

Why Migrate Cucumber Tests to JUnit 5?

JUnit 5 provides several improvements compared to JUnit 4:

• Modern testing architecture
• Better extension support
• Improved parallel execution capabilities
• Integration with JUnit Platform tools
• Better compatibility with modern frameworks

Cucumber’s JUnit Platform Engine allows Cucumber scenarios to run as part of the JUnit 5 test execution platform.

Cucumber JUnit 5 Project Structure

Example project structure:

Project
│
└── src
    └── test
        ├── java
        │   └── com
        │       └── bdd
        │           ├── stepDefinitions
        │           │       └── HooksSteps.java
        │           │
        │           └── testRunner
        │                   └── TestRunner.java
        │
        └── resources
            └── features
                    └── Hooks.feature

The important folders are:

• features → Contains Cucumber feature files
• stepDefinitions → Contains step definition classes
• testRunner → Contains the JUnit 5 Cucumber runner

Required Maven Dependencies

To run Cucumber with JUnit 5, we need:

• JUnit Jupiter
• JUnit Platform Suite
• Cucumber Java
• Cucumber JUnit Platform Engine

Example pom.xml dependencies:

<dependencies>
    <!-- JUnit 5 -->
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.11.4</version>
        <scope>test</scope>
    </dependency>
    <!-- Cucumber Java -->
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-java</artifactId>
        <version>7.18.0</version>
    </dependency>
    <!-- Cucumber JUnit Platform Engine -->
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-junit-platform-engine</artifactId>
        <version>7.18.0</version>
        <scope>test</scope>
    </dependency>
    <!-- JUnit Platform Suite -->
    <dependency>
        <groupId>org.junit.platform</groupId>
        <artifactId>junit-platform-suite</artifactId>
        <version>1.11.4</version>
        <scope>test</scope>
    </dependency>
</dependencies>

The most important dependency is:

<artifactId>cucumber-junit-platform-engine</artifactId>

This connects Cucumber with the JUnit 5 execution engine.

Creating the Cucumber JUnit 5 Test Runner

In JUnit 5, the runner class uses annotations from:

org.junit.platform.suite.api

Create:

src/test/java/com/bdd/testRunner/TestRunner.java

Add the following code:

package com.bdd.testRunner;
import org.junit.platform.suite.api.*;
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 = "com.bdd"
)
@ConfigurationParameter(
        key = PLUGIN_PROPERTY_NAME,
        value =
        "pretty, " +
        "html:target/cucumber.html, " +
        "json:target/cucumber.json, " +
        "junit:target/cucumber.xml, " +
        "rerun:target/rerun.txt"
)
public class TestRunner {
}

Understanding JUnit 5 Cucumber Runner Annotations

Let’s understand each annotation.

@Suite

@Suite

Marks the class as a JUnit Platform test suite.

It replaces the JUnit 4:

@RunWith(Cucumber.class)

approach.

@IncludeEngines(“cucumber”)

@IncludeEngines("cucumber")

Tells JUnit Platform to use the Cucumber engine for execution.

Without this annotation, JUnit will not know that this is a Cucumber test.

@SelectClasspathResource

@SelectClasspathResource("features")

Defines the location of feature files.

Since feature files are inside:

src/test/resources/features

they are available on the test classpath.

Glue Configuration

@ConfigurationParameter(
    key = GLUE_PROPERTY_NAME,
    value = "com.bdd"
)

Defines where Cucumber should search for step definitions and hooks.

Example:

com.bdd
 |
 ├── stepDefinitions
 │       HooksSteps.java

Cucumber scans this package and finds:

• Step definitions
• Hooks
• Supporting classes

Configuring Cucumber Reports

The plugin configuration:

@ConfigurationParameter(
key = PLUGIN_PROPERTY_NAME,
value =
"pretty, " +
"html:target/cucumber.html, " +
"json:target/cucumber.json, " +
"junit:target/cucumber.xml"
)

generates multiple reports.

Pretty Report

pretty

Displays readable console output.

HTML Report

html:target/cucumber.html

Generates an HTML report.

Location:

target/cucumber.html

JSON Report

json:target/cucumber.json

Creates JSON output for:

• CI reporting
• Jenkins plugins
• Custom dashboards

JUnit XML Report

junit:target/cucumber.xml

Useful for CI systems that consume JUnit-style reports.

Failed Scenario Rerun File

rerun:target/rerun.txt

Stores failed scenarios.

Example:

classpath:features/Hooks.feature:15

This can be used to execute only failed scenarios.

Adding Tags in Cucumber JUnit 5

In older Cucumber versions, tags were configured using:

@CucumberOptions(
    tags="@Regression"
)

With JUnit 5, use:

@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "@Regression"
)

Add import:

import static io.cucumber.junit.platform.engine.Constants.FILTER_TAGS_PROPERTY_NAME;

Example:

@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME,
    value = "@End2End"
)

Now only scenarios tagged with:

@End2End
Scenario: User login

will execute.

Running Cucumber JUnit 5 Tests

Execute using Maven:

mvn test

JUnit Platform detects:

TestRunner.java
        |
        ↓
Cucumber Engine
        |
        ↓
Feature Files
        |
        ↓
Step Definitions

Common Migration Issues

Issue 1: Feature Files Not Found

Error:

No features found

Solution:

Verify:

src/test/resources/features

and runner:

@SelectClasspathResource("features")

Issue 2: Step Definitions Not Found

Error:

Undefined step

Solution:

Check glue configuration:

value="com.bdd"

The package should contain your step definitions.

Issue 3: JUnit 4 Dependency Conflicts

If migrating from JUnit 4, remove:

cucumber-junit

because it uses the old JUnit 4 runner.

Use:

cucumber-junit-platform-engine

instead.

Interview Answer: How Do You Configure Cucumber with JUnit 5?

A good interview response:

“With Cucumber 7 and JUnit 5, we use the Cucumber JUnit Platform Engine instead of the JUnit 4 runner. We create a test suite using @Suite, configure the Cucumber engine using @IncludeEngines, specify feature locations using @SelectClasspathResource, and define glue packages and plugins using @ConfigurationParameter.”

Conclusion

Migrating Cucumber tests to JUnit 5 requires replacing the traditional JUnit 4 runner with the JUnit Platform Suite approach.

The key changes are:

• Add cucumber-junit-platform-engine
• Use @Suite
• Use @IncludeEngines("cucumber")
• Configure features using @SelectClasspathResource
• Configure glue and reports using @ConfigurationParameter

This approach provides a modern Cucumber framework compatible with JUnit 5 and current Java testing practices.

Related Articles

Cucumber Guide Page

JUnit5 Guide Page