10.5ADR-005: Snapshot-and-Screenshot Debugging

Context

When a test fails, the agent needs to understand what went wrong. Options:

1. HTML dump of the page
2. Screenshot capture
3. Accessibility snapshot
4. All of the above

Decision

Capture screenshot + YAML snapshot on every failure. Raw DOM via eval on request.

# On failure, the agent executes:
playwright-cli screenshot     # PNG lands in .playwright-cli/ — copy into failures/
playwright-cli snapshot       # YAML a11y summary — copy into failures/
playwright-cli eval "location.href"   # current URL into the failure record

Rationale

• Screenshots provide visual context for humans reviewing failures
• The YAML snapshot provides semantic context the agent can reason about — roles, names, refs — far more useful than a raw text dump
• Both are files: they cost nothing until someone (human or agent) reads them
• Raw HTML is rarely needed but available via playwright-cli eval "document.documentElement.outerHTML"
• Where a Playwright trace is available (test-runner and healer runs), archive it too — it includes every action, before/after snapshots, console output, and since 1.60 the HAR network capture