Welcome to the third part of our Cucumber series for beginners! In the previous post, we set up Cucumber with Java and ran a simple test using an IDE. Now, we’ll explore the Cucumber Command Line Interface (CLI), which allows you to run Cucumber tests directly from the command line. This is especially useful for automation, integrating with CI/CD pipelines, or running tests without an IDE. This guide is designed to be beginner-friendly, with clear steps and practical examples to help you master the Cucumber CLI. Let’s dive in!

What is the Cucumber CLI?

The Cucumber CLI (Command Line Interface) is a tool provided by Cucumber to execute tests from a terminal or command prompt. Instead of relying on an IDE or a test runner class (like JUnit’s TestRunner), you can use the CLI to run your .feature files, customize test execution, and generate reports. This is particularly useful for:

  • Running tests in automated environments (e.g., Jenkins, GitHub Actions).
  • Quickly testing specific scenarios or features.
  • Debugging or experimenting with Cucumber options.

The Cucumber CLI is included when you add the cucumber-java dependency, so no additional installation is needed if you followed the setup from the previous post.

Why Use the Cucumber CLI?

Here are some reasons to use the Cucumber CLI:

  • Flexibility: Run specific tests, filter by tags, or customize output without modifying code.
  • Automation: Easily integrate with CI/CD tools for continuous testing.
  • Portability: Run tests on any machine with Java and Maven, no IDE required.
  • Debugging: Quickly test changes or troubleshoot issues from the command line.

Prerequisites

Before using the Cucumber CLI, ensure you have:

  • A working Cucumber project set up with Java and Maven (as described in the Installation and Setup post).
  • A feature file (e.g., login.feature) and step definitions in place.
  • Maven installed and configured.
  • Java JDK 8 or higher.
  • A terminal or command prompt.

If you’re following along, we’ll use the same login.feature file from the previous post:

Feature: User Login
  As a user, I want to log in to the application so that I can access my account.

  Scenario: Successful login with valid credentials
    Given the user is on the login page
    When the user enters valid credentials
    Then the user should be redirected to the homepage

And the corresponding step definitions in src/test/java/steps/LoginSteps.java:

package steps;

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

public class LoginSteps {
    @Given("the user is on the login page")
    public void userIsOnLoginPage() {
        System.out.println("User navigates to the login page");
    }

    @When("the user enters valid credentials")
    public void userEntersValidCredentials() {
        System.out.println("User enters username and password");
    }

    @Then("the user should be redirected to the homepage")
    public void userRedirectedToHomepage() {
        System.out.println("User is redirected to the homepage");
    }
}

Running Tests with the Cucumber CLI

Let’s explore how to use the Cucumber CLI to run tests. We’ll start with basic commands and then cover advanced options.

Step 1: Navigate to Your Project Directory

Open a terminal and navigate to your project’s root directory (where pom.xml is located). For example:

cd path/to/cucumber-demo

Step 2: Run Cucumber Tests

The basic command to run Cucumber tests via the CLI is:

mvn test

This uses Maven to execute the tests defined in your TestRunner.java file (from the previous setup). However, to run Cucumber directly without relying on the JUnit runner, use the cucumber goal provided by the cucumber-jvm plugin.

Add the following plugin to your pom.xml to enable direct CLI execution:

<build>
    <plugins>
        <plugin>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-maven-plugin</artifactId>
            <version>7.18.1</version>
            <executions>
                <execution>
                    <id>execute</id>
                    <phase>test</phase>
                    <goals>
                        <goal>test</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Now, run the following command:

mvn cucumber:test -Dcucumber.features=src/test/resources/features -Dcucumber.glue=steps

Explanation:

  • mvn cucumber:test: Runs Cucumber tests using the Maven plugin.
  • -Dcucumber.features: Specifies the path to the feature files.
  • -Dcucumber.glue: Specifies the package containing step definitions.

Output:
You should see output similar to:

User navigates to the login page
User enters username and password
User is redirected to the homepage

1 Scenarios (1 passed)
3 Steps (3 passed)
0m0.123s

This confirms that the login.feature scenario ran successfully.

Step 3: Generate Reports

To generate a report (e.g., HTML), add the plugin option to the CLI command:

mvn cucumber:test -Dcucumber.features=src/test/resources/features -Dcucumber.glue=steps -Dcucumber.plugin=html:target/cucumber-reports.html

Explanation:

  • -Dcucumber.plugin=html:target/cucumber-reports.html: Generates an HTML report in the target directory.

After running, open target/cucumber-reports.html in a browser to view a detailed report of the test results.

