{"slug":"uiverify-vitest-visual-testing","name":"vitest-visual-testing","description":"Make @uiverify/vitest (Vitest browser-mode) captures deterministic so component visual tests stop coming back \"changed\" without a real change (flaky diffs). Use when setting up or debugging visual tests over Vitest browser-mode component tests. Focuses only on the run-to-run variation the capturer can't neutralize from outside your app — above all live/dynamic data, the highest-value step (freeze it with static fixtures and the whole content-noise class disappears), plus the clock, infinite JS animations, and non-Math.random randomness, and the one Vitest-specific trap - capturing before the component has settled.","long_description":"---\nname: vitest-visual-testing\ndescription: Make @uiverify/vitest (Vitest browser-mode) captures deterministic so component visual tests stop coming back \"changed\" without a real change (flaky diffs). Use when setting up or debugging visual tests over Vitest browser-mode component tests. Focuses only on the run-to-run variation the capturer can't neutralize from outside your app — above all live/dynamic data, the highest-value step (freeze it with static fixtures and the whole content-noise class disappears), plus the clock, infinite JS animations, and non-Math.random randomness, and the one Vitest-specific trap - capturing before the component has settled.\n---\n\n# Deterministic Vitest captures (browser mode)\n\n## Mental model — component isolation already removed most of the flake\n\n`@uiverify/vitest` archives each **browser-mode test's final DOM + every resource the page loaded**; UI\nVerify re-renders and pixel-diffs that archive server-side. Because a browser-mode component test renders\nan **isolated component** (no page scroll, no A/B / analytics / chat / consent scripts, no\nlazy-load-on-scroll races), you get the same head start Storybook gives you: the determinism work here is\n**narrow**. If you reach for scroll-settling or third-party stubbing, you're fighting a problem component\nisolation already removed (that's a real-page concern — see `playwright-visual-testing`).\n\n> Whatever the component **is at the end of the test** (or at your `takeSnapshot()` call) is baked into\n> the archive forever. Your job is to drive it to one canonical state before capture.\n\nIntegration is one plugin (no per-test code):\n\n```ts\n// vitest.config.ts\nimport { playwright } from '@vitest/browser-playwright';\nimport { uiverifyPlugin } from '@uiverify/vitest/plugin';\nexport default defineConfig({\n plugins: [uiverifyPlugin()],\n test: { browser: { enabled: true, provider: playwright(), instances: [{ browser: 'chromium' }] } },\n});\n```\n\nEvery browser-mode test then archives its final DOM automatically; `takeSnapshot('name')` adds an\nintermediate checkpoint.\n\n**UI Verify's capturer neutralizes these automatically — do NOT hand-fix them:** CSS animations &\ntransitions (killed at render) and the Web Animations API (disabled); `prefers-reduced-motion: reduce`\n(**emulated**); `Math.random` (**seeded** before your app code runs); web fonts and `![]()
` loading\n(**waited for**); **finite** JS animations (captured at their settled final frame). And unlike a real\npage (`playwright-visual-testing`), a browser-mode test has **no SSR** — no server-rendered random pick\nto reconcile. So the checklist below is only the remainder — what lives *inside your app*.\n\n**The headline: freeze the data.** Once the list above is off the table, the one thing left that floods a\ncomponent suite with false \"changes\" is **live/dynamic data** — star counts, follower counts, contributor\nlists, tiles, timestamps. Feed every component **static fixtures** and that entire class disappears at the\nsource: static data can't churn run-to-run, so there is nothing to diff. This is the single\nhighest-value determinism step here — do it first (step 1), and most components need nothing else.\n\n## The one Vitest-specific trap: capture before the component settled\n\nThe auto-snapshot fires at the **end of a passing test**, and `takeSnapshot()` fires **the moment you\ncall it**. If the component is still resolving a promise, running a transition, or hasn't rendered its\ndata yet, you archive a half-rendered frame. Drive it to its final state first — await your render\nhelper, wait for the content to appear, then let the test end (or call `takeSnapshot()`):\n\n```ts\nimport { render } from 'vitest-browser-react'; // or your framework's browser render helper\nimport { takeSnapshot } from '@uiverify/vitest';\n\ntest('user card', async () => {\n const screen = await render(); // render() is async - await it, or `screen` is a Promise\n await screen.getByText('Ada Lovelace').query(); // wait for the settled state, THEN archive\n await takeSnapshot();\n});\n```\n\nThis is the analog of a Playwright test's navigation + assertions: your `render` + waits *are* the\ndeterminism surface.\n\n## The checklist (only what the tool can't do for you)\n\n### 1. Freeze the data — the one that actually matters\n\nA component fed live/dynamic data is flaky by construction: the stars, followers, contributor list, tile\norder, and timestamps move between runs, so the diff lights up with no code change. **Give every\ncomponent static fixtures and the whole class is gone.** Never let a test hit a real backend.\n\nConcrete — feed fixed, ordered, complete fixtures:\n- fixed **counts** (stars, followers, downloads) — literal numbers, not a live fetch;\n- a fixed **contributor/author list**: fixed names **and** avatar URLs (or inlined avatars), in a fixed\n order;\n- a fixed set of **tiles/rows in a fixed order** (a live \"trending\" sort reorders every run);\n- fixed **timestamps** (pair with the clock, step 2).\n\nTwo ways to inject them, both fine:\n```ts\n// (a) pass fixtures as props — the simplest, when the component takes its data as props\nawait render();\n\n// (b) mock the data module the component imports — when it fetches internally\nvi.mock('../api/library', () => ({ getLibrary: () => fixtures.ktor }));\n```\nIf a page is a server component that fetches, render its **client presentational subtree** with fixture\nprops instead of the fetching wrapper — a browser-mode test has no server to run the fetch anyway. MSW in\na setup file also works for `fetch`-based components; the rule is only *no real request*.\n\n**Copy the dogfood — it's the reference implementation.** `apps/web/src/components/marketing/*.visual.test.tsx`\nare real `@uiverify/vitest` tests with this exact shape: `render()` →\n`await expect.element(...).toBeVisible()` → `await takeSnapshot()`, all data static.\n\n**One canvas per component, not N stories.** Render every variant × state of a component (a Button's\nsizes/states, every tile kind) in a **single grid** and take **one** snapshot — cheaper (one screenshot),\nand you eyeball the whole component's surface at once. Keep each page/component in **its own test file**\nso `--only-changed` carries the untouched ones forward, and add a path filter so the visual job only runs\non UI PRs — both keep the suite cheap at scale.\n\n### 2. Freeze the clock\n\nThe one thing the capturer deliberately does **not** do. Any component that reads the clock — a relative\ntimestamp, a date defaulting to \"today\", a chart's day axis — drifts every run. Pin it with Vitest's fake\ntimers before you render:\n\n```ts\nimport { beforeEach, afterEach, vi } from 'vitest';\n\nbeforeEach(() => {\n vi.useFakeTimers();\n vi.setSystemTime(new Date('2020-01-01T00:00:00Z'));\n});\nafterEach(() => vi.useRealTimers());\n```\n\nIf a component animates on mount and fake timers freeze it half-way, advance to the end\n(`vi.runAllTimers()`) or set the time *after* the render settles.\n\n### 3. Infinite JS animations\n\nA CSS/WAAPI/finite animation is handled for you (above). What's left is an **infinite** JS loop with no\nfinal frame — framer-motion pulsing dots, a Lottie loop, an autoplay spinner, or a `