expect

# Expect You verify code changes in a real browser before claiming they work. No browser evidence, no completion claim. Use the expect MCP tools (`open`, `playwright`, `screenshot`, etc.) for all browser interactions. Do not use raw browser tools (Playwright MCP, chrome tools, etc.) unless the user explicitly asks. ## Subagent Usage Browser verification is best run in a subagent (Task tool) or background shell so the main thread stays free for code edits. This keeps the conversation responsive — you can fix code while the browser test runs in parallel. Strongly prefer launching a subagent for browser work, especially when the test involves multiple steps or long interactions. If the test is truly trivial (single screenshot check), inline is acceptable. ## Resuming Browser State Before opening a new browser, check if one is already running. Use `browser_tabs` (action `list`) or the expect `screenshot` tool to see if a session is still active. If a tab is already open at the target URL, reuse it — don't close and reopen. When re-verifying after a code fix, prefer navigating or refreshing the existing session over starting from scratch. ## Compounding The `playwright` tool takes a `code` string with `ref()` to resolve snapshot refs to Locators. One call can do an entire interaction — fills, clicks, AND data collection. Use that. **BAD — 5 tool calls:** ``` screenshot (snapshot) playwright: await ref('e3').fill('Jane') screenshot (snapshot) ← WHY? page didn't change playwright: await ref('e5').fill('jane@example.com') playwright: await ref('e7').click() ``` **GOOD — 2 tool calls:** ``` screenshot (snapshot) playwright (snapshotAfter=true): await ref('e3').fill('Jane'); await ref('e5').fill('jane@example.com'); await ref('e7').click(); return { title: await page.title(), url: page.url(), errors: (await page.$$('.error')).length }; ``` Use `return` to collect data. Response: `{ result: <value>, resultFile: "<tmp path>", snapshot: { tree, refs, stats } }`. The `resultFile` persists until `close` — read or grep it later. Without a return value, responds `"OK"` (or just the snapshot if `snapshotAfter=true`). **Re-snapshot only across DOM boundaries.** Fills and hovers don't change page structure — keep using the same refs. Navigation, submit, dialog open/close DO change structure — set `snapshotAfter=true`. ## Writing Instructions **Bad:** `"Check that the login form renders on http://localhost:5173"` **Good:** `"Submit the login form empty, with invalid email, with wrong password, and with valid credentials. Verify error messages, redirect on success, and console errors on http://localhost:5173"` ## Before Claiming Completion 1. Verify in a browser with adversarial instructions. 2. Read the full output — check failures, accessibility, performance. 3. If ANY failure: fix the code, re-verify immediately. No asking, no waiting. 4. Repeat until 0 failures, then state the claim with passing evidence. ## Rationalizations - "I'll run the browser test inline, it's quick" — Probably not. Launch a subagent so you can keep editing code in parallel. Only skip the subagent for a single screenshot sanity check. - "I'll open a fresh browser to re-test" — Check for an existing session first. If the tab is still open, refresh or navigate — don't waste time on a cold start. - "I'll make one `playwright` call per action" — No. Whole sequence in one call. - "I need a snapshot between fills" — No. Fills don't change DOM. Batch them. - "Let me snapshot to see what changed" — Did the page navigate or submit? No? Use `snapshotAfter=true` on the action that does.