playwright-visual-testing
Make @uiverify/playwright (archive-replay) captures deterministic so real-page visual tests stop coming back "changed" without a real change (flaky diffs). Use when driving a real page — your app under test, a staging build, or live production — and the diff flakes. A symptom-to-lever checklist for the run-to-run variation you probably have - feature flags, live data, the clock, third-party widgets, and dynamic layouts. The lever is almost always "stop the variation at record time" — the archive bakes in whatever the page was.
uiverify · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add uiverify/uiverify --skill playwright-visual-testing技能说明
name: playwright-visual-testing description: Make @uiverify/playwright (archive-replay) captures deterministic so real-page visual tests stop coming back "changed" without a real change (flaky diffs). Use when driving a real page — your app under test, a staging build, or live production — and the diff flakes. A symptom-to-lever checklist for the run-to-run variation you probably have - feature flags, live data, the clock, third-party widgets, and dynamic layouts. The lever is almost always "stop the variation at record time" — the archive bakes in whatever the page was.
Deterministic Playwright captures (archive-replay)
Mental model
@uiverify/playwright captures each test's final DOM + every resource the page loaded into an
archive; UI Verify re-renders and pixel-diffs that archive server-side. So:
Whatever the page was at the instant of capture is baked into the archive forever. Your job is to drive the page to one canonical state before the snapshot. UI Verify can't un-see a random A/B variant, a live feed, or a piece of lazy content that never loaded.
The snapshot fires automatically at the end of every test that passes or fails (a failed one too, so a broken
page shows up as a visual change rather than vanishing from the build; a test that times out is skipped), so your beforeEach + navigation is the
determinism surface. Integration is one import:
- import { test, expect } from '@playwright/test';
+ import { test, expect } from '@uiverify/playwright';
What UI Verify handles server-side (don't hand-fix these): it re-renders the archived DOM with
prefers-reduced-motion emulated and fonts and images settled. So pixel-level settling — waiting on
document.fonts.ready, sticky-header animation, image decode — is not your job. Your job is
narrower: make sure the content and state the archive records is the same every run.
One caveat on "animations": the freeze is replay-side, via reduced-motion emulation — the archive
does not bake a frozen frame. A CSS animation that honors prefers-reduced-motion freezes for free;
an infinite CSS/JS animation that ignores it keeps running on replay and lands on a random frame
(recipe 8), and a <canvas>/requestAnimationFrame loop is beyond the media query entirely (recipe 9).
Those live inside your app, so the fix does too.
The core skill: recognize the class, then pull the lever at record time
Everything below is the same move — something rendered differently run-to-run and it wasn't a real change; find what injected the variation and pin it before the snapshot.
| Symptom in the diff | Cause class | Lever |
|---|---|---|
| Whole page reflows; height differs between runs | Feature flag / A-B experiment rendering a different variant per load (Optimizely, LaunchDarkly, VWO, your own) | Stub the flag calls so one fixed variant renders → recipe 1 |
| A list / feed / counts differ | Live data from an API | Mock the endpoint with a fixed response → recipe 2 |
| Timestamps, "today", a year, a chart's day axis drift | The clock (Date.now) at render time | Freeze Date before navigation → recipe 3 |
| A banner / chat / consent overlay appears or shifts | Third-party widget injecting DOM | Stub or dismiss it → recipe 1 + 4 |
| Blank/placeholder where an image should be | Lazy content that never loaded, so its bytes aren't in the archive | Trigger it at record time → recipe 5 |
| Same content, packed or ordered differently each run | Dynamic layout that reflows or reorders on its own | Mask it (or pin a fixed order/size) → recipe 6 |
An infinite JS animation the capturer can't stop (a charting lib's loop, a <canvas> spinner) | App-driven animation with no final frame | Branch the component on capture and render the end state → recipe 7 |
| A different logo/mascot/hero or list order each run — a whole-element diff, not a pixel shift | Math.random() in the render body, run at SSR time in Next.js/Remix | Pin the variant on isUIVerify() + UI_VERIFY=1 on the app server → recipe 10 |
| An infinite CSS keyframe animation on a different frame | CSS animation that ignores prefers-reduced-motion | Honor the media query in the app's CSS → recipe 8 |
A <canvas> (particles, chart, background) diffs every run | requestAnimationFrame loop the media query can't reach | Draw one static frame on isUIVerify() → recipe 9 |
| The capture is a skeleton / spinner, not the loaded page | Snapshot fired before the data arrived | Wait for the real content (networkidle) → recipe 12 |
Prefer removing a whole class at the source: test a build/staging with flags and third-party scripts off and rows 1 and 4 disappear before you write any code.
Recipes
1. Stub feature-flag / third-party scripts (register in beforeEach, before goto):
await page.route(/optimizely|optly|launchdarkly|segment|intercom/i, (route) =>
route.fulfill({ status: 204, body: '' }).catch(() => undefined),
);
Use fulfill({ status: 204 }), not route.abort() — an aborted request reads as pending network
activity and can hang the page's readiness wait. A 204 completes it empty: the script "loads," resolves
no variant, and the page renders its control DOM. Identify the culprit by loading the page a few times
and watching document.body.scrollHeight flip between values.
2. Mock live data: intercept the API route and fulfill a fixed JSON fixture — same shape every run.
await page.route('**/api/items', (route) =>
route.fulfill({ json: fixtures.items }),
);
3. Freeze the clock (before navigation — it changes what the app renders into the DOM). Use
Playwright's built-in clock so Date, Date.now(), and Date()-without-new all stay correct:
await page.clock.setFixedTime(new Date('2020-01-01T00:00:00Z'));
4. Dismiss overlays (best-effort; absent = fine
阅读完整来源 ↗