Implementation:Webdriverio Webdriverio Options Types

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

Overview

TypeScript type definitions for all WebdriverIO configuration options, covering connection parameters, WebDriver settings, the WebdriverIO extension layer, and the full testrunner configuration interface.

Description

This module defines the layered configuration type hierarchy used across the WebdriverIO ecosystem. The Connection interface provides base protocol/hostname/port settings. WebDriver extends it with logging and retry options. WebdriverIO adds automation-specific settings such as baseUrl and waitforTimeout. The Testrunner interface brings together hooks, services, reporters, and spec management into the complete configuration type used by wdio.conf.ts. Supporting types include RunnerStart and RunnerEnd for runner lifecycle events, and Definition<T> for configuration validation schemas.

Usage

Use these types when creating or extending WebdriverIO configuration files, building custom services that consume configuration, or defining typed configuration parameters. The Testrunner interface is the primary type for the configuration object exported from wdio.conf.ts. The WebDriver and WebdriverIO interfaces are used for standalone or programmatic browser sessions.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/wdio-types/src/Options.ts
Lines: 1-419

Signature

export type WebDriverLogTypes = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent'
export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'HEAD' | 'DELETE' | 'OPTIONS' | 'TRACE'
    | 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete' | 'options' | 'trace'
export type SauceRegions = 'us' | 'eu' | 'us-west-1' | 'us-east-4' | 'eu-central-1' | 'staging'

export interface Connection {
    protocol?: string
    hostname?: string
    port?: number
    path?: string
    queryParams?: { [name: string]: string }
    user?: string
    key?: string
}

export interface WebDriver extends Connection {
    logLevel?: WebDriverLogTypes
    logLevels?: Record<string, WebDriverLogTypes>
    connectionRetryTimeout?: number    // default: 120000
    connectionRetryCount?: number      // default: 3
    headers?: { [name: string]: string }
    transformRequest?: (requestOptions: RequestInit) => RequestInit
    transformResponse?: (response: RequestLibResponse, requestOptions: RequestInit) => RequestLibResponse
    enableDirectConnect?: boolean
    strictSSL?: boolean
    outputDir?: string
    cacheDir?: string
}

export interface WebdriverIO extends WebDriver, Pick<Hooks, 'onReload' | 'beforeCommand' | 'afterCommand'> {
    automationProtocol?: string
    region?: SauceRegions
    baseUrl?: string
    waitforTimeout?: number    // default: 5000
    waitforInterval?: number   // default: 500
}

export interface Testrunner extends Hooks, WebdriverIO, WebdriverIO.HookFunctionExtension {
    runner?: 'local' | 'browser' | ['browser', WebdriverIO.BrowserRunnerOptions] | ['local', never]
    rootDir?: string
    specs?: (string | string[])[]
    exclude?: string[]
    suites?: Record<string, (string | string[])[] | string[][]>
    maxInstances?: number
    maxInstancesPerCapability?: number
    injectGlobals?: boolean
    bail?: number
    specFileRetries?: number
    specFileRetriesDelay?: number
    specFileRetriesDeferred?: boolean
    services?: ServiceEntry[]
    framework?: string
    reporters?: ReporterEntry[]
    shard?: ShardOptions
    mochaOpts?: WebdriverIO.MochaOpts
    jasmineOpts?: WebdriverIO.JasmineOpts
    cucumberOpts?: WebdriverIO.CucumberOpts
}

export type Definition<T> = {
    [k in keyof T]: {
        type: 'string' | 'number' | 'object' | 'boolean' | 'function'
        default?: T[k]
        required?: boolean
        validate?: (option: T[k]) => void
        match?: RegExp
    }
}

export interface RunnerStart {
    cid: string
    specs: string[]
    config: Testrunner
    isMultiremote: boolean
    sessionId: string
    capabilities: WebdriverIO.Capabilities
}

export interface RunnerEnd {
    failures: number
    cid: string
    retries: number
    error?: string
}

Import

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

// Access specific interfaces
type Connection = Options.Connection
type WebDriverOpts = Options.WebDriver
type WdioOpts = Options.WebdriverIO
type TestrunnerOpts = Options.Testrunner
type LogTypes = Options.WebDriverLogTypes
type ConfigDef = Options.Definition<Options.Testrunner>

I/O Contract

Key Type Members (Connection)
Name	Type	Default	Description
`protocol`	`string`	`'http'`	Protocol for WebDriver server communication
`hostname`	`string`	`'localhost'`	Host of the WebDriver server
`port`	`number`	-	Port of the WebDriver server
`path`	`string`	`'/'`	Path to WebDriver endpoint or grid server
`user`	`string`	-	Cloud service username
`key`	`string`	-	Cloud service access key

Key Type Members (Testrunner)
Name	Type	Default	Description
`specs`	string[])[]	`[]`	Spec file glob patterns for test execution
`maxInstances`	`number`	`100`	Maximum parallel running workers
`bail`	`number`	`0`	Stop after N test failures (0 = run all)
`framework`	`string`	`'mocha'`	Test framework to use
`services`	`ServiceEntry[]`	`[]`	Services to enhance test setup
`reporters`	`ReporterEntry[]`	`[]`	List of reporters
`specFileRetries`	`number`	`0`	Number of retries for entire spec files
`shard`	`ShardOptions`	`{ current: 1, total: 1 }`	Test sharding configuration

Dependent / Derived Types
Name	Description	Used By
`Definition<T>`	Schema type for configuration validation rules	`validateConfig()`
`RunnerStart`	Metadata emitted when a worker runner starts	Runner lifecycle events
`RunnerEnd`	Metadata emitted when a worker runner completes	Runner lifecycle events
`RequestLibResponse`	HTTP response shape for request transforms	`transformResponse`

Usage Examples

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

// Type a full testrunner configuration
const config: Options.Testrunner = {
    runner: 'local',
    specs: ['./test/specs/**/*.ts'],
    exclude: ['./test/specs/skip/**'],
    maxInstances: 10,
    maxInstancesPerCapability: 5,
    bail: 0,
    baseUrl: 'https://app.example.com',
    waitforTimeout: 10000,
    connectionRetryTimeout: 120000,
    connectionRetryCount: 3,
    framework: 'mocha',
    reporters: ['spec'],
    services: ['chromedriver'],
    logLevel: 'info',
    specFileRetries: 1,
    specFileRetriesDeferred: true,
    shard: { current: 1, total: 3 },
    mochaOpts: {
        timeout: 60000
    }
}

// Type a standalone WebdriverIO session configuration
const standaloneOpts: Options.WebdriverIO = {
    protocol: 'https',
    hostname: 'hub.example.com',
    port: 4444,
    path: '/wd/hub',
    logLevel: 'warn',
    baseUrl: 'https://app.example.com',
    waitforTimeout: 5000,
    waitforInterval: 500
}

// Use RunnerStart for event handling
function handleRunnerStart(payload: Options.RunnerStart) {
    console.log(`Worker ${payload.cid} started session ${payload.sessionId}`)
    console.log(`Running specs: ${payload.specs.join(', ')}`)
}

// Define configuration validation schema
const myOptionDefs: Options.Definition<{ timeout: number }> = {
    timeout: {
        type: 'number',
        default: 5000,
        required: false
    }
}

Related Pages

Principle:Webdriverio_Webdriverio_Configuration_Management
Implementation:Webdriverio_Webdriverio_Capabilities_Types - Capabilities consumed by configuration
Implementation:Webdriverio_Webdriverio_Services_Types - Service types referenced by Testrunner
Implementation:Webdriverio_Webdriverio_Config_Constants - Default values for these option types
Implementation:Webdriverio_Webdriverio_Config_Utils - Validation utilities using Definition<T>

Page Connections

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

Principle

Implementation

Heuristic

Environment