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