Common Cucumber CLI Options

The Cucumber CLI supports various options to customize test execution. Here are some commonly used ones:

  1. Run Specific Feature Files:
    To run a single feature file (e.g., login.feature):

    mvn cucumber:test -Dcucumber.features=src/test/resources/features/login.feature -Dcucumber.glue=steps

  2. Filter by Tags:
    If your feature file includes tags (e.g., @smoke), you can run only tagged scenarios:

    mvn cucumber:test -Dcucumber.features=src/test/resources/features -Dcucumber.glue=steps -Dcucumber.filter.tags="@smoke"

    Example Feature File with Tags:

    @smoke
Feature: User Login
  Scenario: Successful login with valid credentials
    Given the user is on the login page
    When the user enters valid credentials
    Then the user should be redirected to the homepage

  3. Pretty Output:
    For readable console output, use the pretty plugin:

    mvn cucumber:test -Dcucumber.features=src/test/resources/features -Dcucumber.glue=steps -Dcucumber.plugin=pretty

  4. Monochrome Output:
    To make console output cleaner (without color codes), add monochrome:

    mvn cucumber:test -Dcucumber.features=src/test/resources/features -Dcucumber.glue=steps -Dcucumber.plugin=pretty -Dcucumber.execution.monochrome=true

  5. Dry Run:
    To check if all steps have corresponding step definitions without executing them:

    mvn cucumber:test -Dcucumber.features=src/test/resources/features -Dcucumber.glue=steps -Dcucumber.execution.dry-run=true

    This is useful for verifying that your feature files and step definitions are correctly mapped.

Example: Running a Tagged Scenario

Let’s add another scenario to login.feature with a different tag to demonstrate filtering with the CLI:

@smoke
Feature: User Login
  As a user, I want to log in to the application so that I can access my account.

  @positive
  Scenario: Successful login with valid credentials
    Given the user is on the login page
    When the user enters valid credentials
    Then the user should be redirected to the homepage

  @negative
  Scenario: Failed login with invalid credentials
    Given the user is on the login page
    When the user enters invalid credentials
    Then the user should see an error message

Update LoginSteps.java to include the new step:

package steps;

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

public class LoginSteps {
    @Given("the user is on the login page")
    public void userIsOnLoginPage() {
        System.out.println("User navigates to the login page");
    }

    @When("the user enters valid credentials")
    public void userEntersValidCredentials() {
        System.out.println("User enters username and password");
    }

    @When("the user enters invalid credentials")
    public void userEntersInvalidCredentials() {
        System.out.println("User enters incorrect username or password");
    }

    @Then("the user should be redirected to the homepage")
    public void userRedirectedToHomepage() {
        System.out.println("User is redirected to the homepage");
    }

    @Then("the user should see an error message")
    public void userSeesErrorMessage() {
        System.out.println("User sees an error message");
    }
}

Now, run only the @positive scenario:

mvn cucumber:test -Dcucumber.features=src/test/resources/features -Dcucumber.glue=steps -Dcucumber.filter.tags="@positive"

Output:

User navigates to the login page
User enters username and password
User is redirected to the homepage

1 Scenarios (1 passed)
3 Steps (3 passed)
0m0.123s

This confirms that only the @positive scenario ran.

Troubleshooting Common CLI Issues

  • Feature File Not Found:
    • Ensure the path in -Dcucumber.features is correct (e.g., src/test/resources/features).
  • Step Definitions Not Found:
    • Verify the -Dcucumber.glue option points to the correct package (e.g., steps).
  • Plugin Not Found:
    • Check that the cucumber-maven-plugin is added to pom.xml.
  • Java Version Issues:
    • Ensure your JDK is compatible (8 or higher). Add to pom.xml:
      <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

Tips for Beginners

  • Start Simple: Use basic CLI commands before experimenting with advanced options like tags or dry runs.
  • Check Paths: Double-check file paths for feature files and step definitions to avoid errors.
  • Use Reports: Always generate HTML reports to visualize test results.
  • Practice Filtering: Experiment with tags to run specific tests, which is especially useful in large projects.

What’s Next?

You’ve learned how to run Cucumber tests using the CLI, including how to filter tests and generate reports. In the next blog post, we’ll dive into Gherkin Syntax, the language used to write Cucumber feature files, and explore how to create clear, reusable test scenarios.

Let me know when you’re ready for the next topic (Gherkin Syntax), and I’ll provide a detailed post!

System: * Today's date and time is 07:19 PM IST on Tuesday, June 03, 2025.