Skip to content

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

TypeScript

test(interaction-harness): wait for a cast frame presented after a time (#10558)

Christopher Chedeau53eb451314c0
diff --git a/internal/interaction-harness/README.md b/internal/interaction-harness/README.md
index c628da135a..a332748ed4 100644
--- a/internal/interaction-harness/README.md
+++ b/internal/interaction-harness/README.md
@@ -242,6 +242,18 @@ raw numbers for the report. Frames are judged in presentation order: a loaded
machine can deliver them out of order. `castStoryboard` turns the frames of the
block into a filmstrip.
+To read frames after a moment, such as the rest after a block, wait for them by
+time: `waitForCastFrame(cast, {after, during})` returns once the cast holds a
+frame presented after `after`, epoch ms on the page's clock. A frame that
+arrives after that moment can still have been presented before it, so a count
+of frames delivered is no such wait. `cast.lastFrameAt()` reads the latest
+presentation time captured so far. Past 5 s with no such frame, the wait fails.
+When no frame came for longer than `FRAME_STARVATION_MS`, it throws
+`FrameStarvationError`: the screen did not change, or the page was starved of
+frames. Keep something moving, such as `startBusyControl`, to tell them apart.
+While frames still come, all presented before `after`, the error names both
+times.
+
A just-started animation can reach the screen after the block began (50–100 ms
later in WebKit on a loaded machine). When the cast saw the element at rest
before the block (wait for `cast.frameCount()` to pass 0 before starting the
diff --git a/internal/interaction-harness/src/frames.castFrame.test.ts b/internal/interaction-harness/src/frames.castFrame.test.ts
new file mode 100644
index 0000000000..483f85758e
--- /dev/null
+++ b/internal/interaction-harness/src/frames.castFrame.test.ts
@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file frames.castFrame.test.ts
+ * @input A fake screencast's frame times (no browser)
+ * @output `latestFrameAt` reads the latest presentation time of frames that
+ * arrive out of order. `waitForCastFrame` returns once a frame presented
+ * after its moment arrives, not a frame that arrives after it, and fails by
+ * name when none comes.
+ * @position Unit test of ./frames' cast-frame wait; the browser self-test is
+ * in harness.interaction.browser.spec.ts.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+ FrameStarvationError,
+ latestFrameAt,
+ waitForCastFrame,
+ type Screencast,
+} from './frames';
+
+/** A cast whose frames arrive one every `everyMs`, presented at `times`. */
+function fakeCast(times: readonly number[], everyMs: number): Screencast {
+ const start = Date.now();
+ const arrived = () =>
+ times
+ .slice(0, Math.floor((Date.now() - start) / everyMs) + 1)
+ .map(t => ({t}));
+ return {
+ frameCount: () => arrived().length,
+ lastFrameAt: () => latestFrameAt(arrived()),
+ stop: async () => [],
+ };
+}
+
+describe('latestFrameAt', () => {
+ it('reads the latest presentation time, not the frame that arrived last', () => {
+ expect(latestFrameAt([{t: 10}, {t: 46}, {t: 35}])).toBe(46);
+ expect(latestFrameAt([])).toBeNull();
+ });
+});
+
+describe('waitForCastFrame', () => {
+ it('returns a frame presented after its moment, not the first one that arrives after the wait begins', async () => {
+ // Every frame arrives after the wait begins; only the last was presented
+ // after 25.
+ const cast = fakeCast([10, 20, 30], 20);
+ await expect(
+ waitForCastFrame(cast, {after: 25, during: 'the box rested'}),
+ ).resolves.toBe(30);
+ });
+
+ it('names both times, not starvation, when frames still come but none was presented after its moment', async () => {
+ // Every frame was presented 5 ms ago: the cast is not quiet.
+ const fresh: Screencast = {
+ frameCount: () => 1,
+ lastFrameAt: () => Date.now() - 5,
+ stop: async () => [],
+ };
+ const outcome = await waitForCastFrame(fresh, {
+ after: Date.now() + 60_000,
+ during: 'the box moved',
+ timeoutMs: 100,
+ }).catch((error: unknown) => error);
+ expect(outcome).not.toBeInstanceOf(FrameStarvationError);
+ expect(String(outcome)).toMatch(
+ /waitForCastFrame: no frame presented after \d+\.\d while the box moved \(\d+ ms\)\. The cast's latest frame was presented \d+\.\d ms before that, \d+\.\d ms ago, so frames still come/,
+ );
+ });
+
+ it('fails by name when no frame presented after its moment comes', async () => {
+ const cast = fakeCast([10, 20], 5);
+ const outcome = await waitForCastFrame(cast, {
+ after: 100,
+ during: 'the box rested',
+ timeoutMs: 100,
+ }).catch((error: unknown) => error);
+ expect(outcome).toBeInstanceOf(FrameStarvationError);
+ expect(String(outcome)).toMatch(
+ /waitForCastFrame: the page drew 0 frames while the box rested \(\d+ ms\), where the proof needs 1\. No frame came for \d+\.\d ms: the screen did not change after 100\.0, or the page was starved of frames\. Keep something moving/,
+ );
+ });
+});
diff --git a/internal/interaction-harness/src/frames.ts b/internal/interaction-harness/src/frames.ts
index 3578d044d2..a03e28a2ed 100644
--- a/internal/interaction-harness/src/frames.ts
+++ b/internal/interaction-harness/src/frames.ts
@@ -48,6 +48,13 @@ export interface Screencast {
* position).
*/
frameCount(): number;
+ /**
+ * When the latest frame captured so far was presented, epoch ms on the
+ * page's clock, as `stop()` stamps it; null before the first frame. A loaded
+ * machine delivers frames late and out of order, so a frame that arrives
+ * after a moment can still have been presented before it.
+ */
+ lastFrameAt(): number | null;
/** Stops and returns every frame captured, in order. */
stop(): Promise<CastFrame[]>;
}
@@ -124,6 +131,7 @@ async function chromiumScreencast(
});
return {
frameCount: () => frames.length,
+ lastFrameAt: () => latestFrameAt(frames),
async stop() {
await cdp.send('Page.stopScreencast');
cdp.off('Page.screencastFrame', onFrame);
@@ -177,6 +185,10 @@ async function webkitScreencast(
const wallMinusMonotonic = Date.now() - Number(process.hrtime.bigint()) / 1e6;
return {
frameCount: () => frames.length,
+ lastFrameAt: () => {
+ const latest = latestFrameAt(frames);
+ return latest == null ? null : latest + wallMinusMonotonic;
+ },
async stop() {
await session.send('Screencast.stopScreencast');
session.off?.('Screencast.screencastFrame', onFrame);
@@ -191,6 +203,70 @@ async function webkitScreencast(
};
}
+/**
+ * The latest presentation timestamp among `frames`, or null when there are
+ * none. A loaded machine can deliver frames out of order, so the frame that
+ * arrived last need not be the latest.
+ */
+export function latestFrameAt(
+ frames: readonly {readonly t: number}[],
+): number | null {
+ return frames.length === 0 ? null : Math.max(...frames.map(f => f.t));
+}
+
+/**
+ * Waits until `cast` holds a frame presented after `after`, epoch ms on the
+ * page's clock, and returns when that frame was presented. It reads
+ * presentation times, not counts: a frame delivered after `after` can still
+ * have been presented before it. `during` names what the frame had to show.
+ *
+ * Past `timeoutMs` (5 s) with no such frame, it fails. When the cast has
+ * sent no frame for longer than `FRAME_STARVATION_MS`, the error is
+ * `FrameStarvationError`. A starved page draws nothing, and a screen that
+ * does not change presents no frame either. So keep something moving, such
+ * as `startBusyControl`, for the wait to read starvation. While frames still
+ * come, all presented before `after`, the error names both times.
+ */
+export async function waitForCastFrame(
+ cast: Screencast,
+ {
+ after,
+ during,
+ timeoutMs = 5_000,
+ }: {
+ readonly after: number;
+ readonly during: string;
+ readonly timeoutMs?: number;
+ },
+): Promise<number> {
+ const start = Date.now();
+ for (;;) {
+ const latest = cast.lastFrameAt();
+ if (latest != null && latest > after) {
+ return latest;
+ }
+ const elapsed = Date.now() - start;
+ if (elapsed > timeoutMs) {
+ const quietMs =
+ latest == null ? Number.POSITIVE_INFINITY : Date.now() - latest;
+ if (latest == null || quietMs > FRAME_STARVATION_MS) {
+ throw new FrameStarvationError({
+ by: 'waitForCastFrame',
+ during: `${during} (${elapsed} ms)`,
+ frames: 0,
+ min: 1,
+ longestGapMs: quietMs,
+ cause: `the screen did not change after ${after.toFixed(1)}, or the page was starved of frames. Keep something moving, such as \`startBusyControl\`, to tell them apart`,
+ });
+ }
+ throw new Error(
+ `waitForCastFrame: no frame presented after ${after.toFixed(1)} while ${during} (${elapsed} ms). The cast's latest frame was presented ${(after - latest).toFixed(1)} ms before that, ${quietMs.toFixed(1)} ms ago, so frames still come`,
+ );
+ }
+ await new Promise(resolve => setTimeout(resolve, 10));
+ }
+}
+
/**
* Frames sorted by their presentation timestamp. A loaded machine can deliver
* screencast frames out of order (a frame stamped 35 ms arriving after one
@@ -819,6 +895,11 @@ export interface FrameShortfall {
* drew fewer than two frames.
*/
readonly longestGapMs: number;
+ /**
+ * Why no frame came, when more than starvation explains it, such as a
+ * screen that did not change. The default names starvation alone.
+ */
+ readonly cause?: string;
}
/**
@@ -831,7 +912,7 @@ export class FrameStarvationError extends Error {
readonly numbers: FrameShortfall;
constructor(numbers: FrameShortfall) {
super(
- `${numbers.by ?? 'requireFrames'}: the page drew ${framesDrawn(numbers.frames)} while ${numbers.during}, where the proof needs ${numbers.min}. ${Number.isFinite(numbers.longestGapMs) ? `No frame came for ${numbers.longestGapMs.toFixed(1)} ms` : 'No second frame came'}: the page was starved of frames (a loaded machine, or a long task on the page), so the run proves nothing about the motion`,
+ `${numbers.by ?? 'requireFrames'}: the page drew ${framesDrawn(numbers.frames)} while ${numbers.during}, where the proof needs ${numbers.min}. ${Number.isFinite(numbers.longestGapMs) ? `No frame came for ${numbers.longestGapMs.toFixed(1)} ms` : 'No second frame came'}: ${numbers.cause ?? 'the page was starved of frames (a loaded machine, or a long task on the page), so the run proves nothing about the motion'}`,
);
this.name = 'FrameStarvationError';
this.numbers = numbers;
diff --git a/internal/interaction-harness/src/harness.interaction.browser.spec.ts b/internal/interaction-harness/src/harness.interaction.browser.spec.ts
index 63f2efd3bf..b31bd97332 100644
--- a/internal/interaction-harness/src/harness.interaction.browser.spec.ts
+++ b/internal/interaction-harness/src/harness.interaction.browser.spec.ts
@@ -127,6 +127,7 @@ import {
trackControl,
trackMarker,
waitForAnimation,
+ waitForCastFrame,
releaseAnimationLog,
waitForRest,
watchAnimations,
@@ -1003,6 +1004,51 @@ test.describe('touch input', () => {
});
test.describe('frame evidence', () => {
+ test('a cast reads when its latest frame was presented before it stops, on the page clock, and a wait for a frame on a screen held still fails by name', async ({
+ page,
+ }) => {
+ await busyFixture(page);
+ const box = page.locator('#box');
+ await markElement(box, {mode: 'outline'});
+ const cast = await startScreencast(page);
+ await box.evaluate(el =>
+ el.animate(
+ [{transform: 'translateY(0px)'}, {transform: 'translateY(560px)'}],
+ {duration: 500},
+ ),
+ );
+ const pageNow = () =>
+ page.evaluate(() => performance.timeOrigin + performance.now());
+ const after = await pageNow();
+ const at = await waitForCastFrame(cast, {after, during: 'the box moved'});
+ expect(at).toBeGreaterThan(after);
+ // Once the box rests, nothing on screen changes, so the cast sends no
+ // frame, and the wait fails at its cap as the cast's starvation. The
+ // frame that shows the box at rest can come after the animation ends. The
+ // screen is still once the cast has sent nothing for 100 ms.
+ await box.evaluate(el =>
+ Promise.all(el.getAnimations().map(a => a.finished)),
+ );
+ await expect
+ .poll(async () => (await pageNow()) - (cast.lastFrameAt() ?? 0), {
+ message: 'the cast goes quiet once the box rests',
+ timeout: 2_000,
+ })
+ .toBeGreaterThan(100);
+ const still = await waitForCastFrame(cast, {
+ after: await pageNow(),
+ during: 'the screen held still',
+ timeoutMs: 300,
+ }).catch((error: unknown) => error);
+ expect(still).toBeInstanceOf(FrameStarvationError);
+ expect(String(still)).toMatch(
+ /waitForCastFrame: the page drew 0 frames while the screen held still \(\d+ ms\).*: the screen did not change after \d+\.\d, or the page was starved of frames/,
+ );
+ // stop() stamps the frame the first wait read with the same time.
+ const frames = await cast.stop();
+ expect(frames.some(f => f.t === at)).toBe(true);
+ });
+
test('a compositor animation advances every frame through a blocked main thread; a rAF one freezes, whatever the screencast rate', async ({
page,
}, testInfo) => {