Visual Testing

Overview

Visual testing IS seeing the rendered page, not reading the code. Code review finds logic bugs; screenshots find layout breaks, overflow issues, color contrast problems, and missing elements.

Core principle: If you haven't taken a screenshot of a page and looked at it with your own eyes, you haven't tested that page. Period.

CRITICAL: Visual testing is NOT code review. Reading component code, checking API responses, or verifying TypeScript types does NOT count as visual testing. Only a screenshot reveals:

• Overlapping elements, truncated text, broken layouts
• Color/contrast issues, missing icons, misaligned items
• Overflow, scrollbar behavior, responsive breakpoints
• Animation glitches, loading state flicker, empty state rendering

Prerequisites

• browser-use MCP must be configured and connected — verify with browser_list_sessions or a quick browser_navigate + browser_screenshot before starting
• Dev server must be running — start with npm run dev (or equivalent)
• If browser-use fails to connect, check: is a browser instance available? (Chromium/Chrome with CDP enabled)

When to Use

Use when:

• You implemented a new UI component or page
• You changed CSS, Tailwind classes, or layout logic
• You're asked to "test" or "verify" a page works
• Before merging any frontend change
• A user reports a visual bug

Do NOT use when:

• Testing backend-only API changes (use unit/integration tests)
• The change has zero visual impact (e.g., refactoring a utility function)

Core Pattern

┌─────────────────┐
│ Page to test?   │
└────────┬────────┘
         │
    ┌────▼─────────────────────┐
    │ 1. Navigate with         │
    │    browser_navigate       │
    └────┬─────────────────────┘
         │
    ┌────▼─────────────────────┐
    │ 2. Screenshot + inspect  │
    │    browser_get_state      │
    └────┬─────────────────────┘
         │
    ┌────▼─────────────────────┐
    │ 3. Does it look right?   │─── NO ──► File bug on worktree
    └────┬─────────────────────┘              then fix
         │ YES
    ┌────▼─────────────────────┐
    │ 4. Test interactions:    │
    │   - Click buttons        │
    │   - Type in inputs       │
    │   - Scroll, resize       │
    │   - Hover, open modals   │
    └────┬─────────────────────┘
         │
    ┌────▼─────────────────────┐
    │ 5. Screenshot again      │
    │    after each interaction│
    └────┬─────────────────────┘
         │
    ┌────▼─────────────────────┐
    │ 6. Report with screenshots│
    │    as evidence            │
    └──────────────────────────┘

Testing Workflow

Step 1: Two-Source Test Plan

Before opening the browser, create a test plan from TWO sources:

Source A — User Description (if provided):

• What should the user be able to do on this page?
• What are the critical user journeys?

Source B — Code Inspection (read the component files):

• What UI elements exist? (buttons, inputs, modals, tabs)
• What states should be tested? (empty, loading, populated, error)
• What interactions exist? (click, hover, drag, scroll)

Merge A + B into a checklist. Do not skip elements found in code just because the user didn't mention them.

Step 2: Visual Baseline

browser_navigate → URL
browser_screenshot → full_page: true
browser_get_state → include_screenshot: true

What to check in the screenshot:

• Page renders without blank/white screen
• All expected elements are visible
• Text is not truncated or overlapping
• Colors and spacing look intentional
• No horizontal scrollbar on desktop viewport

Step 3: Interaction Testing

For each interactive element found in Step 1:

1. Get state → find element index via browser_get_state
2. Interact → browser_click or browser_type
3. Screenshot → verify visual result
4. Assert → did it behave as expected?

Step 4: Bug Reporting

If something looks wrong:

1. Screenshot the issue (evidence, not description)
2. Describe the expected behavior
3. Describe the actual behavior
4. File on the worktree — do NOT fix on main branch

Quick Reference

Common Mistakes

Real-World Impact

In baseline testing without this skill, agents consistently:

• Reviewed React component code instead of opening the browser
• Verified API responses but never took a screenshot
• Found 6 code-level issues but zero visual issues
• Rationalized: "efficient" and "structurally OK"

With visual testing:

• Layout breaks, overlapping text, and color issues are caught immediately
• Empty states and error boundaries are actually seen, not assumed
• Screenshots serve as evidence, not memory

Red Flags — STOP and Open the Browser

• About to say "the code looks correct"
• About to report "page works" without a screenshot
• About to verify a UI change by reading a diff
• About to say "I manually verified it" without visual evidence
• About to call API testing "sufficient" for a frontend change

All of these mean: Stop. Open the browser. Take a screenshot.