Implementation:Microsoft Playwright Client WebSocket

Knowledge Sources	Microsoft_Playwright
Domains	Browser Automation, Network Communication
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for establishing WebSocket connections to remote Playwright servers and transporting protocol messages provided by the Playwright library.

Description

This module provides the connectOverWebSocket() function and two internal transport implementations for connecting a client Connection to a remote Playwright server.

The connectOverWebSocket() function accepts a parent connection and connection parameters, selects the appropriate transport (JsonPipe for Node.js with LocalUtils, WebSocket for browser environments), establishes the connection, creates a new Connection marked as remote, and wires up bidirectional message dispatch with error handling and cleanup.

The two transport implementations share a common Transport interface:

• JsonPipeTransport: Uses the LocalUtils channel's connect() method to establish a JSON pipe, providing reliable binary-safe transport with connection headers support.
• WebSocketTransport: Uses the browser's native WebSocket API for direct WebSocket connections, suitable for browser-based Playwright clients.

Usage

Use connectOverWebSocket() when connecting to a remote Playwright server. This is the transport layer used by browserType.connect() and similar remote connection methods.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/client/webSocket.ts

Signature

export async function connectOverWebSocket(
  parentConnection: Connection,
  params: channels.LocalUtilsConnectParams
): Promise<Connection>;

interface Transport {
  connect(params: channels.LocalUtilsConnectParams): Promise<HeadersArray>;
  send(message: any): Promise<void>;
  onMessage(callback: (message: object) => void): void;
  onClose(callback: (reason?: string) => void): void;
  close(): Promise<void>;
}

Import

import { connectOverWebSocket } from 'playwright-core/src/client/webSocket';

I/O Contract

Inputs

Name	Type	Required	Description
parentConnection	Connection	Yes	The existing client connection providing platform and instrumentation context
params	LocalUtilsConnectParams	Yes	Connection parameters including wsEndpoint, headers, slowMo, and timeout

Outputs

Name	Type	Description
connectOverWebSocket()	Promise<Connection>	A new remote Connection instance with bidirectional message transport established

Usage Examples

// Internal usage when connecting to a remote browser:
const remoteConnection = await connectOverWebSocket(existingConnection, {
  wsEndpoint: 'ws://localhost:3000/playwright',
  headers: [{ name: 'Authorization', value: 'Bearer token' }],
  slowMo: 100,
  timeout: 30000,
});

// The returned connection can be used to access remote Playwright objects
remoteConnection.on('close', () => {
  console.log('Remote connection closed');
});

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment