webperf-snippets 1.5.0 → 1.7.0

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/url.js

@@ -0,0 +1,8 @@
+// The pages the CLI measures: http and https only, local servers included. It loads a URL in a browser
+// and returns what the snippets read from it, so a file:// URL would hand the files of the machine to
+// whoever reads the result, an agent among them; javascript:, data: and chrome:// are not pages to
+// measure either. The command line, the matrix file and the MCP server share this rule.
+export function isHttpUrl(value) {
+  if (typeof value !== "string" || !URL.canParse(value)) return false;
+  return ["http:", "https:"].includes(new URL(value).protocol);
+}

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 },
   ],