---
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.