Using Cucumber with Gradle

1. Introduction

Cucumber is a test automation tool that supports Behavior-Driven Development (BDD). It runs specifications written in plain text Gherkin syntax that describes the system behavior.

In this tutorial, we'll see a few ways to integrate Cucumber with Gradle in order to run BDD specifications as part of the project build.

2. Setup

First, let's set up a Gradle project, using Gradle Wrapper.

Next, we'll add the cucumber-java dependency to build.gradle:

testImplementation 'io.cucumber:cucumber-java:6.10.4'

This adds the official Cucumber Java implementation to our project.

3. Running Using Custom Task

In order to run our specifications using Gradle, we'll create a task that uses the Command-Line Interface Runner (CLI) from Cucumber.

3.1. Configuration

Let's start by adding the required configuration to the project's build.gradle file:

configurations {
    cucumberRuntime {
        extendsFrom testImplementation
    }
}

Next, we'll create the custom cucumberCli task:

task cucumberCli() {
    dependsOn assemble, testClasses
    doLast {
        javaexec {
            main = "io.cucumber.core.cli.Main"
            classpath = configurations.cucumberRuntime + sourceSets.main.output + sourceSets.test.output
            args = [
              '--plugin', 'pretty',
              '--plugin', 'html:target/cucumber-report.html', 
              '--glue', 'com.baeldung.cucumber', 
              'src/test/resources']
        }
    }
}

This task is configured to run all the test scenarios found in .feature files under the src/test/resources directory.

The –glue option to the Main class specifies the location of the step definition files required for running the scenarios.

The –plugin option specifies the format and location of the test reports. We can combine several values to generate the report(s) in the required format(s), such as pretty and HTML, as in our example.

There are several other options available. For example, there are options to filter tests based on names and tags.

3.2. Scenario

Now, let's create a simple scenario for our application in the src/test/resources/features/account_credited.feature file:

Feature: Account is credited with amount
  Scenario: Credit amount
    Given account balance is 0.0
    When the account is credited with 10.0
    Then account should have a balance of 10.0

Next, we'll implement the corresponding step definitions — the glue— required for running the scenario:

public class StepDefinitions {
    @Given("account balance is {double}")
    public void givenAccountBalance(Double initialBalance) {
        account = new Account(initialBalance);
    }
    // other step definitions 
}

3.3. Run the Task

Finally, let's run our cucumberCli task from the command line:

>> ./gradlew cucumberCli
> Task :cucumberCli
Scenario: Credit amount                      # src/test/resources/features/account_credited.feature:3
  Given account balance is 0.0               # com.baeldung.cucumber.StepDefinitions.account_balance_is(java.lang.Double)
  When the account is credited with 10.0     # com.baeldung.cucumber.StepDefinitions.the_account_is_credited_with(java.lang.Double)
  Then account should have a balance of 10.0 # com.baeldung.cucumber.StepDefinitions.account_should_have_a_balance_of(java.lang.Double)
1 Scenarios (1 passed)
3 Steps (3 passed)
0m0.381s

As we can see, our specification has been integrated with Gradle, runs successfully, and the output is shown on the console. Also, the HTML test report is available in the specified location.

4. Running Using JUnit

Instead of creating the custom task in Gradle, we can use JUnit to run the cucumber scenarios.

Let's start by including the cucumber-junit dependency:

testImplementation 'io.cucumber:cucumber-junit:6.10.4'

As we're using JUnit 5, we also need to add the junit-vintage-engine dependency:

testImplementation 'org.junit.vintage:junit-vintage-engine:5.7.2'

Next, we'll create an empty runner class in the test sources location:

@RunWith(Cucumber.class)
@CucumberOptions(
  plugin = {"pretty", "html:target/cucumber-report.html"},
  features = {"src/test/resources"}
)
public class RunCucumberTest {
}

Here, we've used the JUnit Cucumber runner in the @RunWith annotation. Furthermore, all the CLI runner options, such as features and plugin, are available via the @CucumberOptions annotation.

Now, executing the standard Gradle test task will find and run all the feature tests, in addition to any other unit tests:

>> ./gradlew test
> Task :test
RunCucumberTest > Credit amount PASSED
BUILD SUCCESSFUL in 2s

5. Running Using Plugin

The last approach is to use a third-party plugin that provides the ability to run specifications from the Gradle build.

In our example, we'll use the gradle-cucumber-runner plugin for running Cucumber JVM. Under the hood, this forwards all calls to the CLI runner that we used earlier. Let's include it in our project:

plugins {
  id "se.thinkcode.cucumber-runner" version "0.0.8"
}

This adds a cucumber task to our build, and now we can run it with default settings:

>> ./gradlew cucumber

It's worth noting that this is not an official Cucumber plugin, and there are others also available that provide similar functionality.

6. Conclusion

In this article, we demonstrated several ways to configure and run BDD specifications using Gradle.

Initially, we looked at how to create a custom task utilizing the CLI runner. Then, we looked at using the Cucumber JUnit runner to execute the specifications using the existing Gradle task. Finally, we used a third-party plugin to run Cucumber without creating our own custom tasks.

As always, the full source can be found over on GitHub.