Skip to content

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

TypeScript

test(interaction-harness): a hold the page arms itself takes a short animation on its first frame (#9230)

Christopher Chedeauad38e6d2f4e7
diff --git a/internal/interaction-harness/README.md b/internal/interaction-harness/README.md
index a739cd0d67..4ab9aaa260 100644
--- a/internal/interaction-harness/README.md
+++ b/internal/interaction-harness/README.md
@@ -53,7 +53,7 @@ committed: a pull request links or attaches it.
| `busy.ts` | `blockMainThread(page, ms)` and `busyWindowProof(tracked, window)`: frames presented, frames that moved, longest stall, a verdict; `presented` adds the compositor's own frames. |
| `webInput.ts` | `webInputDriver(page)`: `wheel({x, y, dx, dy, ctrl})` and `pen(points)` as real engine input, for proofs across pointers (`spec:AST-100` FR4); `wheel` resolves once the page has the step; read back through the input log. |
| `trace.ts` | `traceRendering(page, body)`: main-thread counts of UpdateLayoutTree / Layout / PrePaint / Paint / Layerize / UpdateLayer / ScrollLayer / HitTest, `countBetween`, long tasks; `installLongTaskLog` / `readLongTasks`; `startCompositorTrace`: when the compositor presents. |
-| `curves.ts` | `holdAnimations`, `seekAnimations`, `sampleCurve` (presented transform / opacity at any t), `waitForAnimation`, `watchAnimations`, `waitForRest`, `releaseAnimations`, `releaseAnimationLog` (frees what the recorder kept, before a heap or listener count). |
+| `curves.ts` | `holdAnimations`, `armHold`, `seekAnimations`, `sampleCurve` (presented transform / opacity at any t), `waitForAnimation`, `watchAnimations`, `waitForRest`, `releaseAnimations`, `releaseAnimationLog` (frees what the recorder kept, before a heap or listener count). |
| `math.ts` | Oracles independent of the code under test: `cubicBezier`, `timingFunction`, `springStep` (SwiftUI response / dampingFraction, initial velocity), `projectDecay`, `rubberBand`, `parseTransform`, `compareCurve`, `timeline`. |
| `storyboard.ts` | `animationStoryboard` (seek to t = 0, 16.7, 33.3 … ms), `touchStoryboard` (a frame per scripted event): PNG contact sheet + JSON trace. |
| `output.ts` | `evidenceDir`, `writeEvidence`: where evidence goes and how it is attached to the report. |
@@ -76,7 +76,15 @@ animations are Web Animations too), seek to a time, read `getComputedStyle`:
the presented value at that exact time, independent of frame timing. Finished
animations, ones the page paused and ones on a scroll or view timeline are left
alone; held animations keep their offsets from the first hold's earliest start, and release
-resumes only them. Compare it with an
+resumes only them. A hold sent from the test reaches the page after a round
+trip, and on a loaded runner a short animation can end first: for one that an
+action starts, `await armHold(page, scope)` before the action arms the page
+itself: it looks on every frame and every 4 ms between frames (WebKit can go
+about 70 ms without a frame while it first composites a layer),
+holds everything running under the scope as soon as one of them runs (or
+`count` of them, for parts that start apart; with `newOnly`, only what starts
+after the arm, for a turn that starts mid-motion), and `held()` after the
+action returns that held set. Compare it with an
oracle from `math.ts` through `compareCurve`; a tolerance states the error
budget (for a spring baked into `linear()` stops of `h` ms, chords err by up to
`h² / 8 · |x''|`). A seek past an animation's end lands half a millisecond
diff --git a/internal/interaction-harness/src/curves.ts b/internal/interaction-harness/src/curves.ts
index 8bf2444554..63aaec1b34 100644
--- a/internal/interaction-harness/src/curves.ts
+++ b/internal/interaction-harness/src/curves.ts
@@ -6,6 +6,7 @@
* the Web Animations API in the page (CSS transitions and CSS animations are
* Web Animations too)
* @output `holdAnimations` (pause every running animation and describe it),
+ * `armHold` (the page holds what an action starts, as soon as it runs),
* `seekAnimations` (move them to t ms from the held origin, each keeping
* its offset), `sampleCurve` (the presented
* transform/opacity at each t, with the individual `translate`, `rotate` and
@@ -360,13 +361,21 @@ async function installRecorder(page: Page): Promise<void> {
* keyframes end in a run of identical values (an end value held so that a
* later interruption can read it) ends where that run starts, when it plays
* forward under a linear or cubic-bézier effect easing (the time the run
- * starts is solved from the curve); any other ends at its end time.
+ * starts is solved from the curve); any other ends at its end time. The same
+ * evaluate installs `window.__harnessHold(root)`, which holds every running
+ * animation on the document timeline (only those whose target is `root` or
+ * inside it, when `root` is set) and returns what it held (see
+ * `holdAnimations`), so `holdAnimations` and `armHold` hold the same way.
*/
async function installCurveEnd(page: Page): Promise<void> {
await installRecorder(page);
await page.evaluate(() => {
const w = window as unknown as {
__harnessCurveEnd?: (animation: Animation) => number;
+ __harnessHold?: (
+ root: Element | null,
+ skip?: ReadonlySet<Animation>,
+ ) => unknown[];
};
if (w.__harnessCurveEnd) {
return;
@@ -472,6 +481,108 @@ async function installCurveEnd(page: Page): Promise<void> {
}
return delay + bezier((lo + hi) / 2, x1, x2) * active;
};
+ // The hold, installed with the curve end it reads: one round trip
+ // installs both, so a hold sent from the test costs no extra one.
+ w.__harnessHold = (root: Element | null, skip?: ReadonlySet<Animation>) => {
+ const curveEnd = (
+ window as unknown as {__harnessCurveEnd: (a: Animation) => number}
+ ).__harnessCurveEnd;
+ const describe = (node: Element | null) =>
+ node == null
+ ? null
+ : node.tagName.toLowerCase() +
+ (node.id ? `#${node.id}` : '') +
+ (node.classList.length
+ ? `.${[...node.classList].slice(0, 2).join('.')}`
+ : '');
+ const now = Number(document.timeline.currentTime ?? performance.now());
+ const all = document.getAnimations().filter(animation => {
+ const target =
+ (animation.effect as KeyframeEffect | null)?.target ?? null;
+ return (
+ animation.playState === 'running' &&
+ animation.timeline instanceof DocumentTimeline &&
+ !(skip?.has(animation) ?? false) &&
+ (root == null ||
+ (target != null && (root === target || root.contains(target))))
+ );
+ });
+ // Seeking and sampling run a curve forward: an animation running
+ // backward (`reverse()`, a negative playback rate) cannot be held and
+ // read, so it is refused rather than misread.
+ const backward = all.find(animation => animation.playbackRate < 0);
+ if (backward != null) {
+ throw new Error(
+ `holdAnimations: ${describe((backward.effect as KeyframeEffect | null)?.target ?? null) ?? 'an animation'} runs backward (reverse() or a negative playback rate); hold and sample a forward run instead`,
+ );
+ }
+ // Each animation's start on the document timeline, read before the pause
+ // clears it. A pending play has no start time yet: it starts now, as far
+ // back as its current time reaches through its playback rate (at rate 2,
+ // a run covers its curve in half the timeline), as seeking reads it.
+ const starts = all.map(animation =>
+ animation.startTime != null
+ ? Number(animation.startTime)
+ : now -
+ Number(animation.currentTime ?? 0) / (animation.playbackRate || 1),
+ );
+ const held = all.map(animation => {
+ animation.pause();
+ // `pause()` only schedules the pause: the engine takes the hold time at
+ // its next frame, a frame past where this read it. Setting the current
+ // time completes a pending pause at once, here.
+ // eslint-disable-next-line no-self-assign
+ animation.currentTime = animation.currentTime;
+ return animation;
+ });
+ // A later hold adds to the held set: what an earlier one held stays held
+ // (it is paused, so it is not taken again above) until released.
+ const w = window as unknown as {
+ __harnessHeld?: Animation[];
+ __harnessHeldStarts?: number[];
+ __harnessHeldOrigin?: number;
+ };
+ w.__harnessHeld = [...(w.__harnessHeld ?? []), ...held];
+ w.__harnessHeldStarts = [...(w.__harnessHeldStarts ?? []), ...starts];
+ // Times count from the origin the first hold set (its earliest start)
+ // until the release: a later hold, even of an animation that started
+ // earlier (its offset is then negative), and dropping one never move it,
+ // so every offsetMs already returned stays true.
+ const origin = Number.isFinite(w.__harnessHeldOrigin ?? Number.NaN)
+ ? (w.__harnessHeldOrigin as number)
+ : Math.min(...starts);
+ w.__harnessHeldOrigin = origin;
+ const offsets = starts.map(start => start - origin);
+ return held.map((animation, index) => {
+ const effect = animation.effect as KeyframeEffect | null;
+ const timing = effect?.getComputedTiming();
+ const cssName =
+ 'transitionProperty' in animation
+ ? (animation as unknown as {transitionProperty: string})
+ .transitionProperty
+ : 'animationName' in animation
+ ? (animation as unknown as {animationName: string}).animationName
+ : null;
+ return {
+ index,
+ kind: animation.constructor.name,
+ name: cssName,
+ target: describe((effect?.target as Element | null) ?? null),
+ durationMs: Number(timing?.duration ?? 0),
+ delayMs: Number(timing?.delay ?? 0),
+ curveEndMs: curveEnd(animation),
+ easing: String(effect?.getTiming().easing ?? 'linear'),
+ keyframes: (effect?.getKeyframes() ?? []).map(
+ (k): Record<string, unknown> => ({...k}),
+ ),
+ heldAtMs:
+ animation.currentTime == null
+ ? null
+ : Number(animation.currentTime),
+ offsetMs: offsets[index],
+ };
+ });
+ };
});
}
@@ -522,103 +633,186 @@ export async function holdAnimations(
): Promise<HeldAnimation[]> {
const scopeHandle = scope ? await scope.elementHandle() : null;
await installCurveEnd(page);
- return page.evaluate(root => {
- const curveEnd = (
- window as unknown as {__harnessCurveEnd: (a: Animation) => number}
- ).__harnessCurveEnd;
- const describe = (node: Element | null) =>
- node == null
- ? null
- : node.tagName.toLowerCase() +
- (node.id ? `#${node.id}` : '') +
- (node.classList.length
- ? `.${[...node.classList].slice(0, 2).join('.')}`
- : '');
- const now = Number(document.timeline.currentTime ?? performance.now());
- const all = document.getAnimations().filter(animation => {
- const target =
- (animation.effect as KeyframeEffect | null)?.target ?? null;
- return (
- animation.playState === 'running' &&
- animation.timeline instanceof DocumentTimeline &&
- (root == null ||
- (target != null && (root === target || root.contains(target))))
- );
- });
- // Seeking and sampling run a curve forward: an animation running
- // backward (`reverse()`, a negative playback rate) cannot be held and
- // read, so it is refused rather than misread.
- const backward = all.find(animation => animation.playbackRate < 0);
- if (backward != null) {
- throw new Error(
- `holdAnimations: ${describe((backward.effect as KeyframeEffect | null)?.target ?? null) ?? 'an animation'} runs backward (reverse() or a negative playback rate); hold and sample a forward run instead`,
- );
- }
- // Each animation's start on the document timeline, read before the pause
- // clears it. A pending play has no start time yet: it starts now, as far
- // back as its current time reaches through its playback rate (at rate 2,
- // a run covers its curve in half the timeline), as seeking reads it.
- const starts = all.map(animation =>
- animation.startTime != null
- ? Number(animation.startTime)
- : now -
- Number(animation.currentTime ?? 0) / (animation.playbackRate || 1),
- );
- const held = all.map(animation => {
- animation.pause();
- // `pause()` only schedules the pause: the engine takes the hold time at
- // its next frame, a frame past where this read it. Setting the current
- // time completes a pending pause at once, here.
- // eslint-disable-next-line no-self-assign
- animation.currentTime = animation.currentTime;
- return animation;
- });
- // A later hold adds to the held set: what an earlier one held stays held
- // (it is paused, so it is not taken again above) until released.
- const w = window as unknown as {
- __harnessHeld?: Animation[];
- __harnessHeldStarts?: number[];
- __harnessHeldOrigin?: number;
- };
- w.__harnessHeld = [...(w.__harnessHeld ?? []), ...held];
- w.__harnessHeldStarts = [...(w.__harnessHeldStarts ?? []), ...starts];
- // Times count from the origin the first hold set (its earliest start)
- // until the release: a later hold, even of an animation that started
- // earlier (its offset is then negative), and dropping one never move it,
- // so every offsetMs already returned stays true.
- const origin = Number.isFinite(w.__harnessHeldOrigin ?? Number.NaN)
- ? (w.__harnessHeldOrigin as number)
- : Math.min(...starts);
- w.__harnessHeldOrigin = origin;
- const offsets = starts.map(start => start - origin);
- return held.map((animation, index) => {
- const effect = animation.effect as KeyframeEffect | null;
- const timing = effect?.getComputedTiming();
- const cssName =
- 'transitionProperty' in animation
- ? (animation as unknown as {transitionProperty: string})
- .transitionProperty
- : 'animationName' in animation
- ? (animation as unknown as {animationName: string}).animationName
- : null;
- return {
- index,
- kind: animation.constructor.name,
- name: cssName,
- target: describe((effect?.target as Element | null) ?? null),
- durationMs: Number(timing?.duration ?? 0),
- delayMs: Number(timing?.delay ?? 0),
- curveEndMs: curveEnd(animation),
- easing: String(effect?.getTiming().easing ?? 'linear'),
- keyframes: (effect?.getKeyframes() ?? []).map(
- (k): Record<string, unknown> => ({...k}),
- ),
- heldAtMs:
- animation.currentTime == null ? null : Number(animation.currentTime),
- offsetMs: offsets[index],
+ return page.evaluate(
+ root =>
+ (
+ window as unknown as {
+ __harnessHold: (root: Element | null) => HeldAnimation[];
+ }
+ ).__harnessHold(root),
+ scopeHandle,
+ );
+}
+
+/** An armed hold (`armHold`): the page holds on its own; read what it held. */
+export interface ArmedHold {
+ /** What the page held, once an animation under the scope ran. */
+ held(): Promise<HeldAnimation[]>;
+}
+
+let armedHolds = 0;
+
+/**
+ * Arms the page to hold every running animation under `scope` (the whole
+ * document without one) itself, as soon as one of them runs (and has run
+ * `minProgressMs`, 0 by default; or as soon as `count` of them run, for parts
+ * that start apart; with `newOnly`, only animations that start after the arm
+ * count and are held, so a turn that starts mid-motion is held while the
+ * motion goes on), and resolves once it is armed: await it
+ * before the action that starts the animation, then read `held()` after. A
+ * hold sent from the test once the animation runs (`holdAnimations`) reaches
+ * the page later the busier the machine is, and a short animation can end
+ * first; the page itself looks on every frame and every 4 ms between them and
+ * holds it as soon as it runs, which a starved page only delays, as it delays
+ * the animation's own start. What it
+ * holds joins the held set as `holdAnimations`' does, so `seekAnimations`,
+ * `sampleCurve` and `releaseAnimations` read it the same way, and a later
+ * hold adds to it. Arm it while nothing under `scope` runs, or pass
+ * `newOnly`: otherwise an animation already running counts. The busy-window control's own animation
+ * (`startBusyControl`) never counts, but an unscoped hold, which takes every
+ * running animation, pauses it too: scope the hold in a busy-window proof.
+ * `held()` rejects when nothing under the scope runs within `timeout` ms of
+ * arming.
+ *
+ * @example
+ * ```
+ * const hold = await armHold(page, row);
+ * await driver.play(tap(center, {holdMs: 400}));
+ * const [release] = await hold.held();
+ * ```
+ */
+export async function armHold(
+ page: Page,
+ scope?: Locator,
+ {
+ count = 1,
+ minProgressMs = 0,
+ newOnly = false,
+ timeout = 5_000,
+ }: {
+ count?: number;
+ minProgressMs?: number;
+ newOnly?: boolean;
+ timeout?: number;
+ } = {},
+): Promise<ArmedHold> {
+ const scopeHandle = scope ? await scope.elementHandle() : null;
+ await installCurveEnd(page);
+ armedHolds += 1;
+ const id = armedHolds;
+ await page.evaluate(
+ ([root, needed, minProgress, fresh, wait, key]) => {
+ const w = window as unknown as {
+ __harnessHold: (
+ root: Element | null,
+ skip?: ReadonlySet<Animation>,
+ ) => unknown[];
+ __harnessTimerGate?: {
+ frame?: typeof requestAnimationFrame;
+ timeout?: typeof setTimeout;
+ };
+ __harnessArmed?: Record<number, Promise<unknown[]>>;
};
- });
- }, scopeHandle);
+ // The harness's own waits run on the real timers: a frozen timer gate
+ // (story.ts) holds only the page's.
+ const frame =
+ w.__harnessTimerGate?.frame ??
+ window.requestAnimationFrame.bind(window);
+ const later =
+ w.__harnessTimerGate?.timeout ?? window.setTimeout.bind(window);
+ const deadline = performance.now() + wait;
+ // With `newOnly`, what the document has when armed neither counts nor
+ // joins the hold: a motion already running goes on, and the page holds
+ // the one that starts after it.
+ const before = fresh ? new Set(document.getAnimations()) : undefined;
+ const counts = (animation: Animation) => {
+ const target =
+ (animation.effect as KeyframeEffect | null)?.target ?? null;
+ return (
+ animation.playState === 'running' &&
+ animation.timeline instanceof DocumentTimeline &&
+ !(before?.has(animation) ?? false) &&
+ (root == null ||
+ (target != null && (root === target || root.contains(target)))) &&
+ !(
+ target instanceof Element &&
+ target.closest('[data-harness-control]') != null
+ ) &&
+ Number(animation.currentTime ?? 0) /
+ Math.abs(animation.playbackRate || 1) >=
+ minProgress
+ );
+ };
+ const held = new Promise<unknown[]>((resolve, reject) => {
+ // Looked for on every frame and every 4 ms between them: WebKit can
+ // present no frame for about 70 ms while it first composites a newly
+ // animated layer (longer on a loaded runner), and its animations and
+ // timers run on meanwhile, so a look between frames holds a short one
+ // that much earlier.
+ let done = false;
+ let round = 0;
+ const schedule = () => {
+ const mine = ++round;
+ const run = () => {
+ // Of the frame and the timer a round schedules, the first runs.
+ if (mine === round) {
+ tick();
+ }
+ };
+ frame(run);
+ later(run, 4);
+ };
+ const tick = () => {
+ if (done) {
+ return;
+ }
+ if (document.getAnimations().filter(counts).length >= needed) {
+ done = true;
+ try {
+ resolve(w.__harnessHold(root, before));
+ } catch (error) {
+ reject(error);
+ }
+ } else if (performance.now() > deadline) {
+ done = true;
+ reject(
+ new Error(
+ `armHold: no animation under the scope ran within ${wait} ms`,
+ ),
+ );
+ } else {
+ schedule();
+ }
+ };
+ schedule();
+ });
+ // Read by `held()`; a rejection nobody reads yet is not the page's.
+ held.catch(() => undefined);
+ w.__harnessArmed = {...w.__harnessArmed, [key]: held};
+ },
+ [
+ scopeHandle,
+ Math.max(count, 1),
+ Math.max(minProgressMs, 0),
+ newOnly,
+ timeout,
+ id,
+ ] as const,
+ );
+ return {
+ held: () =>
+ page.evaluate(key => {
+ const w = window as unknown as {
+ __harnessArmed?: Record<number, Promise<HeldAnimation[]>>;
+ };
+ const held = w.__harnessArmed?.[key];
+ if (held == null) {
+ throw new Error('armHold: this hold was never armed on this page');
+ }
+ delete w.__harnessArmed?.[key];
+ return held;
+ }, id),
+ };
}
/**
diff --git a/internal/interaction-harness/src/harness.interaction.browser.spec.ts b/internal/interaction-harness/src/harness.interaction.browser.spec.ts
index dcfb5e51a9..775c631c06 100644
--- a/internal/interaction-harness/src/harness.interaction.browser.spec.ts
+++ b/internal/interaction-harness/src/harness.interaction.browser.spec.ts
@@ -39,6 +39,7 @@ import fs from 'node:fs';
import {expect, test, type Page} from '@playwright/test';
import type {CastFrame, TrackedFrame} from './frames';
import {
+ armHold,
animationStoryboard,
blockMainThread,
busyWindowProof,
@@ -1789,12 +1790,15 @@ test.describe('curve sampling', () => {
}) => {
await fixture(page);
const box = page.locator('#box');
+ // Armed before the 400 ms transition starts, so a busy runner cannot end
+ // it before the hold.
+ const hold = await armHold(page, box);
await box.evaluate(el => {
el.style.transition = 'transform 400ms cubic-bezier(0.24, 1, 0.4, 1)';
void (el as HTMLElement).offsetWidth;
el.style.transform = 'translateY(200px)';
});
- const held = await holdAnimations(page, box);
+ const held = await hold.held();
expect(held).toHaveLength(1);
expect(held[0].kind).toBe('CSSTransition');
const samples = curveOf(
@@ -1815,6 +1819,9 @@ test.describe('curve sampling', () => {
const box = page.locator('#box');
const spring = {response: 0.4, dampingFraction: 0.75};
const duration = 1200;
+ // Armed before the run starts, so a busy runner cannot end it before the
+ // hold.
+ const hold = await armHold(page, box);
await box.evaluate(
(el, {stops, ms}) => {
el.animate(
@@ -1829,7 +1836,7 @@ test.describe('curve sampling', () => {
ms: duration,
},
);
- await holdAnimations(page, box);
+ await hold.held();
const samples = curveOf(
await sampleCurve(box, timeline(duration, 1000 / 60)),
'translateX',
@@ -1849,16 +1856,97 @@ test.describe('curve sampling', () => {
});
test.describe('holding', () => {
+ test('an armed hold takes a short animation on its first frames, from the page itself', async ({
+ page,
+ }) => {
+ await fixture(page);
+ const box = page.locator('#box');
+ // Armed before the animation starts: the page holds it on the first frame
+ // it has run, however late a busy runner would have delivered a hold sent
+ // after it (a 120 ms run can end first).
+ const hold = await armHold(page, box);
+ await box.evaluate(el =>
+ el.animate(
+ [{transform: 'translateY(0px)'}, {transform: 'translateY(200px)'}],
+ {duration: 120, easing: 'linear'},
+ ),
+ );
+ // Read once the run would have ended: what comes back, the page held
+ // itself.
+ await page.waitForTimeout(200);
+ const held = await hold.held();
+ expect(held).toHaveLength(1);
+ expect(held[0].heldAtMs ?? Number.POSITIVE_INFINITY).toBeLessThan(120);
+ const samples = await sampleCurve(box, [0, 60, 120]);
+ const result = compareCurve(
+ curveOf(samples, 'translateY'),
+ t => (200 * t) / 120,
+ 0.05,
+ );
+ expect(result.maxError, JSON.stringify(result.worst)).toBeLessThanOrEqual(
+ 0.05,
+ );
+ await releaseAnimations(page);
+ });
+
+ test('an armed hold with newOnly holds a turn that starts mid-motion, and leaves the motion already running', async ({
+ page,
+ }) => {
+ await fixture(page);
+ const box = page.locator('#box');
+ // A long motion runs first; the hold is armed during it, so only the
+ // 120 ms turn that starts after the arm is held.
+ await box.evaluate(el =>
+ el.animate(
+ [{transform: 'translateX(0px)'}, {transform: 'translateX(100px)'}],
+ {duration: 10_000, easing: 'linear'},
+ ),
+ );
+ const hold = await armHold(page, box, {newOnly: true});
+ await box.evaluate(el =>
+ el.animate([{opacity: 1}, {opacity: 0}], {
+ duration: 120,
+ easing: 'linear',
+ }),
+ );
+ // Read once the turn would have ended: what comes back, the page held
+ // itself.
+ await page.waitForTimeout(200);
+ const held = await hold.held();
+ expect(held).toHaveLength(1);
+ expect(held[0].keyframes.map(k => k.opacity)).toEqual(['1', '0']);
+ expect(held[0].heldAtMs ?? Number.POSITIVE_INFINITY).toBeLessThan(120);
+ expect(
+ await box.evaluate(el =>
+ el.getAnimations().map(animation => animation.playState),
+ ),
+ ).toEqual(['running', 'paused']);
+ await releaseAnimations(page, {finish: true});
+ });
+
+ test('an armed hold rejects when nothing under its scope starts', async ({
+ page,
+ }) => {
+ await fixture(page);
+ const hold = await armHold(page, page.locator('#box'), {timeout: 200});
+ await expect(hold.held()).rejects.toThrow(
+ /no animation under the scope ran/,
+ );
+ });
+
test('a sample at an end reports the time it was read at', async ({page}) => {
await fixture(page);
const box = page.locator('#box');
+ // Armed before the 300 ms run starts, so a busy runner cannot end it
+ // before the hold.
+ const hold = await armHold(page, box);
await box.evaluate(el =>
el.animate(
[{transform: 'translateY(0px)'}, {transform: 'translateY(200px)'}],
{duration: 300, easing: 'linear'},
),
);
- await holdAnimations(page, box);
+ await hold.held();
const samples = await sampleCurve(box, [0, 150, 300]);
// Read just inside the end, and labelled so.
expect(samples.at(-1)).toMatchObject({t: 300, presentedAt: 299.5});
@@ -1910,10 +1998,13 @@ test.describe('holding', () => {
).play();
}
await new Promise(resolve => setTimeout(resolve, 120));
+ // 0.5 px a ms for 6 s: long enough that the hold, sent after the second
+ // runner starts (an armed hold would take the first one alone), reaches
+ // both on a loaded runner.
const run = (el: Element | null) =>
el?.animate(
- [{transform: 'translateX(0px)'}, {transform: 'translateX(300px)'}],
- {duration: 600, easing: 'linear'},
+ [{transform: 'translateX(0px)'}, {transform: 'translateX(3000px)'}],
+ {duration: 6000, easing: 'linear'},
);
const box = run(document.getElementById('box'));
const gap = new Promise(resolve => setTimeout(resolve, 100));
@@ -1925,8 +2016,11 @@ test.describe('holding', () => {
// Busy: no frame runs.
}
await gap;
+ // Made once #box has started, so the two never share a first frame,
+ // however long a loaded engine goes without one.
+ await box?.ready;
const later = run(make('later'));
- await Promise.all([box?.ready, later?.ready]);
+ await later?.ready;
return Number(later?.startTime) - Number(box?.startTime);
});
const held = await holdAnimations(page);
@@ -1939,10 +2033,13 @@ test.describe('holding', () => {
page
.locator(`#${id}`)
.evaluate(el => new DOMMatrix(getComputedStyle(el).transform).m41);
- expect(await seekAnimations(page, 300)).toBe(300);
- expect(await x('box')).toBeCloseTo(150, 1);
+ // A seek 150 ms past the second start, however late it came: both runners
+ // run there, each at its own time.
+ const t = Math.ceil(later.offsetMs) + 150;
+ expect(await seekAnimations(page, t)).toBe(t);
+ expect(await x('box')).toBeCloseTo((3000 * t) / 6000, 1);
expect(await x('later')).toBeCloseTo(
- (300 * (300 - later.offsetMs)) / 600,
+ (3000 * (t - later.offsetMs)) / 6000,
1,
);
// The finished fade kept its end value; the paused animation stays put.
@@ -1966,6 +2063,9 @@ test.describe('holding', () => {
}) => {
await fixture(page);
// #box moves for 300 ms and fades for 400 ms; another element runs longer.
+ // Armed before they start (all in one task), so a busy runner cannot end
+ // the move before the hold.
+ const hold = await armHold(page);
await page.evaluate(() => {
const box = document.getElementById('box');
box?.animate(
@@ -1982,7 +2082,7 @@ test.describe('holding', () => {
document.body.append(other);
other.animate([{opacity: 0}, {opacity: 1}], {duration: 600});
});
- await holdAnimations(page);
+ await hold.held();
const samples = await sampleCurve(page.locator('#box'), [0, 150, 300]);
// The move is read just inside its end, the fade where it is.
expect(samples.at(-1)?.presentedAtFor).toEqual({
@@ -2006,7 +2106,9 @@ test.describe('holding', () => {
page,
}) => {
await fixture(page);
- // #box moves for 300 ms; its ::after fades for 600 ms.
+ // #box moves for 300 ms; its ::after fades for 600 ms. Armed before they
+ // start, so a busy runner cannot end the move before the hold.
+ const hold = await armHold(page);
await page.evaluate(() => {
const style = document.createElement('style');
style.textContent = "#box::after { content: ''; display: block; }";
@@ -2021,7 +2123,7 @@ test.describe('holding', () => {
pseudoElement: '::after',
});
});
- await holdAnimations(page);
+ await hold.held();
const samples = await sampleCurve(page.locator('#box'), [0, 150, 300]);
// The move is read just inside its own end, not at the ::after's time.
expect(samples.at(-1)?.presentedAt).toBe(299.5);
@@ -2033,6 +2135,9 @@ test.describe('holding', () => {
}) => {
await fixture(page);
const box = page.locator('#box');
+ // Each hold is armed before its 300 ms run starts, so a busy runner
+ // cannot end the run before the hold.
+ const hold = await armHold(page, box);
await box.evaluate(el => {
el.style.width = '80.6px';
el.style.height = '40.4px';
@@ -2041,7 +2146,7 @@ test.describe('holding', () => {
easing: 'linear',
});
});
- await holdAnimations(page, box);
+ await hold.held();
const [mid] = await sampleCurve(box, [150]);
expect(mid.transform.translateX).toBeCloseTo(40.3, 2);
expect(mid.transform.translateY).toBeCloseTo(10.1, 2);
@@ -2049,6 +2154,7 @@ test.describe('holding', () => {
// animation with the first one still running.
await releaseAnimations(page, {finish: true});
+ const second = await armHold(page, box);
await box.evaluate(el => {
el.animate(
[
@@ -2058,7 +2164,7 @@ test.describe('holding', () => {
{duration: 300, easing: 'linear'},
);
});
- await holdAnimations(page, box);
+ await second.held();
await expect(sampleCurve(box, [150])).rejects.toThrow(
/cannot resolve translate/,
);
@@ -2072,10 +2178,12 @@ test.describe('holding', () => {
const box = page.locator('#box');
// Reversed, the run starts at its end: progress counts down from there,
// so a wait for 100 ms of it returns once the run has presented that much.
+ // Each run here lasts 10 s, so a busy runner cannot end it before the
+ // test's next read.
const watch = await watchAnimations(box);
await box.evaluate(el => {
el.animate([{translate: '0px 0px'}, {translate: '100px 0px'}], {
- duration: 1000,
+ duration: 10_000,
easing: 'linear',
}).reverse();
});
@@ -2090,18 +2198,18 @@ test.describe('holding', () => {
expect(presented).toBeGreaterThanOrEqual(100);
await box.evaluate(el => el.getAnimations().forEach(a => a.finish()));
- // At playback rate 2 a 1,000 ms curve runs 500 ms: its interval, and a
- // seek or sample at t reads the curve at 2t.
+ // At playback rate 2 a 10,000 ms curve runs 5,000 ms: its interval, and
+ // a seek or sample at t reads the curve at 2t.
const fast = await watchAnimations(box);
await box.evaluate(el => {
const animation = el.animate(
- [{translate: '0px 0px'}, {translate: '100px 0px'}],
- {duration: 1000, easing: 'linear'},
+ [{translate: '0px 0px'}, {translate: '1000px 0px'}],
+ {duration: 10_000, easing: 'linear'},
);
animation.playbackRate = 2;
});
const [running] = await fast.started();
- expect(running.to - running.from).toBeCloseTo(500, 0);
+ expect(running.to - running.from).toBeCloseTo(5000, 0);
await holdAnimations(page, box);
await seekAnimations(page, 125);
const x = await box.evaluate(
@@ -2242,12 +2350,13 @@ test.describe('holding', () => {
test('a hold stays where it was read, not a frame later', async ({page}) => {
await fixture(page);
+ // 10 s, so the hold sent after the wait reaches the run on a busy runner.
await page.evaluate(() => {
document
.getElementById('box')
?.animate(
- [{transform: 'translateX(0px)'}, {transform: 'translateX(300px)'}],
- {duration: 1000, easing: 'linear'},
+ [{transform: 'translateX(0px)'}, {transform: 'translateX(3000px)'}],
+ {duration: 10_000, easing: 'linear'},
);
});
const box = page.locator('#box');
@@ -2355,6 +2464,16 @@ test.describe('holding', () => {
page,
}) => {
await fixture(page);
+ await page.evaluate(() => {
+ const other = document.createElement('div');
+ other.id = 'other';
+ document.body.append(other);
+ });
+ const box = page.locator('#box');
+ // Both holds are armed before the 300 ms runs start, so a busy runner
+ // cannot end either before its hold; each adds to the held set.
+ const first = await armHold(page, box);
+ const second = await armHold(page, page.locator('#other'));
await page.evaluate(() => {
document
.getElementById('box')
@@ -2362,17 +2481,20 @@ test.describe('holding', () => {
[{transform: 'translateX(0px)'}, {transform: 'translateX(300px)'}],
{duration: 300, easing: 'linear', fill: 'forwards'},
);
- const other = document.createElement('div');
- other.id = 'other';
- document.body.append(other);
- other.animate([{opacity: 0}, {opacity: 1}], {
+ document.getElementById('other')?.animate([{opacity: 0}, {opacity: 1}], {
duration: 300,
fill: 'forwards',
});
});
- const box = page.locator('#box');
- expect(await holdAnimations(page, box)).toHaveLength(1);
- expect(await holdAnimations(page, page.locator('#other'))).toHaveLength(1);
+ expect(await first.held()).toHaveLength(1);
+ expect(await second.held()).toHaveLength(1);
+ expect(
+ await page.evaluate(
+ () =>
+ (window as unknown as {__harnessHeld: Animation[]}).__harnessHeld
+ .length,
+ ),
+ ).toBe(2);
await releaseAnimations(page);
// The first hold was released too: the move runs to its end, and rest is
// its end, not the frame it was held on.
@@ -2441,13 +2563,15 @@ test.describe('holding', () => {
}) => {
await fixture(page);
const box = page.locator('#box');
+ // Armed before the 300 ms transition starts, so a busy runner cannot end
+ // it before the hold.
+ const hold = await armHold(page, box);
await box.evaluate(el => {
el.style.transition = 'transform 300ms linear';
el.getBoundingClientRect();
el.style.transform = 'translateX(300px)';
});
- await waitForAnimation(box);
- expect(await holdAnimations(page, box)).toHaveLength(1);
+ expect(await hold.held()).toHaveLength(1);
// The page sends the box back: the held transition is cancelled, and a
// new one runs from where the box is.
await box.evaluate(el => {
@@ -2480,6 +2604,9 @@ test.describe('holding', () => {
page,
}) => {
await fixture(page);
+ // Armed before the 300 ms fade starts, so a busy runner cannot end it
+ // before the hold.
+ const hold = await armHold(page);
await page.evaluate(() => {
const box = document.getElementById('box');
box?.animate([{rotate: '0deg'}, {rotate: '360deg'}], {
@@ -2491,7 +2618,7 @@ test.describe('holding', () => {
document.body.append(fade);
fade.animate([{opacity: 0}, {opacity: 1}], {duration: 300});
});
- expect(await holdAnimations(page)).toHaveLength(2);
+ expect(await hold.held()).toHaveLength(2);
await releaseAnimations(page, {finish: true});
expect(
await page.evaluate(() => ({
@@ -3489,6 +3616,9 @@ test.describe('storyboards', {tag: '@storyboard'}, () => {
}, testInfo) => {
await fixture(page);
const box = page.locator('#box');
+ // Armed before the 200 ms run starts, so a busy runner cannot end it
+ // before the film holds it.
+ const hold = await armHold(page, box);
await box.evaluate(el =>
el.animate(
[{transform: 'translateX(0)'}, {transform: 'translateX(240px)'}],
@@ -3496,6 +3626,7 @@ test.describe('storyboards', {tag: '@storyboard'}, () => {
),
);
const {storyboard} = await animationStoryboard(page, {
+ held: await hold.held(),
name: 'harness-self-test-animation',
clip: {x: 0, y: 340, width: 402, height: 120},
measure: async () => ({
@@ -3677,6 +3808,11 @@ test.describe('storyboards', {tag: '@storyboard'}, () => {
await fixture(page);
await installTimerGate(page);
const box = page.locator('#box');
+ // The gate is frozen and the hold armed before the component's timer is
+ // set and its 300 ms run starts, so on a busy runner neither the timer
+ // nor the run's end can come before them.
+ await freezeTimers(page);
+ const hold = await armHold(page, box);
// A component that ends its own animation from a timer (a transitionend
// backstop): without the gate it would finish behind the held storyboard.
await box.evaluate(el => {
@@ -3689,9 +3825,10 @@ test.describe('storyboards', {tag: '@storyboard'}, () => {
(window as unknown as {timerRan?: boolean}).timerRan = true;
}, 40);
});
- await freezeTimers(page);
+ const held = await hold.held();
await page.waitForTimeout(120); // the timer is due now, and held
const {storyboard} = await animationStoryboard(page, {
+ held,
name: 'harness-self-test-timer-gate',
clip: {x: 0, y: 340, width: 402, height: 120},
measure: async () => ({
@@ -3716,6 +3853,9 @@ test.describe('storyboards', {tag: '@storyboard'}, () => {
page,
}, testInfo) => {
await fixture(page);
+ // Armed before the 200 ms fade starts, so a busy runner cannot end it
+ // before the film holds it.
+ const hold = await armHold(page, page.locator('#box'));
await page.locator('#box').evaluate(el => {
el.animate([{rotate: '0deg'}, {rotate: '360deg'}], {
duration: 800,
@@ -3724,6 +3864,7 @@ test.describe('storyboards', {tag: '@storyboard'}, () => {
el.animate([{opacity: 1}, {opacity: 0.4}], {duration: 200});
});
const {storyboard, held} = await animationStoryboard(page, {
+ held: await hold.held(),
name: 'harness-self-test-endless',
clip: {x: 0, y: 340, width: 402, height: 120},
columns: 4,
@@ -3739,7 +3880,10 @@ test.describe('storyboards', {tag: '@storyboard'}, () => {
}, testInfo) => {
await fixture(page);
// A spinner that started a second earlier, a 300 ms move, and a 240 ms
- // move that starts 83 ms after it.
+ // move that starts 83 ms after it. The page holds all three once the
+ // second move runs, so a busy runner cannot end the first move before the
+ // film holds it.
+ const hold = await armHold(page, undefined, {count: 3});
await page.evaluate(async () => {
const make = (id: string, top: number) => {
const el = document.createElement('div');
@@ -3755,21 +3899,26 @@ test.describe('storyboards', {tag: '@storyboard'}, () => {
iterations: Infinity,
});
await new Promise(resolve => setTimeout(resolve, 1000));
- make('first', 360).animate(
+ const first = make('first', 360).animate(
[{transform: 'translateX(0px)'}, {transform: 'translateX(300px)'}],
{duration: 300, easing: 'linear'},
);
- await new Promise(resolve => setTimeout(resolve, 83));
- make('second', 410).animate(
+ const second = make('second', 410).animate(
[{transform: 'translateX(0px)'}, {transform: 'translateX(240px)'}],
{duration: 240, easing: 'linear'},
);
+ // The second starts 83 ms after the first on the document timeline
+ // itself, however late a busy runner would fire a timer between them.
+ const now = Number(document.timeline.currentTime);
+ first.startTime = now;
+ second.startTime = now + 83;
});
const x = (id: string) =>
page
.locator(`#${id}`)
.evaluate(el => new DOMMatrix(getComputedStyle(el).transform).m41);
const {storyboard, held} = await animationStoryboard(page, {
+ held: await hold.held(),
name: 'harness-self-test-offsets',
clip: {x: 0, y: 340, width: 402, height: 120},
columns: 6,
diff --git a/internal/interaction-harness/src/storyboard.ts b/internal/interaction-harness/src/storyboard.ts
index 2dc22fdc8c..5b7208d309 100644
--- a/internal/interaction-harness/src/storyboard.ts
+++ b/internal/interaction-harness/src/storyboard.ts
@@ -267,21 +267,31 @@ export interface AnimationStoryboardOptions extends StoryboardOptions {
* each animation at its own offset (a held end value is not filmed).
*/
readonly times?: readonly number[];
- /** Restrict to animations inside this element. */
+ /** Restrict to animations inside this element (when `held` is not passed). */
readonly scope?: Locator;
+ /**
+ * What an armed hold already took (`armHold`'s `held()`): filmed instead of
+ * holding now, for an animation an action starts that a hold sent after
+ * the action could miss on a loaded runner.
+ */
+ readonly held?: readonly HeldAnimation[];
/** Measurements per frame (runs after the seek). */
readonly measure?: () => Promise<Readonly<Record<string, unknown>>>;
}
/**
* Holds every running animation, then seeks them together to each time and
- * photographs the clip. Call it right after starting the animation under test.
+ * photographs the clip. Call it right after starting the animation under test,
+ * or pass `held`, what an armed hold took (`armHold`): the film then uses that
+ * held set instead of holding now, and `scope` plays no part.
*/
export async function animationStoryboard(
page: Page,
options: AnimationStoryboardOptions,
): Promise<{storyboard: Storyboard; held: HeldAnimation[]}> {
- const held = await holdAnimations(page, options.scope);
+ const held = options.held
+ ? [...options.held]
+ : await holdAnimations(page, options.scope);
if (held.length === 0) {
throw new Error(`storyboard ${options.name}: no running animation to hold`);
}