| name | website-browser |
| description | Start the containerized Nuxt/Docus docs website and drive it in a real browser with playwright-cli — for manual checks, UI review, debugging rendered docs (code-import / twoslash), and end-to-end testing of container/website/. |
| allowed-tools | Bash(pnpm:*) Bash(playwright-cli:*) Bash(npx:*) |
Website browser testing (Nuxt docs site + playwright-cli)
Drive the project's docs website (container/website/) in a real browser to verify rendered pages, debug console/network, and run end-to-end checks. The site is containerized (podman); playwright-cli runs on the host and reaches it through the published port. Agents start it with --isAgent on http://localhost:3100 (a human's plain dev uses :3000) — see Start the dev server.
Prerequisites
- playwright-cli is installed as a pinned root devDependency (
@playwright/cli, see Installing playwright-cli). Invoke it via pnpm exec playwright-cli ... from the repo root. The command samples below write bare playwright-cli for brevity — prefix each with pnpm exec.
- podman running (the website only ever runs inside its container — see scripts/website/site.mjs).
Start the website, then test it
The site cannot run on the host — its node_modules live only in the image. Use scripts/website/site.mjs (pnpm rtx website dev --agent) to bring it up, then point the browser at http://localhost:3100.
1. Start the dev server (agent mode, hot-reload)
As an agent, always start with --agent. It runs the site in a separate container (tsrt-website-agent) on the reserved port 3100, so you never collide with a human running pnpm rtx website dev on :3000. It's detached (no & needed) and self-stops after ~5 min idle, so a forgotten server cleans itself up. Target 3100 in every command below.
pnpm rtx website dev --agent
until curl -fsS http://localhost:3100 -o /dev/null; do sleep 2; done
echo "website up on http://localhost:3100"
Only use plain pnpm rtx website dev (foreground, :3000) if you specifically need the human-facing port — it will collide with a user's running server.
A one-shot health check with no browser is pnpm rtx website check (starts a bg server, curls :3000, stops).
2. Drive it with the browser
playwright-cli open http://localhost:3100
playwright-cli snapshot
playwright-cli click e15
playwright-cli snapshot
3. Verify rendered docs (code-import / twoslash)
The docs render imported code and twoslash type hovers. To confirm a docs page rendered them:
playwright-cli goto http://localhost:3100/your/doc/path
playwright-cli --raw eval "document.body.innerText" | grep -i "expected snippet text"
playwright-cli --raw eval "document.querySelectorAll('pre.shiki, .twoslash').length"
There is also a non-browser doc verifier: pnpm rtx website check --docs (curl/grep based).
4. Debug a page
playwright-cli console
playwright-cli requests
playwright-cli screenshot --filename=page.png
5. Tear down
playwright-cli close
podman rm -f tsrt-website-agent 2>/dev/null || true
Most-used commands
Full command reference (tabs, mouse, keyboard, storage, network, tracing, video, sessions, etc.) lives in cli-usage.md. The essentials:
playwright-cli open http://localhost:3100
playwright-cli goto <url>
playwright-cli close
playwright-cli list
playwright-cli close-all
playwright-cli snapshot
playwright-cli snapshot "#main"
playwright-cli screenshot --filename=page.png
playwright-cli click e15
playwright-cli fill e5 "user@example.com" --submit
playwright-cli type "search query"
playwright-cli press Enter
playwright-cli hover e4
playwright-cli select e9 "option-value"
playwright-cli eval "document.title"
playwright-cli eval "el => el.getAttribute('data-testid')" e5
playwright-cli --raw eval "document.body.innerText"
playwright-cli console
playwright-cli requests
Targeting elements
Use refs from snapshot (e15), or a CSS selector ("#main > button.submit"), or a Playwright locator ("getByRole('button', { name: 'Submit' })", "getByTestId('submit-button')").
Sessions
Run several independent browsers with -s=<name>:
playwright-cli -s=docs open http://localhost:3100
playwright-cli -s=docs click e6
playwright-cli -s=docs close
Installing playwright-cli
Already installed as a pinned root devDependency: @playwright/cli (Microsoft's agent CLI — distinct from the regular playwright test runner). It's in the root package.json and the lockfile, so pnpm install brings it in for everyone.
pnpm exec playwright-cli --version
Browser binaries are NOT auto-installed. This repo sets ignoreScripts: true in pnpm-workspace.yaml, so Playwright's postinstall browser download is skipped. Install Chromium once per machine:
pnpm exec playwright install chromium
Version bumps are gated by minimumReleaseAge (30 days) and must stay exact-pinned (savePrefix: ''). To upgrade, use pnpm add -D -w @playwright/cli@<version> with a version at least 30 days old, then re-run pnpm exec playwright install chromium if the bundled browser revision changed.
Deeper references
Task-specific guides (originally from the upstream playwright-cli skill) live under references/:
