跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

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 diffCause classLever
Whole page reflows; height differs between runsFeature 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 differLive data from an APIMock the endpoint with a fixed response → recipe 2
Timestamps, "today", a year, a chart's day axis driftThe clock (Date.now) at render timeFreeze Date before navigation → recipe 3
A banner / chat / consent overlay appears or shiftsThird-party widget injecting DOMStub or dismiss it → recipe 1 + 4
Blank/placeholder where an image should beLazy content that never loaded, so its bytes aren't in the archiveTrigger it at record time → recipe 5
Same content, packed or ordered differently each runDynamic layout that reflows or reorders on its ownMask 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 frameBranch 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 shiftMath.random() in the render body, run at SSR time in Next.js/RemixPin the variant on isUIVerify() + UI_VERIFY=1 on the app server → recipe 10
An infinite CSS keyframe animation on a different frameCSS animation that ignores prefers-reduced-motionHonor the media query in the app's CSS → recipe 8
A <canvas> (particles, chart, background) diffs every runrequestAnimationFrame loop the media query can't reachDraw one static frame on isUIVerify() → recipe 9
The capture is a skeleton / spinner, not the loaded pageSnapshot fired before the data arrivedWait 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

阅读完整来源 ↗