Skill: visual-testing

Skill: visual-testing

Delegates visual test execution to the Playwright test runner with the correct flags for baseline consistency: --project=visual for single-browser runs, --update-snapshots mode when intentional updates are needed, comparison artifact generation, and pixel diff reporting.

---

Responsibilities

• Emit the correct npx playwright test invocation for visual suite runs.
• Enforce single-browser execution (--project=visual) for baseline consistency.
• Explain when and how to use --update-snapshots safely.
• Configure the HTML reporter to surface pixel diff percentages and comparison images.
• Generate and preserve comparison artifacts (diff images, actual screenshots) on failure.

---

Standard Visual Suite Run

# Run the visual project only (single browser, consistent baselines)
npx playwright test --project=visual

# Run with verbose output to see per-test diff percentages
npx playwright test --project=visual --reporter=html

---

Targeted Runs

# Run a single visual spec file
npx playwright test tests/visual/specs/hero.visual.spec.ts --project=visual

# Run tests matching a description pattern
npx playwright test --project=visual --grep "landing page"

# Run in headed mode for local debugging
npx playwright test --project=visual --headed

---

Updating Baselines

# Update ALL baselines (use with caution — review every changed PNG)
npx playwright test --project=visual --update-snapshots

# Update baselines for a specific test or file only
npx playwright test --project=visual --update-snapshots --grep "hero section"
npx playwright test tests/visual/specs/hero.visual.spec.ts --project=visual --update-snapshots

After updating:

# Open the HTML report to review the before/after diff for every changed baseline
npx playwright show-report

# Stage only the snapshot changes, review, then commit
git diff --stat tests/visual/__screenshots__/
git add tests/visual/__screenshots__/
git commit -m "chore(visual): update hero baselines — new brand colour"

---

Playwright Config — Visual Project

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  snapshotDir: 'tests/visual/__screenshots__',

  expect: {
    toHaveScreenshot: {
      animations: 'disabled',
      maxDiffPixelRatio: 0.02,
      threshold: 0.1,
    },
  },

  reporter: [
    ['html', { outputFolder: 'playwright-report', open: 'never' }],
    ['list'],
  ],

  projects: [
    {
      name: 'visual',
      use: {
        ...devices['Desktop Chrome'],
        viewport: { width: 1280, height: 800 },
      },
      testMatch: 'tests/visual/**/*.visual.spec.ts',
    },
  ],
});

---

CI Pipeline Integration

# GitHub Actions
- name: Run visual regression tests
  run: npx playwright test --project=visual
  env:
    CI: true   # Playwright treats missing baselines as failures when CI=true

- name: Upload visual report on failure
  uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: playwright-visual-report
    path: playwright-report/
    retention-days: 14

- name: Upload diff images on failure
  uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: playwright-visual-diffs
    path: test-results/
    retention-days: 14

---

Reading Pixel Diff Output

When a visual test fails, Playwright reports:

Error: Screenshot comparison failed:
  5 pixels (ratio 0.0039 %) are different.
  Expected: tests/visual/__screenshots__/hero-desktop-chromium-linux.png
  Received: test-results/hero-desktop-visual/hero-desktop-actual.png
  Diff:     test-results/hero-desktop-visual/hero-desktop-diff.png

Open playwright-report/index.html to see the expected, actual, and diff images side-by-side with the pixel diff percentage highlighted.

---

Guidelines

• Always run the visual suite with --project=visual — never mix visual and functional tests in the same run for baseline management purposes.
• Do not pass --update-snapshots in CI pipeline scripts; set CI=true instead so missing baselines are treated as failures.
• Preserve playwright-report/ and test-results/ as CI artifacts on failure so diffs are accessible without re-running locally.
• Review the HTML report diff viewer before accepting any baseline update in a PR.