53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
---
|
|
name: browser-testing
|
|
description: Use when asked to test a web UI in a real browser — verify a page renders, click through a user flow, check a login/form works, confirm a homelab service's web interface is up, or do end-to-end/browser testing. Drives the homelab Playwright MCP server (headless Chromium on 10.10.20.39). Do NOT use for scraping/extracting page content (that's firecrawl on the webtools box).
|
|
---
|
|
|
|
# Browser testing with the Playwright MCP
|
|
|
|
Interactive browser testing is done through the **Playwright MCP server** — a real
|
|
headless Chromium the homelab runs for exactly this. Prefer it over guessing whether a
|
|
UI works, and over `curl` when the check needs a rendered page, JS, clicks, or forms.
|
|
|
|
## Prerequisite: the MCP must be connected
|
|
|
|
The Playwright tools only exist if this machine has the MCP registered. Check with `/mcp`
|
|
(look for `playwright`) or `claude mcp list`. If it's missing, tell the user to run:
|
|
|
|
```bash
|
|
claude mcp add --transport http playwright https://playwright.home.sneakygeek.net/mcp -s user
|
|
```
|
|
|
|
(Full setup/verification: `docs/playwright-mcp.md`.) Do not try to install or launch a
|
|
browser locally — testing happens on the remote box, not this host.
|
|
|
|
## How to test (the loop)
|
|
|
|
1. **Navigate** to the target URL.
|
|
2. **Snapshot first, screenshot second.** Take an *accessibility snapshot* to read page
|
|
structure/text and get element refs — it's the source of truth and far cheaper than
|
|
pixels. Only take a screenshot when the user needs a visual, or to debug layout.
|
|
3. **Act on refs** from the snapshot (click, fill, select, press), then **re-snapshot** to
|
|
observe the result. Don't assume an action worked — verify from the new state.
|
|
4. **Assert against observed state**, not assumptions: confirm the expected text/element is
|
|
present, the URL changed, the error is gone, etc. Report what you actually saw.
|
|
5. **Wait explicitly** for slow/async pages (wait for a selector/text) instead of retrying
|
|
blindly. Ad-heavy or SPA pages need a beat after navigation.
|
|
|
|
## Homelab specifics
|
|
|
|
- Internal services use `*.home.sneakygeek.net` (e.g. `todo.home.sneakygeek.net`,
|
|
`grafana.home.sneakygeek.net`, `gatus.home.sneakygeek.net`). These resolve only via the
|
|
internal AdGuard DNS — the MCP box is on VLAN 20 and can reach them.
|
|
- **Headless Chromium only** (the Docker image supports nothing else) — don't request
|
|
firefox/webkit/headed mode.
|
|
- Sessions cost memory (each is a Chromium; the container is capped at 4 GB). When done,
|
|
**close pages/contexts** you opened so the box stays clean for the next run.
|
|
- Credentials: ask the user for logins; never hardcode. Vaultwarden holds real secrets.
|
|
|
|
## When NOT to use this
|
|
|
|
- **Just need page content / markdown / a crawl?** That's **firecrawl** (`http://10.10.20.37:3002`,
|
|
or `firecrawl.home.sneakygeek.net`), not this. Playwright MCP is for *interactive* testing.
|
|
- A plain reachability/HTTP-status check is fine with `curl` — don't spin up a browser for it.
|