Implementation:Webdriverio Webdriverio InitializeServices

Knowledge Sources	Webdriverio_Webdriverio
Domains	Service_Architecture, Plugin_Management
Last Updated	2026-02-12 00:00 GMT

Overview

Initializes WebdriverIO services for both launcher and worker processes, resolving service entries from configuration into instantiated service objects.

Description

The InitializeServices module handles the two-phase service initialization pattern used by the WebdriverIO test runner. initializeLauncherService processes the services array from the configuration, supporting three service formats: plain objects with hook methods, class constructors, and NPM package name strings. For each service, it uses initializePlugin to dynamically import NPM packages, instantiates launcher classes with (serviceConfig, caps, config), and tracks services that have no default export (worker-only services are not needed in the launcher). It returns a list of launcherServices and a list of ignoredWorkerServices that can be skipped when initializing workers. initializeWorkerService performs similar resolution but filters out services in the ignore list and instantiates the default export (or the service class directly) for the worker process context. Both functions wrap their logic in try/catch blocks with descriptive error messages identifying which service failed to initialize.

Usage

Use initializeLauncherService in the test runner launcher process to set up services that need to run during the overall test execution (e.g., starting servers, compiling assets). Pass the returned ignoredWorkerServices list to initializeWorkerService in each worker process to avoid loading services that only have launcher-phase logic.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-utils/src/initializeServices.ts
Lines: 1-196

Signature

export async function initializeLauncherService(
    config: Omit<WebdriverIO.Config, 'capabilities' | keyof Services.HookFunctions>,
    caps: Capabilities.TestrunnerCapabilities
): Promise<{
    ignoredWorkerServices: string[];
    launcherServices: Services.ServiceInstance[];
}>

export async function initializeWorkerService(
    config: WebdriverIO.Config,
    caps: WebdriverIO.Capabilities,
    ignoredWorkerServices?: string[]
): Promise<Services.ServiceInstance[]>

Import

import { initializeLauncherService, initializeWorkerService } from '@wdio/utils'

I/O Contract

Inputs

Name	Type	Required	Description
config	WebdriverIO.Config (partial)	Yes	The test runner configuration object, must include the services array with service entries.
caps	Capabilities.TestrunnerCapabilities	Yes (launcher) / WebdriverIO.Capabilities (worker)	Capabilities passed to service constructors. Launcher receives the full capabilities set; worker receives a single capability.
ignoredWorkerServices	string[]	No (worker only)	List of service package names to skip in the worker, as returned by initializeLauncherService.

Outputs

Name	Type	Description
launcherServices	Services.ServiceInstance[]	Array of instantiated service objects for the launcher process, with hook methods ready to be called.
ignoredWorkerServices	string[]	Array of service package name strings that have no default export and should be skipped in worker initialization.
initializeWorkerService result	Services.ServiceInstance[]	Array of instantiated service objects for the worker process.

Usage Examples

import { initializeLauncherService, initializeWorkerService } from '@wdio/utils'

// In the launcher process
const config = {
    services: [
        '@wdio/lighthouse-service',
        ['@wdio/devtools-service', { debuggerAddress: '127.0.0.1:9222' }],
        [{ beforeTest: () => console.log('custom hook') }],
        [MyCustomServiceClass, { option1: true }]
    ]
}
const caps = [{ browserName: 'chrome' }]

const { launcherServices, ignoredWorkerServices } = await initializeLauncherService(config, caps)

// Start all launcher services
for (const service of launcherServices) {
    if (typeof service.onPrepare === 'function') {
        await service.onPrepare(config, caps)
    }
}

// In each worker process
const workerServices = await initializeWorkerService(
    config,
    { browserName: 'chrome' },
    ignoredWorkerServices
)

// Services are now ready to receive hook calls
for (const service of workerServices) {
    if (typeof service.before === 'function') {
        await service.before(caps, [], browser)
    }
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment