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.