An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file curves.ts
* @input Uses a Playwright `Page`, a `Locator` for the animated element, and
* the Web Animations API in the page (CSS transitions and CSS animations are
* Web Animations too)
* @output `holdAnimations` pauses every running animation and describes it.
* `armHold` makes the page hold what an action starts, as soon as it runs,
* and checks that it took the motion the test judges. `seekAnimations`
* moves them to t ms from the held origin, each keeping its offset, and
* `releaseAnimations` lets them go. `sampleCurve` reads the presented
* transform/opacity at each t, with the individual `translate`, `rotate`
* and `scale` properties composed in. `curveOf` picks one channel out of
* the samples for ./math's `compareCurve`. The animation-state waits are
* `waitForAnimation`, `watchAnimations`, `waitForRest` and `settlesAt`.
* @position Curve sampling: the exact presented value of an animation at a
* fixed time, independent of frame timing, so a curve can be compared with
* the UIKit reference to a fraction of a pixel. A paused animation's effect
* is applied at its current time and `getComputedStyle` reads it.
*
* SYNC: Keep ./storyboard.ts using these for its animation filmstrips.
*/
import type {Locator, Page} from '@playwright/test';
import {defineAnimatedProperties} from './animated-properties';
import {defineCurveEnd} from './curve-end';
import {FRAME_STARVATION_MS, FrameStarvationError} from './frames';
import {parseTransform, type TimedValue, type Transform2D} from './math';
/** How far inside its end a seek past an animation's end lands, ms. */
export const END_INSET_MS = 0.5;
/**
* How long a hold waits for its scope, or a judged target, to be on the
* page, ms.
*/
const TARGET_WAIT_MS = 5_000;
/**
* The element that `scope` names, or null without a scope. Throws by name
* when no element matches within TARGET_WAIT_MS: it is gone, or it never
* came.
*/
async function scopeElement(caller: string, scope: Locator | undefined) {
if (scope == null) {
return null;
}
return scope.elementHandle({timeout: TARGET_WAIT_MS}).catch(error => {
if (error instanceof Error && error.name === 'TimeoutError') {
throw new Error(
`${caller}: the scope ${scope.toString()} is not on the page after ${TARGET_WAIT_MS} ms: it is gone, or it never came`,
);
}
throw error;
});
}
/**
* Page side: records every animation the document runs, from its first frame
* or its creation (a frame loop on the page's real requestAnimationFrame, and
* the CSS animation and transition events), so an animation that starts and
* ends before a test looks is still seen, with the time it finished (from its
* finish event, or from a CSS run's end event when the page cancels it there
* before the finish event comes). Each
* entry keeps the animation's start time too: a page that cancels a finished
* animation (an entrance whose class is removed on `animationend`) nulls its
* `startTime`.
*
* A run that the page cancels while it plays is dated at the cancel.
*/
function animationRecorder(): void {
const w = window as unknown as {__harnessAnimations?: unknown};
if (w.__harnessAnimations) {
return;
}
// The run a CSS animation or transition event names.
const cssRunName = (event: Event) =>
event.type.startsWith('animation')
? (event as AnimationEvent).animationName
: (event as TransitionEvent).propertyName;
// The page's real frames, even when a timer gate already holds its callbacks.
const frame = (
(
window as unknown as {
__harnessTimerGate?: {frame: typeof requestAnimationFrame};
}
).__harnessTimerGate?.frame ?? window.requestAnimationFrame
).bind(window);
const log: {
animation: Animation;
seenAt: number;
finishedAt: number | null;
startedAt: number | null;
// Where the run began, as the engine had it when it finished.
finishStart: number | null;
// When the page cancelled the run while it played, and how much of its
// curve it had presented by then (see the cancel wrapper below).
cancelledAt: number | null;
playedMs: number | null;
}[] = [];
// Start events that found no animation to record (see `onStart`), with
// the target's ancestors as they were: an exit the page removes at its end
// is still named for the container it left.
const unread: {
at: number;
target: EventTarget | null;
ancestors: Element[];
type: string;
name: string;
}[] = [];
// Each recorded animation's entry.
const entries = new WeakMap<Animation, (typeof log)[number]>();
// CSS runs whose end event came while a rendering trace ran, with the
// event's time (real) and the active time the event reports.
const endedInTrace: {
entry: (typeof log)[number];
at: number;
elapsedMs: number;
}[] = [];
// The times kept below are real: a page time plus the span a page freeze
// stood still so far. A later freeze then leaves them where they were.
const span = () =>
(window as unknown as {__harnessFreeze?: {offset: number}}).__harnessFreeze
?.offset ?? 0;
const real = (time: number | null) => (time == null ? null : time + span());
// Entries whose start time has not resolved yet (still pending when seen).
let unstarted: (typeof log)[number][] = [];
let armedAt = performance.now();
// When the animation began to play, on the document timeline. A run going
// backward reports as its startTime the moment its current time would
// reach 0, a whole run after it began (it begins at its end).
const playStart = (animation: Animation): number | null => {
if (animation.startTime == null) {
return null;
}
const rate = animation.playbackRate;
if (rate >= 0) {
return Number(animation.startTime);
}
const end = Number(
(animation.effect as KeyframeEffect | null)?.getComputedTiming()
.endTime ?? 0,
);
return Number(animation.startTime) - end / Math.abs(rate);
};
// Dates a recorded run's finish as the engine has it now. Its start time is
// usually still set (the finish listener, added as the animation was made,
// runs before the page's own, and the end-event listener below runs in the
// capture phase), and the run ended where that start puts its end, through
// the rate. Without one, the start the recorder holds stands in, kept as
// the run ran (after a pause, a seek or a rate change). A run that ends as
// it starts (one reversed from rest) can finish before any start resolves:
// it then began where the finish event's timeline time `at` puts its start.
// Read later, the start time can say otherwise (WebKit resolves or moves it
// a frame later), and the finish event itself arrives late (a frame or more
// after a finish() call).
const dateFinish = (
entry: {
animation: Animation;
finishedAt: number | null;
startedAt: number | null;
finishStart: number | null;
},
at: number | null,
) => {
const animation = entry.animation;
const end = Number(
(animation.effect as KeyframeEffect | null)?.getComputedTiming()
.endTime ?? 0,
);
const speed = Math.abs(animation.playbackRate || 1);
// The finish event's timeline time is the engine's own, already real.
entry.finishStart =
real(playStart(animation)) ??
entry.startedAt ??
(at == null ? null : at - end / speed);
entry.finishedAt =
entry.finishStart == null
? performance.now() + span()
: entry.finishStart + end / speed;
if (entry.startedAt == null) {
// Cancelled before a frame read its start: back from where it ended.
entry.startedAt = entry.finishStart ?? entry.finishedAt - end / speed;
}
};
const remember = (animation: Animation) => {
const recorded = entries.get(animation);
if (recorded != null) {
// A run paused and resumed (by the page, or by a hold and its release),
// seeked, or given another rate runs on a new start time: the start
// kept is the one it runs on, which its finish falls back to once the
// page has cancelled it.
if (animation.playState === 'running' && animation.startTime != null) {
recorded.startedAt = real(playStart(animation));
}
return;
}
// A running animation is recorded while still pending: on a cold page the
// next frame can come only after a short animation has finished.
if (animation.playState !== 'running') {
return;
}
// The target's ancestors as recorded: an exit whose element the page
// removes at its end is still reported for the container it left.
const ancestors: Element[] = [];
for (
let node = (animation.effect as KeyframeEffect | null)?.target ?? null;
node != null;
node = node.parentElement
) {
ancestors.push(node);
}
const entry = {
animation,
seenAt: performance.now(),
finishedAt: null as number | null,
startedAt: real(playStart(animation)),
finishStart: null as number | null,
cancelledAt: null as number | null,
playedMs: null as number | null,
ancestors,
};
entries.set(animation, entry);
if (entry.startedAt == null) {
unstarted.push(entry);
}
animation.addEventListener('finish', event => {
const at = (event as AnimationPlaybackEvent).timelineTime;
dateFinish(entry, at == null ? null : Number(at));
});
log.push(entry);
if (log.length > 5000) {
log.splice(0, log.length - 5000);
}
};
const record = () => {
for (const animation of document.getAnimations()) {
remember(animation);
}
unstarted = unstarted.filter(entry => {
if (entry.startedAt == null && entry.animation.startTime != null) {
entry.startedAt = real(playStart(entry.animation));
}
return entry.startedAt == null && entry.animation.playState !== 'idle';
});
};
// While a rendering trace runs (traceRendering sets
// `__harnessRenderingTrace`), the recorder stands down. Its per-frame
// callback would make every frame a main-thread frame, in which Blink
// restyles each running animation's target, a composited one included (and
// lays out an anchored one), and document.getAnimations() flushes style:
// exactly what the trace counts. So it runs no frame callback, and a CSS
// animation or transition event reads only the animations of the element it
// names, once, at that animation's start (one that ends inside the trace is
// otherwise never seen). The animate() wrapper below still records script
// animations (it reads no style), and traceRendering resumes the recorder
// once the trace ends.
const tracing = () =>
(window as unknown as {__harnessRenderingTrace?: boolean})
.__harnessRenderingTrace === true;
let looping = false;
const tick = () => {
if (tracing()) {
looping = false;
return;
}
record();
frame(tick);
};
const loop = () => {
if (!looping) {
looping = true;
frame(tick);
}
};
// What already runs when the recorder starts (a spinner on a page the
// harness touches for the first time) is seen now, before any watch arms;
// first seen a frame later, it would read as started by the watched action.
// (A recorder that starts during a trace reads once here, then waits.)
record();
loop();
// A start event with nothing left to read: a CSS animation shorter than the
// gap between two of the page's frames can start and finish inside it, and
// WebKit sends its start event only at the next frame, when
// `getAnimations()` no longer lists a finished animation that fills
// nothing. No object is left to record, so the event is kept: a wait that
// finds nothing names what it missed.
// Whether a recorded entry is the run a CSS animation or transition event
// is about: the same element (and pseudo-element) and name.
const isRunOf = (entry: {animation: Animation}, event: Event) => {
const effect = entry.animation.effect as KeyframeEffect | null;
const a = entry.animation as unknown as {
animationName?: string;
transitionProperty?: string;
};
return (
effect?.target === event.target &&
(effect?.pseudoElement || '') ===
((event as AnimationEvent).pseudoElement || '') &&
(a.animationName ?? a.transitionProperty) === cssRunName(event)
);
};
const onStart = (event: Event) => {
if (tracing()) {
// Inside a trace, read only the element the event names, once: a
// document-wide read flushes style.
const target = event.target;
if (target instanceof Element) {
// A pseudo-element's animation (`::backdrop`) is in the subtree.
const pseudo = (event as AnimationEvent | TransitionEvent)
.pseudoElement;
for (const animation of target.getAnimations({subtree: !!pseudo})) {
remember(animation);
}
}
return;
}
record();
// Only a live run answers: a replay of an animation that finished on the
// same element is a new run, and missed if nothing recorded it. A run the
// document still lists, running or paused, answers too: one that starts
// paused is never recorded, and one replayed with play() keeps the
// finish of its first run.
const live =
log.some(
entry =>
entry.finishedAt == null &&
entry.animation.playState !== 'idle' &&
isRunOf(entry, event),
) ||
document
.getAnimations()
.some(
animation =>
(animation.playState === 'running' ||
animation.playState === 'paused') &&
isRunOf({animation}, event),
);
if (!live) {
const ancestors: Element[] = [];
for (
let node = event.target instanceof Element ? event.target : null;
node != null;
node = node.parentElement
) {
ancestors.push(node);
}
unread.push({
at: performance.now(),
target: event.target,
ancestors,
type: event.type,
name: cssRunName(event),
});
if (unread.length > 500) {
unread.splice(0, unread.length - 500);
}
}
};
for (const type of ['animationstart', 'transitionrun', 'transitionstart']) {
document.addEventListener(type, onStart, true);
}
// Whether a run stands at its end in the direction it plays: finished, or
// still reading `running` with its current time there, to a microsecond
// (Chromium read 0.00000003 ms for a reversed run at its start). Chromium
// can send a CSS run's end event a frame before the run itself finishes.
const atEnd = (animation: Animation) => {
if (animation.playState === 'finished') {
return true;
}
if (animation.playState !== 'running' || animation.currentTime == null) {
return false;
}
const time = Number(animation.currentTime);
const end = Number(
(animation.effect as KeyframeEffect | null)?.getComputedTiming()
.endTime ?? 0,
);
return animation.playbackRate < 0 ? time <= 0.001 : time >= end - 0.001;
};
// A CSS run's end event, read before the page's own listeners (this one is
// on the document, in the capture phase), while the run still has its start
// time. A page that removes the element at its end cancels a run whose end
// event came before it finished, and a cancelled run never finishes: under
// load, a CSS exit reversed partway sent `transitionend` at current time 0,
// still `running`, and was cancelled a frame later with no finish event.
// Chromium sends a run's end event before its finish event, so the run is
// still unfinished here. While a rendering trace runs, no run's state is
// read, as in the cancel wrapper below. That read flushes style, and lays
// out the run's anchored layer at the end of its own window. Only the newest
// run the event names is kept: an older run of that name that the page cut
// short stays unfinished. The recorder's resume() dates the kept run from
// what it stored.
const onEnd = (event: Event) => {
if (tracing()) {
for (let i = log.length - 1; i >= 0; i--) {
const entry = log[i];
if (!isRunOf(entry, event)) {
continue;
}
if (entry.finishedAt == null) {
endedInTrace.push({
entry,
at: performance.now() + span(),
// The event carries the active time, so nothing is read from the
// run.
elapsedMs:
1000 *
Number(
(event as AnimationEvent | TransitionEvent).elapsedTime || 0,
),
});
}
return;
}
return;
}
for (const entry of log) {
if (
entry.finishedAt == null &&
isRunOf(entry, event) &&
atEnd(entry.animation)
) {
dateFinish(entry, null);
}
}
};
for (const type of ['animationend', 'transitionend']) {
document.addEventListener(type, onEnd, true);
}
// A script animation is recorded as it is made: WebKit can start and finish
// a short one between two frames of a fresh page.
const animate = Element.prototype.animate;
Element.prototype.animate = function (
this: Element,
...args: Parameters<Element['animate']>
) {
const animation = animate.apply(this, args);
remember(animation);
return animation;
};
// A run that the page cancels while it plays ended there, and no finish
// event comes. Core's motion animator retires each run so: once the curve
// ends, it writes the end inline and cancels the run. The run's finish
// would come only after a long end-state tail. So the run's start and how
// much of its curve it presented are read here, before the cancel clears
// them. A run cancelled before its first frame has no start, and it
// presented nothing. The state of a CSS run is read only outside a
// rendering trace, because those reads flush style.
const cancel = Animation.prototype.cancel;
Animation.prototype.cancel = function (this: Animation) {
const entry = entries.get(this);
const isCss = 'animationName' in this || 'transitionProperty' in this;
if (
entry != null &&
entry.finishedAt == null &&
!(isCss && tracing()) &&
this.playState === 'running' &&
this.startTime != null
) {
// The specified timing: a script animation's computed timing can
// restyle its target, which a rendering trace counts.
const timing = this.effect?.getTiming();
const delay = Number(timing?.delay ?? 0);
const endDelay = Number(timing?.endDelay ?? 0);
const duration =
typeof timing?.duration === 'number' ? timing.duration : 0;
const end = delay + duration * Number(timing?.iterations ?? 1) + endDelay;
const rate = this.playbackRate;
const speed = Math.abs(rate || 1);
const time = Number(this.currentTime ?? 0);
// A run going backward began at its end.
if (rate >= 0 || Number.isFinite(end)) {
entry.finishStart = real(
rate < 0
? Number(this.startTime) - end / speed
: Number(this.startTime),
);
entry.cancelledAt = performance.now() + span();
// Negative while the run is still in its start delay: it presented
// nothing, as the live check reads it.
entry.playedMs =
(rate < 0 ? end - endDelay - time : time - delay) / speed;
}
}
return cancel.call(this);
};
w.__harnessAnimations = {
log,
unread,
// A read from outside the recorder (a wait's poll) stands down while a
// trace runs, as the frame loop does: document.getAnimations() flushes
// style. CSS start events and the animate() wrapper still log what
// starts, and resume() catches up.
record: () => {
if (!tracing()) {
record();
}
},
// Dates the CSS runs that ended during a trace, then catches up on what
// started during it and runs its frames again. A run ends where its start
// puts its end, through its specified timing, as the cancel wrapper reads
// it. Its stored start comes first: the page may have cancelled the run at
// its end since then. Without one, the end event's time and active time
// stand in.
resume: () => {
for (const {entry, at, elapsedMs} of endedInTrace.splice(0)) {
if (entry.finishedAt != null) {
continue;
}
const timing = entry.animation.effect?.getTiming();
const delay = Number(timing?.delay ?? 0);
const duration =
typeof timing?.duration === 'number' ? timing.duration : 0;
const end =
delay +
duration * Number(timing?.iterations ?? 1) +
Number(timing?.endDelay ?? 0);
const speed = Math.abs(entry.animation.playbackRate || 1);
entry.finishStart = entry.startedAt ?? at - (delay + elapsedMs) / speed;
entry.startedAt ??= entry.finishStart;
entry.finishedAt = entry.finishStart + end / speed;
}
record();
loop();
},
// Record first, then stamp strictly after the newest entry: a step that
// changed style just before has its transition created by that read,
// and it started before the arm. While a trace runs the page-wide read
// stands down, as record() does; the watched element's own animations
// are still read, which resolves its pending style change. That read
// restyles the element (and lays out an anchored one) in the task that
// takes the watch, so a traced proof takes its watch before the window
// it counts (README: No Layout / Paint).
arm: (element?: Element) => {
if (!tracing()) {
record();
} else if (element != null) {
for (const animation of element.getAnimations({subtree: true})) {
remember(animation);
}
}
const newest = log.length === 0 ? 0 : log[log.length - 1].seenAt;
armedAt = Math.max(performance.now(), newest + 0.001);
return armedAt;
},
armedAt: () => armedAt,
// Drops every animation the log holds, with the elements and ancestors
// they keep alive; later waits record afresh.
release: () => {
log.length = 0;
unread.length = 0;
unstarted = [];
endedInTrace.length = 0;
},
};
}
const recordingPages = new WeakSet<Page>();
/** Starts the recorder now and on every later document of the page. */
async function installRecorder(page: Page): Promise<void> {
if (!recordingPages.has(page)) {
recordingPages.add(page);
await page.addInitScript(animationRecorder);
}
await page.evaluate(animationRecorder);
}
/**
* Installs `window.__harnessCurveEnd(animation)`: the local time (ms, delay
* included) where the animation's effect stops changing. An animation whose
* 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. 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);
// The hold is installed with the curve end it reads and the property match
// of its judged motions. One round trip installs all three, so a hold sent
// from the test costs no extra one.
await page.evaluate(
`(${defineCurveEnd.toString()})();(${defineHold.toString()})();(${defineAnimatedProperties.toString()})();`,
);
}
/**
* Installs `window.__harnessHold(root)` in the page, once (see
* `installCurveEnd`). A page function: it closes over nothing, and reads the
* curve end `defineCurveEnd` installs.
*/
function defineHold(): void {
const w = window as unknown as {
__harnessHold?: (
root: Element | null,
skip?: ReadonlySet<Animation>,
) => unknown[];
};
if (w.__harnessHold) {
return;
}
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],
};
});
};
}
export interface HeldAnimation {
readonly index: number;
/** `CSSTransition`, `CSSAnimation` or `Animation` (script-created). */
readonly kind: string;
/** Transitioned property or animation name, when CSS made it. */
readonly name: string | null;
readonly target: string | null;
readonly durationMs: number;
readonly delayMs: number;
/**
* Where its curve ends, ms from its start (delay included): before a held
* end value, if its keyframes end in one and it plays forward under a
* linear or cubic-bézier effect easing; otherwise its end time.
*/
readonly curveEndMs: number;
readonly easing: string;
readonly keyframes: readonly Record<string, unknown>[];
/** Where it was when held, ms. */
readonly heldAtMs: number | null;
/**
* How much later than the held origin (the earliest start among the
* animations the first hold took) it started, ms; negative for an earlier
* start held by a later hold. A seek to t moves it to its own t - offsetMs,
* so staggered starts stay staggered.
*/
readonly offsetMs: number;
}
/**
* Pauses every running animation in the document (optionally only those whose
* target is inside `scope`) and returns what was held. Finished animations,
* animations the page paused, and animations on a scroll or view timeline are
* left as they are. Later `seekAnimations` calls move exactly the held set,
* each by its offset from the held origin, and `releaseAnimations` resumes
* only it. A second call adds to the held set: what the first held stays held
* until the release, and offsets keep counting from the origin the first call
* set (the earliest start it took), so offsets already returned stay true.
* An animation the page cancels after the hold leaves the held set.
* Retargeting a CSS transition cancels it. Seeking, sampling and releasing
* skip such an animation rather than revive it. A judged motion's run fails
* the next seek or sample instead: a read would show a run that the hold did
* not take.
*
* `judges` names the motion that the test reads from the hold, as for
* `armHold`. A hold sent from the test takes what runs when it reaches the
* page: the judged motion can still be to come, or already over on a busy
* runner, while other animations under the scope run. So the call rejects
* when it took no animation of each judged motion.
*/
export async function holdAnimations(
page: Page,
scope: Locator | undefined,
options: HoldOptions,
): Promise<HeldAnimation[]> {
const motions = judgedMotions('holdAnimations', options?.judges);
const scopeHandle = await scopeElement('holdAnimations', scope);
await installCurveEnd(page);
holdKeys += 1;
const key = holdKeys;
const held = await page.evaluate(
([root, id, judged]) => {
const w = window as unknown as {
__harnessHold: (root: Element | null) => HeldAnimation[];
__harnessHeld?: Animation[];
__harnessTook?: Record<number, Animation[]>;
};
const took = w.__harnessHold(root);
// The hold appends what it took to the held set. The judged-motion
// check reads these animations.
if (judged && took.length > 0) {
w.__harnessTook = {
...w.__harnessTook,
[id]: (w.__harnessHeld ?? []).slice(-took.length),
};
}
return took;
},
[scopeHandle, key, motions.length > 0] as const,
);
await expectJudgedMotionsHeld(page, key, motions, {
caller: 'holdAnimations',
cause:
'The judged motion did not run when the hold reached the page (not started yet, or already over)',
remedy:
'Arm the hold before the action that starts the motion (armHold), so the page holds it as it starts.',
});
return held;
}
/** 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. Rejects when
* the hold took no animation of a judged motion.
*/
held(): Promise<HeldAnimation[]>;
}
/**
* A motion that a test judges from an armed hold: an animation of `property`
* on `target`.
*/
export interface JudgedMotion {
readonly target: Locator;
/**
* The animated property, as CSS names it (`translate`, `background-color`,
* `--press-strength`).
*/
readonly property: string;
/** The pseudo-element that runs the motion, when the target's own does. */
readonly pseudoElement?: '::before' | '::after';
}
/**
* The motions an armed hold must take. `'count-only'` checks none: it marks a
* call site whose hold does not yet take the motion that the test judges.
*/
export type HoldJudges = JudgedMotion | readonly JudgedMotion[] | 'count-only';
/** What a hold must take (`holdAnimations`). */
export interface HoldOptions {
readonly judges: HoldJudges;
}
/** How an armed hold waits (`armHold`), and what it must take. */
export interface ArmHoldOptions extends HoldOptions {
readonly count?: number;
readonly minProgressMs?: number;
readonly newOnly?: boolean;
readonly timeout?: number;
}
/** Keys each hold's record of what it took, for the judged-motion check. */
let holdKeys = 0;
/**
* The judged motions as a list: empty for `'count-only'`. Throws when the
* caller names none.
*/
function judgedMotions(
caller: string,
judges: HoldJudges | undefined,
): readonly JudgedMotion[] {
if (judges == null) {
throw new Error(
`${caller}: name the motion that the test judges ({judges: {target, property}}). Other animations can be what the hold takes while that motion does not run. Pass 'count-only' only for a call site that does not hold its judged motion yet.`,
);
}
return judges === 'count-only' ? [] : 'target' in judges ? [judges] : judges;
}
/**
* 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.
*
* `judges` names the motion that the test reads from the hold. Other
* animations under the scope (a press, a colour change) can meet the count
* before that motion starts, and a hold that took only them proves nothing
* about it. So `held()` also rejects when the hold took no animation of
* each judged motion.
*
* @example
* ```
* const hold = await armHold(page, row, {
* judges: {target: row, property: 'opacity'},
* });
* await driver.play(tap(center, {holdMs: 400}));
* const [release] = await hold.held();
* ```
*/
export async function armHold(
page: Page,
scope: Locator | undefined,
options: ArmHoldOptions,
): Promise<ArmedHold> {
const {
judges,
count = 1,
minProgressMs = 0,
newOnly = false,
timeout = 5_000,
} = options ?? ({} as Partial<ArmHoldOptions>);
const motions = judgedMotions('armHold', judges);
const scopeHandle = await scopeElement('armHold', scope);
await installCurveEnd(page);
holdKeys += 1;
const id = holdKeys;
await page.evaluate(
([root, needed, minProgress, fresh, wait, key, judged]) => {
const w = window as unknown as {
__harnessHold: (
root: Element | null,
skip?: ReadonlySet<Animation>,
) => unknown[];
__harnessHeld?: Animation[];
__harnessTimerGate?: {
frame?: typeof requestAnimationFrame;
now?: () => number;
timeout?: typeof setTimeout;
};
__harnessArmed?: Record<number, Promise<unknown[]>>;
__harnessTook?: Record<number, Animation[]>;
};
// 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);
// The deadline reads the real clock, which a page freeze does not stop.
const realNow = w.__harnessTimerGate?.now ?? (() => performance.now());
const deadline = realNow() + 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 {
const took = w.__harnessHold(root, before);
// The hold appends what it took to the held set. `held()` reads
// these animations to find the judged motions.
if (judged && took.length > 0) {
w.__harnessTook = {
...w.__harnessTook,
[key]: (w.__harnessHeld ?? []).slice(-took.length),
};
}
resolve(took);
} catch (error) {
reject(error);
}
} else if (realNow() > 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,
motions.length > 0,
] as const,
);
return {
held: async () => {
const held = await page.evaluate(key => {
const w = window as unknown as {
__harnessArmed?: Record<number, Promise<HeldAnimation[]>>;
};
const armed = w.__harnessArmed?.[key];
if (armed == null) {
throw new Error('armHold: this hold was never armed on this page');
}
delete w.__harnessArmed?.[key];
return armed;
}, id);
await expectJudgedMotionsHeld(page, id, motions, {
caller: 'armHold',
cause: `Other animations met its count of ${Math.max(count, 1)} first`,
remedy:
'Arm the hold so that it waits for the judged motion (count, newOnly, minProgressMs, scope).',
});
return held;
},
};
}
/**
* Throws unless the hold `key` took an animation of each judged motion. The
* targets resolve only now: the action that an armed hold waits for can add
* them to the page. `cause` and `remedy` complete the error for the caller.
*/
async function expectJudgedMotionsHeld(
page: Page,
key: number,
motions: readonly JudgedMotion[],
failure: {caller: string; cause: string; remedy: string},
): Promise<void> {
if (motions.length === 0) {
return;
}
const targets = await Promise.all(
motions.map(motion =>
motion.target.elementHandle({timeout: TARGET_WAIT_MS}).catch(() => {
throw new Error(
`${failure.caller}: the judged target ${motion.target.toString()} is not on the page`,
);
}),
),
);
const {missing, took} = await page.evaluate(
([armed, elements, wanted]) => {
const w = window as unknown as {
__harnessTook?: Record<number, Animation[]>;
__harnessHeldJudged?: {animation: Animation; motion: string}[];
__harnessAnimatedProperties: (animation: Animation) => string[];
__harnessAnimates: (animation: Animation, property: string) => boolean;
};
const animations = w.__harnessTook?.[armed] ?? [];
delete w.__harnessTook?.[armed];
const nameOf = (animation: Animation) => {
const effect = animation.effect as KeyframeEffect | null;
const target = effect?.target ?? null;
const name =
target == null
? 'no target'
: target.tagName.toLowerCase() +
(target.id ? `#${target.id}` : '') +
(target.classList.length
? `.${[...target.classList].slice(0, 2).join('.')}`
: '');
return `${name}${effect?.pseudoElement ?? ''}`;
};
const describe = (animation: Animation) =>
`${nameOf(animation)} ${w.__harnessAnimatedProperties(animation).join(' ')}`;
const runs = wanted.map((motion, index) =>
animations.filter(animation => {
const effect = animation.effect as KeyframeEffect | null;
return (
effect != null &&
effect.target === elements[index] &&
(effect.pseudoElement ?? null) === motion.pseudoElement &&
w.__harnessAnimates(animation, motion.property)
);
}),
);
// A seek or a sample fails by name once the page cancels one of these.
w.__harnessHeldJudged = [
...(w.__harnessHeldJudged ?? []),
...runs.flatMap((found, index) =>
found.map(animation => ({
animation,
motion: `${wanted[index].property} on ${nameOf(animation)}`,
})),
),
];
return {
missing: runs.flatMap((found, index) =>
found.length > 0 ? [] : [index],
),
took: animations.map(describe),
};
},
[
key,
targets,
motions.map(motion => ({
property: motion.property,
pseudoElement: motion.pseudoElement ?? null,
})),
] as const,
);
if (missing.length > 0) {
const judged = missing
.map(index => {
const motion = motions[index];
return `${motion.property} on ${motion.target.toString()}${motion.pseudoElement ?? ''}`;
})
.join(', ');
throw new Error(
`${failure.caller}: the hold took no animation of the judged motion (${judged}). ` +
`${failure.cause}; it took: ` +
`${took.length > 0 ? took.join('; ') : 'nothing'}. ` +
failure.remedy,
);
}
}
/**
* Moves every held animation to `timeMs` from the held origin (delay
* included): each to its own `timeMs - offsetMs`. A time at or past an
* animation's end is clamped to END_INSET_MS before it: an animation without
* `fill` stops applying its effect exactly at the end, and the frame wanted
* there is the last one it presents. (Half a millisecond, not less: engines
* round `currentTime` writes to their timer resolution.) Returns the time the
* page then presents: `timeMs`, or the latest clamped end when every held
* animation was clamped.
* It throws when the page has cancelled a judged motion's held run since the
* hold.
*/
export async function seekAnimations(
page: Page,
timeMs: number,
): Promise<number> {
return page.evaluate(
({t, inset}) => {
const w = window as unknown as {
__harnessHeld?: Animation[];
__harnessHeldStarts?: number[];
__harnessHeldOrigin?: number;
__harnessHeldJudged?: {animation: Animation; motion: string}[];
};
const cancelled = (w.__harnessHeldJudged ?? []).filter(
run => run.animation.playState === 'idle',
);
if (cancelled.length > 0) {
throw new Error(
`seekAnimations: the page cancelled the held run of a judged motion (${[...new Set(cancelled.map(run => run.motion))].join(', ')}) since the hold. A later style change retargeted it, so a read now shows a run that the hold did not take`,
);
}
// An animation the page cancelled since the hold (a CSS transition is
// cancelled whenever the page retargets its property) leaves the held set:
// applying or playing it again would revive what the page dropped.
const kept = (w.__harnessHeld ?? []).flatMap((animation, index) =>
animation.playState === 'idle'
? []
: [{animation, start: (w.__harnessHeldStarts ?? [])[index] ?? 0}],
);
w.__harnessHeld = kept.map(k => k.animation);
w.__harnessHeldStarts = kept.map(k => k.start);
const origin = w.__harnessHeldOrigin ?? 0;
let presented = -Infinity;
kept.forEach(({animation, start}) => {
const offset = start - origin;
const end = Number(
animation.effect?.getComputedTiming().endTime ?? Infinity,
);
// A faster rate runs more curve per timeline ms.
const rate = animation.playbackRate || 1;
const local = Math.min((t - offset) * rate, end - inset);
animation.currentTime = local;
presented = Math.max(presented, local / rate + offset);
});
return Number.isFinite(presented) ? presented : t;
},
{t: timeMs, inset: END_INSET_MS},
);
}
/**
* Resumes (default) or finishes every held animation: only those
* `holdAnimations` paused, so an animation the page paused stays paused. An
* animation that repeats forever has no end to finish at, so `finish`
* resumes it instead. The held set is cleared even if one throws.
*/
export async function releaseAnimations(
page: Page,
{finish = false}: {finish?: boolean} = {},
): Promise<void> {
await page.evaluate(shouldFinish => {
const w = window as unknown as {
__harnessHeld?: Animation[];
__harnessHeldStarts?: number[];
__harnessHeldOrigin?: number;
__harnessHeldJudged?: {animation: Animation; motion: string}[];
};
// An animation the page cancelled since the hold (a CSS transition is
// cancelled whenever the page retargets its property) leaves the held set:
// applying or playing it again would revive what the page dropped.
const kept = (w.__harnessHeld ?? []).flatMap((animation, index) =>
animation.playState === 'idle'
? []
: [{animation, start: (w.__harnessHeldStarts ?? [])[index] ?? 0}],
);
w.__harnessHeld = kept.map(k => k.animation);
w.__harnessHeldStarts = kept.map(k => k.start);
try {
for (const {animation} of kept) {
const end = Number(
animation.effect?.getComputedTiming().endTime ?? Infinity,
);
if (shouldFinish && Number.isFinite(end)) {
animation.finish();
} else {
animation.play();
}
}
} finally {
w.__harnessHeld = [];
w.__harnessHeldStarts = [];
w.__harnessHeldOrigin = undefined;
w.__harnessHeldJudged = [];
}
}, finish);
}
export interface CurveSample {
/** The requested time. */
readonly t: number;
/**
* The time the sampled element presents: `t`, or just inside the end of
* its own animations when the sample was taken at or past it (see
* `seekAnimations`). Read from the element's own animations only (from
* every held one if none targets it); when sampling a pseudo-element, from
* that pseudo-element's.
*/
readonly presentedAt: number;
/**
* The same per channel group, from the element's animations of those
* properties: a 300 ms move beside a 400 ms fade on one element is read
* just inside 300 ms for the transform and at the requested time for the
* opacity. `curveOf` reads oracles here.
*/
readonly presentedAtFor: {
readonly transform: number;
readonly opacity: number;
};
/**
* The presented 2D transform: `translate` · `rotate` · `scale` ·
* `transform`, composed in the order CSS applies them.
*/
readonly transform: Transform2D;
readonly opacity: number;
/** Raw computed values, for the JSON trace. */
readonly raw: {
readonly transform: string;
readonly translate: string;
readonly rotate: string;
readonly scale: string;
readonly opacity: string;
};
}
/**
* The presented transform and opacity of `locator` at each time (ms from the
* held origin, as for `seekAnimations`). Hold the animations first. An animation of the
* individual `translate`, `rotate` or `scale` properties is included: they
* are composed with `transform` into one matrix.
*
* `pseudoElement` samples the element's `::before` or `::after` instead:
* its presented values, labelled by its own animations (those whose effect
* targets the element with that pseudo-element), as a component that animates
* a pseudo-element (`element.animate(keyframes, {pseudoElement})`) draws it.
*/
export async function sampleCurve(
locator: Locator,
times: readonly number[],
{pseudoElement}: {pseudoElement?: '::before' | '::after'} = {},
): Promise<CurveSample[]> {
const raw = await locator.evaluate(
(element, {ts, inset, pseudo}) => {
const w = window as unknown as {
__harnessHeld?: Animation[];
__harnessHeldStarts?: number[];
__harnessHeldOrigin?: number;
__harnessHeldJudged?: {animation: Animation; motion: string}[];
};
const cancelled = (w.__harnessHeldJudged ?? []).filter(
run => run.animation.playState === 'idle',
);
if (cancelled.length > 0) {
throw new Error(
`sampleCurve: the page cancelled the held run of a judged motion (${[...new Set(cancelled.map(run => run.motion))].join(', ')}) since the hold. A later style change retargeted it, so a read now shows a run that the hold did not take`,
);
}
// An animation the page cancelled since the hold (a CSS transition is
// cancelled whenever the page retargets its property) leaves the held set:
// applying or playing it again would revive what the page dropped.
const kept = (w.__harnessHeld ?? []).flatMap((animation, index) =>
animation.playState === 'idle'
? []
: [{animation, start: (w.__harnessHeldStarts ?? [])[index] ?? 0}],
);
w.__harnessHeld = kept.map(k => k.animation);
w.__harnessHeldStarts = kept.map(k => k.start);
const held = kept.map(k => k.animation);
const origin = w.__harnessHeldOrigin ?? 0;
if (held.length === 0) {
throw new Error(
'sampleCurve: no held animations (call holdAnimations first)',
);
}
// The properties each held animation of the sampled box animates: the
// element's own, or its pseudo-element's when one is sampled. Another
// box's animation (the element's `::before` when the element is
// sampled) is not its own: its clock would label the samples with
// another box's time.
const own = held.map(animation => {
const effect = animation.effect as KeyframeEffect | null;
if (
effect?.target !== element ||
(effect.pseudoElement ?? null) !== pseudo
) {
return null;
}
const properties = new Set<string>();
for (const keyframe of effect.getKeyframes()) {
for (const key of Object.keys(keyframe)) {
properties.add(key);
}
}
return properties;
});
const TRANSFORM = ['transform', 'translate', 'rotate', 'scale'];
return ts.map(t => {
let presented = -Infinity;
let presentedOwn = -Infinity;
let presentedTransform = -Infinity;
let presentedOpacity = -Infinity;
held.forEach((animation, index) => {
// Each at its own offset, just inside its end: see seekAnimations.
const offset = kept[index].start - origin;
const end = Number(
animation.effect?.getComputedTiming().endTime ?? Infinity,
);
// A faster rate runs more curve per timeline ms.
const rate = animation.playbackRate || 1;
const local = Math.min((t - offset) * rate, end - inset);
animation.currentTime = local;
presented = Math.max(presented, local / rate + offset);
const properties = own[index];
if (properties == null) {
return;
}
presentedOwn = Math.max(presentedOwn, local / rate + offset);
if (TRANSFORM.some(p => properties.has(p))) {
presentedTransform = Math.max(
presentedTransform,
local / rate + offset,
);
}
if (properties.has('opacity')) {
presentedOpacity = Math.max(
presentedOpacity,
local / rate + offset,
);
}
});
const or = (value: number, fallback: number) =>
Number.isFinite(value) ? value : fallback;
const presentedAt = or(presentedOwn, or(presented, t));
const style =
pseudo == null
? getComputedStyle(element)
: getComputedStyle(element, pseudo);
// translate · rotate · scale · transform, as CSS applies them (all
// about the same transform origin, which `transform` excludes too).
// A percentage resolves against the border box, unrounded
// (`offsetWidth` rounds it); anything else it cannot resolve (a
// `calc()`) is an error, not a guess.
const px = (value: string) => parseFloat(value) || 0;
const borderBox =
style.boxSizing === 'border-box'
? {width: px(style.width), height: px(style.height)}
: {
width:
px(style.width) +
px(style.paddingLeft) +
px(style.paddingRight) +
px(style.borderLeftWidth) +
px(style.borderRightWidth),
height:
px(style.height) +
px(style.paddingTop) +
px(style.paddingBottom) +
px(style.borderTopWidth) +
px(style.borderBottomWidth),
};
const length = (value: string, size: number) => {
const match = /^(-?[\d.]+(?:e-?\d+)?)(px|%)$/.exec(value);
if (match == null) {
throw new Error(
`sampleCurve: cannot resolve translate ${JSON.stringify(style.translate)}`,
);
}
const amount = Number(match[1]);
return match[2] === '%' ? (amount / 100) * size : amount;
};
const matrix = new DOMMatrix();
if (style.translate !== 'none') {
// "x", "x y" or "x y z"; a calc() holds spaces, so split at the
// top level only.
const parts = style.translate.match(/(?:calc\([^)]*\)|\S)+/g) ?? [];
const [x = '0px', y = '0px'] = parts;
matrix.translateSelf(
length(x, borderBox.width),
length(y, borderBox.height),
);
}
if (style.rotate !== 'none') {
// "45deg", "x 45deg" (or y, z) or "1 0 0 45deg": the angle is the
// last token, the axis what comes before it (z when none).
const tokens = style.rotate.split(' ');
const angle = tokens.at(-1) ?? '0deg';
const turns: Record<string, number> = {
deg: 1,
rad: 180 / Math.PI,
grad: 0.9,
turn: 360,
};
const unit = /[a-z]+$/.exec(angle)?.[0] ?? 'deg';
const named: Record<string, [number, number, number]> = {
x: [1, 0, 0],
y: [0, 1, 0],
z: [0, 0, 1],
};
const axis: [number, number, number] =
tokens.length === 1
? [0, 0, 1]
: tokens.length === 2 && named[tokens[0]] != null
? named[tokens[0]]
: tokens.length === 4
? [Number(tokens[0]), Number(tokens[1]), Number(tokens[2])]
: [Number.NaN, Number.NaN, Number.NaN];
if (!axis.every(Number.isFinite)) {
throw new Error(
`sampleCurve: cannot resolve rotate ${JSON.stringify(style.rotate)}`,
);
}
matrix.rotateAxisAngleSelf(
...axis,
parseFloat(angle) * (turns[unit] ?? 1),
);
}
if (style.scale !== 'none') {
const [sx = 1, sy = sx] = style.scale.split(' ').map(Number);
matrix.scaleSelf(sx, sy);
}
if (style.transform !== 'none') {
matrix.multiplySelf(new DOMMatrix(style.transform));
}
const {a, b, c, d, e, f} = matrix;
return {
t,
presentedAt,
presentedAtFor: {
transform: or(presentedTransform, presentedAt),
opacity: or(presentedOpacity, presentedAt),
},
matrix: `matrix(${a}, ${b}, ${c}, ${d}, ${e}, ${f})`,
transform: style.transform,
translate: style.translate,
rotate: style.rotate,
scale: style.scale,
opacity: style.opacity,
};
});
},
{ts: [...times], inset: END_INSET_MS, pseudo: pseudoElement ?? null},
);
return raw.map(r => ({
t: r.t,
presentedAt: r.presentedAt,
presentedAtFor: r.presentedAtFor,
transform: parseTransform(r.matrix),
opacity: Number(r.opacity),
raw: {
transform: r.transform,
translate: r.translate,
rotate: r.rotate,
scale: r.scale,
opacity: r.opacity,
},
}));
}
export type Channel =
'translateX' | 'translateY' | 'scaleX' | 'scaleY' | 'rotate' | 'opacity';
/** One channel of a sampled curve, ready for `compareCurve`. */
export function curveOf(
samples: readonly CurveSample[],
channel: Channel,
): TimedValue[] {
return samples.map(s => ({
t:
channel === 'opacity'
? s.presentedAtFor.opacity
: s.presentedAtFor.transform,
value: channel === 'opacity' ? s.opacity : s.transform[channel],
}));
}
export interface ActiveAnimation {
readonly kind: string;
readonly name: string | null;
/**
* Epoch ms (page clock) when the animation's curve starts and ends. A held
* end value (see `HeldAnimation.curveEndMs`, which says when one is read)
* is not part of the curve. A finished run is dated from its start as the
* engine had it when it finished.
*/
readonly from: number;
readonly to: number;
readonly durationMs: number;
readonly easing: string;
readonly keyframes: readonly Record<string, unknown>[];
/**
* Epoch ms (page clock) when it finished, if it had already finished when
* it was reported (where its start put its end, by the engine's clock, not
* when the finish event arrived); null while it runs. A run that the page
* cancelled while it played reports when the page cancelled it, which can
* be before `to`.
*/
readonly finishedAt: number | null;
}
/**
* Runs `fn` on `locator`'s element: through the locator, or, `quietly`,
* through a handle to the element it matches now (none yet: `[]`). Each
* locator.evaluate makes a main-thread frame, which a trace counts;
* `elementHandles()` and a handle's evaluate make none.
*/
async function readElement<A, R>(
locator: Locator,
quietly: boolean,
fn: (element: Element, arg: A) => R[],
arg: A,
timeout: number,
): Promise<R[]> {
const run = fn as unknown as (element: Element, arg: unknown) => R[];
if (!quietly) {
return locator.evaluate(run, arg as unknown, {timeout});
}
const handles = await locator.elementHandles();
try {
if (handles.length > 1) {
throw new Error(
`waitForAnimation: ${String(locator)} matches ${handles.length} elements`,
);
}
return handles.length === 0
? []
: await handles[0].evaluate(run, arg as unknown);
} finally {
await Promise.all(handles.map(handle => handle.dispose()));
}
}
/** The rejection for a wait whose element is not in the document. */
function notInDocument(name: string, cause?: unknown): Error {
return new Error(
`${name}: the element is not in the document. An exit that removes ` +
'its element is read through its container (watch the parent).',
cause === undefined ? undefined : {cause},
);
}
/**
* Runs a locator read within the wait's own deadline. A locator waits for
* its element with no timeout of its own, so one the page removed (an exit
* at its end) or never mounted would hold the wait to the test's timeout;
* this turns that into the wait's own rejection. A read that runs out of time
* on an element still present returns null: the caller's own deadline
* message applies.
*/
async function withinTimeout<T>(
name: string,
locator: Locator,
deadline: number,
read: (timeout: number) => Promise<T>,
): Promise<T | null> {
try {
return await read(Math.max(1, deadline - Date.now()));
} catch (error) {
if ((error as Error | null)?.name === 'TimeoutError') {
if ((await locator.count()) > 0) {
return null;
}
throw notInDocument(name, error);
}
throw error;
}
}
/**
* Waits until an animation is running on `locator`'s element (or inside it)
* and has presented `minProgressMs` of its curve (after any delay), and
* returns its active
* interval on the page clock. Use it before blocking the main thread: an
* animation that has not started yet cannot start while the thread is blocked.
*
* It does not race a short animation: the page records every animation from
* its first frame (from the first call into this module on the page: this,
* `waitForRest`, `watchAnimations`, sampling or holding), so one that started
* after the last `waitForRest`, `waitForAnimation` or `watchAnimations` and has already
* finished is reported too, with `finishedAt` set. So is one that the page
* cancelled while it played, once it presented `minProgressMs`. Core's motion
* animator retires each run so, at the end of its curve. For an action that
* may be the page's first contact with this module, take
* `watchAnimations(locator)` before the action instead.
*
* In WebKit a CSS animation shorter than a gap between two of the page's
* frames can start and finish inside it: its start event comes at the next
* frame, when nothing is left to record, and the wait's error names it (a
* starved page's frames can come a second apart).
*
* A run going backward is read when it was reversed before it started. The
* recorder keeps one entry per `Animation` object, so an animation reversed
* or replayed mid-run is misread: a watch taken before the reversal rejects,
* and an unwatched wait returns at once with a curve dated before it.
*
* Started inside a `traceRendering` body, it stands down as the recorder
* does, so it adds no frame the trace counts: it takes the element's
* animations from the recorder's log, judges a started one by its own times,
* and reaches the element through a handle to what the locator matches at
* each look. That holds for script animations and CSS transitions. On a CSS
* `@keyframes` animation (and, unwatched, a cancelled CSS transition) it reads
* the animation's timing, which flushes its style and adds Layouts to the
* trace: wait on one with `waitForRest`, or after the trace.
*/
export async function waitForAnimation(
locator: Locator,
{
timeout = 5_000,
minProgressMs = 1,
since,
}: {
timeout?: number;
minProgressMs?: number;
/** Page-clock ms (performance.now): only animations first seen after it. */
since?: number;
} = {},
): Promise<ActiveAnimation[]> {
const deadline = Date.now() + timeout;
const page = locator.page();
await installCurveEnd(page);
// Inside a rendering trace the wait stands down (see the page function),
// and it reads the element through handles: each locator.evaluate makes a
// main-thread frame (a Layout of an anchored element), where a handle's
// evaluate adds none.
const traced = await page.evaluate(
() =>
(window as unknown as {__harnessRenderingTrace?: boolean})
.__harnessRenderingTrace === true,
);
for (;;) {
const read = await withinTimeout(
'waitForAnimation',
locator,
deadline,
evaluateTimeout =>
readElement(
locator,
traced,
(element, {minProgress, since: watchedFrom}) => {
// The harness's own read: a trace sets it apart (trace.ts HARNESS_READ).
console.timeStamp('harness-read');
const w = window as unknown as {
__harnessCurveEnd: (a: Animation) => number;
__harnessTiming: (
effect: AnimationEffect | null | undefined,
) => ComputedEffectTiming | null;
__harnessAnimations: {
log: {
animation: Animation;
seenAt: number;
finishedAt: number | null;
startedAt: number | null;
finishStart: number | null;
cancelledAt: number | null;
playedMs: number | null;
ancestors: Element[];
}[];
record: () => void;
armedAt: () => number;
};
};
const curveEnd = w.__harnessCurveEnd;
const recorder = w.__harnessAnimations;
// Inside a rendering trace the wait stands down as the recorder does:
// record() reads nothing, the animations come from the recorder's log
// rather than getAnimations(), and a started one runs by its own
// times, since playState flushes a CSS animation's style.
const traced =
(window as unknown as {__harnessRenderingTrace?: boolean})
.__harnessRenderingTrace === true;
recorder.record();
// The recorder keeps real times. A live start time is a page time.
// It trails real time by the span a page freeze stood still, so it
// takes that span as it stands now. The stamps then share the trace's
// clock.
const span =
(window as unknown as {__harnessFreeze?: {offset: number}})
.__harnessFreeze?.offset ?? 0;
const describe = (
a: Animation,
finishedAt: number | null,
recordedStart: number | null,
finishStart: number | null = null,
) => {
const effect = a.effect as KeyframeEffect | null;
const timing = w.__harnessTiming(effect);
// A finished run is dated from its start as its finish recorded
// it: a later startTime read can say otherwise. The recorded
// start stands in once the page has cancelled it. A run going
// backward began at its end: its startTime is where its current
// time would reach 0, a whole run later.
const rate = a.playbackRate;
const speed = Math.abs(rate || 1);
const endTime = Number(timing?.endTime ?? 0);
const delay = Number(timing?.delay ?? 0);
const start =
finishStart != null
? finishStart
: a.startTime == null
? recordedStart
: span +
(rate < 0
? Number(a.startTime) - endTime / speed
: Number(a.startTime));
const startedAt =
performance.timeOrigin + Number(start ?? Number.NaN);
const name =
'transitionProperty' in a
? (a as unknown as {transitionProperty: string})
.transitionProperty
: 'animationName' in a
? (a as unknown as {animationName: string}).animationName
: null;
return {
kind: a.constructor.name,
name,
// Through the playback rate's speed: at rate 2 a curve runs in half
// its duration. Backward, the end delay plays first and the start
// delay last.
from:
rate < 0
? startedAt + Number(timing?.endDelay ?? 0) / speed
: startedAt + delay / speed,
to:
rate < 0
? startedAt + (endTime - delay) / speed
: startedAt + curveEnd(a) / speed,
durationMs: Number(timing?.duration ?? 0),
easing: String(effect?.getTiming().easing ?? 'linear'),
keyframes: (effect?.getKeyframes() ?? []).map(
(k): Record<string, unknown> => ({...k}),
),
finishedAt:
finishedAt == null
? null
: performance.timeOrigin + finishedAt,
};
};
const inside = (a: Animation) => {
const target =
(a.effect as KeyframeEffect | null)?.target ?? null;
return (
target != null &&
(target === element || element.contains(target))
);
};
// The busy-window control (busy.ts) animates on its own, inside a
// dialog with `within`: it never answers for the component.
const isControl = (a: Animation) => {
const target =
(a.effect as KeyframeEffect | null)?.target ?? null;
return (
target instanceof Element &&
target.closest('[data-harness-control]') != null
);
};
const after = watchedFrom ?? recorder.armedAt();
// Document-timeline animations only, as for holdAnimations: a scroll-
// or view-timeline one that reached its end is not a finished curve.
const recorded = recorder.log.filter(
e =>
e.seenAt >= after &&
!isControl(e.animation) &&
(inside(e.animation) || e.ancestors.includes(element)) &&
e.animation.timeline instanceof DocumentTimeline,
);
// Running: since the watch, or (without one) any on the element. A
// pending one (no start time yet) counts too: the action's animation
// may still be pending at the first look, and an earlier one that
// finished must not answer for it. Only document-timeline animations
// count, as for holdAnimations: a scroll- or view-timeline one moves
// only when something scrolls and never progresses on its own.
const runs = (a: Animation) => {
if (!(a.timeline instanceof DocumentTimeline)) {
return false;
}
if (!traced || a.startTime == null) {
return a.playState === 'running';
}
const time = Number(a.currentTime ?? 0);
return a.playbackRate < 0
? time > 0
: time < Number(w.__harnessTiming(a.effect)?.endTime ?? 0);
};
const onElement = () =>
recorder.log.filter(
e => inside(e.animation) || e.ancestors.includes(element),
);
const live = (
watchedFrom == null && !traced
? element.getAnimations({subtree: true})
: (watchedFrom == null ? onElement() : recorded)
.filter(e => e.finishedAt == null)
.map(e => e.animation)
).filter(a => !isControl(a) && runs(a));
const running = live.filter(a => a.startTime != null);
// Progress along the curve, on the timeline: a delay presents nothing
// (going backward, the end delay plays first), a run going backward
// (`reverse()`) progresses from its end, and a faster rate presents
// more curve per ms.
const progressed = running.filter(a => {
const timing = w.__harnessTiming(a.effect);
const time = Number(a.currentTime ?? 0);
const local =
a.playbackRate < 0
? Number(timing?.endTime ?? 0) -
Number(timing?.endDelay ?? 0) -
time
: time - Number(timing?.delay ?? 0);
return local / Math.abs(a.playbackRate || 1) >= minProgress;
});
if (progressed.length > 0) {
return progressed.map(a => describe(a, null, null));
}
if (live.length > 0) {
return [];
}
// Finished: as its finish event recorded it (where its start then put
// its end), or by its state when the event has not been delivered yet
// (then at its scheduled end, through the rate's speed; a run going
// backward ends at its startTime, where its current time reaches 0).
const finishedAt = (e: (typeof recorded)[number]) => {
if (e.finishedAt != null) {
return e.finishedAt;
}
// The page cancelled it while it played: it ended there, once
// it presented `minProgress` of its curve.
if (e.cancelledAt != null) {
return (e.playedMs ?? 0) >= minProgress ? e.cancelledAt : null;
}
const a = e.animation;
if (a.startTime == null) {
return null;
}
const end = Number(w.__harnessTiming(a.effect)?.endTime ?? 0);
// Traced, by its own times; otherwise by its state.
const time = Number(a.currentTime ?? 0);
const done = traced
? a.playbackRate < 0
? time <= 0
: time >= end
: a.playState === 'finished';
if (!done) {
return null;
}
return (
span +
(a.playbackRate < 0
? Number(a.startTime)
: Number(a.startTime) + end / Math.abs(a.playbackRate || 1))
);
};
return recorded
.filter(e => finishedAt(e) != null)
.map(e =>
describe(
e.animation,
finishedAt(e),
e.startedAt,
e.finishStart,
),
);
},
{minProgress: minProgressMs, since: since ?? null},
evaluateTimeout,
),
);
const found = read ?? [];
if (found.length > 0) {
await armRecorder(locator.page());
return found;
}
if (Date.now() > deadline) {
// A traced read goes through handles, which find no element rather
// than wait for one: a missing element is reported as missing, as the
// untraced read reports it.
if (traced && (await locator.count()) === 0) {
throw notInDocument('waitForAnimation');
}
// Start events on the element that found nothing to read: animations
// that started and finished between two of the page's frames.
const missed = await locator
.evaluate(
(element, watchedFrom) => {
const recorder = (
window as unknown as {
__harnessAnimations: {
unread: {
at: number;
ancestors: Element[];
name: string;
}[];
armedAt: () => number;
};
}
).__harnessAnimations;
const after = watchedFrom ?? recorder.armedAt();
// Matched through the ancestors kept at the event, as the log is:
// an exit the page removed is still named for its container. A
// missed transition sends two start events; it is named once.
return [
...new Set(
recorder.unread
.filter(u => u.at >= after && u.ancestors.includes(element))
.map(u => u.name),
),
];
},
since ?? null,
{timeout: 1_000},
)
.catch(() => [] as string[]);
throw new Error(
missed.length > 0
? `waitForAnimation: the element's ${missed.join(', ')} started and finished between two of the page's frames: its start event came after it had finished, with nothing left to read (WebKit sends it at the next frame; README: engine limits). Make the animation last longer than the page's frame gaps under load.`
: 'waitForAnimation: no animation started on the element, none running ' +
'and none recorded since the last wait. If the action is the ' +
"page's first contact with the harness, take " +
'watchAnimations(locator) before it.',
);
}
await new Promise(resolve => setTimeout(resolve, 4));
}
}
/**
* Empties the page's animation log, so a count taken next (heap size, event
* listeners, DOM nodes) reads the page's own objects and not the animations,
* elements and ancestors the recorder kept. Waits after it record afresh; a
* page the recorder never ran on is left alone.
*/
export async function releaseAnimationLog(page: Page): Promise<void> {
await page.evaluate(() =>
(
window as unknown as {__harnessAnimations?: {release: () => void}}
).__harnessAnimations?.release(),
);
}
/**
* Marks now as the point later waits count animations from. With a locator,
* its element's pending style change is resolved first, also inside a trace
* (reached through a handle, which adds no main-thread frame).
*/
async function armRecorder(page: Page, locator?: Locator): Promise<number> {
const handles = locator == null ? [] : await locator.elementHandles();
try {
if (handles.length === 1) {
return await handles[0].evaluate(element =>
(
window as unknown as {
__harnessAnimations: {arm: (element?: Element) => number};
}
).__harnessAnimations.arm(element as Element),
);
}
return await page.evaluate(() =>
(
window as unknown as {__harnessAnimations: {arm: () => number}}
).__harnessAnimations.arm(),
);
} finally {
await Promise.all(handles.map(handle => handle.dispose()));
}
}
export interface AnimationWatch {
/**
* Resolves with the animations on the element that started after the watch
* was taken: running ones once they have presented `minProgressMs`, or,
* when none runs, those that already finished.
*/
started(options?: {
timeout?: number;
minProgressMs?: number;
}): Promise<ActiveAnimation[]>;
}
/**
* Starts watching `locator`'s element before an action, so the animation the
* action starts is caught even when it ends before the test looks (a short
* entrance on a cold page). Taking the watch reads the element's animations,
* which restyles it, inside a rendering trace too: take a traced watch before
* the window the proof counts:
*
* const watch = await watchAnimations(sheet);
* await driver.play(tap(button));
* const [entrance] = await watch.started();
*/
export async function watchAnimations(
locator: Locator,
): Promise<AnimationWatch> {
await installCurveEnd(locator.page());
const since = await armRecorder(locator.page(), locator);
return {
started: options => waitForAnimation(locator, {...options, since}),
};
}
/**
* Resolves once `locator`'s element is at rest: no animation on it (or inside
* it) is pending or still before the end of its curve, and its presented
* `transform`, `translate`, `rotate`, `scale` and `opacity` (and `::backdrop`
* opacity) have held still for `frames` consecutive frames.
*
* It judges curves and presented values, not `playState`: an animation that
* holds its end value (a run of identical final keyframes kept so a later
* interruption can read it) still reports `running` while nothing moves.
* A hold is read as such only where `HeldAnimation.curveEndMs` reads it (a
* forward run under a linear or cubic-bézier effect easing); under any other
* easing or direction, waitForRest waits the hold out, and a hold longer than
* `timeout` rejects with "still moving".
*
* It throws `FrameStarvationError` instead when the page drew too few frames
* to tell. Then, since the element last moved, no frame came for longer than
* `FRAME_STARVATION_MS`. It held still in its last frame, or no frame came
* after the deadline. So the still frames must come by `timeout` plus
* `FRAME_STARVATION_MS`.
*
* While a rendering trace runs (`traceRendering`), it stands down as the
* animation recorder does: a per-frame callback would make every frame a
* main-thread frame, which the trace counts. It then waits on timers for the
* scheduled ends of the curves on the element instead (a run going backward,
* until it finishes), so motion that no animation drives (a script writing
* styles) is not seen until the trace ends. Its one read of the element's
* animations, as it is called, restyles the element (and lays out an anchored
* one) when an animation is already running there: await it right after the
* action that starts the motion, before the window a proof counts, not in its
* middle (README: No Layout / Paint). Finding no animation, it looks again `frames` times a frame
* apart before settling, so one the action starts a few frames later is
* waited for.
*/
export async function waitForRest(
locator: Locator,
{timeout = 5_000, frames = 3}: {timeout?: number; frames?: number} = {},
): Promise<void> {
await installCurveEnd(locator.page());
// The page-side wait rejects at its own deadline; the read gets a second
// more, so only an element that is gone runs it out.
const rested = await withinTimeout(
'waitForRest',
locator,
Date.now() + timeout + 1_000,
async evaluateTimeout => {
const starved = await locator.evaluate(
(element, {ms, need, starvationMs}) =>
new Promise<{
frames: number;
spanMs: number;
longestGapMs: number;
} | null>((resolve, reject) => {
// The deadline reads the real clock, which a page freeze does not
// stop.
const realNow =
(
window as unknown as {
__harnessTimerGate?: {now?: () => number};
}
).__harnessTimerGate?.now ?? (() => performance.now());
const deadline = realNow() + ms;
const curveEnd = (
window as unknown as {__harnessCurveEnd: (a: Animation) => number}
).__harnessCurveEnd;
const read = () => {
const style = getComputedStyle(element);
const backdrop = getComputedStyle(element, '::backdrop').opacity;
return [
style.transform,
style.translate,
style.rotate,
style.scale,
style.opacity,
backdrop,
].join(' | ');
};
// The page's real frames and timers, even while a timer gate holds
// its callbacks: a frozen gate never holds the wait itself.
const gate = (
window as unknown as {
__harnessTimerGate?: {
frame: typeof requestAnimationFrame;
timeout?: typeof setTimeout;
clearTimeout?: typeof clearTimeout;
};
}
).__harnessTimerGate;
const frame = gate?.frame ?? requestAnimationFrame;
const timeout = gate?.timeout ?? setTimeout;
const clearTimer = gate?.clearTimeout ?? clearTimeout;
// Set by traceRendering while it traces (see the recorder above).
const tracing = () =>
(window as unknown as {__harnessRenderingTrace?: boolean})
.__harnessRenderingTrace === true;
// The deadline timer below holds this wait's scope, the element
// too, until it fires: every ending clears it.
const end = () => clearTimer(deadlineTimer);
const settle = () => {
end();
// Later waits count animations from here.
(
window as unknown as {__harnessAnimations?: {arm: () => number}}
).__harnessAnimations?.arm();
resolve(null);
};
let last = '';
let still = 0;
// When each frame of the per-frame check came since the element
// last moved, on the real clock: only those can show it at rest.
let watchedFrom = realNow();
const drawn: number[] = [];
const shortfall = () => {
const times = [watchedFrom, ...drawn, realNow()];
let longestGapMs = 0;
for (let i = 1; i < times.length; i += 1) {
longestGapMs = Math.max(longestGapMs, times[i] - times[i - 1]);
}
return {
frames: drawn.length,
spanMs: realNow() - watchedFrom,
longestGapMs,
};
};
const frames = () => {
last = read();
still = 0;
watchedFrom = realNow();
drawn.length = 0;
frame(tick);
};
// A frame that never comes cannot reach the deadline check in
// `tick`: a starved page is caught here.
let starvedOut = false;
const deadlineTimer = timeout(
() => {
const lastFrame = drawn[drawn.length - 1] ?? watchedFrom;
if (!tracing() && realNow() - lastFrame > starvationMs) {
starvedOut = true;
resolve(shortfall());
}
},
ms + starvationMs + 1,
);
// While traced: one look at the animations, then a timer to the latest
// scheduled curve end. One not started yet is looked at again a frame
// later; a trace that has ended hands over to the per-frame check.
// Finding nothing settles only after `frames` looks a frame apart, as
// the per-frame check needs `frames` still frames: an animation the
// action starts a frame or two later is still waited for.
let idle = 0;
const scheduled = () => {
let wait = 0;
for (const a of element.getAnimations({subtree: true})) {
// A scroll- or view-timeline animation moves only when something
// scrolls: it has no scheduled end to wait for (holdAnimations
// skips it the same way).
if (!(a.timeline instanceof DocumentTimeline)) {
continue;
}
if (
a.pending ||
(a.playState === 'running' && a.startTime == null)
) {
wait = Math.max(wait, 16);
} else if (a.playState === 'running') {
// The curve's time left through the playback rate: forward, to
// its (held) end; backward (`reverse()`), to local time 0,
// where it finishes, as the untraced path waits it out.
const rate = a.playbackRate || 1;
const at = Number(a.currentTime ?? 0);
const left =
rate > 0 ? (curveEnd(a) - at) / rate : at / -rate;
wait = Math.max(wait, left);
}
}
if (wait <= 0) {
idle += 1;
if (idle >= need) {
settle();
return;
}
wait = 16;
} else {
idle = 0;
}
const room = deadline - realNow();
timeout(
() => {
if (realNow() > deadline) {
end();
reject(
new Error('waitForRest: still moving at the deadline'),
);
} else if (tracing()) {
scheduled();
} else {
frames();
}
},
Math.min(wait, Math.max(0, room)) + 1,
);
};
const tick = () => {
if (starvedOut) {
return;
}
const now = read();
const moving = element.getAnimations({subtree: true}).some(
a =>
a.pending ||
(a.playState === 'running' &&
// Going backward the curve ends at the start delay, after
// the end delay (which plays first) and the curve itself.
(a.playbackRate < 0
? Number(a.currentTime ?? 0) >
Number(a.effect?.getComputedTiming().delay ?? 0)
: Number(a.currentTime ?? 0) < curveEnd(a))),
);
const resting = !moving && now === last;
if (resting) {
drawn.push(realNow());
} else {
watchedFrom = realNow();
drawn.length = 0;
}
still = resting ? still + 1 : 0;
last = now;
if (still >= need) {
settle();
} else if (realNow() > deadline) {
const short = shortfall();
end();
if (resting && short.longestGapMs > starvationMs) {
resolve(short);
} else {
reject(new Error(`waitForRest: still moving (${now})`));
}
} else if (tracing()) {
scheduled();
} else {
frame(tick);
}
};
if (tracing()) {
scheduled();
} else {
frames();
}
}),
{ms: timeout, need: frames, starvationMs: FRAME_STARVATION_MS},
{timeout: evaluateTimeout},
);
if (starved != null) {
throw new FrameStarvationError({
by: 'waitForRest',
frames: starved.frames,
during: `it waited ${Math.round(starved.spanMs)} ms for the element to rest`,
min: frames,
longestGapMs: starved.longestGapMs,
});
}
return true;
},
);
if (rested == null) {
throw new Error('waitForRest: still moving at the deadline');
}
}
/** What the page saw by the end of a `settlesAt` wait. */
interface SettleOutcome {
readonly settled: boolean;
/** No frame came for longer than the starvation gap before the deadline. */
readonly starved: boolean;
/** The value the last check read. */
readonly seen: string;
/** The animations still unfinished, described for the error. */
readonly unfinished: readonly string[];
/** From the start of the wait to its end, ms. */
readonly spanMs: number;
/** From the last frame before the deadline to the deadline, ms. */
readonly unwatchedMs: number;
}
/**
* Resolves once `locator`'s element shows `property` at `value` and no
* animation inside it is left unfinished. Held final keyframes count until
* their end, where `waitForRest` reads them as rest. The page checks once a
* frame, on its real frames, so a frozen timer gate does not hold it.
*
* Its deadline is `waitForRest`'s. Past `timeout` ms it rejects, and names
* the property, the last value it read and the animations still unfinished.
* It throws `FrameStarvationError` with the same names instead when the
* page drew no frame for longer than `FRAME_STARVATION_MS` before the
* deadline. A stall after the deadline does not count, because the page was
* watched up to it. An animation that repeats forever never finishes, so a
* wait under one reaches the deadline.
*/
export async function settlesAt(
locator: Locator,
property: string,
value: string,
{timeout = 5_000}: {timeout?: number} = {},
): Promise<void> {
// The page-side wait answers at its own deadline; the read gets a second
// more, so only an element that is gone runs it out.
const outcome = await withinTimeout(
'settlesAt',
locator,
Date.now() + timeout + 1_000,
async evaluateTimeout =>
locator.evaluate(
(element, {prop, expected, ms, starvationMs}) =>
new Promise<SettleOutcome>(resolve => {
// The wait uses the page's real frames, timers and clock, so a
// frozen timer gate does not hold it.
const gate = (
window as unknown as {
__harnessTimerGate?: {
frame: typeof requestAnimationFrame;
now?: () => number;
timeout?: typeof setTimeout;
clearTimeout?: typeof clearTimeout;
};
}
).__harnessTimerGate;
const frame = gate?.frame ?? requestAnimationFrame;
const realNow = gate?.now ?? (() => performance.now());
const later = gate?.timeout ?? setTimeout;
const clearTimer = gate?.clearTimeout ?? clearTimeout;
const startedAt = realNow();
const deadline = startedAt + ms;
let lastFrame = startedAt;
let seen = '';
let ended = false;
const unfinished = () =>
element
.getAnimations({subtree: true})
.filter(animation => animation.playState !== 'finished');
const describe = (animation: Animation) => {
const effect = animation.effect as KeyframeEffect | null;
const target = effect?.target ?? null;
const where =
target == null
? 'no element'
: `${target.tagName.toLowerCase()}${target.id === '' ? '' : `#${target.id}`}${effect?.pseudoElement ?? ''}`;
const css = animation as Animation & {
transitionProperty?: string;
animationName?: string;
};
const label =
css.transitionProperty ?? css.animationName ?? animation.id;
const end = Number(
effect?.getComputedTiming().endTime ?? Infinity,
);
const at = Math.round(Number(animation.currentTime ?? 0));
const length = Number.isFinite(end)
? `${Math.round(end)} ms`
: 'forever';
return `${animation.constructor.name}${label === '' ? '' : ` ${label}`} on ${where}, ${animation.playState} at ${at} of ${length}`;
};
const finish = (
settled: boolean,
starved: boolean,
unwatchedMs: number,
) => {
ended = true;
clearTimer(deadlineTimer);
const listed = settled ? [] : unfinished().map(describe);
resolve({
settled,
starved,
seen,
unfinished:
listed.length > 5
? [...listed.slice(0, 5), `${listed.length - 5} more`]
: listed,
spanMs: realNow() - startedAt,
unwatchedMs,
});
};
// A frame that never comes cannot reach the deadline check in
// `check`, so this timer gives the verdict instead.
const deadlineTimer = later(
() => {
if (!ended) {
const unwatched = Math.max(0, deadline - lastFrame);
finish(false, unwatched > starvationMs, unwatched);
}
},
ms + starvationMs + 1,
);
const check = (frameBefore: number) => {
seen = getComputedStyle(element).getPropertyValue(prop);
if (seen === expected && unfinished().length === 0) {
finish(true, false, 0);
} else if (realNow() > deadline) {
// Only the span from the frame before this one to the
// deadline went unwatched. A stall after the deadline does
// not hide the value read before it.
const unwatched = Math.max(0, deadline - frameBefore);
finish(false, unwatched > starvationMs, unwatched);
} else {
frame(onFrame);
}
};
const onFrame = () => {
if (!ended) {
const frameBefore = lastFrame;
lastFrame = realNow();
check(frameBefore);
}
};
check(startedAt);
}),
{
prop: property,
expected: value,
ms: timeout,
starvationMs: FRAME_STARVATION_MS,
},
{timeout: evaluateTimeout},
),
);
if (outcome == null) {
throw new Error(
`settlesAt: ${property} did not settle at ${value} by the deadline, and the page did not answer`,
);
}
if (outcome.settled) {
return;
}
const read =
outcome.seen === value
? `${property} read ${JSON.stringify(outcome.seen)}`
: `${property} read ${JSON.stringify(outcome.seen)} (not ${JSON.stringify(value)})`;
const running =
outcome.unfinished.length === 0
? 'no animation under it was unfinished'
: `unfinished under it: ${outcome.unfinished.join('; ')}`;
if (outcome.starved) {
throw new FrameStarvationError({
by: 'settlesAt',
frames: 0,
during: `it looked for ${property} to settle at ${value} in the ${Math.round(outcome.unwatchedMs)} ms up to its deadline (${read}; ${running})`,
min: 1,
longestGapMs: outcome.unwatchedMs,
});
}
throw new Error(
`settlesAt: not settled ${Math.round(outcome.spanMs)} ms after it began: ${read}; ${running}`,
);
}