Skip to content

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

TypeScript
23.0 KB
Raw Blame
// 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,
      );
}