taproot

 1---
 2name: playwright
 3description: Drive a real browser for screenshots, page inspection, and UI verification using the playwright-cli command line tool (not an MCP). Invoke when asked to open a page, click through a flow, take a screenshot, inspect selectors, verify rendered UI, or generate a Playwright test from a recorded flow. Token-efficient: state is saved to disk and you read only what you need, instead of an MCP streaming whole accessibility trees into context.
 4---
 5
 6# Browser automation with playwright-cli
 7
 8We use Microsoft's `playwright-cli` (the `@playwright/cli` package) instead of the
 9Playwright MCP server. The MCP streams the full accessibility tree and screenshot bytes
10into context on every step (~4x the tokens). The CLI writes that state to disk and lets
11you read only the snapshot lines you need. Same browser, far cheaper context.
12
13The webdev container already ships Playwright Chromium at `/opt/playwright-browsers`
14(symlinked to `/opt/google/chrome/chrome`), so no extra browser download is needed.
15
16## Setup (one-time, per machine)
17
18```bash
19playwright-cli --version || npm install -g @playwright/cli
20```
21
22If it is missing and `npm` is unavailable, install via the project's JS toolchain or
23add it to the webdev Dockerfile (see `~/code/taproot/containers/webdev/Dockerfile`,
24near the existing Playwright Chromium step).
25
26## Core workflow
27
28```bash
29playwright-cli open http://localhost:8000/login   # add --headed to watch it visually
30playwright-cli snapshot                            # accessibility tree + element refs
31playwright-cli click <ref>                         # refs come from the latest snapshot
32playwright-cli type "hello"
33playwright-cli press Enter
34playwright-cli check <ref>
35playwright-cli screenshot                          # PNG written to disk
36```
37
38After each command the CLI prints the current page URL, title, and a path to the
39snapshot file. **Read that snapshot file to get element refs for the next command** do
40not guess refs.
41
42## Where output lands
43
44- Snapshots: `.playwright-cli/page-<timestamp>.yml` (the accessibility tree with refs).
45- Screenshots: PNG files on disk, opened with the Read tool to view.
46
47Read these files on demand rather than dumping them, which is the reason for using
48the CLI over the MCP.
49
50## Notes for this workspace
51
52- Every app in this workspace serves on **port 8000** in dev (`make run`). Log in at
53  `/login` where the app has auth (analytics, status, finance).
54- Good uses here: confirm a rendered template change, screenshot a chart/map/PDF page,
55  walk a multi-step form, or record a flow to scaffold a test.