Agent Reference

This page is the full agent reference for Playwriter. It's intended for AI agents and coding assistants that need to know every available utility, pattern, and best practice. If you're a human looking for a quick overview, start with Installation or CLI Reference instead.

To give your agent these instructions automatically, install the Playwriter skill:

1npx -y skills add https://playwriter.dev

The skill injects the content below into your agent's context so it knows how to use Playwriter without trial and error. Works with OpenCode, Cursor, Claude Code, and any agent that supports skills.

CLI Usage

If playwriter command is not found, install globally or use npx/bunx:

1234npm install -g playwriter@latest
# or use without installing:
npx playwriter@latest session new
bunx playwriter@latest session new

If using npx or bunx always use @latest for the first session command. so we are sure of using the latest version of the package

Session management

Each session runs in an isolated sandbox with its own state object. Use sessions to:

Keep state separate between different tasks or agents
Persist data (pages, variables) across multiple execute calls
Avoid interference when multiple agents use playwriter simultaneously

Get a new session ID to use in commands:

12playwriter session new
# outputs: 1

Always use your own session - pass -s <id> to all commands. Using the same session preserves your state between calls. Using a different session gives you a fresh state.

List all active sessions with their state keys:

12345playwriter session list
# ID  State Keys
# --------------
# 1   myPage, userData
# 2   -

Reset a session if the browser connection is stale or broken:

1playwriter session reset <sessionId>

Tab groups

Use the shortest clear single-word group name with no spaces, such as docs, shop, test, or scrape. Local sessions default to playwriter; remote-control sessions default to remote.

If you use playwriter on your own initiative (the user did not ask for browser work), for example to verify a local dev server, set a task-specific group: the short project name, like --tab-group kimaki.

12playwriter session new --tab-group docs
playwriter session new --tab-group scrape --tab-group-color grey

Colors: grey, blue, red, yellow, green, pink, purple, cyan, orange; otherwise color is derived from the name. Chrome can collapse or move groups. Dragging a tab between Playwriter groups keeps it connected; dragging it out disconnects it. Local and remote-control extension sessions only.

Node programs and TypeScript SDKs use the playwriter package as a library. Do not POST /cli/session/new yourself. Docs: https://playwriter.dev/docs/sessions#node-api

123456import { connectViaExtension } from 'playwriter'

// auto-closes at scope end, also on throw: closes only tabs it opened, deletes the session
await using connection = await connectViaExtension({ tabGroup: 'docs' })
const page = await connection.browser.contexts()[0].newPage()
await page.goto('https://example.com')

Pass closeTabsOnEnd: false to keep opened tabs after close, so a later process can reuse them via context.pages().

With several browsers or profiles connected, pass selectBrowser: (browsers) => browsers.find((b) => b.email === 'me@work.com'). Each item has id (stable), browser (Chrome, Brave, Ghost...), email.

Remote access (control browser from another machine)

Playwriter can control a Chrome browser running on a different machine over the internet. The host machine runs playwriter serve with a traforo tunnel, and the remote machine connects through the tunnel URL.

12345678# Host machine (has Chrome + extension)
npx -y traforo -p 19988 -- npx -y playwriter serve --token MY_SECRET_TOKEN

# Remote machine
export PLAYWRITER_HOST=https://<tunnel-id>-tunnel.traforo.dev
export PLAYWRITER_TOKEN=MY_SECRET_TOKEN
playwriter session new
playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://example.com')"

For the full guide (Docker, LAN, MCP config, security), see: https://playwriter.dev/docs/remote-access

Direct CDP connection (no extension needed)

Playwriter can connect directly to a Chrome instance via the Chrome DevTools Protocol, bypassing the browser extension entirely. This is useful for:

Chrome running with remote debugging enabled (CI, Docker, headless environments)
Cloud browser providers that expose a CDP endpoint (e.g. wss://xxx.cdp.browser-use.com)
Any service or machine that gives you a ws:// or wss:// URL to a Chrome DevTools session

Prerequisites: you need a CDP-enabled Chrome. Either:

Open chrome://inspect/#remote-debugging in Chrome
Launch Chrome with --remote-debugging-port=9222
Use playwriter browser start (enables debugging automatically)
Use a cloud browser provider URL (no local Chrome needed)

CLI usage:

123456789101112# Auto-discover local Chrome instances with debugging enabled
playwriter session new --direct

# Connect to a specific CDP endpoint (local or cloud browser provider)
playwriter session new --direct ws://localhost:9222/devtools/browser/...
playwriter session new --direct wss://xxx.cdp.browser-use.com

# Connect to a remote Chrome instance (host:port auto-resolves to ws://)
playwriter session new --direct 192.168.1.50:9222

# Then use the session normally
playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://example.com')"

MCP configuration (for AI assistants): set the PLAYWRITER_DIRECT env var in your MCP client config. If the user provides a CDP URL (like wss://xxx.cdp.browser-use.com), use it as the value:

1234567891011{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_DIRECT": "wss://xxx.cdp.browser-use.com"
      }
    }
  }
}

PLAYWRITER_DIRECT accepts:

1 — auto-discover Chrome on port 9222
ws:// or wss:// URL — explicit WebSocket endpoint (local or cloud browser provider)
host:port — resolves via HTTP probe to a ws:// URL

Limitations: screen recording (recording.start/recording.stop) is not available in direct CDP mode since it relies on the extension's chrome.tabCapture API.

