playwright

name	playwright
description	Use when the task requires terminal-driven real-browser automation with `playwright-cli`: navigation, form filling, snapshots, screenshots, data extraction, or UI-flow debugging. Do not use for adding project E2E tests, Playwright test files, or `@playwright/test` dependencies; use `playwright-e2e-testing` for that.

Playwright CLI Skill

Drive a real browser from the terminal using playwright-cli. In Project Flow containers, prefer the image-provided global CLI; use the bundled wrapper only as a fallback in other environments. Treat this skill as CLI-first automation. Do not pivot to @playwright/test unless the user explicitly asks for test files.

Project Flow runtime boundary

Playwright is platform infrastructure in Project Flow. It is not a dependency that every dynamically selected target project must carry.

• Check CLI availability with command -v playwright-cli and playwright-cli --help.
• Do not use require.resolve('@playwright/test') to decide whether browser automation is available.
• Do not inspect a target project's package.json, lockfile, or node_modules for the platform runtime.
• Do not install Playwright into a target project or modify its dependency files as part of design review.
• If a direct Node API script is explicitly needed, the container exposes global @playwright/test through NODE_PATH; resolve it without changing the target project.
• If neither the global CLI nor this skill's wrapper is available in a managed Project Flow container, stop with PLAYWRIGHT_PLATFORM_RUNTIME_UNAVAILABLE instead of installing packages into the target repo.
• playwright-cli writes .playwright-cli state in its current directory. For Project Flow, create and change into a run-scoped directory under the PRD artifactDir before browser commands; never execute it from targetProjectRoot.

Prerequisite check (required)

First prefer the managed runtime:

if command -v playwright-cli >/dev/null 2>&1; then
  playwright-cli --help
fi

Only when the global CLI is unavailable and the wrapper is needed, check whether npx is available:

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. Outside managed Project Flow containers, a global install of playwright-cli is optional.

Skill path (set once)

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"

User-scoped skills install under $CODEX_HOME/skills (default: ~/.codex/skills).

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 "[e-mail]"
"$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 image-provided global CLI in Project Flow. Otherwise prefer the wrapper unless the environment 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.
• Never add Playwright dependencies to a target project solely to run Project Flow preview or design QA.