Openai Playwright

Playwright CLI Skill

Drive a real browser from the terminal using playwright-cli. Prefer the bundled wrapper script so the CLI works even when it is not globally installed. Treat this skill as CLI-first automation. Do not pivot to @playwright/test unless the user explicitly asks for test files.

Prerequisite check (required)

Before proposing commands, check whether npx is available (the wrapper depends on it):

command -v npx >/dev/null 2>&1

If it is not available, pause and ask the user to install Node.js/npm (which provides npx). Provide these steps verbatim:

# Verify Node/npm are installed
node --version
npm --version

# If missing, install Node.js/npm, then:
npm install -g @playwright/cli@latest
playwright-cli --help

Once npx is present, proceed with the wrapper script. A global install of playwright-cli is optional.

Scripts and references are located under {baseDir}/.

Quick start

Use the wrapper script:

"$PWCLI" open https://playwright.dev --headed
"$PWCLI" snapshot
"$PWCLI" click e15
"$PWCLI" type "Playwright"
"$PWCLI" press Enter
"$PWCLI" screenshot

If the user prefers a global install, this is also valid:

npm install -g @playwright/cli@latest
playwright-cli --help

Core workflow

1. Open the page. 2. Snapshot to get stable element refs. 3. Interact using refs from the latest snapshot. 4. Re-snapshot after navigation or significant DOM changes. 5. Capture artifacts (screenshot, pdf, traces) when useful.

Minimal loop:

"$PWCLI" open https://example.com
"$PWCLI" snapshot
"$PWCLI" click e3
"$PWCLI" snapshot

When to snapshot again

Snapshot again after:

• navigation
• clicking elements that change the UI substantially
• opening/closing modals or menus
• tab switches

Refs can go stale. When a command fails due to a missing ref, snapshot again.

Recommended patterns

Form fill and submit

"$PWCLI" open https://example.com/form
"$PWCLI" snapshot
"$PWCLI" fill e1 "user@example.com"
"$PWCLI" fill e2 "password123"
"$PWCLI" click e3
"$PWCLI" snapshot

Debug a UI flow with traces

"$PWCLI" open https://example.com --headed
"$PWCLI" tracing-start
# ...interactions...
"$PWCLI" tracing-stop

Multi-tab work

"$PWCLI" tab-new https://example.com
"$PWCLI" tab-list
"$PWCLI" tab-select 0
"$PWCLI" snapshot

Wrapper script

The wrapper script uses npx --package @playwright/cli playwright-cli so the CLI can run without a global install:

"$PWCLI" --help

Prefer the wrapper unless the repository already standardizes on a global install.

References

Open only what you need:

• CLI command reference: references/cli.md
• Practical workflows and troubleshooting: references/workflows.md

Guardrails

• Always snapshot before referencing element ids like e12.
• Re-snapshot when refs seem stale.
• Prefer explicit commands over eval and run-code unless needed.
• When you do not have a fresh snapshot, use placeholder refs like eX and say why; do not bypass refs with run-code.
• Use --headed when a visual check will help.
• When capturing artifacts in this repo, use output/playwright/ and avoid introducing new top-level artifact folders.
• Default to CLI commands and workflows, not Playwright test specs.

When to Use

<!-- TODO: review -->

When NOT to Use

<!-- TODO: review -->

Playwright CLI Reference

Use the wrapper script unless the CLI is already installed globally:

export PWCLI="{baseDir}/scripts/playwright_cli.sh"
"$PWCLI" --help

User-scoped skills install under {baseDir}/skills (default: ~/.claude/skills).

Optional convenience alias:

alias pwcli="$PWCLI"

Core

pwcli open https://example.com
pwcli close
pwcli snapshot
pwcli click e3
pwcli dblclick e7
pwcli type "search terms"
pwcli press Enter
pwcli fill e5 "user@example.com"
pwcli drag e2 e8
pwcli hover e4
pwcli select e9 "option-value"
pwcli upload ./document.pdf
pwcli check e12
pwcli uncheck e12
pwcli eval "document.title"
pwcli eval "el => el.textContent" e5
pwcli dialog-accept
pwcli dialog-accept "confirmation text"
pwcli dialog-dismiss
pwcli resize 1920 1080

Navigation

pwcli go-back
pwcli go-forward
pwcli reload

Keyboard

pwcli press Enter
pwcli press ArrowDown
pwcli keydown Shift
pwcli keyup Shift

Mouse

pwcli mousemove 150 300
pwcli mousedown
pwcli mousedown right
pwcli mouseup
pwcli mouseup right
pwcli mousewheel 0 100

Save as

pwcli screenshot
pwcli screenshot e5
pwcli pdf

Tabs

pwcli tab-list
pwcli tab-new
pwcli tab-new https://example.com/page
pwcli tab-close
pwcli tab-close 2
pwcli tab-select 0

DevTools

pwcli console
pwcli console warning
pwcli network
pwcli run-code "await page.waitForTimeout(1000)"
pwcli tracing-start
pwcli tracing-stop

Sessions

Use a named session to isolate work:

pwcli --session todo open https://demo.playwright.dev/todomvc
pwcli --session todo snapshot

Or set an environment variable once:

export PLAYWRIGHT_CLI_SESSION=todo
pwcli open https://demo.playwright.dev/todomvc

Playwright CLI Workflows

Use the wrapper script and snapshot often. Assume PWCLI is set and pwcli is an alias for "$PWCLI". In this repo, run commands from output/playwright/<label>/ to keep artifacts contained.

Standard interaction loop

pwcli open https://example.com
pwcli snapshot
pwcli click e3
pwcli snapshot

Form submission

pwcli open https://example.com/form --headed
pwcli snapshot
pwcli fill e1 "user@example.com"
pwcli fill e2 "password123"
pwcli click e3
pwcli snapshot
pwcli screenshot

Data extraction

pwcli open https://example.com
pwcli snapshot
pwcli eval "document.title"
pwcli eval "el => el.textContent" e12

Debugging and inspection

Capture console messages and network activity after reproducing an issue:

pwcli console warning
pwcli network

Record a trace around a suspicious flow:

pwcli tracing-start
# reproduce the issue
pwcli tracing-stop
pwcli screenshot

Sessions

Use sessions to isolate work across projects:

pwcli --session marketing open https://example.com
pwcli --session marketing snapshot
pwcli --session checkout open https://example.com/checkout

Or set the session once:

export PLAYWRIGHT_CLI_SESSION=checkout
pwcli open https://example.com/checkout

Configuration file

By default, the CLI reads playwright-cli.json from the current directory. Use --config to point at a specific file.

Minimal example:

{
  "browser": {
    "launchOptions": {
      "headless": false
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  }
}

Troubleshooting

• If an element ref fails, run pwcli snapshot again and retry.
• If the page looks wrong, re-open with --headed and resize the window.
• If a flow depends on prior state, use a named --session.