Skip to content

Write HTML. Render video. Built for agents.

perf(cli): check splits its samples over a second Chrome when a core and memory are spare (#5896)

Miguel Ángel952c6ba1c5cd
diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.ts
index 30348fbc09..ae720610a7 100644
--- a/packages/cli/src/commands/check.test.ts
+++ b/packages/cli/src/commands/check.test.ts
@@ -1635,6 +1635,117 @@ describe("check pipeline", () => {
expect(checkExitCode(strict.report)).toBe(1);
});
+ it("splits samples over a helper page and returns what one page seeking every sample returns", async () => {
+ const pageOfTime = () => {
+ let seeked = 0;
+ return fakeDriver({
+ seek: vi.fn(async (time: number) => {
+ seeked = time;
+ }),
+ collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
+ collectLayoutGeometry: vi.fn(async () => `geometry-${seeked}`),
+ collectContrast: vi.fn(async (time: number) => ({
+ entries: [contrastEntry({ ...anchor("#hero", time), ratio: 1 + time })],
+ pngBase64: `${PNG_BASE64}-${time}`,
+ })),
+ });
+ };
+ const options = { ...DEFAULT_CHECK_OPTIONS, contrast: true };
+ const { timings: _serialTimings, ...serial } = await runAuditGrid(
+ pageOfTime(),
+ options,
+ noMotion(),
+ );
+ const primary = pageOfTime();
+ const helper = pageOfTime();
+ const { timings: _splitTimings, ...split } = await runAuditGrid(
+ primary,
+ options,
+ noMotion(),
+ Promise.resolve([helper]),
+ );
+
+ expect(split).toEqual(serial);
+ expect(serial.layoutIssues.length).toBeGreaterThan(2);
+ expect(helper.initialize).toHaveBeenCalledWith(true);
+ const seeks = (driver: CheckAuditDriver) =>
+ vi.mocked(driver.seek).mock.calls.map(([time]) => time);
+ expect(seeks(helper).length).toBeGreaterThan(0);
+ expect(seeks(primary).filter((time) => seeks(helper).includes(time))).toEqual([]);
+ });
+
+ it("redoes a crashed helper page's samples on the first page and returns the serial result", async () => {
+ let helperSeeks = 0;
+ const pageOfTime = (crashOnSeek?: number) => {
+ let seeked = 0;
+ return fakeDriver({
+ markSamples: vi.fn(),
+ seek: vi.fn(async (time: number) => {
+ if (crashOnSeek !== undefined && ++helperSeeks === crashOnSeek)
+ throw new Error("Target closed");
+ await new Promise((resolve) => setImmediate(resolve));
+ seeked = time;
+ }),
+ collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
+ collectLayoutGeometry: vi.fn(async () => `geometry-${seeked}`),
+ });
+ };
+ const { timings: _serialTimings, ...serial } = await runAuditGrid(
+ pageOfTime(),
+ DEFAULT_CHECK_OPTIONS,
+ noMotion(),
+ );
+ const unhandled = vi.fn();
+ process.on("unhandledRejection", unhandled);
+ const primary = pageOfTime();
+ const helper = pageOfTime(2);
+ const { timings: _splitTimings, ...split } = await runAuditGrid(
+ primary,
+ DEFAULT_CHECK_OPTIONS,
+ noMotion(),
+ Promise.resolve([helper]),
+ );
+ await new Promise((resolve) => setImmediate(resolve));
+ process.off("unhandledRejection", unhandled);
+
+ expect(split).toEqual(serial);
+ expect(helperSeeks).toBe(2);
+ expect(helper.markSamples).toHaveBeenLastCalledWith("drop");
+ expect(unhandled).not.toHaveBeenCalled();
+ });
+
+ it("waits for the helper's sample in flight when the first page runs out of samples", async () => {
+ const pageOfTime = (onSeek?: () => Promise<void>) =>
+ fakeDriver({
+ seek: vi.fn(async () => onSeek?.()),
+ collectLayout: vi.fn(async (time: number) => [layoutIssue("error", { time })]),
+ collectLayoutGeometry: vi.fn(async () => "geometry"),
+ });
+ const serialPage = pageOfTime();
+ const { timings: _serialTimings, ...serial } = await runAuditGrid(
+ serialPage,
+ DEFAULT_CHECK_OPTIONS,
+ noMotion(),
+ );
+ const samples = vi.mocked(serialPage.seek).mock.calls.length;
+ let firstPageSeeks = 0;
+ let othersTaken!: () => void;
+ const allOthersTaken = new Promise<void>((resolve) => (othersTaken = resolve));
+ const primary = pageOfTime(async () => {
+ if (++firstPageSeeks === samples - 1) setImmediate(othersTaken);
+ });
+ const helper = pageOfTime(() => allOthersTaken);
+ const { timings: _splitTimings, ...split } = await runAuditGrid(
+ primary,
+ DEFAULT_CHECK_OPTIONS,
+ noMotion(),
+ Promise.resolve([helper]),
+ );
+
+ expect(vi.mocked(helper.seek).mock.calls).toHaveLength(1);
+ expect(split).toEqual(serial);
+ });
+
it("fails clearly without samples when no timeline duration is available, without hanging", async () => {
const driver = fakeDriver({ getDuration: vi.fn(async () => 0) });
await expect(runAuditGrid(driver, DEFAULT_CHECK_OPTIONS, noMotion())).rejects.toThrow(
diff --git a/packages/cli/src/utils/checkBrowser.test.ts b/packages/cli/src/utils/checkBrowser.test.ts
index 2ac2369211..17467a3f6a 100644
--- a/packages/cli/src/utils/checkBrowser.test.ts
+++ b/packages/cli/src/utils/checkBrowser.test.ts
@@ -2,7 +2,7 @@
// fallow-ignore-file code-duplication
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import os, { tmpdir } from "node:os";
import { join } from "node:path";
import {
openSettledCompositionPage,
@@ -19,6 +19,8 @@ import {
dropFailedProxyEchoes,
runBrowserCheck,
collectSeekClock,
+ mergeHelperDrafts,
+ samplingBrowserCount,
} from "./checkBrowser.js";
import type { ProjectDir } from "./project.js";
@@ -94,9 +96,13 @@ const PROJECT: ProjectDir = {
indexPath: "/project/index.html",
};
-// The overlap grid logs one marker per sample; keep them out of test output.
+// The overlap grid logs one marker per sample; keep them out of test output. One core keeps
+// the browser pass on one page unless a test says otherwise.
beforeEach(() => {
vi.spyOn(console, "debug").mockImplementation(() => undefined);
+ vi.spyOn(os, "availableParallelism").mockReturnValue(1);
+ vi.spyOn(os, "freemem").mockReturnValue(16 * 1024 ** 3);
+ vi.spyOn(process, "availableMemory").mockReturnValue(16 * 1024 ** 3);
});
afterEach(() => {
@@ -177,6 +183,83 @@ it("carries raw browser geometry through the page driver and pipeline", async ()
expect(mocks.serverClose).toHaveBeenCalledOnce();
});
+it("splits the samples over a second Chrome and reports what one Chrome reports", async () => {
+ mountCanvasFixture(`<p id="copy" data-layout-name="copy">Hi</p>`);
+ type Message = ReturnType<typeof fakeConsoleMessage>;
+ const run = async (cores: number, helper: "works" | "crashes" | "never opens" = "works") => {
+ vi.mocked(os.availableParallelism).mockReturnValue(cores);
+ let helperSeeks = 0;
+ const pages: ReturnType<typeof fakePage>[] = [];
+ const helperPages = new Set<unknown>();
+ const handlers = new Map<unknown, ((message: Message) => void)[]>();
+ const log = (page: unknown, text: string) =>
+ handlers.get(page)?.forEach((handler) => handler(fakeConsoleMessage("error", text)));
+ const browser = Object.assign(Object.create(null), {
+ close: vi.fn(async () => undefined),
+ process: () => ({ exitCode: 0, signalCode: null }),
+ });
+ vi.mocked(openSettledCompositionPage).mockImplementation(
+ async (_html: string, _url: string, options: OpenSettledCompositionPageOptions) => {
+ const page = fakePage();
+ page.on = vi.fn((event: string, handler: (message: Message) => void) => {
+ if (event === "console") handlers.set(page, [...(handlers.get(page) ?? []), handler]);
+ });
+ const opened = pages.push(page);
+ // Only the first page's open takes prelaunched Chromes.
+ if (!("prelaunched" in options)) helperPages.add(page);
+ if (helperPages.has(page) && helper === "never opens")
+ await new Promise((_, reject) => options.signal?.addEventListener("abort", reject));
+ options.onBrowser?.(browser);
+ await options.beforeNavigate?.(page);
+ log(page, `logged at load on page ${opened}`);
+ return { page, browser, renderReadyTimedOut: false };
+ },
+ );
+ vi.mocked(seekCompositionTimeline).mockImplementation(async (page, time) => {
+ if (helperPages.has(page) && helper === "crashes" && ++helperSeeks === 2) {
+ log(page, "renderer crashed");
+ throw new Error("Target closed");
+ }
+ log(page, `seeked to ${time}`);
+ });
+ const result = await runBrowserCheck(
+ PROJECT,
+ { ...DEFAULT_CHECK_OPTIONS, contrast: false },
+ { kind: "none" },
+ runAuditGrid,
+ );
+ const seeks = vi.mocked(seekCompositionTimeline).mock.calls;
+ vi.mocked(seekCompositionTimeline).mockClear();
+ return {
+ pages,
+ seekingPages: new Set(seeks.map(([page]) => page)).size,
+ messages: result.runtimeFindings.map((finding) => `${finding.time} ${finding.message}`),
+ };
+ };
+
+ const serial = await run(1);
+ const split = await run(4);
+ expect(serial.pages).toHaveLength(1);
+ expect(split.pages).toHaveLength(2);
+ expect(split.seekingPages).toBe(2);
+ const loads = (messages: string[]) => messages.filter((line) => line.includes("at load"));
+ const sampled = (messages: string[]) => messages.filter((line) => !line.includes("at load"));
+ expect(loads(serial.messages)).toHaveLength(1);
+ expect(loads(split.messages)).toHaveLength(1);
+ expect(sampled(split.messages)).toEqual(sampled(serial.messages));
+ expect(serial.messages.length).toBeGreaterThan(3);
+
+ const crashed = await run(4, "crashes");
+ expect(crashed.seekingPages).toBe(2);
+ expect(loads(crashed.messages)).toHaveLength(1);
+ expect(sampled(crashed.messages)).toEqual(sampled(serial.messages));
+ const unopened = await run(4, "never opens");
+ expect(unopened.pages).toHaveLength(2);
+ expect(unopened.seekingPages).toBe(1);
+ expect(loads(unopened.messages)).toHaveLength(1);
+ expect(sampled(unopened.messages)).toEqual(sampled(serial.messages));
+});
+
it("runs the dense overlap grid in one page task, keeping each sample's time on what it logs", async () => {
mountCanvasFixture(
`<section data-composition-file="scenes/copy.html"><p id="copy" data-layout-name="copy">Hi</p></section>`,
@@ -836,6 +919,76 @@ describe("keepBrokenImageAborts", () => {
});
});
+describe("samplingBrowserCount", () => {
+ const GB = 1024 ** 3;
+ it("uses a second Chrome only with a spare core, 250 MB free each and more than one sample", () => {
+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 8, 16 * GB)).toBe(2);
+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 3, 1 * GB)).toBe(2);
+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 2, 16 * GB)).toBe(1);
+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 1, 2 * GB)).toBe(1);
+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 8, 400 * 1024 ** 2)).toBe(1);
+ expect(samplingBrowserCount({ ...DEFAULT_CHECK_OPTIONS, at: [1] }, 8, 16 * GB)).toBe(1);
+ });
+
+ it("counts a container's memory limit, not the host's free memory", () => {
+ vi.mocked(os.freemem).mockReturnValue(100 * GB);
+ vi.mocked(process.availableMemory).mockReturnValue(400 * 1024 ** 2);
+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 8)).toBe(1);
+ vi.mocked(process.availableMemory).mockReturnValue(16 * GB);
+ expect(samplingBrowserCount(DEFAULT_CHECK_OPTIONS, 8)).toBe(2);
+ });
+});
+
+describe("mergeHelperDrafts", () => {
+ const draft = (message: string, time: number) =>
+ ({ code: "console_error", severity: "error", message, time }) as const;
+ it("orders the helper's sample-loop messages by time and drops its load and same-time repeats", () => {
+ const primary = {
+ drafts: [draft("load", 0), draft("at 0", 0), draft("at 2", 2), draft("dense", 0)],
+ start: 1,
+ end: 3,
+ };
+ const helper = {
+ drafts: [draft("load", 0), draft("at 1", 1), draft("at 2", 2), draft("at 3", 3)],
+ start: 1,
+ end: 4,
+ };
+ expect(mergeHelperDrafts(primary, helper).map((entry) => entry.message)).toEqual([
+ "load",
+ "at 0",
+ "at 1",
+ "at 2",
+ "at 3",
+ "dense",
+ ]);
+ });
+
+ it("orders samples the first page redid after its own later ones", () => {
+ const primary = {
+ drafts: [draft("load", 0), draft("at 0", 0), draft("at 2", 2), draft("at 1", 1)],
+ start: 1,
+ end: 4,
+ };
+ const dropped = { drafts: [draft("at 1", 1)], start: Infinity, end: Infinity };
+ expect(mergeHelperDrafts(primary, dropped).map((entry) => entry.message)).toEqual([
+ "load",
+ "at 0",
+ "at 1",
+ "at 2",
+ ]);
+ });
+
+ it("adds nothing from a helper that never sampled", () => {
+ const primary = { drafts: [draft("load", 0)], start: 1, end: 1 };
+ const helper = {
+ drafts: [draft("load", 0)],
+ start: Number.POSITIVE_INFINITY,
+ end: Number.POSITIVE_INFINITY,
+ };
+ expect(mergeHelperDrafts(primary, helper)).toEqual(primary.drafts);
+ });
+});
+
describe("dropFailedProxyEchoes", () => {
it("keeps one finding for a failed proxy and drops the preview's repeats of it", () => {
const at = (code: string, message: string, url?: string) =>
diff --git a/packages/cli/src/utils/checkBrowser.ts b/packages/cli/src/utils/checkBrowser.ts
index afd25868eb..6dc38db92f 100644
--- a/packages/cli/src/utils/checkBrowser.ts
+++ b/packages/cli/src/utils/checkBrowser.ts
@@ -2,6 +2,7 @@ import type { CheckDeadline } from "./checkDeadline.js";
import { BrowserCleanupError, closeManagedBrowser } from "../browser/launch.js";
import { checkSnapshotDirectory } from "./checkSnapshotDirectory.js";
import { mkdirSync, writeFileSync } from "node:fs";
+import os from "node:os";
import { join, resolve } from "node:path";
import type { Browser, Page } from "puppeteer-core";
import {
@@ -223,18 +224,18 @@ export async function runBrowserCheck(
[],
options.autoProxy,
);
- let stamp: RuntimeStamp = { time: 0 };
- const clock: RuntimeClock = {
- now: () => stamp,
- at: (time) => {
- stamp = { time };
- },
- during: (range) => {
- stamp = { time: range[0], timeRange: range };
- },
- };
+ const clock = createRuntimeClock();
let failure: { kind: "none" } | { kind: "failed"; error: unknown } = { kind: "none" };
let chromeBrowser: import("puppeteer-core").Browser | undefined;
+ const helperSession =
+ samplingBrowserCount(options) > 1
+ ? startHelperSession(html, server.url, options, deadline)
+ : undefined;
+ const helperOpen = helperSession?.opened;
+ const helpers = helperOpen?.then(
+ (helper) => [helper.driver],
+ () => [],
+ );
try {
const launchSettleStart = Date.now();
@@ -271,14 +272,18 @@ export async function runBrowserCheck(
const message = tweenTailMessage(tail);
drafts.push({ code: "gsap_tween_tail", severity: "warning", message, time: tail.later.end });
}
- const driver = createPageDriver(page, clock);
- const result = await runGrid(driver, options, motion);
- const broken = await abortedImagesStillBroken(page, drafts);
+ const sampleLog = sampleWindow(drafts);
+ const driver = createPageDriver(page, clock, sampleLog);
+ const result = await runGrid(driver, options, motion, helpers);
+ helperSession?.stop();
+ const helper = await helperOpen?.catch(() => undefined);
+ const merged = helper ? mergeHelperDrafts(sampleLog, helper.sampleLog) : drafts;
+ const broken = await abortedImagesStillBroken(page, merged);
return {
...result,
timings: { ...result.timings, launchSettleMs },
runtimeFindings: dropFailedProxyEchoes(
- keepBrokenImageAborts(drafts, broken),
+ keepBrokenImageAborts(merged, broken),
failedPaths,
).map((draft) => runtimeFinding(draft, rootAnchor)),
};
@@ -286,10 +291,127 @@ export async function runBrowserCheck(
failure = { kind: "failed", error };
throw error;
} finally {
- await closeCheckResources(chromeBrowser, server, failure);
+ helperSession?.stop();
+ await helperOpen?.catch(() => undefined);
+ await closeCheckResources([chromeBrowser, helperSession?.browser()], server, failure);
}
}
+function createRuntimeClock(): RuntimeClock {
+ let stamp: RuntimeStamp = { time: 0 };
+ return {
+ now: () => stamp,
+ at: (time) => {
+ stamp = { time };
+ },
+ during: (range) => {
+ stamp = { time: range[0], timeRange: range };
+ },
+ };
+}
+
+const SAMPLING_BROWSER_BYTES = 250 * 1024 * 1024;
+
+/** Chromes the sample grid splits over: one per spare core and 250 MB free (a container's limit counts), at most 2. */
+export function samplingBrowserCount(
+ options: CheckOptions,
+ cores = os.availableParallelism(),
+ free = Math.min(os.freemem(), process.availableMemory()),
+): number {
+ if (options.at?.length === 1) return 1;
+ return Math.max(1, Math.min(2, cores - 1, Math.floor(free / SAMPLING_BROWSER_BYTES)));
+}
+
+interface SampleWindow {
+ drafts: RuntimeDraft[];
+ start: number;
+ end: number;
+}
+
+function sampleWindow(drafts: RuntimeDraft[]): SampleWindow {
+ return { drafts, start: Number.POSITIVE_INFINITY, end: Number.POSITIVE_INFINITY };
+}
+
+interface HelperSession {
+ driver: CheckAuditDriver;
+ sampleLog: SampleWindow;
+}
+
+/** Opens the helper Chrome; stop() cancels an open still in flight and closes it, once its pages are unused. */
+function startHelperSession(
+ html: string,
+ url: string,
+ options: CheckOptions,
+ deadline: CheckDeadline | undefined,
+) {
+ const abort = new AbortController();
+ let browser: Browser | undefined;
+ const opened = openHelperSession(html, url, options, deadline, {
+ signal: deadline ? AbortSignal.any([deadline.signal, abort.signal]) : abort.signal,
+ onBrowser: (launched) => {
+ browser = launched;
+ deadline?.ownBrowser(launched);
+ },
+ });
+ return {
+ opened,
+ browser: () => browser,
+ stop: () => {
+ abort.abort();
+ // The close is shared, so the check's cleanup awaits this same close and reports its error.
+ if (browser) void closeManagedBrowser(browser).catch(() => undefined);
+ },
+ };
+}
+
+async function openHelperSession(
+ html: string,
+ url: string,
+ options: CheckOptions,
+ deadline: CheckDeadline | undefined,
+ owner: { signal: AbortSignal; onBrowser: (browser: Browser) => void },
+): Promise<HelperSession> {
+ const sampleLog = sampleWindow([]);
+ const clock = createRuntimeClock();
+ const session = await openSettledCompositionPage(html, url, {
+ navigationTimeoutMs: options.timeout,
+ renderReadyTimeoutMs: options.timeout,
+ renderReadyWarningSuffix: "checking the current page state",
+ browserGpuMode: options.browserGpuMode ?? resolveCliChromeGpuMode(),
+ signal: owner.signal,
+ onBrowser: owner.onBrowser,
+ beforeNavigate: async (page) => {
+ wireRuntimeListeners(page, sampleLog.drafts, clock);
+ await deadline?.preparePage(page);
+ },
+ });
+ await waitForPreferredSeekTarget(session.page);
+ return {
+ driver: createPageDriver(session.page, clock, sampleLog),
+ sampleLog,
+ };
+}
+
+const draftKey = (draft: RuntimeDraft) => `${draft.code} ${draft.time} ${draft.message}`;
+
+/**
+ * The first page's drafts with the helper's sample-loop drafts merged in by time, as one page seeking every
+ * sample would have logged them; the helper's load is the first page's, and what both logged at one time counts once.
+ */
+export function mergeHelperDrafts(primary: SampleWindow, helper: SampleWindow): RuntimeDraft[] {
+ const window = ({ drafts, start, end }: SampleWindow) =>
+ drafts.slice(Math.min(start, drafts.length), Math.min(end, drafts.length));
+ const own = window(primary);
+ const seen = new Set(own.map(draftKey));
+ const extra = window(helper).filter((draft) => !seen.has(draftKey(draft)));
+ const start = Math.min(primary.start, primary.drafts.length);
+ return [
+ ...primary.drafts.slice(0, start),
+ ...[...own, ...extra].sort((a, b) => a.time - b.time),
+ ...primary.drafts.slice(start + own.length),
+ ];
+}
+
/**
* `check --snapshots`'s per-finding evidence crops. Opens its own session
* (the main grid session already closed by the time findings are shaped) and
@@ -348,17 +470,17 @@ export async function captureFindingCrops(
failure = { kind: "failed", error };
throw error;
} finally {
- await closeCheckResources(chromeBrowser, server, failure);
+ await closeCheckResources([chromeBrowser], server, failure);
}
}
async function closeCheckResources(
- browser: Browser | undefined,
+ browsers: (Browser | undefined)[],
server: { close(): Promise<void> },
failure: { kind: "none" } | { kind: "failed"; error: unknown },
): Promise<void> {
const cleanup = await Promise.allSettled([
- browser ? closeManagedBrowser(browser) : Promise.resolve(),
+ ...browsers.map((browser) => (browser ? closeManagedBrowser(browser) : Promise.resolve())),
server.close(),
]);
const errors = cleanup
@@ -585,9 +707,18 @@ function wireNetworkListeners(page: Page, drafts: RuntimeDraft[], clock: Runtime
});
}
-function createPageDriver(page: Page, clock: RuntimeClock): CheckAuditDriver {
+function createPageDriver(
+ page: Page,
+ clock: RuntimeClock,
+ sampleLog?: SampleWindow,
+): CheckAuditDriver {
return {
initialize: (contrast) => injectAuditScripts(page, contrast),
+ markSamples: (phase) => {
+ if (!sampleLog) return;
+ if (phase === "drop") sampleLog.start = sampleLog.end = Number.POSITIVE_INFINITY;
+ else sampleLog[phase] = sampleLog.drafts.length;
+ },
matchComponents: (components, findings) =>
page.evaluate(matchComponentFindings, { components, findings }),
getDuration: () => getCompositionDuration(page),
diff --git a/packages/cli/src/utils/checkPipeline.ts b/packages/cli/src/utils/checkPipeline.ts
index 2d5efd0343..14322bc698 100644
--- a/packages/cli/src/utils/checkPipeline.ts
+++ b/packages/cli/src/utils/checkPipeline.ts
@@ -424,18 +424,8 @@ async function collectGeometryAt(
return issues;
}
-async function collectGridSamples(
- driver: CheckAuditDriver,
- options: CheckOptions,
- grid: SampleGrid,
- motion: MotionPlan,
-): Promise<GridSamples> {
- const layoutSet = new Set(grid.layoutSamples);
- const motionSet = new Set(motion.times);
- const contrastSet = new Set(grid.contrastSamples);
- const geometryEnabled = grid.captionSamples.length > 0 || grid.frameSamples.length > 0;
- const canvas = geometryEnabled ? await driver.getCanvas() : null;
- const collected: GridSamples = {
+function emptyGridSamples(): GridSamples {
+ return {
layoutIssues: [],
motionFrames: [],
contrastEntries: [],
@@ -445,37 +435,121 @@ async function collectGridSamples(
rotationSamples: [],
indicatorFrames: [],
};
- for (const time of mergeSampleTimes(grid.layoutSamples, motion.times)) {
- await driver.seek(time, contrastSet.has(time));
- // Findings collected for THIS sample time, so the overview overlay (below)
- // only ever annotates a frame with defects that are actually valid at
- // that render time — never a stale bbox from an earlier/later sample.
- const issuesAtTime: AnchoredLayoutIssue[] = [];
- if (layoutSet.has(time)) {
- const layoutIssues = await driver.collectLayout(time, options.tolerance, options.layout);
- collected.layoutIssues.push(...layoutIssues);
- issuesAtTime.push(...layoutIssues);
- collected.layoutStateSignatures.push({
- time,
- signature: await driver.collectLayoutGeometry(),
- clock: await driver.collectSeekClock(),
- });
- collected.rotationSamples.push(...(await driver.collectRotationSample(time)));
- collected.indicatorFrames.push(await driver.collectOffPivotRotationSample(time));
- }
- if (canvas) {
- const geometryIssues = await collectGeometryAt(driver, options, grid, canvas, time);
- collected.layoutIssues.push(...geometryIssues);
- issuesAtTime.push(...geometryIssues);
+}
+
+function appendGridSamples(into: GridSamples, from: GridSamples): void {
+ into.layoutIssues.push(...from.layoutIssues);
+ into.motionFrames.push(...from.motionFrames);
+ into.contrastEntries.push(...from.contrastEntries);
+ into.screenshots.push(...from.screenshots);
+ // Summed over pages, so with a helper it can exceed the wall time.
+ into.contrastMs += from.contrastMs;
+ into.layoutStateSignatures.push(...from.layoutStateSignatures);
+ into.rotationSamples.push(...from.rotationSamples);
+ into.indicatorFrames.push(...from.indicatorFrames);
+}
+
+interface SampleSets {
+ layout: Set<number>;
+ motion: Set<number>;
+ contrast: Set<number>;
+ canvas: Canvas | null;
+}
+
+async function collectSampleAt(
+ driver: CheckAuditDriver,
+ options: CheckOptions,
+ grid: SampleGrid,
+ motion: MotionPlan,
+ sets: SampleSets,
+ time: number,
+): Promise<GridSamples> {
+ const collected = emptyGridSamples();
+ await driver.seek(time, sets.contrast.has(time));
+ // Findings collected for THIS sample time, so the overview overlay (below)
+ // only ever annotates a frame with defects that are actually valid at
+ // that render time — never a stale bbox from an earlier/later sample.
+ const issuesAtTime: AnchoredLayoutIssue[] = [];
+ if (sets.layout.has(time)) {
+ const layoutIssues = await driver.collectLayout(time, options.tolerance, options.layout);
+ collected.layoutIssues.push(...layoutIssues);
+ issuesAtTime.push(...layoutIssues);
+ collected.layoutStateSignatures.push({
+ time,
+ signature: await driver.collectLayoutGeometry(),
+ clock: await driver.collectSeekClock(),
+ });
+ collected.rotationSamples.push(...(await driver.collectRotationSample(time)));
+ collected.indicatorFrames.push(await driver.collectOffPivotRotationSample(time));
+ }
+ if (sets.canvas) {
+ const geometryIssues = await collectGeometryAt(driver, options, grid, sets.canvas, time);
+ collected.layoutIssues.push(...geometryIssues);
+ issuesAtTime.push(...geometryIssues);
+ }
+ if (sets.motion.has(time)) {
+ collected.motionFrames.push(
+ await driver.collectMotionFrame(time, motion.selectors, motion.livenessScopes),
+ );
+ }
+ if (sets.contrast.has(time))
+ await collectContrastAt(driver, options, time, issuesAtTime, collected);
+ return collected;
+}
+
+// Frames are a function of time, so a helper page that is ready takes the next unclaimed sample
+// and the merge keeps the serial order. A helper only adds speed: one that fails hands its samples back.
+async function collectGridSamples(
+ driver: CheckAuditDriver,
+ options: CheckOptions,
+ grid: SampleGrid,
+ motion: MotionPlan,
+ helpers: Promise<CheckAuditDriver[]>,
+): Promise<GridSamples> {
+ const geometryEnabled = grid.captionSamples.length > 0 || grid.frameSamples.length > 0;
+ const sets: SampleSets = {
+ layout: new Set(grid.layoutSamples),
+ motion: new Set(motion.times),
+ contrast: new Set(grid.contrastSamples),
+ canvas: geometryEnabled ? await driver.getCanvas() : null,
+ };
+ const times = mergeSampleTimes(grid.layoutSamples, motion.times);
+ const pending = times.map((_, index) => index);
+ const perTime: GridSamples[] = [];
+ const work = async (worker: CheckAuditDriver, taken: number[] = []) => {
+ for (let index = pending.shift(); index !== undefined; index = pending.shift()) {
+ taken.push(index);
+ const time = times[index] ?? 0;
+ perTime[index] = await collectSampleAt(worker, options, grid, motion, sets, time);
}
- if (motionSet.has(time)) {
- collected.motionFrames.push(
- await driver.collectMotionFrame(time, motion.selectors, motion.livenessScopes),
- );
+ };
+ const helpWith = async (helper: CheckAuditDriver) => {
+ const taken: number[] = [];
+ try {
+ await helper.initialize(options.contrast);
+ helper.markSamples?.("start");
+ await work(helper, taken);
+ helper.markSamples?.("end");
+ } catch {
+ helper.markSamples?.("drop");
+ for (const index of taken) delete perTime[index];
+ pending.push(...taken);
}
- if (contrastSet.has(time))
- await collectContrastAt(driver, options, time, issuesAtTime, collected);
- }
+ };
+ let firstPageDone = false;
+ const running: Promise<void>[] = [];
+ void helpers.then((ready) => {
+ for (const helper of ready) if (!firstPageDone) running.push(helpWith(helper));
+ });
+ driver.markSamples?.("start");
+ await work(driver);
+ // A helper still opening is never waited for; one mid-sample may yet hand samples back.
+ firstPageDone = true;
+ await Promise.all(running);
+ await work(driver);
+ driver.markSamples?.("end");
+ const collected = emptyGridSamples();
+ for (const samples of perTime) appendGridSamples(collected, samples);
await collectMotionOverlapSamples(driver, grid, collected, options.range);
return collected;
}
@@ -1225,6 +1299,7 @@ export async function runAuditGrid(
driver: CheckAuditDriver,
options: CheckOptions,
motion: MotionSpecResolution,
+ helpers: Promise<CheckAuditDriver[]> = Promise.resolve([]),
): Promise<CheckBrowserResult> {
await driver.initialize(options.contrast);
const grid = await buildSampleGrid(driver, options);
@@ -1234,7 +1309,7 @@ export async function runAuditGrid(
grid.duration,
);
const seekLoopStart = Date.now();
- const collected = await collectGridSamples(driver, options, grid, plan);
+ const collected = await collectGridSamples(driver, options, grid, plan, helpers);
const seekLoopMs = Date.now() - seekLoopStart;
let motionIssues = plan.preflightIssues;
diff --git a/packages/cli/src/utils/checkTypes.ts b/packages/cli/src/utils/checkTypes.ts
index 9081da74d3..27938ece79 100644
--- a/packages/cli/src/utils/checkTypes.ts
+++ b/packages/cli/src/utils/checkTypes.ts
@@ -192,6 +192,7 @@ export type MotionSpecResolution =
export interface CheckAuditDriver {
initialize(contrast: boolean): Promise<void>;
+ markSamples?(phase: "start" | "end" | "drop"): void;
matchComponents?(components: string[], findings: CheckFinding[]): Promise<boolean[]>;
getDuration(): Promise<number>;
/** True when the root composition explicitly declares that it is intentionally timeline-free. */
@@ -272,6 +273,7 @@ export type RunAuditGrid = (
driver: CheckAuditDriver,
options: CheckOptions,
motion: MotionSpecResolution,
+ helpers?: Promise<CheckAuditDriver[]>,
) => Promise<CheckBrowserResult>;
export interface CheckSection<T extends CheckFinding = CheckFinding> {