Cucumber Java Runner

A powerful VS Code extension that seamlessly integrates Cucumber feature files with VS Code's Test Explorer. Run and debug your Java Cucumber tests directly from the test panel with a clean, modern interface.

✨ What's New in This Fork

This is an enhanced version of the original Cucumber Java Easy Runner with significant improvements:

🚀 Major Enhancements

⚡ Maven Incremental Compilation (v1.0.12): Optimized build performance
- 🚀 Always up-to-date: Automatically detects and compiles only changed files
- ⏱️ Faster rebuilds: Maven's incremental compilation only recompiles what's necessary
- 🎯 More reliable: No longer skips compilation when source files have changed
- 🔧 Simpler code: Removed custom directory checking, leveraging Maven's built-in intelligence
- ✅ Dependency aware: Properly recompiles when dependencies or pom.xml changes
📊 Structured Logging System (v1.0.11): Professional logging with configurable levels
- 🎯 Configurable log levels: ERROR, WARN, INFO, DEBUG, TRACE - control verbosity via settings
- 🔍 Better troubleshooting: Set logLevel: "debug" or "trace" for detailed diagnostics
- 📝 Cleaner code: Removed all if (debugMode) blocks and debugMode setting
- ⏱️ Timestamp support: All log entries include timestamps for better traceability
- 📺 Output Channel integration: View logs in VS Code's Output Panel
- 🎨 Consistent formatting: All messages follow standard format [timestamp] [LEVEL] message
🎯 100% Accurate Results (v1.0.10): Fixed critical result processing bugs
- ✅ All scenarios marked correctly: Previously only first scenario was marked when running multiple scenarios
- ✅ Proper background filtering: Cucumber JSON includes non-test "background" elements that are now filtered out
- ✅ File URI handling: Correctly processes Cucumber's file: prefix in JSON results
- ✅ Multiple features work perfectly: Cross-feature contamination fixed with precise path matching
⚡ Lightning Fast Batch Execution (v1.0.9): Dramatically improved test execution speed
- 🚀 Run all tests in one go: Multiple features execute in a single Cucumber process
- ⏱️ Massive time savings: No more redundant startups/shutdowns for each feature
- 🎯 Smart mode detection: Automatically uses batch mode when running multiple features
- 📊 Perfect for CI/CD: Optimized for continuous integration pipelines
🛡️ Rock-Solid Reliability (v1.0.9): Fixed critical bugs and improved error handling
- ✅ No more infinite loops: Fixed Test Explorer running tests repeatedly
- ✅ No more crashes: Robust file validation prevents reading incomplete result files
- ✅ Accurate results: Fixed logic that incorrectly marked failed tests as passed
- ✅ Smart error detection: Detects errors in @Before/@After hooks and scenario setup
- ✅ Clear error messages: Shows exactly what failed (hook, setup, or specific step)
- ✅ Correct error location: Points to scenario line for setup errors, step line for step failures
- ✅ Optimized execution: No duplicate test runs when executing multiple tests
🌐 Multi-Platform Availability (v1.0.7+): Now available on both VS Code Marketplace AND Open VSX Registry
- ✅ Full support for Cursor, VSCodium, Eclipse Theia, Gitpod, and other VS Code-based editors
- ✅ Automated dual publishing to both marketplaces
✅ Real Test Results: Tests are now marked as passed ✅ or failed ❌ based on actual Cucumber execution results (not just "always passed")
📊 Individual Scenario Results: When running entire features, each scenario is marked individually with its real result
📍 Precise Error Location: Error markers appear on the exact line of the failed step, making debugging instant
🎯 Detailed Error Messages: See the exact step that failed with complete stack trace and error details
🔍 Multiple Failure Support: When multiple scenarios fail, each shows its specific error at the correct location
⚡ Smart Maven Compilation: Uses Maven's incremental compilation to automatically detect and compile only changed files - now configurable!
🐛 Debug & Run Modes: Both modes now use the same unified approach with proper result tracking
📝 JSON Result Analysis: Uses Cucumber's JSON output to determine pass/fail status with detailed error messages
🧹 Code Refactoring: Consolidated duplicate code and extracted result processing into dedicated module
🔧 Cleaner Architecture: Simplified codebase with better separation of concerns
⚙️ Flexible Configuration: Control compilation, exclude directories, and add external step definitions (v1.0.6+)

🔍 Technical Improvements

Batch Execution (v1.0.9): Multiple features run in a single Cucumber process for maximum speed
Robust File Processing (v1.0.9): Async result processing with retry mechanism and comprehensive validation
Accurate Test Status (v1.0.9): Correct pass/fail logic - only passes if ALL steps are 'passed'
Hook Error Detection (v1.0.9): Detects and reports errors in @Before/@After hooks
Unified Test Execution: Single runCucumberTest() function handles both run and debug modes
Result File Analysis: Uses --plugin json:${resultFile} to capture detailed test results
Dedicated Result Processor: New resultProcessor.ts module handles all test result parsing and marking
Precise Line Matching: Exact numeric comparison prevents false positives (e.g., line 5 vs line 57)
Smart Compilation: Maven's incremental compilation automatically detects and compiles only changed files
Consolidated Methods: Merged duplicate methods (runTests/debugTests, runSingleTest/debugSingleTest)
DRY Principles: Eliminated code repetition throughout the codebase

🎯 Features

Core Functionality

🧪 Test Explorer Integration: All your Cucumber features and scenarios appear in VS Code's Test Explorer panel
✅ Real Pass/Fail Status: Tests show actual results from Cucumber execution
🎯 Individual Scenario Execution: Run specific scenarios without executing the entire feature
🐛 Full Debug Support: Debug your step definitions with breakpoints
📊 Detailed Results: See which scenarios passed and which failed, with error details
🔄 Auto-discovery: Automatically finds and displays all feature files in your workspace
🚫 Smart Filtering: Excludes build directories (target, build, out) to prevent duplicate tests
⚡ Fast Refresh: Instantly refresh test list when new features are added
🔧 Auto-configuration: Automatically detects glue path, no manual setup required
📋 Optional CodeLens: Enable traditional play buttons in feature files if preferred

🚀 Usage

1. Test Explorer (Recommended)

The primary way to run Cucumber tests is through VS Code's Test Explorer:

Open Test Explorer: Click the test tube icon in the activity bar or press Ctrl+Shift+T
View Your Tests: All feature files and scenarios are automatically discovered and displayed
Run Tests: Click the play button next to any feature or scenario to run it
Debug Tests: Right-click and select "Debug Test" to debug with breakpoints
View Results: Tests are marked with ✅ (passed) or ❌ (failed) based on actual execution

🧪 Test Explorer
├─ 📁 Cucumber Java Tests
   ├─ 📄 Login Feature
   │  ├─ ✅ Successful login
   │  ├─ ❌ Failed login with wrong password  ← Shows real failure!
   │  └─ ✅ Password reset flow
   ├─ 📄 Shopping Cart Feature
   │  ├─ ✅ Add item to cart
   │  ├─ ✅ Remove item from cart
   │  └─ ❌ Checkout process  ← Shows which scenario actually failed!
   └─ 📄 User Registration Feature
      ├─ ✅ Valid registration
      └─ ❌ Invalid email format  ← Click to see error details

2. Running Multiple Scenarios

When you run an entire feature file:

Each scenario is executed
Each scenario is marked individually with its own pass/fail status
You can see at a glance which scenarios passed and which failed
Click on failed scenarios to see error details

3. Debugging

Right-click any test → "Debug Test"
Set breakpoints in your step definitions
Step through your code with full debugging support
Even in debug mode, tests are marked with correct pass/fail status after execution

4. CodeLens Play Buttons (Optional)

If you prefer the traditional approach with play buttons in feature files:

Enable CodeLens: Go to VS Code Settings → Extensions → Cucumber Java Runner
Check "Enable CodeLens": This will show play buttons directly in your feature files
Use Play Buttons: Click the buttons that appear on Feature, Scenario, and Example lines

Example feature file with CodeLens enabled:

▶ Run Feature | 🐛 Debug Feature
Feature: Shopping Cart

  ▶ Run Scenario | 🐛 Debug Scenario
  Scenario: Adding an item to cart
    Given I am on the product page
    When I click "Add to Cart"
    Then the item should be added to my cart

  ▶ Run Scenario | 🐛 Debug Scenario
  Scenario Outline: User login
    Given I enter "<username>" and "<password>"
    Then I should see "<result>"

    Examples:
      | username | password | result    |
      | admin    | admin123 | Welcome!  |
      | user1    | pass123  | Welcome!  |

You can also right-click on feature files:

Right-click on a .feature file in the file explorer → "Cucumber: Run Feature"
Right-click in an open feature file → "Cucumber: Run Feature/Scenario/Example"
Right-click in an open feature file → "Cucumber: Debug Feature/Scenario/Example"

⚙️ Configuration

Access settings via: Settings → Extensions → Cucumber Java Runner or edit your settings.json file directly.

Available Settings

Setting	Type	Default	Description
`cucumberJavaRunner.enableCodeLens`	boolean	`false`	Enable CodeLens buttons (▶ Run, 🐛 Debug) in feature files. When disabled, use Test Explorer instead for a cleaner interface.
`cucumberJavaRunner.logLevel`	string	`"info"`	Log level for extension output: `error`, `warn`, `info`, `debug`, or `trace`. Use `debug` or `trace` for troubleshooting.
`cucumberJavaRunner.objectFactory`	string	`""`	Custom Cucumber ObjectFactory class for dependency injection (e.g., Spring, Guice, PicoContainer). Leave empty for default.
`cucumberJavaRunner.autoCompileMaven`	boolean	`true`	Automatically compile Maven projects before running tests (only when target directory is missing).
`cucumberJavaRunner.excludeBuildDirectories`	array	`["target", "build", "out", "dist", "node_modules", ".git"]`	Directories to exclude when discovering feature files to avoid duplicates.
`cucumberJavaRunner.additionalGluePaths`	array	`[]`	Additional glue paths for step definitions (e.g., from external libraries). Use Java package format.

Configuration Examples

Using Spring Dependency Injection

{
  "cucumberJavaRunner.objectFactory": "cucumber.api.spring.SpringFactory"
}

Using Guice Dependency Injection

{
  "cucumberJavaRunner.objectFactory": "cucumber.api.guice.GuiceFactory"
}

Disable Auto-Compilation

{
  "cucumberJavaRunner.autoCompileMaven": false
}

Custom Excluded Directories

{
  "cucumberJavaRunner.excludeBuildDirectories": [
    "target",
    "build",
    "generated",
    "bin"
  ]
}

Additional Glue Paths (External Step Definitions)

Use this when you have step definitions in external libraries or modules:

{
  "cucumberJavaRunner.additionalGluePaths": [
    "com.external.library.steps",
    "org.another.library.cucumber.steps"
  ]
}

Enable CodeLens Buttons

{
  "cucumberJavaRunner.enableCodeLens": true
}

Log Level Configuration

Control extension logging verbosity:

{
  "cucumberJavaRunner.logLevel": "info"  // Options: error, warn, info, debug, trace
}

Use debug or trace when troubleshooting issues:

{
  "cucumberJavaRunner.logLevel": "debug"  // Enables detailed logging
}

View logs in Output Panel → Cucumber Java Runner.

Complete Configuration Example

{
  "cucumberJavaRunner.enableCodeLens": false,
  "cucumberJavaRunner.logLevel": "info",
  "cucumberJavaRunner.objectFactory": "cucumber.api.spring.SpringFactory",
  "cucumberJavaRunner.autoCompileMaven": true,
  "cucumberJavaRunner.excludeBuildDirectories": [
    "target",
    "build",
    "out",
    "dist"
  ],
  "cucumberJavaRunner.additionalGluePaths": [
    "com.mycompany.shared.steps"
  ]
}

🎨 Interface Options

Test Explorer (Default) - Recommended

Clean, organized view of all tests
Integrated with VS Code's testing framework
Shows real test status with ✅/❌ icons
Detailed error messages on failures
No visual clutter in feature files

CodeLens Buttons (Optional)

Traditional play buttons in feature files
Similar to IntelliJ IDEA experience
Enable via settings if preferred

📦 Installation

From Extension Marketplaces

VS Code

Open VS Code
Go to Extensions view (Ctrl+Shift+X)
Search for "Cucumber Java Runner"
Click Install

Or install directly from VS Code Marketplace

Cursor, VSCodium, and Other VS Code-based Editors

Open your editor
Go to Extensions view (Ctrl+Shift+X)
Search for "Cucumber Java Runner"
Click Install

Or install directly from Open VSX Registry

Manual Installation

Download the .vsix file from Releases
Open Extensions view → "..." menu → "Install from VSIX"
Select the downloaded file

🔧 Requirements

Java: JDK 8 or higher
Maven: 3.6 or higher
Project Structure: Standard Maven layout
Dependencies: Cucumber-JVM in your pom.xml
VS Code Extension: Java Extension Pack (for debugging support)

🤝 Works Great With Official Cucumber Extension

This extension is designed to work seamlessly with the Official Cucumber Extension.

Recommended Setup: Install both extensions together!

Official Cucumber: Provides syntax highlighting, formatting, validation, and step navigation
This Extension: Provides test execution, debugging, and Test Explorer integration

See USING_WITH_CUCUMBER_OFFICIAL.md for detailed compatibility guide.

🚀 Zero Configuration Required

The extension works automatically with standard Maven projects:

✅ Auto-detects step definition glue path
✅ Finds all feature files in your workspace
✅ Excludes build directories automatically
✅ Integrates with VS Code Test Explorer
✅ Optimized Maven compilation (only when needed)

If auto-detection fails, you'll be prompted to enter your glue path manually (e.g., com.example.steps).

🔄 Refreshing Tests

Automatic: New feature files are detected automatically Manual: Use the refresh button in Test Explorer or Command Palette → "Refresh Cucumber Tests"

💡 How It Works

Test Discovery: Scans workspace for .feature files
Auto-compilation: Uses Maven's incremental compilation to ensure code is up-to-date (compiles only changed files)
Test Execution: Runs Cucumber with --plugin json:${resultFile} to capture results
Result Analysis: Reads JSON output to determine pass/fail status for each scenario
UI Update: Updates Test Explorer with ✅ (passed) or ❌ (failed) icons
Cleanup: Removes temporary JSON result files

❓ Troubleshooting

Tests not showing in Test Explorer:

Make sure you have .feature files in your workspace
Check that files aren't in excluded directories (target, build, out)
Use the refresh button in Test Explorer
Check VS Code Output panel → "Cucumber Java Runner" for logs

CodeLens buttons not showing:

Enable CodeLens in extension settings
Make sure you're viewing a .feature file
Reload VS Code window

Glue path errors:

Extension will prompt you to enter the path manually
Use Java package format: com.example.steps
Check your step definitions are in the correct package

Test execution issues:

Verify Maven project structure (standard layout)
Check Cucumber dependencies in pom.xml
Ensure Java and Maven are in your PATH
Check terminal output for detailed error messages

Tests always showing as passed (old versions):

Update to latest version! This fork fixes that issue.
Make sure you're using version 1.0.0 or higher

Compilation issues:

Version 1.0.12+ uses Maven's incremental compilation for optimal performance
Maven automatically detects and compiles only changed files
If you need a clean build, run mvn clean manually before running tests

🛠️ Development

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode (auto-compile on changes)
npm run watch

# Package extension
npx vsce package

# Install locally for testing
code --install-extension cucumber-java-runner-1.0.0.vsix
# or
cursor --install-extension cucumber-java-runner-1.0.0.vsix

📊 Comparison: Original vs This Fork

Feature	Original	This Fork
Test Results	Always "passed" ⚠️	Real pass/fail status ✅
Individual Scenario Results	No ❌	Yes ✅
Maven Compilation	Always runs 🐌	Incremental (v1.0.12+) ⚡
Code Duplication	High 📚	Low (refactored) 🎯
Debug Mode Results	No tracking ❌	Full tracking ✅
Error Messages	Generic ⚠️	Detailed with step info 📝
Architecture	Separate runners 🔀	Unified runner 🎯

🔄 Contributing

Found a bug or have a feature request? Please report it on GitHub Issues.

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

📝 Changelog

See CHANGELOG.md for detailed version history.

🙏 Credits

This project is a fork of Cucumber Java Easy Runner by Hakki Etem.

Enhanced and maintained by: Lucas Biel (@lucasbiel7)

Major improvements include:

Real test result tracking
Individual scenario result marking
Optimized Maven compilation
Code refactoring and consolidation
Better error messages and debugging support

📄 License

MIT

Enjoy testing with Cucumber! 🥒✨

If you find this extension helpful, please ⭐ star the repository and leave a review on the marketplace!

Cucumber Java Runner

Lucas Dutra

Cucumber Java Runner

✨ What's New in This Fork

🚀 Major Enhancements

🔍 Technical Improvements

🎯 Features

Core Functionality

🚀 Usage

1. Test Explorer (Recommended)

2. Running Multiple Scenarios

3. Debugging

4. CodeLens Play Buttons (Optional)

5. Context Menu Options

⚙️ Configuration

Available Settings

Configuration Examples

Using Spring Dependency Injection

Using Guice Dependency Injection

Disable Auto-Compilation

Custom Excluded Directories

Additional Glue Paths (External Step Definitions)

Enable CodeLens Buttons

Log Level Configuration

Complete Configuration Example

🎨 Interface Options

Test Explorer (Default) - Recommended

CodeLens Buttons (Optional)

📦 Installation

From Extension Marketplaces

VS Code

Cursor, VSCodium, and Other VS Code-based Editors

Manual Installation

🔧 Requirements

🤝 Works Great With Official Cucumber Extension

🚀 Zero Configuration Required

🔄 Refreshing Tests

💡 How It Works

❓ Troubleshooting

🛠️ Development

📊 Comparison: Original vs This Fork

🔄 Contributing

📝 Changelog

🙏 Credits

📄 License