Implementation:Webdriverio Webdriverio WebDriver Utils

Knowledge Sources	Webdriverio_Webdriverio
Domains	WebDriver, Session_Management
Last Updated	2026-02-12 00:00 GMT

Overview

The WebDriver_Utils module provides essential utility functions for WebDriver session initialization, capability validation, protocol prototype construction, response checking, Bidi setup, and sensitive data masking.

Description

This module contains 10 exported functions that form the backbone of WebDriver session management. startWebDriverSession() initiates a browser session by normalizing W3C/JSONWP capabilities, automatically opting into WebDriver Bidi for non-Safari browsers, resolving firstMatch/alwaysMatch conflicts, and making the POST /session request. validateCapabilities() checks for common misconfigurations like Chrome incognito mode and mixed protocol capabilities. isSuccessfulResponse() determines whether a WebDriver HTTP response indicates success by inspecting status codes and body structures, handling edge cases for lazy-loaded elements and JSONWP compatibility. getPrototype() builds the protocol command prototype by deep-merging the appropriate protocol definitions (WebDriver, Appium, Chromium, Gecko, SauceLabs, Selenium, Bidi) based on session flags and mapping each endpoint to a command function via the command factory. getEnvironmentVars() converts session flags into a property descriptor map for the monad, including a dynamic isBidi getter. setupDirectConnect() mutates client options based on Appium direct connect capabilities. getSessionError() produces human-readable error messages for common session creation failures. initiateBidi() creates and connects a BidiHandler instance, attaching Bidi command methods to the client prototype. parseBidiMessage() parses incoming Bidi events and emits them on the EventEmitter. mask() applies sensitive data masking to the text parameter in commands when the mask runtime option is set.

Usage

Use these utilities when creating, configuring, or managing WebDriver sessions. They are called by the WebDriver monad initialization code and the command factory.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/webdriver/src/utils.ts

Signature

export async function startWebDriverSession(
    params: RemoteConfig
): Promise<{ sessionId: string; capabilities: WebdriverIO.Capabilities }>

export function validateCapabilities(capabilities: WebdriverIO.Capabilities): void

export function isSuccessfulResponse(statusCode?: number, body?: unknown): boolean

export function getPrototype(flags: Partial<SessionFlags>): Record<string, PropertyDescriptor>

export function getEnvironmentVars(flags: Partial<SessionFlags>): PropertyDescriptorMap

export function setupDirectConnect(client: Client): void

export const getSessionError: (
    err: JSONWPCommandError,
    params?: Partial<Options.WebDriver>
) => string

export function initiateBidi(
    socketUrl: string,
    strictSSL?: boolean,
    userHeaders?: Record<string, string>
): PropertyDescriptorMap

export function parseBidiMessage(this: EventEmitter, data: ArrayBuffer): void

export function mask(
    commandInfo: CommandEndpoint,
    options: CommandRuntimeOptions,
    body: Record<string, unknown>,
    args: unknown[]
): { maskedBody: Record<string, unknown>; maskedArgs: unknown[]; isMasked: boolean }

Import

import {
    startWebDriverSession,
    validateCapabilities,
    isSuccessfulResponse,
    getPrototype,
    getEnvironmentVars,
    setupDirectConnect,
    getSessionError,
    initiateBidi,
    parseBidiMessage,
    mask
} from './utils.js'

I/O Contract

Inputs

Name	Type	Required	Description
params (startWebDriverSession)	`RemoteConfig`	Yes	Full WebDriver configuration including capabilities and connection options.
capabilities (validateCapabilities)	`WebdriverIO.Capabilities`	Yes	Capabilities object to validate for W3C compliance.
statusCode, body (isSuccessfulResponse)	`number?, unknown?`	No	HTTP status code and response body to check.
flags (getPrototype, getEnvironmentVars)	`Partial<SessionFlags>`	Yes	Session flags (isW3C, isChromium, isFirefox, isMobile, etc.).
client (setupDirectConnect)	`Client`	Yes	WebDriver client instance whose options may be mutated.
err, params (getSessionError)	`JSONWPCommandError, Partial<Options.WebDriver>?`	Yes	Error from session creation and optional connection params.
socketUrl, strictSSL, userHeaders (initiateBidi)	`string, boolean?, Record?`	Yes (socketUrl)	WebSocket URL, SSL verification flag, and optional custom headers.
commandInfo, options, body, args (mask)	`CommandEndpoint, CommandRuntimeOptions, Record, unknown[]`	Yes	Command metadata, runtime options, request body, and arguments.

Outputs

Name	Type	Description
startWebDriverSession	`Promise<{ sessionId, capabilities }>`	Session ID and resolved capabilities from the browser.
validateCapabilities	`void`	Throws on invalid capabilities; returns nothing on success.
isSuccessfulResponse	`boolean`	Whether the response indicates a successful command execution.
getPrototype	`Record<string, PropertyDescriptor>`	Protocol command prototype with all applicable commands.
getEnvironmentVars	`PropertyDescriptorMap`	Property descriptors for session flags to attach to the client monad.
initiateBidi	`PropertyDescriptorMap`	Property descriptors for Bidi handler and command methods.
getSessionError	`string`	Human-readable error message for session creation failures.
mask	`{ maskedBody, maskedArgs, isMasked }`	Masked body and arguments with a flag indicating if masking was applied.

Usage Examples

import { startWebDriverSession, isSuccessfulResponse, getPrototype, initiateBidi } from './utils.js'

// Start a new WebDriver session
const { sessionId, capabilities } = await startWebDriverSession({
    protocol: 'http',
    hostname: 'localhost',
    port: 4444,
    path: '/',
    capabilities: { browserName: 'chrome' }
});

// Check if a response is successful
const isSuccess = isSuccessfulResponse(200, { value: { title: 'Example' } });
// isSuccess: true

// Build the protocol prototype
const prototype = getPrototype({
    isW3C: true,
    isChromium: true,
    isMobile: false
});

// Initialize Bidi connection
const bidiProps = initiateBidi('ws://127.0.0.1:9222/session/abc/se/bidi', true);

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment