visual-regression
Automated pixel-level visual regression testing (VRT), Playwright snapshot integration, SSIM/pixelmatch diffing, dynamic masking, animation freezing, and deterministic CI rendering gates.
- License 许可
- MIT
- 所属仓库
- poppyTM/oride
- 最近更新
- 2026-09-30
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- visual-regression
- description
- Automated pixel-level visual regression testing (VRT), Playwright snapshot integration, SSIM/pixelmatch diffing, dynamic masking, animation freezing, and deterministic CI rendering gates.
02 资源文件 7
- 参考文档checks/visual-regression-checklist.md1.7 KB
- 脚本examples/playwright_vrt_config.js902 B
- 参考文档manifest.json1.7 KB
- 参考文档references/visual-testing-strategies.md2.9 KB
- 脚本scripts/compare_screenshots.js1.2 KB
- 脚本scripts/verify.sh1.5 KB
- 参考文档templates/visual-regression-report.md1.8 KB
03 SKILL.md 正文
Automated Visual Regression Testing (VRT) Contract
1. Purpose
Design, execute, and govern automated pixel-level Visual Regression Testing (VRT) suites across component libraries and full-page application views. Prevent unintended layout shifts, font regressions, color mutations, and responsive breakpoint bugs by enforcing deterministic headless environments, dynamic content masking, animation freezing, and strict pixelmatch/SSIM thresholds.
2. Use When
- Establishing CI visual gates for component design systems (Storybook, Playwright Test).
- Validating refactored CSS, Tailwind classes, or global design tokens against visual regressions.
- Auditing multi-theme rendering (Light, Dark, High-Contrast) across responsive viewports.
- Verifying cross-browser rendering parity (Chromium, WebKit, Firefox).
3. Do Not Use When
- Performing functional assertion testing (DOM text, API mocks, unit state logic) where Playwright standard assertions or Jest suffice.
- Auditing purely semantic accessibility or keyboard roving focus without visual rendering (use
keyboard-accessibilityorscreen-reader). - Rapid low-fidelity prototyping where designs change hourly.
4. Required Context
Before capturing or updating visual snapshot baselines, verify:
- Target Viewports & Device Matrix: Desktop (1280x720), Tablet (768x1024), Mobile (375x667), and Device Pixel Ratio (DPR 1x vs 2x Retina).
- Theme Matrix: Light mode, Dark mode, High-contrast mode.
- Dynamic Content Selectors: Selectors for timestamps, user profile pictures, live counters, random transaction IDs, and ads.
- Target Rendering Engine: Headless Chromium / WebKit running in a standardized Docker container to guarantee identical font rasterization.
5. Procedure
Step 1: Flakiness Mitigation & Environment Stabilization
To prevent false-positive visual failures:
- Freeze Motion: Inject CSS disabling all CSS transitions, animations, and smooth scrolling:
*, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; transition-duration: 0s !important; transition-delay: 0s !important; } - Mock Clocks & Deterministic Data: Freeze the system time via Playwright
page.clock.setFixedTime()and mock all API network payloads. - Await Font & Asset Readiness: Wait explicitly for
document.fonts.readyand all visible<img>tags to complete loading prior to taking the snapshot.
Step 2: Dynamic Content Masking
- Identify elements with unpredictable visual variation (e.g., live clocks, fluctuating metric charts, user avatars).
- Pass locator masks to the snapshot capture command:
await expect(page).toHaveScreenshot('dashboard-view.png', { mask: [page.locator('[data-testid="live-timestamp"]'), page.locator('.user-avatar')], maskColor: '#ff00ff', });
Step 3: Snapshot Capture & Comparison (Pixelmatch / SSIM)
- Execute image comparison comparing the current capture against the committed golden baseline.
- Configure threshold boundaries:
threshold(perceptual color delta):0.1to0.2(in CIELAB or YIQ color space).maxDiffPixelRatio: Max acceptable ratio of mismatched pixels (default: $\le 0.001$, i.e. 0.1%).
- Automatically generate a 3-way visual artifact upon failure:
- Baseline Image (Approved Golden State).
- Current Image (Test Execution State).
- Diff Image (Mismatched pixels highlighted in high-visibility magenta
#ff00ff).
Step 4: Baseline Triage & Update Governance
- If diffs represent legitimate intentional design modifications:
- Review the diff in PR review.
- Run
prumo test visual --update-snapshots(ornpx playwright test --update-snapshots). - Commit the updated baseline images with explicit PR approval.
- If diffs represent unintended styling defects:
- Reject the CI build and remediate CSS/component layout.
6. Decision Rules
- Zero Unfrozen Animations: A snapshot test executed without animation freezing is an invalid, flaky test that must not merge into CI.
- Standardized CI Rasterization: Baselines must be generated inside the exact same container image / Linux distribution as the CI runner to prevent macOS vs. Linux FreeType antialiasing discrepancies.
- No Unmasked Dynamic Timestamps: Any test capturing a live date/time without a mask or frozen clock is a defect.
- Explicit PR Review for Baseline Mutations: Golden image commits require visual sign-off from the design or frontend lead.
7. Evidence Required
- VRT Test Run Log: Playwright or pixelmatch test execution log passing with 0 mismatched pixels.
- Diff Artifact Bundle: When failures occur, baseline, actual, and diff PNG files published as CI artifacts.
- Environment Hash: Docker container image tag or OS/font configuration recorded with the baseline.
8. Output Contract
A production visual regression deliverable must contain:
- Playwright test suite (
tests/visual/*.spec.ts). - Playwright VRT configuration (
playwright.config.ts). - Visual Regression Audit Report (
templates/visual-regression-report.md). - Baseline image repository under version control.
9. Stop Conditions
- 100% of defined visual snapshot test cases match baseline within tolerance.
- Zero flaky false positives across 5 consecutive CI runs.
- Failure artifacts generate clear 3-way image diffs.
10. Escalation Rules
- Escalate to Design Lead if cross-browser rendering discrepancies (e.g. WebKit sub-pixel text rendering differences) cannot be reconciled within standard tolerance.
- Escalate to DevOps if CI container resource constraints cause headless browser screenshot timeouts.
04 同仓库更多 Skills
zoom-reflow
暂无简介
wireframe-styleguide
暂无简介
visual-regression
Pixel-by-pixel snapshot testing, Playwright integration, dynamic content masking, deterministic font rendering, and cross-browser CI gates
ui-implementation
Component-driven UI implementation, multi-state matrix (default, hover, focus-visible, active, disabled, loading, empty, error), DTCG design tokens, responsive layout contracts, and accessibility tree mapping.
tui-editor-engine
Text buffer and editing semantics for a terminal code editor — index conversion, transaction-first editing, multi-cursor invariants, undo grouping, and large-file behaviour.
tree-sitter-context-indexing
暂无简介