webdriverio-cucumber-parallel

🚀 Execute WebDriverIO Cucumber tests in parallel - Reduce test execution time by up to 80%!

🎯 Problem It Solves

WebDriverIO with Cucumber runs tests sequentially by default. If you have 100 test scenarios taking 2 minutes each, that's 200 minutes of waiting!

This package enables true parallel execution by:

• Extracting individual scenarios from feature files
• Running each scenario in its own isolated session
• Managing parallel instances automatically

⚡ Performance Impact

Sequential Execution:  100 scenarios × 2 min = 200 minutes ⏱️
Parallel Execution:    100 scenarios ÷ 10   =  20 minutes ⚡
Time Saved:            180 minutes (80% faster!)

📦 Installation

npm install webdriverio-cucumber-parallel --save-dev

🚀 Quick Start

CLI Usage (Easiest)

# Run tests with @smoke tag
npx wdio-parallel @smoke

# Run with custom config and 10 parallel instances
npx wdio-parallel @regression ./wdio.parallel.conf.js --max-instances=10

# Run all scenarios in specific features directory
npx wdio-parallel @e2e --features=./test/features/**/*.feature

Programmatic Usage

const { ParallelExecutor } = require('webdriverio-cucumber-parallel');

const executor = new ParallelExecutor({
    configPath: './wdio.conf.js',
    maxInstances: 5,
    featuresPath: './features/**/*.feature'
});

executor.run('@smoke');

Add to package.json

{
  "scripts": {
    "test:parallel": "wdio-parallel @smoke",
    "test:parallel:regression": "wdio-parallel @regression --max-instances=10",
    "test:parallel:sanity": "wdio-parallel @sanity"
  }
}

Then run:

npm run test:parallel

🛠️ Configuration

Step 1: Create Parallel Config

Create wdio.parallel.conf.js:

const baseConfig = require('./wdio.conf.js').config;

exports.config = {
    ...baseConfig,
    
    // Point to temp features directory (created automatically)
    specs: [
        './temp-features/**/*.feature'
    ],
    
    // Set max parallel instances
    maxInstances: process.env.MAX_INSTANCES || 5,
    
    capabilities: [{
        browserName: 'chrome',
        maxInstances: process.env.MAX_INSTANCES || 5,
        'goog:chromeOptions': {
            args: ['--headless', '--disable-gpu']
        }
    }]
};

Step 2: Run Tests

wdio-parallel @yourTag ./wdio.parallel.conf.js

📋 How It Works

1. Extraction: Searches feature files for scenarios matching your tag
2. Isolation: Creates individual feature files for each scenario in temp-features/
3. Execution: Runs WebDriverIO with config pointing to temp features
4. Parallel: Each scenario runs in its own browser session simultaneously
5. Cleanup: Automatically removes temp files after execution

🎨 API Reference

ParallelExecutor

const { ParallelExecutor } = require('webdriverio-cucumber-parallel');

const executor = new ParallelExecutor(options);

Options:

• configPath (string): Path to WDIO config file (default: './wdio.conf.js')
• maxInstances (number): Max parallel instances (default: 5)
• featuresPath (string): Features glob pattern (default: './features/**/*.feature')
• tempDir (string): Temp directory name (default: 'temp-features')

Methods:

• run(tagExpression) - Execute tests with given tag

ScenarioExtractor

const { ScenarioExtractor } = require('webdriverio-cucumber-parallel');

const extractor = new ScenarioExtractor(options);
const count = extractor.extract('@smoke');

Options:

• featuresPath (string): Features glob pattern
• tempDir (string): Output directory for extracted scenarios

Methods:

• extract(tagExpression) - Extract scenarios and return count
• cleanup() - Remove temp directory

🏷️ Tag Support

Supports full Cucumber tag expressions, including logical AND, OR, and NOT:

# Single tag
wdio-parallel @smoke
# Logical AND (scenarios with both tags)
wdio-parallel "@smoke and @critical"
# Logical OR (scenarios with either tag)
wdio-parallel "@smoke or @regression"
# NOT (scenarios without a tag)
wdio-parallel "not @regression"
# Complex expressions
wdio-parallel "(@smoke and not @regression) or @critical"

Tags can be at feature level or scenario level:

@smoke
Feature: Login

    @critical
    Scenario: Valid login
        Given I am on login page
    
    Scenario: Invalid login
        Given I am on login page

Running wdio-parallel "@critical" will execute only "Valid login" scenario. Running wdio-parallel "@smoke and @critical" will execute only scenarios with both tags.

Multi-tag Example Scenario File

This repo includes examples/basic-usage/features/multitag.feature, which contains scenarios tagged with different @smoke, @regression, and @critical combinations. To try it out locally:

cd examples/basic-usage
# Install dependencies once
npm install

# Run only scenarios that have both @smoke AND @critical tags
node ../../bin/wdio-parallel "@smoke and @critical" wdio.parallel.conf.js --features=./features/multitag.feature

# Run scenarios that are @smoke but NOT @regression
node ../../bin/wdio-parallel "@smoke and not @regression" wdio.parallel.conf.js --features=./features/multitag.feature

Quotes are required so the shell passes the tag expression unchanged to the CLI. Use any Cucumber-valid expression—parentheses, and, or, and not are all supported.

🌐 BrowserStack / Cloud Support

Works with any WebDriver service! Just configure in your WDIO config:

// wdio.browserstack.parallel.conf.js
exports.config = {
    user: process.env.BROWSERSTACK_USERNAME,
    key: process.env.BROWSERSTACK_ACCESS_KEY,
    
    specs: ['./temp-features/**/*.feature'],
    
    maxInstances: 5,
    
    capabilities[{
        browserName: 'chrome',
        maxInstances: 5
    }],
    
    services: ['browserstack']
};

Run with:

wdio-parallel @smoke ./wdio.browserstack.parallel.conf.js

📊 Reports

Works with all WDIO reporters! Configure in your WDIO config:

reporters: [
    'spec',
    ['allure', {
        outputDir: 'allure-results-parallel'
    }]
]

🔧 Troubleshooting

No scenarios found

Problem: No scenarios found with the specified tag

Solution:

• Check tag spelling (include @ symbol)
• Verify features path in options
• Ensure feature files have matching tags

Tests not running in parallel

Problem: Tests still run sequentially

Solution:

• Check maxInstances in your WDIO config
• Ensure config points to temp-features/**/*.feature
• Verify maxInstances is set in capabilities too

Temp files not cleaned up

Problem: temp-features/ directory persists

Solution:

• Package automatically cleans up after execution
• Manually clean: rm -rf temp-features

💡 Best Practices

1. Use specific tags: Instead of running all tests, use meaningful tags
2. Adjust maxInstances: Start with 5, increase based on your machine/plan
3. Independent scenarios: Ensure scenarios don't depend on each other
4. Resource limits: Don't exceed your machine's capability or cloud plan limits

🤝 Contributing

Contributions welcome! If you create a GitHub repository for this package, others can fork and submit pull requests.

📝 License

MIT © Gagan Singh

🙏 Credits

Created to solve real-world test execution time problems in WebDriverIO + Cucumber projects.

📞 Support

• 🐛 Issues: Create an issue on npm or GitHub (if repository created)
• 💬 Questions: WebDriverIO Discord community
• 📧 Contact: Available after publishing

Made with ❤️ for the test automation community

If this package saved you time, consider giving it a ⭐ on GitHub!