🎯 What You Will Learn
Install the CLI, open a real browser, inspect snapshots, interact with element refs, capture screenshots, record traces, and troubleshoot stale refs.
- Install and verify Playwright CLI
- Open a headed browser in a named session
- Read a snapshot and use its current element refs
- Complete and verify a TodoMVC browser workflow
Choose Your CLI Setup
Codex users can run the bundled wrapper without installing a global command. Other readers can install Playwright CLI globally.
# Codex wrapper
PWCLI="$HOME/.codex/skills/playwright/scripts/playwright_cli.sh"
"$PWCLI" --help
# Portable global alternative
npm install -g @playwright/cli@latest
playwright-cli --help
playwright-cli install-browser chromiumReady: The help output should list open, snapshot, click, type, screenshot, and tracing commands.
Open a Headed Browser
Use a named session so every later command controls the same browser. Headed mode lets you watch the automation.
mkdir -p output/playwright/tutorial
cd output/playwright/tutorial
"$PWCLI" -s=tutorial open https://demo.playwright.dev/todomvc/ --headedCapture the First Snapshot
A snapshot describes the accessible page and assigns temporary refs to interactive nodes. Capture it before every new interaction sequence.
"$PWCLI" -s=tutorial snapshot- heading "todos" - textbox "What needs to be done?" [ref=eX]
Replace eX: Use the actual textbox ref from your live snapshot. Documentation cannot predict the ref generated for your page.
Add a Todo Item
Click the current textbox ref, type a task, and submit with Enter.
- Replace eX with the textbox ref from the latest snapshot.
- Focus the textbox.
- Type the task text.
- Press Enter to submit.
"$PWCLI" -s=tutorial click eX
"$PWCLI" -s=tutorial type "Learn Playwright CLI"
"$PWCLI" -s=tutorial press EnterVerify the Updated Page
Take another snapshot after the DOM changes and search it for the exact todo text.
"$PWCLI" -s=tutorial snapshot
"$PWCLI" -s=tutorial find "Learn Playwright CLI"- listitem: - checkbox "Toggle Todo" - text "Learn Playwright CLI" - text "1 item left!"
Recover from a Stale Reference
Refs can change after navigation, re-rendering, modals, and tab switches. Re-snapshot instead of guessing or forcing an old target.
"$PWCLI" -s=tutorial snapshot
"$PWCLI" -s=tutorial find "Toggle Todo"
"$PWCLI" -s=tutorial click eNEWRef lifetime: A ref is a handle to the latest observed page state, not a permanent selector.
Capture Visual Evidence
Save a viewport screenshot after the workflow reaches the expected state. You can also capture one current element or export the page as PDF.
"$PWCLI" -s=tutorial screenshot
"$PWCLI" -s=tutorial screenshot eCURRENT
"$PWCLI" -s=tutorial pdfRecord a Debug Trace
Start tracing immediately before a suspicious action, reproduce it once, then inspect console and request data.
"$PWCLI" -s=tutorial tracing-start
"$PWCLI" -s=tutorial snapshot
"$PWCLI" -s=tutorial click eCURRENT
"$PWCLI" -s=tutorial tracing-stop
"$PWCLI" -s=tutorial console warning
"$PWCLI" -s=tutorial requests
"$PWCLI" -s=tutorial closeRecap
- Use a named session to preserve browser state across commands.
- Snapshot before interacting and after meaningful UI changes.
- Use only current element refs from the active page.
- Capture screenshots and focused traces as evidence.
Checkpoint: You have completed the workflow and have a repeatable reference for your next Playwright project.