webperf-snippets 1.5.0 → 1.6.0

package/src/reporters/human.js

@@ -1,9 +1,12 @@
 import { styleText } from "node:util";
+import { describeResult } from "../view.js";
+import { isSummaryResult, summaryNumbers } from "./summary-view.js";
 import { fieldDataView } from "../crux.js";
 import { describeThrottling } from "../throttling.js";
 import { describeRuns } from "../runs.js";
 import { matrixView } from "./matrix-view.js";
 import { baselineView } from "./baseline-view.js";
+import { budgetRows, matrixBudgetFailures } from "./budgets-view.js";
 
 const RATING_ICON = {
   good: "🟢",
@@ -102,12 +105,12 @@ function renderAuditResult(r, verbose) {
   const items = r.items ?? [];
   if (items.length > 0 && (!isGreen || verbose)) {
     lines.push("");
-    const shown = items.slice(0, MAX_ITEMS);
-    for (const item of shown) {
-      const name = item.shortName ?? item.resource ?? item.url ?? item.src ?? item.selector ?? item.filename ?? item.target ?? "";
-      const tag = item.type ?? item.tag ?? item.strategy ?? item.media ?? item.kind ?? "";
-      const timing = item.responseEndMs != null ? `${item.responseEndMs}ms` : item.durationMs != null ? `${item.durationMs}ms` : "";
-      const cols = [tag, name, item.detail, timing].filter(Boolean).join("  ");
+    // The cells of each row as the view gives them: the file of a URL, the values in their units
+    const { rows, constants } = describeResult(r);
+    // The values that are the same in every row, once above them, as in the extension
+    if (constants.length) lines.push(`     ${styleText("dim", constants.map((c) => `${c.label} ${c.text}`).join(" · "))}`);
+    for (const row of rows.slice(0, MAX_ITEMS)) {
+      const cols = row.cells.map((c) => c.text).filter(Boolean).join("  ");
       if (cols) lines.push(`     ${styleText("dim", `· ${cols}`)}`);
     }
     if (items.length > MAX_ITEMS) {
@@ -125,10 +128,7 @@ function renderAuditResult(r, verbose) {
 // A result with a count and details but no value and no issues, such as the long tasks: the count,
 // then the first numbers of its details.
 function renderSummaryResult(r) {
-  const numbers = Object.entries(r.details ?? {})
-    .filter(([, value]) => typeof value === "number")
-    .slice(0, 3)
-    .map(([key, value]) => `${key} ${value}`);
+  const numbers = summaryNumbers(r);
   const summary = [r.count !== undefined ? String(r.count) : null, ...numbers].filter(Boolean).join("  ·  ");
   return `  ${RATING_ICON[r.rating] ?? "·"} ${pad(r.id, 16)} ${styleText("dim", summary)}`;
 }
@@ -142,6 +142,11 @@ function renderResult(r, verbose) {
     return `  ${styleText("red", "✗")} ${pad(r.id, 16)} ${styleText("dim", r.error)}`;
   }
 
+  // A tracking snippet with nothing recorded, such as INP without interactions, measured nothing
+  if (r.status === "tracking") {
+    return `  ${styleText("dim", "·")} ${pad(r.id, 16)} ${styleText("dim", `not measured: ${r.message ?? "nothing recorded"}`)}`;
+  }
+
   if (r.script === "Fonts-Preloaded-Loaded-and-used-above-the-fold") {
     return renderFontsResult(r);
   }
@@ -150,7 +155,7 @@ function renderResult(r, verbose) {
     return renderAuditResult(r, verbose);
   }
 
-  if (r.value === undefined && (r.count !== undefined || r.details)) {
+  if (isSummaryResult(r)) {
     return renderSummaryResult(r);
   }
 
@@ -163,12 +168,10 @@ function renderResult(r, verbose) {
 
   if (r.metric === "LCP" && r.details?.subParts) {
     const sp = r.details.subParts;
-    const rows = [
-      ["TTFB", sp.ttfb],
-      ["Resource Load Delay", sp.resourceLoadDelay],
-      ["Resource Load Time", sp.resourceLoadTime],
-      ["Element Render Delay", sp.elementRenderDelay],
-    ];
+    const view = describeResult(r);
+    // The phases with the labels of the view, and the slowest one by its label, not its key
+    const phases = view.details.find((d) => d.key === "subParts" && d.format === "phases");
+    const rows = (phases?.parts ?? []).map((p) => [p.label, sp[p.key]]);
     out += "\n";
     out += rows
       .map(([name, info]) => {
@@ -180,8 +183,9 @@ function renderResult(r, verbose) {
           : `${row}\n         ${styleText("dim", `${info.waiting}ms waiting for the server, ${info.download}ms downloading`)}`;
       })
       .join("\n");
-    if (r.details.slowestPhase) {
-      out += `\n       ${styleText("blue", "→ Slowest:")} ${r.details.slowestPhase}`;
+    const slowest = view.details.find((d) => d.key === "slowestPhase");
+    if (slowest) {
+      out += `\n       ${styleText("blue", "→ Slowest:")} ${slowest.text}`;
     }
   }
 
@@ -218,6 +222,16 @@ function renderRuns(runs) {
 
 const VERDICT_STYLE = { regressed: "red", improved: "green", unchanged: "dim", "not measured": "dim", new: "cyan" };
 
+// Every budget the run was given, passed or not, so the report says which one decided the exit code
+function renderBudgets(budgets) {
+  const lines = ["", styleText("bold", "Budgets")];
+  for (const row of budgetRows(budgets, formatValue)) {
+    const mark = row.passed ? styleText("green", "✓") : styleText("red", "✗");
+    lines.push(`  ${mark} ${pad(row.metric, 6)}${pad(row.value, 10)}${pad(`budget ${row.budget}`, 18)}${styleText(row.passed ? "green" : "red", row.verdict)}`);
+  }
+  return lines;
+}
+
 // The comparison with --baseline, after the report: its warnings first, since they say how far to
 // trust the table, then a row per metric and the errors that appeared or went away
 function renderBaseline(comparison) {
@@ -235,7 +249,7 @@ function renderBaseline(comparison) {
   return lines;
 }
 
-export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, throttling, runs, baseline, title = `WebPerf Snippets — ${url}` }) {
+export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, throttling, runs, baseline, budgets, title = `WebPerf Snippets — ${url}` }) {
   const lines = [];
   lines.push(styleText(["bold"], title));
   lines.push(styleText("dim", `Navigated in ${navMs}ms`));
@@ -252,6 +266,7 @@ export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, th
     lines.push(styleText("yellow", "Page errors during run:"));
     for (const err of pageErrors) lines.push(`  ${styleText("dim", err)}`);
   }
+  if (budgets?.length) lines.push(...renderBudgets(budgets));
   if (baseline) lines.push(...renderBaseline(baseline));
   return lines.join("\n");
 }
@@ -289,6 +304,13 @@ export function reportMatrixHuman(report) {
     for (const e of errors) lines.push(`  ${styleText("red", "✗")} ${e}`);
   }
 
+  const budgetFailures = matrixBudgetFailures(report.combinations, formatValue);
+  if (budgetFailures) {
+    lines.push("", styleText("bold", "Budgets"));
+    for (const f of budgetFailures) lines.push(`  ${styleText("red", "✗")} ${f}`);
+    if (!budgetFailures.length) lines.push(`  ${styleText("green", "✓ Every budget passed")}`);
+  }
+
   if (comparison) {
     lines.push("", styleText("bold", `Compared with ${comparison.file}`));
     for (const warning of comparison.warnings) lines.push(`  ${styleText("yellow", `Warning: ${warning}`)}`);

package/src/reporters/markdown.js

@@ -1,8 +1,11 @@
 import { fieldDataView } from "../crux.js";
+import { describeResult } from "../view.js";
+import { isSummaryResult, summaryNumbers } from "./summary-view.js";
 import { describeThrottling } from "../throttling.js";
 import { describeRuns } from "../runs.js";
 import { matrixView } from "./matrix-view.js";
 import { baselineView } from "./baseline-view.js";
+import { budgetRows, matrixBudgetFailures } from "./budgets-view.js";
 
 const RATING_ICON = {
   good: "✅",
@@ -39,10 +42,22 @@ function renderSkippedRow(r) {
   return `| ${r.id} | ⏭ skipped | ${r.reason} |`;
 }
 
+// A tracking snippet with nothing recorded, such as INP without interactions, measured nothing
+function renderNotMeasuredRow(r) {
+  return `| ${r.id} | · not measured | ${r.message ?? "nothing recorded"} |`;
+}
+
+// A result with a count and no value: its count, and its first numbers as the human report gives them
+function renderSummaryRow(r) {
+  return `| ${r.id} | · ${r.count ?? ""} | ${summaryNumbers(r).join(" · ")} |`;
+}
+
 function renderRow(r) {
   if (r.status === "skipped") return renderSkippedRow(r);
   if (r.status === "error") return renderErrorRow(r);
+  if (r.status === "tracking") return renderNotMeasuredRow(r);
   if (Array.isArray(r.issues)) return renderAuditRow(r);
+  if (isSummaryResult(r)) return renderSummaryRow(r);
   return renderMetricRow(r);
 }
 
@@ -53,11 +68,36 @@ function sectionHeader(results) {
   return ["| Metric | Value | Status |", "|--------|-------|--------|"];
 }
 
+// Text from the page in a list item: the characters that markdown reads as emphasis or code, escaped
+const md = (text) => String(text).replace(/[\\`*_[\]]/g, "\\$&");
+
+// A field of the view as a list item, with the labels and formats of the extension: a nested table is
+// a line per row, and the fields of an object are items under it
+function detailLines(field, indent = "") {
+  if (field.format === "table") {
+    return [`${indent}- **${md(field.label)}**:`, ...field.rows.map((row) => `${indent}  - ${row.cells.map((c) => md(c.text)).filter(Boolean).join(" · ")}`)];
+  }
+  if (field.format === "fields") {
+    return [`${indent}- **${md(field.label)}**:`, ...field.fields.flatMap((f) => detailLines(f, `${indent}  `))];
+  }
+  return [`${indent}- **${md(field.label)}**: ${md(field.text)}`];
+}
+
+// The details of each result, folded under its id, so the comment of a pull request stays short
+function renderDetails(results) {
+  return results.flatMap((r) => {
+    const { details } = describeResult(r);
+    if (details.length === 0) return [];
+    return ["", `<details><summary>${r.id}</summary>`, "", ...details.flatMap((f) => detailLines(f)), "", "</details>"];
+  });
+}
+
 function renderSection(title, results) {
   return [
     `### ${title}`,
     ...sectionHeader(results),
     ...results.map(renderRow),
+    ...renderDetails(results),
   ].join("\n");
 }
 
@@ -104,7 +144,13 @@ function renderBaseline(comparison) {
 }
 
 // With a null title, the report has no heading, as inside the details block of a matrix
-export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttling, runs, baseline, title = `WebPerf Results — ${url}` }) {
+// Every budget the run was given, passed or not: the comment of a pull request says which one failed
+function renderBudgets(budgets) {
+  const rows = budgetRows(budgets, formatValue).map((row) => `| ${row.metric} | ${row.value} | ${row.budget} | ${row.passed ? "✅" : "❌"} ${row.verdict} |`);
+  return ["", "### Budgets", "| Metric | Value | Budget | Verdict |", "|--------|-------|--------|---------|", ...rows];
+}
+
+export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttling, runs, baseline, budgets, title = `WebPerf Results — ${url}` }) {
   const lines = [];
   if (title) lines.push(`## ${title}`);
   lines.push(`> Navigated in ${navMs}ms`);
@@ -140,6 +186,7 @@ export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttli
     for (const err of pageErrors) lines.push(`- ${err}`);
   }
 
+  if (budgets?.length) lines.push(...renderBudgets(budgets));
   if (baseline) lines.push(...renderBaseline(baseline));
 
   return lines.join("\n");
@@ -172,6 +219,11 @@ export function reportMatrixMarkdown(report) {
     lines.push("", "### Errors", ...errors.map((e) => `- ${e}`));
   }
 
+  const budgetFailures = matrixBudgetFailures(report.combinations, formatValue);
+  if (budgetFailures) {
+    lines.push("", "### Budgets", ...(budgetFailures.length ? budgetFailures.map((f) => `- ❌ ${f}`) : ["✅ Every budget passed"]));
+  }
+
   if (comparison) {
     lines.push("", `### Compared with \`${comparison.file}\``);
     if (comparison.warnings.length) lines.push(...comparison.warnings.flatMap((w, i) => [...(i ? [">"] : []), `> ⚠️ ${w}`]), "");

package/src/reporters/summary-view.js

@@ -0,0 +1,12 @@
+import { describeResult } from "../view.js";
+
+// A result with a count and details but no value and no issues, such as the long tasks: whether it is
+// one, and its first numbers with the labels and formats of the view, which both reports show
+export const isSummaryResult = (r) => r.value === undefined && !Array.isArray(r.issues) && (r.count !== undefined || r.details !== undefined);
+
+export function summaryNumbers(r) {
+  return describeResult(r)
+    .details.filter((d) => typeof d.value === "number")
+    .slice(0, 3)
+    .map((d) => `${d.label} ${d.text}`);
+}

package/src/runner.js

@@ -16,8 +16,8 @@ export const VIEWPORT_PRESETS = {
 const DEFAULT_NAV_TIMEOUT = 30000;
 
 // On a loaded machine the browser can deliver the timing of a click later than the frames `settle`
-// waits for. After a click or a key press, a tracking snippet that has no data yet is read again,
-// every POLL_MS, until it has some or LATE_ENTRIES_MS have passed.
+// waits for. After a click or a key press, a tracking snippet that has no data yet, and so is still
+// tracking, is read again every POLL_MS until it has some or LATE_ENTRIES_MS have passed.
 const LATE_ENTRIES_MS = 2000;
 const POLL_MS = 100;
 
@@ -79,7 +79,7 @@ export async function collectTrackingData(page, result, hasInput) {
     const read = () => page.evaluate(`(async () => await ${result.getDataFn}())()`);
     let data = await read();
     const deadline = Date.now() + LATE_ENTRIES_MS;
-    while (hasInput && data?.status === "error" && Date.now() < deadline) {
+    while (hasInput && data?.status === "tracking" && Date.now() < deadline) {
       await page.waitForTimeout(POLL_MS);
       data = await read();
     }

package/src/view.js

@@ -0,0 +1,11 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { SNIPPET_DIRS } from "./load-snippet.js";
+
+// The view of a result (snippets/_view/): the labels, formats and order the extension shows, so the
+// reports say the same. It comes with the snippets, in the package or at the root of the repository.
+const dir = SNIPPET_DIRS.find((d) => existsSync(join(d, "_view", "index.js")));
+if (!dir) throw new Error("The view of the results is missing: snippets/_view/index.js");
+
+export const { describeResult } = await import(pathToFileURL(join(dir, "_view", "index.js")).href);

package/src/workflows/interaction.js

@@ -24,6 +24,7 @@ export const interactionWorkflow = {
     { id: "scroll", path: "Interaction/Scroll-Performance" },
     { id: "layout-shifts", path: "Interaction/Layout-Shift-Loading-and-Interaction" },
     { id: "forced-layout", path: "Interaction/Forced-Synchronous-Layout" },
+    { id: "INP", path: "CoreWebVitals/INP", needsInput: true },
     { id: "interactions", path: "Interaction/Interactions", needsInput: true },
     { id: "input-latency", path: "Interaction/Input-Latency-Breakdown", needsInput: true },
   ],