Implementation:Webdriverio Webdriverio CommandFactory

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

Overview

The CommandFactory is the default export function that generates protocol command functions from WebDriver endpoint metadata, handling parameter validation, URL variable substitution, deprecation warnings, and session abort management.

Description

This module exports a factory function that accepts an HTTP method, endpoint URI template, command endpoint metadata, and an optional double-encoding flag, then returns an async protocolCommand function bound to the WebDriver client. When invoked, the generated command function: (1) extracts optional CommandRuntimeOptions from the arguments, (2) throws an error for Bidi-only commands if no Bidi session exists, (3) validates parameter count and types against the command definition, (4) substitutes URL path variables (e.g., :sessionId), (5) applies sensitive data masking via the mask() utility, (6) creates an abort signal for session deletion management via the internal manageSessionAbortions() function, (7) constructs and dispatches the HTTP request through the environment's Request class, and (8) handles the response including logging, Bidi socket cleanup on deleteSession, and driver process termination.

The internal manageSessionAbortions() function maintains a per-session map of AbortController instances, ensuring all in-flight requests are aborted when a deleteSession command completes, and subsequent commands on a deleted session are rejected immediately.

Usage

Use this factory when building protocol command prototypes for a WebDriver client. It is called by getPrototype() in the utils module for every command defined in the protocol specifications.

Code Reference

Source Location

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

Signature

export default function (
    method: string,
    endpointUri: string,
    commandInfo: CommandEndpoint,
    doubleEncodeVariables?: boolean
): (this: BaseClient, ...args: unknown[]) => Promise<WebDriverResponse | BidiResponses | void>

// Internal helper
function manageSessionAbortions(this: BaseClient): {
    isAborted: boolean;
    abortSignal?: AbortSignal;
    cleanup: () => void;
}

Import

import command from './command.js'

I/O Contract

Inputs

Name	Type	Required	Description
method	`string`	Yes	HTTP method (e.g., `'GET'`, `'POST'`, `'DELETE'`).
endpointUri	`string`	Yes	URL template with path variables (e.g., `'/session/:sessionId/url'`).
commandInfo	`CommandEndpoint`	Yes	Protocol command metadata including command name, parameters, variables, ref URL, and deprecation notice.
doubleEncodeVariables	`boolean`	No	Whether to double-encode URL path variables (used for Selenium Standalone compatibility). Defaults to `false`.

Outputs

Name	Type	Description
protocolCommand	BidiResponses \| void>	A bound async function that, when called on a `BaseClient`, executes the protocol command with full validation, masking, abort management, and retry logic.

Usage Examples

import command from './command.js'
import type { CommandEndpoint } from '@wdio/protocols'

// Create a protocol command for navigateTo
const commandInfo: CommandEndpoint = {
    command: 'navigateTo',
    ref: 'https://w3c.github.io/webdriver/#navigate-to',
    parameters: [{ name: 'url', type: 'string', required: true, description: 'URL to navigate to' }],
    variables: []
};

const navigateTo = command('POST', '/session/:sessionId/url', commandInfo);

// The returned function is bound to a WebDriver client instance
// and called internally like:
// await client.navigateTo('https://example.com');

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment