Implementation:Microsoft Playwright PlaywrightConnection

Knowledge Sources	Microsoft_Playwright
Domains	Remote, WebSocket
Last Updated	2026-02-12 00:00 GMT

Overview

Concrete tool for managing a remote WebSocket connection between a Playwright client and server provided by the Playwright library.

Description

The `PlaywrightConnection` class wraps a single WebSocket connection from a remote Playwright client. It creates a `DispatcherConnection` for routing protocol messages, sets up message serialization/deserialization over the WebSocket, and manages the connection lifecycle including profiling, logging, and cleanup callbacks. A `Semaphore` is used to control concurrency of outgoing messages. The connection supports both controller mode (for debug controller) and standard mode, dispatching a `PlaywrightDispatcher` or `DebugControllerDispatcher` as the root.

Usage

Use PlaywrightConnection when establishing a remote Playwright server that accepts WebSocket connections from clients, such as when using `browserType.connect()` or the Playwright server CLI.

Code Reference

Source Location

• Repository: Microsoft_Playwright
• File: packages/playwright-core/src/remote/playwrightConnection.ts

Signature

export interface PlaywrightInitializeResult extends PlaywrightDispatcherOptions {
  dispose?(): Promise<void>;
}

export class PlaywrightConnection {
  constructor(
    semaphore: Semaphore,
    ws: WebSocket,
    controller: boolean,
    playwright: Playwright,
    initialize: () => Promise<PlaywrightInitializeResult>,
    id: string
  );
}

Import

import { PlaywrightConnection } from '../remote/playwrightConnection';

I/O Contract

Inputs

Name	Type	Required	Description
semaphore	Semaphore	Yes	Concurrency limiter for outgoing messages
ws	WebSocket	Yes	The underlying WebSocket transport
controller	boolean	Yes	Whether this is a debug controller connection
playwright	Playwright	Yes	The Playwright server instance
initialize	() => Promise<PlaywrightInitializeResult>	Yes	Callback that returns dispatcher options and optional dispose function
id	string	Yes	Unique identifier for this connection

Outputs

Name	Type	Description
(side effect)	void	Sets up bidirectional message routing over the WebSocket

Usage Examples

import { PlaywrightConnection } from '../remote/playwrightConnection';
import { Semaphore } from '../utils';

const semaphore = new Semaphore(1);
const connection = new PlaywrightConnection(
  semaphore,
  webSocket,
  false, // not a controller
  playwrightInstance,
  async () => ({ socksProxy }),
  'connection-id-1'
);

Related Pages

• Environment:Microsoft_Playwright_Node_Runtime_Environment