webperf-snippets 1.2.0 → 1.4.0

package/src/reporters/baseline-view.js

@@ -0,0 +1,83 @@
+// The comparison with a baseline as the human and markdown reports draw it: one row per metric with
+// its two values, the change and the verdict, and why an unchanged one did not count. The values stay
+// numbers with their unit, for each report to format.
+
+const MINUS = "−";
+const signed = (n, text) => (n > 0 ? `+${text}` : n < 0 ? `${MINUS}${text}` : text);
+const arrow = (delta) => (delta > 0 ? "▲" : delta < 0 ? "▼" : "=");
+const unitOf = (metric) => (metric === "CLS" ? "score" : "ms");
+
+// "▲ +380ms (+18%)", "▼ −90ms (−15%)", "▼ −0.0020"
+function describeChange(metric, { delta, deltaPercent }) {
+  if (metric === "CLS") return `${arrow(delta)} ${signed(delta, Math.abs(delta).toFixed(4))}`;
+  const ms = signed(delta, `${Math.abs(Math.round(delta))}ms`);
+  const percent = deltaPercent == null ? "" : ` (${signed(deltaPercent, `${Math.abs(Math.round(deltaPercent))}%`)})`;
+  return `${arrow(delta)} ${ms}${percent}`;
+}
+
+// An unchanged metric that moved stayed under its threshold, or beat it inside the range of the runs
+// of the baseline: noise the baseline already had
+function noteOf(metric, m) {
+  if (m.verdict !== "unchanged" || m.delta === 0) return null;
+  if (Math.abs(m.delta) > m.threshold) return "inside the range of the baseline";
+  return `under ${metric === "CLS" ? m.threshold : `${Math.round(m.threshold)}ms`}`;
+}
+
+export function baselineView({ file, url, runs, metrics, errors, warnings }) {
+  const summary = `${url}, ${runs.count === 1 ? "1 run" : `${runs.count} runs, median by ${runs.medianBy}`}`;
+  const rows = Object.entries(metrics).map(([metric, m]) => ({
+    metric,
+    unit: unitOf(metric),
+    baseline: m.baseline,
+    current: m.current,
+    change: m.verdict === "not measured" ? null : describeChange(metric, m),
+    verdict: m.verdict,
+    note: m.verdict === "not measured" ? null : noteOf(metric, m),
+  }));
+  return { file, summary, rows, newErrors: errors.new, fixedErrors: errors.fixed, warnings };
+}
+
+// What got worse, one line each, for --fail-on-regression: the metrics that regressed and the errors
+// that only this run has
+export function describeRegressions({ metrics, errors }) {
+  return [
+    ...Object.entries(metrics)
+      .filter(([, m]) => m.verdict === "regressed")
+      .map(([metric, m]) => `${metric} ${describeChange(metric, m)}`),
+    ...errors.new.map((e) => `new error ${e.id}: ${e.message}`),
+  ];
+}
+
+// The change of a metric in a cell of the matrix table: the figure only when it counts, so the table
+// reads at a glance. "▲ +380ms", "▼ −400ms", "=" for unchanged, "·" when one side did not measure it.
+export function changeCell(metric, m) {
+  if (m.verdict === "not measured") return { text: "·", verdict: m.verdict };
+  if (m.verdict === "unchanged") return { text: "=", verdict: m.verdict };
+  const amount = metric === "CLS" ? Math.abs(m.delta).toFixed(4) : `${Math.abs(Math.round(m.delta))}ms`;
+  return { text: `${arrow(m.delta)} ${signed(m.delta, amount)}`, verdict: m.verdict };
+}
+
+// The comparison of a matrix below its table. A warning that every compared combination has, such as
+// a baseline of one run, shows once; the others name their combinations.
+export function matrixComparisonView(root, combinations) {
+  const compared = combinations.filter((c) => c.baseline);
+  const idsByWarning = new Map();
+  for (const c of compared) {
+    for (const warning of c.baseline.warnings) idsByWarning.set(warning, [...(idsByWarning.get(warning) ?? []), c.id]);
+  }
+  const warnings = [...idsByWarning].map(([warning, ids]) => (ids.length === compared.length ? warning : `${ids.join(", ")}: ${warning}`));
+  const errorsOf = (kind) => compared.flatMap((c) => c.baseline.errors[kind].map((e) => `${c.id}: ${e.id}: ${e.message}`));
+  return {
+    file: root.file,
+    warnings: [...root.warnings, ...warnings],
+    newErrors: errorsOf("new"),
+    fixedErrors: errorsOf("fixed"),
+    added: root.added,
+    missing: root.missing,
+  };
+}
+
+// The regressions of every combination, each named by its combination
+export function describeMatrixRegressions(combinations) {
+  return combinations.filter((c) => c.baseline).flatMap((c) => describeRegressions(c.baseline).map((r) => `${c.id}: ${r}`));
+}

package/src/reporters/human.js

@@ -1,6 +1,9 @@
 import { styleText } from "node:util";
 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";
 
 const RATING_ICON = {
   good: "🟢",
@@ -203,11 +206,41 @@ function renderFieldData(crux, results) {
   return lines;
 }
 
-export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, throttling }) {
+// The runs line, and the median, min and max of each metric across the runs
+function renderRuns(runs) {
+  const lines = [styleText("dim", describeRuns(runs))];
+  for (const [metric, { median, min, max, unit }] of Object.entries(runs.summary)) {
+    const cell = (label, value) => pad(`${label} ${formatValue(value, unit)}`, 16);
+    lines.push(styleText("dim", `  ${pad(metric, 6)}${cell("median", median)}${cell("min", min)}${cell("max", max).trimEnd()}`));
+  }
+  return lines;
+}
+
+const VERDICT_STYLE = { regressed: "red", improved: "green", unchanged: "dim", "not measured": "dim", new: "cyan" };
+
+// 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) {
+  const view = baselineView(comparison);
+  const lines = ["", styleText("bold", `Compared with ${view.file} (${view.summary})`)];
+  for (const warning of view.warnings) lines.push(`  ${styleText("yellow", `Warning: ${warning}`)}`);
+  lines.push(styleText("dim", `  ${pad("Metric", 9)}${pad("Baseline", 11)}${pad("Now", 10)}Change`));
+  for (const row of view.rows) {
+    const value = (v) => (v == null ? "·" : formatValue(v, row.unit));
+    const verdict = row.note ? `${row.verdict} (${row.note})` : row.verdict;
+    lines.push(`  ${pad(row.metric, 9)}${pad(value(row.baseline), 11)}${pad(value(row.current), 10)}${pad(row.change ?? "", 20)}${styleText(VERDICT_STYLE[row.verdict], verdict)}`);
+  }
+  for (const e of view.newErrors) lines.push(`  ${styleText("red", "+ new error")}  ${e.id}: ${e.message}`);
+  for (const e of view.fixedErrors) lines.push(`  ${styleText("green", "− fixed")}      ${e.id}: ${e.message}`);
+  return lines;
+}
+
+export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, throttling, runs, baseline, title = `WebPerf Snippets — ${url}` }) {
   const lines = [];
-  lines.push(styleText(["bold"], `WebPerf Snippets — ${url}`));
+  lines.push(styleText(["bold"], title));
   lines.push(styleText("dim", `Navigated in ${navMs}ms`));
   if (throttling) lines.push(styleText("dim", `Throttling: ${describeThrottling(throttling)}`));
+  if (runs) lines.push(...renderRuns(runs));
   lines.push("");
   for (const r of results) lines.push(renderResult(r, verbose));
   if (crux) {
@@ -219,5 +252,59 @@ 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 (baseline) lines.push(...renderBaseline(baseline));
+  return lines.join("\n");
+}
+
+// One row per combination with the rated median of each metric, and below it the errors that decide
+// the exit code. With verbose, the report of the median run of each combination follows.
+export function reportMatrixHuman(report) {
+  const { file, summary, hasVariants, metrics, rows, errors, comparison } = matrixView(report);
+  const columns = [["name", "Page"], ["device", "Device"], ...(hasVariants ? [["variant", "Variant"]] : [])];
+  const widths = columns.map(([key, label]) => Math.max(...report.combinations.map((c) => c[key].length), label.length) + 3);
+  const identity = (values) => values.map((value, i) => pad(value, widths[i])).join("");
+
+  const lines = [];
+  lines.push(styleText(["bold"], `WebPerf Snippets — ${file} (${summary})`));
+  lines.push("");
+  // With --baseline, a change column follows each metric
+  const headings = metrics.map((m) => pad(m, 14) + (comparison ? pad("Δ", 12) : "")).join("");
+  lines.push(styleText("dim", `  ${identity(columns.map(([, label]) => label))}${headings.trimEnd()}`));
+  for (const { combination: c, cells, changes } of rows) {
+    const row = `  ${identity(columns.map(([key]) => c[key]))}`;
+    if (!cells) {
+      lines.push(row + styleText("red", "✗ every run failed"));
+      continue;
+    }
+    const drawn = cells.map((cell, i) => {
+      const value = cell ? pad(paint(cell.rating, `${RATING_ICON[cell.rating] ?? "·"} ${formatValue(cell.median, cell.unit)}`), 14) : pad("·", 14);
+      return value + (changes ? pad(styleText(VERDICT_STYLE[changes[i].verdict], changes[i].text), 12) : "");
+    });
+    lines.push(row + drawn.join("").trimEnd());
+  }
+
+  if (errors.length) {
+    lines.push("");
+    lines.push(styleText("red", "Errors:"));
+    for (const e of errors) lines.push(`  ${styleText("red", "✗")} ${e}`);
+  }
+
+  if (comparison) {
+    lines.push("", styleText("bold", `Compared with ${comparison.file}`));
+    for (const warning of comparison.warnings) lines.push(`  ${styleText("yellow", `Warning: ${warning}`)}`);
+    for (const e of comparison.newErrors) lines.push(`  ${styleText("red", "+ new error")}  ${e}`);
+    for (const e of comparison.fixedErrors) lines.push(`  ${styleText("green", "− fixed")}      ${e}`);
+    if (comparison.added.length) lines.push(`  Added: ${comparison.added.join(", ")}`);
+    if (comparison.missing.length) lines.push(`  Missing: ${comparison.missing.join(", ")}`);
+    if (!comparison.warnings.length && !comparison.newErrors.length && !comparison.fixedErrors.length && !comparison.added.length && !comparison.missing.length) {
+      lines.push(styleText("dim", "  The same combinations, no new or fixed errors, and no warnings"));
+    }
+  }
+
+  if (report.verbose) {
+    for (const c of report.combinations.filter((c) => !c.error)) {
+      lines.push("", reportHuman({ ...c, verbose: true, title: `${c.id} — ${c.url}` }));
+    }
+  }
   return lines.join("\n");
 }

package/src/reporters/markdown.js

@@ -1,5 +1,8 @@
 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";
 
 const RATING_ICON = {
   good: "✅",
@@ -72,12 +75,43 @@ function renderFieldData(crux, results) {
   ];
 }
 
-export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttling }) {
+// The median, min and max of each metric across the runs
+function renderRuns(runs) {
+  const lines = ["| Metric | Median | Min | Max |", "|--------|--------|-----|-----|"];
+  for (const [metric, { median, min, max, unit }] of Object.entries(runs.summary)) {
+    lines.push(`| ${metric} | ${formatValue(median, unit)} | ${formatValue(min, unit)} | ${formatValue(max, unit)} |`);
+  }
+  return lines;
+}
+
+const VERDICT_ICON = { regressed: "❌", improved: "✅", unchanged: "➖", "not measured": "·" };
+
+// The comparison with --baseline. The warnings go in the comment itself: whoever reads the pull
+// request does not see the stderr of the CI.
+function renderBaseline(comparison) {
+  const view = baselineView(comparison);
+  const lines = ["", `### Compared with \`${view.file}\``, `> ${view.summary}`];
+  for (const warning of view.warnings) lines.push(">", `> ⚠️ ${warning}`);
+  lines.push("", "| Metric | Baseline | Now | Change | Verdict |", "|--------|----------|-----|--------|---------|");
+  for (const row of view.rows) {
+    const value = (v) => (v == null ? "·" : formatValue(v, row.unit));
+    const verdict = `${VERDICT_ICON[row.verdict]} ${row.verdict}${row.note ? ` (${row.note})` : ""}`;
+    lines.push(`| ${row.metric} | ${value(row.baseline)} | ${value(row.current)} | ${row.change ?? "·"} | ${verdict} |`);
+  }
+  if (view.newErrors.length) lines.push("", "#### New errors", ...view.newErrors.map((e) => `- \`${e.id}\`: ${e.message}`));
+  if (view.fixedErrors.length) lines.push("", "#### Fixed errors", ...view.fixedErrors.map((e) => `- \`${e.id}\`: ${e.message}`));
+  return lines;
+}
+
+// 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}` }) {
   const lines = [];
-  lines.push(`## WebPerf Results — ${url}`);
+  if (title) lines.push(`## ${title}`);
   lines.push(`> Navigated in ${navMs}ms`);
   if (throttling) lines.push(">", `> Throttling: ${describeThrottling(throttling)}`);
+  if (runs) lines.push(">", `> ${describeRuns(runs)}`);
   lines.push("");
+  if (runs) lines.push(...renderRuns(runs), "");
 
   const initial = results.filter((r) => !r.reason);
   if (initial.length > 0) {
@@ -106,5 +140,53 @@ export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttli
     for (const err of pageErrors) lines.push(`- ${err}`);
   }
 
+  if (baseline) lines.push(...renderBaseline(baseline));
+
+  return lines.join("\n");
+}
+
+// A table with the rated median of each combination, the errors that decide the exit code, and the
+// report of the median run of each combination folded into a details block, to keep a pull request
+// comment readable.
+export function reportMatrixMarkdown(report) {
+  const { file, summary, hasVariants, metrics, rows, errors, comparison } = matrixView(report);
+  // With --baseline, a change column follows each metric
+  const metricHeadings = metrics.flatMap((m) => (comparison ? [m, "Δ"] : [m]));
+  const headings = ["Page", "Device", ...(hasVariants ? ["Variant"] : []), ...metricHeadings];
+  const row = (parts) => `|${parts.map((part) => (part ? ` ${part} ` : " ")).join("|")}|`;
+
+  const lines = [`## WebPerf Results — ${file}`, `> ${summary}`, ""];
+  lines.push(row(headings));
+  lines.push(`|${headings.map((h) => "-".repeat(h.length + 2)).join("|")}|`);
+  for (const { combination: c, cells, changes } of rows) {
+    const drawn = cells
+      ? cells.flatMap((cell, i) => {
+          const value = cell ? `${RATING_ICON[cell.rating] ?? "·"} ${formatValue(cell.median, cell.unit)}` : "·";
+          return changes ? [value, changes[i].text] : [value];
+        })
+      : ["❌ every run failed", ...metricHeadings.slice(1).map(() => "")];
+    lines.push(row([c.name, c.device, ...(hasVariants ? [c.variant] : []), ...drawn]));
+  }
+
+  if (errors.length) {
+    lines.push("", "### Errors", ...errors.map((e) => `- ${e}`));
+  }
+
+  if (comparison) {
+    lines.push("", `### Compared with \`${comparison.file}\``);
+    if (comparison.warnings.length) lines.push(...comparison.warnings.flatMap((w, i) => [...(i ? [">"] : []), `> ⚠️ ${w}`]), "");
+    const ids = (list) => list.map((id) => `\`${id}\``).join(", ");
+    const items = [
+      ...comparison.newErrors.map((e) => `- New error: ${e}`),
+      ...comparison.fixedErrors.map((e) => `- Fixed: ${e}`),
+      ...(comparison.added.length ? [`- Added: ${ids(comparison.added)}`] : []),
+      ...(comparison.missing.length ? [`- Missing: ${ids(comparison.missing)}`] : []),
+    ];
+    lines.push(...(items.length ? items : ["The same combinations, no new or fixed errors."]));
+  }
+
+  for (const c of report.combinations.filter((c) => !c.error)) {
+    lines.push("", `<details><summary>${c.id}</summary>`, "", reportMarkdown({ ...c, title: null }), "", "</details>");
+  }
   return lines.join("\n");
 }

package/src/reporters/matrix-view.js

@@ -0,0 +1,42 @@
+import { basename } from "node:path";
+import { rate } from "../ratings.js";
+import { blockingErrors } from "../blocking.js";
+import { changeCell, matrixComparisonView } from "./baseline-view.js";
+
+// The order of the metric columns of the matrix table
+const METRICS = ["LCP", "FCP", "TTFB", "CLS", "INP"];
+
+// What the human and markdown reports of a matrix show, so they only differ in how they draw it:
+// the title, the metric columns, one row per combination with the rated median of each metric, and
+// the errors that decide the exit code. With --baseline, each row also has the change of each metric
+// ("new" for a combination the baseline did not have), and the comparison goes below the table.
+export function matrixView({ matrix, runs, combinations, baseline }) {
+  const measured = combinations.filter((c) => !c.error);
+  const medianBys = [...new Set(measured.map((c) => c.runs.medianBy))];
+  const metrics = METRICS.filter((metric) => measured.some((c) => c.runs.summary[metric]));
+  const median = medianBys.length ? `, median by ${medianBys.join(", ")}` : "";
+
+  return {
+    file: basename(matrix),
+    // A matrix without variants has no Variant column
+    hasVariants: combinations.some((c) => c.variant),
+    summary: `${combinations.length} combinations, ${runs} run${runs === 1 ? "" : "s"} each${median}`,
+    metrics,
+    rows: combinations.map((c) => ({
+      combination: c,
+      ...(baseline
+        ? { changes: metrics.map((metric) => (!c.baseline ? { text: "new", verdict: "new" } : c.baseline.metrics[metric] ? changeCell(metric, c.baseline.metrics[metric]) : { text: "·", verdict: "not measured" })) }
+        : {}),
+      cells: c.error
+        ? null
+        : metrics.map((metric) => {
+            const value = c.runs.summary[metric];
+            return value ? { median: value.median, unit: value.unit, rating: rate(metric, value.median) } : null;
+          }),
+    })),
+    ...(baseline ? { comparison: matrixComparisonView(baseline, combinations) } : {}),
+    errors: combinations.flatMap((c) =>
+      c.error ? [`${c.id}: ${c.error}`] : blockingErrors(c.results).map((e) => `${c.id}: ${e.id}: ${e.message}`)
+    ),
+  };
+}

