visual-testing
Design and implement visual regression testing for UI changes. Definesscreenshot coverage, rendering stabilization, baseline management, and CIintegration (e.g., Playwright screenshots, Percy/Chromatic). Use whenUI/styling/layout changes need protection against regressions, or when addingscreenshot-based tests to a web/WASM/desktop UI.
When & Why to Use This Skill
This Claude skill automates visual regression testing to ensure UI consistency across web, WASM, and desktop applications. It enables developers and QA engineers to establish stable visual baselines, manage screenshot diffs, and integrate automated visual checks into CI/CD pipelines to prevent unintended layout or styling regressions.
Use Cases
- Preventing unintended layout shifts and styling regressions during major CSS refactoring or component updates.
- Ensuring UI consistency across various responsive breakpoints, themes (e.g., Light/Dark mode), and localized versions.
- Automating visual quality assurance for component libraries to verify that changes don't break existing UI states or interactions.
- Integrating automated screenshot-based testing into CI/CD workflows using tools like Playwright, Cypress, or Percy to catch UI bugs before deployment.
| name | visual-testing |
|---|---|
| description | | |
| license | Apache-2.0 |
Visual Testing
Overview
You are a visual QA engineer. Prevent unintended UI changes by establishing repeatable visual baselines and diff-based tests.
Inputs (Ask If Missing)
- UI type: Web/WASM, component library, desktop (e.g., GPUI)
- Existing test runner: Playwright/Cypress/Webdriver/Storybook/etc.
- CI environment constraints: fonts, GPU/renderer, headless support
- The specific UI changes (screens, components, states)
Core Principles
- Determinism beats coverage: a stable test is better than a broad flaky one.
- Smallest stable surface: snapshot components/states, not entire apps, when possible.
- Interaction ≠ pixels: keep e2e interaction assertions separate from pixel diffs.
- Baselines are reviewed artifacts: never update blindly.
Workflow
1) Select Visual Surfaces
Prioritize:
- Critical user flows and top-level pages
- Components with frequent styling changes
- Error/empty/loading states
- Responsive breakpoints and themes (light/dark) if applicable
2) Stabilize Rendering
- Fixed viewport and device scale
- Disable animations, transitions, blinking caret
- Deterministic data (fixtures/mocks, seeded DB)
- Stable fonts (bundle or ensure CI installs the same fonts)
3) Implement Visual Tests
Default choice for web/WASM UIs: Playwright (if present).
Example snippet (adapt to repo conventions):
// @playwright/test
await page.setViewportSize({ width: 1280, height: 720 });
await page.goto("/settings");
await expect(page.getByRole("main")).toHaveScreenshot("settings.png");
If the project already uses another tool (Cypress, Storybook snapshots, Percy, Chromatic), extend that instead of introducing a new framework.
4) Baseline & Review Policy
- Store baselines in-repo (or via a review service) and review diffs in PRs.
- Require explicit “baseline update” notes in the PR when changes are expected.
5) CI Integration
- Run visual tests on PRs that touch UI code.
- Upload diff artifacts on failure (screenshots, HTML report).
Visual Regression Plan Output
# Visual Regression Plan: {change}
## Coverage
- Pages/components:
- States:
## Determinism Controls
- Viewport:
- Animations:
- Data:
- Fonts:
## Baseline Policy
- Where stored:
- When to update:
- Review requirements:
## Execution
- Local command:
- CI job:
Constraints
- Avoid pixel diffs for highly dynamic surfaces unless you can stabilize them.
- Do not introduce a new framework if one already exists; extend the current stack.