LibreChat/e2e/lighthouse/measure.mts
Danny Avila 445668a371
🧭 ci: Assert Lighthouse Blocking Time at a Reference CPU on the Quietest Run (#18406)
Total blocking time is CPU time, and the hosted runner's CPU is not a constant: Lighthouse's
own benchmark of the runner moves by more than 2x between consecutive runs of one build on a
two-core runner, and blocking time moves with it. A median of three raw measurements against
a fixed budget therefore fails on the runner rather than on the page.

Rescale each run's main-thread tasks by that run's benchmark index to a reference CPU, assert
the lowest run instead of the median, and measure an over-budget batch once more before
failing. Budgets move to their own file so a fork with a heavier client changes numbers only.
2026-11-18 07:47:01 -05:00

111 lines
3.9 KiB
TypeScript

import type Result from 'lighthouse/types/lhr/lhr.js';
import type { Budgets } from './budgets.mts';
/**
* Lighthouse's CPU benchmark score on the hosted runners the budgets are calibrated against.
* Blocking time is restated at this speed: one build has measured 613, 191 and 159 ms of it in
* three consecutive runs, and the benchmark moves with whatever else the runner is doing.
*/
export const REFERENCE_BENCHMARK_INDEX = 2750;
/** Only the part of a main-thread task that runs past this blocks input. */
const BLOCKING_THRESHOLD_MS = 50;
const BLOCKING_AUDIT = 'total-blocking-time';
export interface Task {
startTime: number;
duration: number;
}
/** First contentful paint to time to interactive, in ms after navigation start. */
export interface Window {
start: number;
end: number;
}
export interface Measurement {
audit: string;
statistic: string;
value: number;
limit: number;
}
/**
* Total blocking time with every task `cpuScale` times as long. At a scale of 1 this is
* Lighthouse's own sum: each task's tail past the threshold, clipped to the window.
*/
export function blockingTime(tasks: Task[], window: Window, cpuScale = 1): number {
let total = 0;
for (const { startTime, duration } of tasks) {
const blocking = duration * cpuScale - BLOCKING_THRESHOLD_MS;
if (blocking <= 0) continue;
// A task too short to block on this runner has no tail, so its whole span stands in.
const tail = duration > BLOCKING_THRESHOLD_MS ? duration - BLOCKING_THRESHOLD_MS : duration;
const end = startTime + duration;
const counted = Math.min(end, window.end) - Math.max(end - tail, window.start);
if (counted > 0) total += blocking * (counted / tail);
}
return total;
}
/** One run's blocking time as the reference CPU would have measured it. */
export function referenceBlockingTime(report: Result): number {
const tasks = report.audits['main-thread-tasks']?.details;
const start = report.audits['first-contentful-paint']?.numericValue;
const end = report.audits['interactive']?.numericValue;
const benchmarkIndex = report.environment?.benchmarkIndex;
if (
tasks?.type !== 'table' ||
typeof start !== 'number' ||
typeof end !== 'number' ||
typeof benchmarkIndex !== 'number' ||
benchmarkIndex <= 0
) {
throw new Error(
'Lighthouse reported no main-thread tasks, paint window or CPU benchmark; check `main-thread-tasks`, `first-contentful-paint`, `interactive` and `environment.benchmarkIndex`.',
);
}
return blockingTime(
tasks.items.map((item) => ({
startTime: Number(item.startTime),
duration: Number(item.duration),
})),
{ start, end },
benchmarkIndex / REFERENCE_BENCHMARK_INDEX,
);
}
function median(results: Result[], audit: string): number {
const values = results
.map((report) => report.audits[audit]?.numericValue)
.filter((value): value is number => typeof value === 'number')
.sort((a, b) => a - b);
if (!values.length || values.length !== results.length) {
throw new Error(`Lighthouse must report a numeric ${audit} for every run`);
}
const middle = values.length >> 1;
return values.length % 2 ? values[middle] : (values[middle - 1] + values[middle]) / 2;
}
/**
* Blocking time takes the lowest run rather than the median: a busy runner only ever adds
* blocking time, so the quietest run is the closest to what the page itself costs.
*/
export function measure(results: Result[], budgets: Budgets): Measurement[] {
return Object.entries(budgets).map(([audit, limit]) => {
if (audit !== BLOCKING_AUDIT) {
return { audit, statistic: 'median', value: median(results, audit), limit };
}
if (!results.length) {
throw new Error(`Lighthouse must report a numeric ${audit} for every run`);
}
return {
audit,
statistic: 'lowest, at reference CPU',
value: Math.min(...results.map(referenceBlockingTime)),
limit,
};
});
}