Playwriter Documentation

Playwriter operates on a local-only architecture. The relay server binds to localhost:19988 and only accepts connections from the Playwriter extension via WebSocket.

Key security features include:

• Origin Validation: The extension WebSocket endpoint only accepts the Playwriter extension origin to prevent malicious websites from controlling your browser.
• Explicit Consent: Only tabs where you have explicitly clicked the extension icon are controlled. There is no background access to other tabs.
• Visible Automation: Chrome displays an automation banner on all controlled tabs, allowing you to monitor agent activity in real time.

Playwright implements accessibility snapshots via the ariaSnapshot() method. Instead of using Chrome DevTools Protocol (CDP) commands, Playwright uses browser-side JavaScript injection. An injected script traverses the DOM directly using browser APIs to generate the tree.

Key characteristics:

• Cross-browser compatibility: Works in Firefox, WebKit, and Chromium.
• Limitations: It cannot automatically traverse into <iframe> content due to security restrictions and design choices. It detects iframes and adds them to the tree with role: 'iframe', but the children array for an iframe node is always empty.

Automation in Playwright is managed through two primary objects:

• page: Represents a single browser tab.
• context: Represents a browser session, containing cookies, storage, and other session-specific data.

You can create a new page from an existing context using context.newPage().

// Assuming you have page and context already available
const page = await context.newPage()

Playwriter is designed for agent-driven browser control by running the Playwright API against your existing Chrome instance, whereas the Playwright CLI (npx playwright) spawns a fresh, isolated browser instance.

Key differences include:

• Browser State: Playwright CLI starts with a fresh (logged out) browser; Playwriter uses your existing Chrome with all cookies and login states intact.
• Extensions: Playwright CLI has no extensions; Playwriter uses your existing Chrome extensions.
• Captchas: Playwright CLI is often blocked by captchas; Playwriter can bypass them by using your existing session.
• Capabilities: Playwriter provides raw CDP access and native high-FPS video recording, which the Playwright CLI lacks.

Playwriter is designed to run locally on your machine with the following security constraints:

• Local only: The WebSocket server binds to localhost:19988. No data leaves your machine to a remote server.
• Origin validation: Only the Playwriter extension origin is accepted, preventing malicious websites from spoofing the connection.
• Explicit consent: The agent only controls tabs where you have manually clicked the extension icon; it has no background access.
• Visible automation: Chrome displays an automation banner on all controlled tabs.

Playwriter is designed to run locally on your machine with the following security constraints:

• Local-only WebSocket: The relay binds to localhost:19988 and only accepts connections from the extension.
• Origin validation: Only the Playwriter extension origin is accepted, preventing malicious websites from spoofing connections.
• Explicit consent: Automation only occurs on tabs where you have manually clicked the extension icon; there is no background access.
• Visible automation: Chrome displays an automation banner on all controlled tabs.

For large datasets that might truncate in console output, use state.page.evaluate to create a Blob and trigger a client-side download link.

await state.page.evaluate(async url => {
  const resp = await fetch(url)
  const data = await resp.text()
  const blob = new Blob([data], { type: 'application/octet-stream' })
  const a = document.createElement('a')
  a.href = URL.createObjectURL(blob)
  a.download = 'data.json'
  a.click()
}, 'https://example.com/protected/large-file')

Once the host machine is running, you can control it from a remote machine using the playwriter CLI. You can configure the connection using environment variables or command-line flags.

Using Environment Variables

Set the PLAYWRITER_HOST and PLAYWRITER_TOKEN variables:

export PLAYWRITER_HOST=https://my-machine-tunnel.traforo.dev
export PLAYWRITER_TOKEN=MY_SECRET_TOKEN

Then run commands using the -s (session) flag. Use playwriter session new to generate a new session ID:

playwriter session new          # outputs: 1
playwriter -s 1 -e "await page.goto('https://example.com')"

Using CLI Flags

Alternatively, pass the connection details directly as flags:

playwriter --host https://my-machine-tunnel.traforo.dev --token MY_SECRET_TOKEN -s 1 -e "await page.goto('https://example.com')"

You can control Chrome over a Local Area Network (LAN) without using tunnels. Set the PLAYWRITER_HOST environment variable to the IP address of the host machine.

For MCP (Model Context Protocol) clients, set both PLAYWRITER_HOST and PLAYWRITER_TOKEN in your MCP client's environment configuration.