An open source design system that's fully customizable and agent ready
TypeScript
feat(interaction): Chromium rendering traces, the compositor presentation record and the long-task log (#8548)
Cindy Zhangacda0a187bea
diff --git a/internal/interaction-harness/README.md b/internal/interaction-harness/README.mdindex 4c67256a26..b7f583829f 100644--- a/internal/interaction-harness/README.md+++ b/internal/interaction-harness/README.md@@ -10,9 +10,10 @@ pixels per CSS px, touch, mobile viewport rules), in Chromium and WebKit.The harness proves its own instruments in[`src/harness.interaction.browser.spec.ts`](src/harness.interaction.browser.spec.ts).-The busy-main-thread proof has a negative control beside its positive check-(a rAF animation that freezes under a blocked main thread); other self-tests-check an instrument against a known answer.+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@@ -41,17 +42,18 @@ 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), `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. |-| `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`. |-| `storyboard.ts` | `animationStoryboard` (seek to t = 0, 16.7, 33.3 … ms), `touchStoryboard` (a frame per scripted event): PNG contact sheet + JSON trace. |-| `output.ts` | `evidenceDir`, `writeEvidence`: where evidence goes and how it is attached to the report. |-| `story.ts` | `phone`, `withStorybook`, `openStory`, `frames`, and the timer gate (`installTimerGate`, `freezeTimers`, `thawTimers`). |+| 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), `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. |+| `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`. |+| `storyboard.ts` | `animationStoryboard` (seek to t = 0, 16.7, 33.3 … ms), `touchStoryboard` (a frame per scripted event): PNG contact sheet + JSON trace. |+| `output.ts` | `evidenceDir`, `writeEvidence`: where evidence goes and how it is attached to the report. |+| `story.ts` | `phone`, `withStorybook`, `openStory`, `frames`, and the timer gate (`installTimerGate`, `freezeTimers`, `thawTimers`). |## The proofs@@ -155,8 +157,11 @@ two steps per frame, which never fails it. Move a proof's element at least twosteps a frame: the self-tests move 560 px in 1,600 ms, about 4.8 px a frame.On a loaded machine Chromium's screencast can skip frames the compositor-still presents. Pass when the compositor presented each frame (epoch ms on the-page clock, from a trace of `Display::FrameDisplayed`) as `presented`. A gap between two moved+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 movedframes with nothing delivered inside it is then measured between thecompositor's own frames: the frames it presented there count as presented(`recorderSkipped`, in the summary), and a gap it did not present through is@@ -165,8 +170,18 @@ delivered frame that did not move, is judged from the screencast, so afrozen element fails whatever else the compositor draws (a rAF animation'sblock presents no compositor frame at all). With the record, the 90% counts thecompositor's frames from the first to the last moved frame; the gaps before and-after are the stall check's. Without a record (WebKit has no such trace), the-screencast is judged alone.+after are the stall check's. WebKit has no such trace:+`stop()` resolves to `[]` and the screencast is judged alone.++**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. Its+`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 a long task, whether it calls page code+directly or sets it off.**Storyboards.** Deterministic: frames come from seeking held animations orfrom stepping scripted input, never from wall-clock capture. The JSON trace@@ -200,6 +215,8 @@ in all, and lists each retake under `recaptures` in the trace.| 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 |What WebKit cannot show here — native scroll hand-off, flings, a fingerlifting while another stays down, finger tracking under a busy main thread, anddiff --git a/internal/interaction-harness/src/busy.skip.fixture.ts b/internal/interaction-harness/src/busy.skip.fixture.tsnew file mode 100644index 0000000000..409886f12e--- /dev/null+++ b/internal/interaction-harness/src/busy.skip.fixture.ts@@ -0,0 +1,125 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file busy.skip.fixture.ts+ * @input One recorded busy-main-thread run in headless Chromium under+ * parallel load: a compositor coast through a 566 ms block+ * @output `frames`: the screencast frames the marker was tracked in, as+ * [ms after the block started, y in CSS px, or null where the marker was not+ * found]; `presented`: when the compositor presented each frame+ * (`Display::FrameDisplayed`), ms after the block started; `block`: the+ * block's span on the same clock. The screencast skipped frames at about+ * +366 and +466 ms while the compositor kept presenting every 16.7 ms.+ * @position Fixture for busy.test.ts+ */++export const block = {from: 0, to: 566.1};++export const frames: ReadonlyArray<readonly [number, number | null]> = [+ [-1145.8, null],+ [-1114, null],+ [-1063.9, null],+ [-1031.1, null],+ [-996.6, null],+ [-964.3, null],+ [-930.7, null],+ [-896.7, null],+ [-864, null],+ [-830.6, null],+ [-797.8, null],+ [-762.7, null],+ [-731.3, null],+ [-686.5, null],+ [-680.8, null],+ [-651, null],+ [-634.1, null],+ [-620.7, null],+ [-615.8, null],+ [-514.4, null],+ [-495, null],+ [-472.4, null],+ [-465.3, null],+ [-448.5, null],+ [-430.3, null],+ [-414.8, null],+ [-398.3, null],+ [-379.5, null],+ [-364.2, null],+ [-348.3, null],+ [-330.6, null],+ [-315, null],+ [-297.6, null],+ [-281.9, null],+ [-265.1, null],+ [-247.6, null],+ [-230.8, null],+ [-215.3, null],+ [-198.6, null],+ [-181, null],+ [-165.3, null],+ [-147.7, null],+ [-132, null],+ [-115.4, null],+ [-98.5, null],+ [-81.2, 504],+ [-65.2, 500],+ [-48.5, 496],+ [-30.9, 491],+ [-15.2, 487],+ [1.3, 484],+ [32.8, 480],+ [49.8, 476],+ [66.3, 473],+ [82.8, 469],+ [99.7, 466],+ [116.1, 463],+ [132.9, 460],+ [149.5, 457],+ [166.3, 454],+ [182.9, 451],+ [199.4, 448],+ [216.2, 446],+ [232.8, 443],+ [249.4, 441],+ [266.1, 438],+ [282.7, 436],+ [299.5, 434],+ [316, 432],+ [332.7, 430],+ [349.5, 428],+ [366.1, 426],+ [433.1, 418],+ [449.7, 417],+ [466.2, 415],+ [516.2, 411],+ [532.8, 409],+ [549.5, 408],+ [566.2, 407],+ [650.6, 401],+ [666.2, 400],+ [682.9, 399],+ [699.6, 398],+ [716.3, 397],+ [816.1, 391],+ [832.8, 391],+ [849.5, 390],+ [866.2, 389],+ [882.9, 388],+ [899.5, 388],+ [916.1, 387],+ [1033.8, 383],+ [1050.1, 383],+ [1066.7, 382],+ [1083.3, 382],+ [1099.5, 381],+ [1117.3, 381],+ [1134.2, 380],+ [1149.5, 380],+];++export const presented: readonly number[] = [+ -98.7, -81.3, -65.3, -48.7, -31.1, -15.3, 1.3, 32.5, 49.6, 66.1, 82.7, 99.6,+ 115.9, 132.6, 149.3, 166.1, 182.6, 199.3, 216, 232.6, 249.3, 266, 282.6,+ 299.2, 315.8, 332.6, 349.3, 366, 381.5, 398.3, 415.1, 432.9, 449.6, 466.1,+ 481.5, 498.3, 516, 532.6, 549.4, 566.1, 581.7, 598.4, 615, 631.6, 650.3, 666,+];diff --git a/internal/interaction-harness/src/busy.test.ts b/internal/interaction-harness/src/busy.test.tsindex 372860125f..44a2446ecc 100644--- a/internal/interaction-harness/src/busy.test.ts+++ b/internal/interaction-harness/src/busy.test.ts@@ -14,6 +14,7 @@import {describe, expect, it} from 'vitest';import {busyWindowProof} from './busy';+import * as skip from './busy.skip.fixture';import {inPresentationOrder, type TrackedFrame} from './frames';const FRAME = 1000 / 60;@@ -361,6 +362,15 @@ function drawn(return draws;}+const skipFrames = (): TrackedFrame[] =>+ skip.frames.map(+ ([t, y]) =>+ ({+ t,+ box: y == null ? null : {x: 0, y, width: 10, height: 10},+ }) as TrackedFrame,+ );+describe('busyWindowProof with the compositor record', () => {it('with a compositor record, judges a sparse cast from its first to its last moved frame', () => {// One screencast frame in six, as on a loaded machine, with the compositor@@ -402,6 +412,29 @@ describe('busyWindowProof with the compositor record', () => {expect(clean.movedFraction).toBeLessThanOrEqual(1);});+ it('reads frames the screencast skipped while the compositor presented them as presented: a recorded run that fails without the record', () => {+ const frames = skipFrames();+ const alone = busyWindowProof(frames, skip.block, {settledWithin: 1});+ expect(alone.verdict.failures.join('\n')).toMatch(+ /longest stall 6\d\.\d ms = 4 intervals > 3/,+ );+ // Every frame the screencast delivered moved: only the stall remains,+ // which the record resolves.+ expect(alone.verdict.failures.join('\n')).not.toMatch(+ /expected frames moved/,+ );+ const proof = busyWindowProof(frames, skip.block, {+ settledWithin: 1,+ presented: skip.presented,+ });+ expect(proof.verdict.failures).toEqual([]);+ expect(proof.recorderSkipped).toBe(5);+ expect(proof.longestStallFrames).toBeLessThanOrEqual(2);+ expect(proof.summary).toMatch(+ /the screencast skipped 5 frames the compositor presented \(at \+3\d\d ms, \+4\d\d ms\)/,+ );+ });+it('counts a gap the compositor drew through as skipped, and one it did not draw through as a stall', () => {const k = at(1300);const gap: [number, number] = [diff --git a/internal/interaction-harness/src/busy.ts b/internal/interaction-harness/src/busy.tsindex 20c3d86a11..55fd9d670d 100644--- a/internal/interaction-harness/src/busy.ts+++ b/internal/interaction-harness/src/busy.ts@@ -67,6 +67,8 @@ export async function blockMainThread(const minProgress = Math.max(minProgressMs, ONE_FRAME_MS);if (during == null) {return page.evaluate(duration => {+ // The harness's own work: a trace sets it apart (trace.ts HARNESS_READ).+ console.timeStamp('harness-read');const from = performance.timeOrigin + performance.now();const end = performance.now() + duration;let spins = 0;@@ -252,8 +254,8 @@ export interface BusyProof extends FrameStats {* no step and read as not moved, which the proof notes (never a failure).** A loaded machine's screencast can skip frames the compositor still presents- * (Chromium). Given the compositor's record (`presented`: when it presented- * each frame), a gap between two moved frames with no frame+ * (Chromium). Given the compositor's record (`presented`, from+ * `startCompositorTrace`), a gap between two moved frames with no frame* delivered inside it is measured between the compositor's own frames: it is* a stall only where the compositor presented nothing, and the frames it did* present there are neither stalls nor misses (`recorderSkipped`). A gap@@ -310,8 +312,8 @@ export function busyWindowProof(settledAt?: number;/*** When the compositor presented each frame, epoch ms on the page clock- * (Chromium's `Display::FrameDisplayed`). Empty or absent, the screencast- * is judged alone.+ * (`startCompositorTrace`; Chromium). Empty or absent, the screencast is+ * judged alone.*/presented?: readonly number[];} = {},diff --git a/internal/interaction-harness/src/curves.ts b/internal/interaction-harness/src/curves.tsindex 69b9908066..52d187ea0a 100644--- a/internal/interaction-harness/src/curves.ts+++ b/internal/interaction-harness/src/curves.ts@@ -900,6 +900,8 @@ export async function waitForAnimation(evaluateTimeout =>locator.evaluate((element, {minProgress, since: watchedFrom}) => {+ // The harness's own read: a trace sets it apart (trace.ts HARNESS_READ).+ console.timeStamp('harness-read');const w = window as unknown as {__harnessCurveEnd: (a: Animation) => number;__harnessAnimations: {diff --git a/internal/interaction-harness/src/harness.interaction.browser.spec.ts b/internal/interaction-harness/src/harness.interaction.browser.spec.tsindex a6c73fdf88..d5ecffece8 100644--- a/internal/interaction-harness/src/harness.interaction.browser.spec.ts+++ b/internal/interaction-harness/src/harness.interaction.browser.spec.ts@@ -4,12 +4,14 @@* @file harness.interaction.browser.spec.ts* @input Fixture pages written inline (no Storybook), real Chromium/WebKit* @output Proof that each harness instrument measures what it claims (the- * busy-main-thread proof with a negative control beside its positive- * check): scripted timestamps reach 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;- * sampled curves+ * 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@@ -35,6 +37,7 @@ import {blockMainThread,busyWindowProof,compareCurve,+ countBetween,cubicBezier,curveOf,drag,@@ -43,6 +46,7 @@ import {freezeTimers,holdAnimations,installInputLog,+ installLongTaskLog,installTimerGate,markElement,merge,@@ -50,10 +54,12 @@ import {PARTIAL_LIFT_SKIP,pinch,readInputLog,+ readLongTasks,releaseAnimations,sampleCurve,seekAnimations,springStep,+ startCompositorTrace,startScreencast,Storyboard,tap,@@ -61,6 +67,7 @@ import {timeline,touchDriver,touchStoryboard,+ traceRendering,trackMarker,waitForAnimation,waitForRest,@@ -342,6 +349,85 @@ test.describe('frame evidence', () => {expect(slowRaf.verdict.failures.join('\n')).toMatch(/longest stall/);});+ test('frames the screencast skips while the compositor presents them are not a stall; a frozen animation still fails with the compositor record', async ({+ page,+ browserName,+ }, testInfo) => {+ test.skip(+ browserName !== 'chromium',+ 'compositor traces are Chromium-only (README: engine limits)',+ );+ await busyFixture(page);+ const box = page.locator('#box');+ await markElement(box, {mode: 'outline'});+ const run = async (driver: 'compositor' | 'raf') => {+ await box.evaluate((el, how) => {+ el.getAnimations().forEach(a => a.cancel());+ el.style.transform = 'none';+ if (how === 'compositor') {+ el.animate(+ [{transform: 'translateY(0px)'}, {transform: 'translateY(560px)'}],+ {duration: 1600, easing: 'linear'},+ );+ } else {+ const start = performance.now();+ const step = (now: number) => {+ const p = Math.min(1, (now - start) / 1600);+ el.style.transform = `translateY(${560 * p}px)`;+ if (p < 1) {+ requestAnimationFrame(step);+ }+ };+ requestAnimationFrame(step);+ }+ }, driver);+ const cast = await startScreencast(page);+ const compositor = await startCompositorTrace(page);+ await page.waitForTimeout(200);+ const window = await blockMainThread(page, 700);+ await page.waitForTimeout(200);+ const presented = await compositor.stop();+ const tracked = await trackMarker(page, await cast.stop());+ return {window, tracked, presented};+ };++ const moving = await run('compositor');+ expect(moving.presented.length).toBeGreaterThan(0);+ // The screencast as a loaded machine delivers it: four frames in a row+ // skipped mid-block, which the compositor still presented.+ const mid = moving.tracked.findIndex(f => f.t > moving.window.from + 350);+ const skipped = moving.tracked.filter((_, i) => i < mid || i >= mid + 4);+ const alone = busyWindowProof(skipped, moving.window, {axis: 'y'});+ expect(alone.verdict.failures.join('\n'), alone.summary).toMatch(+ /longest stall/,+ );+ const proof = busyWindowProof(skipped, moving.window, {+ axis: 'y',+ presented: moving.presented,+ });+ testInfo.annotations.push({+ type: 'busy-main-thread compositor record',+ description: proof.summary,+ });+ expect(proof.verdict.failures, proof.summary).toEqual([]);+ expect(proof.recorderSkipped).toBeGreaterThanOrEqual(4);++ // A rAF animation presents no change for the whole block: the record+ // excuses nothing, whatever the compositor drew meanwhile.+ const frozen = await run('raf');+ const still = busyWindowProof(frozen.tracked, frozen.window, {+ axis: 'y',+ presented: frozen.presented,+ });+ testInfo.annotations.push({+ type: 'busy-main-thread rAF control, compositor record',+ description: `${still.summary}; compositor frames inside the block: ${frozen.presented.filter(t => t > frozen.window.from && t < frozen.window.to).length}`,+ });+ expect(still.verdict.pass).toBe(false);+ expect(still.recorderSkipped).toBe(0);+ expect(still.verdict.failures.join('\n')).toMatch(/longest stall/);+ });+test('a block that starts during a just-started transition still lets the compositor advance it', async ({page,}, testInfo) => {@@ -422,6 +508,246 @@ test.describe('frame evidence', () => {expect(proof.verdict.failures, proof.summary).toEqual([]);expect(proof.monotonic).toBe(true);});++ test('the trace counts no Layout for a transform animation and one per frame for `top`', async ({+ page,+ browserName,+ }) => {+ test.skip(+ browserName !== 'chromium',+ 'rendering traces are Chromium-only (README: engine limits)',+ );+ await fixture(page);+ const box = page.locator('#box');+ // Count the animation's steady middle: starting and ending it may lay out once each.+ const animate = async (property: 'transform' | 'top') => {+ let started = 0;+ const trace = await traceRendering(page, async () => {+ started = await box.evaluate((el, prop) => {+ const keyframes =+ prop === 'transform'+ ? [+ {transform: 'translateY(0px)'},+ {transform: 'translateY(200px)'},+ ]+ : [{top: '360px'}, {top: '560px'}];+ el.animate(keyframes, {duration: 600});+ return performance.timeOrigin + performance.now();+ }, property);+ await page.waitForTimeout(700);+ });+ return countBetween(trace, started + 100, started + 500);+ };+ const transform = await animate('transform');+ const top = await animate('top');+ expect(transform.Layout ?? 0).toBe(0);+ expect(transform.Paint ?? 0).toBe(0);+ // ~24 frames in 400 ms: one layout per frame.+ expect(top.Layout ?? 0).toBeGreaterThan(18);+ });++ test('the compositor record refuses another open page, whose frames it could not tell apart', async ({+ page,+ browserName,+ }) => {+ test.skip(+ browserName !== 'chromium',+ 'the compositor record is a Chromium trace (README: engine limits)',+ );+ await fixture(page);+ // Another page animating: its presented frames would be credited to+ // this one, so the record refuses to start.+ const other = await page.context().newPage();+ await other.setContent(+ '<style>@keyframes spin{to{transform:rotate(360deg)}}</style><div style="width:50px;height:50px;background:red;animation:spin 1s linear infinite"></div>',+ );+ await expect(startCompositorTrace(page)).rejects.toThrow(+ /another page is open as the trace starts/,+ );+ await other.close();+ // A page opened mid-trace: stop() refuses too, whether it is still open+ // or closed again before the record stops.+ const record = await startCompositorTrace(page);+ const late = await page.context().newPage();+ await expect(record.stop()).rejects.toThrow(+ /another page opened during the record/,+ );+ await late.close();+ const brief = await startCompositorTrace(page);+ const spinner = await page.context().newPage();+ await spinner.setContent(+ '<style>@keyframes spin{to{transform:rotate(360deg)}}</style><div style="width:50px;height:50px;background:red;animation:spin 1s linear infinite"></div>',+ );+ await page.waitForTimeout(200);+ await spinner.close();+ await expect(brief.stop()).rejects.toThrow(+ /another page opened during the record/,+ );+ // In another context too.+ const browser = page.context().browser();+ if (browser != null) {+ const elsewhere = await startCompositorTrace(page);+ const context = await browser.newContext();+ await (await context.newPage()).close();+ await context.close();+ await expect(elsewhere.stop()).rejects.toThrow(+ /another page opened during the record/,+ );+ }+ // Alone, it records.+ const alone = await startCompositorTrace(page);+ await page.waitForTimeout(100);+ await expect(alone.stop()).resolves.toBeInstanceOf(Array);+ });++ test('the long-task log fails closed when it never ran on the document', async ({+ page,+ }) => {+ // No installLongTaskLog before navigating: an empty answer would read as+ // "no long task", so it throws instead.+ await fixture(page);+ await expect(readLongTasks(page)).rejects.toThrow(+ /not running on this document/,+ );+ });++ test("the long-task log records the page's own long task but not a DevTools evaluate, which the trace reports apart", async ({+ page,+ browserName,+ }) => {+ test.skip(+ browserName !== 'chromium',+ 'the Long Tasks API and rendering traces are Chromium-only',+ );+ await installLongTaskLog(page);+ await fixture(page);+ // The page's own task: a timer that spins 120 ms.+ const own = await page.evaluate(+ () =>+ new Promise<{from: number; to: number}>(resolve => {+ setTimeout(() => {+ const from = performance.timeOrigin + performance.now();+ const end = performance.now() + 120;+ while (performance.now() < end) {+ // spin+ }+ resolve({from, to: performance.timeOrigin + performance.now()});+ }, 0);+ }),+ );+ await frames(page, 2);+ const recorded = await readLongTasks(page, own);+ expect(recorded).toHaveLength(1);+ expect(recorded[0].durationMs).toBeGreaterThanOrEqual(110);+ // A DevTools evaluate that spins 300 ms: the trace reports it apart from+ // the page's long tasks, and the log never sees it.+ let block = {from: 0, to: 0};+ const trace = await traceRendering(page, async () => {+ block = await blockMainThread(page, 300);+ });+ await frames(page, 2);+ const inBlock = (t: {start: number}) =>+ t.start < block.to && t.start >= block.from - 20;+ expect(+ trace.devtoolsTasks.some(t => t.durationMs >= 290 && inBlock(t)),+ ).toBe(true);+ expect(trace.longTasks.filter(inBlock)).toEqual([]);+ expect(await readLongTasks(page, block)).toEqual([]);+ });++ test("a harness read inside a trace is not the page's long task, while a test's own evaluate is, whether it calls the page directly or sets it off", async ({+ page,+ browserName,+ }) => {+ test.skip(+ browserName !== 'chromium',+ 'rendering traces are Chromium-only (README: engine limits)',+ );+ // Enough animated rows that describing their keyframes takes a DevTools+ // task over 50 ms.+ const rows = Array.from(+ {length: 1200},+ (_, i) => `<div class="row">row ${i}</div>`,+ ).join('');+ await page.setContent(+ `<style>.row { height: 4px; animation: slide 2s linear infinite; } @keyframes slide { from { transform: translateX(0); } 25% { transform: translateX(4px); } 50% { transform: translateX(0); } 75% { transform: translateX(4px); } to { transform: translateX(0); } }</style><button id="slow">slow</button><div id="list">${rows}</div>`,+ );+ const slow = page.locator('#slow');+ await slow.evaluate(el =>+ el.addEventListener('click', () => {+ const end = performance.now() + 60;+ while (performance.now() < end) {+ // spin+ }+ }),+ );+ // Page code a test can call directly, as through a story's own API.+ await page.evaluate(() => {+ (window as unknown as {pageWork: (ms: number) => void}).pageWork = (+ ms: number,+ ) => {+ const end = performance.now() + ms;+ while (performance.now() < end) {+ // spin+ }+ };+ });+ await frames(page, 3);+ const now = () =>+ page.evaluate(() => performance.timeOrigin + performance.now());+ const read = {from: 0, to: 0};+ const click = {from: 0, to: 0};+ const direct = {from: 0, to: 0};+ let timer = {from: 0, to: 0};+ const trace = await traceRendering(page, async () => {+ read.from = await now();+ await waitForAnimation(page.locator('#list'));+ read.to = await now();+ // On a slow machine each frame of 1,200 running rows is a long task of+ // the page's own; the windows below hold only their own work.+ await page.evaluate(() => document.getElementById('list')?.remove());+ await frames(page, 2);+ // The page's own task: a timer that spins 60 ms.+ timer = await page.evaluate(+ () =>+ new Promise<{from: number; to: number}>(resolve => {+ setTimeout(() => {+ const from = performance.timeOrigin + performance.now();+ const end = performance.now() + 60;+ while (performance.now() < end) {+ // spin+ }+ resolve({from, to: performance.timeOrigin + performance.now()});+ }, 0);+ }),+ );+ // Page script run inside a DevTools evaluate: a 60 ms click handler.+ click.from = await now();+ await slow.evaluate(el => (el as HTMLElement).click());+ click.to = await now();+ // Page code a test's evaluate calls directly: 60 ms of the page's work.+ direct.from = await now();+ await page.evaluate(() =>+ (window as unknown as {pageWork: (ms: number) => void}).pageWork(60),+ );+ direct.to = await now();+ });+ const within = (w: {from: number; to: number}) => (t: {start: number}) =>+ t.start >= w.from - 20 && t.start < w.to;+ // The read itself is set apart. The rows' frames around it may be long+ // tasks too, the page's own: they stay in longTasks.+ expect(trace.devtoolsTasks.some(within(read))).toBe(true);+ expect(+ trace.longTasks.some(t => within(timer)(t) && t.durationMs >= 55),+ ).toBe(true);+ expect(+ trace.longTasks.some(t => within(click)(t) && t.durationMs >= 55),+ ).toBe(true);+ expect(+ trace.longTasks.some(t => within(direct)(t) && t.durationMs >= 55),+ ).toBe(true);+ expect(trace.devtoolsTasks.filter(within(direct))).toEqual([]);+ });});test.describe('curve sampling', () => {diff --git a/internal/interaction-harness/src/index.ts b/internal/interaction-harness/src/index.tsindex 2bcb127f36..7a45ff45df 100644--- a/internal/interaction-harness/src/index.ts+++ b/internal/interaction-harness/src/index.ts@@ -21,3 +21,4 @@ export * from './scripts';export * from './story';export * from './storyboard';export * from './touch';+export * from './trace';diff --git a/internal/interaction-harness/src/trace.ts b/internal/interaction-harness/src/trace.tsnew file mode 100644index 0000000000..533a32e06b--- /dev/null+++ b/internal/interaction-harness/src/trace.ts@@ -0,0 +1,432 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file trace.ts+ * @input Uses a Playwright `Page` (Chromium: CDP `Tracing`) and the page's+ * PerformanceObserver for long tasks+ * @output `traceRendering` — counts of the main thread's rendering work+ * (Layout, Paint, UpdateLayoutTree, PrePaint, …) between two marks — and+ * `installLongTaskLog` / `readLongTasks`.+ * @position The "no Layout/Paint during a transform/opacity animation" proof.+ * A compositor animation costs the main thread nothing per frame; one that+ * animates a layout property, or writes styles from JavaScript each frame,+ * shows a Layout (and usually a Paint) per frame. Chromium only: WebKit+ * exposes no comparable trace to Playwright.+ *+ * Counting is scoped to the renderer main thread that ran the page's own+ * `performance.mark` calls, and to the time between the start and end marks,+ * so other pages, the browser process and setup work are excluded.+ *+ * SYNC: Keep RENDERING_EVENTS equal to the README's list.+ */++import type {CDPSession, Page} from '@playwright/test';++/**+ * The mark a harness function puts on its own page-side work+ * (`console.timeStamp('harness-read')` at the start of the function it+ * evaluates in the page), so a trace can tell the harness's reads from page+ * code a test's own evaluate runs.+ */+export const HARNESS_READ = 'harness-read';++/** Trace events that run page script: a listener, a timer, a frame callback. */+const PAGE_SCRIPT_EVENTS = new Set([+ 'EventDispatch',+ 'FunctionCall',+ 'TimerFire',+ 'FireAnimationFrame',+ 'FireIdleCallback',+]);++/** Main-thread trace events that are rendering work, by their trace names. */+export const RENDERING_EVENTS = [+ 'UpdateLayoutTree', // style recalculation+ 'Layout',+ 'PrePaint',+ 'Paint',+ 'Layerize',+ 'UpdateLayer',+ 'ScrollLayer',+ 'HitTest',+] as const;++export interface RenderingTrace {+ /** Count per trace event name inside the window, on the page's main thread. */+ readonly counts: Readonly<Record<string, number>>;+ /** Shorthand for the four that matter most. */+ readonly layout: number;+ readonly paint: number;+ readonly styleRecalc: number;+ readonly prePaint: number;+ /** Window length, ms. */+ readonly durationMs: number;+ /**+ * The page's own main-thread tasks longer than 50 ms inside the window (long+ * tasks), epoch ms. A task that ran a test's own DevTools command (a+ * `page.evaluate`) is one, whether it calls page code directly or sets it+ * off; only the harness's own marked reads are in `devtoolsTasks`.+ */+ readonly longTasks: readonly {+ readonly start: number;+ readonly durationMs: number;+ }[];+ /**+ * Main-thread tasks longer than 50 ms inside the window that ran a DevTools+ * command the harness marked as its own read (`HARNESS_READ`) and no page+ * script, epoch ms: `waitForAnimation` describing every animation's+ * keyframes, or `blockMainThread(page, ms)` without `during`.+ */+ readonly devtoolsTasks: readonly {+ readonly start: number;+ readonly durationMs: number;+ }[];+ /** Every counted rendering event with its epoch-ms time, for sub-window counts. */+ readonly events: readonly {readonly name: string; readonly t: number}[];+ /** The window, epoch ms on the page's clock. */+ readonly window: {readonly from: number; readonly to: number};+}++/** Counts rendering events by name inside `[from, to]` (epoch ms). */+export function countBetween(+ trace: RenderingTrace,+ from: number,+ to: number,+): Record<string, number> {+ const counts: Record<string, number> = {};+ for (const e of trace.events) {+ if (e.t >= from && e.t <= to) {+ counts[e.name] = (counts[e.name] ?? 0) + 1;+ }+ }+ return counts;+}++interface TraceEvent {+ name: string;+ cat: string;+ ph: string;+ ts: number;+ dur?: number;+ pid: number;+ tid: number;+ args?: Record<string, unknown>;+}++/**+ * Traces the page while `body` runs and counts the rendering work its main+ * thread did between a start mark (placed just before `body`) and an end mark+ * (just after).+ */+export async function traceRendering(+ page: Page,+ body: () => Promise<unknown>,+): Promise<RenderingTrace> {+ const cdp: CDPSession = await page.context().newCDPSession(page);+ const events: TraceEvent[] = [];+ cdp.on('Tracing.dataCollected', ({value}) => {+ events.push(...(value as unknown as TraceEvent[]));+ });+ const complete = new Promise<void>(resolve =>+ cdp.once('Tracing.tracingComplete', () => resolve()),+ );+ await cdp.send('Tracing.start', {+ transferMode: 'ReportEvents',+ traceConfig: {+ includedCategories: [+ 'devtools.timeline',+ 'disabled-by-default-devtools.timeline',+ 'blink.user_timing',+ 'toplevel',+ ],+ excludedCategories: ['*'],+ },+ });+ const tag = `harness-${Math.random().toString(36).slice(2, 8)}`;+ const mark = (name: string) =>+ page.evaluate(+ n => performance.timeOrigin + performance.mark(n).startTime,+ name,+ );+ const fromEpoch = await mark(`${tag}:start`);+ await body();+ const toEpoch = await mark(`${tag}:end`);+ await cdp.send('Tracing.end');+ await complete;+ await cdp.detach().catch(() => {});++ const start = events.find(e => e.name === `${tag}:start`);+ const end = events.find(e => e.name === `${tag}:end`);+ if (start == null || end == null) {+ throw new Error('traceRendering: the window marks were not traced');+ }+ const onMain = (e: TraceEvent) =>+ e.pid === start.pid &&+ e.tid === start.tid &&+ e.ts >= start.ts &&+ e.ts <= end.ts;+ // Trace time (µs, monotonic) -> epoch ms, anchored on the start mark.+ const toEpochMs = (ts: number) => fromEpoch + (ts - start.ts) / 1000;+ const counts: Record<string, number> = {};+ const counted: {name: string; t: number}[] = [];+ for (const e of events) {+ if (!onMain(e) || e.ph === 'E') {+ continue;+ }+ if ((RENDERING_EVENTS as readonly string[]).includes(e.name)) {+ counts[e.name] = (counts[e.name] ?? 0) + 1;+ counted.push({name: e.name, t: toEpochMs(e.ts)});+ }+ }+ // A task that ran a DevTools command received it over the DevTools+ // session's pipe; page script it set off shows as its listener, timer or+ // frame callback.+ const main = events.filter(e => onMain(e) && e.ph !== 'E');+ const longTasks: {start: number; durationMs: number}[] = [];+ const devtoolsTasks: {start: number; durationMs: number}[] = [];+ for (const task of main) {+ if (task.name !== 'RunTask' || (task.dur ?? 0) <= 50_000) {+ continue;+ }+ const end = task.ts + (task.dur ?? 0);+ const inside = main.filter(+ e => e !== task && e.ts >= task.ts && e.ts <= end,+ );+ const devtools = inside.some(+ e =>+ e.name === 'Receive mojo message' &&+ (+ e.args?.chrome_mojo_event_info as+ {mojo_interface_tag?: unknown} | undefined+ )?.mojo_interface_tag === 'blink.mojom.DevToolsSession',+ );+ // Only the harness's own reads are set apart: a test's evaluate may call+ // page code directly, which leaves no listener or timer in the trace.+ const harnessRead = inside.some(+ e =>+ e.name === 'TimeStamp' &&+ (e.args?.data as {message?: unknown} | undefined)?.message ===+ HARNESS_READ,+ );+ const pageScript = inside.some(e => PAGE_SCRIPT_EVENTS.has(e.name));+ (devtools && harnessRead && !pageScript ? devtoolsTasks : longTasks).push({+ start: toEpochMs(task.ts),+ durationMs: (task.dur ?? 0) / 1000,+ });+ }+ return {+ counts,+ layout: counts.Layout ?? 0,+ paint: counts.Paint ?? 0,+ styleRecalc: counts.UpdateLayoutTree ?? 0,+ prePaint: counts.PrePaint ?? 0,+ durationMs: (end.ts - start.ts) / 1000,+ longTasks,+ devtoolsTasks,+ events: counted,+ window: {from: fromEpoch, to: toEpoch},+ };+}++/**+ * The browser's open pages. The compositor record is browser-wide: its+ * `Display::FrameDisplayed` events carry no page identity.+ */+function openPages(page: Page): Page[] {+ const browser = page.context().browser();+ return browser == null+ ? page.context().pages()+ : browser.contexts().flatMap(context => context.pages());+}++/**+ * Watches for a page that opens while the record runs, in any context (it+ * may close again before the record stops). Returns whether one opened.+ */+async function watchForOtherPages(+ page: Page,+): Promise<{stop(): Promise<boolean>}> {+ let opened = false;+ const onPage = (other: Page) => {+ if (other !== page) {+ opened = true;+ }+ };+ // The page's own context, through Playwright (a persistent context has no+ // browser to ask).+ page.context().on('page', onPage);+ // Every context, through the browser's target discovery: a page in a+ // context created during the record is a new target too.+ let targets: CDPSession | null = null;+ const browser = page.context().browser();+ if (browser != null) {+ try {+ targets = await browser.newBrowserCDPSession();+ const {targetInfos} = await targets.send('Target.getTargets');+ const known = new Set(targetInfos.map(info => info.targetId));+ targets.on('Target.targetCreated', ({targetInfo}) => {+ if (targetInfo.type === 'page' && !known.has(targetInfo.targetId)) {+ opened = true;+ }+ });+ await targets.send('Target.setDiscoverTargets', {discover: true});+ } catch {+ targets = null;+ }+ }+ return {+ async stop() {+ page.context().off('page', onPage);+ await targets?.detach().catch(() => {});+ return opened;+ },+ };+}++function assertOnlyPage(page: Page, when: string): void {+ if (openPages(page).some(other => other !== page && !other.isClosed())) {+ throw new Error(+ `startCompositorTrace: another page is open ${when}; the compositor record is browser-wide (its frames carry no page identity), so another page's frames would be credited to this one`,+ );+ }+}++/**+ * Records when the compositor presents each frame, for `busyWindowProof`'s+ * `presented`: a Chromium trace of `Display::FrameDisplayed`, on the page+ * clock. Start it with the screencast, before the block, and stop it after.+ * Engines without a CDP trace (WebKit) resolve `stop()` to [], and the+ * verdict then judges the screencast alone. It runs its own trace, so not+ * inside `traceRendering`. The record is browser-wide, so it throws when+ * another page is open as it starts or stops, or opened while it ran.+ */+export async function startCompositorTrace(+ page: Page,+): Promise<{stop(): Promise<number[]>}> {+ let cdp: CDPSession;+ try {+ cdp = await page.context().newCDPSession(page);+ } catch {+ return {stop: async () => []};+ }+ try {+ assertOnlyPage(page, 'as the trace starts');+ } catch (error) {+ await cdp.detach().catch(() => {});+ throw error;+ }+ const others = await watchForOtherPages(page);+ const events: TraceEvent[] = [];+ cdp.on('Tracing.dataCollected', ({value}) => {+ events.push(...(value as unknown as TraceEvent[]));+ });+ const complete = new Promise<void>(resolve =>+ cdp.once('Tracing.tracingComplete', () => resolve()),+ );+ await cdp.send('Tracing.start', {+ transferMode: 'ReportEvents',+ traceConfig: {+ includedCategories: [+ 'disabled-by-default-display.framedisplayed',+ 'blink.user_timing',+ ],+ excludedCategories: ['*'],+ },+ });+ const tag = `harness-compositor-${Math.random().toString(36).slice(2, 8)}`;+ const epoch = await page.evaluate(+ n => performance.timeOrigin + performance.mark(n).startTime,+ tag,+ );+ return {+ async stop() {+ await cdp.send('Tracing.end');+ await complete;+ await cdp.detach().catch(() => {});+ if (await others.stop()) {+ throw new Error(+ "startCompositorTrace: another page opened during the record; the compositor record is browser-wide (its frames carry no page identity), so that page's frames would be credited to this one",+ );+ }+ assertOnlyPage(page, 'as the trace stops');+ const mark = events.find(e => e.name === tag);+ if (mark == null) {+ throw new Error('startCompositorTrace: the clock mark was not traced');+ }+ // Trace time (µs, monotonic) -> epoch ms, anchored on the mark.+ return events+ .filter(e => e.name === 'Display::FrameDisplayed')+ .map(e => epoch + (e.ts - mark.ts) / 1000)+ .sort((a, b) => a - b);+ },+ };+}++const LONG_TASK_SCRIPT = `(() => {+ if (window.__harnessLongTasks) return;+ const tasks = [];+ const log = {tasks, supported: false};+ window.__harnessLongTasks = log;+ if (typeof PerformanceObserver === 'undefined' || !(PerformanceObserver.supportedEntryTypes || []).includes('longtask')) return;+ try {+ new PerformanceObserver(list => {+ for (const entry of list.getEntries()) tasks.push({start: performance.timeOrigin + entry.startTime, durationMs: entry.duration, name: entry.name});+ }).observe({type: 'longtask', buffered: true});+ log.supported = true;+ } catch {}+})()`;++/**+ * Records every long task (> 50 ms) the page runs (install before navigation;+ * Chromium), through the Long Tasks API. That sees the tasks of the page's own+ * event loop: a timer, an event handler, `blockMainThread(page, ms, {during})`.+ * A DevTools `page.evaluate`, such as `blockMainThread(page, ms)` without+ * `during`, is not one of them and is never recorded here; `traceRendering`+ * reports it in `devtoolsTasks`, apart from the page's `longTasks`.+ */+export async function installLongTaskLog(page: Page): Promise<void> {+ await page.addInitScript(LONG_TASK_SCRIPT);+}++export interface LongTask {+ /** Epoch ms. */+ readonly start: number;+ readonly durationMs: number;+ readonly name: string;+}++/**+ * Long tasks recorded since navigation, optionally only those overlapping a+ * window. Fails closed: it throws when the log never ran on this document+ * (installed after the page navigated) or the engine has no Long Tasks API+ * (WebKit), so an empty answer is evidence of no long task, never of no log.+ */+export async function readLongTasks(+ page: Page,+ range?: {from: number; to: number},+): Promise<LongTask[]> {+ const log = await page.evaluate(+ () =>+ (+ window as unknown as {+ __harnessLongTasks?: {tasks: LongTask[]; supported: boolean};+ }+ ).__harnessLongTasks ?? null,+ );+ if (log == null) {+ throw new Error(+ 'readLongTasks: the long-task log is not running on this document; call installLongTaskLog(page) before navigating',+ );+ }+ if (!log.supported) {+ throw new Error(+ 'readLongTasks: this engine has no Long Tasks API, so the log records nothing',+ );+ }+ const tasks = log.tasks;+ return range == null+ ? tasks+ : tasks.filter(+ t => t.start < range.to && t.start + t.durationMs > range.from,+ );+}