Implementation:Webdriverio Webdriverio Services Types

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

Overview

Interfaces and types for WebdriverIO services, runners, and lifecycle hooks that define the plugin architecture for extending test execution behavior.

Description

This module provides the type contracts for the WebdriverIO service and runner plugin system. RunnerInstance and RunnerClass define the interface for test runners (local or browser). ServiceClass and ServiceInstance define how services are constructed and what lifecycle methods they expose. The central HookFunctions interface enumerates all available lifecycle hooks (e.g., onPrepare, before, beforeTest, afterCommand) with their full signatures. The Hooks type wraps these to allow either single functions or arrays. ServiceEntry is a union type supporting multiple service declaration formats in configuration.

Usage

Use these types when creating custom WebdriverIO services or runners. Implement ServiceInstance to define a service class with lifecycle hooks. Use HookFunctions when you need to type individual hook implementations. Reference ServiceEntry when building dynamic configuration that programmatically constructs the services array. The Hooks type is consumed by the testrunner configuration interface.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-types/src/Services.ts
Lines: 1-320

Signature

export interface RunnerInstance {
    initialize(): Promise<void>
    shutdown(): Promise<boolean>
    closeSession?: (cid: number) => Promise<void>
    getWorkerCount(): number
    run(args: any): Worker
    workerPool: any
    browserPool: any
}

export interface RunnerClass {
    new(
        options: WebdriverIO.BrowserRunnerOptions,
        config: Omit<WebdriverIOOptions, 'capabilities' | keyof Hooks>
    ): RunnerInstance
}

export interface ServiceClass {
    new(
        options: WebdriverIO.ServiceOption,
        capabilities: ResolvedTestrunnerCapabilities,
        config: WebdriverIOOptions
    ): ServiceInstance
}

export interface ServiceInstance extends HookFunctions {
    options?: Record<string, any>
    capabilities?: WebdriverIO.Capabilities
    config?: TestrunnerOptions
}

export type ServiceEntry = (
    string |
    HookFunctions |
    ServiceClass |
    [string, WebdriverIO.ServiceOption] |
    [ServiceClass, WebdriverIO.ServiceOption]
)

export type Hooks = {
    [k in keyof HookFunctions]: HookFunctions[k] | NonNullable<HookFunctions[k]>[]
}

export interface HookFunctions {
    onPrepare?(config: TestrunnerOptions, capabilities: TestrunnerCapabilities): unknown | Promise<unknown>
    onComplete?(exitCode: number, config: Omit<TestrunnerOptions, 'capabilities'>,
        capabilities: TestrunnerCapabilities, results: any): unknown | Promise<unknown>
    onWorkerStart?(cid: string, capabilities: WebdriverIO.Capabilities,
        specs: string[], args: TestrunnerOptions, execArgv: string[]): unknown | Promise<unknown>
    onWorkerEnd?(cid: string, exitCode: number, specs: string[], retries: number): unknown | Promise<unknown>
    before?(capabilities: RequestedStandaloneCapabilities | RequestedMultiremoteCapabilities,
        specs: string[], browser: any): unknown | Promise<unknown>
    after?(result: number, capabilities: RequestedStandaloneCapabilities | RequestedMultiremoteCapabilities,
        specs: string[]): unknown | Promise<unknown>
    beforeSession?(config: Omit<TestrunnerOptions, 'capabilities'>,
        capabilities: RequestedStandaloneCapabilities | RequestedMultiremoteCapabilities,
        specs: string[], cid: string): unknown | Promise<unknown>
    afterSession?(config: TestrunnerOptions, capabilities: WebdriverIO.Capabilities,
        specs: string[]): unknown | Promise<unknown>
    beforeSuite?(suite: Suite): unknown | Promise<unknown>
    afterSuite?(suite: Suite): unknown | Promise<unknown>
    beforeTest?(test: Test, context: any): unknown | Promise<unknown>
    afterTest?(test: Test, context: any, result: TestResult): unknown | Promise<unknown>
    beforeHook?(test: any, context: any, hookName: string): unknown | Promise<unknown>
    afterHook?(test: Test, context: any, result: TestResult, hookName: string): unknown | Promise<unknown>
    beforeCommand?(commandName: string, args: any[]): unknown | Promise<unknown>
    afterCommand?(commandName: string, args: any[], result: any, error?: Error): unknown | Promise<unknown>
    onReload?(oldSessionId: string, newSessionId: string): unknown | Promise<unknown>
    beforeAssertion?(params: AssertionHookParams): unknown | Promise<unknown>
    afterAssertion?(params: AfterAssertionHookParams): unknown | Promise<unknown>
}

Import

import type { Services } from '@wdio/types'

// Access specific types
type MyRunner = Services.RunnerInstance
type MyService = Services.ServiceInstance
type Entry = Services.ServiceEntry
type AllHooks = Services.Hooks
type HookFns = Services.HookFunctions

I/O Contract

Key Type Members (HookFunctions)
Hook Name	Phase	Key Parameters	Description
`onPrepare`	Setup	config, capabilities	Runs once before all workers launch
`onWorkerStart`	Setup	cid, capabilities, specs	Runs before each worker process spawns
`beforeSession`	Session	config, capabilities, specs, cid	Runs before WebDriver session initialization
`before`	Execution	capabilities, specs, browser	Runs before test execution begins
`beforeSuite`	Execution	suite	Runs before each test suite starts
`beforeTest`	Execution	test, context	Runs before each individual test
`beforeCommand`	Execution	commandName, args	Runs before each WebdriverIO command
`afterCommand`	Execution	commandName, args, result, error	Runs after each WebdriverIO command
`afterTest`	Execution	test, context, result	Runs after each individual test
`afterSuite`	Execution	suite	Runs after each test suite ends
`after`	Teardown	result, capabilities, specs	Runs after all tests complete
`afterSession`	Teardown	config, capabilities, specs	Runs after WebDriver session terminates
`onWorkerEnd`	Teardown	cid, exitCode, specs, retries	Runs after each worker process exits
`onComplete`	Teardown	exitCode, config, capabilities, results	Runs once after all workers shut down

Dependent / Derived Types
Name	Description	Used By
`Hooks`	Mapped type allowing single or array hook values	`Options.Testrunner`
`ServiceEntry`	Union of all valid service declaration formats	`services` config property
`RunnerInstance`	Contract for runner implementations	Local and Browser runners
`ServiceInstance`	Contract for service implementations	All WebdriverIO services

Usage Examples

import type { Services, Capabilities, Options } from '@wdio/types'

// Implement a custom service
class MyCustomService implements Services.ServiceInstance {
    private baseUrl: string

    constructor(
        options: WebdriverIO.ServiceOption,
        capabilities: Capabilities.ResolvedTestrunnerCapabilities,
        config: Options.WebdriverIO
    ) {
        this.baseUrl = config.baseUrl || ''
    }

    async onPrepare(config: Options.Testrunner) {
        console.log('Starting test environment...')
    }

    async before(
        capabilities: WebdriverIO.Capabilities,
        specs: string[],
        browser: WebdriverIO.Browser
    ) {
        await browser.url(this.baseUrl)
    }

    async beforeTest(test: Frameworks.Test, context: any) {
        console.log(`Running test: ${test.fullTitle}`)
    }

    async afterTest(
        test: Frameworks.Test,
        context: any,
        result: Frameworks.TestResult
    ) {
        if (!result.passed) {
            console.error(`Test failed: ${test.fullTitle}`)
        }
    }

    async onComplete(exitCode: number) {
        console.log(`Tests completed with exit code: ${exitCode}`)
    }
}

// Configure services in wdio.conf.ts
const services: Services.ServiceEntry[] = [
    'chromedriver',
    ['@wdio/sauce-service', { sauceConnect: true }],
    [MyCustomService, { customOption: 'value' }],
    { onPrepare: () => console.log('inline service hook') }
]

Related Pages

Principle:Webdriverio_Webdriverio_Plugin_Architecture
Implementation:Webdriverio_Webdriverio_Options_Types - Testrunner interface that consumes Hooks and ServiceEntry
Implementation:Webdriverio_Webdriverio_Frameworks_Types - Suite/Test/TestResult types used in hook parameters
Implementation:Webdriverio_Webdriverio_Workers_Types - Worker interface returned by RunnerInstance.run()
Implementation:Webdriverio_Webdriverio_Config_Constants - SUPPORTED_HOOKS array listing all hook names

Page Connections

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

Principle

Implementation

Heuristic

Environment