Remote control (drive another user's browser)

When a user shares their browser with you, they send a secret id (created by clicking the Remote control button in the Playwriter toolbar). The user needs no playwriter install, only the extension.

How it works: the extension opens a secret tunnel. Your CLI dials it with the id and talks CDP as if the browser were local. You see every tab where the user enabled Playwriter and can open new tabs with context.newPage() (older extensions reject new tabs; then stay in the shared tab). context.pages()[0] is the tab where the user started sharing.

Connect with:

123playwriter session new --remote <id>
# prints a session id; use it normally afterwards, no extra flags needed
playwriter -s 1 -e "state.page = context.pages()[0]; console.log(await state.page.title())"

Tabs you open join the remote tab group. Set another title with --tab-group <name>.

Rules for remote-control sessions:

Other tabs may belong to the user or their local agents. Prefer your own pages: state.page = context.pages()[0] for the shared tab, or await context.newPage() for new work.
The user revokes access anytime with Stop sharing, or by closing the tab where sharing started; the id then stops working permanently. If the connection dies, ask the user for a fresh id.
Never print, log, or share the id: whoever has it can control the user's browser as them.
Screen recording is not available on remote-control sessions.

Use cases: the user is logged into a website and wants you (a remote agent like Devin, a cloud bot, or a CLI agent on another machine) to act in their authenticated session without sharing passwords.

Headless browser (no extension, no user browser)

Launch a headless Chrome automatically. No extension setup, no user browser involvement. Useful when the user doesn't want their personal browser used, in CI/server environments, or for fully autonomous automation.

123456789# Install Chrome for Testing (first time only, if no Chrome is available)
playwriter browser install

# Launch headless Chrome and create a session
playwriter session new --browser headless

# Use the session normally
playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://example.com')"
playwriter -s 1 -e "console.log(await snapshot({ page: state.page }))"

Multiple sessions reuse the same headless Chrome process. Recording is not available in headless mode.

If no Chrome binary is found, playwriter session new --browser headless will tell you to run playwriter browser install first to download Chrome for Testing.

Cloud browsers (stealth, proxies, CAPTCHA solving)

Cloud browsers are full Chromium instances running in the cloud. They work exactly like a local Chrome session but with stealth and anti-detection built in. No local Chrome or extension needed.

When to use cloud browsers:

CAPTCHA bypass. Cloudflare Turnstile, reCAPTCHA v2/v3, and hCaptcha are solved automatically via token injection. No API keys, no manual solving, no extra code.
Anti-detection. Stealth Chromium patches remove navigator.webdriver, CDP leak fingerprints, and other automation signals. Sites that block Playwright, Puppeteer, or Selenium work normally.
Residential proxies. Route traffic through residential IPs in 195+ countries with --proxy <region>. Proxy is disabled by default to save cost; enable it only when you need anti-detection or geo-targeting.
VPS and headless environments. Run browser automation from any server without installing Chrome. The cloud browser runs remotely and you connect via CDP.
Parallel execution. Spin up multiple cloud browsers to run tasks in parallel with subagents. Each browser is an isolated instance with its own IP, fingerprint, and cookie jar.
Multiple identities. Control separate logged-in accounts on the same site simultaneously. Each cloud browser has independent cookies and storage, so sessions don't interfere with each other.

Authentication: two options depending on your environment.

123456# Option 1: Interactive login (opens browser for OAuth)
playwriter cloud login

# Option 2: API key (for CI, VPS, headless — no browser needed)
# Create one at https://playwriter.dev/dashboard, then:
export PLAYWRITER_API_KEY=pw_xxxxx

1234567891011121314# Check active cloud sessions
playwriter cloud status

# Start a cloud browser session (no proxy, cheapest)
playwriter session new --browser cloud

# Start with US residential proxy (for anti-detection / geo-targeting)
playwriter session new --browser cloud --proxy us

# Use a different region
playwriter session new --browser cloud --proxy de

# Use a custom proxy
playwriter session new --browser cloud --custom-proxy user:pass@host:8080

Cloud sessions auto-stop after 10 minutes of inactivity. When proxy is enabled, raster images are blocked by default to reduce bandwidth costs. Pass --disable-proxy-bandwidth-acceleration if you need images to load.

Execute code

1playwriter -s <sessionId> -e "<code>"

The -s flag specifies a session ID (required). Get one with playwriter session new. Use the same session to persist state across commands.

Execution timeout: default is 10000ms. Override per call with --timeout <ms>, or set a new default via env:

123456# One-off longer timeout 
playwriter -s 1 --timeout 120000 -e '...'

# Default for all -e/-f in this shell
export PLAYWRITER_EXEC_TIMEOUT=30000
playwriter -s 1 -e '...'

PLAYWRITER_EXEC_TIMEOUT is the default fallback. --timeout overrides it, and MCP clients can set the env var or pass a per-call timeout.

Calls in one session run in order.

File-based execution: for complex multi-line code, write a .js file and run it with -f instead of fighting with bash quoting:

1playwriter -s 1 -f ./scripts/my-automation.js

-f and -e cannot be used together. The file content is executed with the same sandbox context (context, state, snapshot, etc.).

Examples:

1234567891011121314151617# Navigate to a page
playwriter -s 1 -e 'state.page = await context.newPage(); await state.page.goto("https://example.com")'

# Click a button
playwriter -s 1 -e 'await state.page.click("button")'

# Get page title
playwriter -s 1 -e 'await state.page.title()'

# Take a screenshot
playwriter -s 1 -e 'await state.page.screenshot({ path: "/absolute/path/to/screenshot.png", scale: "css" })'

# Get accessibility snapshot
playwriter -s 1 -e 'await snapshot({ page: state.page })'

# Get accessibility snapshot for a specific iframe
playwriter -s 1 -e 'const frame = await state.page.locator("iframe").contentFrame(); await snapshot({ page: state.page, frame })'

Why single quotes? Always wrap -e code in single quotes ('...') to prevent bash from interpreting $, backticks, and other special characters inside your JS code. Use double quotes or backtick template literals for strings inside the JS code.

Multiline code:

123456789101112131415# Preferred: use heredoc with quoted delimiter (disables all bash expansion)
playwriter -s 1 -e "$(cat <<'EOF'
const links = await state.page.$$eval('a', els => els.map(e => e.href));
console.log('Found', links.length, 'links');
const price = text.match(/\$[\d.]+/);
EOF
)"

# Alternative: $'...' syntax (but beware: \n and \t become special, and
# single quotes inside must be escaped as \')
playwriter -s 1 -e $'
const title = await state.page.title();
const url = state.page.url();
console.log({ title, url });
'

Quoting rules summary:

Single quotes ('...'): best for one-liners. No bash expansion at all. But you cannot include a literal single quote inside — use double quotes for JS strings instead.
Heredoc (<<'EOF'): best for multiline code. The quoted 'EOF' delimiter disables all bash expansion. Any character works inside, including $, backticks, and single quotes.
$'...': allows \' escaping but \n, \t, \\ become special — conflicts with JS regex patterns.

Execute from file

For longer scripts, use -f instead of -e to execute JavaScript from a file:

1playwriter -s 1 -f script.js

The file is read from disk and executed in the same sandbox as -e. All context variables (state, context, etc.) are available. -e and -f cannot be used together.

Before any recorder work, run playwriter skill once and read the full output (never truncate).

The user can start recording from the in-page toolbar (Record) or ask you to run playwriter recorder start. Both write the same event file. The toolbar does not pick a session; the relay attaches to any free extension session (or creates one). Session choice does not matter: extension sessions share the same Chrome tabs. You identify the recording later at stop time.

playwriter recorder start records everything the user does in the browser (clicks, typing, navigations, mutating xhr/fetch) as events with generated locator strings. It also saves a jpeg of each visual change into a frames folder (~/.playwriter/recordings/<id>/frames, files named <ms>.jpg). User clicks flash a ripple in those frames. To see the screen at an event, read the jpeg whose filename is closest to that event's ms. When the user asks you to "start recording", run it and let them perform their workflow. You may run playwriter commands on that session if they ask (snapshot, inspect, click something). If they did not ask, ask first. Do not drive the workflow yourself.

12345678playwriter recorder start            # reuse the only session, or create one
playwriter recorder start -s 1       # attach to an existing session
playwriter recorder status           # active recordings + current page urls
playwriter recorder stop             # stop the only active recording
playwriter recorder stop 3           # stop recording 3 when several are active
playwriter recorder events           # thin timeline of the latest recording
playwriter recorder events -r 3      # events of recording 3
playwriter recorder events 4 7       # full details of events 4 and 7

Run playwriter recorder stop when they say done, then playwriter recorder events -r <id> to read the events. If stop fails because more than one recording is active, the error lists each recording id, session, and current or last page URL. Pick the one that matches the workflow (or ask the user), then playwriter recorder stop <id>. Replay the flow with playwriter commands only (playwriter -s <id> -e '...'), never raw Playwright. The recorder start output prints full instructions for turning a recording into a reusable skill: a SKILL.md of markdown instructions with example playwriter commands, plus an importable helper script (submit.js, sdk.js) for cheap replay. Recording runs inside the relay daemon, so it survives CLI exits. Pass -s <id> to record an existing session; the recorder attaches to all Playwriter-enabled tabs and does not open a new tab. A recording auto-stops after 20 minutes.

If the user started from the toolbar and then says "done", still run playwriter recorder stop (or stop <id> if several are listed). The toolbar Stop button also works; it stops the recording it started.

Live streaming to RTMP (X Live, Twitch, YouTube)

Niche use case: playwriter stream start|stop|status streams a tab live to RTMP endpoints via ffmpeg, surviving navigation and running 24/7 after the CLI exits. Docs: https://playwriter.dev/docs/streaming

Debugging playwriter issues

If some internal critical error happens you can read the relay server logs to understand the issue. The log file is located in the user home directory:

12playwriter logfile  # prints the log file path
# typically: ~/.playwriter/relay-server.log

The relay log contains logs from the extension, MCP and WS server. A separate CDP JSONL log is created alongside it (see playwriter logfile) with all CDP commands/responses and events, with long strings truncated. Both files are recreated every time the server starts. For debugging internal playwriter errors, read these files with grep/rg to find relevant lines.

Example: summarize CDP traffic counts by direction + method:

1jq -r '.direction + "\t" + (.message.method // "response")' ~/.playwriter/cdp.jsonl | uniq -c

If you find a bug, you can create a gh issue using gh issue create -R remorses/playwriter --title title --body body. Ask for user confirmation before doing this.

playwriter best practices

Control user's Chrome browser via playwright code snippets. Prefer single-line code with semicolons between statements. Use playwriter immediately without waiting for user actions; only if you get "extension is not connected" or "no browser tabs have Playwriter enabled" should you ask the user to click the playwriter extension icon on the target tab.

When to use playwriter instead of webfetch/curl: If a website is JS-heavy (SPAs like Instagram, Twitter, Facebook, etc.), has cookie consent modals, login walls, lazy-loaded content, carousels, or infinite scroll — always use playwriter. Simple fetch/webfetch will return an empty HTML shell with no content. Do NOT waste time trying curl, webfetch, or parsing raw HTML from JS-rendered sites. Go straight to playwriter: navigate with a real browser, dismiss modals, then extract what you need via page.evaluate() or network interception.

If Chrome is not running, the extension can't connect. Start Chrome from the command line before retrying:

1234567891011# macOS
open -a "Google Chrome" --args --profile-directory=Default

# Linux
google-chrome --profile-directory=Default &

# Windows (cmd)
start chrome.exe --profile-directory=Default

# Windows (PowerShell)
Start-Process chrome.exe -ArgumentList '--profile-directory=Default'

To also enable automatic tab capture for screen recording (no manual extension click needed), add the --allowlisted-extension-id and --auto-accept-this-tab-capture flags:

12345678# macOS
open -a "Google Chrome" --args --profile-directory=Default --allowlisted-extension-id=jfeammnjpkecdekppnclgkkffahnhfhe --auto-accept-this-tab-capture

# Linux
google-chrome --profile-directory=Default --allowlisted-extension-id=jfeammnjpkecdekppnclgkkffahnhfhe --auto-accept-this-tab-capture &

# Windows
start chrome.exe --profile-directory=Default --allowlisted-extension-id=jfeammnjpkecdekppnclgkkffahnhfhe --auto-accept-this-tab-capture

You can collaborate with the user - they can help with captchas, difficult elements, or reproducing bugs.

Direct CDP mode (no extension needed): Playwriter can connect directly to Chrome's DevTools Protocol, bypassing the extension. This is useful in CI, Docker, headless environments, when Chrome has --remote-debugging-port=9222, or with cloud browser providers (e.g. wss://xxx.cdp.browser-use.com). If the user provides a CDP URL, set PLAYWRITER_DIRECT in the MCP client config:

1234567891011{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"],
      "env": {
        "PLAYWRITER_DIRECT": "wss://xxx.cdp.browser-use.com"
      }
    }
  }
}

PLAYWRITER_DIRECT accepts 1 (auto-discover Chrome on port 9222), a ws:// or wss:// endpoint (including cloud browser providers), or host:port. Screen recording is not available in direct CDP mode since it relies on the extension's chrome.tabCapture API.

context variables

state - object persisted between calls within your session. Each session has its own isolated state. Use to store pages, data, listeners (e.g., state.page = await context.newPage())
context - browser context, access all pages via context.pages(), create one with context.newPage()
cloud - list active cloud browsers and send a page's cookies to one. Available in local CLI sessions, but not in cloud or remote-control sessions
require - load Node.js modules (e.g., const fs = require('node:fs'))
import() - use Node.js ESM to load local scripts, packages, and built-ins (e.g., const helpers = await import('./scripts/helpers.js')). Relative paths resolve from the session cwd
importModule - restricted async import for allowlisted Node.js built-ins (e.g., const fs = await importModule('node:fs'))
Node.js globals: setTimeout, setInterval, fetch, URL, Buffer, crypto, process, etc.

Not available in the sandbox: __dirname, __filename, and a default page. Reading page throws. Get your own page (see "working with pages").

sending page cookies to a cloud browser

List active cloud browsers, then send the cookies that apply to a page URL:

123const browsers = await cloud.browsers.list()
console.log(browsers)
await cloud.sendCookies({ from: state.page, to: browsers[0] })

You can use a cloud key or either session ID directly:

1await cloud.sendCookies({ from: state.page, to: 'cloud-1' })

sendCookies reads cookies for from.url(). from is required. Pass urls when the login uses more than one HTTP origin:

12345await cloud.sendCookies({
  from: state.page,
  to: 'cloud-1',
  urls: ['https://example.com', 'https://api.example.com'],
})

The result contains the browser key, cookie count, domains, and skipped count. It never contains cookie values. This copies cookies only. It does not copy local storage, IndexedDB, service workers, saved passwords, or device-bound credentials.

cloud is available for local extension, headless, and direct CLI sessions. It is not available inside managed cloud sessions, remote-control sessions, or the MCP server. Run playwriter cloud login or set PLAYWRITER_API_KEY on the CLI machine before you create the session. The CLI forwards the credentials to the relay without exposing them in the execution scope. Credentials already present on the relay machine also work.

importing local scripts

Local modules use normal Node.js ESM. Export helper functions from a .js or .mjs file and pass Playwriter values such as page explicitly:

1234567// scripts/page-helpers.mjs
export async function getPageInfo({ page }) {
  return {
    title: await page.title(),
    url: page.url(),
  }
}

Load the module from the directory where the Playwriter session was created:

12const { getPageInfo } = await import('./scripts/page-helpers.mjs')
console.log(await getPageInfo({ page: state.page }))

Local modules can use static imports and package imports normally:

12345678// scripts/save-title.mjs
import fs from 'node:fs/promises'
import path from 'node:path'

export async function saveTitle({ page, outputPath }) {
  await fs.mkdir(path.dirname(outputPath), { recursive: true })
  await fs.writeFile(outputPath, await page.title())
}

Security: Modules loaded with import() run with normal Node.js permissions. Only import code you trust. Use sandboxed require or importModule when you need restricted built-ins and scoped filesystem writes.

Important: state is session-isolated but pages are shared across all sessions. See "working with pages" for how to avoid interference.

Sandboxed fs write restrictions: require('node:fs') is scoped. Writes (writeFileSync, mkdirSync, etc.) only succeed in:

The directory where playwriter CLI was invoked (the session's cwd)
/tmp
The OS temp directory (os.tmpdir(), e.g. /var/folders/.../T/ on macOS)

Writing to any other path (e.g. ~/Downloads, ~/Desktop) throws EPERM: operation not permitted, access outside allowed directories. To save files elsewhere, write to a temp path first, then move the file using a shell command outside the sandbox.

rules

Initialize state.page first: see "working with pages". There is no default page. At the start of a task, assign state.page (a new tab, or the tab the user pointed to) and use state.page for all automation steps.
Multiple calls: use multiple execute calls for complex logic - helps understand intermediate state and isolate which action failed
Never close: never call browser.close() or context.close(). Only close pages you created or if user asks
No bringToFront: never call unless user asks - it's disruptive and unnecessary, you can interact with background pages
Click before keyboard input in extension mode. Call click() on the target field immediately before fill() or keyboard methods. CDP sends keyboard input to the browser's OS-focused surface, so DOM focus and bringToFront() can still leave text in Chrome's omnibox.
Check state after actions: always verify page state after clicking/submitting (see next section)
Clean up only your listeners: remove listeners you added by event name or handler reference. Never call removeAllListeners() because it also removes Playwriter's page error and console listeners.
Tracked page errors are automatic: uncaught errors from pages assigned directly to state keys appear in the current or next execute output as [PAGE ERROR]. Errors from pages tracked by other sessions are excluded.
Always print page logs after every action: call getLatestLogs({ page: state.page, sinceLastCall: true }) after every goto, click, or submit to catch console errors and warnings. Do not manually collect page.on('console') events; manual listeners miss logs emitted before the listener is attached. The first sinceLastCall call returns all buffered logs including startup and hydration errors. getLatestLogs needs page. snapshot needs page, or a locator/frame from your tab.
CDP sessions: use getCDPSession({ page: state.page }) not state.page.context().newCDPSession() - NEVER use newCDPSession() method, it doesn't work through playwriter relay
Wait for load: use state.page.waitForLoadState('domcontentloaded') not state.page.waitForEvent('load') - waitForEvent times out if already loaded
Minimize timeouts: prefer proper waits (waitForSelector, waitForPageLoad) over state.page.waitForTimeout(). Short timeouts (1-2s) are acceptable for non-deterministic events like animations, tab opens, or async UI updates where no specific selector is available
Snapshot before screenshot: always use snapshot({ page: state.page }) first to understand page state (text-based, fast, cheap). Only use screenshot when you specifically need visual/spatial information. Never take a screenshot just to check if a page loaded or to read text content — snapshot gives you that instantly without burning image tokens
Always use absolute file paths for Playwright artifact APIs: for page.screenshot({ path }), locator.screenshot({ path }), elementHandle.screenshot({ path }), page.pdf({ path }), download.saveAs(path), and video.saveAs(path), always pass an absolute path. Relative paths are resolved by Playwright client internals, not the sandboxed fs, so they may use the relay server cwd instead of your session cwd.
Use snapshot() for element discovery, inspect() for layout: snapshot({ page: state.page }) shows roles, text, and locators — use it to find elements and check visibility. inspect() shows bounding boxes, scroll state, and computed styles — use it when you need layout or scroll info. Do NOT write page.evaluate() calls to query class names, bounding boxes, or visibility flags. Reserve page.evaluate() for state mutations (e.g., localStorage.clear(), el.scrollTop += 300) or extracting non-DOM data (e.g., window.__CONFIG__)

interaction feedback loop

Every browser interaction must follow observe → act → observe. Never chain multiple actions blindly.

Open page — get or create your page, navigate to URL
Observe — print state.page.url() + snapshot({ page: state.page }) + getLatestLogs({ page: state.page, sinceLastCall: true }). Always print URL — pages can redirect unexpectedly.
Check — if page isn't ready (loading, wrong URL, content missing), wait and observe again
Act — perform one action (click, type, submit)
Observe again — print URL + snapshot + page logs to verify the action's effect
Repeat from step 3 until task is complete

Always print page logs after every action using getLatestLogs({ page: state.page, sinceLastCall: true }). This returns only new console messages and errors since the last call, so you catch hydration errors, failed network requests, and runtime exceptions without duplicates. The first call returns all buffered logs from the page, including logs emitted before your script started.

1234567// Each step should be a separate execute call:
// Step 1: navigate + observe
state.page = await context.newPage()
await state.page.goto('https://example.com', { waitUntil: 'domcontentloaded' })
console.log('URL:', state.page.url())
console.log('Page logs:', await getLatestLogs({ page: state.page, sinceLastCall: true }))
await snapshot({ page: state.page }).then(console.log)

12345// Step 2: act + observe
await state.page.locator('button:has-text("Submit")').click()
console.log('URL:', state.page.url())
console.log('Page logs:', await getLatestLogs({ page: state.page, sinceLastCall: true }))
await snapshot({ page: state.page }).then(console.log)

If nothing changed after an action, try waitForPageLoad({ page: state.page, timeout: 3000 }) or you may have clicked the wrong element.

Deeper observation — when snapshots aren't enough to understand what happened, combine snapshot with filtered logs:

12345678// Search for specific errors in all logs (not just since last call)
const errors = await getLatestLogs({ page: state.page, search: /error|fail/i, count: 20 })

// Combine snapshot + filtered logs for full picture
const snap = await snapshot({ page: state.page, search: /dialog|error|message/ })
const logs = await getLatestLogs({ page: state.page, search: /error/i, count: 10 })
console.log('UI:', snap)
console.log('Logs:', logs)

Use getLatestLogs({ page: state.page, sinceLastCall: true }) after every action, getLatestLogs({ page: state.page, search }) for targeted debugging, state.page.url() for navigation, screenshots only for visual layout issues.

common mistakes to avoid

1. Not verifying actions succeeded Always check page state after important actions (form submissions, uploads, typing). Your mental model can diverge from actual browser state:

123await state.page.keyboard.type('my text')
await snapshot({ page: state.page, search: /my text/ })
// If verifying visual layout specifically, use screenshotWithAccessibilityLabels instead

2. Assuming paste/upload worked Clipboard paste (Meta+v) can silently fail. For file uploads, prefer file input:

123456// Reliable: use file input
const fileInput = state.page.locator('input[type="file"]').first()
await fileInput.setInputFiles('/path/to/image.png')

// Unreliable: clipboard paste may silently fail, need to focus textarea first for example
await state.page.keyboard.press('Meta+v') // always verify with screenshot!

3. Using stale locators from old snapshots Locators (especially ones with >> nth=) can change when the page updates. Main-frame navigation invalidates all refs and diff baselines for that page. Always get a fresh snapshot before clicking, then immediately use locators from that output:

12await snapshot({ page: state.page, showDiffSinceLastCall: true })
// Now use the NEW locators from this output

4. Wrong assumptions about current page/element Before destructive actions (delete, submit), verify you're targeting the right thing:

123// Before deleting, verify it's the right item
await screenshotWithAccessibilityLabels({ page: state.page })
// READ the screenshot to confirm, THEN proceed with delete

5. Text concatenation without line breaks keyboard.type() doesn't insert newlines from \n in strings. Use keyboard.press('Enter') between lines:

123await state.page.keyboard.type('Line 1')
await state.page.keyboard.press('Enter')
await state.page.keyboard.type('Line 2')

6. Quote escaping in bash Bash parses $, backticks, and \ inside double-quoted strings. This silently corrupts JS code. Always use single quotes or heredoc:

123456789# single quotes — bash passes everything through literally
playwriter -s 1 -e 'await state.page.locator(`[id="_r_a_"]`).click()'

# heredoc for complex code with mixed quotes
playwriter -s 1 -e "$(cat <<'EOF'
await state.page.locator('[id="_r_a_"]').click()
const match = html.match(/\$[\d.]+/g)
EOF
)"

7. Using screenshots when snapshots suffice Screenshots + image analysis is expensive and slow. Only use screenshots for visual/CSS issues. Use snapshot for text checks:

1await snapshot({ page: state.page, search: /expected text/i })

8. Assuming page content loaded Even after goto(), dynamic content may not be ready:

12345await state.page.goto('https://example.com')
// Content may still be loading via JavaScript!
await state.page.waitForSelector('article', { timeout: 10000 })
// Or use waitForPageLoad utility
await waitForPageLoad({ page: state.page, timeout: 5000 })

9. Not using playwriter for JS-rendered sites Do NOT waste context trying webfetch, curl, or Playwright CLI screenshots on SPAs (Instagram, Twitter, etc.). These return empty HTML shells. Use playwriter directly:

1234state.page = await context.newPage()
await state.page.goto('https://www.instagram.com/p/ABC123/', { waitUntil: 'domcontentloaded' })
await waitForPageLoad({ page: state.page, timeout: 8000 })
await snapshot({ page: state.page, search: /cookie|consent|accept/i }).then(console.log)

10. Login buttons that open popups Popup windows (window.open with features, OAuth buttons) are auto-relocated to tabs in the main window by the Playwriter extension. The new tab appears in context.pages() and is fully controllable. You will receive a [WARNING] New page opened from current page (index N, initial url: ...) message pointing to the new tab — the initial url may be about:blank for blank-then-scripted popups, so check context.pages()[N].url() for the final URL:

1234567891011await state.page.locator('button:has-text("Login with Google")').click()
await state.page.waitForTimeout(1000)

// New tab is the last page in the context
const pages = context.pages()
const loginPage = pages[pages.length - 1]

// Complete login flow in loginPage, cookies are shared with original page
await loginPage.locator('[data-email]').first().click()
await loginPage.waitForURL('**/callback**')
// Original page should now be authenticated

11. Click times out or does nothing — snapshot to find the blocker When a click times out, a modal or overlay is likely intercepting pointer events. Do not retry with different selectors or { force: true } — snapshot to find the blocker:

1234// click timed out → don't retry blindly, find what's blocking
await snapshot({ page: state.page, search: /dialog|modal/i })
// Found modal → interact with it properly (don't just close via X, it may reappear)
await state.page.getByRole('radio', { name: 'Nope, Vanilla' }).click()

12. Never use dispatchEvent or { force: true } to bypass blockers dispatchEvent(new MouseEvent(...)), { force: true }, and element.click() inside page.evaluate() bypass Playwright checks but do not trigger React/Vue/Svelte handlers — state won't update. Use snapshot to find the real interactive element:

1await state.page.getByRole('radio', { name: 'Node.js' }).click()

13. Over-investigating instead of just interacting When something doesn't respond to a click, do NOT start inspecting CDP event listeners, React fibers, canvas pixel data, or writing page.evaluate() to read class names and bounding boxes. This wastes massive context. Instead:

Take a snapshot({ page: state.page }) — it shows every interactive element and what to click
Try a different interaction pattern if click() didn't work:
- Drawing/annotation tools, canvas paint → mouse.down, move with steps, mouse.up (see drag section)
- Keyboard-activated modes → press the shortcut key (snapshot shows tooltip text like "Draw mode D")
- Sliders, timeline scrubbers → drag pattern
- Collapsed/toggled toolbars → click the toggle first, wait, then interact
Take another snapshot({ page: state.page }) to see what changed
Only investigate DOM internals if correct interaction patterns produce zero response after 2–3 attempts

accessibility snapshots

1await snapshot({ page: state.page, search?, showDiffSinceLastCall? })

Always pass { page: state.page }, or pass a locator/frame from that tab. snapshot() with no arguments throws. A locator is enough: the helper uses locator.page().

12await snapshot({ page: state.page, locator: state.page.locator('form') })
await snapshot({ locator: state.page.locator('form') })

search - string/regex to filter results (returns first 10 matching lines)
showDiffSinceLastCall - returns diff since last snapshot (default: true, but false when search is provided). Pass false to get full snapshot.

Snapshots return full content on first call, then diffs on subsequent calls. Diff is only returned when shorter than full content. If nothing changed, returns "No changes since last snapshot" after the URL line. Use showDiffSinceLastCall: false to always get full content. When search is provided, diffing is disabled by default so the search filters the full content — pass showDiffSinceLastCall: true explicitly to combine both. This diffing behavior also applies to getCleanHTML and getPageMarkdown.

Every snapshot starts with URL: <current page url> so you can see which tab was snapshotted. Diffs and "No changes" / "No matches found" include that line too.

Example output:

1234567URL: https://example.com/

- banner:
  - link "Home" [id="nav-home"]
  - navigation:
    - link "Docs" [data-testid="docs-link"]
    - link "Blog" role=link[name="Blog"]

Each interactive line ends with a Playwright locator you can pass to state.page.locator(). If multiple elements share the same locator, a >> nth=N suffix is added (0-based) to make it unique.

Use snapshot locators directly — never invent selectors. The snapshot output IS the selector. Do not guess CSS selectors or getByText when the snapshot already gives you the exact match:

1234// Snapshot shows: role=radio[name="Nope, Vanilla"]  →  use it directly
await state.page.getByRole('radio', { name: 'Nope, Vanilla' }).click()
// Snapshot shows: role=link[name="SIGN IN"]  →  or pass raw string to locator()
await state.page.locator('role=link[name="SIGN IN"]').click()

Beware CSS text-transform: snapshots show visual text (heading "NODE.JS") but DOM may be "Node.js". Use case-insensitive regex: getByRole('heading', { name: /node\.js/i }).

If a screenshot shows ref labels like e3, resolve them using the last snapshot:

123const snap = await snapshot({ page: state.page })
const locator = refToLocator({ ref: 'e3', page: state.page })
await state.page.locator(locator!).click()

Search for specific elements:

1const snap = await snapshot({ page: state.page, search: /button|submit/i })

Scoping snapshots to a specific element — pass page and a locator to snapshot only a subtree. This dramatically reduces output size when you only care about one section of the page (e.g., the main content area, ignoring the sidebar/header/footer):

123456789// Full page snapshot: ~150 lines (sidebar, nav, header, footer, everything)
await snapshot({ page: state.page })

// Scoped to main: ~20 lines (just the content you care about)
await snapshot({ page: state.page, locator: state.page.locator('main') })

// Scope to a specific form, dialog, or section
await snapshot({ page: state.page, locator: state.page.locator('[role="dialog"]') })
await snapshot({ page: state.page, locator: state.page.locator('form#checkout') })

Use this whenever the full page snapshot is dominated by navigation or layout elements you don't need. It saves significant tokens and makes the output much easier to parse.

Filtering large snapshots in JS — when search isn't enough, filter the string directly: snap.split('\n').filter(l => l.includes('dialog') || l.includes('error')).join('\n')

choosing between snapshot methods

Use snapshot for text-heavy pages (forms, articles) — fast, cheap, searchable. Use screenshotWithAccessibilityLabels for complex visual layouts (grids, galleries, dashboards) where spatial position matters. Both share the same ref system and can be combined.

selector best practices

For unknown websites: use snapshot({ page: state.page }) - it shows what's actually interactive with stable locators.

For development (when you have source code access), prefer stable selectors in this order:

Best: [data-testid="submit"] - explicit test attributes, never change accidentally
Good: getByRole('button', { name: 'Save' }) - accessible, semantic
Good: getByText('Sign in'), getByLabel('Email') - readable, user-facing
OK: input[name="email"], button[type="submit"] - semantic HTML
Avoid: .btn-primary, #submit - classes/IDs change frequently
Last resort: div.container > form > button - fragile, breaks easily

Combine locators for precision:

12state.page.locator('tr').filter({ hasText: 'John' }).locator('button').click()
state.page.locator('button').nth(2).click()

If a locator matches multiple elements, Playwright throws "strict mode violation". Use .first(), .last(), or .nth(n):

123await state.page.locator('button').first().click() // first match
await state.page.locator('.item').last().click() // last match
await state.page.locator('li').nth(3).click() // 4th item (0-indexed)

working with pages

Pages are shared, state is not. context.pages() returns all browser tabs with playwriter enabled — shared across all sessions. Multiple agents see the same tabs. If another agent navigates or closes a page you're using, you'll be affected. To avoid interference, get your own page.

There is no default page in the sandbox. Reading page throws. Helpers that take page (snapshot, getLatestLogs, waitForPageLoad, recording, ghostCursor, refToLocator) need { page: state.page }. snapshot also accepts a locator or frame from your tab.

New task: create your own tab (first call):

Create a tab, store it in state, and navigate it in the same execute call. Use state.page for all later operations:

12state.page = await context.newPage()
await state.page.goto('https://example.com')

User points to an existing tab:

Use a page from context.pages() only if the user asks you to control a tab they already opened (e.g., they're logged into an app, or they mention its URL or content). Find it by URL and take the last match. context.pages() is ordered oldest first, so the last match is the most recently opened tab:

12state.page = context.pages().findLast((p) => p.url().includes('myapp.com'))
if (!state.page) throw new Error('No myapp.com tab found. Ask the user to enable playwriter on it.')

Handle page closures gracefully:

The user may close your page by accident (e.g., closing a tab in Chrome). Check before using it and recreate if needed:

12if (!state.page || state.page.isClosed()) state.page = await context.newPage()
await state.page.goto('https://example.com')

List all available pages:

1context.pages().map((p) => p.url())

Popup windows become tabs automatically:

The extension intercepts Chrome popup windows (window.open(url, '', 'width=...'), OAuth login flows) and relocates them into the main window as regular tabs. You don't need cmd+click or { modifiers: ['Meta'] } to avoid popups. When a page opens another, you receive a [WARNING] New page opened from current page (index N, initial url: ...) and can access it via context.pages()[N].

Use domcontentloaded for page.goto():

12await state.page.goto('https://example.com', { waitUntil: 'domcontentloaded' })
await waitForPageLoad({ page: state.page, timeout: 5000 })

common patterns

Authenticated fetches - fetch from within page context to include session cookies automatically:

1234const data = await state.page.evaluate(async (url) => {
  const resp = await fetch(url)
  return await resp.text()
}, 'https://example.com/protected/resource')

Read page cookies via CDP - use Network.getCookies on the page CDP session:

123const cdp = await getCDPSession({ page: state.page })
const { cookies } = await cdp.send('Network.getCookies', { urls: [state.page.url()] })
console.log(cookies)

MUST use this for page-scoped cookies in extension mode. Storage.getCookies is a root-session command and will fail in playwriter.

NEVER use Network.clearBrowserCookies or Network.clearBrowserCache — these CDP commands are profile-wide destructive operations that wipe ALL cookies/cache across every domain in the user's Chrome profile. They will log the user out of Gmail, GitHub, and every authenticated session.

Clear cookies for a specific domain — use Network.getCookies to fetch cookies scoped to URLs, then delete them individually with Network.deleteCookies:

1234567const cdp = await getCDPSession({ page: state.page })
const { cookies } = await cdp.send('Network.getCookies', {
  urls: ['https://example.com', 'https://www.example.com'],
})
for (const cookie of cookies) {
  await cdp.send('Network.deleteCookies', { name: cookie.name, domain: cookie.domain })
}

Downloading large data - console output truncates large strings. Trigger a browser download instead:

1234567891011// Fetch protected data and trigger download to user's Downloads folder
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')
// File saves to ~/Downloads - read it from there

Avoid permission-gated browser APIs - some APIs require user permission prompts or special browser flags. These often fail silently or hang. Examples to avoid:

navigator.clipboard.writeText() - requires permission
Multiple concurrent downloads - browser may block
window.showSaveFilePicker() - requires user gesture
Geolocation, camera, microphone APIs

Instead, use simpler alternatives (single download via a.click(), store data in state, etc).

Downloads - capture and save:

12const [download] = await Promise.all([state.page.waitForEvent('download'), state.page.click('button.download')])
await download.saveAs(`/absolute/path/${download.suggestedFilename()}`)

iFrames - two approaches depending on what you need:

1234567// frameLocator: for chaining locator operations (click, fill, etc.)
const frame = state.page.frameLocator('#my-iframe')
await frame.locator('button').click()

// contentFrame: returns a Frame object, needed for snapshot({ frame })
const frame2 = await state.page.locator('iframe').contentFrame()
await snapshot({ page: state.page, frame: frame2 })

Dialogs - handle alerts/confirms/prompts:

12345state.page.on('dialog', async (dialog) => {
  console.log(dialog.message())
  await dialog.accept()
})
await state.page.click('button.trigger-alert')

Handling page obstacles (cookie modals, login walls, age gates) - most major websites show blocking overlays. Always check for these with snapshot({ page: state.page }) right after navigation and dismiss them before doing anything else:

1234567891011// After navigating, check for common obstacles
await waitForPageLoad({ page: state.page, timeout: 5000 })
const snap = await snapshot({
  page: state.page,
  search: /cookie|consent|accept|reject|decline|allow|age|verify|login|sign.in/i,
})
console.log(snap)
// Look for dismiss/accept/decline buttons in the snapshot, then click them:
// await state.page.locator('button:has-text("Accept")').click();
// await state.page.locator('button:has-text("Decline optional")').click();
// Then re-snapshot to confirm the modal is gone before proceeding

If the page requires login and the user is already logged into Chrome, their session cookies are available — just navigate and the page should load authenticated. If not, ask the user for help or use their existing logged-in tab via context.pages().

Extracting and downloading media (images, videos) - use page.evaluate() to extract URLs from the rendered DOM, then download via Node.js in the sandbox. This is far more reliable than parsing raw HTML:

12345678910111213141516// Extract all image URLs from rendered DOM
const images = await state.page.evaluate(() =>
  Array.from(document.querySelectorAll('img[src]')).map((img) => ({
    src: img.src,
    alt: img.alt,
    width: img.naturalWidth,
  })),
)
console.log(JSON.stringify(images, null, 2))

// Download a specific image to disk
const fs = require('node:fs')
const resp = await fetch(images[0].src)
const buf = Buffer.from(await resp.arrayBuffer())
fs.writeFileSync('./downloaded-image.jpg', buf)
console.log('Saved', buf.length, 'bytes')

For carousels or lazy-loaded galleries, you may need to click navigation arrows or scroll first, then re-extract. Use network interception (see "network interception" section) to capture high-resolution CDN URLs that may differ from the img.src thumbnails.

utility functions

inspect - get layout, scroll, visibility, input state, and aria attributes for a locator as formatted text. Use this instead of page.evaluate() for element inspection:

1234567891011121314151617181920212223const info = await inspect({ locator: state.page.locator('.sidebar') })
console.log(info)
// Element: div.sidebar
// Box: x=1000 y=144 w=396 h=756
// Children: 4  Text length: 1832
// Scroll Y: size=1200 client=756 overflowing=true top=0
// Scroll X: size=396 client=396 overflowing=false left=0
// Styles: overflow-y=auto overflow-x=visible position=sticky max-height=756px display=flex flex-direction=column flex-shrink=0

// Visibility line only appears when something is non-default:
// Visibility: opacity=0 pointer-events=none

// Input line only appears for form elements:
// Input: value="hello" checked=true disabled

// Aria line only appears when aria attributes are set:
// Aria: aria-expanded=true aria-selected=false

// Custom CSS properties
const info = await inspect({
  locator: state.page.locator('.card'),
  properties: ['background-color', 'border-radius', 'gap', 'padding']
})

Default CSS properties: overflow-y, overflow-x, position, max-height, display, flex-direction, flex-shrink. Override with the properties array. Visibility, input state, and aria attributes are always checked regardless of properties.

getLatestLogs - retrieve captured browser console logs and page errors (up to 5000 per page):

Always use this helper when inspecting browser logs. Do not attach new page.on('console') listeners for debugging because they only see future events and can miss logs emitted during page startup or hydration.

Uncaught errors from pages assigned directly to state keys also appear automatically in execute output. getLatestLogs() keeps the full page log history for filtering and deeper diagnosis.

Use sinceLastCall: true after every action to get only new logs since the previous call. The first call returns all buffered logs including pre-existing ones. Logs persist across navigations so you never miss errors from page transitions.

123456await getLatestLogs({ page: state.page, count?, search?, sinceLastCall? })
// After every action: get only new logs
const newLogs = await getLatestLogs({ page: state.page, sinceLastCall: true })
const errors = await getLatestLogs({ page: state.page, search: /error/i, count: 50 })
const pageLogs = await getLatestLogs({ page: state.page, count: 100 })
const hydrationErrors = await getLatestLogs({ page: state.page, search: /hydration|pageerror|React/i })

getCleanHTML - get cleaned HTML from a locator or page, with search and diffing:

12345await getCleanHTML({ locator, search?, showDiffSinceLastCall?, includeStyles? })
// Examples:
const html = await getCleanHTML({ locator: state.page.locator('body') })
const html = await getCleanHTML({ locator: state.page, search: /button/i })
const fullHtml = await getCleanHTML({ locator: state.page, showDiffSinceLastCall: false })  // disable diff

Parameters:

locator - Playwright Locator or Page to get HTML from
search - string/regex to filter results (returns first 10 matching lines with 5 lines context)
showDiffSinceLastCall - returns diff since last call (default: true, but false when search is provided). Pass false to get full HTML.
includeStyles - keep style and class attributes (default: false)

Cleans HTML automatically: removes script/style/svg/head tags, unwraps empty wrappers, removes empty elements, truncates long values. Keeps semantic attributes (href, name, type, aria-*, data-*).

getPageMarkdown - extract main page content as plain text using Mozilla Readability (same algorithm as Firefox Reader View). Strips navigation, ads, sidebars, and other clutter. Returns formatted text with title, author, and content:

1234await getPageMarkdown({ page: state.page, search?, showDiffSinceLastCall? })
// Examples:
const content = await getPageMarkdown({ page: state.page, showDiffSinceLastCall: false })  // full article
const matches = await getPageMarkdown({ page: state.page, search: /API/i })  // search within content

Output format:

1234567# Article Title

Author: John Doe | Site: example.com | Published: 2024-01-15

> Article excerpt or description

The main article content as plain text, with paragraphs preserved...

Parameters:

page - Playwright Page to extract content from
search - string/regex to filter content (returns first 10 matching lines with 5 lines context)
showDiffSinceLastCall - returns diff since last call (default: true, but false when search is provided). Pass false to get full content.

waitForPageLoad - smart load detection that ignores analytics/ads:

12await waitForPageLoad({ page: state.page, timeout?, pollInterval?, minWait? })
// Returns: { success, readyState, pendingRequests, waitTimeMs, timedOut }

getCDPSession - send raw CDP commands:

12const cdp = await getCDPSession({ page: state.page })
const metrics = await cdp.send('Page.getLayoutMetrics')

getLocatorStringForElement - get stable Playwright selector from an element:

12const selector = await getLocatorStringForElement(state.page.locator('[id="submit-btn"]'))
// => "getByRole('button', { name: 'Save' })"

getReactSource - get React component source location (dev mode only):

12const source = await getReactSource({ locator: state.page.locator('[data-testid="submit-btn"]') })
// => { fileName, lineNumber, columnNumber, componentName }

getReactComponentInfo - get best-effort React component info for an element. Returns null for non-React elements and never throws just because an element was not rendered by React. Source locations are usually only available in React dev builds. Props are sanitized and truncated so functions, DOM nodes, circular refs, and huge objects do not flood the output.

12const info = await getReactComponentInfo({ locator: state.page.locator('[data-testid="submit-btn"]') })
// => { componentName, source, hierarchy, props } | null

inspectPinnedElement - inspect a Playwriter pinned element and print the element outerHTML plus React component info when available. Used by the in-page toolbar and right-click copy flow.

1await inspectPinnedElement('https://example.com', 'globalThis.playwriterPinnedElem1')

getStylesForLocator - inspect CSS styles applied to an element, like browser DevTools "Styles" panel. Useful for debugging styling issues, finding where a CSS property is defined (file:line), and checking inherited styles. Returns selector, source location, and declarations for each matching rule. ALWAYS fetch https://playwriter.dev/resources/styles-api.md first with curl or webfetch tool.

12345const styles = await getStylesForLocator({
  locator: state.page.locator('.btn'),
  cdp: await getCDPSession({ page: state.page }),
})
console.log(formatStylesAsText(styles))

createDebugger - set breakpoints, step through code, inspect variables at runtime. Useful for debugging issues that only reproduce in browser, understanding code flow, and inspecting state at specific points. Can pause on exceptions, evaluate expressions in scope, and blackbox framework code. ALWAYS fetch https://playwriter.dev/resources/debugger-api.md first.

123456const cdp = await getCDPSession({ page: state.page })
const dbg = createDebugger({ cdp })
await dbg.enable()
const scripts = await dbg.listScripts({ search: 'app' })
await dbg.setBreakpoint({ file: scripts[0].url, line: 42 })
// when paused: dbg.inspectLocalVariables(), dbg.stepOver(), dbg.resume()

createEditor - view and live-edit page scripts and CSS at runtime. Edits are in-memory (persist until reload). Useful for testing quick fixes, searching page scripts with grep, and toggling debug flags. ALWAYS read https://playwriter.dev/resources/editor-api.md first.

12345const cdp = await getCDPSession({ page: state.page })
const editor = createEditor({ cdp })
await editor.enable()
const matches = await editor.grep({ regex: /console\.log/ })
await editor.edit({ url: matches[0].url, oldString: 'DEBUG = false', newString: 'DEBUG = true' })

screenshotWithAccessibilityLabels - take a screenshot with Vimium-style visual labels overlaid on interactive elements. Shows labels, captures screenshot, then removes labels. The image and accessibility snapshot are automatically included in the response. Can be called multiple times to capture multiple screenshots. Use a timeout of 20 seconds for complex pages.

This is only for finding interactive elements on the page. To share a screenshot with the user or save an image, use page.screenshot() + resizeImageForAgent() instead (see "taking screenshots" section below).

Prefer this for pages with grids, image galleries, maps, or complex visual layouts where spatial position matters. For simple text-heavy pages, snapshot with search is faster and uses fewer tokens.

12345678910await screenshotWithAccessibilityLabels({ page: state.page })
// Image and accessibility snapshot are automatically included in response
// Use refs from snapshot to interact with elements
await state.page.locator('[id="submit-btn"]').click()

// Can take multiple screenshots in one execution
await screenshotWithAccessibilityLabels({ page: state.page })
await state.page.click('button')
await screenshotWithAccessibilityLabels({ page: state.page })
// Both images are included in the response

Labels are color-coded: yellow=links, orange=buttons, coral=inputs, pink=checkboxes, peach=sliders, salmon=menus, amber=tabs.

resizeImageForAgent - shrink an image so it consumes fewer tokens when read back into context. The resized image is automatically included in the response (visible to the LLM). await resizeImageForAgent({ input: '/absolute/path/to/screenshot.png' }). Also accepts width, height, maxDimension, quality, format (default: 'png'), output. Alias: resizeImage.

recording.start / recording.stop - record the page as a video at native FPS (30-60fps). Uses chrome.tabCapture so recording survives page navigation. Auto-overlays a ghost cursor that follows mouse actions. Requires user to have clicked the Playwriter extension icon on the tab. Auto-resizes viewport to 16:9 (override with aspectRatio: null). Auto-stops after 15 min (override with maxDurationMs).

For demos, use interaction methods (locator.click(), page.mouse.move()) instead of goto() to show realistic cursor motion.

123456789101112131415161718await recording.start({
  page: state.page,
  outputPath: '/absolute/path/to/recording.mp4',
  frameRate: 30, // default
  audio: false, // default (tab audio)
  videoBitsPerSecond: 2500000,
  aspectRatio: { width: 16, height: 9 }, // default, set null to skip
  maxDurationMs: 15 * 60 * 1000, // default, set 0 to disable
})

// Recording survives navigation
await state.page.click('a')
await state.page.waitForLoadState('domcontentloaded')

// Stop — save full result including executionTimestamps for createDemoVideo
state.recordingResult = await recording.stop({ page: state.page })

// Other: recording.isRecording({ page: state.page }), recording.cancel({ page: state.page })

ghostCursor.show / ghostCursor.hide - the ghost cursor overlay is always on: the extension injects it on every Playwriter-attached tab and it stays visible at the last spot Playwright clicked or moved. These methods only matter if you want to change the cursor style or temporarily hide it:

12await ghostCursor.show({ page: state.page, style: 'screenstudio' }) // 'minimal' (default), 'dot', 'screenstudio'
await ghostCursor.hide({ page: state.page }) // hide until next show() or hard navigation

createDemoVideo - speeds up idle sections (time between execute() calls) while keeping interactions at normal speed. Requires ffmpeg/ffprobe. Timestamps are tracked automatically during recording and returned by recording.stop(). Timeout: can take 60–120+ seconds, always pass --timeout 120000 or higher.

12345678910// After recording.stop(), save full result to state (executionTimestamps powers idle detection)
state.recordingResult = await recording.stop({ page: state.page })

// In a SEPARATE execute call with --timeout 120000:
const demoPath = await createDemoVideo({
  recordingPath: state.recordingResult.path,
  durationMs: state.recordingResult.duration,
  executionTimestamps: state.recordingResult.executionTimestamps,
  speed: 6, // default 6x for idle sections
})

pinned elements

Users can right-click → "Copy Playwriter Element Reference" to store elements in globalThis.playwriterPinnedElem1 (increments for each pin). The reference is copied to clipboard:

12const el = await state.page.evaluateHandle(() => globalThis.playwriterPinnedElem1)
await el.click()

taking screenshots

Always use scale: 'css' to avoid 2-4x larger images on high-DPI displays:

1await state.page.screenshot({ path: '/absolute/path/to/shot.png', scale: 'css' })

If you want to read back the image file into context, resize it first so it consumes fewer tokens:

1await resizeImageForAgent({ input: './shot.png' })

page.evaluate

Code inside page.evaluate() runs in the browser - use plain JavaScript only, no TypeScript syntax. Return values and log outside (console.log inside evaluate runs in browser, not visible):

12345678const title = await state.page.evaluate(() => document.title)
console.log('Title:', title)

const info = await state.page.evaluate(() => ({
  url: location.href,
  buttons: document.querySelectorAll('button').length,
}))
console.log(info)

loading files

Fill inputs with file content:

123const fs = require('node:fs')
const content = fs.readFileSync('./data.txt', 'utf-8')
await state.page.locator('textarea').fill(content)

network interception

For scraping or reverse-engineering APIs, intercept network requests instead of scrolling DOM. Store in state to analyze across calls:

123456789101112state.requests = []
state.responses = []
state.page.on('request', (req) => {
  if (req.url().includes('/api/')) state.requests.push({ url: req.url(), method: req.method(), headers: req.headers() })
})
state.page.on('response', async (res) => {
  if (res.url().includes('/api/')) {
    try {
      state.responses.push({ url: res.url(), status: res.status(), body: await res.json() })
    } catch {}
  }
})

Then trigger actions (scroll, click, navigate) and analyze captured data:

12console.log('Captured', state.responses.length, 'API calls')
state.responses.forEach((r) => console.log(r.status, r.url.slice(0, 80)))

Inspect a specific response to understand schema:

12const resp = state.responses.find((r) => r.url.includes('users'))
console.log(JSON.stringify(resp.body, null, 2).slice(0, 2000))

Replay API directly (useful for pagination):

123456789const { url, headers } = state.requests.find((r) => r.url.includes('feed'))
const data = await state.page.evaluate(
  async ({ url, headers }) => {
    const res = await fetch(url, { headers })
    return res.json()
  },
  { url, headers },
)
console.log(data)

Clean up listeners when done: state.page.removeAllListeners('request'); state.page.removeAllListeners('response');

computer use (low-level mouse/keyboard)

clicking

123456789101112131415// Preferred: by locator (stable, auto-waits, no coordinates needed)
await state.page.locator('button[name="Submit"]').click()
await state.page.locator('text=Login').click({ button: 'right' })
await state.page.locator('text=Login').dblclick()
await state.page
  .locator('a')
  .first()
  .click({ modifiers: ['Meta'] }) // cmd+click opens link in new background tab

// By coordinates (when locators aren't available, e.g. canvas, maps, custom widgets)
await state.page.mouse.click(450, 320) // left click
await state.page.mouse.click(450, 320, { button: 'right' }) // right click
await state.page.mouse.dblclick(450, 320) // double click
await state.page.mouse.click(450, 320, { clickCount: 3 }) // triple click
await state.page.mouse.click(450, 320, { modifiers: ['Shift'] }) // shift+click

hover

12await state.page.locator('.tooltip-trigger').hover() // by locator (preferred)
await state.page.mouse.move(450, 320) // by coordinates

scroll

1234567891011121314151617// By locator (preferred)
await state.page.locator('#footer').scrollIntoViewIfNeeded()

// By pixel (for canvas, maps, infinite scroll)
await state.page.mouse.wheel(0, 300) // scroll down 300px
await state.page.mouse.wheel(0, -300) // scroll up
await state.page.mouse.wheel(300, 0) // scroll right
await state.page.mouse.wheel(-300, 0) // scroll left

// Scroll at a specific position
await state.page.mouse.move(450, 320)
await state.page.mouse.wheel(0, 500)

// Scroll inside a container
await state.page.locator('.scrollable-list').evaluate((el) => {
  el.scrollTop += 500
})

drag

12345678// By locator (preferred)
await state.page.locator('#item').dragTo(state.page.locator('#target'))

// By coordinates (for canvas, sliders, custom drag targets)
await state.page.mouse.move(100, 200)
await state.page.mouse.down()
await state.page.mouse.move(400, 500, { steps: 10 }) // steps for smooth drag
await state.page.mouse.up()

Freehand drawing, annotation widgets, and canvas tools use this same mouse.down → move → up pattern. If a widget expects a drawn stroke (paint tools, annotation overlays, range sliders, timeline scrubbers), always use held-mouse motion — not mouse.click():

123456// Draw a stroke across a canvas or annotation layer
await state.page.mouse.move(startX, startY)
await state.page.mouse.down()
await state.page.mouse.move(endX, endY, { steps: 15 }) // steps = smoother stroke
await state.page.mouse.up()
await state.page.waitForTimeout(500) // let the widget process the stroke

key hold / release / repeat

1234567// Hold modifier while pressing another key
await state.page.keyboard.down('Shift')
await state.page.keyboard.press('ArrowDown')
await state.page.keyboard.up('Shift')

// Repeat a key
for (let i = 0; i < 5; i++) await state.page.keyboard.press('ArrowDown')

resize viewport

1await state.page.setViewportSize({ width: 1280, height: 720 })

region screenshot (zoom equivalent)

1await state.page.screenshot({ path: '/absolute/path/to/region.png', scale: 'css', clip: { x: 100, y: 200, width: 400, height: 300 } })

Prefer locator-based actions over coordinates — locators are stable across scroll/resize, auto-wait for elements, and don't require screenshot round-trips that burn ~800 image tokens per cycle.

Ghost Browser integration

When running in Ghost Browser, the chrome object exposes APIs for multi-identity automation (identities, proxies, sessions). See extension/src/ghost-browser-api.d.ts for full API reference. Only works in Ghost Browser — calls fail in regular Chrome.