Skip to content

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

TypeScript

test(harness): busyWindowProof reads a slow tail inside a fast window locally (#9233)

Christopher Chedeau3a2d3d97bbff
diff --git a/internal/interaction-harness/README.md b/internal/interaction-harness/README.md
index e258459a33..a1fbf1876e 100644
--- a/internal/interaction-harness/README.md
+++ b/internal/interaction-harness/README.md
@@ -160,8 +160,9 @@ casts are 2 px quantized: the frames come at the
viewport's size, but the page in them is captured at half resolution, so
positions move in 2 CSS px steps (Chromium's in 1). With under two steps of
motion per frame, a frame delivered a few ms early shows no step and reads as
-not moved. The proof reports `stepPx` and `pxPerFrame` and notes motion under
-two steps per frame, which never fails it. Move a proof's element at least two
+not moved. The proof reports `stepPx` and `pxPerFrame` and notes each stretch
+that moves under two steps per frame, read over four frames at a time so a
+slow tail inside a fast window shows, which never fails it. Move a proof's element at least two
steps a frame: the self-tests move 560 px in 1,600 ms, about 4.8 px a frame.
On a two-core runner the software compositor and the screencast share the core
@@ -187,9 +188,12 @@ which the control moved on fewer than four frames fails, since the machine
presented too little to judge. A run of frames with no new position counts as
moved when the change that ends it is a single cast step: the component moves
under one step a frame there, as on an easing tail, which the cast cannot show
-on every frame. The run must also read as a slowing curve, at most one frame
-longer than the component's run before it. A freeze ends in a catch-up of more
-than one step, a stall in a frame-counted animation is longer than its runs
+on every frame. Where it moved under two steps a frame over the frames just
+before the run (a spring's slow tail inside a fast window), a frame delivered
+early can show no step too, so the change may carry the motion of every frame
+the run held at that pace, to the nearest step. The run must also read as a
+slowing curve, at most one frame longer than the component's run before it. A
+freeze ends in a catch-up of more than that, a stall in a frame-counted animation is longer than its runs
before it, and a run that no change ends stays a miss. The component still has
to show a new position on at least four of the control's frames. The cast step (`stepPx`)
is read from the value's changes in the judged part, so a position the page
diff --git a/internal/interaction-harness/src/busy.control.test.ts b/internal/interaction-harness/src/busy.control.test.ts
index f18b732b53..8ce77e9cf0 100644
--- a/internal/interaction-harness/src/busy.control.test.ts
+++ b/internal/interaction-harness/src/busy.control.test.ts
@@ -157,7 +157,7 @@ describe('busyWindowProof against a control', () => {
const proof = busyWindowProof(tail, BLOCK, {control: asControl(moving())});
expect(proof.verdict.failures, proof.summary).toEqual([]);
expect(proof.control?.belowStep).toBeGreaterThan(0);
- expect(proof.summary).toMatch(/under one cast step a frame/);
+ expect(proof.summary).toMatch(/where the cast could not show the step/);
});
it('still fails a slow component frozen on frames the control moved on: the change that ends the run catches up more than one step', () => {
diff --git a/internal/interaction-harness/src/busy.slowtail.fixture.ts b/internal/interaction-harness/src/busy.slowtail.fixture.ts
new file mode 100644
index 0000000000..717b941537
--- /dev/null
+++ b/internal/interaction-harness/src/busy.slowtail.fixture.ts
@@ -0,0 +1,193 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file busy.slowtail.fixture.ts
+ * @input One recorded busy-main-thread run of a spring settling through a
+ * 1,000 ms block in headless Chromium, with a compositor control box
+ * @output `tracked` and `control`: the screencast frames each was tracked
+ * in, as [ms after the block started, x in CSS px, or null where it was not
+ * found]; `block`: the block's
+ * span on the same clock. The spring moves 3.6 px a frame over the window
+ * and about 1.7 px a frame in its tail, on a 1 px cast grid: at +968 ms its
+ * frame holds the position before (the control moved), and the next frame
+ * catches up 2 px.
+ * @position Fixture for busy.test.ts
+ */
+
+export const block = {from: 0, to: 1000};
+
+export const tracked: ReadonlyArray<readonly [number, number | null]> = [
+ [-73.1, null],
+ [-56.1, 9],
+ [-41.3, 41],
+ [-26, 45],
+ [-10.1, 50],
+ [1.1, 55],
+ [17.1, 59],
+ [29.7, 64],
+ [46.8, 68],
+ [57.2, 74],
+ [73.9, 78],
+ [85.1, 83],
+ [101.3, 87],
+ [124.4, 93],
+ [141.7, 101],
+ [152.3, 107],
+ [169.5, 110],
+ [185.6, 116],
+ [196.6, 122],
+ [212.6, 125],
+ [229.8, 131],
+ [246.5, 136],
+ [257.7, 141],
+ [273.8, 145],
+ [286, 150],
+ [301.1, 154],
+ [323.4, 158],
+ [340.6, 165],
+ [350.6, 170],
+ [367.9, 172],
+ [384.2, 177],
+ [395.7, 181],
+ [411.8, 184],
+ [429.2, 189],
+ [446.7, 193],
+ [456.8, 197],
+ [474.1, 200],
+ [484.4, 204],
+ [501.8, 206],
+ [523.8, 210],
+ [540.9, 214],
+ [551.3, 218],
+ [568.7, 220],
+ [584.9, 223],
+ [596.2, 226],
+ [612.3, 229],
+ [630, 231],
+ [647.3, 235],
+ [658.4, 237],
+ [675.6, 239],
+ [686.1, 242],
+ [703.2, 244],
+ [729, 246],
+ [746.3, 250],
+ [756.5, 252],
+ [773.6, 254],
+ [784.8, 256],
+ [801, 257],
+ [812.3, 259],
+ [829.7, 260],
+ [846.9, 262],
+ [857, 264],
+ [874.2, 265],
+ [884.3, 267],
+ [901.5, 268],
+ [923.8, 270],
+ [941, 272],
+ [951.2, 274],
+ [968.4, 274],
+ [981.9, 276],
+ [996, 277],
+ [1008.7, 278],
+ [1029, 279],
+ [1046.2, 281],
+ [1056.3, 282],
+ [1073.7, 282],
+ [1085.9, 284],
+ [1103.6, 284],
+ [1113.8, 285],
+ [1131, 286],
+ [1141.1, 287],
+ [1158.8, 288],
+ [1168.9, 289],
+ [1186.3, 289],
+ [1196.5, 290],
+];
+
+export const control: ReadonlyArray<readonly [number, number | null]> = [
+ [-73.1, null],
+ [-56.1, 123],
+ [-41.3, 133],
+ [-26, 142],
+ [-10.1, 151],
+ [1.1, 160],
+ [17.1, 167],
+ [29.7, 177],
+ [46.8, 184],
+ [57.2, 194],
+ [73.9, 201],
+ [85.1, 210],
+ [101.3, 217],
+ [124.4, 226],
+ [141.7, 241],
+ [152.3, 231],
+ [169.5, 224],
+ [185.6, 214],
+ [196.6, 204],
+ [212.6, 198],
+ [229.8, 188],
+ [246.5, 178],
+ [257.7, 168],
+ [273.8, 161],
+ [286, 151],
+ [301.1, 144],
+ [323.4, 135],
+ [340.6, 122],
+ [350.6, 110],
+ [367.9, 105],
+ [384.2, 94],
+ [395.7, 85],
+ [411.8, 78],
+ [429.2, 68],
+ [446.7, 58],
+ [456.8, 48],
+ [474.1, 42],
+ [484.4, 30],
+ [501.8, 25],
+ [523.8, 14],
+ [540.9, 0],
+ [551.3, 11],
+ [568.7, 17],
+ [584.9, 28],
+ [596.2, 37],
+ [612.3, 44],
+ [630, 54],
+ [647.3, 64],
+ [658.4, 75],
+ [675.6, 81],
+ [686.1, 92],
+ [703.2, 98],
+ [729, 108],
+ [746.3, 124],
+ [756.5, 134],
+ [773.6, 140],
+ [784.8, 151],
+ [801, 157],
+ [812.3, 167],
+ [829.7, 174],
+ [846.9, 184],
+ [857, 194],
+ [874.2, 201],
+ [884.3, 210],
+ [901.5, 217],
+ [923.8, 226],
+ [941, 241],
+ [951.2, 231],
+ [968.4, 225],
+ [981.9, 215],
+ [996, 206],
+ [1008.7, 198],
+ [1029, 190],
+ [1046.2, 178],
+ [1056.3, 168],
+ [1073.7, 162],
+ [1085.9, 151],
+ [1103.6, 144],
+ [1113.8, 133],
+ [1131, 126],
+ [1141.1, 117],
+ [1158.8, 110],
+ [1168.9, 100],
+ [1186.3, 94],
+ [1196.5, 84],
+];
diff --git a/internal/interaction-harness/src/busy.test.ts b/internal/interaction-harness/src/busy.test.ts
index 44a2446ecc..20c5b0f614 100644
--- a/internal/interaction-harness/src/busy.test.ts
+++ b/internal/interaction-harness/src/busy.test.ts
@@ -15,6 +15,7 @@
import {describe, expect, it} from 'vitest';
import {busyWindowProof} from './busy';
import * as skip from './busy.skip.fixture';
+import * as slowTail from './busy.slowtail.fixture';
import {inPresentationOrder, type TrackedFrame} from './frames';
const FRAME = 1000 / 60;
@@ -534,3 +535,121 @@ describe('inPresentationOrder', () => {
expect(proof.verdict.failures).toEqual([]);
});
});
+
+/** `slowTail`'s frames as tracked boxes on the x axis. */
+const slowTailFrames = (
+ frames: ReadonlyArray<readonly [number, number | null]>,
+): TrackedFrame[] =>
+ frames.map(
+ ([t, x]) =>
+ ({
+ t,
+ box: x == null ? null : {x, y: 0, width: 1, height: 1},
+ }) as TrackedFrame,
+ );
+
+describe('busyWindowProof in a slow tail', () => {
+ it('reads a frame that shows no step under two steps a frame, then a two-frame catch-up, as moved', () => {
+ // A spring settling: 3.6 px a frame over the window, about 1.7 in its
+ // tail on a 1 px grid. Its frame at +968 ms holds the position before
+ // while the control moves, and the next catches up 2 px.
+ const proof = busyWindowProof(
+ slowTailFrames(slowTail.tracked),
+ slowTail.block,
+ {
+ axis: 'x',
+ settledWithin: 2,
+ control: slowTailFrames(slowTail.control),
+ },
+ );
+ expect(proof.verdict.failures).toEqual([]);
+ expect(proof.notes.join('\n')).toMatch(
+ /under two of the cast's 1 px position steps from \+\d+ ms/,
+ );
+ });
+
+ it('still fails a two-frame freeze in a slow tail', () => {
+ const tracked = slowTailFrames(slowTail.tracked);
+ // Hold the tail's position for two frames before the catch-up.
+ const i = tracked.findIndex(f => f.t > 968 && f.t < 975);
+ const frozen = tracked.map((f, k) =>
+ k === i + 1 ? ({...f, box: {...tracked[i].box!}} as TrackedFrame) : f,
+ );
+ const proof = busyWindowProof(frozen, slowTail.block, {
+ axis: 'x',
+ settledWithin: 2,
+ control: slowTailFrames(slowTail.control),
+ });
+ expect(proof.verdict.failures.join('\n')).toMatch(/moved on \d+ of/);
+ });
+
+ it('still fails a two-frame freeze right after one frame that showed no step, at one step a frame or more', () => {
+ // 1.75 px a frame on a 1 px grid, the control moving on every frame: one
+ // frame shows no step (an early delivery can explain that), then the two
+ // frames after the next step hold too, which an early delivery cannot.
+ const j = at(1300);
+ const frames = moving().map((f, i) => {
+ const y =
+ i === j
+ ? Math.floor(1.75 * (j - 1))
+ : i === j + 2 || i === j + 3
+ ? Math.floor(1.75 * (j + 1))
+ : Math.floor(1.75 * i);
+ return {...f, box: {...f.box!, y}} as TrackedFrame;
+ });
+ const control = moving().map(
+ f =>
+ ({
+ ...f,
+ box: {x: f.box!.y, y: 0, width: 12, height: 12},
+ }) as TrackedFrame,
+ );
+ const proof = busyWindowProof(frames, BLOCK, {control});
+ expect(proof.stepPx).toBe(1);
+ expect(proof.verdict.failures.join('\n')).toMatch(/moved on \d+ of/);
+ });
+
+ it('under one step a frame, still fails a two-frame freeze that ends in a three-step catch-up, and reads one early frame as moved', () => {
+ // 0.8 px a frame on a 1 px grid, then the same doubled on a 2 px grid,
+ // the control moving on every frame. Frame 42 shows 33 px (0.8 px a frame
+ // from 0); an early frame there adds at most one step to the catch-up.
+ const control = moving().map(
+ f =>
+ ({
+ ...f,
+ box: {x: f.box!.y, y: 0, width: 12, height: 12},
+ }) as TrackedFrame,
+ );
+ const at08 = (held: readonly number[], grid: number) =>
+ moving().map((f, i) => {
+ const shown = held.includes(i) ? 42 : i;
+ return {
+ ...f,
+ box: {...f.box!, y: grid * Math.floor(0.8 * shown)},
+ } as TrackedFrame;
+ });
+ for (const grid of [1, 2]) {
+ // 32, 32, 33, 33, 33, 36 (doubled on the 2 px grid): a freeze.
+ const frozen = busyWindowProof(at08([43, 44], grid), BLOCK, {control});
+ expect(frozen.stepPx).toBe(grid);
+ expect(frozen.verdict.failures.join('\n')).toMatch(/moved on \d+ of/);
+ // 32, 32, 33, 33, 35: one early frame, then the frames go on.
+ const early = busyWindowProof(at08([43], grid), BLOCK, {control});
+ expect(early.verdict.failures).toEqual([]);
+ }
+ });
+
+ it('still fails a frame that shows no step in a fast window', () => {
+ // 3 px a frame, the control moving on every frame: one repeated frame is
+ // a freeze there, and its 6 px catch-up two steps past the grid.
+ const control = moving().map(
+ f =>
+ ({
+ ...f,
+ box: {x: f.box!.y, y: 0, width: 12, height: 12},
+ }) as TrackedFrame,
+ );
+ const proof = busyWindowProof(repeating([at(1300)]), BLOCK, {control});
+ expect(proof.verdict.failures.join('\n')).toMatch(/moved on \d+ of/);
+ });
+});
diff --git a/internal/interaction-harness/src/busy.ts b/internal/interaction-harness/src/busy.ts
index 918834f7cd..226a4191de 100644
--- a/internal/interaction-harness/src/busy.ts
+++ b/internal/interaction-harness/src/busy.ts
@@ -142,13 +142,14 @@ export interface BusyControlRead {
/** The control's longest time without a new position, the edges included. */
readonly longestStallMs: number;
/**
- * Of `movedWith`, the frames counted as moved because the component's motion
- * there was under one cast step per frame (see `busyWindowProof`).
+ * Of `movedWith`, the frames counted as moved where the cast could not show
+ * the component's motion: under one cast step per frame, or a frame
+ * delivered early under two (see `busyWindowProof`).
*/
readonly belowStep: number;
/**
* The component's longest time without a new position, read the same way:
- * a run of unchanged frames under one cast step per frame is motion.
+ * a run of unchanged frames the cast could not show is motion.
*/
readonly componentStallMs: number;
}
@@ -361,6 +362,37 @@ export interface BusyProof extends FrameStats {
readonly summary: string;
}
+/**
+ * The stretches of a judged series that move under `limitPx` per frame,
+ * read over four frames at a time, merged where they overlap: where the cast
+ * cannot show a step on every frame.
+ */
+function slowStretches(
+ values: readonly {t: number; value: number}[],
+ cadence: number,
+ limitPx: number,
+): {from: number; to: number; pxPerFrame: number}[] {
+ const SPAN = 4;
+ const stretches: {from: number; to: number; pxPerFrame: number}[] = [];
+ for (let k = 0; k + SPAN < values.length; k += 1) {
+ const a = values[k];
+ const b = values[k + SPAN];
+ const frames = (b.t - a.t) / cadence;
+ const pxPerFrame = frames > 0 ? Math.abs(b.value - a.value) / frames : 0;
+ if (pxPerFrame <= 0 || pxPerFrame >= limitPx) {
+ continue;
+ }
+ const last = stretches[stretches.length - 1];
+ if (last != null && a.t <= last.to) {
+ last.to = b.t;
+ last.pxPerFrame = Math.min(last.pxPerFrame, pxPerFrame);
+ } else {
+ stretches.push({from: a.t, to: b.t, pxPerFrame});
+ }
+ }
+ return stretches;
+}
+
/**
* Frame evidence for a busy window: how many frames the screencast presented
* inside it, how many of them moved the tracked axis, and the longest stall.
@@ -407,7 +439,9 @@ export interface BusyProof extends FrameStats {
*
* `stepPx` and `pxPerFrame` say whether a frame's motion is resolvable at
* all: under two position steps per frame, a frame delivered early can show
- * no step and read as not moved, which the proof notes (never a failure).
+ * no step and read as not moved. The proof notes each stretch of the judged
+ * part that moves that slowly, read over four frames at a time so a slow tail
+ * inside a fast window shows (never a failure).
*
* A loaded machine's screencast can skip frames the compositor still presents
* (Chromium). Given the compositor's record (`presented`, from
@@ -433,9 +467,12 @@ export interface BusyProof extends FrameStats {
* A run of frames with no new component position counts as moved when the
* change that ends it is a single cast step (`stepPx`): the component moves
* under one step per frame there, as on an easing tail, which the cast cannot
- * show on every frame. The run also has to read as a slowing curve, at most
- * one frame longer than the component's run before it. A freeze ends in a
- * catch-up of more than one step, a stall in a frame-counted animation is
+ * show on every frame. Where the component moved under two steps per frame
+ * over the frames just before the run, a frame delivered early can show no
+ * step too, so the change may carry the motion of every frame the run held
+ * at that pace, to the nearest step. The run also has to read as a slowing
+ * curve, at most one frame longer than the component's run before it. A
+ * freeze ends in a larger catch-up, a stall in a frame-counted animation is
* longer than its runs before it, and a run that no change ends stays a miss.
* The component still has to show a new position on at least
* `minJudgedFrames` of the control's frames.
@@ -742,9 +779,11 @@ export function busyWindowProof(
`the screencast skipped ${recorderSkipped} frames the compositor presented (at ${skips.map(g => `+${(g.from - window.from).toFixed(0)} ms`).join(', ')})`,
);
}
- if (pxPerFrame > 0 && pxPerFrame < 2 * stepPx) {
+ // Read over a few frames at a time, not the whole part: a fast window can
+ // end in a slow tail whose frames the cast cannot all show.
+ for (const stretch of slowStretches(judgedValues, cadence, 2 * stepPx)) {
notes.push(
- `${pxPerFrame.toFixed(1)} px/frame is under two of the cast's ${stepPx} px position steps: a frame delivered early can show no step and read as not moved`,
+ `${stretch.pxPerFrame.toFixed(1)} px/frame is under two of the cast's ${stepPx} px position steps from +${(stretch.from - window.from).toFixed(0)} ms to +${(stretch.to - window.from).toFixed(0)} ms: a frame delivered early there can show no step and read as not moved`,
);
}
// The control's own new positions in the judged part, against its frame
@@ -770,10 +809,10 @@ export function busyWindowProof(
}
const controlEdges = [judged.from, ...controlChanges, judged.to];
// A frame with no new component position, in a run of such frames whose
- // next change is a single cast step: the component moves under one step
- // per frame there, which the cast cannot show on every frame, so the
- // frame counts as moved. A freeze ends in a catch-up of more than one
- // step, and a run that no change ends stays a miss.
+ // next change the cast's step or an early frame explains (`underStep`):
+ // the cast cannot show every frame there, so the frame counts as moved.
+ // A freeze ends in a larger catch-up, and a run that no change ends stays
+ // a miss.
const series = tracked.flatMap(f =>
f.box == null ? [] : [{t: f.t, value: f.box[axis]}],
);
@@ -788,6 +827,18 @@ export function busyWindowProof(
}
return s;
};
+ // The component's motion per frame over up to four frames before frame
+ // `start`, or null with fewer than two to read.
+ const pxPerFrameBefore = (start: number): number | null => {
+ const back = Math.min(4, start);
+ if (back < 2) {
+ return null;
+ }
+ const frames = (series[start].t - series[start - back].t) / cadence;
+ return frames > 0
+ ? Math.abs(series[start].value - series[start - back].value) / frames
+ : null;
+ };
const underStep = (t: number): boolean => {
const i = seriesIndex.get(t);
if (i == null || changed.has(t)) {
@@ -798,15 +849,30 @@ export function busyWindowProof(
while (k < series.length && same(k, i)) {
k += 1;
}
- if (
- k >= series.length ||
- Math.abs(series[k].value - series[i].value) >= 1.5 * stepPx
- ) {
+ if (k >= series.length) {
+ return false;
+ }
+ const unchanged = k - 1 - start;
+ // Under one step a frame the change that ends the run is a single step.
+ // Under two, a frame delivered early can also show no step, and the
+ // change then carries the motion of every frame the run held, at the
+ // pace of the frames before it, to the nearest step. An early frame
+ // hides one frame's motion: at one step a frame or more the run is one
+ // frame long, and under one step a frame it adds at most one step to
+ // the catch-up.
+ const catchUp = Math.abs(series[k].value - series[i].value);
+ const pace = pxPerFrameBefore(start);
+ const shown =
+ catchUp < 1.5 * stepPx ||
+ (pace != null &&
+ pace < 2 * stepPx &&
+ (pace < stepPx ? catchUp < 2.5 * stepPx : unchanged <= 1) &&
+ catchUp <= (unchanged + 1) * pace + stepPx);
+ if (!shown) {
return false;
}
// A slowing curve lengthens its runs a frame at a time: a run more than
// one frame longer than the one before it is a stall.
- const unchanged = k - 1 - start;
const before = start > 0 ? start - 1 - runStart(start - 1) : 0;
return unchanged <= before + 1;
};
@@ -897,7 +963,7 @@ export function busyWindowProof(
: `, on screen from +${onScreenFromMs.toFixed(0)} ms (nothing moved before the block)`) +
(controlRead == null
? ''
- : `; against the control: moved on ${controlRead.movedWith} of its ${controlRead.moved} frames${controlRead.belowStep > 0 ? ` (${controlRead.belowStep} under one cast step a frame)` : ''}, its longest stall ${controlRead.longestStallMs.toFixed(1)} ms`) +
+ : `; against the control: moved on ${controlRead.movedWith} of its ${controlRead.moved} frames${controlRead.belowStep > 0 ? ` (${controlRead.belowStep} where the cast could not show the step)` : ''}, its longest stall ${controlRead.longestStallMs.toFixed(1)} ms`) +
notes.map(note => `; note: ${note}`).join('');
return {
...stats,