Playwright Browser Server #5424

bmiddha · 2025-10-30T19:35:54Z

Summary

Introducing Playwright Browser Server. A CLI based tool to launch a remote browser provider for Playwright.

This tool enables using headful browsers on the local machine when using Playwright with VS Code remote sessions.

Use cases:

Running Playwright tests in Codespaces / WSL / VS Code Tunnels workspaces and using local browsers on the local computer
Running Playwright MCP in VS Code when using remote workspaces

Details

This tool uses a reverse port forwarder concept to tunnel the Playwright WebSocket control messages over VS Code port forwarding.

Flow:

User has this playwright browser server tool running on the local computer
User runs a playwright test in a VS Code window connected to a Codespace
The browser fixture in the Codespace starts a server on a known port (3000). This log message is read by VS Code and it forwards this port.
The browser server tool is polling this known port to be opened.
Once a connection is established, it launches the requested browser with the launch options and sets up a forwarding between the Playwright browser and the existing open connection.
Test can now use the remote browser.

Playwright MCP can also be used through this setup in VS Code remote environments.

sequenceDiagram
    participant PT as Playwright Tests
    participant BF as Browser Fixture
    participant TS as Tunnel Server (WebSocket)
    participant HS as HTTP Server
    participant VSC as VS Code Extension
    participant BS as Browser Server
    participant LB as Local Browser

    Note over PT,LB: Context:  Enables local browser testing for remote VS Code environments (e.g., Codespaces)

    PT->>BF:  Trigger custom browser fixture
    
    par Fixture Setup
        BF->>HS: Launch localhost HTTP server
        BF->>TS: Launch WebSocket tunnel server (well-known port)
    end

    BF->>HS: browser.connect('http://localhost:<port>? browser=chromium&launchOptions={}')
    
    loop Polling
        VSC->>TS: Poll for connection (well-known port)
    end

    TS-->>VSC: WebSocket connection established
    
    BF->>VSC: Send handshake (browser type, launchOptions, Playwright version)
    
    VSC->>VSC: Install requested Playwright version
    VSC->>VSC: Install requested browser
    
    VSC->>BS: Launch browserServer via Playwright API
    BS->>LB: Start local browser instance
    
    VSC->>BS: Create WebSocket client connection
    
    VSC->>TS: Send acknowledgement (ready to go)
    
    par Setup Forwarding
        Note over BF,TS:  Fixture:  PT ↔ Tunnel Server
        Note over VSC,BS: Extension: Tunnel Server ↔ Browser Server
    end

    BF->>BF:  Flush buffered messages from test

    rect rgb(200, 230, 200)
        Note over PT,LB:  Transparent bidirectional communication established
        PT->>BF:  Playwright commands
        BF->>TS: Forward to tunnel
        TS->>VSC: Forward to extension
        VSC->>BS: Forward to browser server
        BS->>LB: Execute in local browser
        LB-->>BS: Response
        BS-->>VSC: Forward response
        VSC-->>TS: Forward to tunnel
        TS-->>BF: Forward to fixture
        BF-->>PT: Return to test
    end

    Note over PT,LB: 🎉 Profit!  Local browser available to remote tests transparently

How it was tested

Tested end-to-end with the Playwright test and fixture introduced in this change.
Tested this on pure local setup as well as on Codespaces

Tested MCP change by prompting agent mode to use Playwright MCP on Codespaces.

…m/microsoft/rushstack into bmiddha/playwright-browser-server

Copilot

Pull request overview

This PR introduces the Playwright Browser Server, a CLI-based tool that enables headful browser testing in VS Code remote environments (Codespaces, WSL, VS Code Tunnels) by tunneling Playwright WebSocket control messages over VS Code port forwarding.

Key changes:

Adds @rushstack/playwright-browser-tunnel package implementing the browser tunnel server and client connection logic
Introduces playwright-on-codespaces VS Code extension that polls for connections and launches local browsers
Implements bidirectional WebSocket forwarding between remote Playwright tests and local browser instances

Reviewed changes

Copilot reviewed 32 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts	Core tunnel implementation handling connection polling, browser server setup, and WebSocket forwarding
apps/playwright-browser-tunnel/src/tunneledBrowserConnection.ts	Client-side tunnel connection logic with handshake protocol and message buffering
apps/playwright-browser-tunnel/tests/testFixture.ts	Playwright test fixture that integrates the tunneled browser connection
vscode-extensions/playwright-on-codespaces-vscode-extension/src/extension.ts	VS Code extension that manages tunnel lifecycle with status bar UI and command palette integration
apps/playwright-browser-tunnel/package.json	Package configuration for the browser tunnel tool
rush.json	Registers new projects in Rush monorepo
common/config/rush/*-approved-packages.json	Approves Playwright dependencies for use in the monorepo

Files not reviewed (1)

common/config/subspaces/default/pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

vscode-extensions/playwright-on-codespaces-vscode-extension/src/extension.ts:1

Corrected spelling of 'Exension' to 'Extension'.

vscode-extensions/playwright-on-codespaces-vscode-extension/LICENSE

Copilot · 2025-12-18T15:32:26Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+
+            this.status = 'browser-server-running';
+
+            // send ack so that the counterpart also knows to start forwarding messages


The hardcoded 2-second sleep delay is unexplained and appears to be a workaround. Consider documenting why this delay is necessary or investigating if it can be replaced with a more deterministic synchronization mechanism.

Suggested change

// send ack so that the counterpart also knows to start forwarding messages

// Send ack so that the counterpart also knows to start forwarding messages.

// NOTE: The 2-second delay is an intentional workaround. In the current

// protocol, the remote tunnel endpoint does not expose an explicit "ready"

// signal for when it has finished initializing its own forwarding logic

// after receiving the initial handshake. Empirically, introducing this

// delay avoids races where early messages could be dropped or mishandled

// if they arrive before the remote side is fully ready.

//

// A future improvement would be to replace this delay with a deterministic

// synchronization mechanism (e.g. an explicit "ready" message or event)

// instead of relying on a fixed timeout.

Why is this sleep here?

apps/playwright-browser-tunnel/src/tunneledBrowserConnection.ts

…CENSE Co-authored-by: Copilot <[email protected]>

Co-authored-by: Copilot <[email protected]>

…ightTunnel

dmichon-msft · 2025-12-18T20:50:41Z

apps/playwright-browser-tunnel/src/index.ts

+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+export * from './PlaywrightBrowserTunnel';


Let's get out of the habit of using export * and prefer explicitly enumerating the exports that comprise the public API surface

"no-restricted-syntax": [ "error", { "selector": "ExportAllDeclaration", "message": "Use explicit named exports instead of `export * from '...'`." } ]

dmichon-msft · 2025-12-18T20:55:52Z

vscode-extensions/playwright-on-codespaces-vscode-extension/webpack.config.js

+  // `ws` module depends on `bufferutil` and `utf-8-validate`
+  Object.assign(config.resolve.fallback, {
+    bufferutil: require.resolve('bufferutil/'),
+    'utf-8-validate': require.resolve('utf-8-validate/')
+  });


Are these part of node? If so we shouldn't need to deal with the fallback stuff, we should just be able to tell the bundler that the target is node.

dmichon-msft · 2025-12-18T21:00:09Z

apps/playwright-browser-tunnel/tests/testFixture.ts

+      await using tunnel = await tunneledBrowser(browserName, {
+        channel,
+        headless,
+        ...launchOptions
+      });


Is it safe to destruct this object upon this function returning? I'm not sufficiently familiar with how the Playwright test fixtures work.

I believe the await use() line right after this resolve after the test is done. So yes, the function will return after the test is completed.
@TheLarkInn can you confirm this behavior with a debugger.

dmichon-msft · 2025-12-18T21:00:58Z

apps/playwright-browser-tunnel/tests/demo.spec.ts

+import { expect } from '@playwright/test';
+
+test('woohoo!', async ({ page }) => {
+  await page.goto('https://playwright.dev/');


We should ideally have the demo test work even if you don't have internet and are just remoting into a local container.

dmichon-msft · 2025-12-18T21:01:25Z

apps/playwright-browser-tunnel/src/utilities.ts

+  // Read file from os.tempdir() + '/.playwright-codespaces-extension-installed'
+  const tempDir: string = (await import('node:os')).tmpdir();
+
+  const extensionInstalledFilePath: string = `${tempDir}/.playwright-codespaces-extension-installed.txt`;


Externalize the name of the file into a constant.

dmichon-msft · 2025-12-18T22:06:05Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+    this._mode = mode;
+    this._terminal = terminal;
+    this._onStatusChange = onStatusChange;
+    this._tmpPath = tmpPath;


Seems like tmpPath should be better understood as playwrightInstallPath or similar? Its purpose seems to be a folder for installing versions of Playwright, so it would be useful for it to be a configuration setting and be constant.

dmichon-msft · 2025-12-18T22:10:22Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+    ws1.on('close', () => {
+      if (ws2.readyState === WebSocket.OPEN) {
+        ws2.close();
+      }
+    });
+    ws2.on('close', () => {
+      if (ws1.readyState === WebSocket.OPEN) {
+        ws1.close();
+      }
+    });


These should be using once since you can't close a socket twice.

dmichon-msft · 2025-12-18T22:11:00Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+      handshake = undefined;
+    });
+
+    ws.onerror = (error) => {


Is this different than on('error', ...)? Weirdly inconsistent.

dmichon-msft · 2025-12-18T22:11:32Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+    };
+
+    return new Promise<WebSocket>((resolve, reject) => {
+      ws.onmessage = async (event) => {


Uhh... weirdly inconsistent message handling registration

dmichon-msft · 2025-12-18T22:12:23Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+
+            this.status = 'browser-server-running';
+
+            // send ack so that the counterpart also knows to start forwarding messages


Why is this sleep here?

TheLarkInn · 2025-12-19T01:01:22Z

vscode-extensions/playwright-on-codespaces-vscode-extension/assets/extension-icon.png

Come up with an actual icon for this extension. This was just a placeholder.

iclanton · 2025-12-18T22:44:34Z

apps/playwright-browser-tunnel/src/index.ts

+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+export * from './PlaywrightBrowserTunnel';


"no-restricted-syntax": [ "error", { "selector": "ExportAllDeclaration", "message": "Use explicit named exports instead of `export * from '...'`." } ]

iclanton · 2025-12-18T22:46:21Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+
+/**
+ * Allowed Playwright browser names.
+ * @alpha


I'm pretty sure the TSDoc configuration in the rushstack repo doesn't define the @alpha tag. Use @beta instead.

iclanton · 2025-12-18T22:47:26Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+ * Allowed Playwright browser names.
+ * @alpha
+ */
+export type BrowserNames = 'chromium' | 'firefox' | 'webkit';


Suggested change

export type BrowserNames = 'chromium' | 'firefox' | 'webkit';

export type BrowserName = 'chromium' | 'firefox' | 'webkit';

iclanton · 2025-12-18T22:47:54Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+  playwrightVersion: semver.SemVer;
+}
+
+type ITunnelMode = 'poll-connection' | 'wait-for-incoming-connection';


Suggested change

type ITunnelMode = 'poll-connection' | 'wait-for-incoming-connection';

type TunnelMode = 'poll-connection' | 'wait-for-incoming-connection';

This isn't an interface.

iclanton · 2025-12-18T22:48:34Z

apps/playwright-browser-tunnel/src/PlaywrightBrowserTunnel.ts

+export type IPlaywrightTunnelOptions = {
+  terminal: ITerminal;
+  onStatusChange: (status: TunnelStatus) => void;
+  tmpPath: string;


Suggested change

tmpPath: string;

tempPath: string;

iclanton · 2025-12-19T01:23:23Z

vscode-extensions/playwright-on-codespaces-vscode-extension/package.json

+  "displayName": "Playwright on Codespaces",
+  "description": "VS Code extension to enable Playwright testing in GitHub Codespaces.",
+  "homepage": "https://github.com/microsoft/rushstack/tree/main/vscode-extensions/playwright-on-codespaces-vscode-extension",
+  "icon": "assets/extension-icon.png",


Can you include the original vector version of this icon (either SVG or Illustrator file) as well?

iclanton · 2025-12-19T01:24:05Z

vscode-extensions/playwright-on-codespaces-vscode-extension/webpack.config.js

+    entry: {
+      extension: './lib/extension.js'
+    },
+    outputPath: path.resolve(__dirname, 'dist', 'vsix', 'unpacked')


Suggested change

outputPath: path.resolve(__dirname, 'dist', 'vsix', 'unpacked')

outputPath: `${__dirname}/dist/vsix/unpacked`

iclanton · 2025-12-19T01:26:10Z

vscode-extensions/playwright-on-codespaces-vscode-extension/src/extension.ts

+  let tunnel: PlaywrightTunnel | undefined;
+
+  function getTmpPath(): string {
+    return path.join(os.tmpdir(), 'playwright-browser-tunnel');


Suggested change

return path.join(os.tmpdir(), 'playwright-browser-tunnel');

return `${os.tmpdir()}/playwright-browser-tunnel`;

Should the temp folder path be configurable?

iclanton · 2025-12-19T01:26:50Z

vscode-extensions/playwright-on-codespaces-vscode-extension/src/extension.ts

+    );
+  }
+
+  async function handleStartTunnel(): Promise<void> {


Suggested change

async function handleStartTunnel(): Promise<void> {

async function handleStartTunnelAsync(): Promise<void> {

iclanton · 2025-12-19T01:27:12Z

vscode-extensions/playwright-on-codespaces-vscode-extension/src/extension.ts

+    }
+  }
+
+  async function handleStopTunnel(): Promise<void> {


Suggested change

async function handleStopTunnel(): Promise<void> {

async function handleStopTunnelAsync(): Promise<void> {

github-project-automation bot added this to Bug Triage Oct 30, 2025

github-project-automation bot moved this to Needs triage in Bug Triage Oct 30, 2025

playwright browser server

7956637

bmiddha force-pushed the bmiddha/playwright-browser-server branch from 4e78a35 to 7956637 Compare October 30, 2025 19:42

bmiddha and others added 14 commits October 30, 2025 13:23

fixup server listening log message

d0d71c2

Implement playwright-on-codespaces vscode extension and impl

3325d49

DROP: rush update

de6a58f

fix wsEndpoint

234d090

revert some browser options

46f7c0b

remove check about remote

9aef4a1

vscode status bar icon

8528353

demo: disable loading bundled extension

92fd7dc

Actually use bufferutils and utf-8-validate in bundled websocket code

e7a38d5

update webpack config comment

3b85d15

auto start the tunnel on activation

646b76b

Add todos and update version

a186ab1

Merge branch 'bmiddha/playwright-browser-server' of https://github.co…

9db3c84

…m/microsoft/rushstack into bmiddha/playwright-browser-server

Refactoring workspaceCommand fn and minor changes

93a0594

TheLarkInn marked this pull request as ready for review December 18, 2025 01:13

TheLarkInn requested review from D4N14L, apostolisms, dmichon-msft, iclanton, octogonz and patmill as code owners December 18, 2025 01:13

TheLarkInn and others added 3 commits December 17, 2025 17:14

Merge branch 'main' into bmiddha/playwright-browser-server

4ff682a

DROP: rush update

cce4517

repo-toolbox readme

29a8e03

TheLarkInn requested a review from Copilot December 18, 2025 15:30

Copilot AI reviewed Dec 18, 2025

View reviewed changes

TheLarkInn and others added 6 commits December 18, 2025 10:06

add README's, api-extractor and removed unused CLI and start commands

48408b3

Update vscode-extensions/playwright-on-codespaces-vscode-extension/LI…

1d849b3

…CENSE Co-authored-by: Copilot <[email protected]>

Update apps/playwright-browser-tunnel/src/tunneledBrowserConnection.ts

d03eecc

Co-authored-by: Copilot <[email protected]>

fix spelling mistake

bcd1cf8

remove console.log usage for terminal

2e52a89

refactor: improve WebSocket connection handling and logging in Playwr…

e43651c

…ightTunnel

dmichon-msft reviewed Dec 18, 2025

View reviewed changes

TheLarkInn reviewed Dec 19, 2025

View reviewed changes

iclanton reviewed Dec 19, 2025

View reviewed changes


		this.status = 'browser-server-running';

		// send ack so that the counterpart also knows to start forwarding messages

-            // send ack so that the counterpart also knows to start forwarding messages
+            // Send ack so that the counterpart also knows to start forwarding messages.
+            // NOTE: The 2-second delay is an intentional workaround. In the current
+            // protocol, the remote tunnel endpoint does not expose an explicit "ready"
+            // signal for when it has finished initializing its own forwarding logic
+            // after receiving the initial handshake. Empirically, introducing this
+            // delay avoids races where early messages could be dropped or mishandled
+            // if they arrive before the remote side is fully ready.
+            //
+            // A future improvement would be to replace this delay with a deterministic
+            // synchronization mechanism (e.g. an explicit "ready" message or event)
+            // instead of relying on a fixed timeout.

	export type BrowserNames = 'chromium' \| 'firefox' \| 'webkit';
	export type BrowserName = 'chromium' \| 'firefox' \| 'webkit';

	type ITunnelMode = 'poll-connection' \| 'wait-for-incoming-connection';
	type TunnelMode = 'poll-connection' \| 'wait-for-incoming-connection';

	outputPath: path.resolve(__dirname, 'dist', 'vsix', 'unpacked')
	outputPath: `${__dirname}/dist/vsix/unpacked`

	return path.join(os.tmpdir(), 'playwright-browser-tunnel');
	return `${os.tmpdir()}/playwright-browser-tunnel`;

	async function handleStartTunnel(): Promise<void> {
	async function handleStartTunnelAsync(): Promise<void> {

	async function handleStopTunnel(): Promise<void> {
	async function handleStopTunnelAsync(): Promise<void> {

Playwright Browser Server #5424

Are you sure you want to change the base?

Playwright Browser Server #5424

Conversation

bmiddha commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

How it was tested

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Dec 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bmiddha commented Oct 30, 2025 •

edited

Loading