| name | ui-verify |
| description | Verify a user-facing flow in a real browser via the Playwright MCP server — after a change to the app shell, routing, a shared UI primitive, or any flow whose exit criterion is "user-facing", or when asked to confirm a UI change actually works (not just that tests pass). Drives navigate → snapshot → interact → assert. Starter skill — adapt the blocking-failure list to the target repo. |
ui-verify
Confirm a UI/UX flow actually works in a live browser. Tests prove logic; this proves the control is
reachable and behaves. It is the live-runtime / browser check named in
docs/agent_rules/testing.md (§ 5 "UI or Runtime Smoke-Checks").
Mechanism: the Playwright MCP server, pinned in .mcp.json. Tools are exposed as
mcp__playwright__browser_*. Use browser_snapshot (accessibility tree) to locate elements and
drive interactions — it's structured and cheap. But acceptance of a user-facing criterion is
judged on the rendered screenshot (browser_take_screenshot), not the snapshot: a clean DOM and
an empty console can coexist with an unusable screen (the canonical miss rendered an error inside
a cross-origin iframe that no DOM/accessibility snapshot could see). The seam and the render are
different facts.
This is a starter skill: the steps are generic; replace the placeholder blocking-failure list
below with the target repo's real list (its docs/agent_rules/frontend.md). A docs-only or
backend-only repo doesn't need it — delete it.
When to use
- A change touched the app shell, primary navigation, routing, or a shared UI primitive.
- A change touched an interactive flow (forms, drag, live recompute, real-time updates).
- You're asked to verify/confirm a UI fix works, or to screenshot the running app.
- An implementation step's exit criterion is "user-facing change".
Skip for pure logic / data / parser changes with no rendered surface — a unit or integration test is
the cheaper reliable surface there.
Steps
- Start the app (or confirm it's running) and get its local URL (e.g. the dev server).
- Navigate —
browser_navigate to the route under test.
- Snapshot —
browser_snapshot to capture the accessibility tree; locate the elements you'll
touch (and their ref= handles).
- Interact — drive the real flow:
browser_click, browser_type, browser_fill_form,
browser_drag, browser_select_option, browser_press_key.
- Assert — re-snapshot to check the expected structural change, then take a screenshot and
judge the pixels for the user-facing claim; pull
browser_console_messages for errors and
browser_network_requests when the network path matters. No rendered evidence ⇒ the user-facing
criterion is not verified.
- Report — record what you drove and observed (see
docs/agent_rules/testing.md reporting).
Close with browser_close.
What to check (replace with this repo's blocking failures)
- The app shell renders and primary navigation / routing works.
- No critical console errors after the change (
browser_console_messages).
- The control you changed is actually usable in the live app, not just present in the DOM.
[repo-specific blocking failure — e.g. a perf budget, a no-network-roundtrip rule, a required state on every figure].
What this skill does NOT do
- It does not replace unit / integration tests — it's the live-runtime layer on top of them.
- It does not assert numeric / business correctness; targeted tests own that. Here you confirm the
result is shown and wired, not that it's right.
Reference
- Tooling config:
.mcp.json · .claude/README.md (MCP servers)
- Conventions:
docs/agent_rules/frontend.md, docs/agent_rules/testing.md
