Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,16 @@ jobs:
id: verify
working-directory: samples/react
run: npx vcase-react verify
- name: Fake-clock determinism (frameIntervalMs cases, 5 more runs, zero tolerance)
# A frameIntervalMs case must capture the same instant however fast the page loads;
# once flaked by a few ms. Each run fails on any pixel off the golden.
id: determinism
working-directory: samples/react
run: |
for i in 1 2 3 4 5; do
echo "run $i"
npx vcase-react verify --filter 'ui.progress.*'
done
- name: Parity report against the Compose sample (report-only)
if: always() && steps.verify.outcome != 'skipped'
working-directory: samples/react
Expand Down
20 changes: 17 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -335,9 +335,23 @@ network idle, `readySelector`, fonts and images, then `settleFrames` animation f
transitions, CSS animations and the caret are stopped. A component is captured at its root
element's bounds (cut at `maxWidth`, default the viewport width, and `maxHeight`, default 4x
the viewport height, with a warning); `maxWidth` also widens the window so a wide gallery can
lay out. A screen is captured at the viewport. With `frameIntervalMs`, the page runs on
Playwright's paused fake clock and each settle frame advances it by that many ms, so a
JavaScript animation is captured at a known instant (`0` keeps it at its start).
lay out. A screen is captured at the viewport.

With `frameIntervalMs`, the page runs on Playwright's fake clock, paused from before
navigation, and the capture instant does not depend on how fast the page loads:

- Through load, network idle, `readySelector`, fonts and images, `performance.now()` is `0`
and `Date.now()` is `clock` (default `2026-01-01T00:00:00.000Z`); no timer, interval or
animation frame runs. Module code, the first render and mount effects all see time 0.
- Settle frame `i` (1-based) runs the clock forward by exactly `frameIntervalMs`, firing the
timers due on the way. `requestAnimationFrame` callbacks fire at every multiple of 16 ms of
`performance.now()`, with that value as their timestamp.
- The capture is at `performance.now() = settleFrames * frameIntervalMs` (`0` keeps an
animation at its start). For example, `settleFrames: 10, frameIntervalMs: 16` mounts a
component at 0, runs its frames at 16, 32, ... 160 and captures at 160.

The renderer reads the page's clock before the first settle frame and at the capture; any
other value makes the variant an error rather than a slightly different image.

A page error, an HTTP error for the page, or a request to an origin that is not allowed (and
that no route answers) makes the variant an error: no image, and verify fails.
Expand Down
8 changes: 6 additions & 2 deletions packages/react/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,12 @@ export interface VCaseMeta {
/** Animation frames waited before the capture (default: the config's `settleFrames`). */
settleFrames?: number;
/**
* With a value, the page runs on a fake clock and each settle frame advances it by this many
* ms; `0` keeps time-driven animations at their start.
* With a value, the page runs on a paused fake clock: it loads and first renders at
* `performance.now() === 0` (`Date.now()` = the config's `clock`), however long loading takes,
* and each settle frame advances it by exactly this many ms, so the capture is at
* `settleFrames * frameIntervalMs`. `requestAnimationFrame` fires at every multiple of 16 ms
* of `performance.now()`, with that value as its timestamp. `0` keeps time-driven animations
* at their start.
*/
frameIntervalMs?: number;
}
Expand Down
50 changes: 44 additions & 6 deletions packages/react/src/node/render.ts
Original file line number Diff line number Diff line change
Expand Up @@ -127,11 +127,11 @@ async function renderVariant(browser: Browser, cfg: VCaseReactConfig, hash: stri

const interval = cap.frameIntervalMs ?? null;
const clock = cfg.clock === undefined ? DEFAULT_CLOCK : cfg.clock;
if (interval != null) {
// Fake timers, paused: time moves only in settle(), so the capture is at a known instant.
const start = new Date(clock ?? DEFAULT_CLOCK).getTime();
await page.clock.install({ time: start });
await page.clock.pauseAt(start + 1000);
const frames = cap.settleFrames ?? cfg.settleFrames ?? 2;
const plan = interval != null ? frameClock(clock, frames, interval) : null;
if (plan) {
// One pauseAt, no install: see frameClock() for why.
await page.clock.pauseAt(plan.wallStart);
} else if (clock) {
await page.clock.setFixedTime(clock);
}
Expand All @@ -151,7 +151,9 @@ async function renderVariant(browser: Browser, cfg: VCaseReactConfig, hash: stri
await Promise.all([...document.images].map((img) => (img.complete ? Promise.resolve() : img.decode().catch(() => undefined))));
});
await page.waitForLoadState("networkidle");
await settle(page, cap.settleFrames ?? cfg.settleFrames ?? 2, interval);
if (plan) errors.push(...clockProblems(await readClock(page), plan.wallStart, 0, "before the first frame"));
await settle(page, frames, interval);
if (plan) errors.push(...clockProblems(await readClock(page), plan.wallStart + plan.capture, plan.capture, "at capture"));
if (errors.length > 0) return { kind: "error", message: errors.join("; "), meta: meta() };

const shot = { animations: "disabled", caret: "hide", scale: "device", timeout } as const;
Expand Down Expand Up @@ -194,6 +196,42 @@ async function renderVariant(browser: Browser, cfg: VCaseReactConfig, hash: stri
}
}

