Principle:Webdriverio Webdriverio Test Configuration Parsing

Overview

A mechanism for loading, validating, and merging test suite configuration from file-based definitions and CLI overrides.

Metadata

Field	Value
Page Type	Principle
Repository	webdriverio/webdriverio
Knowledge Sources	Repo (GitHub), Doc (Configuration File)
Domains	Testing, Configuration
Related Implementations	Implementation: ConfigParser_Class

Description

Test Configuration Parsing is the process of reading a configuration file (typically wdio.conf.ts or wdio.conf.js), validating it against expected schemas, merging CLI argument overrides, resolving spec file glob patterns, and producing a finalized configuration object. This decouples test definition from execution parameterization, enabling the same tests to run against different environments, browsers, and settings without code changes.

The configuration file must export a named config object (either via export const config = { ... } in ESM or exports.config = { ... } in CommonJS). This object conforms to the WebdriverIO.Config TypeScript interface and defines all runtime behavior: which spec files to run, what browser capabilities to target, which framework adapter to use, which reporters and services to load, and all hook functions for test lifecycle events.

The parsing process produces a single, fully-resolved configuration object that the Launcher and Runner classes consume to orchestrate test execution.

Usage

Use Test Configuration Parsing when setting up a WDIO testrunner project. The configuration file defines specs, capabilities, framework, reporters, services, baseUrl, and all other runtime options. Configuration parsing happens automatically when running:

npx wdio run wdio.conf.ts

A minimal configuration file looks like:

export const config: WebdriverIO.Config = {
    specs: ['./test/specs/**/*.ts'],
    capabilities: [{
        browserName: 'chrome'
    }],
    framework: 'mocha',
    reporters: ['spec'],
    services: ['chromedriver'],
    baseUrl: 'http://localhost:8080',
    logLevel: 'info',
    mochaOpts: {
        timeout: 60000
    }
}

CLI arguments override file-based settings:

npx wdio run wdio.conf.ts --spec ./test/specs/login.ts --baseUrl http://staging.example.com --logLevel debug

Theoretical Basis

Configuration parsing follows a layered merge strategy: defaults -> config file -> CLI overrides. The merge process uses specific rules for different property types:

Array properties like services, reporters, and capabilities are deduplicated using a custom deep merge strategy (via deepmerge-ts with a custom mergeArrays handler) that prevents duplicate entries while preserving object-type entries
Object properties are recursively deep-merged, with later values overriding earlier ones
Scalar properties (strings, numbers, booleans) are directly overridden by the last source in the chain
Hook arrays are concatenated, allowing both config file hooks and service hooks to coexist

The parser resolves glob patterns in spec paths using a PathService abstraction, validates that referenced plugins exist, and merges capability objects. Spec file paths specified via CLI (--spec) are resolved relative to the current working directory, while paths in the config file are resolved relative to the config file's rootDir.

The configuration schema is defined by the WebdriverIO.Config TypeScript interface, with defaults provided by the DEFAULT_CONFIGS function in @wdio/config. Key default values include:

Property	Default
`framework`	`'mocha'`
`runner`	`'local'`
`maxInstances`	`100`
`logLevel`	`'info'`
`bail`	`0` (don't bail)
`waitforTimeout`	`5000` ms
`connectionRetryTimeout`	`120000` ms
`connectionRetryCount`	`3`
`specFileRetries`	`0`

The supported file extensions for spec files are: .js, .jsx, .mjs, .mts, .es6, .ts, .tsx, .feature, .coffee, .cjs.

Implemented by: Implementation: ConfigParser_Class
Used by: Principle: Test_Execution_Orchestration
Used by: Implementation: Launcher_Class
Heuristic:Webdriverio_Webdriverio_Default_Timeout_Configuration

Page Connections

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

Principle

Implementation

Heuristic

Environment