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.mdindex 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 loadedmachine can deliver them out of order. `castStoryboard` turns the frames of theblock 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 mslater in WebKit on a loaded machine). When the cast saw the element at restbefore the block (wait for `cast.frameCount()` to pass 0 before starting thediff --git a/internal/interaction-harness/src/frames.castFrame.test.ts b/internal/interaction-harness/src/frames.castFrame.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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) => {