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

✅ 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
⚡ Optimized Maven Compilation: Only compiles when target folder doesn't exist (much faster execution) - 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

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 compilation only runs when needed (checks for target directory)
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.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
}

Complete Configuration Example

{
  "cucumberJavaRunner.enableCodeLens": false,
  "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 VS Code Marketplace

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

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: Compiles Maven project only if target folder doesn't exist
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 is slow:

This fork optimizes compilation! Only runs when target folder doesn't exist
Delete target folder to force recompilation when needed

🛠️ 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 🐌	Smart/optimized ⚡
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

Complete Configuration Example

🎨 Interface Options

Test Explorer (Default) - Recommended

CodeLens Buttons (Optional)

📦 Installation

From VS Code Marketplace

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