Principle:Webdriverio Webdriverio Test Execution Orchestration

Overview

A mechanism for orchestrating parallel test execution across multiple browser capabilities and worker processes.

Metadata

Field	Value
Page Type	Principle
Repository	webdriverio/webdriverio
Knowledge Sources	Repo (GitHub)
Domains	Testing, Orchestration
Related Implementations	Implementation: Launcher_Class

Description

Test Execution Orchestration coordinates the entire test run lifecycle: parsing configuration, launching browser driver processes, scheduling spec files across worker processes, managing parallel execution limits (maxInstances), collecting results, and producing a final exit code. It handles the lifecycle from config loading through test completion, including watch mode for iterative development.

The orchestrator is the central coordinator that connects all other components of the WDIO testrunner:

• Configuration -- the ConfigParser provides the fully-merged config object
• Runner -- the LocalRunner (or BrowserRunner) spawns and manages worker processes
• Framework Adapter -- Mocha, Jasmine, or Cucumber runs the actual tests within each worker
• Services -- lifecycle plugins (chromedriver, devtools, etc.) start/stop alongside the test run
• Reporters -- consume test events and produce output

The orchestrator ensures that all these components are initialized in the correct order, that parallel execution respects resource constraints, and that cleanup happens reliably even on unexpected failures or SIGINT/SIGTERM signals.

Usage

Use when running tests via the WDIO testrunner. Execution orchestration is triggered by the CLI command or programmatically via the Launcher class:

CLI invocation

# Standard test run
npx wdio run wdio.conf.ts

# Run specific specs
npx wdio run wdio.conf.ts --spec ./test/specs/login.ts

# Run a named suite
npx wdio run wdio.conf.ts --suite smoke

# Watch mode for development
npx wdio run wdio.conf.ts --watch

# Sharded execution for CI
npx wdio run wdio.conf.ts --shard 1/4

Programmatic invocation

import Launcher from '@wdio/cli'

const launcher = new Launcher('./wdio.conf.ts', {
    spec: ['./test/specs/login.ts'],
    baseUrl: 'http://staging.example.com'
})

const exitCode = await launcher.run()
process.exit(exitCode)

Theoretical Basis

Producer-Consumer Pattern

The orchestrator follows a producer-consumer pattern: spec files are produced from configuration (via ConfigParser.getSpecs()), and worker processes consume them. The scheduling algorithm:

1. Build a schedule array, one entry per capability, containing:
   • The capability definition (browser, platform, etc.)
   • The list of spec files to run for that capability
   • The number of available instances (from wdio:maxInstances or maxInstancesPerCapability)
   • The count of currently running instances
2. In a loop, find capabilities with available instances and pending specs
3. Sort schedulable capabilities by running instances (fewest first) for load balancing
4. Spawn a worker for the next spec file from the least-loaded capability
5. Repeat until maxInstances global limit is reached or no specs remain
6. When a worker exits, update the schedule and spawn the next pending spec

Parallel Execution Constraints

Parallelism is controlled at two levels:

• Global: maxInstances (default 100) -- the total number of concurrent worker processes across all capabilities
• Per-capability: wdio:maxInstances or maxInstancesPerCapability (default 100) -- the maximum concurrent workers for a single capability

Lifecycle Hooks

The orchestrator invokes lifecycle hooks in a specific order:

1. onPrepare -- before any worker is spawned (config-level and service-level)
2. onWorkerStart -- before each individual worker starts
3. (worker executes specs)
4. onWorkerEnd -- after each worker completes
5. onComplete -- after all workers have finished (user hooks run before service hooks to ensure plugins like shared store are still available)

Failure Handling

• bail: If config.bail is set to a positive number, the orchestrator stops scheduling new specs after that many workers have failed
• specFileRetries: Failed spec files can be retried a configurable number of times, either immediately (specFileRetriesDeferred: false) or after all other specs (specFileRetriesDeferred: true)
• Exit code: The orchestrator returns 0 if all specs passed, 1 if any failed

Watch Mode

In watch mode, the orchestrator monitors spec files for changes and re-runs affected tests automatically. The Watcher class manages file system monitoring and triggers re-execution through the Launcher.

Related Pages

Implementation:Webdriverio_Webdriverio_Launcher_Class

• Implemented by: Implementation: Launcher_Class
• Depends on: Principle: Test_Configuration_Parsing
• Executes: Principle: Test_Spec_Authoring
• Reports via: Principle: Test_Result_Reporting