The latest versions of the Cucumber artifacts for Java incorporates a JUnit 5 extension for Cucumber. This section contains a complete example of a feature defined in Gherkin and the JUnit 5 to execute it with Cucumber. As usual, the source code of this example is hosted on GitHub (https://github.com/bonigarcia/mastering-junit5).

The structure of the project containing this example is as follows:

First of all, we need to create our Gherkin file, which is aimed to test a simple calculator system. This calculator will be the SUT or our test. The content of our feature file is as follows:

Feature: Basic Arithmetic
  Background: A Calculator
    Given a calculator I just turned on
  Scenario: Addition
    When I add 4 and 5
    Then the result is 9
  Scenario: Substraction
    When I substract 7 to 2
    Then the result is 5
  Scenario Outline: Several additions
    When I add <a> and <b>
    Then the result is <c>
  Examples: Single digits
    | a | b | c  |
    | 1 | 2 | 3  |
    | 3 | 7 | 10 |

Then, we need to implement our steps definition. As described earlier, we use annotations and regular expression to map the text contained in the Gherkin file to the actual exercise of SUT depending on the step:

package io.github.bonigarcia;

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

import cucumber.api.java.en.Given;
import cucumber.api.java.en.Then;
import cucumber.api.java.en.When;

public class CalculatorSteps {

    private Calculator calc;

    @Given("^a calculator I just turned on$")
    public void setup() {
        calc = new Calculator();
    }

    @When("^I add (\d+) and (\d+)$")
    public void add(int arg1, int arg2) {
        calc.push(arg1);
        calc.push(arg2);
        calc.push("+");
    }

    @When("^I substract (\d+) to (\d+)$")
    public void substract(int arg1, int arg2) {
        calc.push(arg1);
        calc.push(arg2);
        calc.push("-");
    }

    @Then("^the result is (\d+)$")
    public void the_result_is(double expected) {
        assertEquals(expected, calc.value());
    }

}

Of course, we still need to implement our JUnit 5 test. To achieve the integration of Cucumber and JUnit 5, the Cucumber extension needs to be registered in our class by means of @ExtendWith(CucumberExtension.class). Internally, CucumberExtension implements the ParameterResolver callback of the Jupiter extension model. The objective is to inject the corresponding tests of the Cucumber feature as Jupiter DynamicTest objects in the tests. Notice in the example how a @TestFactory is used.

Optionally, we can annotate our test class with @CucumberOptions. This annotation allows to configure the Cucumber settings for our test. The allowed elements for this annotation are:

• plugin: Built-in formatter: pretty, progress, JSON, usage, among others. Default: {}.
• dryRun: Checks if all steps have definitions. Default: false.
• features: Paths of the features files. Default: {}.
• glue: Paths for step definitions. Default: {}.
• tags: Tags in the features to be executed. Default {}.
• monochrome: Displays console output in a readable way. Default: false.
• format: Reports formatter to be used. Default: {}.
• strict: Fails if there are undefined or pending steps. Default: false.

package io.github.bonigarcia;

import java.util.List;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import org.junit.jupiter.api.DynamicTest;
import org.junit.jupiter.api.TestFactory;
import org.junit.jupiter.api.extension.ExtendWith;
import cucumber.api.CucumberOptions;
import cucumber.api.junit.jupiter.CucumberExtension;

@CucumberOptions(plugin = { "pretty" })
@ExtendWith(CucumberExtension.class)
public class CucumberTest {

    @TestFactory
    public Stream<DynamicTest> runCukes(Stream<DynamicTest> scenarios) {
        List<DynamicTest> tests = scenarios.collect(Collectors.toList());
        return tests.stream();
    }

}

At this point, we are able to execute our Cucumber suite with JUnit 5. In the following example we see the output when running the test with Gradle: