Cucumber Test Runner for Java
Run and debug Cucumber BDD scenarios from VS Code's native Test Explorer.
Features
- Discovers
.feature files and displays them in the Test Explorer with full hierarchy: Feature > Rule > Scenario > Scenario Outline > Examples
- Run individual scenarios, entire feature files, or all tests with the play button
- Debug mode with breakpoint support in step definitions (attaches to Maven Surefire's forked JVM via JDWP)
- Parses all Gherkin constructs: Scenario Outline with multiple Examples blocks, Rule keyword, Background, Data Tables, Doc Strings, tags, i18n
- Tag inheritance displayed in the test tree (Feature tags propagate to scenarios)
- Auto-detects Maven Wrapper (
mvnw / mvnw.cmd) — prefers it over global mvn
- Auto-detects Cucumber runner class (
@IncludeEngines("cucumber") or @Cucumber)
- Preserves existing Cucumber reporter plugins while adding JSON output for result parsing
- Multi-project support: multiple Maven projects in one workspace are grouped by project name
- File watching with debouncing — test tree updates as you edit
.feature files
Requirements
- Java —
JAVA_HOME must be set, or java must be on your PATH
- Maven — the project must use Maven with
maven-surefire-plugin
cucumber-junit-platform-engine — Cucumber's JUnit Platform integration must be in your test dependencies- Debugger for Java (
vscjava.vscode-java-debug) — required only for debug mode
A typical pom.xml setup:
<dependency>
<groupId>io.cucumber</groupId>
<artifactId>cucumber-java</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.cucumber</groupId>
<artifactId>cucumber-junit-platform-engine</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.platform</groupId>
<artifactId>junit-platform-suite</artifactId>
<scope>test</scope>
</dependency>
With a runner class like:
@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
public class CucumberTest {
}
Installation
From VSIX (local)
code --install-extension cucumber-java-test-runner-0.1.0.vsix
From source
git clone <repo-url>
cd cucumber-java-test-runner
npm install
npm run build
npx vsce package --no-dependencies --allow-missing-repository
code --install-extension cucumber-java-test-runner-0.1.0.vsix
Usage
- Open a Maven project that has
.feature files in src/test/resources/
- Open the Testing sidebar (beaker icon)
- Feature files appear grouped by project, with scenarios listed under each feature
- Click the play button next to a scenario to run it, or the play button on a feature to run all its scenarios
- Click the debug icon to debug with breakpoints in your step definitions
Multiple Maven projects in one workspace are automatically detected and grouped by project name.
Configuration
| Setting |
Default |
Description |
cucumberTestRunner.maven.executable |
mvn |
Path to Maven executable. Maven Wrapper is auto-detected and preferred. |
cucumberTestRunner.maven.additionalArgs |
[] |
Additional Maven arguments (e.g., ["-Pintegration"]). |
cucumberTestRunner.runnerClass |
(auto-detected) |
Cucumber runner class name. Scanned from src/test/java/ if empty. |
cucumberTestRunner.featuresPath |
(auto-detected) |
Path to features directory relative to project root. |
cucumberTestRunner.defaultTags |
(none) |
Default tag expression for all runs (e.g., "not @wip"). |
cucumberTestRunner.glue |
(auto-detected) |
Cucumber glue (step definitions) package. Read from junit-platform.properties if empty. |
Known Limitations
- Maven only — Gradle support is planned but not yet implemented. The architecture supports it (pluggable
BuildToolRunner interface).
- Multi-module Maven projects (parent POM with
<modules>) are not supported. The extension detects independent Maven projects within a workspace by finding the nearest pom.xml with a src/ directory. Multi-module aggregator POMs without src/ are skipped.
- Debug mode supports one project at a time. If you select tests from multiple projects and click Debug, only the first project runs in debug mode. The rest are skipped with a warning. Run mode handles multiple projects sequentially without this restriction.
Releasing New Versions
The main branch is protected — all changes go through pull requests. Publishing to the VS Code Marketplace is automated via GitHub Actions:
- Create a branch and make your changes
- Bump
version in package.json (e.g., "0.1.1" → "0.2.0")
- Open a PR and merge to
main
- CI detects the version change, runs tests, publishes to the marketplace, and creates a git tag
If the version in package.json is unchanged, CI skips publishing. Only version bumps trigger a release.
How It Works
- Discovery: Parses
.feature files using the official @cucumber/gherkin parser (the same one the Cucumber VS Code extension uses)
- Execution (specific scenarios): Compiles with
mvn test-compile, then runs io.cucumber.core.cli.Main directly — bypasses Surefire for reliable single-scenario execution
- Execution (Run All): Runs
mvn test with the detected runner class
- Results: Parses Cucumber's JSON reporter output and maps results back to test items by feature URI and line number
- Debug: Runs
io.cucumber.core.cli.Main with JDWP debug arguments, polls the debug port, then attaches VS Code's Java debugger
License
MIT