package/src/runs.js

@@ -0,0 +1,65 @@
+// Several runs of the same measurement, reduced to one: the median run, as WebPageTest reports it.
+// Every result of the report comes from that run, so they agree with each other (the sub-parts of
+// the LCP add up to its LCP), and a summary gives the median, min and max of each metric.
+
+// The metrics the snippets report, and navMs, which every run has
+export const MEDIAN_METRICS = ["LCP", "FCP", "TTFB", "CLS", "INP", "navMs"];
+
+// Without --median-by, the median follows the first of these that the runs measured
+const DEFAULT_ORDER = ["LCP", "FCP", "TTFB", "navMs"];
+
+const SUMMARY_METRICS = MEDIAN_METRICS.filter((metric) => metric !== "navMs");
+
+// The value of a metric in a run: its first result with that metric, as LCP comes before its
+// follow-up LCP-Subparts, which reports the same metric
+function valueOf(run, metric) {
+  if (metric === "navMs") return run.navMs;
+  const result = run.results.find((r) => r.metric === metric && r.status === "ok" && typeof r.value === "number");
+  return result?.value;
+}
+
+const measures = (runs, metric) => runs.some((run) => typeof valueOf(run, metric) === "number");
+
+// The middle element of numbers sorted from low to high. With an even count it takes the lower of
+// the two middle ones, so the median is always a run that happened, never an average of two.
+const middle = (sorted) => sorted[Math.floor((sorted.length - 1) / 2)];
+
+// "3 runs, median by LCP: run 2 (1 failed)", for the header of the reports
+export function describeRuns({ count, failed, medianRun, medianBy, medianByRequested }) {
+  const by = medianByRequested ? `${medianBy} (no run measured ${medianByRequested})` : medianBy;
+  return `${count} run${count === 1 ? "" : "s"}, median by ${by}: run ${medianRun}${failed ? ` (${failed} failed)` : ""}`;
+}
+
+// The runs as the CLI made them, in order, a run that failed being { error }. Returns the payload of
+// the median run and the `runs` field of the report, or nulls and the errors when every run failed.
+export function summarizeRuns(runs, { medianBy: requested } = {}) {
+  const completed = runs.filter((run) => !run.error);
+  if (completed.length === 0) return { payload: null, runs: null, errors: runs.map((run) => run.error) };
+
+  const medianBy = requested && measures(completed, requested) ? requested : DEFAULT_ORDER.find((metric) => measures(completed, metric));
+  const ranked = completed
+    .filter((run) => typeof valueOf(run, medianBy) === "number")
+    .sort((a, b) => valueOf(a, medianBy) - valueOf(b, medianBy));
+  const payload = middle(ranked);
+
+  const summary = {};
+  for (const metric of SUMMARY_METRICS) {
+    if (!measures(completed, metric)) continue;
+    const values = runs.map((run) => (run.error ? null : (valueOf(run, metric) ?? null)));
+    const sorted = values.filter((value) => value !== null).sort((a, b) => a - b);
+    const unit = completed.flatMap((run) => run.results).find((r) => r.metric === metric && r.unit)?.unit;
+    summary[metric] = { median: middle(sorted), min: sorted[0], max: sorted[sorted.length - 1], values, unit };
+  }
+
+  return {
+    payload,
+    runs: {
+      count: runs.length,
+      failed: runs.length - completed.length,
+      medianRun: runs.indexOf(payload) + 1,
+      medianBy,
+      ...(requested && requested !== medianBy ? { medianByRequested: requested } : {}),
+      summary,
+    },
+  };
+}

