Implementation:Webdriverio Webdriverio Bidi NodeConnection

Knowledge Sources	Webdriverio_Webdriverio
Domains	Bidi_Protocol, Network
Last Updated	2026-02-12 00:00 GMT

Overview

The Bidi_NodeConnection module provides Node.js-specific WebSocket connection establishment for WebDriver Bidi, with DNS resolution to generate IPv4/IPv6 candidate URLs and proxy support.

Description

This module exports three functions that handle the complexities of establishing a reliable WebSocket connection in Node.js environments. createBidiConnection() is the top-level entry point that first resolves candidate URLs via listWebsocketCandidateUrls(), then attempts connections with connectWebsocket(). listWebsocketCandidateUrls() performs DNS lookup on the hostname (if it is not already an IP address) and generates alternate URLs using resolved IPv4 and IPv6 addresses, addressing issues where hostnames resolve to multiple addresses. connectWebsocket() creates WebSocket instances for all candidate URLs simultaneously, racing them with a 10-second timeout. It supports HTTP proxy configuration via environment variables (PROXY_URL and NO_PROXY) using HttpsProxyAgent. The internal firstResolved() helper implements a cascading race pattern: if the first WebSocket to resolve shows a failed connection, it recursively races the remaining candidates until one succeeds or all fail, collecting error messages along the way. All non-winning sockets are terminated after a winner is found.

Usage

Use this module as the Node.js implementation of createBidiConnection() in the environment adapter. It is called by BidiCore.connect() through the environment abstraction layer.

Code Reference

Source Location

Repository: Webdriverio_Webdriverio
File: packages/webdriver/src/node/bidi.ts

Signature

export async function createBidiConnection(
    webSocketUrl: string,
    options?: ClientOptions
): Promise<WebSocket | undefined>

export async function listWebsocketCandidateUrls(
    webSocketUrl: string
): Promise<string[]>

export async function connectWebsocket(
    candidateUrls: string[],
    options?: ClientOptions
): Promise<WebSocket | undefined>

Import

import { createBidiConnection, listWebsocketCandidateUrls, connectWebsocket } from './node/bidi.js'

I/O Contract

Inputs

Name	Type	Required	Description
webSocketUrl	`string`	Yes	The WebSocket URL to connect to (e.g., `ws://localhost:9222/session/.../se/bidi`).
options	`ClientOptions`	No	Optional WebSocket client options (e.g., `rejectUnauthorized`, custom headers).
candidateUrls (connectWebsocket)	`string[]`	Yes	List of candidate WebSocket URLs to attempt connections to simultaneously.

Outputs

Name	Type	Description
createBidiConnection	undefined>	A connected WebSocket instance, or `undefined` if all connection attempts failed.
listWebsocketCandidateUrls	`Promise<string[]>`	List of candidate URLs: the original URL plus any DNS-resolved IP variants.
connectWebsocket	undefined>	The first successfully connected WebSocket, or `undefined` on failure.

Usage Examples

import { createBidiConnection, listWebsocketCandidateUrls } from './node/bidi.js'

// Establish a Bidi WebSocket connection (handles DNS resolution internally)
const ws = await createBidiConnection('ws://localhost:9222/session/abc123/se/bidi', {
    rejectUnauthorized: false
});

if (ws) {
    ws.on('message', (data) => {
        console.log('Received:', data.toString());
    });
}

// List candidate URLs for a hostname-based WebSocket URL
const candidates = await listWebsocketCandidateUrls('ws://myhost:9222/session/abc/se/bidi');
// candidates: [
//   'ws://myhost:9222/session/abc/se/bidi',
//   'ws://127.0.0.1:9222/session/abc/se/bidi',
//   'ws://[::1]:9222/session/abc/se/bidi'
// ]

// For IP-based URLs, only the original is returned
const ipCandidates = await listWebsocketCandidateUrls('ws://127.0.0.1:9222/session/abc/se/bidi');
// ipCandidates: ['ws://127.0.0.1:9222/session/abc/se/bidi']

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment