Freeze time, animations, and fonts so an unchanged component produces identical pixels every run. The determinism playbook behind stable Playwright and Storybook snapshots.

Reducing Flaky Screenshots with Deterministic Rendering

Your visual suite fails maybe one run in eight, always on a different component, always with a diff too small to read. The team has learned to click “re-run,” and the moment that habit set in, the suite stopped protecting anything. This guide is for engineers running Playwright 1.4x or the Storybook test-runner whose screenshot tests are intermittently red for reasons unrelated to any component change. We will identify the three inputs that make a render non-deterministic — time, animation, and fonts — and neutralise each so an unchanged component produces byte-identical pixels on every run. This is the determinism layer the rest of the visual regression testing topic area depends on; without it, no threshold or baseline strategy can stabilise a flaky screenshot.

Root Cause Analysis

A flaky screenshot is not a flaky test — it is a deterministic test observing a non-deterministic render. The screenshot mechanism does exactly what it is told: it captures the pixels present at capture time. If those pixels differ between runs while the component source is unchanged, some input to the render varied, and there are only a handful of usual suspects. The instinct to raise the diff threshold treats the symptom and worsens the disease: a threshold wide enough to swallow the variance is also wide enough to swallow a real regression, converting a visible false positive into an invisible false negative. The only correct fix is to remove the varying input so the render becomes a pure function of the component again.

Three inputs account for nearly all screenshot flake. Time is the first: any component that renders new Date(), a relative timestamp, a countdown, or a randomized seed derived from the clock paints different pixels each second. Animation is the second: CSS transitions, keyframe animations, spinners, and entrance effects mean the frame you capture depends on exactly when in the animation you captured it. Fonts are the third and subtlest: a web font that has not finished loading renders in a fallback face, and if the capture races the font load, some runs show the fallback and some show the real font — a large, whole-glyph difference. Every one of these is a degree of freedom, and determinism is the discipline of driving each to zero before the shutter clicks. The same reasoning underlies retrying flaky Playwright tests without masking bugs: the answer to nondeterminism is control, not retries.

Three sources of screenshot nondeterminism and their fixes Time, animation, and fonts are the three inputs that vary a render; freezing the clock, disabling animation, and awaiting fonts drives each to a fixed value. Remove the variable, not the threshold Time freeze the clock setFixedTime / fake timers Animation disable motion animations: 'disabled' Fonts await load document.fonts .ready
The three degrees of freedom in a render, each with its own fix.

Reproducible Setup

Start from a component that is non-deterministic on all three axes so each fix is observable. It shows a live timestamp, animates in, and uses a web font.

// LiveBadge.tsx — deliberately non-deterministic on time, animation, and font
export function LiveBadge() {
  return (
    <span className="live-badge">
      Updated {new Date().toLocaleTimeString()}
    </span>
  );
}
/* live-badge.css */
.live-badge {
  font-family: 'Inter', system-ui, sans-serif; /* web font, may load late */
  animation: fade-in 400ms ease-in;             /* entrance animation */
}
@keyframes fade-in { from { opacity: 0 } to { opacity: 1 } }

Captured naively, this component fails a stability run immediately — the timestamp alone guarantees a different image every second.

Implementation

Step 1 — Freeze the clock. Pin the browser’s time before the component mounts so any Date-derived output is constant. Playwright’s clock API installs a fixed time that the page’s Date and timers observe.

import { test, expect } from '@playwright/experimental-ct-react';
import { LiveBadge } from './LiveBadge';

test.beforeEach(async ({ page }) => {
  await page.clock.setFixedTime(new Date('2026-07-24T12:00:00Z'));
});

test('live badge', async ({ mount }) => {
  const c = await mount(<LiveBadge />);
  await expect(c).toHaveScreenshot('live-badge.png');
});

In a Vitest component test using fake timers, the equivalent is to set the system time before render so the same fixed instant is observed.

import { vi, beforeEach } from 'vitest';

beforeEach(() => {
  vi.useFakeTimers();
  vi.setSystemTime(new Date('2026-07-24T12:00:00Z'));
});

Step 2 — Disable animation and transitions. Use Playwright’s built-in animations: 'disabled', which freezes CSS animations to their end state and stops transitions for the duration of the capture. Belt-and-braces, inject a stylesheet that zeroes motion so nothing is mid-flight.

await page.addStyleTag({
  content: `*, *::before, *::after {
    animation-duration: 0s !important;
    animation-delay: 0s !important;
    transition-duration: 0s !important;
    transition-delay: 0s !important;
    caret-color: transparent !important;
  }`,
});
await expect(c).toHaveScreenshot('live-badge.png', { animations: 'disabled' });

Step 3 — Wait for fonts and vendor them locally. Await document.fonts.ready so the web font is applied before capture, and — critically — self-host the font file in the repo rather than loading it from a CDN, so a slow or blocked network request can never leave the render in its fallback face.

await page.evaluate(() => document.fonts.ready);
// Preload the vendored font so it is ready deterministically, not network-timed.
// public/fonts/inter.woff2 committed to the repo; @font-face points at it locally.

Step 4 — Mask any residual dynamic region. Some variance is intrinsic — a genuinely live value that must not be frozen, a third-party embed. Mask that specific element so its pixels are excluded from the diff, keeping the rest of the component under a strict tolerance rather than loosening the whole threshold.

await expect(c).toHaveScreenshot('live-badge.png', {
  animations: 'disabled',
  mask: [page.getByTestId('third-party-embed')],
  maxDiffPixelRatio: 0.01,
});

Step 5 — Pin the device pixel ratio and viewport. A capture on a 2x display has four times the pixels of a 1x capture, so pin deviceScaleFactor and the viewport size in config to remove that variable, then apply the same determinism setup to Storybook captures via the test-runner hook described in catching CSS regressions in Storybook.

// playwright.config.ts
use: { viewport: { width: 1280, height: 720 }, deviceScaleFactor: 1 },
Same render across ten runs before and after determinism Before the fixes, repeated captures of an unchanged component vary; after freezing time, disabling animation, and awaiting fonts, every run produces identical pixels. Before — non-deterministic run varies 1 in 8 fails team re-runs, trust erodes After — deterministic identical pixels 10 / 10 green every diff is a real regression
Determinism converts an eroding, re-run-riddled suite into one where every diff means something.

Verification

The verification for determinism is a repetition test, not a single pass. Run the unchanged component’s screenshot test many times in one invocation and require every run to be pixel-identical. Playwright’s --repeat-each runs each test N times in the same session, which is the cheapest way to expose residual nondeterminism.

# Require 20 identical captures of the unchanged component
npx playwright test --repeat-each=20 src/LiveBadge.spec.tsx

Twenty clean repeats is a reasonable bar before a screenshot test enters the merge gate; if any run differs, one input is still varying. Isolate which by removing fixes one at a time and re-running: reintroduce the timestamp and the failures return, confirming time was a source. This bisection turns “it’s flaky” into a named, fixed cause. Once the repetition test is solidly green, the diff threshold can be tightened close to exact, because there is no longer any legitimate variance for it to absorb — every remaining diff is a real change.

Bisecting a residual flake by reintroducing one input When a repetition run still flakes, removing then reintroducing each fix in turn names the varying input, turning an unexplained flake into a fixed cause. Repeat x20 still flakes Toggle one fix time / motion / font Flake returns input identified fix it bisection turns "it's flaky" into a named cause
Toggling one fix at a time names the varying input behind a residual flake.

Troubleshooting

Symptom: the timestamp is frozen but the component still flakes occasionally. Diagnosis: the clock was set after the component already read Date during mount, so the first render captured a live time. Fix: set the fixed time in beforeEach before mount, and for fake-timer setups call setSystemTime before rendering, so the frozen clock is in place for the very first paint.

Symptom: captures differ only in the text weight or letterforms. Diagnosis: the web font is racing the screenshot, so some runs paint the fallback face and some the real font. Fix: await document.fonts.ready before every capture and self-host the font in the repository, eliminating the network request whose timing caused the race. A CDN-loaded font is inherently nondeterministic under test.

Symptom: images are stable locally but twice the size and mismatched in CI. Diagnosis: the local machine renders at a 2x device pixel ratio while CI runs at 1x, so the pixel dimensions differ. Fix: pin deviceScaleFactor and viewport in the Playwright config so every environment captures at the same resolution, and generate baselines in the CI environment as described in managing visual baselines across browsers.

FAQ

Why not just raise the diff threshold to stop the flake?

Because a threshold is a blunt instrument that cannot distinguish noise from a real regression. A threshold loose enough to absorb an in-flight animation frame or a font swap is also loose enough to let a genuine styling regression pass unnoticed, so you trade a visible false positive for an invisible false negative. Determinism removes the variance at its source, which lets you keep the threshold tight and trust every diff. Raising the threshold treats the symptom; freezing the input cures the cause.

Do I need to freeze time even if my component has no clock?

Only if some part of the render is time-derived, which is easy to underestimate — a “posted 3 minutes ago” label, an animation whose progress depends on elapsed time, a chart with a time axis, or a randomized value seeded from Date.now(). If nothing in the captured region reads the clock, you can skip it, but freezing time is cheap and harmless, so many teams apply it globally in a shared beforeEach as insurance against a future component quietly introducing a time dependency.

Is animations: ‘disabled’ enough, or do I also need the injected stylesheet?

For most cases animations: 'disabled' suffices, because Playwright freezes CSS animations to their end state and halts transitions during the capture. The injected zero-duration stylesheet is belt-and-braces for edge cases the built-in flag does not cover, such as JavaScript-driven animation or third-party widgets that animate outside CSS. Applying both costs nothing and closes the gap, so it is a reasonable default for a suite that must never flake.

How many repeat runs prove a test is deterministic?

Twenty identical captures in a single --repeat-each invocation is a solid practical bar; it is enough to expose the common timing races without making the check slow. The exact number matters less than making the repetition test a required step before a screenshot assertion joins the merge gate. If a test cannot pass twenty consecutive identical captures, it is not ready to gate anything, and the fix is always to find the varying input rather than to lower the bar.