e2e-write-visual-test

Writing and Running Visual Regression Tests

Overview

Visual regression tests are normal Playwright e2e tests tagged @visual that compare a screenshot against a committed baseline PNG instead of (or in addition to) asserting on the DOM. They live alongside normal e2e tests — there is no separate test type or directory to register a test in.

Key pieces:

• test/__helpers/e2e/visual.ts — the visual() helper. Declares a test tagged @visual without the tag needing to be typed (and possibly forgotten) at each call site. Prefer this over test() with a manual tag for any normal visual regression test.
• test/__helpers/e2e/expectScreenshot.ts — the helper that takes the screenshot and diffs it against the baseline.
• test/playwright.config.ts — toHaveScreenshot.maxDiffPixelRatio (anti-aliasing tolerance) and snapshotPathTemplate (where baselines are stored).
• .github/scripts/visual/find-visual-suites.mjs — discovers every suite that has an @visual-tagged test by scanning test/**/e2e.spec.ts for either the string @visual or a visual() helper import. Nothing needs to be registered anywhere else — add a visual() test and it's picked up automatically next time visual tests run.
• .github/scripts/visual/run-visual-suites.sh — loops pnpm test:e2e:prod:server:run:noturbo <suite> --grep @visual over either an explicit suite or every discovered suite. Shared by CI and the local Docker script.

Writing a new visual test

Use the visual() helper instead of test() and call expectScreenshot instead of (or alongside) normal assertions:

import { expectScreenshot } from '../__helpers/e2e/expectScreenshot.js'
import { visual } from '../__helpers/e2e/visual.js'

visual('renders the posts list view', async () => {
  await page.goto(url.list)

  // Assert the page actually loaded before screenshotting — a screenshot of an error
  // page or a spinner will "pass" the pixel diff and hide a real bug.
  const textCell = page.locator('.row-1 .cell-title')
  await expect(textCell).toBeVisible()

  await expectScreenshot({ name: 'posts-list-view.png', page })
})