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.mdindex 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. Finishedanimations, ones the page paused and ones on a scroll or view timeline are leftalone; 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 anoracle from `math.ts` through `compareCurve`; a tolerance states the errorbudget (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 milliseconddiff --git a/internal/interaction-harness/src/curves.ts b/internal/interaction-harness/src/curves.tsindex 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.tsindex 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 heldconst {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.tsindex 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`);}