An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file busy.control.test.ts
* @input Synthetic tracked frames (no browser)
* @output The busy-main-thread verdict against a control: a component that
* moves on the control's frames passes through a stall the compositor itself
* makes, and a frozen one, or one the control outpaces by a single frame,
* still fails. Unchanged frames under one cast step a frame count as
* moved; a freeze, whose catch-up is more than one step, and a stall
* longer than the component's runs before it do not. Runs
* of a block too short to judge alone are judged pooled: the control over
* all of them, each run's stall against that run's control. A held
* animation is judged up to its curve's end. A stall before that end still
* fails, and a curve that ends too soon is named.
* @position Unit test of ./busy's control judgment; the frames are
* busy.test.ts's fixtures, and the browser proof with a real compositor
* control is in harness.interaction.browser.spec.ts.
*/
import {describe, expect, it} from 'vitest';
import {busyWindowProof, BusyWindowTooLateError, pooledBusyProof} from './busy';
import {FrameStarvationError, type TrackedFrame} from './frames';
const FRAME = 1000 / 60;
const BLOCK = {from: 1000, to: 1700};
/** A marker moving 3 px per frame from t = 800 to 1900, minus `dropped` frame indices. */
function moving(dropped: readonly number[] = []): TrackedFrame[] {
const frames: TrackedFrame[] = [];
for (let i = 0; 800 + i * FRAME <= 1900; i += 1) {
if (dropped.includes(i)) {
continue;
}
frames.push({
t: 800 + i * FRAME,
box: {x: 0, y: 3 * i, width: 10, height: 10},
} as TrackedFrame);
}
return frames;
}
/** Index of the first frame at or after `t`. */
const at = (t: number) => Math.ceil((t - 800) / FRAME);
/** `moving()` with each frame in `repeats` presenting the previous frame's position. */
function repeating(repeats: readonly number[]): TrackedFrame[] {
return moving().map((f, i) =>
repeats.includes(i)
? ({...f, box: {...f.box!, y: 3 * (i - 1)}} as TrackedFrame)
: f,
);
}
/** `frames` as the control's: the same frames and times, moving along x. */
function asControl(frames: readonly TrackedFrame[]): TrackedFrame[] {
return frames.map(
f =>
({
...f,
box: f.box == null ? null : {x: f.box.y, y: 0, width: 12, height: 12},
}) as TrackedFrame,
);
}
/**
* A frame-counted loop: `step` px a frame, standing still from `lag` ms into
* each window to its end, then going on without catching up.
*/
function frameCounted(
windows: readonly {from: number; to: number}[],
lag: number,
step = 1,
): TrackedFrame[] {
let y = 0;
return moving().map((f, i) => {
if (i > 0 && !windows.some(w => f.t >= w.from + lag && f.t < w.to)) {
y += step;
}
return {...f, box: {...f.box!, y}} as TrackedFrame;
});
}
describe('busyWindowProof against a control', () => {
it('passes a component that moves on every frame the control does, through a stall the compositor makes for both, which fails without the control', () => {
// Three frames in a row presented nothing, for the control too: the
// compositor shared the core the block spins on (a two-core runner).
const gap = [at(1300), at(1300) + 1, at(1300) + 2];
const component = moving(gap);
const control = asControl(moving(gap));
const alone = busyWindowProof(component, BLOCK);
expect(alone.verdict.failures.join('\n')).toMatch(/longest stall/);
const against = busyWindowProof(component, BLOCK, {control});
expect(against.verdict.failures, against.summary).toEqual([]);
expect(against.control).toMatchObject({moved: against.control?.movedWith});
expect(against.summary).toMatch(
/against the control: moved on \d+ of its \d+ frames/,
);
});
it('still fails a frozen component while the control moves', () => {
const frozen = moving().map(
f =>
({
...f,
box: {
...f.box!,
y: f.t >= BLOCK.from ? 3 * at(BLOCK.from) : f.box!.y,
},
}) as TrackedFrame,
);
const proof = busyWindowProof(frozen, BLOCK, {
control: asControl(moving()),
});
expect(proof.verdict.pass).toBe(false);
expect(proof.verdict.failures.join('\n')).toMatch(
/moved on 0 of the \d+ frames the control moved/,
);
expect(proof.verdict.failures.join('\n')).toMatch(
/longer than the control's/,
);
});
it('fails a component the control outpaces: it repeats positions on frames the control moves', () => {
const repeats = [0, 1, 2, 3].map(k => at(1100) + 6 * k);
const proof = busyWindowProof(repeating(repeats), BLOCK, {
control: asControl(moving()),
});
expect(proof.verdict.failures.join('\n')).toMatch(
/moved on \d+ of the \d+ frames the control moved/,
);
});
it('fails a component that misses a single frame the control moved', () => {
// One repeated position: a frame the control moved on and the component
// did not, which a compositor animation never shows, since both are read
// from the same screencast frames.
const proof = busyWindowProof(repeating([at(1300)]), BLOCK, {
control: asControl(moving()),
});
expect(proof.verdict.failures.join('\n')).toMatch(
/moved on \d+ of the \d+ frames the control moved/,
);
expect(proof.control!.moved - proof.control!.movedWith).toBe(1);
});
it('counts unchanged frames on a tail under one cast step a frame as moved: each run of them ends in a single step', () => {
// 3 px a frame, then half a pixel a frame from 1400 ms: the whole-pixel
// positions change every other frame, one step at a time.
const k = at(1400);
const tail = moving().map((f, i) =>
i < k
? f
: ({
...f,
box: {...f.box!, y: 3 * k + Math.floor((i - k) / 2)},
} as TrackedFrame),
);
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(/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', () => {
// Half a pixel a frame throughout, frozen for 12 frames from 1200 ms, then
// back where its clock says: the change that ends the run is 6 steps.
const k = at(1200);
const slow = moving().map(
(f, i) =>
({
...f,
box: {
...f.box!,
y: Math.floor((i >= k && i < k + 12 ? k - 1 : i) / 2),
},
}) as TrackedFrame,
);
const proof = busyWindowProof(slow, BLOCK, {control: asControl(moving())});
expect(proof.verdict.failures.join('\n')).toMatch(
/moved on \d+ of the \d+ frames the control moved/,
);
});
it('still fails a component that stops for good while the control moves: no change ends its run', () => {
const k = at(1300);
const stopped = moving().map((f, i) =>
i < k ? f : ({...f, box: {...f.box!, y: 3 * k}} as TrackedFrame),
);
const proof = busyWindowProof(stopped, BLOCK, {
control: asControl(moving()),
});
expect(proof.verdict.failures.join('\n')).toMatch(
/moved on \d+ of the \d+ frames the control moved/,
);
});
it('still fails a frame-counted component that stands still through the block and resumes one step a frame: it shows too little motion to judge', () => {
// 1 px a frame, counted per frame rather than by the clock: it stands
// still from the block's start to its end, then goes on one step a
// frame, so the change that ends the run is a single step.
const s0 = at(BLOCK.from);
const s1 = at(BLOCK.to);
const counted = moving().map(
(f, i) =>
({
...f,
box: {
...f.box!,
y: i < s0 ? i : i <= s1 ? s0 - 1 : s0 - 1 + (i - s1),
},
}) as TrackedFrame,
);
const proof = busyWindowProof(counted, BLOCK, {
control: asControl(moving()),
});
expect(proof.verdict.failures.join('\n')).toMatch(
/too little motion in this window to judge/,
);
});
it('still fails a frame-counted loop that stalls for a few frames inside the block: its run is longer than the runs before it', () => {
// 1 px a frame, so each step is one cast step, standing still for three
// frames from 1300 ms and going on from there without catching up.
const proof = busyWindowProof(
frameCounted([{from: 1300, to: 1350}], 0),
BLOCK,
{control: asControl(moving())},
);
expect(proof.verdict.failures.join('\n')).toMatch(
/moved on \d+ of the \d+ frames the control moved/,
);
expect(proof.control?.belowStep).toBe(0);
});
it('reads the finest cast step when the judged part shows no change, so a larger jump never passes for one step', () => {
const frozen = moving().map(
f =>
({...f, box: {...f.box!, y: f.t < BLOCK.to ? 0 : 2}}) as TrackedFrame,
);
const proof = busyWindowProof(frozen, BLOCK, {
control: asControl(moving()),
});
expect(proof.stepPx).toBe(0.5);
expect(proof.control?.belowStep).toBe(0);
});
it('reads the cast step from changes, so a position committed off the grid once the block ends does not shrink it', () => {
// An ease-out on a 2 px grid, as WebKit casts one, that ends on 401 once
// the block is over: its tail shows runs of unchanged frames that end in
// a single 2 px step.
const eased = moving().map(
(f, i) =>
({
...f,
box: {
...f.box!,
y:
f.t > BLOCK.to + 20
? 401
: 2 * Math.round((400 - 400 * 0.93 ** i) / 2),
},
}) as TrackedFrame,
);
const proof = busyWindowProof(eased, BLOCK, {
control: asControl(moving()),
});
expect(proof.stepPx).toBe(2);
expect(proof.verdict.failures, proof.summary).toEqual([]);
expect(proof.control?.belowStep).toBeGreaterThan(0);
});
it('judges a component that enters from off screen from its first position inside the block, against the control', () => {
// A card pushed in from an edge first shows 20 ms into the block. The
// cast's frames before the block show the screen without it.
const entering = moving().map(f =>
f.t < 1020
? ({...f, box: null} as TrackedFrame)
: ({...f, box: {...f.box!, y: f.box!.y - 60}} as TrackedFrame),
);
const proof = busyWindowProof(entering, BLOCK, {
control: asControl(moving()),
});
expect(proof.verdict.failures, proof.summary).toEqual([]);
expect(proof.onScreenFromMs).toBeGreaterThanOrEqual(20);
});
it('throws FrameStarvationError for a run the machine starved: its control moved on too few frames, and no frame came for longer than 50 ms', () => {
const run = () =>
busyWindowProof(starvedCast(), BLOCK, {
control: asControl(starvedCast()),
});
expect(run).toThrow(FrameStarvationError);
expect(run).toThrow(
/busyWindowProof: the page drew 3 frames while a 700 ms block held the main thread, and the control moved on 3 of them, where the proof needs 4\. No frame came for 2\d\d\.\d ms/,
);
});
it('fails a component hidden inside an on-pace block as the component, not as starvation', () => {
// Every 60 Hz frame came, and none inside the 90 ms block showed the
// component: the cast's own frames show it was not starved.
const block = {from: 1000, to: 1090};
const hidden = moving().map(f =>
f.t > block.from && f.t < block.to
? ({...f, box: null} as TrackedFrame)
: f,
);
const proof = busyWindowProof(hidden, block, {
control: asControl(moving()),
});
expect(proof.verdict.failures.join('\n')).toMatch(
/moved on 0 of the 3 frames the control moved/,
);
});
it('names a window in which the control itself presented too little to judge as starvation, though every frame came', () => {
const still = asControl(
moving().map(f => ({...f, box: {...f.box!, y: 0}}) as TrackedFrame),
);
const run = () => busyWindowProof(moving(), BLOCK, {control: still});
expect(run).toThrow(FrameStarvationError);
// It names how starved the cast was: here every frame came, 60 Hz.
expect(run).toThrow(
/busyWindowProof: the page drew \d+ frames while a 700 ms block held the main thread, and the control moved on 0 of them, where the proof needs 4\. No frame came for 1[67]\.\d ms: the compositor presented too little in this window to judge/,
);
});
it("names a window under the control's floor as starvation when no frame came for less than 50 ms: a loaded machine's cast, its component on every frame the control moved on", () => {
// A 152 ms block: the cast delivered 8 frames, none for 44 ms. The control
// moved on 3 of them, as on a loaded runner.
const block = {from: 1000, to: 1152};
const times = [1008, 1028, 1048, 1092, 1104, 1116, 1128, 1146];
const moves = new Set([1048, 1092, 1128]);
let y = 0;
const loaded = [
...moving().filter(f => f.t < block.from),
...times.map(t => ({t, box: null}) as TrackedFrame),
...moving().filter(f => f.t > block.to),
].map(f => {
if (f.t < block.from || f.t > block.to || moves.has(f.t)) {
y += 3;
}
return {...f, box: {x: 0, y, width: 10, height: 10}} as TrackedFrame;
});
const run = () =>
busyWindowProof(loaded, block, {control: asControl(loaded)});
expect(run).toThrow(FrameStarvationError);
expect(run).toThrow(
/busyWindowProof: the page drew 8 frames while a 152 ms block held the main thread, and the control moved on 3 of them, where the proof needs 4\. No frame came for 44\.0 ms: the compositor presented too little in this window to judge/,
);
});
it('still fails a main-thread component under the floor: it misses the frames the control moved on, and the cast kept pace', () => {
const block = {from: 1000, to: 1090};
const frozen = moving().map(f =>
f.t > block.from && f.t < block.to + 20
? ({...f, box: {...f.box!, y: 3 * at(block.from)}} as TrackedFrame)
: f,
);
const proof = busyWindowProof(frozen, block, {
control: asControl(moving()),
});
expect(proof.verdict.failures.join('\n')).toMatch(
/moved on 0 of the 3 frames the control moved/,
);
});
it("names a window under the floor as starvation when only the cast's median interval fails: the median is the cast's pace, not the component", () => {
const run = () =>
busyWindowProof(moving(), short(1000), {
control: asControl(moving()),
maxMedianFrameMs: 10,
});
expect(run).toThrow(FrameStarvationError);
expect(run).toThrow(
/the control moved on 3 of them, where the proof needs 4/,
);
});
it("judges a held animation up to its curve's end: after it, the frames show the compositor's fallback to the committed value", () => {
// The curve ends 520 ms into the block. WebKit then presents the value
// the main thread last committed, the box at rest, until the block ends.
const curveEnd = 1520;
const fallback = moving().map(f =>
f.t > curveEnd ? ({...f, box: {...f.box!, y: 0}} as TrackedFrame) : f,
);
const proof = busyWindowProof(fallback, held(curveEnd), {
control: asControl(moving()),
});
expect(proof.verdict.failures, proof.summary).toEqual([]);
expect(proof.monotonic).toBe(true);
expect(proof.judged.to).toBe(curveEnd);
expect(proof.summary).toMatch(/judged to the held curve's end at \+520 ms/);
});
it('still names a starved run as starvation when its held curve also ends inside the block', () => {
// Three frames in the whole block: too few even before the curve's end.
const run = () =>
busyWindowProof(starvedCast(), held(1600), {
control: asControl(starvedCast()),
});
expect(run).toThrow(FrameStarvationError);
});
it("keeps a settle bound's end: the held curve's end does not cut a proof that bounds its settle", () => {
// Arrives at 1530, just after its curve's end at 1520.
const arrives = moving().map(f =>
f.t > 1530
? ({...f, box: {...f.box!, y: 3 * at(1530)}} as TrackedFrame)
: f,
);
const proof = busyWindowProof(arrives, held(1520), {
control: asControl(moving()),
settledWithin: 2,
});
expect(proof.judged.to).toBeGreaterThan(1520);
expect(proof.summary).not.toMatch(/held curve's end/);
});
it('judges the whole block when the held animation keeps its end value: a stop at its curve end still fails', () => {
// A fill that holds the end, or a held tail: the frames after the curve
// still show the animation, at rest.
const curveEnd = 1520;
const stops = moving().map(f =>
f.t > curveEnd
? ({...f, box: {...f.box!, y: 3 * at(curveEnd)}} as TrackedFrame)
: f,
);
const proof = busyWindowProof(stops, held(curveEnd, true), {
control: asControl(moving()),
});
expect(proof.judged.to).toBe(BLOCK.to - 20);
expect(proof.verdict.failures.join('\n')).toMatch(
/longest stall [\d.]+ ms, longer than the control's/,
);
});
it('still fails a held animation that stops advancing before its curve ends', () => {
// Frozen from 300 ms into the block, while its curve runs to 520 ms.
const frozen = moving().map(f =>
f.t > 1300
? ({...f, box: {...f.box!, y: 3 * (at(1300) - 1)}} as TrackedFrame)
: f,
);
const proof = busyWindowProof(frozen, held(1520), {
control: asControl(moving()),
});
const failures = proof.verdict.failures.join('\n');
expect(failures).toMatch(
/moved on \d+ of the \d+ frames the control moved/,
);
expect(failures).toMatch(
/longest stall [\d.]+ ms, longer than the control's/,
);
});
it('throws BusyWindowTooLateError when the held curve ends too soon after the block began for the control to move on enough frames', () => {
const run = (curveEnd: number) => () =>
busyWindowProof(moving(), held(curveEnd), {
control: asControl(moving()),
});
expect(run(1060)).toThrow(BusyWindowTooLateError);
expect(run(1060)).toThrow(
/busyWindowProof: the held animation's curve ended 60 ms after the block began, so the part judged from 20 ms held 2 of the frames it needs, 4 \(\d+ frames presented in the block\): the block started late for the motion\./,
);
// A curve that ended before the judged part began leaves nothing.
expect(run(1010)).toThrow(
/curve ended 10 ms after the block began, so the part judged from 20 ms held 0 of the frames it needs/,
);
let caught: unknown = null;
try {
run(1060)();
} catch (error) {
caught = error;
}
expect(caught).toBeInstanceOf(BusyWindowTooLateError);
expect((caught as BusyWindowTooLateError).numbers).toMatchObject({
curveEndMs: 60,
judgedFromMs: 20,
});
});
});
/**
* `BLOCK` as `blockMainThread` holds it with `during`: the held animation
* started before the block and its curve ends at `curveEnd`. It keeps its end
* value after that only with `holds`.
*/
function held(curveEnd: number, holds = false) {
return {...BLOCK, spanMs: 700, animation: {from: 800, to: curveEnd, holds}};
}
/**
* `moving()` with three frames in `BLOCK`, about 200 ms apart, as a cast the
* machine starved delivers.
*/
function starvedCast(): TrackedFrame[] {
const kept = [at(1150), at(1350), at(1550)];
return moving().filter(
(f, i) => f.t < BLOCK.from || f.t > BLOCK.to || kept.includes(i),
);
}
/** The numbers a `FrameStarvationError` from `run` names. */
function starvationNumbers(run: () => unknown) {
try {
run();
} catch (error) {
if (error instanceof FrameStarvationError) {
return error.numbers;
}
throw error;
}
throw new Error('no FrameStarvationError');
}
/** A 90 ms block from `from`: its judged part holds three 60 Hz frames. */
const short = (from: number) => ({from, to: from + 90});
describe('pooledBusyProof', () => {
it('judges a block too short for one run over pooled runs: one run cannot decide, three runs of a component that moves with the control pass', () => {
const control = asControl(moving());
const single = () => busyWindowProof(moving(), short(1000), {control});
expect(single).toThrow(FrameStarvationError);
expect(single).toThrow(
/the control moved on 3 of them, where the proof needs 4/,
);
const runs = [1000, 1300, 1600].map(from => ({
tracked: moving(),
control,
window: short(from),
}));
const pooled = pooledBusyProof(runs);
expect(pooled.verdict.failures, pooled.summary).toEqual([]);
expect(pooled.control).toEqual({moved: 9, movedWith: 9});
expect(pooled.runs).toHaveLength(3);
expect(pooled.summary).toMatch(
/^3 runs pooled: moved on 9 of the control's 9 frames; run 1: /,
);
});
it('leaves out a run whose block began after its motion had settled, and names it', () => {
const control = asControl(moving());
// Settled 50 ms before the run's block: nothing in it is left to judge.
const settled = moving().map(f =>
f.t < 950
? f
: ({...f, box: {...f.box!, y: 3 * at(950)}} as TrackedFrame),
);
const pooled = pooledBusyProof(
[
{tracked: settled, control, window: short(1000)},
{tracked: moving(), control, window: short(1300)},
{tracked: moving(), control, window: short(1600)},
],
{settledWithin: 2},
);
expect(pooled.verdict.failures, pooled.summary).toEqual([]);
expect(pooled.judged).toEqual([false, true, true]);
expect(pooled.runs[0]).toBeNull();
expect(pooled.late[0]).toBeInstanceOf(BusyWindowTooLateError);
expect(pooled.late.slice(1)).toEqual([null, null]);
// Only the judged runs' frames count toward the pool's floors.
expect(pooled.control).toEqual({moved: 6, movedWith: 6});
expect(pooled.summary).toMatch(
/^3 runs pooled, 2 judged: .*; run 1: too late to judge: busyWindowProof: /,
);
});
it('fails by name a pool left with fewer judged runs than its minimum, however many began too late', () => {
const control = asControl(moving());
const settled = moving().map(f =>
f.t < 950
? f
: ({...f, box: {...f.box!, y: 3 * at(950)}} as TrackedFrame),
);
// One long run passes every floor alone, beside two that began too late.
const pooled = pooledBusyProof(
[
{tracked: settled, control, window: short(1000)},
{tracked: settled, control, window: short(1000)},
{tracked: moving(), control, window: {from: 1100, to: 1700}},
],
{settledWithin: 2},
);
expect(pooled.verdict.pass).toBe(false);
expect(pooled.verdict.failures).toEqual([
'1 of 3 runs judged, under 2: 2 began too late for their motion, and the compositor presented too little in any other to judge',
]);
expect(pooled.summary).toMatch(/run 1: too late to judge/);
expect(pooled.summary).toMatch(/run 2: too late to judge/);
});
it('still fails a component that is frozen in every run while the control moves', () => {
const frozen = moving().map(
f => ({...f, box: {...f.box!, y: 0}}) as TrackedFrame,
);
const pooled = pooledBusyProof(
[1000, 1300, 1600].map(from => ({
tracked: frozen,
control: asControl(moving()),
window: short(from),
})),
);
expect(pooled.verdict.pass).toBe(false);
expect(pooled.verdict.failures.join('\n')).toMatch(
/moved on 0 of the 9 frames the control moved over 3 runs/,
);
expect(pooled.verdict.failures.join('\n')).toMatch(
/run 1: longest stall .* longer than the control's/,
);
});
it("judges each run's longest stall against that run's control, never pooled", () => {
// Two frames in a row present no new position, inside run 2 only.
const k = at(1320);
const stalled = moving().map((f, i) =>
i === k || i === k + 1
? ({...f, box: {...f.box!, y: 3 * (k - 1)}} as TrackedFrame)
: f,
);
const pooled = pooledBusyProof(
[1000, 1300, 1600].map(from => ({
tracked: stalled,
control: asControl(moving()),
window: short(from),
})),
);
const failures = pooled.verdict.failures.join('\n');
expect(failures).toMatch(
/run 2: longest stall .* longer than the control's/,
);
expect(failures).not.toMatch(/run [13]: longest stall/);
});
it('fails a pool in which the component misses a single frame the control moved', () => {
const pooled = pooledBusyProof(
[1000, 1300, 1600].map(from => ({
tracked: repeating([at(1320)]),
control: asControl(moving()),
window: short(from),
})),
);
expect(pooled.verdict.failures.join('\n')).toMatch(
/moved on \d+ of the \d+ frames the control moved over 3 runs/,
);
expect(pooled.control.moved - pooled.control.movedWith).toBe(1);
});
it("counts a pooled run's unchanged frames under one cast step a frame as moved, as one window does", () => {
const k = at(1000);
const tail = moving().map((f, i) =>
i < k
? f
: ({
...f,
box: {...f.box!, y: 3 * k + Math.floor((i - k) / 2)},
} as TrackedFrame),
);
const pooled = pooledBusyProof(
[1000, 1300, 1600].map(from => ({
tracked: tail,
control: asControl(moving()),
window: short(from),
})),
);
expect(pooled.verdict.failures, pooled.summary).toEqual([]);
});
it('still fails a pooled frame-counted loop that the cast shows moving early in each judged part', () => {
// Six 70 ms blocks; the cast shows the loop's last frames up to 35 ms into
// each, then it stands still to the block's end and goes on one step a
// frame: a 1 px loop's steps are one cast step, and a 2 px loop's read
// as one when its changes are all 2 px.
const windows = [1000, 1150, 1300, 1450, 1600, 1750].map(from => ({
from,
to: from + 70,
}));
for (const step of [1, 2]) {
const pooled = pooledBusyProof(
windows.map(window => ({
tracked: frameCounted(windows, 35, step),
control: asControl(moving()),
window,
})),
);
expect(pooled.verdict.failures.join('\n'), `${step} px`).toMatch(
/moved on \d+ of the \d+ frames the control moved over 6 runs/,
);
}
});
it('names a pool whose control presented too little in every run as starvation', () => {
const still = asControl(
moving().map(f => ({...f, box: {...f.box!, y: 0}}) as TrackedFrame),
);
const run = () =>
pooledBusyProof(
[1000, 1300].map(from => ({
tracked: moving(),
control: still,
window: short(from),
})),
);
expect(run).toThrow(FrameStarvationError);
expect(run).toThrow(
/pooledBusyProof: .*0 of 2 runs judged, under 1, and the control moved on 0 frames over them: the compositor presented too little in the others to judge/,
);
});
/** `frames` held at the position they had at `from`, from `from` to `to`. */
const held = (frames: TrackedFrame[], from: number, to: number) =>
frames.map(f =>
f.t >= from && f.t <= to
? ({...f, box: {...f.box!, y: 3 * at(from)}} as TrackedFrame)
: f,
);
it('names a run whose control presented nothing as too little to judge and leaves it out: the other runs decide', () => {
// The control stands still through run 2's block only, as if the machine
// starved it there.
const pooled = pooledBusyProof(
[1000, 1300, 1600].map(from => ({
tracked: moving(),
control: asControl(held(moving(), 1300, 1390)),
window: short(from),
})),
);
expect(pooled.verdict.failures, pooled.summary).toEqual([]);
expect(pooled.judged).toEqual([true, false, true]);
expect(pooled.control).toEqual({moved: 6, movedWith: 6});
expect(pooled.summary).toMatch(
/^3 runs pooled, 2 judged: .*; run 2: too little to judge, the control moved on 0 frames, under 1: /,
);
});
it('names a pool in which every run but one was too little to judge as starvation, even when that run holds enough frames', () => {
const windows = [1000, 1300, 1600].map(from => ({from, to: from + 200}));
const starved = held(held(moving(), 1300, 1500), 1600, 1800);
const pool = () =>
pooledBusyProof(
windows.map(window => ({
tracked: moving(),
control: asControl(starved),
window,
})),
);
expect(pool).toThrow(FrameStarvationError);
expect(pool).toThrow(
/pooledBusyProof: the page drew \d+ frames while 3 blocks held the main thread, and 1 of them had enough control frames to judge, where the proof needs 2\. .*1 of 3 runs judged, under 2, and the control moved on \d+ frames over them: the compositor presented too little in the others to judge/,
);
});
it('names a pool of four runs with one judged as starvation: its component moved on every frame its control moved on', () => {
const windows = [1000, 1250, 1500, 1750].map(short);
const control = asControl(
held(held(held(moving(), 1250, 1340), 1500, 1590), 1750, 1840),
);
const pool = () =>
pooledBusyProof(
windows.map(window => ({tracked: moving(), control, window})),
);
expect(pool).toThrow(FrameStarvationError);
expect(pool).toThrow(/1 of 4 runs judged, under 2/);
// Short of judged runs, the error counts every block's frames.
const numbers = starvationNumbers(pool);
expect(numbers.frames).toBe(20);
expect(numbers.longestGapMs).toBeCloseTo(FRAME, 1);
});
it('names the longest gap of every block in a pool short of judged runs, where the unjudged blocks drew no frame', () => {
const windows = [1000, 1250, 1500, 1750].map(short);
const control = asControl(
held(held(held(moving(), 1250, 1340), 1500, 1590), 1750, 1840),
);
const tracked = moving().filter(
f => !windows.slice(1).some(w => f.t > w.from && f.t < w.to),
);
const numbers = starvationNumbers(() =>
pooledBusyProof(windows.map(window => ({tracked, control, window}))),
);
expect(numbers.frames).toBe(5);
expect(numbers.longestGapMs).toBeCloseTo(90, 5);
});
it("names a pool short of judged runs as starvation when only the runs' median intervals fail", () => {
const windows = [1000, 1250, 1500, 1750].map(short);
const control = asControl(
held(held(held(moving(), 1250, 1340), 1500, 1590), 1750, 1840),
);
const pool = () =>
pooledBusyProof(
windows.map(window => ({tracked: moving(), control, window})),
{maxMedianFrameMs: 10},
);
expect(pool).toThrow(FrameStarvationError);
expect(pool).toThrow(/1 of 4 runs judged, under 2/);
});
it('still fails a pool short of judged runs when its judged run shows a component red', () => {
const windows = [1000, 1250, 1500, 1750].map(short);
const control = asControl(
held(held(held(moving(), 1250, 1340), 1500, 1590), 1750, 1840),
);
const pooled = pooledBusyProof(
windows.map(window => ({
tracked: held(moving(), 1000, 1090),
control,
window,
})),
);
expect(pooled.judged).toEqual([true, false, false, false]);
expect(pooled.verdict.failures.join('\n'), pooled.summary).toMatch(
/run 1: moved on 0 of the 3 frames its control moved/,
);
});
it('judges a run in which the component froze while its control moved: it is never left out, and it fails on its own', () => {
const pooled = pooledBusyProof(
[1000, 1300, 1600].map(from => ({
tracked: held(moving(), 1300, 1390),
control: asControl(moving()),
window: short(from),
})),
);
expect(pooled.judged).toEqual([true, true, true]);
const failures = pooled.verdict.failures.join('\n');
expect(failures).toMatch(
/moved on 6 of the 9 frames the control moved over 3 runs/,
);
expect(failures).toMatch(
/run 2: moved on 0 of the 3 frames its control moved/,
);
expect(failures).not.toMatch(/run [13]: moved on/);
expect(failures).toMatch(
/run 2: longest stall .* longer than the control's/,
);
});
it('throws when it needs more judged runs than it has, or none', () => {
expect(() =>
pooledBusyProof(
[{tracked: moving(), control: asControl(moving()), window: BLOCK}],
{minJudgedRuns: 2},
),
).toThrow(/minJudgedRuns 2 is not between 1 and the 1 runs/);
expect(() =>
pooledBusyProof(
[{tracked: moving(), control: asControl(moving()), window: BLOCK}],
{minJudgedRuns: 0},
),
).toThrow(/minJudgedRuns 0 is not between 1 and the 1 runs/);
});
it('judges one long run as busyWindowProof judges it against the control', () => {
const control = asControl(moving());
const pooled = pooledBusyProof([
{tracked: moving(), control, window: BLOCK},
]);
const single = busyWindowProof(moving(), BLOCK, {control});
expect(pooled.verdict).toEqual(single.verdict);
expect(pooled.control).toEqual({
moved: single.control?.moved,
movedWith: single.control?.movedWith,
});
});
it('reads a run the machine starved without throwing, and judges it with the others', () => {
const run = (tracked: TrackedFrame[]) => ({
tracked,
control: asControl(tracked),
window: BLOCK,
});
const pooled = pooledBusyProof([
run(moving()),
run(moving()),
run(starvedCast()),
]);
expect(pooled.judged).toEqual([true, true, true]);
expect(pooled.verdict.failures, pooled.summary).toEqual([]);
});
it('throws on no runs', () => {
expect(() => pooledBusyProof([])).toThrow(/no runs/);
});
});
describe('a hold that starts before the block', () => {
// A sheet's release in WebKit: moving until 120 ms before the block, held
// (the just-started animation not presented yet) until 100 ms into it,
// then moving on every frame.
const holdFrom = BLOCK.from - 120;
const holdTo = BLOCK.from + 100;
const sheet = ({freezeAfterFirst = false} = {}) => {
let y = 0;
let changed = false;
return moving().map(f => {
if (f.t < holdFrom) {
y += 3;
} else if (f.t >= holdTo && (!freezeAfterFirst || !changed)) {
y += 3;
changed = true;
}
return {...f, box: {...f.box!, y}} as TrackedFrame;
});
};
const control = asControl(moving());
// The position the page set last, at the release: where the sheet holds.
const released = sheet()
.filter(f => f.t < holdFrom)
.at(-1)!.box!.y;
it('is judged from its first presented change inside the block when it holds the position the page set', () => {
const proof = busyWindowProof(sheet(), BLOCK, {
axis: 'y',
control,
setBeforeBlock: released,
});
expect(proof.verdict.failures, proof.summary).toEqual([]);
expect(proof.onScreenFromMs).toBeGreaterThanOrEqual(100);
});
it('is not excused without the position the page set', () => {
const proof = busyWindowProof(sheet(), BLOCK, {axis: 'y', control});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it('is not excused when it holds a position the page did not set', () => {
const proof = busyWindowProof(sheet(), BLOCK, {
axis: 'y',
control,
setBeforeBlock: released + 6,
});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it('is excused on a 2 px cast that reads the held position up to a step off', () => {
// WebKit's cast reads positions on a 2 px grid: a hold at a half pixel
// reads up to 1.5 px off.
const grid = sheet().map(f => ({...f, step: {x: 2, y: 2}}));
const proof = busyWindowProof(grid, BLOCK, {
axis: 'y',
control,
setBeforeBlock: released + 1.5,
});
expect(proof.verdict.failures, proof.summary).toEqual([]);
expect(proof.onScreenFromMs).toBeGreaterThanOrEqual(100);
});
it('matches the held position within a pixel on a cast that carries no step', () => {
const proof = busyWindowProof(sheet(), BLOCK, {
axis: 'y',
control,
setBeforeBlock: released + 1.5,
});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it('is not excused when the position it holds shows on one frame only', () => {
// Moving up to the last frame before the block, then not found on any
// frame until 150 ms in, then moving on. The position the page set
// shows on one frame only, which is no hold. So the window is judged
// from the judged part's start.
let y = 0;
const frames = moving().map(f => {
y += 3;
return (
f.t >= BLOCK.from && f.t < BLOCK.from + 150
? {...f, box: null}
: {...f, box: {...f.box!, y}}
) as TrackedFrame;
});
const last = frames.filter(f => f.t < BLOCK.from).at(-1)!.box!.y;
const proof = busyWindowProof(frames, BLOCK, {
axis: 'y',
control,
setBeforeBlock: last,
});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it('fails an animation that was moving, freezes from just before the block for 50 ms, then moves on', () => {
// Moving every frame up to the block, frozen from the frame before it
// until 50 ms in, then moving on every frame. This is a compositor
// animation stalled at the block's start, at none of the page's positions.
let y = 0;
const frames = moving().map(f => {
if (f.t < BLOCK.from - 5 || f.t >= BLOCK.from + 50) {
y += 3;
}
return {...f, box: {...f.box!, y}} as TrackedFrame;
});
const proof = busyWindowProof(frames, BLOCK, {axis: 'y', control});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it('still fails when the element changes once inside the block and then freezes', () => {
const proof = busyWindowProof(sheet({freezeAfterFirst: true}), BLOCK, {
axis: 'y',
control,
setBeforeBlock: released,
});
expect(proof.verdict.pass, proof.summary).toBe(false);
});
it('is not excused when it starts inside the block', () => {
let y = 0;
const frames = moving().map(f => {
if (f.t < BLOCK.from + 50 || f.t >= BLOCK.from + 250) {
y += 3;
}
return {...f, box: {...f.box!, y}} as TrackedFrame;
});
// Even at the last position before the judged part, as if the page had
// set it.
const proof = busyWindowProof(frames, BLOCK, {
axis: 'y',
control,
setBeforeBlock: frames.filter(f => f.t < BLOCK.from + 20).at(-1)!.box!.y,
});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it('is not excused when its first held frame is the one at the block start', () => {
// Moving up to the frame presented as the block starts, then held on it
// and the frames after until 250 ms in. The hold has two frames before
// the judged part, at the position the page set, but starts inside the
// block.
let y = 0;
const frames = moving().map(f => {
if (f.t <= BLOCK.from || f.t >= BLOCK.from + 250) {
y += 3;
}
return {...f, box: {...f.box!, y}} as TrackedFrame;
});
const held = frames.find(f => f.t >= BLOCK.from)!.box!.y;
const proof = busyWindowProof(frames, BLOCK, {
axis: 'y',
control,
setBeforeBlock: held,
});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
// A window that caught the animation (`blockMainThread`'s `during`) knows
// its start. The position on the cast's last frame before that start then
// stands for the position the page set.
const caught = {
...BLOCK,
animation: {from: holdFrom, to: BLOCK.to + 500, holds: true},
};
it('takes the position from the last frame before the caught animation starts when no position is given', () => {
const proof = busyWindowProof(sheet(), caught, {axis: 'y', control});
const named = busyWindowProof(sheet(), caught, {
axis: 'y',
control,
setBeforeBlock: released,
});
expect(proof.verdict.failures, proof.summary).toEqual([]);
expect(proof.onScreenFromMs).toBeGreaterThanOrEqual(100);
expect(proof.summary).toBe(named.summary);
});
it("keeps the position the page set over the caught animation's start", () => {
const proof = busyWindowProof(sheet(), caught, {
axis: 'y',
control,
setBeforeBlock: released + 6,
});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it('still fails a main-thread animation held at its start until after the block', () => {
let y = 0;
const frames = moving().map(f => {
if (f.t < holdFrom || f.t >= BLOCK.to + 50) {
y += 3;
}
return {...f, box: {...f.box!, y}} as TrackedFrame;
});
const proof = busyWindowProof(frames, caught, {axis: 'y', control});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it('does not excuse a hold at a position the animation moved to after its start', () => {
// Moving for 60 ms after the caught animation's start, then held there
// until 100 ms into the block, then moving on every frame.
let y = 0;
const frames = moving().map(f => {
if (f.t < holdFrom + 60 || f.t >= holdTo) {
y += 3;
}
return {...f, box: {...f.box!, y}} as TrackedFrame;
});
const proof = busyWindowProof(frames, caught, {axis: 'y', control});
expect(proof.verdict.pass, proof.summary).toBe(false);
expect(proof.onScreenFromMs).toBeNull();
});
it("judges a recorded slider coast the same with the caught animation's start as with the position the page set", () => {
// Recorded in Chromium on a loaded runner: SliderTouch's coast through a
// 400 ms block, with the busy control. Each row is [ms from the block's
// start, thumb x, control x] on one cast frame. The thumb holds at its
// release position, 163 px, from before the coast's start. Here the hold
// is extended through the second judged frame, as a late hand-off can be.
const recorded: ReadonlyArray<readonly [number, number, number]> = [
[-222.1, 156, 130],
[-188.6, 156, 150],
[-179, 156, 160],
[-153.7, 163, 180],
[-144.6, 163, 190],
[-122.4, 163, 200],
[-86.2, 163, 210],
[-85.6, 163, 220],
[-45.2, 163, 240],
[-29.8, 163, 230],
[-24.1, 163, 220],
[15.2, 206, 190],
[42.1, 214, 180],
[49.2, 220, 170],
[66.8, 225, 160],
[93.7, 229, 150],
[135.3, 232, 140],
[139, 236, 130],
[171.4, 241, 100],
[186.5, 243, 90],
[210.6, 244, 80],
[231.8, 245, 60],
[259.7, 246, 50],
[279.9, 246, 40],
[287.7, 247, 30],
[318.4, 247, 20],
];
const from = 10_000;
const coastStart = from - 74.7;
const holdUntil = from + 49.2;
const thumb = recorded.map(
([t, x]) =>
({
t: from + t,
box: {
x: from + t > coastStart && from + t <= holdUntil ? 163 : x,
y: 0,
width: 28,
height: 28,
},
pixels: 400,
step: {x: 1, y: 1},
}) as TrackedFrame,
);
const slider = recorded.map(
([t, , x]) =>
({
t: from + t,
box: {x, y: 0, width: 12, height: 12},
pixels: 100,
}) as TrackedFrame,
);
const window = {
from,
to: from + 400,
animation: {from: coastStart, to: coastStart + 564.3, holds: true},
};
const options = {
axis: 'x',
settledWithinSteps: 2,
control: slider,
} as const;
const byStart = busyWindowProof(thumb, window, options);
const named = busyWindowProof(thumb, window, {
...options,
setBeforeBlock: 163,
});
const plain = busyWindowProof(thumb, {from, to: from + 400}, options);
expect(byStart.verdict.failures, byStart.summary).toEqual([]);
expect(byStart.summary).toBe(named.summary);
expect(plain.verdict.pass, plain.summary).toBe(false);
});
});