Home > @rushstack/playwright-browser-tunnel

playwright-browser-tunnel package

Run a Playwright browser server in one environment and drive it from another environment by forwarding Playwright's WebSocket traffic through a tunnel.

Remarks

This package is intended for remote development and CI scenarios (for example: Codespaces, devcontainers, or a separate "browser host" machine) where you want tests to run in one environment but the actual browser process to run in another.

The package provides two main APIs: - PlaywrightTunnel - Run on the browser host to launch the real browser server and forward messages - tunneledBrowserConnection() - Run on the test runner to create a local endpoint that your Playwright client can connect to

Classes

Class	Description
LaunchOptionsValidator	(BETA) Validates Playwright launch options against security allowlists. Provides utilities for managing client-side allowlist configuration.
PlaywrightTunnel	(BETA) Hosts a Playwright browser server and forwards traffic over a WebSocket tunnel.

Functions

Function	Description
createTunneledBrowserAsync(browserName, launchOptions, logger, port)	(BETA) Creates a Playwright Browser instance connected via a tunneled WebSocket connection.
getNormalizedErrorString(error)	(BETA) Normalizes an error to a string for logging purposes.
isExtensionInstalledAsync()	(BETA) Helper to determine if the Playwright Local Browser Server extension is installed. This checks for the existence of a well-known file in the OS temp directory.
tunneledBrowserConnection(logger, port, playwrightVersion)	(BETA) Creates a tunneled WebSocket endpoint that a local Playwright client can connect to.

Interfaces

Interface	Description
IDisposableTunneledBrowser	(BETA) Disposable handle returned by createTunneledBrowserAsync().
IDisposableTunneledBrowserConnection	(BETA) Disposable handle returned by tunneledBrowserConnection().
IHandshake	(BETA) Handshake data exchanged during the initial WebSocket connection.
ILaunchOptionsAllowlist	(BETA) Interface for the allowlist configuration stored in the user's local file system.
ILaunchOptionsValidationResult	(BETA) Result of validating launch options against the allowlist.

Variables

Variable	Description
EXTENSION_INSTALLED_FILENAME	(BETA) The filename used to indicate that the Playwright Local Browser Server extension is installed.
LAUNCH_OPTIONS_ALLOWLIST_FILENAME	(BETA) The filename used to store the launch options allowlist. Stored in the user's home directory/.playwright-browser-tunnel folder.

Type Aliases

Type Alias	Description
BrowserName	(BETA) Allowed Playwright browser names.
IPlaywrightTunnelOptions	(BETA) Options for configuring a PlaywrightTunnel instance.
TunnelStatus	(BETA) Status values reported by PlaywrightTunnel.