Implementation:Webdriverio Webdriverio Utils
| Knowledge Sources | |
|---|---|
| Domains | Utilities, Core_Helpers |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Provides general-purpose utility functions for path handling, parameter validation, browser detection, command logging, module imports, and file logging configuration.
Description
The Utils module is a collection of helper functions used throughout the WebdriverIO ecosystem. isAbsolute checks if a path string is absolute (supporting both POSIX and Windows formats). overwriteElementCommands applies user-defined command overrides stored in __elementOverrides__ to element property descriptors. commandCallStructure formats command invocations into readable log strings, replacing base64 screenshots, functions, and objects with placeholder tokens. transformCommandLogResult sanitizes WebDriver response bodies for logging, detecting base64 screenshots and minified scripts. isValidParameter and getArgumentType validate command arguments against expected type specifications. userImport and safeImport provide user-friendly module import with error messages and support for both ESM and CJS packages. isAppiumCapability detects Appium-specific capabilities, definesRemoteDriver determines if connection options point to a remote driver, and isChrome/isSafari/isFirefox/isEdge identify browsers by name. getBrowserObject traverses the element scope chain to find the root browser object. sleep provides a promise-based delay, and enableFileLogging configures file-based log output.
Usage
Use these utilities throughout WebdriverIO packages for common operations. Browser detection functions are used by the driver manager to select the correct driver. Import helpers are used by the service and plugin initialization system. Logging utilities are used by the protocol layer and reporters. Path and parameter utilities support configuration validation.
Code Reference
Source Location
- Repository: Webdriverio_Webdriverio
- File: packages/wdio-utils/src/utils.ts
- Lines: 1-413
Signature
export function isAbsolute(p: string): boolean
export function overwriteElementCommands(propertiesObject: {
'__elementOverrides__'?: { value: Record<string, unknown> };
[key: string]: unknown;
}): void
export function commandCallStructure(commandName: string, args: unknown[], unfurl?: boolean): string
export function transformCommandLogResult(result: unknown): unknown
export function isValidParameter(arg: unknown, expectedType: string): boolean
export function getArgumentType(arg: unknown): string
export async function userImport<T>(moduleName: string, namedImport?: string): Promise<T>
export async function safeImport(name: string): Promise<Services.ServicePlugin | null>
export function isFunctionAsync(fn: Function): boolean
export function isBase64(str: string): boolean
export const sleep: (ms?: number) => Promise<void>
export function isAppiumCapability(caps: WebdriverIO.Capabilities): boolean
export function definesRemoteDriver(options: Pick<Options.WebDriver, 'user' | 'key' | 'protocol' | 'hostname' | 'port' | 'path'>): boolean
export function isChrome(browserName?: string): boolean
export function isSafari(browserName?: string): boolean
export function isFirefox(browserName?: string): boolean
export function isEdge(browserName?: string): boolean
export function getBrowserObject(elem: WebdriverIO.Element | WebdriverIO.Browser | WebdriverIO.ElementArray): WebdriverIO.Browser
export async function enableFileLogging(outputDir?: string): Promise<void>
Import
import { isAppiumCapability, sleep, isChrome } from '@wdio/utils'
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| p | string | Yes (isAbsolute) | Path string to check for absolute format. |
| propertiesObject | object | Yes (overwriteElementCommands) | Property descriptors with optional __elementOverrides__ containing user-defined command overrides. |
| commandName | string | Yes (commandCallStructure) | Name of the command for log formatting. |
| args | unknown[] | Yes (commandCallStructure) | Command arguments to format into a readable string. |
| result | unknown | Yes (transformCommandLogResult) | WebDriver response body to sanitize for logging. |
| arg | unknown | Yes (isValidParameter) | Value to validate against the expected type. |
| expectedType | string | Yes (isValidParameter) | string)"). |
| moduleName | string | Yes (userImport/safeImport) | NPM package name or path to import. |
| caps | WebdriverIO.Capabilities | Yes (isAppiumCapability) | Capabilities object to check for Appium-specific properties. |
| options | Options.WebDriver (partial) | Yes (definesRemoteDriver) | Connection options with protocol, hostname, port, path, user, key. |
| browserName | string | No (isChrome etc.) | Browser name string to match against known browser name variants. |
| elem | WebdriverIO.Element or Browser | Yes (getBrowserObject) | Element or browser to traverse upward from. |
| outputDir | string | No (enableFileLogging) | Directory for log file output. |
Outputs
| Name | Type | Description |
|---|---|---|
| isAbsolute | boolean | True if the path is absolute (starts with / or a Windows drive letter). |
| commandCallStructure | string | Formatted string like "click(\"#btn\")" with functions, base64, and objects replaced by placeholders. |
| transformCommandLogResult | unknown | Sanitized result with screenshots replaced by "<Screenshot[base64]>" and scripts summarized. |
| isValidParameter | boolean | True if the argument matches the expected type specification. |
| userImport | Promise<T> | The resolved module export, or throws with a user-friendly install message. |
| safeImport | Promise<ServicePlugin or null> | The loaded service plugin, null if not found, or throws if found but failed to load. |
| isAppiumCapability | boolean | True if Appium-specific capabilities are present. |
| definesRemoteDriver | boolean | True if connection options differ from defaults or user/key credentials are set. |
| isChrome/isSafari/isFirefox/isEdge | boolean | True if the browser name matches the respective browser's known name variants. |
| getBrowserObject | WebdriverIO.Browser | The root browser object from the element scope chain. |
| sleep | Promise<void> | Resolves after the specified milliseconds. |
Usage Examples
import {
isAppiumCapability, sleep, isChrome, definesRemoteDriver,
commandCallStructure, getBrowserObject, userImport
} from '@wdio/utils'
// Check if capabilities indicate an Appium session
const caps = { 'appium:automationName': 'UiAutomator2', platformName: 'Android' }
console.log(isAppiumCapability(caps)) // true
// Detect browser type
console.log(isChrome('googlechrome')) // true
console.log(isChrome('firefox')) // false
// Check if remote driver is configured
const needsDriverSetup = !definesRemoteDriver({
protocol: 'http',
hostname: 'localhost',
path: '/'
})
// Format command for logging
const logStr = commandCallStructure('click', ['#submit-btn'])
console.log(logStr) // 'click("#submit-btn")'
// Traverse to browser from element
const browser = getBrowserObject(element)
// Import a module with user-friendly error
const myPlugin = await userImport('wdio-my-plugin')
// Sleep for 1 second
await sleep(1000)