An open source design system that's fully customizable and agent ready
@astryxdesign/interaction-harness
Playwright instruments for touch interaction and animation proofs: real touch
input, frame evidence, curve sampling and storyboards. Internal and
unpublished. Specs live next to their component as
*.interaction.browser.spec.ts and run under
playwright.interaction.config.ts on
a phone-sized touch screen (402 × 714 CSS px page, 402 × 874 screen, 3 device
pixels per CSS px, touch, mobile viewport rules), in Chromium and WebKit.
An accessibility spec (*.a11y.browser.spec.ts, under
playwright.config.ts) may use the animation
holds and the timer gate too, to check a state an animation passes through.
The exemplar to copy is
BottomSheetDetent.interaction.browser.spec.ts.
The harness proves its own instruments in
src/harness.interaction.browser.spec.ts.
The busy-main-thread proof and the rendering-trace counts have a negative
control beside their positive checks (a rAF animation that freezes under a
blocked main thread, a top animation that lays out every frame); other
self-tests check an instrument against a known answer.
Running
pnpm storybook:build # the specs read stories from the built Storybook
pnpm exec playwright install chromium webkit
pnpm test:interaction --project chromium # everything, Chromium
pnpm test:interaction BottomSheetDetent # one spec, both engines
pnpm storyboards # only the tests tagged @storyboard
On Linux distributions whose system libraries are older than Playwright's
WebKit build needs, run the WebKit project inside the official Playwright
image (podman or docker; the repository is mounted at the same path, and
under a rootful docker daemon the container runs as your user so its
test-results/ stay yours):
node internal/interaction-harness/scripts/webkit-container.mjs [playwright test args…]
WebKit composites through Mesa's software GL there, which compiles each shader
the first time a page draws it (450–700 ms for the first frame of a blurred or
newly animated layer). The script keeps Mesa's shader cache on the host
(~/.cache/astryx-webkit-shaders/<image>, or ASTRYX_WEBKIT_SHADER_CACHE), so
only the first run on a machine pays for them.
With CI set, the script gives the container the four CPUs of CI's WebKit
runners as a quota, and llvmpipe as many threads. ASTRYX_WEBKIT_CPUS sets
another count. On Linux the container runs only on the CPUs the script may use,
so taskset limits it too.
Evidence (storyboards, curve traces) is written to
test-results/interaction-evidence/ (override with
ASTRYX_INTERACTION_EVIDENCE) and attached to the test report. It is never
committed: a pull request links or attaches it.
Instruments
| Module | What it gives a spec |
|---|---|
scripts.ts |
Touch scripts as data: tap, drag (hold, rest), flick (exact final-move speed, velocity profiles), holdThenDrag, pinch, rotate, path, merge (a second finger mid-gesture), releaseVelocity, toTouchEvents. |
touch.ts |
touchDriver(page).play(script): the script as real engine input. installInputLog / readInputLog: what the page received. |
frames.ts |
startScreencast (timestamped composited frames), markElement (a marker chip or outline), trackMarker (marker box per frame), trackMarkers (several colors from one decode of each frame), sampleRects (per-rAF rects), frameStats, requireFrames. |
busy.ts |
blockMainThread(page, ms), which returns the window it held and the span its loop measured, and busyWindowProof(tracked, window): frames presented, frames that moved, longest stall, a verdict; presented adds the compositor's own frames. |
brightness.ts |
trackBrightness(page, frames, {x, y}): a colour channel's mean in a square per frame, as a scalar on box.x, for a busy-window proof of a fade or a dim. |
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, armHold, seekAnimations, sampleCurve (presented transform / opacity at any t), waitForAnimation, watchAnimations, waitForRest, settlesAt (a computed value reached and every animation inside finished, on waitForRest's deadline), 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), castStoryboard (real screencast frames): PNG contact sheet + JSON trace. |
output.ts |
evidenceDir, writeEvidence: where evidence goes and how it is attached to the report. |
story.ts |
phone, withStorybook, openStory, frames, and the timer gate (installTimerGate, freezeTimers, thawTimers). |
pointer.ts |
newFinePointerPage(browser): a page under a mouse that really reads (pointer: fine). assertFinePointer / assertCoarsePointer: fail before a case's checks when the page reads the other pointer. |
A fine pointer
Every interaction project is the touch phone, and a context a test makes with
browser.newContext() inherits it: it reads (pointer: coarse) unless it
passes hasTouch: false. A case that shows touch work costs nothing under a
mouse opens its page with newFinePointerPage(browser), which turns touch and
mobile off and checks the pointer first. A case that builds its own context
calls assertFinePointer(page) before its checks.
The proofs
Real touch. Untrusted DOM events are not input: they start no native
scroll, claim no gesture, and read isTrusted: false. Chromium input goes
through CDP Input.dispatchTouchEvent with an explicit timestamp per event: the
page's event.timeStamp is the scripted time to 0.1 ms, whatever the
dispatch latency, and the events go through the compositor's gesture detection
(native scrolling, flings with velocity from those timestamps, touch-action,
pointercancel). WebKit input goes through the engine's own input command; see
the limits below. Read positions a frame after a move: Chromium delivers
pointermove aligned to animation frames.
Stories, not Storybook. openStory turns Storybook's highlight module off
on every page it opens, and checks that its root element is absent. Left on,
the module observes #storybook-root and, on every insertion, reads the
computed style of every element on the page inside the inserting task (117
reads and two forced style recalculations for one exit copy in a Button story),
so a proof would measure Storybook as well as the component.
openStory(page, origin, id, args, {storybookHighlight: true}) keeps it on.
Curve sampling. Pause every running animation (CSS transitions and
animations are Web Animations too), seek to a time, read getComputedStyle:
the presented value at that exact time, independent of frame timing. Finished
animations, ones the page paused and ones on a scroll or view timeline are left
alone; held animations keep their offsets from the first hold's earliest start, and release
resumes only them. 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, {judges}) 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. Other animations under the scope (a press, a
colour change) can meet that count before the motion a test judges starts,
and a hold that took only them proves nothing about it. So every armed hold
names the motion it judges, {judges: {target, property}} (a list for
several; pseudoElement for a ::before or ::after), and held() rejects
when the hold took no animation of it. A judged run that the page cancels after
the hold (a later style change retargets a CSS transition) fails the next
seekAnimations or sampleCurve by name: a read would show a run that the
hold did not take. A hold whose scope is not on the page within 5 s fails by
name too. judges: 'count-only' checks nothing:
it marks a call site whose hold does not take its judged motion yet.
A hold sent from the test (holdAnimations, and animationStoryboard
without held) takes the same judges and rejects the same way: it takes
what runs when it reaches the page, and on a busy runner the judged motion
can still be to come or already over.
Compare it with an
oracle from math.ts through compareCurve; a tolerance states the error
budget (for a spring baked into linear() stops of h ms, chords err by up to
h² / 8 · |x''|). A seek past an animation's end lands half a millisecond
inside it, the last frame it presents, and the sample says so (presentedAt,
where oracles are read). An animation whose keyframes end in a run of
identical values (an end value held so a later interruption can read it)
ends where that run starts: curveEndMs, waitForAnimation's interval and
the default storyboard times stop there, and waitForRest, which judges the
presented transform, translate, rotate, scale and opacity rather
than playState, does not wait the hold out. That holds for an animation that
plays forward under a linear or cubic-bézier effect easing (the time the run
starts is solved from the curve); under any other effect easing (steps,
linear() stops, an overshoot) or another direction the curve is read to its
full end, and waitForRest waits the hold out. An animation reversed before it starts (reverse()
on a new animation, a negative playback rate from the start) is reported by
waitForAnimation from when it started, but holdAnimations refuses it:
seeking and sampling run a curve forward. The recorder keeps one entry per
Animation object, so one 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. Take a fresh animation for each run a proof reads.
sampleCurve(locator, times, {pseudoElement: '::before'}) samples the
element's ::before or ::after instead: its presented values, labelled by
that pseudo-element's own animations.
Waiting for an animation. The page records every animation from the first
call into curves.ts on it (and on every later document): a frame loop on the
page's own requestAnimationFrame, the CSS animation and transition events,
and Element.animate as it is called, pending animations included. So
waitForAnimation also reports one that started after the last
waitForRest, waitForAnimation or watchAnimations and has already finished (finishedAt
set): a short entrance no longer races the first look on a cold page. A run
that the page cancels while it plays ended there, with no finish event. Core's
motion animator retires each run with cancel() once its curve ends. The
recorder dates such a run at the cancel, and a wait reports it once it
presented minProgressMs. When the action may be the page's first contact
with the harness, take watchAnimations(locator) before it and read
watch.started() after.
Busy main thread. Mark the element, start the screencast, start the
animation, wait until it runs (waitForAnimation: an animation cannot start
while the thread is held), block the main thread for 1 s (spec:AST-094
FR5's verification row), stop. Always
start the gesture or animation first and block mid-flight, never before:
in headless Chromium a touch that starts while the main thread is busy does
not scroll or start a gesture even with only passive listeners (the input
waits for the main thread). Tracking a finger under a busy main thread is
therefore proven on the iOS simulator, not here. The
screencast is captured off the main thread, so a compositor animation shows a
new position every frame of the block, and a main-thread animation shows none
(nothing changed, so no frame is sent at all: busyWindowProof counts the
whole window as one stall). settledWithin (2 px) stops judging at the easing
tail: the screencast rounds to whole pixels, so a tail that still moves shows
plateaus within a pixel or two of rest. settledWithinSteps counts that bound
in the cast's own position steps, read from the cast (castStep, from the
step trackMarker gives each frame of the default marker; a control tracked
by another color carries none, and castStep refuses it): 1 px in Chromium's PNG cast and 2 px in
WebKit's JPEG cast, whose 4:2:0 chroma holds the marker's color in 2 by 2
pixel blocks and so makes the tail's plateaus longer. Two steps stop at the
same tail in either engine while a freeze further from rest is still judged.
Motion slower than two whole pixels a frame needs a finer read. In Chromium,
trackMarker(page, frames, {subpixel: true}) reads the marker under a pixel
from its anti-aliased edges: a 10 px slide over 60 frames read 0.164 to 0.169
px a frame, where it moves 0.167 px, and a box at rest between pixels read the
same value on every frame. Each frame then carries SUBPIXEL_STEP_PX
(0.05 px) as its step, and the proof counts a change from half of it. The
marker must be opaque on a plain background. Use the default chip marker: an
outline marker's window holds the element's own content. WebKit's JPEG cast
holds color in 2 by 2 pixel blocks, so the read throws there.
A judged part shorter than four of the
screencast's intervals fails: the animation under test was not moving during
the block. One that had already settled when the judged part began (nothing in
the window to judge) throws BusyWindowTooLateError, with the numbers: the
block ran too late, which is no reading of the component. The held animation
can also end inside the block. When it keeps no end value (holds false: no
held tail, and no fill the compositor honors; WebKit on Linux honors none)
and no settle bound applies, the judged part ends at its curve's end. Past it,
WebKit presents the value the main thread last committed, not the animation.
If that leaves the control fewer than four frames, where the uncut part held
enough, the block also began too late: BusyWindowTooLateError, with
curveEndMs. A starved run still throws FrameStarvationError. With
during, blockMainThread starts the loop from a task queued in the frame
that saw the animation, after that frame's rendering update: WebKit hands a
newly started animation to its compositor there, and a loop inside the rAF
callback would freeze even a compositor animation. Call it before the release
that starts a settle and await it after, so the page is already waiting when
the settle begins. An animation counts once it is no longer pending and has
run at least one frame: a minProgressMs under 16 is raised to 16, since one
created in the frame the page looks is not on the compositor yet. It counts
only before its curve's held tail (keyframes that end in a run of identical
values, read as waitForRest reads them): when the only animation running
there started while the page waited, or the wait times out with only such
animations, the page looked too late, and the wait rejects with
BusyWindowTooLateError. With pseudoElement ('::before' or
'::after'), only that pseudo-element's animations on during itself count,
as sampleCurve reads them: a child's animation, such as a switch thumb's
press, does not start the block. With property, only animations that set
that property count, named as CSS names it (translate, background-color,
--press-strength), as a hold's judged motion names it. The animation must
also be the same one the page saw at its frame before:
a component can rebuild a running animation on its old clock, and the page sees
it running before the compositor shows a frame of it. The window names the
animation it caught (animation): when it started and where its curve ends.
These times are on the real clock, as the window's own are, after a page
freeze too.
The verdict judges the
frames the screencast delivered, whatever its rate (a loaded machine's can
deliver one frame in five or six), and tolerates nothing a frozen animation
does: at least one frame in the judged part, no stall longer than three of the
screencast's intervals (two dropped frames), and at least 90% of the frames it
delivered in the judged part presenting a new position (one miss is always
allowed; a frame it did not deliver is a gap, for the stall check, unless
it delivered fewer than four frames there: then the judged part's span counts
every frame, so one late frame is not "1 of 1 moved"). Pass
maxMedianFrameMs (20 at 60 Hz) only in a proof that claims display rate.
verdict.failures names each miss with its numbers, and summary carries the
raw numbers for the report. Frames are judged in presentation order: a loaded
machine can deliver them out of order. castStoryboard turns the frames of the
block into a filmstrip.
To read frames after a moment, such as the rest after a block, wait for them by
time: waitForCastFrame(cast, {after, during}) returns once the cast holds a
frame presented after after, epoch ms on the page's clock. A frame that
arrives after that moment can still have been presented before it, so a count
of frames delivered is no such wait. cast.lastFrameAt() reads the latest
presentation time captured so far. Past 5 s with no such frame, the wait fails.
When no frame came for longer than FRAME_STARVATION_MS, it throws
FrameStarvationError: the screen did not change, or the page was starved of
frames. Keep something moving, such as startBusyControl, to tell them apart.
While frames still come, all presented before after, the error names both
times.
A just-started animation can reach the screen after the block began (50–100 ms
later in WebKit on a loaded machine). When the cast saw the element at rest
before the block (wait for cast.frameCount() to pass 0 before starting the
animation), judging starts at its first presented change: the judged part still
ends with the block (or the held curve, above) and still needs four intervals,
and onScreenFromMs and the
summary report when it came. So is an element that moved, then held from
before the block until its first presented change inside it: WebKit presents
a just-started compositor animation late (a sheet's release held on screen for
130 to 300 ms while its timeline ran), and its cast reaches Node about 0.7 s
late on a loaded runner, too late to wait on before blocking. Only a hold that
starts before the block, on two frames at least, at the position the page last
set before the block is excused. Pass that position as setBeforeBlock, such
as the drag's last position at the release. Without it, a block with during
takes the position on the cast's last frame before the caught animation's
start. Chromium on a loaded runner presents a just-started compositor
animation late too: a slider's coast first showed 25–111 ms after its start.
An animation frozen at the block's
start holds a position of its own, and is judged as a stall. Every frame after
its first change is judged, so a freeze later in the block still fails.
An element off screen before the block, such as a card that enters from an
edge, is judged from its first position inside the block. The cast's frames
before the block must show the screen without it. A main-thread entrance
shows no frame during the block, so it still fails. With no frame before the
block at all, nothing is known, and the block is judged from its start.
Any other element already moving is judged from the block's start. WebKit's
casts are 2 px quantized: their JPEG frames hold the
marker's color in 2 by 2 pixel chroma blocks (4:2:0, which the frame header
reports), so positions move in 2 CSS px steps (Chromium's in 1). With under two steps of
motion per frame, a frame delivered a few ms early shows no step and reads as
not moved. The proof reports stepPx and pxPerFrame and notes each stretch
that moves under two steps per frame, read over four frames at a time so a
slow tail inside a fast window shows, which never fails it. Move a proof's element at least two
steps a frame: the self-tests move 560 px in 1,600 ms, about 4.8 px a frame.
On a two-core runner the software compositor and the screencast share the core
the block spins on, so every compositor animation presents fewer frames there:
Lightbox's double-tap zoom, pinned to two cores, missed a display-rate bound in
7 of 10 runs while it moved on every frame the compositor presented. Judge such
a proof against a control instead of a rate: startBusyControl(page) shows a
small CONTROL_RGB box in the top layer (a manual popover, so above a modal
dialog opened before it; raise() after one opened later) whose transform
moves it along the top edge for as long as the page runs. A proof of a
dialog's backdrop mounts the control inside the dialog with
startBusyControl(page, {within: dialog}), a plain fixed box with no top-layer
entry: in WebKit, with the popover above BottomSheet's open modal dialog, the
sheet's dim held for 155 to 225 ms into a block while the control moved, and
inside the dialog it moves in step with the sheet. waitForAnimation and
blockMainThread's during never count the control's own animation, so on
a dialog they still wait for the backdrop's. Track a top-layer control from
the same screencast with trackControl(page, frames) (trackMarker with
CONTROL_RGB, searching only the top strip it crosses). A control mounted
within a dialog moves with it, so track that one with trackMarker(page, frames, {rgb: CONTROL_RGB}), or track the marker and the control together
with trackMarkers(page, frames, {colors: [MARKER_RGB, CONTROL_RGB]}), which
decodes each frame once. A proof reads frames up to
BUSY_PROOF_LOOKAROUND_MS (250 ms) around its judged part, so a spec may
decode only those. Pass either as control: the component passes when it moved on every frame the control
moved and its longest stall is no longer than the control's. Both are read from
the same screencast frames, so a compositor animation misses none. A window in
which the control moved on fewer than four frames is under the floor. Under the
floor, a run with no component failure on the frames shown is too little to
judge: busyWindowProof throws FrameStarvationError instead of returning a
verdict. The error names the control's moves, the cast's frames in the window
and its longest gap. A component that missed a frame the control moved on, or
stalled longer than it, failed on frames the compositor presented, so the
verdict keeps that red. A run the machine starved, with no frame for longer
than FRAME_STARVATION_MS, throws either way. maxMedianFrameMs judges the
cast's pace, not the component, so under the floor it keeps no red.
A run of frames with no new position counts as
moved when the change that ends it is a single cast step: the component moves
under one step a frame there, as on an easing tail, which the cast cannot show
on every frame. Where it moved under two steps a frame over the frames just
before the run (a spring's slow tail inside a fast window), or across the run
itself (its catch-up over the frames it spans) where the curve slows faster
than those frames show, a frame delivered early can show no step too, so the change may carry the motion of every frame
the run held at that pace, to the nearest step. The run must also read as a
slowing curve, at most one frame longer than the component's run before it.
Under settledWithinSteps, a run under one cast step a frame may instead last
ceil(step ÷ travel) frames, whatever the run before it. The travel is the
slower moving pace around the run, never less than its own catch-up per frame.
The run also lasts at most one frame more than the pace into it allows:
ceil(step ÷ max(pace before, catch-up per frame)) + 1. A
freeze ends in a catch-up of more than that, a stall in a frame-counted animation is longer than its runs
before it, and a run that no change ends stays a miss. The component still has
to show a new position on at least four of the control's frames. The cast step (stepPx)
is read from the value's changes in the judged part, so a position the page
commits off the grid once the block ends does not shrink it.
A main-thread animation still fails: the control moves and it does not.
Each such run counts in the control read's belowStep. A proof that claims a
new position on every frame the control moved passes judgeEveryFrame. A frame
the cast's step explains is then too little to judge: busyWindowProof throws
BusyFrameUnjudgedError with each such frame, the component's move per frame
there and the cast's step. A verdict that fails anyway comes back as it is, so
a frozen or main-thread component stays a red on the component.
A window that caught an animation (blockMainThread with during) predicts
each frame instead, when two things hold. The proof passes both controls,
ahead included, so every frame has a time of its own. The engine is
Chromium. A geometry replay also needs the harness marker on the caught
element. Once the loop ends, the
page replays the element's geometry animations, paused, on a hidden copy of
its box. The copy is aligned to the element, and its box is read every 2 ms.
A fade or a pseudo-element replays one numeric channel. The tracked value at
rest and at the curve's end map that channel to a position. The proof dates
each frame on the controls' clock, from the controls' starts that the window
keeps. A frame predicted to move a full cast step since the last new position must
show one, so a hold ends once its moves add up to a step.
A frame predicted to move less is too little to judge, and so is a frame with
no control reading of its own. Each such frame is named in the proof's
unjudged list and in its summary. It counts neither as moved nor as missed,
and judgeEveryFrame throws for none. When too few judged frames are left,
the proof throws FrameStarvationError. Where a replay predicts, one the
proof cannot read throws BusyPredictionError: an ancestor moves too, or a
run composites onto another. A replay whose travel or first judged position
differs from the cast's by more than two steps or a tenth of the travel falls
back by name. So does a geometry window without the marker, a window without
ahead or in WebKit, and a window whose run left the element before the
replay. WebKit reads the element's box at the loop's end before its
animation's current time, so the replay cannot be aligned there. A window that falls back is judged exactly as without a
replay, and its notes say why. The proof gives its judged part in the
cast's stamps, so a spec selects frames by it as before.
controlClock(control) reads the compositor's own time in each frame off the
control's position, for a proof that judges motion against time, not against
the screencast's stamps. A loaded machine stamps frames late, and
inPresentationOrder can then put a frame after frames that came after it.
The clock takes the cycle origin that most frames agree with, so such a frame
moves only its own reading. A frame within 36 px of a turn gets no reading.
A proof that needs every frame read starts a second control after the first,
startBusyControl(page, {ahead: true}): an AHEAD_CONTROL_RGB box in the
strip below, half a leg (200 ms) ahead. Wherever the first control is near a
turn, the one ahead is mid-leg. Track it with trackControl(page, frames, {ahead: true}) and read it with its own controlClock. startBusyControl
resolves with each control's start on the page clock, where its own time
is zero. Keep the component's marker out of the top 28 px then.
In WebKit, a busy proof with a control judges every frame on the controls'
clock, not on the screencast's stamps. WebKit stamps the frame after a delivery
gap about 60 ms late. So busyWindowProof and pooledBusyProof date each
WebKit frame from the control's positions, the component's and the control's
alike. A frame with no reading keeps its stamp's distance from the nearest frame
whose stamp agrees with its reading. The dated frames keep the cast's order,
since the cast delivers them in the order they were drawn. The proof's judged
part stays on the cast's stamps, so a spec selects the judged part from its own
cast; frames the display-rate keep left out fall inside it too. A spec that
needs a frame's own time for another check reads it with pageTimesOnControls,
the readings the proof dates from. Without the control ahead, a late frame near
the first control's turn keeps its lateness. A proof that judges every frame
near a turn starts the control ahead too
(startBusyControl(page, {ahead: true})). It passes that control's frames as
ahead, per run in a pool; controlStarts is optional. A Chromium cast with
a control is dated the same way. Its cast stamps each frame as it arrives.
Under load, the stamps trail presentation unevenly: in a slider's coast, by a
median 4.6 ms and up to 38 ms. So the frame interval read from the stamps is
wrong, and a proof on them misreads a slow tail's pace. Two frames a whole
frame apart can even carry stamps 2 ms apart. Without the control ahead, such a
pair near the first control's turn keeps its stamps, as a late WebKit frame
there keeps its lateness. Only frames that carry their engine, as trackMarker
reads them, are dated. Frames a spec builds without it, and a cast with no
control, are judged on their stamps. On
WebKit's stamps, a late frame inside the judged part changes no verdict, since
the proof reads a slow curve's held frames as motion. At the part's start, it
shows a stall the control does not have: the false reds came from there.
A WebKit proof keeps one dated frame per display interval. A frame under one interval after the last one kept is left out; the earlier one stays. WebKit's compositor can draw two frames 6 to 9 ms apart, and a curve then shows no new step between them. A frame with no reading always stays, since its time is a neighbour's. A WebKit cast rarely shows two frames one interval apart. So the proof judges motion on every kept frame the control moved, but no 30 Hz cadence. Its summary says so in a note, with the count of pairs one interval apart. Chromium's cast judges that cadence.
An animation that lasts a fraction of a second, such as a 0.2 s fade, leaves a
block only a few frames to judge: in WebKit, or on a loaded machine, the control
can present fewer than four, and one run cannot decide. Play it several times
and judge the runs pooled (pooledBusyProof(runs), each run with its own
tracked frames, control and window): the control must move on at least four
frames over all the runs, the component on every one of them, and in each run
its longest stall may be no longer than that run's control's, since a stall
belongs to its run. A run whose control moved on fewer frames than
minRunFrames (1 by default) is too little to judge: the summary names it,
and the pool leaves it out, so it never counts as a pass. A run whose block
began too late for its motion is left out the same way: its runs entry
is null, and late holds its BusyWindowTooLateError. The pool reads each
run without the starvation throw. With fewer than minJudgedRuns judged runs
(half of all the runs, rounded up), or a control that moved on fewer than four
frames over them, the pool is under the floor. Under the floor, a pool with no
component failure on the frames shown is too little to judge, and it throws
FrameStarvationError. A pool left short of judged runs by a run that began
too late fails instead, and so does a pool whose judged runs show a component
red. In each judged run,
the component must move on every frame its control moved on, so a freeze fails
its run.
On a loaded machine Chromium's screencast can skip frames the compositor
still presents. startCompositorTrace(page), started with the screencast and
stopped after the block, records when the compositor presented each frame
(Display::FrameDisplayed); pass it as presented. The record is
browser-wide (its frames carry no page identity), so it throws when another
page is open as it starts or stops, or opened while it ran. A gap between two moved
frames with nothing delivered inside it is then measured between the
compositor's own frames: the frames it presented there count as presented
(recorderSkipped, in the summary), and a gap it did not present through is
a stall as before. A gap that opens or closes the judged part, or holds a
delivered frame that did not move, is judged from the screencast, so a
frozen element fails whatever else the compositor draws (a rAF animation's
block presents no compositor frame at all). With the record, the 90% counts the
compositor's frames from the first to the last moved frame; the gaps before and
after are the stall check's. WebKit has no such trace:
stop() resolves to [] and the screencast is judged alone.
Too few frames. A proof that samples the page every frame (sampleRects,
or a rAF trace of its own) takes its frames through requireFrames(samples, {min, during, where}). It returns the samples that where selects when there
are at least min of them. A loaded machine, or a long task on the page, can
starve the page of frames. When no frame came for longer than
FRAME_STARVATION_MS (50 ms) around the selected samples, the proof fails
with FrameStarvationError, which names the frames drawn and the longest gap.
So a run that cannot prove anything still fails, and says why. With too few frames on pace, the motion did not last that
long, and the error says that instead.
waitForRest fails the same way when it cannot tell. The element held still
in its last frame, or no frame came after the deadline, and no frame came for
longer than FRAME_STARVATION_MS: it throws FrameStarvationError, not
"still moving".
No Layout / Paint. traceRendering records a Chromium trace around the
interaction; countBetween counts the steady middle of an animation (its
first and last frames may commit). A transform/opacity animation does no
Layout or Paint there; a layout-property animation does one per frame. Each
counted Paint names the node it painted (node), and each UpdateLayoutTree
counts the elements it restyled (elements). A proof that expects no Layout
can explain one: traceRendering(page, body, {keepEvents: true}) keeps the
window's main-thread events, and layoutSources names the task that ran each
Layout and each invalidation before it. The
harness's own animation recorder stands down while the trace runs, since its
frame loop would make every frame a main-thread one, restyling each running
animation's target and laying out an anchored one: it reads only the element a
CSS animation or transition event names, once, when that animation starts, and
catches up afterwards. A CSS run's end event reads nothing then either: the
recorder keeps the end and dates the run once the trace ends. The frame it
requested before the trace runs before the start mark, so the whole window
counts none of its work. A waitForRest
awaited inside the traced body stands
down too: it waits on timers for the scheduled ends of the element's curves
(looking frames times a frame apart before settling on none, so an
animation the action starts a frame or two later is waited for) and polls no
style until the trace ends (in the anchored fixture's steady middle,
24 Layouts before, 0 now). Its one read of the element's animations, as it is
called, restyles the element (2 Layouts and 2 style recalculations in the
anchored fixture when called 200 ms into its animation), so await it right
after the action that starts the motion, before the window a proof counts. So do waitForAnimation and a watch's
started(): they take the element's animations from the recorder's log,
judge a started one by its own times, and reach the element through a handle,
since each locator.evaluate makes a main-thread frame (there too, 24
Layouts before, 0 now). That holds for script animations and CSS
transitions. On a CSS @keyframes animation (and, unwatched, a cancelled CSS
transition), waitForAnimation and started() read the animation's timing,
which flushes its style and adds Layouts to the trace: wait on one with
waitForRest, or after the trace. Taking a watch (watchAnimations) inside
a trace reads the watched element's animations, which restyles it (and lays
out an anchored one), so a proof takes its traced watch before the window it
counts. The trace's longTasks are the page's own: only a task the harness marked as its own read
(waitForAnimation describing keyframes, blockMainThread without during)
is in devtoolsTasks instead, and only when no page script ran inside it. A
test's own page.evaluate stays the page's own task, long or stretched,
whether it calls page code directly or sets it off. Each long task carries its wall time (durationMs)
and the main thread's own run time (threadMs, from the trace's thread
clock). A busy machine stretches the first but not the second, so a task is
long only when its thread ran longer than 50 ms: the page's own work. A task
only the wall clock stretched past 50 ms is in stretchedTasks, with both
times. A thread that waits (a synchronous request, Atomics.wait) gains wall
time but no thread time, so a claim about a blocking wait judges
stretchedTasks too.
Storyboards. Deterministic: frames come from seeking held animations or
from stepping scripted input, never from wall-clock capture. The JSON trace
carries each frame's measurements and the spec asserts on it; the sheet is
evidence. A component that finishes an animation from a timer (a transitionend
backstop, a cleanup render) would do so behind a held storyboard's back:
installTimerGate before the animation starts and freezeTimers while
photographing. The page can still cancel a held callback, a held frame callback
gets the time it actually runs, and the harness's own waits (its frame waits,
blockMainThread with during, sampleRects) are not held.
An animation that repeats forever does not set a storyboard's default length;
with nothing else to film, pass times. A touch filmstrip keeps the scripted
event timeStamps (Chromium), but a handler that reads performance.now() or
Date.now() sees one event per photograph, about 100 ms apart, so a
clock-timed release flings slower when filmed than when played: a storyboard
cannot show such a gesture; record it in real time instead, with
startScreencast and castStoryboard. A photograph the engine fails
throws the engine's error; a storyboard never takes it again.
Page freeze
A proof that must act on a component mid-animation (a second tap mid-slide, a
finger that lands before the last lift reaches the app) races the test
process: on a loaded runner the motion has moved on, or ended, before the next
command reaches the page. The page freeze (src/freeze.ts) stops the scene
instead, and the proof acts at an instant of the scene's own time.
installPageFreeze(page)installs the page clock, before the page loads (beforeopenStory); theninstallTimerGateas usual. A page that never calls it keeps its own clock. Code that kept a boundperformance.nowbefore the install keeps the real clock.freezePageandthawPagestop and start the scene in one page task.freezePageOn(page, type)freezes on the nexttypeevent, in that event's own task and before any page listener for it: the install adds one window capture listener for each pointer, touch, mouse, key, wheel and scroll event before any page script runs, and the call arms it. Any other type throws. A freeze armed onscrolllands when the scroll event fires, after the scroll position has already moved.freezePageWhen(page, predicate, arg)freezes on the first real frame the predicate holds, and rejects after its timeout.advanceFrozenPage(page, ms)moves the page's clock and every held animation on together byms; timers and frame callbacks stay held.holdInputUntil(page, {afterResumeMs})makes the page handle its next lift late, after the thaw, while the scene runs (below).
While frozen, every animation in the document is paused where it stands (Web
Animations, CSS animations and transitions), and so is any the page starts
meanwhile, at its start. The timer gate holds the page's timers and frame
callbacks. These clocks stand still: performance.now(), Date.now(),
event.timeStamp, frame callback times, document.timeline.currentTime
and Animation.startTime. new Date() keeps the real clock. Timeouts the
page set before the freeze stop counting too, and come due on the page's clock
after the thaw. An interval keeps the real clock and skips its ticks while
frozen. The harness's own waits keep the real clock, so they still sample,
hold and time out on a frozen page. Only animations on the document timeline are held: one on a
scroll or view timeline follows its scroller, frozen or not. Input still
arrives, and its handlers run, each reading the frozen instant. An animation
reads as it did before the freeze (playState stays running).
At the thaw every held animation plays on from where it stood, dated on the timeline's own time, so it is drawn where it stood in the thaw frame. That includes one whose start the page wrote while frozen: the timeline reads the current frame's time, which trails the page's clock by however far into the frame the thaw runs, so a start dated from now would sit before its start for the rest of that frame. After a thaw the page's times run again, behind real time by every frozen span so far, so the page's clock and its animations on the compositor agree as they did before the freeze.
Not held yet: a run the page reverses, or a finished run it plays again,
while frozen. A freeze holds the top document; a frame's content keeps running.
A CSS animation a freeze held no longer follows animation-play-state after
the thaw. A freeze in which no frame starts ends at the frame before it, so the page's
clock and its runs come out of it up to a frame ahead.
The clock lives in script because no engine has a native freeze that holds
animations. Chromium's Emulation.setVirtualTimePolicy stops
performance.now() and timers but not Web Animations or frame callbacks in
the headless shell (300 ms into a pause the timeline had advanced 300 ms and a
compositor animation 45 px), and its advance policy cannot return to real
time: it fast-forwards whenever the page is idle.
Input the page handles late
A frozen page handles input at once. A proof that needs a late handling, with
the compositor still moving, cannot freeze through the input. A held run resumes
only at the first frame after the thaw, and a block before that frame holds the
screen too. holdInputUntil(page, {afterResumeMs}), called before the thaw,
holds the next lift instead (pointerup or touchend; on names others). The
install's window capture listener runs first in the input's task and keeps the
main thread busy until afterResumeMs after that first frame. Send the input
once resumed() resolves. landed() then gives when the input arrived, when it
was due, and when the page let it through. The event keeps its own timeStamp,
earlier than its handling, as on a busy page. An input that arrives more than a
frame late, before that first frame, or while the page is frozen again, rejects
landed() with LiftPlacementError and the numbers. The page cannot hold back
an input it has not received, and a hold before the frame would stop the screen.
Choose afterResumeMs above the runner's time from resumed() to the input's
arrival. Under load, that round trip is what makes a hold late. The page lets
the input through at its time, or at its arrival if that came later within the
frame. On a starved runner it can be later still, by as long as its main thread
did not run: landed() gives that as stalledMs.
navigator.scheduling.isInputPending() cannot gate a lift. In Playwright's
Chromium 149 it reports a queued mouse press or key at once, but never a touch
sent with Input.dispatchTouchEvent. WebKit has no isInputPending.
Engine limits (measured with Playwright 1.61)
| Chromium 149 | WebKit 26.5 (Linux build) | |
|---|---|---|
| Trusted touch + pointer events, multi-touch | yes | yes (a touchstart lists only the fingers that landed in it; pointer events exact) |
| Page sees the scripted timestamps | yes, exactly | no: real dispatch time; pacing keeps velocities within ~1 ms on an idle runner; after a stall each step waits its gap, less 2 ms, after WebKit answered the one before, even with onEvent, so no gap can shrink; a play fails when its page read a resting finger where the script moves, a throw where the script rests, or fewer than two moves, or, given releaseTolerance, a release straying further from the script's (each read as Core's tracker reads it): TouchLiftStallError when onEvent held the lift back, TouchPageStallError when the page's listeners held an event, TouchStarvationError when the page drew no frame across the late gap, else TouchPacingError; the lift's release names what the page read |
| Sub-pixel touch positions | yes | no: integer CSS px |
| Native scroll, fling, pinch-zoom from injected touches | yes | no |
| Lifting one finger while others stay down | yes | pointer events right, but that touchend lists no remaining touches: skip with PARTIAL_LIFT_SKIP |
| Click synthesised from a touch | yes | only from driver.tap (WebKit's tap gesture), not from a raw touch sequence |
| Curve sampling, storyboards, input log | yes | yes |
| A CSS animation shorter than a gap between two frames | yes: a pending animation starts at the next frame, and runs then | no: it can start and finish inside the gap, and its start event, sent at the next frame, finds nothing to record; waitForAnimation names it |
| Screencast frame evidence (busy main thread) | yes | yes (WebKit's own screencast; frames keep coming while the main thread is blocked) |
| Rendering trace, long tasks | yes | no (Playwright exposes neither) |
| Compositor presentation record | yes | no: stop() resolves to []; the busy verdict judges the screencast alone |
Wheel steps, exact CSS px deltas (webInput.ts) |
yes | desktop context only (isMobile: false): skip with WHEEL_SKIP; the step also moves the mouse there (a pointermove) and holds Control as a key |
| Pen strokes, pressure, scripted timestamps | yes | no: skip with PEN_SKIP |
| Pen over a native scroller | no pan: the pen takes the mouse pipeline, so a stroke scrolls nothing, raises no pointercancel and ends in a click |
no: skip with PEN_SKIP |
What WebKit cannot show here — native scroll hand-off, flings, a finger
lifting while another stays down, finger tracking under a busy main thread, and
anything iOS-only — needs Mobile Safari itself, on a device or the iOS
simulator. Skip such a proof on the driver's flag, citing the reason:
test.skip(!driver.partialLifts, PARTIAL_LIFT_SKIP).
A touch play waits for its onEvent before it sends the next event, so page
work there delays that event by a round trip. WebKit stamps a touch when it
arrives. So a lift that reaches the page past the 40 ms stillness interval
after its finger's last move reads as a resting finger. The page releases it
at 0. Every WebKit play reads its release from the page's own stamps, however
it is paced, and fails by name when the page's release is not the script's.
The error is TouchLiftStallError when onEvent alone carries the scripted
gap past the stillness interval, however much a loaded runner stretched it.
Record what the page did in a listener of its own, or let the script rest
before the lift. A runner too loaded to dispatch in time stretches a
gesture the same way, and the play fails with TouchPacingError. When the
page also drew no frame for longer than FRAME_STARVATION_MS across that
gap, and no page work held the event, it fails with TouchStarvationError:
the runner starved the page, so judge the proof from a run with CI's CPU
limits. A play whose
proof reads no release from the lift, such as a pinch's end, passes
releaseUnread.
A proof whose component decides on a threshold names it in boundaries:
the release speed a pager pages from (releasePxPerS), or the hold after
which it catches the content (holdMs). In WebKit the play then fails by
name when the page read the release, or the first finger's hold from
touch-down to lift, on the other side of the threshold from the script. A
scrolling surface reads its release as Core's scrollVelocity does: pass
release: 'scroll'. Each pacing error names the longest time the page drew no
frame during the gesture. A page that drew nothing for 100 ms or more never
received the gesture as scripted. To read a frame before the gesture, a judged
play starts one frame later.
A wheel gesture is a run of steps, and wheel waits for each step's round
trip, so on a loaded runner awaited steps land as far apart as a round trip
takes: 49 to 141 ms in WebKit, past the 100 ms a proof may allow between the
steps of one wheel gesture. wheelBurst({x, y, steps, everyMs, maxGapMs})
sends a run at one point on its schedule (16 ms by default) without waiting for
each round trip and resolves once the page has the run's whole delta; where the
page still handles one step when the next arrives, the engine coalesces them,
as it does a trackpad's.
WebKit dispatches a step only once the page's main thread is free, and the
steps it holds meanwhile reach the page coalesced into one, stamped like the
step before it, so the burst times each WebKit step by when the page's first
listener received it (wheelArrivals). Three things can split a run past
maxGapMs. When a step reached the page within one frame of its own wheel
listeners finishing the step before, and the gap is more than a frame wider
than the harness's own spacing of those sends, those listeners held it back:
the burst throws WheelPageStallError, the page split the gesture, and the
proof fails. A page can only widen a gap, so one no wider than the send
spacing is the dispatch's even when a starved renderer also held the step.
When the page drew no frame across nearly all of a widened gap, engine or page
work held the main thread: the burst records the page's frames and throws
WheelPageStallError with the frame gap, the arrival gap and the listeners'
time. A starved runner's renderer draws no frame either, so judge such a stall
from a run with CI's CPU limits. Otherwise the dispatch stalled before the
page (a loaded runner) and it throws WheelPacingError with the gaps. A proof
never re-takes itself: a WheelPacingError stays red, named as the runner's.
Where one shows in CI's profile, fix the wheel's delivery, not the proof. The
burst times the
page's handling with a listener on the window that runs after the page's own.
A step whose propagation the page stops is marked by a task queued when it
arrived, and never later than the next step's arrival. So its handling, with
any work queued before that task, counts as the page's. Other main-thread work
between steps that leaves frames running still counts as the dispatch's stall.
Chromium stamps a step with its dispatch time, so a page that holds its main
thread does not widen the gaps there, and every gap past maxGapMs is a
WheelPacingError.
The WebKit input command is reached through Playwright's in-process server
object, so it needs a locally launched browser (the default), not connect().
Firefox has no touch input path and no project.