Running Cucumber from Command Line

What Is Running from the Command Line?

Running from the command line means executing Cucumber tests using terminal commands instead of launching them from an IDE. In Java projects, command-line execution is usually performed through Maven or Gradle. This is the same style used by Jenkins, GitHub Actions, Azure DevOps, Bamboo, TeamCity, Docker containers, and scheduled automation jobs.

In simple terms, command-line execution lets Cucumber tests run without an IDE. This makes the framework scriptable, repeatable, portable, and suitable for CI/CD.

Why Run from the Command Line?

IDE execution is convenient for development, but command-line execution is preferred for automation. A CI server cannot depend on a tester right-clicking a runner class. It needs a repeatable command such as mvn test or gradle test. Command-line execution also makes it easy to pass tags, browser settings, environment names, headless mode, and other runtime properties.

In enterprise workflows, a developer commits code, Jenkins checks out the repository, Maven downloads dependencies, the test framework starts, Cucumber scenarios execute, and reports are published. This entire flow depends on command-line execution.

Execution Flow

Open Terminal
  -> Navigate to Project
  -> Execute Maven or Gradle Command
  -> Build Tool Starts
  -> JUnit or TestNG Starts
  -> Cucumber Executes
  -> Reports Are Generated

The current directory should be the project root, usually the folder containing pom.xml for Maven or build.gradle for Gradle. Running from the wrong folder is a simple but common mistake.

Prerequisites

Before running from the command line, Java must be installed, Maven or Gradle must be available, dependencies must be configured, feature files must exist, a runner class or JUnit Platform suite must be configured, and the build file must know how to execute tests. If Selenium is used, browser drivers or driver management must also be configured.

cd C:\Projects\CucumberFramework
mvn test

On Linux or macOS, the path style changes but the idea is the same. Navigate to the project root and execute the build command.

Running with Maven

The most common Maven command is:

mvn test

Maven validates the project, compiles source and test code, copies resources, starts the test framework, and executes Cucumber through JUnit or TestNG integration. Reports are generated based on the configured plugins.

In many teams, Maven is the standard because it works consistently across local machines and CI servers. Maven commands can be copied into Jenkins pipeline scripts, GitHub Actions workflows, or local terminal sessions.

Running with Gradle

Gradle projects commonly use:

gradle test

or with the wrapper:

./gradlew test

The Gradle wrapper is often preferred because it ensures the project uses the intended Gradle version. Like Maven, Gradle compiles the project, starts the test framework, executes Cucumber scenarios, and generates reports.

Running by Tags

Tag filtering is one of the most useful command-line features. Instead of editing feature files or runner classes, a pipeline can pass a tag expression externally.

mvn test -Dcucumber.filter.tags="@Smoke"

More complex expressions are also possible:

mvn test -Dcucumber.filter.tags="@Regression and not @API"

This makes command-line execution flexible. A pull request job can run smoke tests. A nightly job can run regression. A release job can run critical scenarios. The framework code does not need to change for each execution plan.

Passing Environment and Browser Properties

Command-line execution should avoid hardcoded environment values. Instead of writing a QA URL directly into test code, pass the environment as a property and let the framework load the correct configuration.

mvn test -Denvironment=qa -Dbrowser=chrome

The framework can read system properties and decide which URL, credentials, browser, grid, or timeout settings to use. This allows the same codebase to run locally, in QA, in staging, or in CI.

Headless execution can also be controlled externally:

mvn test -Dheadless=true

This is useful on CI servers where no visible browser is needed.

Running Specific Suites

Enterprise frameworks often have smoke, regression, API, and UI runners. Command-line execution can select these through Maven configuration, TestNG XML files, JUnit class filtering, Gradle tasks, or CI parameters. The exact approach depends on the framework design.

For TestNG projects, a Maven command may point to a specific suite XML. For JUnit projects, build tools may discover runner classes by naming convention. The important principle is that suite selection should be repeatable and documented.

Report Generation

Reports are generated during command-line execution if plugins are configured. A typical target folder may contain HTML, JSON, JUnit XML, and failed scenario files.

target
  report.html
  report.json
  report.xml
  failed.txt

CI servers can publish these outputs. HTML helps humans review results. JSON supports reporting tools. JUnit XML supports CI dashboards. Failed scenario files support rerun workflows.

CI/CD Execution

Command-line execution is the foundation of CI/CD. A Jenkins stage may run mvn test. A GitHub Actions workflow may run ./mvnw test. Azure DevOps may run Maven or Gradle tasks. In each case, the automation must run without IDE interaction.

Git Commit
  -> Jenkins
  -> mvn test
  -> Runner
  -> Cucumber
  -> Reports
  -> Publish Results

A good framework uses the same command locally and in CI. If local command-line execution differs from CI execution, debugging becomes harder. Keep commands, properties, and report paths consistent.

Common Mistakes

Common mistakes include running commands outside the project root, missing dependencies, wrong runner configuration, wrong feature path, wrong glue path, hardcoded environment URLs, ignored build failures, and inconsistent local versus CI commands. Always read the console output. Build failures may come from compilation errors, dependency issues, configuration problems, or actual test failures.

Best Practices

Run commands from the project root directory. Use mvn test or gradle test as the standard execution command. Use tag expressions for selective execution. Pass browser, environment, and headless settings as external properties. Keep runner classes free from environment-specific values. Generate reports automatically in every run. Make sure the same command works locally and in CI/CD.

Real-Time Enterprise Command Examples

A smoke suite might run with a simple tag expression and environment property:

mvn test -Dcucumber.filter.tags="@Smoke" -Denvironment=qa -Dbrowser=chrome

A nightly regression suite might exclude unstable work-in-progress scenarios:

mvn test -Dcucumber.filter.tags="@Regression and not @Wip" -Denvironment=staging

A CI server may run headless browser execution to reduce resource usage:

mvn test -Dcucumber.filter.tags="@Smoke" -Dbrowser=chrome -Dheadless=true

These commands show why external properties are useful. The same codebase can support many execution needs without editing feature files, step definitions, or runner classes.

Command-Line Execution and Framework Configuration

A good framework reads command-line properties through a configuration layer. Step definitions should not directly parse many system properties. Instead, a configuration reader can collect environment, browser, timeout, grid URL, and headless values once and expose them to the driver factory or service clients. This keeps test code clean.

For example, -Denvironment=qa can tell the framework to load qa.properties. -Dbrowser=chrome can tell the driver factory which browser to create. -Dheadless=true can add browser options. This design separates execution control from test behavior.

Using Maven Wrapper and Gradle Wrapper

Many projects use mvnw or gradlew instead of requiring every machine to install the exact build tool version globally. A Maven wrapper command may look like ./mvnw test on Linux/macOS or mvnw test on Windows. A Gradle wrapper command may look like ./gradlew test.

Wrappers improve consistency because local machines and CI agents use the project-approved build tool version. This reduces "works on my machine" problems caused by version differences.

Troubleshooting Command-Line Runs

If the command fails before tests start, check Java installation, Maven or Gradle setup, dependency resolution, and compilation errors. If Cucumber starts but finds no scenarios, check feature path and tag filters. If scenarios are found but steps are undefined, check glue configuration. If Selenium tests fail only in CI, check browser availability, headless settings, window size, waits, network access, and test data.

Command-line output should be read from the first error, not only the last line. A final build failure may be caused by an earlier compilation problem, dependency conflict, or configuration issue. Good engineers inspect the full execution context before changing test code.

Command Line vs CI/CD

CI/CD execution is essentially command-line execution controlled by automation servers. The same commands should work locally before they are placed in Jenkins or another pipeline. If the local command is unreliable, the CI job will also be unreliable. Stable command-line execution is the foundation for stable CI execution.

Teams should document standard commands for smoke, regression, API, UI, and local debugging runs. This helps new team members run the framework correctly and reduces dependency on tribal knowledge.

Interview-Ready Summary

Running from the command line executes Cucumber tests using build tools such as Maven or Gradle instead of an IDE. It supports tag filtering, external configuration, automatic report generation, and CI/CD integration. Maven projects commonly use mvn test, while Gradle projects use gradle test or the Gradle wrapper.

The golden rule is to make command-line execution scriptable, repeatable, and environment-independent. Browser and environment values should be passed externally, not hardcoded into runner classes or step definitions.