An open source design system that's fully customizable and agent ready
TypeScript
// 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`. `longTasksOf` gives each long task
* its wall and thread time. `layoutSources` names what ran each counted
* Layout and what invalidated layout before it.
* @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';
import {frames} from './story';
/**
* 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;
/** A main-thread task longer than 50 ms, epoch ms. */
export interface TracedTask {
readonly start: number;
/** Wall time, ms. */
readonly durationMs: number;
/**
* The main thread's own run time in the task, from the trace's thread clock,
* ms; at most `durationMs`. A busy machine stretches a task's wall time but
* not its thread time. Without a thread clock it is the wall time.
*/
readonly threadMs: number;
}
/** A counted rendering event, epoch ms. */
export interface RenderingEvent {
readonly name: string;
readonly t: number;
/** A `Paint`'s node, as the trace names it. */
readonly node?: string;
/** How many elements an `UpdateLayoutTree` restyled. */
readonly elements?: number;
}
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 inside the window whose main thread ran
* longer than 50 ms (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 TracedTask[];
/**
* The page's own tasks longer than 50 ms of wall time whose main thread ran
* 50 ms or less, epoch ms. A busy machine kept the renderer off the CPU, or
* the thread waited (a synchronous request, `Atomics.wait`). A claim about
* a blocking wait judges these too.
*/
readonly stretchedTasks: readonly TracedTask[];
/**
* 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 TracedTask[];
/**
* Every counted rendering event with its epoch-ms time, for sub-window
* counts. A `Paint` names the node it painted, and an `UpdateLayoutTree`
* counts the elements it restyled.
*/
readonly events: readonly RenderingEvent[];
/** The window, epoch ms on the page's clock. */
readonly window: {readonly from: number; readonly to: number};
/**
* Every main-thread trace event inside the window, in time order, when the
* trace keeps them (`keepEvents`). A proof reads them only to explain a
* failure.
*/
readonly mainThread?: readonly TimedTraceEvent[];
}
/** A main-thread trace event with its epoch-ms time. */
export interface TimedTraceEvent extends TraceEvent {
readonly t: 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;
}
/** What ran a counted Layout, and what invalidated layout before it. */
export interface LayoutSource {
/** The Layout's time, epoch ms. */
readonly t: number;
/** The task that ran the Layout: its dispatches and calls, in order. */
readonly task: readonly string[];
/**
* Each layout or style invalidation since the previous Layout, with the
* task it ran in. The trace names the reason and the node only when it
* tracks invalidations.
*/
readonly invalidations: ReadonlyArray<{
readonly t: number;
readonly what: string;
readonly task: readonly string[];
}>;
}
const TASK_STEPS = new Set([
...PAGE_SCRIPT_EVENTS,
'BeginMainThreadFrame',
'EvaluateScript',
'HitTest',
'IntersectionObserverController::computeIntersections',
'ParseHTML',
'UpdateLayoutTree',
'Layout',
]);
const INVALIDATIONS = new Set([
'InvalidateLayout',
'ScheduleStyleRecalculation',
'LayoutInvalidationTracking',
'StyleRecalcInvalidationTracking',
]);
/** One trace event as text: its name and what its data says about it. */
function describeEvent(e: TraceEvent): string {
const data = (e.args?.data ?? {}) as Record<string, unknown>;
const text = (value: unknown) =>
typeof value === 'string' || typeof value === 'number'
? String(value)
: null;
const url = text(data.url);
const parts = [
text(data.type),
text(data.functionName),
url == null
? null
: `${url.split('/').pop()}:${text(data.lineNumber) ?? '?'}:${text(data.columnNumber) ?? '?'}`,
text(data.reason),
text(data.nodeName),
].filter(part => part != null && part !== '');
// Square brackets: a message line that ends in `:line:column` or
// `:line:column)` reads as a stack frame to Playwright, which then reports
// that line as the failure's location.
return parts.length === 0 ? e.name : `${e.name}[${parts.join(' ')}]`;
}
/**
* Names the source of each Layout in `[from, to]` (epoch ms) from a trace that
* kept its events (`traceRendering(page, body, {keepEvents: true})`). For a
* Layout it gives the steps of the task that ran it. It also gives every
* invalidation since the previous Layout, with the steps of its own task.
*/
export function layoutSources(
trace: RenderingTrace,
from: number,
to: number,
): LayoutSource[] {
const main = trace.mainThread;
if (main == null) {
throw new Error(
'layoutSources: the trace kept no events; trace with {keepEvents: true}',
);
}
const tasks = main.filter(e => e.name === 'RunTask' && e.ph === 'X');
const stepsBefore = (e: TimedTraceEvent): string[] => {
const task = tasks.find(t => t.ts <= e.ts && t.ts + (t.dur ?? 0) >= e.ts);
if (task == null) {
return [];
}
return main
.filter(
x =>
x !== e && x.ts >= task.ts && x.ts <= e.ts && TASK_STEPS.has(x.name),
)
.map(describeEvent)
.slice(-8);
};
const layouts = main.filter(e => e.name === 'Layout');
return layouts
.filter(e => e.t >= from && e.t <= to)
.map(layout => {
const previous = layouts.filter(e => e.ts < layout.ts).at(-1);
return {
t: layout.t,
task: stepsBefore(layout),
invalidations: main
.filter(
e =>
INVALIDATIONS.has(e.name) &&
e.ts > (previous?.ts ?? -Infinity) &&
e.ts <= layout.ts,
)
.slice(-12)
.map(e => ({t: e.t, what: describeEvent(e), task: stepsBefore(e)})),
};
});
}
export interface TraceEvent {
name: string;
cat: string;
ph: string;
ts: number;
dur?: number;
/** Thread-clock duration, µs. */
tdur?: 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). The harness's animation recorder, `waitForRest`,
* `waitForAnimation` and a watch's `started()` stand down meanwhile, so a body
* may wait with any of them and add no frame of its own, with one gap: on a
* CSS `@keyframes` animation (and, for an unwatched `waitForAnimation`, a
* cancelled CSS transition) the wait reads its timing, which flushes that
* animation's style, so wait on such an animation with `waitForRest`, or
* after the trace. Taking a watch, or calling `waitForRest` while an
* animation already runs on the element, reads its animations once, which
* restyles it: do either before the window a proof counts.
*/
export async function traceRendering(
page: Page,
body: () => Promise<unknown>,
{keepEvents = false}: {keepEvents?: boolean} = {},
): 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,
);
// The harness's animation recorder (curves.ts) runs a callback every frame,
// which makes each frame a main-thread one where Blink restyles every running
// animation's target (and lays out an anchored one), and it reads the page's
// animations, which flushes style: exactly what this counts. It stands down
// while this flag is set, a recorder the body itself starts included, and
// resumes once the trace ends.
const standDown = (on: boolean) =>
page.evaluate(value => {
const w = window as unknown as {
__harnessRenderingTrace?: boolean;
__harnessAnimations?: {resume?: () => void};
};
w.__harnessRenderingTrace = value;
if (!value) {
w.__harnessAnimations?.resume?.();
}
}, on);
await standDown(true);
// The frame the recorder requested before it stood down runs now, before the
// start mark. A frame callback makes its frame a main-thread one, in which an
// anchored layer that animates lays out.
await frames(page, 1);
let fromEpoch: number;
let toEpoch: number;
try {
fromEpoch = await mark(`${tag}:start`);
await body();
toEpoch = await mark(`${tag}:end`);
} finally {
// Its catch-up read lands after the end mark, outside the counted window.
// A failure here would hide the body's own error, which is the one to see.
await standDown(false).catch(() => {});
}
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: RenderingEvent[] = [];
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;
const node = (e.args?.data as {nodeName?: unknown} | undefined)?.nodeName;
const elements = e.args?.elementCount;
counted.push({
name: e.name,
t: toEpochMs(e.ts),
...(typeof node === 'string' ? {node} : {}),
...(typeof elements === 'number' ? {elements} : {}),
});
}
}
const {longTasks, devtoolsTasks, stretchedTasks} = longTasksOf(
events.filter(e => onMain(e) && e.ph !== 'E'),
toEpochMs,
);
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,
stretchedTasks,
devtoolsTasks,
events: counted,
window: {from: fromEpoch, to: toEpoch},
...(keepEvents
? {
mainThread: events
.filter(e => onMain(e) && e.ph !== 'E')
.sort((a, b) => a.ts - b.ts)
.map(e => ({...e, t: toEpochMs(e.ts)})),
}
: {}),
};
}
/**
* The main thread's tasks longer than 50 ms, split into the page's own and the
* harness's marked reads. A page task is long when its main thread ran longer
* than 50 ms; one only the wall clock stretched past that is apart
* (`stretchedTasks`). `main` holds the main thread's events in the window;
* `toEpochMs` turns trace time into epoch ms.
*/
export function longTasksOf(
main: readonly TraceEvent[],
toEpochMs: (ts: number) => number,
): {
longTasks: TracedTask[];
devtoolsTasks: TracedTask[];
stretchedTasks: TracedTask[];
} {
// 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 longTasks: TracedTask[] = [];
const devtoolsTasks: TracedTask[] = [];
const stretchedTasks: TracedTask[] = [];
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));
const wall = task.dur ?? 0;
const traced = {
start: toEpochMs(task.ts),
durationMs: wall / 1000,
threadMs: Math.min(task.tdur ?? wall, wall) / 1000,
};
if (devtools && harnessRead && !pageScript) {
devtoolsTasks.push(traced);
} else if (traced.threadMs > 50) {
longTasks.push(traced);
} else {
stretchedTasks.push(traced);
}
}
return {longTasks, devtoolsTasks, stretchedTasks};
}
/**
* 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,
);
}