Implementation:Webdriverio Webdriverio WebDriverRequest Class

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

Overview

The WebDriverRequest abstract class provides the core HTTP request infrastructure for WebDriver protocol commands, with URL construction, authentication, timeout management, response parsing, and exponential backoff retry logic.

Description

WebDriverRequest is the abstract base class that all platform-specific request implementations must extend, providing a single abstract method fetch(url, opts). The constructor accepts the HTTP method, endpoint template, optional body, optional abort signal, a hub command flag, and event handlers for observability.

The makeRequest() method is the public entry point that creates request options and delegates to _request(). The createOptions() method builds the full URL from connection options (protocol, hostname, port, path), substitutes :sessionId in the endpoint, sets up headers (Content-Type, Connection, Accept, User-Agent with package version), computes Content-Length for bodies, adds Basic authentication for session creation, applies query parameters, and runs the user's transformRequest hook. It creates a composite AbortSignal from both the connection timeout and the optional session abort signal.

The protected _request() method implements the retry loop with exponential backoff (minimum 500ms, maximum 10s, using 250 * 2^retryCount). It handles: retryable errors by checking error codes and status codes against configurable lists, stale element reference errors (no retry), specific exclusion patterns like "detached shadow root" and "move target out of bounds", and invalid session ID errors (stop retrying). It emits performance, response, retry, and log events throughout the request lifecycle. The _libRequest() helper wraps the abstract fetch() call with error handling, parsing JSON responses and wrapping failures in WebDriverRequestError.

Usage

Use WebDriverRequest as the base class for platform-specific HTTP implementations (e.g., FetchRequest for Node.js). It is instantiated by the command factory for each protocol command execution.

Code Reference

Source Location

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

Signature

export abstract class WebDriverRequest {
    protected abstract fetch(url: URL, opts: RequestInit): Promise<Response>

    body?: Record<string, unknown>
    method: string
    endpoint: string
    isHubCommand: boolean
    requiresSessionId: boolean
    eventHandler: RequestEventHandler
    abortSignal?: AbortSignal

    constructor(
        method: string,
        endpoint: string,
        body?: Record<string, unknown>,
        abortSignal?: AbortSignal,
        isHubCommand?: boolean,
        eventHandler?: RequestEventHandler
    )

    async makeRequest(options: RequestOptions, sessionId?: string): Promise<WebDriverResponse>

    async createOptions(
        options: RequestOptions,
        sessionId?: string,
        isBrowser?: boolean
    ): Promise<{ url: URL; requestOptions: RequestInit }>

    protected async _libRequest(url: URL, opts: RequestInit): Promise<Options.RequestLibResponse>

    protected async _request(
        url: URL,
        fullRequestOptions: RequestInit,
        transformResponse?: (response: RequestLibResponse, requestOptions: RequestInit) => RequestLibResponse,
        totalRetryCount?: number,
        retryCount?: number
    ): Promise<WebDriverResponse>
}

Import

import { WebDriverRequest } from './request/request.js'

I/O Contract

Inputs

Name	Type	Required	Description
method	`string`	Yes	HTTP method (GET, POST, DELETE, etc.).
endpoint	`string`	Yes	URL endpoint template (e.g., `/session/:sessionId/url`).
body	`Record<string, unknown>`	No	Request body for POST/PUT commands.
abortSignal	`AbortSignal`	No	Signal to abort the request (used for session deletion management).
isHubCommand	`boolean`	No	Whether this is a Selenium Hub command (affects URL construction and error handling).
eventHandler	`RequestEventHandler`	No	Callbacks for request lifecycle events (onRequest, onResponse, onRetry, onPerformance, onLogData).
options (makeRequest)	`RequestOptions`	Yes	Full connection options including protocol, hostname, port, path, timeouts, and retry counts.
sessionId	`string`	No	Session ID to substitute in the endpoint URL.

Outputs

Name	Type	Description
makeRequest()	`Promise<WebDriverResponse>`	The parsed response body from the WebDriver server.
createOptions()	`Promise<{ url, requestOptions }>`	The constructed URL and fully configured request options.
_request()	`Promise<WebDriverResponse>`	The final response after retry logic and error handling.

Usage Examples

import { WebDriverRequest } from './request/request.js'

// Concrete implementation (simplified)
class MyRequest extends WebDriverRequest {
    async fetch(url: URL, opts: RequestInit): Promise<Response> {
        return globalThis.fetch(url, opts);
    }
}

// Create a request for navigating to a URL
const request = new MyRequest('POST', '/session/:sessionId/url', {
    url: 'https://example.com'
}, undefined, false, {
    onPerformance: (data) => console.log(`Request took ${data.durationMillisecond}ms`),
    onRetry: (data) => console.log(`Retry ${data.retryCount}`)
});

// Execute the request with options
const result = await request.makeRequest({
    protocol: 'http',
    hostname: 'localhost',
    port: 4444,
    path: '/',
    connectionRetryTimeout: 120000,
    connectionRetryCount: 3
}, 'session-abc-123');

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment