Playwright Visual Testing

Trigger On

• the user asks for pixel, screenshot, visual, or UI regression testing with Playwright
• a .NET repo needs visual baselines for ASP.NET Core, Blazor, WebAssembly, static pages, or generated frontend assets
• GitHub Actions should run Playwright screenshots and expose expected, actual, and diff artifacts
• tests fail with screenshot mismatches, noisy baselines, or unstable visual snapshots

Workflow

flowchart TD
    A["Need visual regression coverage"] --> B{"Uses Playwright Test"}
    B -->|"Yes"| C["Prefer expect(page).toHaveScreenshot"]
    B -->|"No or custom compare needed"| D["Capture page.screenshot output"]
    D --> E["Compare with pixelmatch and pngjs"]
    C --> F["Stabilize viewport, data, animation, and volatile regions"]
    E --> F
    F --> G["Commit reviewed baselines"]
    G --> H["Run in CI and upload reports or image diffs"]
    H --> I["Triage expected, actual, and diff before changing thresholds"]

1. Inspect the current browser-test surface:

- nearest AGENTS.md - package.json, lockfile, Playwright config, test folders, and CI workflows - how the app starts locally: dotnet run, Aspire AppHost, static preview, or frontend dev server

1. Choose the comparison path deliberately:

- default to Playwright Test expect(page).toHaveScreenshot() when the repo can use Playwright Test snapshots - use page.screenshot() plus a standalone Pixelmatch script only when the repo needs article-style central screenshots/baseline, screenshots/actual, and screenshots/diff folders, non-Playwright image inputs, or custom reporting outside Playwright Test

1. Make screenshots deterministic before tuning thresholds:

- fix viewport, browser project, locale/time zone, color scheme, and device scale factor - use stable test data and wait for the app-specific ready state - disable animations or use Playwright screenshot options for animations - mask or hide volatile regions such as ads, time, avatars, random IDs, spinners, and third-party iframes

1. Keep baseline updates explicit:

- generate missing baselines once, review them, and commit them - update intended Playwright snapshots with npx playwright test --update-snapshots - do not auto-create or auto-update baselines in pull-request CI

1. Wire CI for repeatability:

- use npm ci, then npx playwright install --with-deps, then the focused Playwright command - set CI workers conservatively when screenshots are resource-sensitive - upload the Playwright HTML report and test-results/, or upload screenshots/baseline, screenshots/actual, and screenshots/diff for a custom Pixelmatch flow

1. Triage failures from artifacts:

- inspect expected, actual, and diff images together - classify the mismatch as intentional design change, rendering nondeterminism, app bug, or baseline drift - fix nondeterminism before increasing maxDiffPixels, maxDiffPixelRatio, or Pixelmatch mismatch thresholds

Deliver

• a Playwright visual-test path that matches the repo's existing package manager and test layout
• committed reviewed baseline images or a clear command to generate and review them
• deterministic screenshot controls for dynamic UI regions
• GitHub Actions report or diff artifacts that make failures reviewable
• a short note on whether the implementation uses built-in Playwright snapshots or a custom Pixelmatch comparison script

Validate

• npm ci
• npx playwright install --with-deps
• npx playwright test or the repo's focused visual-test script
• npx playwright test --update-snapshots only when accepting intentional baseline changes
• in CI changes, confirm artifact upload uses maintained GitHub Actions versions and runs on pull requests without requiring secrets

Load References

Related skills