Skip to content

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.md
index 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 two
steps 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 moved
frames with nothing delivered inside it is then measured between the
compositor's own frames: the frames it presented there count as presented
(`recorderSkipped`, in the summary), and a gap it did not present through is
@@ -165,8 +170,18 @@ delivered frame that did not move, is judged from the screencast, so a
frozen element fails whatever else the compositor draws (a rAF animation's
block presents no compositor frame at all). With the record, the 90% counts the
compositor's frames from the first to the last moved frame; the gaps before and
-after are the stall check's. 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 or
from 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 finger
lifting while another stays down, finger tracking under a busy main thread, and
diff --git a/internal/interaction-harness/src/busy.skip.fixture.ts b/internal/interaction-harness/src/busy.skip.fixture.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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,
+ );
+}