visual-regression-ci

Adds Playwright screenshot comparisons to CI to catch silent visual regressions in Astro sites.

Updated Jun 17, 2026
One-click install
npx skills add https://github.com/ccediland/web-stack-skills --skill visual-regression-ci-ccediland
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: visual-regression-ci
Source: https://github.com/ccediland/web-stack-skills/tree/main/plugin/skills/visual-regression-ci
Command: npx skills add https://github.com/ccediland/web-stack-skills --skill visual-regression-ci-ccediland

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @playwright/test, and includes references (resource) components.

What problem does it solve? Performance, code health, and accessibility gates can all pass while a token refactor, Tailwind upgrade, or stray global style silently breaks how pages look. This Skill adds a fourth CI gate that compares screenshots of built pages against committed baselines so unintended visual changes fail the build. ## Core Features & Use Cases - Native Playwright screenshot testing: Uses toHaveScreenshot with the same Playwright pin already installed for the accessibility job, adding one spec file and one CI job with no new dependencies. - CI-generated baselines: Baselines are rendered in the same CI environment that compares them (or a pinned Playwright Docker image), committed to the repo, and reviewed as PR diffs. - Determinism and flake discipline: Explicit maxDiffPixelRatio thresholds, disabled animations, self-hosted fonts, and masking of non-deterministic regions like WebGL canvases and videos. - Tool verdicts: Defaults to committed-baseline Playwright, escalates to Argos, Chromatic, or Percy (5,000 free snapshots/month each) when review UIs earn their place, and flags Lost Pixel and BackstopJS as tombstones. - Use Case: After a design token refactor, run the visual gate in GitHub Actions to confirm home, contact, and gallery pages render pixel-identically across desktop and mobile viewports before merging. ## Quick Start Add a Playwright visual regression job to my CI workflow that screenshots my built Astro pages and compares them against committed baselines.

Frequently Asked Questions about visual-regression-ci

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add visual regression testing to CI with Playwright?▼

Use Playwright's built-in toHaveScreenshot assertion against the built site served locally, with explicit maxDiffPixelRatio and animations disabled. Commit the generated snapshots to the repo and run the comparison as a job in your existing GitHub Actions workflow.

Playwright vs Chromatic vs Percy for visual regression testing?▼

Playwright toHaveScreenshot is the default when it is already installed, since baselines live in git at zero added cost. Escalate to Argos, Chromatic, or Percy (each with 5,000 free snapshots per month) when you need a review UI, multi-viewport matrices, or baselines outside the repo.

Why do Playwright screenshot tests fail in CI but pass locally?▼

Rendering differs across operating systems, hardware, and settings, so baselines generated on a developer laptop fail on Linux CI runners by design. Generate baselines in CI itself or in the official Playwright Docker image pinned to the exact version.

How do I update Playwright screenshot baselines?▼

Trigger the CI workflow with an update_snapshots input so the runner renders fresh baselines and uploads them as an artifact, then download, commit, and push them. Repeat on Playwright version bumps, intended redesigns, or rendering-stack changes, with the reason stated in the commit message.

How do I reduce flakiness in screenshot comparison tests?▼

Mask non-deterministic regions like WebGL canvases, videos, and third-party iframes, self-host fonts, set animations to disabled, and keep the tested page set small. If a page flakes twice, redesign its test rather than muting it.

Is Lost Pixel or BackstopJS still maintained for visual testing?▼

No. Lost Pixel's repository was archived in 2026 after the team joined Figma and sunset the product, and BackstopJS has had no release since September 2024 with an unanswered security issue. Neither should be adopted for new projects.