package/src/throttling.js

@@ -1,6 +1,9 @@
 // CPU and network throttling through CDP, as the Performance panel of DevTools applies it. The
 // network presets copy the values of DevTools, so a measurement of the CLI compares with one made
 // there. Throughputs are in bytes per second and latencies in milliseconds.
+//
+// A network can also be given by its own values, for the ones DevTools has no preset for, such as
+// 5G or fibre: { downloadKbps, uploadKbps, latencyMs }, in kilobits per second and milliseconds.
 export const NETWORK_PRESETS = {
   "fast-4g": { title: "Fast 4G", download: (9 * 1000 * 1000) / 8 * 0.9, upload: (1.5 * 1000 * 1000) / 8 * 0.9, latency: 60 * 2.75 },
   "slow-4g": { title: "Slow 4G", download: (1.6 * 1000 * 1000) / 8 * 0.9, upload: (750 * 1000) / 8 * 0.9, latency: 150 * 3.75 },
@@ -13,25 +16,59 @@ export function parseCpuFactor(raw) {
   return raw.trim() !== "" && Number.isFinite(factor) && factor >= 1 ? factor : null;
 }
 
+const NETWORK_VALUES = ["downloadKbps", "uploadKbps", "latencyMs"];
+
+// The throughputs and latency of a preset name or of a network given by its values
+export function resolveNetwork(network) {
+  if (typeof network === "string") {
+    const preset = NETWORK_PRESETS[network];
+    if (!preset) throw new Error(`Unknown network preset: "${network}". Choose from: ${Object.keys(NETWORK_PRESETS).join(", ")}`);
+    return preset;
+  }
+  for (const key of NETWORK_VALUES) {
+    const value = network?.[key];
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      throw new Error(`Invalid network: ${key} must be a number of at least 0, such as { "downloadKbps": 50000, "uploadKbps": 10000, "latencyMs": 20 }`);
+    }
+  }
+  return {
+    download: (network.downloadKbps * 1000) / 8,
+    upload: (network.uploadKbps * 1000) / 8,
+    latency: network.latencyMs,
+  };
+}
+
+// 400 kbps, 1.44 Mbps, 50 Mbps
+function formatKbps(kbps) {
+  return kbps < 1000 ? `${kbps} kbps` : `${Number((kbps / 1000).toFixed(2))} Mbps`;
+}
+
+function describeNetwork(network) {
+  if (typeof network === "string") return NETWORK_PRESETS[network]?.title ?? network;
+  return `${formatKbps(network.downloadKbps)}, ${network.latencyMs} ms`;
+}
+
 // The conditions of a run, as the payload reports them, or undefined without throttling
 export function throttlingOf({ cpu, network }) {
   if (cpu == null && network == null) return undefined;
   return { ...(cpu != null ? { cpu } : {}), ...(network != null ? { network } : {}) };
 }
 
-// "CPU 4x, Slow 4G", for the header of the reports
+// "CPU 4x, Slow 4G" or "CPU 1x, 50 Mbps, 20 ms", for the header of the reports
 export function describeThrottling({ cpu, network }) {
-  return [cpu != null ? `CPU ${cpu}x` : null, network != null ? (NETWORK_PRESETS[network]?.title ?? network) : null]
+  return [cpu != null ? `CPU ${cpu}x` : null, network != null ? describeNetwork(network) : null]
     .filter(Boolean)
     .join(", ");
 }
 
 export async function applyThrottling(context, page, { cpu, network }) {
   if (cpu == null && network == null) return;
+  // An invalid network fails before anything is applied to the page
+  const conditions = network != null ? resolveNetwork(network) : null;
   const cdp = await context.newCDPSession(page);
   if (cpu != null) await cdp.send("Emulation.setCPUThrottlingRate", { rate: cpu });
-  if (network != null) {
-    const { download, upload, latency } = NETWORK_PRESETS[network];
+  if (conditions) {
+    const { download, upload, latency } = conditions;
     await cdp.send("Network.enable");
     await cdp.send("Network.emulateNetworkConditions", {
       offline: false,