Raw view: Visual Qa Testing

No invisible, zero-width, or bidi-control characters detected.

---
name: visual-qa-testing
description: >-
  Visually QA a web application in the harness's browser tool: screenshot the
  changed page, read console errors, and check for failed network requests.
  Use after making UI changes to verify they look and behave correctly.
user-invocable: true
disable-model-invocation: true
---

# Visual QA

Use this skill after UI changes to verify the result in a real browser, catch console errors, and catch failed requests.

## Runtime requirements

- A browser tool and a running dev server. See **Tool mapping** below.
- Works fully in local agents. Cloud Agents need the app runnable in the VM with browser access.
- If the environment cannot run the app or open a browser, say so and skip visual QA. Do not report a clean result you did not observe.
- For multi-viewport checks use `responsive-testing`; for theme checks use `dark-mode-testing`.

## Tool mapping

Skills describe capabilities. Map each to whatever your harness provides:

| Capability | Cursor browser MCP | Claude Code browser | Playwright MCP |
|------------|-------------------|---------------------|----------------|
| Navigate | `browser_navigate` | `navigate` | `browser_navigate` |
| Screenshot | `browser_take_screenshot` | `computer` (screenshot) | `browser_take_screenshot` |
| Accessibility tree | `browser_snapshot` | `read_page` | `browser_snapshot` |
| Click / type | `browser_click`, `browser_fill` | `computer`, `form_input` | `browser_click`, `browser_type` |
| Run JS in page | `browser_cdp` (`Runtime.evaluate`) | `javascript_tool` | `browser_evaluate` |
| Console messages | via JS shim (below) | `read_console_messages` | `browser_console_messages` |
| Network requests | via JS shim (below) | `read_network_requests` | `browser_network_requests` |

If your harness has a direct console or network tool, use it and skip the shim.

## Steps

1. **Ensure the dev server is running.** Use the command from `AGENTS.md`. If no terminal is running it, start it in the background and wait for the ready line with the localhost URL.

2. **Install the capture shim before navigating** (only when there is no direct console or network tool). Run this in the page with your run-JS capability, then navigate or reload so it captures from page load:

   ```javascript
   (() => {
     if (window.__qa) return "already installed";
     const log = { console: [], errors: [], network: [] };
     window.__qa = log;
     for (const level of ["error", "warn"]) {
       const orig = console[level].bind(console);
       console[level] = (...args) => {
         log.console.push({ level, msg: args.map(String).join(" ") });
         orig(...args);
       };
     }
     window.addEventListener("error", (e) => log.errors.push(String(e.message)));
     window.addEventListener("unhandledrejection", (e) => log.errors.push("unhandled: " + String(e.reason)));
     const origFetch = window.fetch.bind(window);
     window.fetch = async (...args) => {
       const res = await origFetch(...args);
       if (res.status >= 400) log.network.push({ url: String(args[0]), status: res.status });
       return res;
     };
     return "installed";
   })()
   ```

   Some harnesses reset page scripts on full navigation. If `window.__qa` is undefined after navigating, install the shim, then trigger the change by interacting (client-side route change, button, form) rather than reloading.

3. **Navigate to the changed route** directly, for example `/settings` rather than the home page.

4. **Screenshot** the page, full-page if the tool supports it. Look for layout breaks, missing content, wrong colors, misaligned or overlapping elements, and placeholder text that should have been replaced.

5. **Read the console.** With a direct tool, list error-level messages. With the shim, evaluate:

   ```javascript
   JSON.stringify(window.__qa, null, 2)
   ```

   Report `TypeError`, `ReferenceError`, failed imports, hydration mismatches, and unhandled rejections. Treat warnings as informational unless they relate to the change.

6. **Check network.** With a direct tool, filter for 4xx and 5xx responses and CORS failures. With the shim, inspect `window.__qa.network`. The shim only sees `fetch`, not `XMLHttpRequest` or asset loads; use the accessibility tree and screenshot to spot broken images.

7. **Interact if the change is interactive.** Read the accessibility tree first to get element refs, then click, type, or submit, and screenshot again.

8. **Report** in this shape:

   ```
   Visual QA: /settings
     Screenshot: OK (or: what is wrong)
     Console: clean (or: list)
     Network: healthy (or: list)
   ```

   Fix each issue you introduced and re-run the affected steps.

## Related skills

- `responsive-testing` — the same page at multiple viewport widths
- `dark-mode-testing` — theme token and contrast checks