Implementation:Webdriverio Webdriverio Config Utils

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

Overview

Utility functions for WebdriverIO configuration validation, spec file path parsing, cloud capability detection, and the defineConfig helper for typed configuration authoring.

Description

This module provides essential utility functions for configuration processing in WebdriverIO. defineConfig creates a fully typed configuration object by merging user options with defaults, serving as the primary entry point for wdio.conf.ts authoring. validateConfig performs runtime type checking and validation against a schema defined by Options.Definition<T>, throwing errors for missing required options or type mismatches. removeLineNumbers strips line number suffixes from spec file paths (e.g., /foo:9 becomes /foo). isCucumberFeatureWithLineNumber detects whether a spec path contains Cucumber line number notation. isCloudCapability checks if capabilities contain vendor extensions for cloud providers (Sauce Labs, BrowserStack, or TestingBot). validObjectOrArray validates that a value is a non-empty object or array.

Usage

Use defineConfig() in wdio.conf.ts files to get TypeScript autocompletion and type safety for configuration objects. Use validateConfig() when building custom packages that need to validate option objects against a schema. The path utility functions are used internally during spec file resolution, particularly for Cucumber features that specify line numbers. Use isCloudCapability() when implementing logic that differs between local and cloud test execution.

Code Reference

Source Location

• Repository: Webdriverio_Webdriverio
• File: packages/wdio-config/src/utils.ts
• Lines: 1-96

Signature

export const validObjectOrArray = (
    object: object
): object is object | Array<unknown> =>
    (Array.isArray(object) && object.length > 0) ||
    (typeof object === 'object' && Object.keys(object).length > 0)

export function removeLineNumbers(filePath: string): string

export function isCucumberFeatureWithLineNumber(spec: string | string[]): boolean

export function isCloudCapability(caps: WebdriverIO.Capabilities): boolean

export const defineConfig = (
    options?: Partial<WebdriverIO.Config> | WebdriverIO.Config
): WebdriverIO.Config => ({
    ...DEFAULT_CONFIGS(),
    ...options,
})

export function validateConfig<T>(
    defaults: Options.Definition<T>,
    options: T,
    keysToKeep?: (keyof T)[]
): T

Import

import {
    defineConfig,
    validateConfig,
    removeLineNumbers,
    isCucumberFeatureWithLineNumber,
    isCloudCapability,
    validObjectOrArray
} from '@wdio/config'

I/O Contract

Function Signatures
Function	Parameters	Return Type	Throws	Description
defineConfig	options?: Partial<WebdriverIO.Config>	WebdriverIO.Config	-	Merges user options with DEFAULT_CONFIGS
validateConfig	defaults: Definition<T>, options: T, keysToKeep?: (keyof T)[]	T	Error on missing required or type mismatch	Validates options against a schema definition
removeLineNumbers	filePath: string	string	-	Strips :line or :line:col suffixes
isCucumberFeatureWithLineNumber	string[]	boolean	-	Checks if spec path has Cucumber line numbers
isCloudCapability	caps: WebdriverIO.Capabilities	boolean	-	Detects cloud provider vendor extensions
validObjectOrArray	object: object	boolean	-	Checks for non-empty object or array

validateConfig Error Conditions
Condition	Error Message	Example
Required option missing	Required option "specs" is missing	Missing a required field with no default
Type mismatch	Expected option "bail" to be type of number but was string	Passing wrong value type
Custom validation failure	Type check for option "logLevel" failed: ...	Custom validate function throws
Pattern mismatch	Option "hostname" doesn't match expected values: ...	String doesn't match required regex

Usage Examples

import { defineConfig, validateConfig, isCloudCapability } from '@wdio/config'
import type { Options } from '@wdio/types'

// Use defineConfig in wdio.conf.ts for typed configuration
export const config = defineConfig({
    specs: ['./test/specs/**/*.ts'],
    capabilities: [{
        browserName: 'chrome',
        'goog:chromeOptions': {
            args: ['--headless']
        }
    }],
    framework: 'mocha',
    reporters: ['spec'],
    services: ['chromedriver'],
    logLevel: 'info',
    bail: 0,
    baseUrl: 'https://app.example.com',
    waitforTimeout: 10000,
    mochaOpts: {
        timeout: 60000
    }
})

// Validate custom service options
interface MyServiceOptions {
    apiKey: string
    timeout: number
    verbose: boolean
}

const optionDefs: Options.Definition<MyServiceOptions> = {
    apiKey: {
        type: 'string',
        required: true
    },
    timeout: {
        type: 'number',
        default: 5000
    },
    verbose: {
        type: 'boolean',
        default: false
    }
}

const validatedOpts = validateConfig(optionDefs, {
    apiKey: 'my-secret-key',
    timeout: 10000,
    verbose: true
})

// Detect cloud vs local execution
function getTestUrl(caps: WebdriverIO.Capabilities, localUrl: string): string {
    if (isCloudCapability(caps)) {
        return 'https://staging.example.com'
    }
    return localUrl
}

// Handle Cucumber feature files with line numbers
import { removeLineNumbers, isCucumberFeatureWithLineNumber } from '@wdio/config'

const specPath = './features/login.feature:15:3'
if (isCucumberFeatureWithLineNumber(specPath)) {
    const cleanPath = removeLineNumbers(specPath)
    console.log(cleanPath) // './features/login.feature'
}

Related Pages

• Principle:Webdriverio_Webdriverio_Configuration_Management
• Implementation:Webdriverio_Webdriverio_Config_Constants - DEFAULT_CONFIGS used by defineConfig
• Implementation:Webdriverio_Webdriverio_Options_Types - Definition<T> type used by validateConfig
• Implementation:Webdriverio_Webdriverio_Capabilities_Types - Capabilities checked by isCloudCapability