Playwright Browser Server

[bmiddha]

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

Loading

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.

[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'.

[Copilot]

@TheLarkInn I've opened a new pull request, #5555, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@TheLarkInn I've opened a new pull request, #5556, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@TheLarkInn I've opened a new pull request, #5557, to work on those changes. Once the pull request is ready, I'll request review from you.