/visual-qa

name: visual-qa
description: Use when verifying that a UI renders correctly. Covers visual regression testing, responsive checks across breakpoints, cross-browser verification, and screenshot-based review of an implementation against a design.
metadata:
  category: frontend
  version: 1.0.0
  tags: [visual-testing, regression, screenshots, responsive, qa]

Visual QA

Purpose

Catch visual defects before users do. Functional tests confirm the button works; they say nothing about the button being invisible, overlapping, or off-screen on a phone.

When to Use

• Verifying an implementation against a design.
• Setting up visual regression testing.
• Checking responsive behavior across breakpoints.
• Reviewing a UI change that a unit test cannot meaningfully assert on.

Capabilities

• Visual regression testing with deterministic screenshots.
• Responsive verification across a defined breakpoint set.
• Cross-browser and cross-platform rendering checks.
• Design-to-implementation comparison.
• Detection of layout shift, overflow, and truncation.

Inputs

• The design reference, if there is one.
• The breakpoints and browsers that are in scope.
• The pages or components under test, and their states.

Outputs

• Baseline screenshots committed to the repository.
• A diff report for each change, with the pixel delta.
• A list of visual defects with viewport and browser.

Workflow

1. **Enumerate the states** — Not just the happy one. Empty, loading, error, long content, and the state with a 60-character name in a field designed for eight. 2. **Make screenshots deterministic** — Freeze time, seed data, disable animations, and wait for fonts and images. A flaky visual test is worse than no visual test; it will be ignored, then deleted. 3. **Capture at every breakpoint** — Mobile (375), tablet (768), desktop (1280), wide (1920). Check the boundaries themselves, where layouts switch. 4. **Diff against the baseline** — Review each diff. Approve intentional changes to update the baseline; investigate the rest. 5. **Check the overflow cases** — Long words, long lists, missing images, and a 200% browser zoom. These are where layouts break, and where designs rarely go.

Best Practices

• Animation and time are the two causes of visual-test flakiness. Disable both in the test environment before you do anything else.
• Screenshot the component, not the whole page, when testing a component. A full-page baseline changes every time anything on the page does.
• A visual diff threshold that is too tight flags anti-aliasing noise; too loose and it misses a 4px misalignment. Tune it once, on real diffs.
• Test the states that are hard to reach manually — error, empty, and loading — because those are the ones nobody looks at before shipping.
• Run visual tests in a container so the fonts and rendering engine are identical to CI. Screenshots taken on macOS will not match those taken on Linux.
• Review the diff, do not just approve it. A rubber-stamped baseline update defeats the entire mechanism.

Examples

**Deterministic Playwright visual test across breakpoints and states:**

const VIEWPORTS = [
  { name: "mobile",  width: 375,  height: 812 },
  { name: "tablet",  width: 768,  height: 1024 },
  { name: "desktop", width: 1280, height: 800 },
];

for (const vp of VIEWPORTS) {
  test.describe(`order card @ ${vp.name}`, () => {
    test.use({ viewport: { width: vp.width, height: vp.height } });

    for (const state of ["default", "loading", "error", "long-content"] as const) {
      test(state, async ({ page }) => {
        await page.clock.setFixedTime(new Date("2026-01-15T12:00:00Z")); // freeze time
        await page.goto(`/storybook/order-card?state=${state}`);
        await page.waitForFunction(() => document.fonts.ready);          // fonts settled

        await expect(page.getByTestId("order-card")).toHaveScreenshot(
          `order-card-${state}-${vp.name}.png`,
          { animations: "disabled", maxDiffPixelRatio: 0.01 },
        );
      });
    }
  });
}

**Catching overflow that a functional test would pass:**

test("long customer name does not overflow the card", async ({ page }) => {
  await page.goto("/orders/ord_1?customer=Bartholomew%20Wintersmith-Kensington");

  const card = page.getByTestId("order-card");
  const overflows = await card.evaluate(
    (el) => el.scrollWidth > el.clientWidth || el.scrollHeight > el.clientHeight,
  );
  expect(overflows).toBe(false);
});

Notes

• `page.clock` (Playwright 1.45+) freezes both `Date` and timers, which is what makes relative timestamps ("2 hours ago") stable in screenshots.
• Storybook plus a visual-testing runner gives you every component state in isolation, which is far cheaper to screenshot than navigating the real application into each state.
• Visual tests are not a substitute for accessibility testing. A screenshot cannot tell you the contrast is 2.1:1.