play

name: play description: Run Playwright scripts and inspect durable browser sessions with flat agent-first commands context: fork

play

Run Playwright scripts with zero boilerplate. No imports, no browser lifecycle, no await keywords for the built-in globals.

Use play in two modes:

1. One-shot scripts for quick navigation, assertions, screenshots, and extraction.
2. Named sessions for multi-step browser work and real page-debugger control across commands.

Quick Start

play 'goto("https://example.com"); log(title())'

One-Shot Input Modes

# Inline code
play 'goto("https://example.com"); log(text("h1"))'

# Script file
play check-homepage.play.ts

# Pipe / heredoc
echo 'goto("https://example.com"); screenshot()' | play

play << 'EOF'
goto("https://example.com")
assert(text("h1") === "Example Domain", "heading correct")
EOF

Named Sessions

Use named sessions when the browser needs to stay alive across commands. Each session is also persisted under .play/sessions/<session-id>/, so inspection still works after the worker exits.

play do auto-opens the session if needed. Pass --headed and --devtools on the first do when you want a visible Chromium session.

play do agent1 'goto("https://example.com")' --headed --devtools
play console agent1
play events agent1 --limit 20
play net agent1 --limit 20
play dom agent1
play status
play close agent1

Use play open only when you want to start the browser before sending actions:

play open agent1 --headed --devtools
play do agent1 'goto("https://example.com"); click("More information")'
play close agent1

Capture And Probe

Use play capture to run one action batch and get only the console emitted during that batch:

play capture agent1 'goto("http://localhost:3000"); click("Save")'

Use play probe to install temporary session-lifetime instrumentation without editing app code:

play probe agent1 'window.__lastSave' --file app.js --line 120
play probes agent1
play unprobe agent1

Debugger Workflow

play debug still handles live page-debugger control for pause/step/eval/source work.

Key debugger commands:

• play debug status <name>
• play debug pause <name>
• play debug continue <name>
• play debug step-over <name>
• play debug step-into <name>
• play debug step-out <name>
• play debug eval <name> '<expr>'
• play debug query <name> '<expr>'
• play debug source <name> [file start end]

Use -q with debugger status and step commands for one-line summaries instead of JSON blobs.

For inspection, prefer the flat commands:

• play console <name>
• play events <name>
• play net <name>
• play dom <name> [selector]
• play capture <name> '<actions>'
• play probe <name> ...
• play probes <name>
• play unprobe <name> [probeId]

Inside scripts, browser console output is buffered separately from log(...). Use consoleCursor(), consoleSince(cursor), capture(async () => ...), consoleLogs(limit?), and clearConsole() when you need precise temporary inspection.

Common Examples

# Navigate and extract
play 'goto("https://example.com"); log(url()); log(text("h1"))'

# Work against a detected local dev server
play 'goto(); click("Sign in"); wait("**/dashboard"); log(title())'

# Screenshot or PDF
play 'goto("https://example.com"); screenshot("homepage.png")'
play 'goto("https://example.com"); pdf("page.pdf")'

# Assertions with exit codes
play 'goto("https://example.com"); assert(visible("h1"), "heading visible")'

# Use the raw Playwright page object when needed
play 'goto("https://example.com"); const resp = await page.request.get("/api/health"); log(await resp.text())'

Globals

All built-in globals are auto-awaited.

Selector Resolution

click("Submit") and similar helpers resolve selectors in this order:

1. CSS fast-path
2. XPath
3. ARIA role
4. Label or placeholder
5. Text
6. Test ID
7. Tag fallback

fill() prefers labels and placeholders. click() prefers roles.

Options