Skip to content

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

TypeScript

test(interaction-harness): wheel and pen input drivers for every-pointer proofs (#8666)

Christopher Chedeaud48bca59b624
diff --git a/internal/interaction-harness/README.md b/internal/interaction-harness/README.md
index b7f583829f..dc881a675a 100644
--- a/internal/interaction-harness/README.md
+++ b/internal/interaction-harness/README.md
@@ -48,6 +48,7 @@ committed: a pull request links or attaches it.
| `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), `frameStats`. |
| `busy.ts` | `blockMainThread(page, ms)` and `busyWindowProof(tracked, window)`: frames presented, frames that moved, longest stall, a verdict; `presented` adds the compositor's own frames. |
+| `webInput.ts` | `webInputDriver(page)`: `wheel({x, y, dx, dy, ctrl})` and `pen(points)` as real engine input, for proofs across pointers (`spec:AST-100` FR4); `wheel` resolves once the page has the step; read back through the input log. |
| `trace.ts` | `traceRendering(page, body)`: main-thread counts of UpdateLayoutTree / Layout / PrePaint / Paint / Layerize / UpdateLayer / ScrollLayer / HitTest, `countBetween`, long tasks; `installLongTaskLog` / `readLongTasks`; `startCompositorTrace`: when the compositor presents. |
| `curves.ts` | `holdAnimations`, `seekAnimations`, `sampleCurve` (presented transform / opacity at any t), `waitForAnimation`, `watchAnimations`, `waitForRest`, `releaseAnimations`. |
| `math.ts` | Oracles independent of the code under test: `cubicBezier`, `timingFunction`, `springStep` (SwiftUI response / dampingFraction, initial velocity), `projectDecay`, `rubberBand`, `parseTransform`, `compareCurve`, `timeline`. |
@@ -205,18 +206,21 @@ in all, and lists each retake under `recaptures` in the trace.
## 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; real-time pacing keeps velocities within ~1 ms |
-| 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 |
-| 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 |
+| | 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; real-time pacing keeps velocities within ~1 ms |
+| 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 |
+| 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
@@ -224,6 +228,30 @@ 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 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 stamps each step when its web process dispatches it, and dispatches it
+only once the page's main thread is free, so two 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, those listeners held it back: the burst
+throws `WheelPageStallError`, the page split the gesture, and the proof fails.
+Otherwise the dispatch stalled before the page (a loaded runner) and it throws
+`WheelPacingError` with the gaps. Wrap such a
+proof in `retakeOnWheelPacing(testInfo, attempt)`: one re-take, only on
+`WheelPacingError`, listed as a `wheel-retake` annotation. The burst times the
+page's handling with a listener on the window that runs after the page's own,
+so a listener that stops the step's propagation, or other main-thread work
+between steps (timers, frames), 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.
diff --git a/internal/interaction-harness/src/harness.interaction.browser.spec.ts b/internal/interaction-harness/src/harness.interaction.browser.spec.ts
index d5ecffece8..1004c6b6bf 100644
--- a/internal/interaction-harness/src/harness.interaction.browser.spec.ts
+++ b/internal/interaction-harness/src/harness.interaction.browser.spec.ts
@@ -6,12 +6,15 @@
* @output Proof that each harness instrument measures what it claims (the
* busy-main-thread proof and the rendering-trace counts with a negative
* control beside their positive checks): scripted timestamps reach the
- * page; a flick flings natively (Chromium); a second finger and a pinch
- * arrive as distinct pointers; the screencast shows a compositor animation
- * advancing through a blocked main thread while a rAF animation freezes;
- * the trace counts zero Layout for a transform animation and one per frame
- * for a `top` animation; the long-task log records the page's own long
- * task but not a DevTools evaluate, which the trace counts; sampled curves
+ * page; a flick flings natively (Chromium); a wheel step arrives as
+ * exactly its deltas, with Control when held, and a pen stroke as trusted
+ * pen pointers with its pressure and times (Chromium); a second finger and
+ * a pinch arrive as distinct pointers; the screencast shows a compositor
+ * animation advancing through a blocked main thread while a rAF animation
+ * freezes; the trace counts zero Layout for a transform animation and one
+ * per frame for a `top` animation; the long-task log records the page's
+ * own long task but not a DevTools evaluate, which the trace counts;
+ * sampled curves
* match the oracles, individual transform properties included; a sample at
* an end reports the time it was read at; holding takes only running
* document-timeline animations, each at its own offset, holds each where it
@@ -56,6 +59,7 @@ import {
readInputLog,
readLongTasks,
releaseAnimations,
+ retakeOnWheelPacing,
sampleCurve,
seekAnimations,
springStep,
@@ -72,6 +76,11 @@ import {
waitForAnimation,
waitForRest,
watchAnimations,
+ webInputDriver,
+ WheelPacingError,
+ WheelPageStallError,
+ PEN_SKIP,
+ WHEEL_SKIP,
withFinger,
} from './index';
@@ -750,6 +759,429 @@ test.describe('frame evidence', () => {
});
});
+test.describe('wheel and pen input', () => {
+ test("at a device-pixel ratio of 3, a wheel step reaches the page as exactly its delta, where Playwright's own wheel delivers a third of it in Chromium", async ({
+ browser,
+ browserName,
+ }) => {
+ // A desktop context at DPR 3: the phone context has no wheel in WebKit.
+ const context = await browser.newContext({
+ viewport: {width: 402, height: 714},
+ deviceScaleFactor: 3,
+ isMobile: false,
+ hasTouch: false,
+ });
+ try {
+ const page = await context.newPage();
+ await page.route('http://wheel.test/', route =>
+ route.fulfill({
+ contentType: 'text/html',
+ body: `<!doctype html><meta name=viewport content="width=device-width,initial-scale=1"><body style="margin:0;height:3000px"><script>window.__deltas=[];addEventListener('wheel',e=>__deltas.push(e.deltaY),{passive:true});</script>`,
+ }),
+ );
+ await page.goto('http://wheel.test/');
+ // Read without draining, so a wrong delta shows in the failure.
+ const seen = () =>
+ page.evaluate(() =>
+ (window as unknown as {__deltas: number[]}).__deltas.slice(),
+ );
+ expect(await page.evaluate(() => window.devicePixelRatio)).toBe(3);
+
+ const driver = await webInputDriver(page);
+ expect(driver.wheels).toBe(true);
+ await driver.wheel({x: 200, y: 300, dy: 100});
+ // Read once the page has the step, not at a time.
+ await expect.poll(seen).toEqual([100]);
+
+ // Playwright's own wheel, pinned: Chromium divides it by the ratio.
+ await page.mouse.move(200, 300);
+ await page.mouse.wheel(0, 100);
+ await expect
+ .poll(async () => (await seen())[1])
+ .toBeCloseTo(browserName === 'chromium' ? 100 / 3 : 100, 5);
+ } finally {
+ await context.close();
+ }
+ });
+
+ test("a wheel step that misses the main document throws its named error within the limit, while a frozen timer gate holds the page's timers too", async ({
+ browser,
+ }) => {
+ const context = await browser.newContext({
+ viewport: {width: 402, height: 714},
+ isMobile: false,
+ hasTouch: false,
+ });
+ try {
+ const page = await context.newPage();
+ // A frame over the whole page: a step there lands in the frame's
+ // document, never the main one.
+ await page.route('http://wheel-miss.test/', route =>
+ route.fulfill({
+ contentType: 'text/html',
+ body: '<!doctype html><body style="margin:0;height:3000px"><iframe srcdoc="<body style=height:3000px>" style="position:fixed;inset:0;width:100%;height:100%;border:0"></iframe>',
+ }),
+ );
+ await page.goto('http://wheel-miss.test/');
+ await installTimerGate(page);
+ const driver = await webInputDriver(page);
+ test.skip(!driver.wheels, WHEEL_SKIP);
+ await freezeTimers(page);
+ // Over the frame, the main document receives nothing, and the driver's
+ // own limit, not the test's timeout, ends the wait.
+ await expect(driver.wheel({x: 200, y: 300, dy: 100})).rejects.toThrow(
+ /did not receive the wheel step/,
+ );
+ await thawTimers(page);
+ } finally {
+ await context.close();
+ }
+ });
+
+ test('a wheel burst reaches the page as one run with its whole delta and no gap past the 100 ms a proof allows within a wheel gesture, re-taken once when the runner stalls it', async ({
+ browser,
+ }) => {
+ const context = await browser.newContext({
+ viewport: {width: 402, height: 714},
+ isMobile: false,
+ hasTouch: false,
+ });
+ try {
+ const page = await context.newPage();
+ // A gesture's listener: not passive, and it takes every step.
+ await page.route('http://wheel-burst.test/', route =>
+ route.fulfill({
+ contentType: 'text/html',
+ body: '<!doctype html><body style="margin:0;height:3000px"><script>window.__deltas=[];addEventListener("wheel",e=>{__deltas.push(e.deltaX);e.preventDefault();},{passive:false});</script>',
+ }),
+ );
+ await page.goto('http://wheel-burst.test/');
+ const driver = await webInputDriver(page);
+ test.skip(!driver.wheels, WHEEL_SKIP);
+ // A proof allows 100 ms between the steps of one wheel gesture: sent on
+ // its schedule, the run stays one gesture however long each step's
+ // round trip takes, and a runner stall past that bound is re-taken once.
+ await retakeOnWheelPacing(test.info(), async () => {
+ await page.evaluate(() => {
+ (window as unknown as {__deltas: number[]}).__deltas = [];
+ });
+ const {receivedSteps, receivedGapsMs} = await driver.wheelBurst({
+ x: 200,
+ y: 300,
+ steps: Array.from({length: 20}, () => ({dx: 40})),
+ maxGapMs: 100,
+ });
+ // Every pixel arrives, in steps of 40 px or, where the engine
+ // coalesced steps the page was still handling, their sums.
+ const deltas = await page.evaluate(
+ () => (window as unknown as {__deltas: number[]}).__deltas,
+ );
+ expect(deltas.reduce((sum, d) => sum + d, 0)).toBe(800);
+ expect(
+ deltas.every(d => d > 0 && d % 40 === 0),
+ String(deltas),
+ ).toBe(true);
+ expect(receivedSteps).toBe(deltas.length);
+ expect(receivedGapsMs).toHaveLength(receivedSteps - 1);
+ });
+ } finally {
+ await context.close();
+ }
+ });
+
+ test('a wheel burst sent slower than its maxGapMs throws WheelPacingError, in both engines', async ({
+ browser,
+ }) => {
+ // The negative control for the pacing check the re-take relies on: steps
+ // 180 ms apart, on a page that handles each at once, against a 100 ms
+ // bound.
+ const context = await browser.newContext({
+ viewport: {width: 402, height: 714},
+ isMobile: false,
+ hasTouch: false,
+ });
+ try {
+ const page = await context.newPage();
+ await page.route('http://wheel-slow-burst.test/', route =>
+ route.fulfill({
+ contentType: 'text/html',
+ body: '<!doctype html><body style="margin:0;height:3000px"><script>addEventListener("wheel",e=>e.preventDefault(),{passive:false});</script>',
+ }),
+ );
+ await page.goto('http://wheel-slow-burst.test/');
+ const driver = await webInputDriver(page);
+ test.skip(!driver.wheels, WHEEL_SKIP);
+ await expect(
+ driver.wheelBurst({
+ x: 200,
+ y: 300,
+ steps: Array.from({length: 4}, () => ({dx: 10})),
+ everyMs: 180,
+ maxGapMs: 100,
+ }),
+ ).rejects.toBeInstanceOf(WheelPacingError);
+ } finally {
+ await context.close();
+ }
+ });
+
+ test('a burst whose steps the dispatch spaces past maxGapMs throws WheelPacingError over a page whose listener takes 30 ms, in both engines', async ({
+ browser,
+ }) => {
+ // The page is free well before each next step arrives, so the gap is the
+ // dispatch's, not the page's.
+ const context = await browser.newContext({
+ viewport: {width: 402, height: 714},
+ isMobile: false,
+ hasTouch: false,
+ });
+ try {
+ const page = await context.newPage();
+ await page.route('http://wheel-busy-listener.test/', route =>
+ route.fulfill({
+ contentType: 'text/html',
+ body: '<!doctype html><body style="margin:0;height:3000px"><script>addEventListener("wheel",e=>{e.preventDefault();const end=performance.now()+30;while(performance.now()<end){}},{passive:false});</script>',
+ }),
+ );
+ await page.goto('http://wheel-busy-listener.test/');
+ const driver = await webInputDriver(page);
+ test.skip(!driver.wheels, WHEEL_SKIP);
+ await expect(
+ driver.wheelBurst({
+ x: 200,
+ y: 300,
+ steps: Array.from({length: 4}, () => ({dx: 10})),
+ everyMs: 125,
+ maxGapMs: 100,
+ }),
+ ).rejects.toBeInstanceOf(WheelPacingError);
+ } finally {
+ await context.close();
+ }
+ });
+
+ test('a page whose wheel listener holds its main thread splits a burst itself: never a runner stall, never re-taken', async ({
+ browser,
+ browserName,
+ }) => {
+ const context = await browser.newContext({
+ viewport: {width: 402, height: 714},
+ isMobile: false,
+ hasTouch: false,
+ });
+ try {
+ const page = await context.newPage();
+ // Each step blocks the main thread for 150 ms, past the 100 ms bound.
+ await page.route('http://wheel-stalling-page.test/', route =>
+ route.fulfill({
+ contentType: 'text/html',
+ body: '<!doctype html><body style="margin:0;height:3000px"><script>addEventListener("wheel",e=>{e.preventDefault();const end=performance.now()+150;while(performance.now()<end){}},{passive:false});</script>',
+ }),
+ );
+ await page.goto('http://wheel-stalling-page.test/');
+ const driver = await webInputDriver(page);
+ test.skip(!driver.wheels, WHEEL_SKIP);
+ const testInfo = {
+ annotations: [] as {type: string; description?: string}[],
+ };
+ const attempts: number[] = [];
+ const outcome = await retakeOnWheelPacing(testInfo, async n => {
+ attempts.push(n);
+ return driver.wheelBurst({
+ x: 200,
+ y: 300,
+ steps: Array.from({length: 4}, () => ({dx: 10})),
+ maxGapMs: 100,
+ });
+ }).then(
+ () => 'resolved',
+ (error: unknown) => error,
+ );
+ expect(outcome).not.toBeInstanceOf(WheelPacingError);
+ expect(attempts).toEqual([1]);
+ expect(testInfo.annotations).toEqual([]);
+ if (browserName === 'webkit') {
+ // WebKit dispatches the next step only once the page is free, so the
+ // page's stall widens the gaps, and the error names it.
+ expect(outcome).toBeInstanceOf(WheelPageStallError);
+ expect(String(outcome)).toMatch(/the page split the run/);
+ }
+ } finally {
+ await context.close();
+ }
+ });
+
+ /** A non-passive wheel listener: Chromium then waits for the page itself. */
+ const listenNonPassively = (page: Page) =>
+ page.evaluate(() =>
+ window.addEventListener('wheel', () => {}, {passive: false}),
+ );
+ /** The wheel steps the page received. */
+ const wheelsOf = async (page: Page) =>
+ (await readInputLog(page)).filter(r => r.type === 'wheel');
+
+ test('a wheel step reaches the page as exactly its deltas, trusted, with Control when held, by the time wheel() resolves on a page whose wheel listeners are all passive', async ({
+ page,
+ }) => {
+ await fixture(page);
+ const driver = await webInputDriver(page);
+ test.skip(!driver.wheels, WHEEL_SKIP);
+ await driver.wheel({x: 60, y: 520, dy: 120});
+ // The input log listens passively, so Chromium answers the dispatch
+ // before the page has the step: read right after the call.
+ expect(await wheelsOf(page)).toHaveLength(1);
+ await driver.wheel({x: 60, y: 520, dx: 30, dy: -40, ctrl: true});
+ const wheels = await wheelsOf(page);
+ expect(wheels).toHaveLength(2);
+ // Chromium's phone context has a device scale factor of 3: the driver
+ // multiplies back what Chromium divides by, so the page sees CSS px.
+ expect(wheels[0]).toMatchObject({
+ isTrusted: true,
+ deltaX: 0,
+ deltaY: 120,
+ deltaMode: 0,
+ ctrlKey: false,
+ x: 60,
+ y: 520,
+ });
+ expect(wheels[1]).toMatchObject({
+ isTrusted: true,
+ deltaX: 30,
+ deltaY: -40,
+ deltaMode: 0,
+ ctrlKey: true,
+ });
+ });
+
+ test('a wheel step reaches the page by the time wheel() resolves with a non-passive wheel listener too', async ({
+ page,
+ }) => {
+ await fixture(page);
+ const driver = await webInputDriver(page);
+ test.skip(!driver.wheels, WHEEL_SKIP);
+ await listenNonPassively(page);
+ await driver.wheel({x: 60, y: 520, dy: 80});
+ expect(await wheelsOf(page)).toHaveLength(1);
+ await driver.wheel({x: 60, y: 520, dy: -20, ctrl: true});
+ const wheels = await wheelsOf(page);
+ expect(wheels).toHaveLength(2);
+ expect(wheels[0]).toMatchObject({
+ isTrusted: true,
+ deltaY: 80,
+ ctrlKey: false,
+ });
+ expect(wheels[1]).toMatchObject({
+ isTrusted: true,
+ deltaY: -20,
+ ctrlKey: true,
+ });
+ });
+
+ test('a pen stroke reaches the page as trusted pen pointers, with its pressure, at its scripted times', async ({
+ page,
+ }) => {
+ await fixture(page);
+ const driver = await webInputDriver(page);
+ test.skip(!driver.pens, PEN_SKIP);
+ await driver.pen([
+ {x: 100, y: 100, t: 0, pressure: 0.3},
+ {x: 100, y: 140, t: 50, pressure: 0.6},
+ {x: 100, y: 180, t: 100, pressure: 0.6},
+ ]);
+ const log = await readInputLog(page);
+ const down = log.find(r => r.type === 'pointerdown');
+ const moves = log.filter(r => r.type === 'pointermove');
+ const up = log.find(r => r.type === 'pointerup');
+ expect(down).toMatchObject({
+ isTrusted: true,
+ pointerType: 'pen',
+ x: 100,
+ y: 100,
+ });
+ expect(down?.pressure).toBeCloseTo(0.3, 2);
+ expect(moves.at(-1)).toMatchObject({pointerType: 'pen', y: 180});
+ expect(moves.at(-1)?.pressure).toBeCloseTo(0.6, 2);
+ expect(up).toMatchObject({isTrusted: true, pointerType: 'pen'});
+ // The scripted 100 ms between the first and last points reach the page.
+ expect(
+ (moves.at(-1)?.timeStamp ?? NaN) - (down?.timeStamp ?? NaN),
+ ).toBeCloseTo(100, 0);
+ });
+
+ test('a stroke sent right after a navigation presses where it is scripted', async ({
+ page,
+ }) => {
+ // The driver exists before the page navigates, and the stroke goes out
+ // the moment the page has loaded: the press must not take the previous
+ // document's page scale (about:blank's, in the phone project).
+ const driver = await webInputDriver(page);
+ test.skip(!driver.pens, PEN_SKIP);
+ await fixture(page);
+ await driver.pen([
+ {x: 100, y: 100, t: 0, pressure: 0.5},
+ {x: 100, y: 120, t: 30, pressure: 0.5},
+ ]);
+ const down = (await readInputLog(page)).find(r => r.type === 'pointerdown');
+ expect(down).toMatchObject({pointerType: 'pen', x: 100, y: 100});
+ });
+
+ test('says which inputs it has: WebKit in a phone context has no wheel and no pen', async ({
+ page,
+ browserName,
+ }) => {
+ await fixture(page);
+ const driver = await webInputDriver(page);
+ if (browserName === 'chromium') {
+ expect({wheels: driver.wheels, pens: driver.pens}).toEqual({
+ wheels: true,
+ pens: true,
+ });
+ return;
+ }
+ expect({wheels: driver.wheels, pens: driver.pens}).toEqual({
+ wheels: false,
+ pens: false,
+ });
+ await expect(driver.wheel({x: 60, y: 520, dy: 120})).rejects.toThrow(
+ WHEEL_SKIP,
+ );
+ await expect(driver.pen([{x: 100, y: 100, t: 0}])).rejects.toThrow(
+ PEN_SKIP,
+ );
+ });
+
+ test.describe('in a desktop context', () => {
+ test.use({isMobile: false, hasTouch: false, deviceScaleFactor: 1});
+
+ test('a wheel step reaches the page as exactly its deltas in both engines', async ({
+ page,
+ }) => {
+ await fixture(page);
+ const driver = await webInputDriver(page);
+ expect(driver.wheels).toBe(true);
+ await driver.wheel({x: 60, y: 520, dy: 120});
+ expect(await wheelsOf(page)).toHaveLength(1);
+ await driver.wheel({x: 60, y: 520, dx: -25, dy: 0, ctrl: true});
+ const wheels = await wheelsOf(page);
+ expect(wheels).toHaveLength(2);
+ expect(wheels[0]).toMatchObject({
+ isTrusted: true,
+ deltaX: 0,
+ deltaY: 120,
+ deltaMode: 0,
+ ctrlKey: false,
+ });
+ expect(wheels[1]).toMatchObject({
+ isTrusted: true,
+ deltaX: -25,
+ deltaY: 0,
+ deltaMode: 0,
+ ctrlKey: true,
+ });
+ });
+ });
+});
+
test.describe('curve sampling', () => {
test('a CSS transition samples onto its cubic-bezier to 0.05 px', async ({
page,
diff --git a/internal/interaction-harness/src/index.ts b/internal/interaction-harness/src/index.ts
index 7a45ff45df..73ba38af0d 100644
--- a/internal/interaction-harness/src/index.ts
+++ b/internal/interaction-harness/src/index.ts
@@ -22,3 +22,4 @@ export * from './story';
export * from './storyboard';
export * from './touch';
export * from './trace';
+export * from './webInput';
diff --git a/internal/interaction-harness/src/touch.ts b/internal/interaction-harness/src/touch.ts
index 1c16c4b1f8..3a5803d1e6 100644
--- a/internal/interaction-harness/src/touch.ts
+++ b/internal/interaction-harness/src/touch.ts
@@ -265,6 +265,13 @@ export interface InputRecord {
readonly x?: number;
readonly y?: number;
readonly touches?: number;
+ /** A pointer event's pressure (a pen's, 0–1). */
+ readonly pressure?: number;
+ /** A wheel step's deltas, mode and Control key (webInput.ts). */
+ readonly deltaX?: number;
+ readonly deltaY?: number;
+ readonly deltaMode?: number;
+ readonly ctrlKey?: boolean;
readonly target: string;
}
@@ -276,20 +283,21 @@ const INPUT_LOG_SCRIPT = `(() => {
? node.tagName.toLowerCase() + (node.id ? '#' + node.id : '') + (node.getAttribute('aria-label') ? '[' + node.getAttribute('aria-label') + ']' : '')
: String(node && node.nodeName);
const types = ['pointerdown', 'pointermove', 'pointerup', 'pointercancel', 'touchstart', 'touchmove',
- 'touchend', 'touchcancel', 'click', 'contextmenu', 'gotpointercapture', 'lostpointercapture'];
+ 'touchend', 'touchcancel', 'click', 'contextmenu', 'gotpointercapture', 'lostpointercapture', 'wheel'];
for (const type of types) {
// Bubble phase on window, so defaultPrevented reflects the page's own handlers.
window.addEventListener(type, event => {
const record = {type, timeStamp: event.timeStamp, isTrusted: event.isTrusted, cancelable: event.cancelable,
defaultPrevented: event.defaultPrevented, target: describe(event.target)};
- if ('pointerId' in event) Object.assign(record, {pointerId: event.pointerId, pointerType: event.pointerType, x: event.clientX, y: event.clientY});
+ if ('pointerId' in event) Object.assign(record, {pointerId: event.pointerId, pointerType: event.pointerType, x: event.clientX, y: event.clientY, pressure: event.pressure});
+ if (type === 'wheel') Object.assign(record, {deltaX: event.deltaX, deltaY: event.deltaY, deltaMode: event.deltaMode, ctrlKey: event.ctrlKey, x: event.clientX, y: event.clientY});
if (event.touches) Object.assign(record, {touches: event.touches.length, x: event.changedTouches[0] && event.changedTouches[0].clientX, y: event.changedTouches[0] && event.changedTouches[0].clientY});
log.push(record);
}, {passive: true});
}
})()`;
-/** Records every pointer/touch/click the page receives (install before navigation). */
+/** Records every pointer, touch, click and wheel step the page receives (install before navigation). */
export async function installInputLog(page: Page): Promise<void> {
await page.addInitScript(INPUT_LOG_SCRIPT);
}
diff --git a/internal/interaction-harness/src/webInput.pacing.test.ts b/internal/interaction-harness/src/webInput.pacing.test.ts
new file mode 100644
index 0000000000..010fe67709
--- /dev/null
+++ b/internal/interaction-harness/src/webInput.pacing.test.ts
@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file webInput.pacing.test.ts
+ * @input webInput.ts's wheel pacing error and re-take
+ * @output Unit cases: a wheel burst's gaps past its bound are the page's when
+ * its own handling of the step before caused them, and the dispatch's
+ * otherwise; each error names its gaps; and a proof is re-taken once, only
+ * on a dispatch stall, with the re-take listed.
+ * @position Node unit tests beside the harness's browser self-tests.
+ *
+ * SYNC: When modified, update webInput.ts (wheelGapCauses, WheelPacingError,
+ * WheelPageStallError, retakeOnWheelPacing).
+ */
+
+import {describe, expect, it} from 'vitest';
+import {
+ retakeOnWheelPacing,
+ wheelGapCauses,
+ WheelPacingError,
+ WheelPageStallError,
+} from './webInput';
+
+describe('WheelPacingError', () => {
+ it('names the longest gap, the bound and every gap', () => {
+ const error = new WheelPacingError(100, [16, 16, 141, 0, 16]);
+ expect(error.name).toBe('WheelPacingError');
+ expect(error.message).toMatch(/a gap of 141 ms, over its 100 ms/);
+ expect(error.message).toMatch(/gaps 16, 16, 141, 0, 16 ms/);
+ expect(error.receivedGapsMs).toEqual([16, 16, 141, 0, 16]);
+ });
+});
+
+describe('wheelGapCauses', () => {
+ it('finds nothing within the bound', () => {
+ expect(
+ wheelGapCauses('webkit', [0, 16, 32, 48], [1, 17, 33, 49], 100),
+ ).toEqual({pageStalls: [], dispatchStalls: []});
+ });
+
+ it('gives a WebKit gap to the page when the step reached it within a frame of the listeners finishing the one before', () => {
+ // The listeners held the main thread 150 ms on the first step; the next
+ // was dispatched 2 ms after they finished.
+ expect(
+ wheelGapCauses('webkit', [0, 152, 168], [150, 153, 169], 100),
+ ).toEqual({
+ pageStalls: [{gapMs: 152, handlingMs: 150}],
+ dispatchStalls: [],
+ });
+ });
+
+ it('gives a WebKit gap to the dispatch when the page sat free before the step arrived', () => {
+ // A 30 ms listener, steps 125 ms apart: the page was free 95 ms before
+ // each next step.
+ expect(
+ wheelGapCauses('webkit', [0, 125, 250], [30, 155, 280], 100),
+ ).toEqual({
+ pageStalls: [],
+ dispatchStalls: [125, 125],
+ });
+ });
+
+ it('gives every Chromium gap to the dispatch, whose stamps the page cannot move', () => {
+ expect(
+ wheelGapCauses('chromium', [0, 120, 240], [25, 145, 265], 100),
+ ).toEqual({pageStalls: [], dispatchStalls: [120, 120]});
+ expect(
+ wheelGapCauses('chromium', [0, 152, 168], [150, 153, 169], 100),
+ ).toEqual({pageStalls: [], dispatchStalls: [152]});
+ });
+
+ it('counts a step whose handling was never seen as the dispatch\u2019s', () => {
+ expect(wheelGapCauses('webkit', [0, 150], [Number.NaN, 151], 100)).toEqual({
+ pageStalls: [],
+ dispatchStalls: [150],
+ });
+ });
+});
+
+describe('WheelPageStallError', () => {
+ it("names the page's handling, the gap and the bound, and is not a pacing error", () => {
+ const error = new WheelPageStallError(100, {gapMs: 152, handlingMs: 150});
+ expect(error.name).toBe('WheelPageStallError');
+ expect(error.message).toMatch(/took 150 ms to handle a step/);
+ expect(error.message).toMatch(/152 ms later, over its 100 ms/);
+ expect(error.message).toMatch(/the page split the run, not the runner/);
+ expect(error).not.toBeInstanceOf(WheelPacingError);
+ });
+});
+
+describe('retakeOnWheelPacing', () => {
+ const offPace = () => new WheelPacingError(100, [16, 120]);
+
+ it('stays red when both attempts are off pace, with one re-take listed', async () => {
+ const testInfo = {
+ annotations: [] as {type: string; description?: string}[],
+ };
+ let attempts = 0;
+ await expect(
+ retakeOnWheelPacing(testInfo, async () => {
+ attempts += 1;
+ throw offPace();
+ }),
+ ).rejects.toBeInstanceOf(WheelPacingError);
+ expect(attempts).toBe(2);
+ expect(testInfo.annotations.map(a => a.type)).toEqual(['wheel-retake']);
+ });
+
+ it('never re-takes a product failure after input that kept its pace', async () => {
+ const testInfo = {
+ annotations: [] as {type: string; description?: string}[],
+ };
+ let attempts = 0;
+ await expect(
+ retakeOnWheelPacing(testInfo, async () => {
+ attempts += 1;
+ throw new Error('the gallery did not page');
+ }),
+ ).rejects.toThrow('the gallery did not page');
+ expect(attempts).toBe(1);
+ expect(testInfo.annotations).toEqual([]);
+ });
+
+ it('never re-takes a stall the page caused', async () => {
+ const testInfo = {
+ annotations: [] as {type: string; description?: string}[],
+ };
+ let attempts = 0;
+ await expect(
+ retakeOnWheelPacing(testInfo, async () => {
+ attempts += 1;
+ throw new WheelPageStallError(100, {gapMs: 152, handlingMs: 150});
+ }),
+ ).rejects.toBeInstanceOf(WheelPageStallError);
+ expect(attempts).toBe(1);
+ expect(testInfo.annotations).toEqual([]);
+ });
+
+ it('passes on a good second attempt after one off pace, and lists the re-take', async () => {
+ const testInfo = {
+ annotations: [] as {type: string; description?: string}[],
+ };
+ const seen: number[] = [];
+ const result = await retakeOnWheelPacing(testInfo, async n => {
+ seen.push(n);
+ if (n === 1) {
+ throw offPace();
+ }
+ return 'paged';
+ });
+ expect(result).toBe('paged');
+ expect(seen).toEqual([1, 2]);
+ expect(testInfo.annotations).toEqual([
+ {type: 'wheel-retake', description: offPace().message},
+ ]);
+ });
+});
diff --git a/internal/interaction-harness/src/webInput.ts b/internal/interaction-harness/src/webInput.ts
new file mode 100644
index 0000000000..206d1ed5e9
--- /dev/null
+++ b/internal/interaction-harness/src/webInput.ts
@@ -0,0 +1,603 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file webInput.ts
+ * @input Uses a Playwright `Page` (Chromium or WebKit)
+ * @output `webInputDriver(page)`: a wheel step (`wheel({x, y, dx, dy, ctrl})`),
+ * a run of wheel steps as one gesture (`wheelBurst({x, y, steps})`) and a
+ * pen stroke (`pen(points)`) as REAL engine input, for proofs that the same
+ * motion works for every pointer, not only a finger (`spec:AST-100` FR4).
+ * @position The non-touch half of the input drivers; touch.ts is the touch
+ * half and owns the input log both are read through. Untrusted DOM events
+ * are not input (a component can tell them apart with `isTrusted`), so both
+ * go through the engine's own input pipeline.
+ *
+ * Chromium: CDP `Input.dispatchMouseEvent`.
+ * - A wheel step is a `mouseWheel` event at (x, y). Chromium divides the
+ * deltas it delivers by the device scale factor times the visual viewport's
+ * scale, so the driver multiplies them back: the page receives exactly `dx`
+ * and `dy` CSS px, in pixel mode (`deltaMode` 0). `ctrl` holds Control, as a
+ * trackpad pinch arrives. On a page whose wheel listeners are all passive
+ * (every page with the input log), Chromium answers the dispatch at once
+ * and delivers the step to the page afterwards, so `wheel` waits, through a
+ * one-shot passive listener, until the page has the step.
+ * - A pen stroke is pressed at its first point, moved through every point and
+ * released at the last, with `pointerType: 'pen'`, a pressure and an
+ * optional tilt, each event stamped with its scripted time: the page
+ * receives trusted pen pointer events (and the compatibility mouse events)
+ * with those timestamps. The stroke starts once the page has presented two
+ * frames: the press goes out with no page round trip, so right after a
+ * navigation it could carry the previous document's page scale (about:blank
+ * scales a press at 100 px to 41 px in the phone project).
+ * - A pen stroke over a native scroller does not pan it: Chromium sends the
+ * pen through its mouse pipeline, so the stroke scrolls nothing, raises no
+ * `pointercancel` and ends in a `click`.
+ *
+ * WebKit (Playwright's Linux build): `page.mouse.wheel` in a desktop context
+ * (`isMobile: false`, `hasTouch: false`), waiting the same way. The step
+ * moves the mouse to (x, y) first (a `pointermove`) and holds Control as a key,
+ * which Chromium's step does neither. WebKit's mobile emulation has no
+ * wheel input, and Playwright has no pen for WebKit: both throw, naming the
+ * reason, so a proof skips on the driver's flags instead.
+ *
+ * SYNC: Keep the engine limits above equal to the README's table and to the
+ * harness self-test (../src/harness.interaction.browser.spec.ts).
+ */
+
+import type {CDPSession, JSHandle, Page, TestInfo} from '@playwright/test';
+import type {Engine} from './touch';
+
+/** One wheel step: the page receives exactly `dx`, `dy` CSS px. */
+export interface WheelInput {
+ readonly x: number;
+ readonly y: number;
+ readonly dx?: number;
+ readonly dy?: number;
+ /** Hold Control during the step (a trackpad pinch arrives as a ctrl wheel). */
+ readonly ctrl?: boolean;
+}
+
+/** A run of wheel steps at one point: one continuous wheel gesture. */
+export interface WheelBurst {
+ readonly x: number;
+ readonly y: number;
+ /** Each step's deltas, in order: the page receives exactly these CSS px. */
+ readonly steps: readonly {readonly dx?: number; readonly dy?: number}[];
+ /** Ms between the steps' dispatch (default 16, a frame). */
+ readonly everyMs?: number;
+ /** Hold Control through the run. */
+ readonly ctrl?: boolean;
+ /**
+ * The longest gap the page may stamp between two received steps, ms: the
+ * gap after which the proof's component would treat the run as more than
+ * one gesture. Past it `wheelBurst` throws `WheelPageStallError` when the
+ * page's own handling of the step before caused the gap, and
+ * `WheelPacingError` otherwise.
+ */
+ readonly maxGapMs?: number;
+}
+
+/**
+ * The page stamped a wheel burst's steps further apart than the proof's
+ * `maxGapMs`, and its wheel listeners did not hold the step back: the step
+ * reached the page later than one frame after they finished the one before.
+ * WebKit stamps a step when its web process dispatches it, so a loaded runner
+ * splits what the driver sent as one gesture. Other work on the page's main
+ * thread between steps (timers, frame callbacks) also lands here, so a
+ * re-taken run is the runner's or that work's, never the wheel listeners'.
+ */
+export class WheelPacingError extends Error {
+ constructor(
+ readonly maxGapMs: number,
+ readonly receivedGapsMs: readonly number[],
+ ) {
+ super(
+ `webInputDriver: the page received the wheel burst with a gap of ${Math.max(...receivedGapsMs).toFixed(0)} ms, over its ${maxGapMs} ms (gaps ${receivedGapsMs.map(g => g.toFixed(0)).join(', ')} ms): the dispatch stalled before the page, so the page saw more than one gesture`,
+ );
+ this.name = 'WheelPacingError';
+ }
+}
+
+/**
+ * The page stamped a wheel burst's steps further apart than the proof's
+ * `maxGapMs` because it was still handling the step before: its own wheel
+ * listeners held the main thread, and WebKit dispatches the next step only
+ * once it is free. The page split the gesture, so this is the proof's own
+ * failure, never re-taken.
+ */
+export class WheelPageStallError extends Error {
+ constructor(
+ readonly maxGapMs: number,
+ readonly stall: WheelPageStall,
+ ) {
+ super(
+ `webInputDriver: the page's own wheel listeners took ${stall.handlingMs.toFixed(0)} ms to handle a step, so the next reached it ${stall.gapMs.toFixed(0)} ms later, over its ${maxGapMs} ms: the page split the run, not the runner`,
+ );
+ this.name = 'WheelPageStallError';
+ }
+}
+
+/** A gap the page caused: how long it was, and how long the page spent handling the step before it. */
+export interface WheelPageStall {
+ readonly gapMs: number;
+ readonly handlingMs: number;
+}
+
+/**
+ * How soon after the page's wheel listeners finish one step the next must
+ * reach the page for the page to have held it back: one frame, with a few ms
+ * for the dispatch itself.
+ */
+const HELD_BACK_MS = 20;
+
+/**
+ * Sorts a burst's gaps past `maxGapMs` by cause. `stamps` are the received
+ * steps' `timeStamp`s; `handledAt` is when the page's wheel listeners had
+ * finished with each (NaN where that was not seen). In WebKit, which
+ * dispatches a step only once the page's main thread is free, a gap is the
+ * page's when the step reached the page within one frame of the listeners
+ * finishing the step before: it was waiting on them. Every other gap is the
+ * dispatch's, and in Chromium, which stamps a step with its dispatch time, so
+ * the page cannot move its stamps, every gap is. Other work on the page's main
+ * thread between steps (timers, frame callbacks) counts as the dispatch's.
+ */
+export function wheelGapCauses(
+ engine: Engine,
+ stamps: readonly number[],
+ handledAt: readonly number[],
+ maxGapMs: number,
+): {pageStalls: WheelPageStall[]; dispatchStalls: number[]} {
+ const pageStalls: WheelPageStall[] = [];
+ const dispatchStalls: number[] = [];
+ for (let i = 1; i < stamps.length; i++) {
+ const gapMs = stamps[i] - stamps[i - 1];
+ if (gapMs <= maxGapMs) {
+ continue;
+ }
+ const heldBack =
+ engine === 'webkit' &&
+ Number.isFinite(handledAt[i - 1]) &&
+ stamps[i] - handledAt[i - 1] <= HELD_BACK_MS;
+ if (heldBack) {
+ pageStalls.push({gapMs, handlingMs: handledAt[i - 1] - stamps[i - 1]});
+ } else {
+ dispatchStalls.push(gapMs);
+ }
+ }
+ return {pageStalls, dispatchStalls};
+}
+
+/**
+ * Runs a wheel proof through `attempt`, and once more when the page received
+ * its burst off pace: `attempt` builds the page's state, sends the burst with
+ * `maxGapMs` and makes the spec's assertions, so a re-take starts over. One
+ * re-take, two attempts in all, and only on a `WheelPacingError`: any other
+ * error (a `WheelPageStallError`, which the page's wheel listeners caused,
+ * among them), and a second `WheelPacingError`, fail the test with their own
+ * cause. A `WheelPacingError` is the runner's or other work on the page's main
+ * thread between steps, so a re-take does not clear the page of that work.
+ * Each re-take is listed in the report as a `wheel-retake` annotation.
+ */
+export async function retakeOnWheelPacing<T>(
+ testInfo: Pick<TestInfo, 'annotations'>,
+ attempt: (n: 1 | 2) => Promise<T>,
+): Promise<T> {
+ try {
+ return await attempt(1);
+ } catch (error) {
+ if (!(error instanceof WheelPacingError)) {
+ throw error;
+ }
+ testInfo.annotations.push({
+ type: 'wheel-retake',
+ description: error.message,
+ });
+ return attempt(2);
+ }
+}
+
+/** A point of a pen stroke. */
+export interface PenPoint {
+ readonly x: number;
+ readonly y: number;
+ /** Ms after the stroke's first point. */
+ readonly t: number;
+ /** 0–1 (default 0.5) while the pen touches. */
+ readonly pressure?: number;
+ /** Degrees, -90–90 (default 0). */
+ readonly tiltX?: number;
+ readonly tiltY?: number;
+}
+
+export interface WebInputDriver {
+ readonly engine: Engine;
+ /** Whether `wheel` works in this page (WebKit's mobile emulation has none). */
+ readonly wheels: boolean;
+ /** Whether `pen` works in this page (Chromium only). */
+ readonly pens: boolean;
+ wheel(input: WheelInput): Promise<void>;
+ /**
+ * Sends a run of steps at one point on its schedule, without waiting for
+ * each step's round trip as `wheel` does, and resolves once the page has
+ * received the run's whole delta. Awaited steps land as far apart as a
+ * round trip takes on a loaded runner (49 to 141 ms in WebKit), past the
+ * 100 ms a proof may allow between the steps of one gesture. Where the page still
+ * handles one step when the next arrives, the engine coalesces them, as it
+ * does a trackpad's: the page can receive fewer, larger steps with the same
+ * total. Returns how many steps the page received and the gaps between
+ * their `timeStamp`s, ms; with `maxGapMs`, a longer gap throws
+ * `WheelPageStallError` when the page's own handling of the step before
+ * caused it, and `WheelPacingError` otherwise.
+ */
+ wheelBurst(burst: WheelBurst): Promise<{
+ readonly receivedSteps: number;
+ readonly receivedGapsMs: readonly number[];
+ }>;
+ /** Presses at the first point, moves through all of them, releases at the last; paced on the wall clock. */
+ pen(points: readonly PenPoint[]): Promise<void>;
+}
+
+/** Why a proof skips when the driver has no wheel in this page. */
+export const WHEEL_SKIP =
+ "WebKit's mobile emulation has no wheel input: run wheel proofs in a desktop context";
+/** Why a proof skips when the driver has no pen. */
+export const PEN_SKIP =
+ 'Playwright has no pen input for WebKit: pen proofs run in Chromium';
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+/** How long `wheel` waits for the page to receive its step. */
+const WHEEL_DELIVERY_MS = 2000;
+
+/**
+ * Arms a one-shot passive capture listener for the page's next wheel step,
+ * before the step is dispatched. Passive, so the page's own listeners keep
+ * deciding whether the engine waits for it. (The promise sits in an object:
+ * a handle to a bare promise would wait for it to settle.)
+ */
+function armWheel(page: Page): Promise<JSHandle<{received: Promise<void>}>> {
+ return page.evaluateHandle(() => ({
+ received: new Promise<void>(resolve => {
+ window.addEventListener('wheel', () => resolve(), {
+ capture: true,
+ once: true,
+ passive: true,
+ });
+ }),
+ }));
+}
+
+/** Waits until the armed listener has seen the step; throws past the limit. */
+async function untilReceived(
+ page: Page,
+ armed: JSHandle<{received: Promise<void>}>,
+): Promise<void> {
+ const received = await page.evaluate(
+ ([box, ms]) => {
+ // The harness's own wait runs on the real timer: a frozen timer gate
+ // (story.ts) holds only the page's.
+ const later =
+ (
+ window as unknown as {
+ __harnessTimerGate?: {timeout?: typeof setTimeout};
+ }
+ ).__harnessTimerGate?.timeout ?? window.setTimeout.bind(window);
+ return Promise.race([
+ box.received.then(() => true),
+ new Promise<boolean>(resolve => later(() => resolve(false), ms)),
+ ]);
+ },
+ [armed, WHEEL_DELIVERY_MS] as const,
+ );
+ await armed.dispose();
+ if (!received) {
+ throw new Error(
+ `webInputDriver: the page did not receive the wheel step within ${WHEEL_DELIVERY_MS} ms (is the point inside the viewport, over the main document?)`,
+ );
+ }
+}
+
+interface WheelRun {
+ stamps: number[];
+ /** When the page's wheel listeners had finished with each step; NaN until seen. */
+ handledAt: number[];
+ dx: number;
+ dy: number;
+ stop: () => void;
+}
+
+/**
+ * Arms a passive capture listener that stamps every wheel step the page
+ * receives and sums its deltas, before a burst is dispatched, and a passive
+ * bubble listener on the window, after the page's own, that notes when the
+ * page has finished with each step (a step whose propagation the page stops
+ * is never noted, and counts as handled at once).
+ */
+function armWheelRun(page: Page): Promise<JSHandle<WheelRun>> {
+ return page.evaluateHandle(() => {
+ const first = {capture: true, passive: true};
+ const last = {capture: false, passive: true};
+ const run = {
+ stamps: [] as number[],
+ handledAt: [] as number[],
+ dx: 0,
+ dy: 0,
+ stop: () => {
+ window.removeEventListener('wheel', received, first);
+ window.removeEventListener('wheel', handled, last);
+ },
+ };
+ const received = (event: Event) => {
+ const wheel = event as WheelEvent;
+ run.stamps.push(wheel.timeStamp);
+ run.handledAt.push(Number.NaN);
+ run.dx += wheel.deltaX;
+ run.dy += wheel.deltaY;
+ };
+ const handled = () => {
+ run.handledAt[run.handledAt.length - 1] = performance.now();
+ };
+ window.addEventListener('wheel', received, first);
+ window.addEventListener('wheel', handled, last);
+ return run;
+ });
+}
+
+/**
+ * Waits until the armed listener has summed the run's whole delta and returns
+ * what it received; throws past the limit, naming how much arrived.
+ */
+async function untilRunReceived(
+ page: Page,
+ engine: Engine,
+ armed: JSHandle<WheelRun>,
+ {steps, maxGapMs}: Pick<WheelBurst, 'steps' | 'maxGapMs'>,
+): Promise<{receivedSteps: number; receivedGapsMs: number[]}> {
+ const want = steps.reduce<{dx: number; dy: number}>(
+ (sum, {dx = 0, dy = 0}) => ({dx: sum.dx + dx, dy: sum.dy + dy}),
+ {dx: 0, dy: 0},
+ );
+ const got = await page.evaluate(
+ ([run, total, ms]) =>
+ new Promise<{
+ stamps: number[];
+ handledAt: number[];
+ dx: number;
+ dy: number;
+ }>(resolve => {
+ // The harness's own wait runs on the real timer: a frozen timer gate
+ // (story.ts) holds only the page's.
+ const later =
+ (
+ window as unknown as {
+ __harnessTimerGate?: {timeout?: typeof setTimeout};
+ }
+ ).__harnessTimerGate?.timeout ?? window.setTimeout.bind(window);
+ const deadline = performance.now() + ms;
+ const whole = () =>
+ Math.abs(run.dx - total.dx) < 0.01 &&
+ Math.abs(run.dy - total.dy) < 0.01;
+ const check = () => {
+ if (whole() || performance.now() > deadline) {
+ run.stop();
+ resolve({
+ stamps: run.stamps.slice(),
+ handledAt: run.handledAt.slice(),
+ dx: run.dx,
+ dy: run.dy,
+ });
+ } else {
+ later(check, 10);
+ }
+ };
+ check();
+ }),
+ [armed, want, WHEEL_DELIVERY_MS] as const,
+ );
+ await armed.dispose();
+ if (
+ Math.abs(got.dx - want.dx) >= 0.01 ||
+ Math.abs(got.dy - want.dy) >= 0.01
+ ) {
+ throw new Error(
+ `webInputDriver: the page received ${got.dx}, ${got.dy} px of the run's ${want.dx}, ${want.dy} px within ${WHEEL_DELIVERY_MS} ms (is the point inside the viewport, over the main document?)`,
+ );
+ }
+ const receivedGapsMs = got.stamps.slice(1).map((t, i) => t - got.stamps[i]);
+ if (maxGapMs != null) {
+ const {pageStalls, dispatchStalls} = wheelGapCauses(
+ engine,
+ got.stamps,
+ got.handledAt,
+ maxGapMs,
+ );
+ if (pageStalls.length > 0) {
+ throw new WheelPageStallError(maxGapMs, pageStalls[0]);
+ }
+ if (dispatchStalls.length > 0) {
+ throw new WheelPacingError(maxGapMs, receivedGapsMs);
+ }
+ }
+ return {receivedSteps: got.stamps.length, receivedGapsMs};
+}
+
+/**
+ * Sends each step at its scheduled time without awaiting the one before, then
+ * waits until every dispatch is answered.
+ */
+async function dispatchOnSchedule<T>(
+ steps: readonly T[],
+ everyMs: number,
+ send: (step: T) => Promise<unknown>,
+): Promise<void> {
+ const start = Date.now();
+ const sent: Promise<unknown>[] = [];
+ for (const [i, step] of steps.entries()) {
+ const wait = start + i * everyMs - Date.now();
+ if (wait > 0) {
+ await sleep(wait);
+ }
+ sent.push(send(step));
+ }
+ await Promise.all(sent);
+}
+
+async function chromiumWebInput(page: Page): Promise<WebInputDriver> {
+ const cdp: CDPSession = await page.context().newCDPSession(page);
+ return {
+ engine: 'chromium',
+ wheels: true,
+ pens: true,
+ async wheel({x, y, dx = 0, dy = 0, ctrl = false}) {
+ const scale = await page.evaluate(
+ () => window.devicePixelRatio * (window.visualViewport?.scale ?? 1),
+ );
+ const armed = await armWheel(page);
+ await cdp.send('Input.dispatchMouseEvent', {
+ type: 'mouseWheel',
+ x,
+ y,
+ deltaX: dx * scale,
+ deltaY: dy * scale,
+ modifiers: ctrl ? 2 : 0,
+ });
+ await untilReceived(page, armed);
+ },
+ async wheelBurst({x, y, steps, everyMs = 16, ctrl = false, maxGapMs}) {
+ const scale = await page.evaluate(
+ () => window.devicePixelRatio * (window.visualViewport?.scale ?? 1),
+ );
+ const armed = await armWheelRun(page);
+ await dispatchOnSchedule(steps, everyMs, ({dx = 0, dy = 0}) =>
+ cdp.send('Input.dispatchMouseEvent', {
+ type: 'mouseWheel',
+ x,
+ y,
+ deltaX: dx * scale,
+ deltaY: dy * scale,
+ modifiers: ctrl ? 2 : 0,
+ }),
+ );
+ return untilRunReceived(page, 'chromium', armed, {steps, maxGapMs});
+ },
+ async pen(points) {
+ if (points.length === 0) {
+ return;
+ }
+ // Two presented frames first: the press reaches the compositor with no
+ // page round trip, and right after a navigation it could still carry
+ // the previous document's page scale. The harness's own frames, not a
+ // frozen timer gate's (story.ts).
+ await page.evaluate(
+ () =>
+ new Promise<void>(resolve => {
+ const gate = (
+ window as unknown as {
+ __harnessTimerGate?: {frame?: typeof requestAnimationFrame};
+ }
+ ).__harnessTimerGate;
+ const frame =
+ gate?.frame ?? window.requestAnimationFrame.bind(window);
+ frame(() => frame(() => resolve()));
+ }),
+ );
+ const startWall = Date.now();
+ const startStamp = Date.now() / 1000;
+ const events = [
+ {type: 'mousePressed' as const, point: points[0]},
+ ...points.slice(1).map(point => ({type: 'mouseMoved' as const, point})),
+ {type: 'mouseReleased' as const, point: points[points.length - 1]},
+ ];
+ for (const {type, point} of events) {
+ const wait = startWall + point.t - Date.now();
+ if (wait > 0) {
+ await sleep(wait);
+ }
+ await cdp.send('Input.dispatchMouseEvent', {
+ type,
+ x: point.x,
+ y: point.y,
+ button: 'left',
+ buttons: type === 'mouseReleased' ? 0 : 1,
+ clickCount: type === 'mouseMoved' ? 0 : 1,
+ pointerType: 'pen',
+ force: type === 'mouseReleased' ? 0 : (point.pressure ?? 0.5),
+ tiltX: point.tiltX ?? 0,
+ tiltY: point.tiltY ?? 0,
+ timestamp: startStamp + point.t / 1000,
+ });
+ }
+ },
+ };
+}
+
+async function webkitWebInput(page: Page): Promise<WebInputDriver> {
+ // Playwright refuses a wheel in a WebKit context that emulates a phone: read
+ // the option it reads, the context's `isMobile`.
+ const mobile =
+ (page.context() as unknown as {_options?: {isMobile?: boolean}})._options
+ ?.isMobile === true;
+ return {
+ engine: 'webkit',
+ wheels: !mobile,
+ pens: false,
+ async wheel({x, y, dx = 0, dy = 0, ctrl = false}) {
+ if (mobile) {
+ throw new Error(`webInputDriver: ${WHEEL_SKIP}`);
+ }
+ await page.mouse.move(x, y);
+ if (ctrl) {
+ await page.keyboard.down('Control');
+ }
+ try {
+ const armed = await armWheel(page);
+ await page.mouse.wheel(dx, dy);
+ await untilReceived(page, armed);
+ } finally {
+ if (ctrl) {
+ await page.keyboard.up('Control');
+ }
+ }
+ },
+ async wheelBurst({x, y, steps, everyMs = 16, ctrl = false, maxGapMs}) {
+ if (mobile) {
+ throw new Error(`webInputDriver: ${WHEEL_SKIP}`);
+ }
+ await page.mouse.move(x, y);
+ if (ctrl) {
+ await page.keyboard.down('Control');
+ }
+ try {
+ const armed = await armWheelRun(page);
+ await dispatchOnSchedule(steps, everyMs, ({dx = 0, dy = 0}) =>
+ page.mouse.wheel(dx, dy),
+ );
+ return await untilRunReceived(page, 'webkit', armed, {
+ steps,
+ maxGapMs,
+ });
+ } finally {
+ if (ctrl) {
+ await page.keyboard.up('Control');
+ }
+ }
+ },
+ async pen() {
+ throw new Error(`webInputDriver: ${PEN_SKIP}`);
+ },
+ };
+}
+
+/** Wheel and pen input for the page's engine. Firefox is not supported (no project). */
+export async function webInputDriver(page: Page): Promise<WebInputDriver> {
+ const name = page.context().browser()?.browserType().name();
+ if (name === 'chromium') {
+ return chromiumWebInput(page);
+ }
+ if (name === 'webkit') {
+ return webkitWebInput(page);
+ }
+ throw new Error(
+ `webInputDriver: no wheel or pen input path for ${name ?? 'this browser'}`,
+ );
+}