/**
* The fake-clock instants of a case with a frame interval. The page's clock is paused before
* navigation and stays paused through load, readiness, fonts and images, so everything up to
* the first settle frame (module code, React's first render and effects) sees
* `performance.now() === 0` and `Date.now() === wallStart`, however long loading takes in real
* time. Each settle frame then runs the clock forward by exactly `interval` ms; Playwright's
* fake `requestAnimationFrame` fires at every multiple of 16 ms of `performance.now()` with that
* value as its timestamp. The capture is at `performance.now() === capture`.
*
* Only `page.clock.pauseAt(wallStart)` is called, never `install` + `pauseAt`: Playwright
* replays clock calls into each new document with the real wall time at which they were made,
* and the clock runs between `install` and `pauseAt`, so the page's `performance.now()` would
* start at the real milliseconds between the two calls (0 on one run, 4 on another).
*/
export function frameClock(clock: string | null | undefined, frames: number, interval: number): { wallStart: number; capture: number } {
const wallStart = new Date(clock ?? DEFAULT_CLOCK).getTime();
if (!Number.isFinite(wallStart)) throw new Error(`invalid clock ${JSON.stringify(clock)}`);
return { wallStart, capture: frames * interval };
}

/** What the page's (fake) clock reads. */
export interface ClockReading {
wall: number;
perf: number;
}

async function readClock(page: Page): Promise<ClockReading> {
return page.evaluate(() => ({ wall: Date.now(), perf: performance.now() }));
}

/** Empty when the page's clock reads exactly the expected instant; otherwise why not. */
export function clockProblems(read: ClockReading, wall: number, perf: number, when: string): string[] {
if (read.wall === wall && read.perf === perf) return [];
return [`fake clock ${when}: performance.now() = ${read.perf}, Date.now() = ${read.wall}; expected ${perf} and ${wall}`];
}

/**
* Waits [frames] frames. On the real clock these are animation frames. With a frame interval
* the page runs on Playwright's fake clock and each frame advances it by that many ms, so a
Expand Down
24 changes: 24 additions & 0 deletions packages/react/test/clock.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import { describe, expect, it } from "vitest";
import { clockProblems, DEFAULT_CLOCK, frameClock } from "../src/node/index.js";

describe("frame clock", () => {
it("starts at the configured clock, or the default one, and captures at frames * interval", () => {
expect(frameClock("2030-05-06T07:08:09.010Z", 10, 16)).toEqual({ wallStart: Date.UTC(2030, 4, 6, 7, 8, 9, 10), capture: 160 });
expect(frameClock(undefined, 3, 100)).toEqual({ wallStart: new Date(DEFAULT_CLOCK).getTime(), capture: 300 });
expect(frameClock(null, 2, 0)).toEqual({ wallStart: new Date(DEFAULT_CLOCK).getTime(), capture: 0 });
});

it("rejects a clock that is not a date", () => {
expect(() => frameClock("soon", 1, 16)).toThrow(/invalid clock/);
});

it("accepts only the exact expected instant", () => {
const { wallStart } = frameClock(undefined, 10, 16);
expect(clockProblems({ wall: wallStart, perf: 0 }, wallStart, 0, "before the first frame")).toEqual([]);
// The flake this guards against: the page's performance.now() started a few real ms late.
expect(clockProblems({ wall: wallStart, perf: 4 }, wallStart, 0, "before the first frame")).toEqual([
`fake clock before the first frame: performance.now() = 4, Date.now() = ${wallStart}; expected 0 and ${wallStart}`,
]);
expect(clockProblems({ wall: wallStart + 1000, perf: 160 }, wallStart + 160, 160, "at capture")).toHaveLength(1);
});
});
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading