Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(visual-gate): freeze the clock at capture time (#5434)

Cindy Zhange6dc4bda57d6
diff --git a/.github/scripts/visual-gate/README.md b/.github/scripts/visual-gate/README.md
index 89ec1efea1..f78c397cb0 100644
--- a/.github/scripts/visual-gate/README.md
+++ b/.github/scripts/visual-gate/README.md
@@ -114,9 +114,17 @@ tells you to refresh rather than reporting hundreds of regressions.
## Determinism
Every shot is taken with animations and transitions forced to their end state,
-carets hidden, a fixed viewport at device scale 1, fonts awaited, and **all
-off-origin requests blocked** — nothing that renders may depend on a CDN being
-up. Theme and colour mode are switched over Storybook's own channel rather than
+carets hidden, a fixed viewport at device scale 1, fonts awaited, **the clock
+frozen at a fixed instant in a fixed timezone**, and **all off-origin requests
+blocked** — nothing that renders may depend on a CDN being up.
+
+The frozen clock is why a story built from `new Date()` — Schedule, Calendar,
+DateRangeInput — does not report `changed` every day. Shots of those stories
+show 13 May 2026, not today; that is the capture's clock, not stale data. The
+instant lives in `lib/capture.mjs` and is recorded in every manifest. Changing
+it changes those shots, so it is a deliberate rebaseline, not a tweak.
+
+Theme and colour mode are switched over Storybook's own channel rather than
by reloading, which is what keeps 514 shots inside a few minutes;
`--no-fast-globals` forces a reload per shot if a story's state ever turns out
to survive the re-render.
diff --git a/.github/scripts/visual-gate/lib/capture.mjs b/.github/scripts/visual-gate/lib/capture.mjs
index e41b1f8f7a..e0dc296d0f 100644
--- a/.github/scripts/visual-gate/lib/capture.mjs
+++ b/.github/scripts/visual-gate/lib/capture.mjs
@@ -14,10 +14,11 @@
* false diff costs a human judgement and teaches everyone to ignore it. So
* the page is pinned: no external network (nothing that renders may depend on
* a CDN being up), animations and transitions forced to their end state,
- * carets hidden, a fixed viewport and device scale factor, and a wait on
- * `document.fonts.ready` before the shutter. Even so, a baseline is only
- * comparable against a capture from the same OS and browser build, which is
- * why the manifest records the platform and the comparison refuses to cross it.
+ * carets hidden, a fixed viewport and device scale factor, a frozen clock in
+ * a fixed timezone, and a wait on `document.fonts.ready` before the shutter.
+ * Even so, a baseline is only comparable against a capture from the same OS
+ * and browser build, which is why the manifest records the platform and the
+ * comparison refuses to cross it.
*
* Speed. Storybook applies the theme through a global, so a theme change is a
* re-render, not a reload: the plan is walked grouped by story, and the theme
@@ -80,6 +81,24 @@ const SEEDED_RANDOM = `(() => {
};
})();`;
+/** The instant every capture happens at, and the zone it happens in.
+ *
+ * Stories that build their data from `new Date()` photograph a different day
+ * on every run, so the gate reports them changed every single day — and a
+ * gate that always says changed teaches everyone to skim the changed list.
+ *
+ * Wednesday 13 May 2026, 10:15 UTC, chosen so that a date-driven story still
+ * has something to show: mid-month and mid-week, so a "today" marker has
+ * ordinary days around it and does not sit on the edge of a month grid; and
+ * mid-morning, so the day's earlier events are already past while its later
+ * ones are still ahead. A clock that put everything in the past would hide a
+ * regression in how future events are drawn. The zone is pinned with it —
+ * an instant alone is a different wall-clock hour on every machine, and the
+ * hour is the half of this choice that does the work.
+ */
+const FROZEN_NOW = new Date('2026-05-13T10:15:00Z');
+const TIMEZONE_ID = 'UTC';
+
/**
* Serve a directory over loopback. The gate never talks to the network, so
* this is the only origin the browser can reach.
@@ -255,7 +274,12 @@ export async function scout({storyIds, storybookDir, theme, viewport, onProgress
const server = await serveDirectory(storybookDir);
const origin = `http://127.0.0.1:${server.port}`;
const browser = await chromium.launch();
- const context = await browser.newContext({viewport, deviceScaleFactor: 1});
+ const context = await browser.newContext({
+ viewport,
+ deviceScaleFactor: 1,
+ timezoneId: TIMEZONE_ID,
+ });
+ await context.clock.setFixedTime(FROZEN_NOW);
await context.addInitScript(SEEDED_RANDOM);
await context.route('**', route =>
route.request().url().startsWith(origin) ? route.continue() : route.abort(),
@@ -319,7 +343,9 @@ export async function capture({
deviceScaleFactor: 1,
reducedMotion: 'reduce',
colorScheme: 'light',
+ timezoneId: TIMEZONE_ID,
});
+ await context.clock.setFixedTime(FROZEN_NOW);
await context.addInitScript(SEEDED_RANDOM);
// Anything off-origin is a determinism hazard, and nothing in a component
// story legitimately needs it.
@@ -401,6 +427,8 @@ export async function capture({
browser: `chromium-${browserVersion}`,
viewport,
settleMs,
+ frozenClock: FROZEN_NOW.toISOString(),
+ timezoneId: TIMEZONE_ID,
capturedAt: new Date().toISOString(),
shots,
observedTargets: Object.fromEntries(