visual-web-qa

Visual Web QA

Verify rendered behavior in a browser. Never claim a rendered change looks correct from code alone, and never claim more than the captured evidence shows.

Resolve The Target

Use this order:

1. User-provided URL
2. Running local development server
3. Repo-native server such as pnpm dev
4. Preview deployment
5. Production as an explicitly requested or read-only baseline
6. file:// output only when the site renders correctly without a server

Do not check production and claim an unmerged change is present. If no valid target is reachable, report blocked and name the missing server, preview, build, or authentication requirement.

Choose Evidence

• Stable states such as layout, CSS, typography, themes, breakpoints, menus, modals, and focus: take screenshots. Take one for each relevant theme or breakpoint.
• Temporal behavior such as loading, animation, transitions, and interaction sequences: record a short video. A redundant screenshot is not necessary.
• Exact text, route, ARIA, or attributes: use a DOM check. A DOM check supports visual evidence. It does not replace visual evidence when the user asks how something looks.

Check one to four representative pages or states, with the viewport-theme combinations most likely to show the issue. Do not build an exhaustive matrix unless the user asks for it.

agent-browser --session visual-qa screenshot /tmp/visual-qa.png
agent-browser --session visual-qa screenshot --full /tmp/visual-qa-full.png
agent-browser --session visual-qa screenshot --annotate /tmp/visual-qa-issue.png

Capture Reliable State

Wait for a signal that proves progress, not an arbitrary delay:

• wait --url "**/expected-path" or wait --text "Expected text" for route and content changes.
• wait --load networkidle only when the action makes real network requests.
• wait 100 only for an animation that has no completion signal.

Run snapshot -i after navigation or significant DOM changes before you use element refs.

For initial loading behavior, start recording before the first navigation:

agent-browser --session visual-qa set viewport 1440 900
agent-browser --session visual-qa record start /tmp/visual-qa-load.webm "$URL"
agent-browser --session visual-qa wait --load networkidle
agent-browser --session visual-qa record stop

For post-load interactions, explore first, then start recording. record start creates a fresh browser context and reloads the page, so discard earlier refs and run snapshot -i again before interacting. Stop recording as soon as the target behavior is captured. Never end a QA run with an active recording.

Share Evidence

Send every artifact the user should receive with sendFiles. Claim an artifact was shared only when sendFiles succeeds in this turn. If delivery fails or sendFiles is unavailable, report the error and the saved paths.

Attach Evidence To Pull Requests

When the QA is for a pull request, attach screenshots to the PR when you can. Reviewers then see the rendered result without the Slack thread.

1. Open each screenshot with viewImage and check it for sensitive data. See Protect Sensitive Data.
2. If a screenshot shows sensitive data, do not publish it. Recapture it with the data out of view, or skip it.
3. Publish each safe screenshot with publishImage. The URL is public to anyone who has it.
4. Embed the returned URLs in the PR body or a PR comment, with one short caption for each page, state, viewport, or theme.

• publishImage accepts only images. Do not publish videos. Describe the temporal result in text instead.
• Do not link private Slack files or conversation attachment URLs in the PR.
• If you publish an image by mistake, remove it with unpublishImage and remove it from the PR.
• If publishImage or the PR update fails, report the failure and do not claim the PR has screenshots.

Protect Sensitive Data

Never capture or share credential entry, session tokens, customer data, or unrelated sensitive UI state. Apply this rule with more care to published images, because their URLs are public. Look for real emails, names, avatars, customer org or project names, tokens, API keys, DSNs, and private URLs. Seeded or fake local data is safe. If reaching the target requires exposing that data, use an existing safe authenticated session or report the authentication requirement as a limitation or blocker.

Report The Result

• Target: exact URL verified
• Evidence: screenshots, videos, and state checks gathered, with why each was chosen
• Result: pass, issues found, or blocked
• Findings: specific rendered behavior observed
• Limitations: requested pages, states, viewports, or themes not verified

Use pass only when the captured evidence matches the requested behavior without an obvious scoped regression. Use issues found for broken layout, incorrect motion, flicker, missing assets, or invalid states. Use blocked when no safe reachable target exists.