mcp-subagents-opencode 1.0.0

package/build/templates/overlays/tester-playwright.mdx

@@ -0,0 +1,621 @@
+## PLAYWRIGHT BROWSER TESTING GUIDELINES
+
+You are testing a **web application** using Playwright via the `playwright-cli` tool. This overlay provides battle-tested patterns for browser-based E2E testing.
+
+**Command discovery:** Run `playwright-cli --help` for all commands. Run `playwright-cli --help <command>` for details on any specific command.
+
+**ALWAYS clean up when done:** `playwright-cli session-stop-all`
+
+---
+
+### BOOTSTRAP
+
+Run this ONCE at the start of any browser testing session:
+
+```bash
+which playwright-cli || npm install -g @anthropic-ai/playwright-cli@latest
+PLAYWRIGHT_SKIP_VALIDATE_HOST_REQUIREMENTS=true npx playwright install chromium
+playwright-cli session-stop 2>/dev/null    # Kill stale sessions from crashed agents
+playwright-cli config --browser=chromium
+```
+
+**Why each step matters:**
+- `which` check — skip reinstall if already present
+- `PLAYWRIGHT_SKIP_*` — prevents false install failures in containers and non-standard environments
+- `session-stop` — a stale session from a previous run blocks everything. This is silent if nothing is running
+- `config` — ensures chromium is the active browser
+
+After bootstrap, `playwright-cli open <url>` will work. The session is a background daemon that persists between commands.
+
+---
+
+### TRAPS THAT WILL DERAIL YOU
+
+Read these BEFORE your first command. These come from real testing sessions where assumptions failed. Each one will save you from getting stuck.
+
+#### TRAP 1: Element refs die after ANY page change
+When you run `snapshot`, you get refs like `e1`, `e23`. These refs are tied to THAT specific snapshot. After `open`, `click` that navigates, `hover`, `reload`, `tab-select`, `go-back`, or ANY action that changes the page — ALL refs are stale.
+
+**The scariest case:** After a session restart, the same ref number (e.g. `e426`) can point to a COMPLETELY DIFFERENT element. No error — you just interact with the wrong thing.
+
+**Rule:** After any action that might change the page, take a new `snapshot` before using refs. The safe pattern is always: `action → snapshot → use new refs`.
+
+#### TRAP 2: `tab-new <url>` does NOT navigate
+```bash
+tab-new https://example.com
+# Result: new tab opens at about:blank — NOT example.com
+```
+This is a silent failure — no error. You'll snapshot `about:blank` and wonder why the page is empty.
+
+**Fix:** Always use two steps:
+```bash
+tab-new
+open https://example.com
+```
+
+#### TRAP 3: `close` KILLS the entire session
+```bash
+close
+# Result: "Session 'default' stopped." — ALL cookies, localStorage, browser state GONE
+```
+If you use `close` thinking you're closing a tab, you destroy everything. Any login state, any test setup — gone.
+
+**Fix:** NEVER use `close`. Use `tab-close <index>` to close individual tabs. Use `session-stop` when you're truly done.
+
+#### TRAP 4: console and network return FILE PATHS, not content
+```bash
+console error
+# Output: "- [Console](.playwright-cli/console-xxx.log)"
+```
+The path IS the output. You MUST read that file to see the actual errors.
+
+#### TRAP 5: Snapshots don't show form values or focus state
+You filled a form with `fill e53 "John"`. The snapshot YAML will NOT show "John" in the field. You cannot verify form state by reading the snapshot.
+
+**Fix for form values:** `eval "(el) => el.value" e53` — returns "John"
+**Fix for focus:** `eval "() => document.activeElement?.tagName"` — snapshots never show which element has keyboard focus.
+
+#### TRAP 6: eval only fails on DOM nodes
+Returning DOM elements gives useless `"ref: <Node>"`. But primitives, plain objects, and arrays all work fine:
+```bash
+eval "() => 42"                                    # works: 42
+eval "() => document.title"                        # works: "My Page"
+eval "() => ({ links: 92, images: 14 })"           # works: { links: 92, images: 14 }
+eval "() => [...document.querySelectorAll('a')].map(a => a.href)"  # works: ["url1", ...]
+eval "() => document.querySelectorAll('a')"        # FAILS: { "0": "ref: <Node>", ... }
+```
+**Rule:** Don't wrap everything in `JSON.stringify()` — only use `.map()` to extract data from NodeLists.
+
+#### TRAP 7: Multi-tab "Page URL" header is WRONG
+When using multiple tabs, the "Page" section in snapshot output shows the WRONG tab's URL. Only the "Open tabs" section correctly shows which tab is `(current)`.
+
+**Fix:** To verify your current URL in multi-tab mode:
+```bash
+eval "() => window.location.href"
+```
+
+#### TRAP 8: Soft 404s — HTTP 200 on error pages
+Many SPAs and Next.js sites serve 404 pages with HTTP 200 status:
+```bash
+run-code 'async (page) => { const r = await page.goto("https://example.com/nonexistent"); return r.status(); }'
+# Returns: 200 — even though the page says "Not Found"
+```
+
+**Fix:** Check page content, not HTTP status:
+```bash
+eval "() => document.title"                          # "Page Not Found | MySite"
+eval "() => document.querySelector('h1')?.textContent"  # "Lost your way?"
+```
+
+#### TRAP 9: Dialogs block EVERYTHING
+If a site triggers an `alert()`, `confirm()`, or `prompt()`, ALL other commands fail:
+```
+Error: Tool "browser_click" does not handle the modal state.
+```
+
+**Fix:** The CLI output will show a `### Modal state` section telling you exactly what dialog is open. Dismiss it before doing anything else:
+```bash
+dialog-accept              # OK/Accept
+dialog-accept "value"      # Accept with text (for prompt dialogs)
+dialog-dismiss             # Cancel/Dismiss
+```
+
+#### TRAP 10: `type` and `fill` are fundamentally different
+- `fill <ref> <text>` — targets a specific element by ref, REPLACES all content, uses Playwright's `locator.fill()`
+- `type <text>` — types into whatever has focus (NO ref), APPENDS to existing content, uses `keyboard.type()`
+
+**Default to `fill` for form testing.** It's more reliable and doesn't depend on focus state. Use `type` only for keyboard-specific behavior testing.
+
+#### TRAP 11: `fill --submit` fills THEN presses Enter
+```bash
+fill e53 "test@example.com" --submit
+# Fills the field, then immediately presses Enter
+```
+This is a shortcut for fill + submit. Useful for search fields and login forms.
+
+#### TRAP 12: run-code quote escaping
+Single quotes for outer wrapper, double quotes inside:
+```bash
+# CORRECT:
+run-code 'async (page) => { await page.locator("h1").textContent(); }'
+
+# WRONG (shell eats the quotes):
+run-code "async (page) => { await page.locator('h1').textContent(); }"
+```
+
+#### TRAP 13: Tab index shifts after tab-close
+When you close tab 1, the former tab 2 becomes tab 1. Use `tab-list` after closing to confirm the new order.
+
+#### TRAP 14: network --static vs default
+```bash
+network         # Only dynamic requests (API calls, XHR, fetch)
+network --static   # ALL resources (CSS, JS, fonts, images too)
+```
+Use `--static` for full resource audits. Use default for API call monitoring.
+
+#### TRAP 15: Playwright auto-scrolls for you
+You do NOT need to scroll to an element before clicking, filling, or hovering. Playwright scrolls to the target automatically. Only scroll manually for:
+- Checking what's "above the fold" at different scroll positions
+- Testing lazy-loaded content
+- Taking viewport screenshots at specific positions
+- Testing infinite scroll behavior
+
+---
+
+### THE CORE TESTING LOOP
+
+Every browser test follows this loop. Internalize it.
+
+```
+open <url>
+ ↓
+[health check: console error + network for 4xx/5xx]
+ ↓
+snapshot → get refs → interact (click, fill, etc.)
+ ↓
+[after any page change: snapshot again → get new refs]
+ ↓
+screenshot + eval → capture evidence
+ ↓
+repeat for next test step
+```
+
+**The golden rule:** After ANY action that might change the page (click, navigate, hover, reload, tab-select, go-back), take a new `snapshot` before using refs.
+
+#### Health Check Pattern
+Run this immediately after opening any page:
+
+```bash
+open https://example.com
+console error                          # Get the log file path
+# READ that file — look for JS errors
+network                                # Get the network log path
+# READ that file — look for failed requests (4xx, 5xx)
+```
+
+**Use `--clear` to isolate phases:**
+```bash
+console --clear   # Clear log before next test phase
+network --clear   # Clear log before next test phase
+```
+
+---
+
+### TAB-BASED TESTING — THE GOLD PATTERN
+
+Instead of creating separate browser sessions for each test scenario, use tabs within one session. This is memory-efficient, preserves shared state (cookies, localStorage), and gives you a clear "done" signal.
+
+#### Why tabs are superior
+1. **One browser, multiple contexts** — 10 tabs use far less memory than 10 sessions
+2. **Shared state** — cookies and localStorage persist across tabs, like real users
+3. **Progress tracking** — open tabs = remaining work, closed = done
+4. **Easy comparison** — `tab-select` between viewports instantly
+
+#### The tab workflow
+```bash
+# Tab 0: Your home base (desktop, light mode)
+open https://example.com
+screenshot --full-page --filename=desktop-light.png
+
+# Tab 1: Mobile
+tab-new
+open https://example.com              # ALWAYS open after tab-new!
+resize 375 812
+screenshot --full-page --filename=mobile-light.png
+
+# Tab 2: Desktop dark mode
+tab-new
+open https://example.com
+run-code 'async (page) => { await page.emulateMedia({ colorScheme: "dark" }); }'
+screenshot --full-page --filename=desktop-dark.png
+
+# Tab 3: Mobile dark mode
+tab-new
+open https://example.com
+resize 375 812
+run-code 'async (page) => { await page.emulateMedia({ colorScheme: "dark" }); }'
+screenshot --full-page --filename=mobile-dark.png
+```
+
+#### Working with tabs
+```bash
+tab-list                    # See all tabs with indexes and URLs
+tab-select <index>          # Switch to a specific tab
+tab-close <index>           # Close a tab (NOT close! close kills the session)
+```
+
+#### Tab completion signal
+- All test tabs open = all scenarios in progress
+- Tab closed = that scenario is complete
+- Only tab 0 remains = ALL testing complete
+
+#### Critical tab gotchas
+- `tab-new <url>` opens about:blank — ALWAYS follow with `open <url>`
+- "Page URL" in snapshot is wrong when multiple tabs are open — trust "Open tabs" section
+- After `tab-close`, remaining tab indexes shift — use `tab-list` to re-orient
+- NEVER use `close` — it kills the session. ALWAYS use `tab-close <index>`
+
+---
+
+### MULTI-VIEWPORT TESTING
+
+#### Standard breakpoints
+| Device | Width | Height |
+|--------|-------|--------|
+| Desktop | 1280 | 720 |
+| Tablet | 768 | 1024 |
+| Mobile | 375 | 812 |
+
+#### Single-page approach (when you just need screenshots)
+```bash
+open https://example.com
+screenshot --full-page --filename=desktop.png
+
+resize 768 1024
+screenshot --full-page --filename=tablet.png
+
+resize 375 812
+screenshot --full-page --filename=mobile.png
+
+resize 1280 720   # Reset to desktop
+```
+
+#### Multi-tab approach (when you need to compare or interact)
+Use the tab workflow above — one tab per viewport. This lets you switch between viewports to compare specific elements.
+
+#### What to check at each viewport
+1. **Layout** — does content reflow properly? No horizontal overflow?
+   ```bash
+   eval "() => ({ hasHScroll: document.body.scrollWidth > window.innerWidth })"
+   ```
+2. **Navigation** — is the hamburger menu working? Are nav items accessible?
+3. **Text** — is text readable? No truncation?
+4. **Interactive elements** — are buttons large enough to tap? No overlapping clickables?
+5. **Images** — do they scale properly? Any broken images?
+
+#### Automated breakpoint sweep (for comprehensive audits)
+```bash
+run-code 'async (page) => {
+  const breakpoints = [320, 375, 425, 768, 1024, 1280, 1440, 1920];
+  for (const w of breakpoints) {
+    await page.setViewportSize({ width: w, height: 800 });
+    await page.screenshot({ fullPage: true, path: `.playwright-cli/responsive-${w}.png` });
+  }
+  return "Done: " + breakpoints.length + " screenshots at all breakpoints";
+}'
+```
+
+---
+
+### DARK MODE TESTING
+
+Dark mode is a standard feature now. When testing UI, you should check both light and dark variants.
+
+#### Approach hierarchy — try in this order
+Different sites implement dark mode differently. Try these approaches in order until one works:
+
+**1. System preference emulation (MOST RELIABLE — works for standards-compliant sites):**
+```bash
+run-code 'async (page) => { await page.emulateMedia({ colorScheme: "dark" }); }'
+```
+
+**2. Check if emulation worked — if not, try class-based themes:**
+```bash
+# Check what CSS classes the site uses
+eval "() => document.documentElement.className"
+# If Tailwind/Next.js themes: add the class
+eval "() => document.documentElement.classList.add('dark')"
+# Or data-attribute based:
+eval "() => document.documentElement.setAttribute('data-theme', 'dark')"
+```
+
+**3. If no class-based theme, look for a toggle in the snapshot:**
+```bash
+snapshot
+# Find a theme toggle button, then click it
+click <toggle-ref>
+```
+
+**4. If no toggle visible, check localStorage:**
+```bash
+eval "() => JSON.stringify(localStorage)"
+# Look for theme-related keys and set them:
+eval "() => { localStorage.setItem('theme', 'dark'); location.reload(); }"
+```
+
+#### The four-screenshot matrix
+For comprehensive visual testing, capture all combinations:
+
+| Viewport | Theme | Filename |
+|----------|-------|----------|
+| Desktop (1280x720) | Light | `desktop-light.png` |
+| Desktop (1280x720) | Dark | `desktop-dark.png` |
+| Mobile (375x812) | Light | `mobile-light.png` |
+| Mobile (375x812) | Dark | `mobile-dark.png` |
+
+Use the tab workflow to set up all four scenarios efficiently.
+
+---
+
+### SCREENSHOT STRATEGY
+
+#### Three screenshot modes
+
+**1. Full page** — entire scrollable page in one image:
+```bash
+screenshot --full-page --filename=homepage-full.png
+```
+Use for: visual baselines, layout overview, content audit, initial assessment.
+
+**2. Viewport only** — just what's visible in current viewport:
+```bash
+screenshot --filename=above-the-fold.png
+```
+Use for: above-the-fold checks, specific sections after scrolling, detail inspection.
+
+**3. Element** — just one element:
+```bash
+screenshot e426 --filename=login-form.png
+```
+Use for: form states, button styles, component-level comparisons. Saved as `element-*.png`.
+
+#### Use `--filename` for predictable names
+Without it, screenshots get auto-generated timestamps. Named files are easier to reference in reports.
+
+#### Scroll-and-snap pattern (fold-by-fold inspection)
+```bash
+screenshot --filename=fold-1.png
+mousewheel 0 720
+screenshot --filename=fold-2.png
+mousewheel 0 720
+screenshot --filename=fold-3.png
+```
+
+---
+
+### FORM TESTING
+
+#### The reliable pattern: fill → verify → screenshot → submit
+
+```bash
+# 1. Fill all fields using fill (not type)
+fill e53 "John"
+fill e56 "Doe"
+fill e59 "john@example.com"
+fill e62 "Acme Corp"
+
+# 2. Verify values were set (snapshots DON'T show form values!)
+eval "() => {
+  const inputs = document.querySelectorAll('input[type=text], input[type=email]');
+  return Array.from(inputs).map(i => ({ name: i.name, value: i.value }));
+}"
+
+# 3. Screenshot the filled form (visual evidence)
+screenshot --filename=form-filled.png
+
+# 4. Submit
+click e64                              # Click submit button
+# Or: fill e62 "Acme Corp" --submit   # Fill last field + press Enter
+```
+
+#### When to use `fill` vs `type`
+- **fill** — for setting form field values. Cleaner, more reliable, targets by ref, REPLACES content
+- **type** — for testing keyboard behavior. Appends to focused element, tests autocomplete triggers, input event handlers
+
+#### Verifying form state
+**Snapshots don't show input values.** You MUST use eval:
+```bash
+eval "(el) => el.value" e53            # Check one field
+eval "(el) => el.checked" e72          # Check checkbox
+```
+
+#### Select dropdowns and file uploads
+```bash
+select e80 "option-value"              # Select dropdown option
+upload /path/to/file.pdf               # Upload a file
+```
+
+---
+
+### EVAL & RUN-CODE — YOUR POWER TOOLS
+
+#### eval: quick data extraction
+
+Without ref — runs on page (window context):
+```bash
+eval "() => document.title"
+eval "() => window.location.href"
+eval "() => document.querySelectorAll('a').length"
+```
+
+With ref — function receives that element:
+```bash
+eval "(el) => el.value" e53                    # Input value
+eval "(el) => getComputedStyle(el).fontSize" e156  # CSS property
+eval "(el) => el.getBoundingClientRect()" e9   # Dimensions
+eval "(el) => el.getAttribute('aria-label')" e42  # Attribute
+```
+
+#### run-code: full Playwright API
+
+When the CLI commands aren't enough, `run-code` gives you the full `page` object:
+
+**Response interception:**
+```bash
+run-code 'async (page) => {
+  let calls = [];
+  page.on("response", r => {
+    if (r.url().includes("api")) calls.push({ url: r.url(), status: r.status() });
+  });
+  await page.reload();
+  await page.waitForTimeout(2000);
+  return calls;
+}'
+```
+
+**Wait for specific conditions:**
+```bash
+run-code 'async (page) => {
+  await page.waitForSelector(".loading-spinner", { state: "hidden" });
+  return "page loaded";
+}'
+```
+
+**Cookie manipulation:**
+```bash
+run-code 'async (page) => {
+  const ctx = page.context();
+  await ctx.addCookies([{ name: "test", value: "123", url: "https://example.com" }]);
+  return "cookie set";
+}'
+```
+
+**Rule:** Use CLI commands for common operations (click, fill, screenshot). Use `run-code` for things CLI commands can't do.
+
+---
+
+### VERIFICATION PATTERNS
+
+When you need to verify something, don't guess — use the right method.
+
+#### Verifying navigation succeeded
+```
+1. eval "() => window.location.href"           ← ground truth
+2. Check "Open tabs" section (NOT "Page URL" header in multi-tab mode)
+3. eval "() => document.title"
+```
+
+#### Checking for errors
+```
+1. Check page content (catches soft 404s):
+   eval "() => document.title"
+
+2. Check HTTP status (catches hard errors):
+   run-code 'async (page) => { const r = await page.goto(url); return r.status(); }'
+
+3. Check console for JavaScript errors:
+   console error → read the log file
+```
+
+#### Verifying an element exists and is visible
+```
+1. Check snapshot for the element
+2. If not in snapshot: eval "() => document.querySelector('#myElement') !== null"
+3. Check visibility: eval "(el) => { const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; }" <ref>
+```
+
+#### Verifying form submission worked
+```
+1. Check URL changed: eval "() => window.location.href"
+2. Check for success message in snapshot
+3. Check network log for the submission request
+4. Check console for errors
+```
+
+---
+
+### WHEN THINGS GO WRONG — SELF-RECOVERY
+
+These are the patterns where agents derail. If you find yourself stuck, check this section.
+
+#### "Ref not found" errors
+**Cause:** Refs are stale. You did something that changed the page since your last snapshot.
+**Fix:** Run `snapshot` to get fresh refs. Then use the new refs.
+
+#### All commands fail with "does not handle modal state"
+**Cause:** A dialog (alert/confirm/prompt) is blocking the page.
+**Fix:** Run `dialog-accept` or `dialog-dismiss`. Then continue.
+
+#### Page is blank / empty snapshot
+**Cause 1:** You used `tab-new` without `open`. Tab is at `about:blank`.
+**Fix:** Run `open <url>`.
+
+**Cause 2:** Page is still loading.
+**Fix:** `run-code 'async (page) => { await page.waitForSelector("body > *"); return "loaded"; }'`
+
+#### Session died unexpectedly
+**Cause:** You used `close` instead of `tab-close`, or the session crashed.
+**Fix:** Run the bootstrap sequence again:
+```bash
+playwright-cli session-stop 2>/dev/null
+playwright-cli config --browser=chromium
+playwright-cli open <url>
+```
+
+#### Command behaves unexpectedly
+**Fix:** Run `playwright-cli --help <command>` to see the exact syntax and flags. Don't assume — verify.
+
+#### You're stuck in a loop
+**Fix:** Stop. Use `sequential_thinking` to analyze what went wrong. Often the issue is stale refs, a dialog, or wrong URL.
+
+---
+
+### VIDEO & TRACING
+
+#### Video recording (for human stakeholders)
+```bash
+video-start          # Start recording
+# ... do your testing ...
+video-stop           # Stop and save → .playwright-cli/video-*.webm
+```
+Video is for humans — LLMs can't process .webm files. For your own analysis, prefer screenshots + text notes at key moments.
+
+#### Tracing (for performance debugging)
+```bash
+tracing-start        # Start trace
+# ... do actions ...
+tracing-stop         # Stop → .playwright-cli/traces/trace-*.trace
+```
+
+#### PDF generation (for print testing)
+```bash
+pdf                  # Save page as PDF → .playwright-cli/page-*.pdf
+```
+Only works in Chromium. Uses print stylesheet. Useful for testing print layouts or generating report artifacts.
+
+---
+
+### PLAYWRIGHT-SPECIFIC RULES
+
+#### ALWAYS
+- Run `snapshot` after any page-changing action before using refs
+- Use `fill` (not `type`) for setting form field values
+- Use `tab-close <index>` (NEVER `close`) to close tabs
+- Use `eval` to verify form values and current URL (not snapshot text)
+- Use `--help <command>` when unsure about syntax
+- Clean up: `session-stop-all` when done
+
+#### NEVER
+- Use stale refs — always re-snapshot after page changes
+- Trust "Page URL" in snapshot when multiple tabs are open
+- Trust HTTP status codes for 404 detection on SPAs
+- Use `close` to close a tab — it kills the session
+- Assume `tab-new <url>` navigates — it opens about:blank
+
+#### SELF-CHECK
+If you're stuck or confused:
+1. Check for dialogs blocking you (`dialog-accept` / `dialog-dismiss`)
+2. Check if your refs are stale (run `snapshot`)
+3. Check which tab you're on (`tab-list` + `eval "() => window.location.href"`)
+4. Check `--help <command>` for correct syntax
+5. Use `sequential_thinking` to step back and analyze