🥒 Cucumber Runner 4J

A professional VSCode extension to run Cucumber tests directly from .feature files with integrated Java support, optimized for Spring Boot and TestContainers.

✨ Features

• 🎯 Integrated CodeLens: "Run Scenario", "Run Feature" and "Run All Tests" buttons directly in the editor
• 🧪 VSCode Testing Panel: Complete integration with native test explorer
• 🔍 Intelligent Detection: Automatic configuration for JUnit Platform, JUnit Classic, TestNG
• ⚙️ Build Tools Support: Maven and Gradle with automatic runner detection
• 🚀 Optimized Execution: Automatic RunCucumberIT detection to avoid container duplication
• 🐳 TestContainers Friendly: Sequential execution to prevent Spring Boot context duplication
• ⚡ Maven Performance: Optimization options to avoid unnecessary recompilation
• 📊 Detailed Results: Status, logs and errors display in VSCode interface

📋 Prerequisites

• Java 8+ installed and configured in PATH
• Maven 3.6+ or Gradle 6+ configured in your project
• Cucumber dependencies in your pom.xml or build.gradle

Recommended Maven Configuration

<!-- Cucumber Dependencies -->
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>7.18.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit-platform-engine</artifactId>
    <version>7.18.0</version>
    <scope>test</scope>
</dependency>

<!-- For Spring Boot + TestContainers -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-testcontainers</artifactId>
    <scope>test</scope>
</dependency>

Recommended RunCucumberIT Class

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "com.example.steps")
@CucumberContextConfiguration
@SpringBootTest
public class RunCucumberIT {
    // Optimized runner class for Spring Boot + TestContainers
}

🚀 Usage

Method 1: CodeLens (Recommended)

1. Open a .feature file: The extension automatically detects Gherkin files
2. Visible CodeLens: Buttons appear automatically:
   • 🎯 "Run Scenario": Above each scenario
   • 📁 "Run Feature": At the top of the file for the entire feature
   • 🧪 "Run All Tests": To execute all Cucumber tests
3. Click to execute: Tests launch with optimal configuration

Method 2: VSCode Testing Panel

1. Open Testing Panel: Ctrl+Shift+T or via sidebar
2. Tree Navigation: Features → Scenarios organized automatically
3. Flexible Execution: Right-click for "Run" or "Debug" (coming soon)

🎯 Intelligent Detection

The extension automatically detects your configuration:

• ✅ RunCucumberIT detected → Uses JUnit Platform to avoid TestContainers duplicates
• ✅ Spring Boot + TestContainers → Forces sequential execution
• ✅ Maven Failsafe plugin → Uses mvn failsafe:integration-test
• ✅ Parent POM configuration → Inherited plugin detection
• ✅ Automatic glue packages → Scans step definitions

🏗️ Technical Architecture

Main Components

• GherkinParser: Parses .feature files and extracts features/scenarios
• CodeLensProvider: Displays execution buttons in the editor
• TestController: Native integration with VSCode Testing panel
• JavaTestRunner: Intelligent execution engine (JUnit + CLI hybrid)
• TestResultManager: Results management and visual decorators

Hybrid Execution Strategy

flowchart TD
    A[.feature file opened] --> B[RunCucumberIT Detection]
    B -->|Found| C[JUnit Platform Execution]
    B -->|Not Found| D[CLI Cucumber Fallback]
    C --> E[Maven failsafe:integration-test]
    D --> F[Maven test + cucumber.options]
    E --> G[Optimized Results]
    F --> G

⚡ Maven Optimizations

The extension includes automatic Maven optimizations to improve performance:

# Options automatically added to all Maven commands
-Dmaven.compiler.useIncrementalCompilation=false 
-Dhibernate.enhance.skip=true

Benefits

• ⚡ Faster compilation: Avoids unnecessary recompilation
• 🚫 Skip Hibernate enhance: No superfluous bytecode processing
• 🔄 Class reuse: Maven reuses already compiled classes

🐳 TestContainers Support

Automatic Spring Boot + TestContainers Detection

The extension automatically detects projects using TestContainers and adapts execution:

// Automatic detection of these annotations/dependencies
@SpringBootTest
@Testcontainers
@Container
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");

Applied Optimizations

• 🔒 Sequential execution: maxConcurrentTests = 1 to avoid container duplicates
• 🎯 RunCucumberIT usage: Priority to JUnit classes for unique context
• ⏱️ Context reuse: Avoids container restarts

🛠️ Development

Installation

npm install

Compilation

npm run compile

Watch Mode (Hot reload)

npm run watch

Testing the Extension

1. F5: Launches a new VSCode window with the extension
2. Open examples/calculator.feature: Test functionality
3. Observe CodeLens: Verify button display

🔧 Supported Configurations

The extension automatically detects your Cucumber configuration and adapts execution:

JUnit Platform Engine (⭐ Recommended)

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit-platform-engine</artifactId>
    <version>7.18.0</version>
    <scope>test</scope>
</dependency>

Benefits: Better integration, advanced filter support, TestContainers compatible

JUnit Classic

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-junit</artifactId>
    <version>7.18.0</version>
    <scope>test</scope>
</dependency>

TestNG

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-testng</artifactId>
    <version>7.18.0</version>
    <scope>test</scope>
</dependency>

Gradle (Basic Support)

testImplementation("io.cucumber:cucumber-java:7.18.0")
testImplementation("io.cucumber:cucumber-junit-platform-engine:7.18.0")

Integration Tests with Failsafe

For projects using Maven Failsafe plugin for integration tests:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <systemPropertyVariables>
            <cucumber.filter.name></cucumber.filter.name>
        </systemPropertyVariables>
    </configuration>
</plugin>

🔍 Troubleshooting

Tests Won't Execute

1. Output Channel: View > Output > Cucumber Runner 4J to see detailed logs
2. Generated Command: The exact Maven/Gradle command is displayed
3. Detected Configuration: Check which runner/setup was detected
4. Java PATH: Ensure Java is in the system PATH

TestContainers Issues

1. Container Duplicates: Check that RunCucumberIT is detected (logs in Output)
2. Spring Boot Context: Extension forces sequential execution if detected
3. Docker Permissions: Ensure user can access Docker

Maven/Gradle Configuration

# Check effective Maven configuration
mvn help:effective-pom

# Check Cucumber dependencies
mvn dependency:tree | grep cucumber

# Manual test of generated command (see Output Channel)
mvn test-compile failsafe:integration-test -Dit.test="RunCucumberIT" -Dcucumber.features="src/test/resources/features/calculator.feature"

Scenario Filtering

• JUnit Platform + RunCucumberIT: uses cucumber.filter.name
• CLI Fallback: uses cucumber.options="--name"
• Special Characters: Automatic regex escaping
• Spaces and Quotes: Automatic shell escaping

Maven Configuration Inheritance

The extension intelligently detects:

• ✅ Failsafe plugin in local POM
• ✅ Plugin inherited from parent POM
• ✅ Known parent POM patterns (api-tooling-parent, spring-boot-parent, etc.)
• ✅ Effective POM via mvn help:effective-pom
• ✅ Fallback to found *IT.java classes

Slow Maven Performance

Optimizations are applied automatically, but you can verify:

# In logs, you should see these options
-Dmaven.compiler.useIncrementalCompilation=false -Dhibernate.enhance.skip=true

🗺️ Roadmap

✅ Completed

• [x] Integrated CodeLens for direct execution from editor
• [x] VSCode Testing Panel with tree navigation
• [x] Intelligent RunCucumberIT detection to optimize TestContainers
• [x] Spring Boot + TestContainers support with sequential execution
• [x] Maven optimizations to avoid unnecessary recompilation
• [x] Automatic detection of Cucumber configurations (JUnit Platform, Classic, TestNG)
• [x] Maven inheritance support for Failsafe plugin from parent POM
• [x] Special character handling in scenario names with escaping
• [x] Auto-detection glue packages via step definitions scan
• [x] Hybrid strategy JUnit Platform + CLI fallback

🚧 In Progress

• [ ] Debug Mode with breakpoints in step definitions
• [ ] Cucumber tags support for advanced filtering (@smoke, @integration, etc.)
• [ ] JSON results parser for detailed error display

📅 Planned

• [ ] Enhanced Gradle with automatic runner detection
• [ ] Intelligent parallel execution (excluding TestContainers)
• [ ] Coverage integration with JaCoCo
• [ ] Cucumber Reports integrated in VSCode
• [ ] Auto-generation step definitions from scenarios

⚠️ Current Limitations

• Debug Mode: Not yet implemented (planned v0.2.0)
• Gradle: Basic support, improvements in progress
• Parallel Tests: Automatically disabled for TestContainers projects
• Windows: Not extensively tested (feedback welcome)

🤝 Contributing

Contributions are welcome!

Project Structure

src/
├── extension.ts          # VSCode entry point
├── gherkinParser.ts      # .feature files parser  
├── codeLensProvider.ts   # Editor buttons
├── testController.ts     # Testing panel integration
├── javaTestRunner.ts     # Main execution engine
└── testResultManager.ts  # Results and decorators management

Guidelines

• Strict TypeScript: No any, explicit types
• Unit Tests: Cover new functionality
• Detailed Logs: Use outputChannel for debugging
• Compatibility: Test on real Maven projects

📄 License

MIT License - See LICENSE for details.

🙏 Acknowledgments

• Cucumber team for the excellent BDD framework
• VSCode team for the extensible and well-documented API
• Spring Boot + TestContainers for the modern testing ecosystem
• Java community for feedback and contributions