webperf-snippets 0.2.0 → 0.3.0

package/snippets/_shared/helpers.js

@@ -0,0 +1,44 @@
+/* eslint-disable no-unused-vars */
+// Canonical source of the helpers that several snippets copy.
+//
+// Snippets run pasted into the DevTools console, so they cannot import anything. Each snippet
+// that needs a helper carries a copy of it between the same two markers:
+//
+//   // @shared <name>
+//   ...
+//   // @end-shared <name>
+//
+// `npm run check:consistency` fails when a copy differs from the block below (indentation is
+// ignored). Edit the block here first, then paste it into every snippet that carries the marker.
+
+// @shared getRootDomain
+function getRootDomain(hostname) {
+  const host = hostname.replace(/\.$/, "");
+  // An IP address has no registrable domain, so each address is its own root
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":")) return host;
+  const parts = host.split(".");
+  if (parts.length <= 2) return host;
+  // Country-code domains with a second-level suffix: example.co.uk, example.com.au, example.ac.jp
+  const secondLevelSuffixes = ["ac", "co", "com", "edu", "go", "gob", "gouv", "gov", "govt", "mil", "ne", "net", "nom", "or", "org", "sch"];
+  const tld = parts[parts.length - 1];
+  const sld = parts[parts.length - 2];
+  if (tld.length === 2 && secondLevelSuffixes.includes(sld)) return parts.slice(-3).join(".");
+  return parts.slice(-2).join(".");
+}
+// @end-shared getRootDomain
+
+// @shared isFirstParty
+function isFirstParty(hostname) {
+  return getRootDomain(hostname) === getRootDomain(location.hostname);
+}
+// @end-shared isFirstParty
+
+// @shared formatBytes
+function formatBytes(bytes) {
+  if (bytes === null || bytes === undefined || Number.isNaN(bytes)) return "-";
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.max(0, Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1));
+  return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
+}
+// @end-shared formatBytes

package/src/bin.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { existsSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { loadSnippet } from "./load-snippet.js";
 import { runSnippets, runMeasurement, VIEWPORT_PRESETS } from "./runner.js";
@@ -9,6 +10,8 @@ import { RULES } from "./decision-tree.js";
 import { reportHuman } from "./reporters/human.js";
 import { reportJson } from "./reporters/json.js";
 import { reportMarkdown } from "./reporters/markdown.js";
+import { cliVersion, reportTo, validateReportUrl } from "./report-to.js";
+import { fetchCrux, formFactorFor } from "./crux.js";
 
 const WORKFLOWS = {
   "core-web-vitals": cwvWorkflow,
@@ -19,6 +22,7 @@ const WORKFLOWS = {
 const SNIPPET_ALIASES = {
   LCP: "CoreWebVitals/LCP",
   CLS: "CoreWebVitals/CLS",
+  INP: "CoreWebVitals/INP",
   "LCP-Subparts": "CoreWebVitals/LCP-Subparts",
   fonts: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold",
   "Fonts-Preloaded-Loaded-and-used-above-the-fold":
@@ -58,7 +62,7 @@ Options:
   --workflow <name>     Workflow to run (default: core-web-vitals)
                         Workflows: core-web-vitals, audit, loading
   --snippet <name>      Run a single snippet by alias or Category/Name path
-                        Aliases: LCP, CLS, LCP-Subparts, fonts,
+                        Aliases: LCP, CLS, INP, LCP-Subparts, fonts,
                                  render-blocking, resource-hints, preload-scripts,
                                  priority-hints, critical-css, ttfb,
                                  script-parties, script-loading,
@@ -71,6 +75,14 @@ Options:
   --budget-cls <score>  Exit 1 if CLS exceeds this value
   --interact-script <path>  JSON file with interactions to run before evaluation
                             Actions: scroll, click, hover, type, wait
+  --storage-state <path>    Playwright storage state (cookies + localStorage) to
+                            measure pages that require authentication
+  --crux-key <key>          Add CrUX field data (p75) next to the measured values.
+                            Also read from the CRUX_API_KEY environment variable
+  --report-to <url>         POST the results to this https URL after the run
+                            (without it the CLI makes no external calls)
+  --api-key <key>           Sent as "Authorization: Bearer <key>" with --report-to.
+                            Prefer the PERF_REVIEWS_API_KEY environment variable
   --verbose             Show all items, even for passing checks
   --headed              Show the browser window (debug)
   -h, --help            Show this help
@@ -84,6 +96,7 @@ Examples:
   npx webperf-snippets https://web.dev --snippet fonts
   npx webperf-snippets https://web.dev --budget-lcp 2500
   npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
+  npx webperf-snippets https://example.com/dashboard --storage-state auth.json
 `;
 
 function fail(message, code = 2) {
@@ -131,6 +144,10 @@ async function main() {
         "budget-cls": { type: "string" },
         viewport: { type: "string" },
         "interact-script": { type: "string" },
+        "storage-state": { type: "string" },
+        "crux-key": { type: "string" },
+        "report-to": { type: "string" },
+        "api-key": { type: "string" },
         verbose: { type: "boolean" },
         headed: { type: "boolean" },
         help: { type: "boolean", short: "h" },
@@ -161,19 +178,33 @@ async function main() {
     fail(`Unknown viewport preset: "${viewportName}". Choose from: ${Object.keys(VIEWPORT_PRESETS).join(", ")}`);
   }
 
+  const reportUrl = values["report-to"];
+  if (reportUrl) {
+    const problem = validateReportUrl(reportUrl);
+    if (problem) fail(problem);
+  }
+
   const interactScript = values["interact-script"];
+  const storageState = values["storage-state"];
+  if (storageState && !existsSync(storageState)) {
+    fail(`Storage state file not found: ${storageState}`);
+  }
 
   let payload;
   if (values.snippet) {
     const items = buildSnippetItem(values);
-    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript });
+    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript, storageState });
   } else {
     const workflowName = values.workflow ?? "core-web-vitals";
     const workflow = WORKFLOWS[workflowName];
     if (!workflow) fail(`Unknown workflow: ${workflowName}`);
-    payload = await runMeasurement({ url, workflow, rules: RULES, waitMs, headless: !values.headed, viewport, interactScript });
+    payload = await runMeasurement({ url, workflow, rules: RULES, waitMs, headless: !values.headed, viewport, interactScript, storageState });
   }
 
+  const cruxKey = values["crux-key"] || process.env.CRUX_API_KEY;
+  const crux = cruxKey ? await fetchCrux({ url, apiKey: cruxKey, formFactor: formFactorFor(viewportName) }) : undefined;
+  if (crux) payload.crux = crux;
+
   let output;
   if (values.markdown) {
     output = reportMarkdown(payload);
@@ -184,6 +215,27 @@ async function main() {
   }
   process.stdout.write(output + "\n");
 
+  if (reportUrl) {
+    const outcome = await reportTo({
+      url: reportUrl,
+      apiKey: values["api-key"] || process.env.PERF_REVIEWS_API_KEY,
+      body: {
+        url,
+        workflow: values.snippet ? null : (values.workflow ?? "core-web-vitals"),
+        ...(values.snippet ? { snippet: values.snippet } : {}),
+        timestamp: new Date().toISOString(),
+        navMs: payload.navMs,
+        results: payload.results,
+        meta: { viewport: viewportName, waitMs, cli_version: cliVersion },
+      },
+    });
+    if (!outcome.ok) {
+      process.stderr.write(`Warning: could not report results to ${new URL(reportUrl).origin} (${outcome.warning})\n`);
+    } else if (outcome.regressions.length > 0) {
+      process.stderr.write(`Regressions detected:\n${outcome.regressions.map((r) => `  - ${typeof r === "string" ? r : JSON.stringify(r)}`).join("\n")}\n`);
+    }
+  }
+
   // Exit codes.
   const violations = checkBudgets(payload.results, values);
   if (violations.length > 0) {

package/src/crux.js

@@ -0,0 +1,84 @@
+const DEFAULT_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord";
+const CRUX_TIMEOUT_MS = 10000;
+
+// Good / needs-improvement upper bounds from web.dev/articles/vitals.
+const METRICS = [
+  { name: "LCP", key: "largest_contentful_paint", unit: "ms", good: 2500, poor: 4000 },
+  { name: "CLS", key: "cumulative_layout_shift", unit: "score", good: 0.1, poor: 0.25 },
+  { name: "INP", key: "interaction_to_next_paint", unit: "ms", good: 200, poor: 500 },
+];
+
+const FORM_FACTOR_LABEL = { PHONE: "mobile", DESKTOP: "desktop", TABLET: "tablet" };
+
+const rate = (value, { good, poor }) => (value <= good ? "good" : value <= poor ? "needs-improvement" : "poor");
+
+// The viewport preset decides which population the field data describes.
+export function formFactorFor(viewportName) {
+  return viewportName === "desktop" ? "DESKTOP" : "PHONE";
+}
+
+function parseMetrics(record) {
+  const metrics = {};
+  for (const m of METRICS) {
+    // CLS p75 comes as a string ("0.08"); LCP and INP as numbers.
+    const p75 = Number(record?.metrics?.[m.key]?.percentiles?.p75);
+    if (Number.isFinite(p75)) metrics[m.name] = { p75, rating: rate(p75, m), unit: m.unit };
+  }
+  return metrics;
+}
+
+async function query({ endpoint, apiKey, body, timeoutMs }) {
+  const res = await fetch(`${endpoint}?key=${encodeURIComponent(apiKey)}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (res.status === 404) return { notFound: true };
+  if (!res.ok) return { status: res.status };
+  return { record: (await res.json()).record };
+}
+
+// Never throws, and no message it returns contains the key (it travels in the
+// query string, so the request URL is never logged or put in an error).
+export async function fetchCrux({
+  url,
+  apiKey,
+  formFactor = "PHONE",
+  endpoint = process.env.WEBPERF_CRUX_ENDPOINT ?? DEFAULT_ENDPOINT,
+  timeoutMs = CRUX_TIMEOUT_MS,
+}) {
+  try {
+    let scope = "url";
+    let answer = await query({ endpoint, apiKey, body: { url, formFactor }, timeoutMs });
+    if (answer.notFound) {
+      scope = "origin";
+      answer = await query({ endpoint, apiKey, body: { origin: new URL(url).origin, formFactor }, timeoutMs });
+    }
+    if (answer.notFound) return { unavailable: "not in the CrUX dataset" };
+    if (answer.status) return { unavailable: `the CrUX API answered ${answer.status}` };
+    const metrics = parseMetrics(answer.record);
+    if (Object.keys(metrics).length === 0) return { unavailable: "no Core Web Vitals in the CrUX record" };
+    return { scope, formFactor, metrics };
+  } catch (err) {
+    const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? "request failed");
+    return { unavailable: reason };
+  }
+}
+
+// Shared by both reporters: what to show and next to which synthetic value.
+export function fieldDataView(crux, results) {
+  const label = FORM_FACTOR_LABEL[crux.formFactor] ?? crux.formFactor.toLowerCase();
+  const title = `Field data (CrUX p75, ${label}${crux.scope === "origin" ? ", origin-level" : ""})`;
+  const rows = METRICS.filter((m) => crux.metrics[m.name]).map((m) => {
+    const synthetic = results.find((r) => r.status === "ok" && r.metric === m.name);
+    return {
+      metric: m.name,
+      unit: m.unit,
+      p75: crux.metrics[m.name].p75,
+      rating: crux.metrics[m.name].rating,
+      synthetic: synthetic ? synthetic.value : null,
+    };
+  });
+  return { title, rows };
+}

package/src/report-to.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPORT_TIMEOUT_MS = 5000;
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+export const cliVersion = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version;
+
+// Returns an error message when the URL cannot receive a report, or null.
+// https is required so the API key is never sent in clear text; local hosts
+// are allowed over http for development and tests.
+export function validateReportUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return `--report-to must be an https URL, got "${value}"`;
+  }
+  if (parsed.protocol === "https:") return null;
+  if (parsed.protocol === "http:" && LOCAL_HOSTS.has(parsed.hostname)) return null;
+  return `--report-to must be an https URL (http is allowed only for localhost), got "${value}"`;
+}
+
+// POSTs the results to `url`. Never throws and never touches the exit code:
+// the caller decides what to do with the outcome. The key is only sent in the
+// Authorization header and never appears in a returned message.
+export async function reportTo({ url, apiKey, body, timeoutMs = REPORT_TIMEOUT_MS }) {
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return { ok: false, warning: `the endpoint answered ${res.status}` };
+    const data = await res.json().catch(() => ({}));
+    return { ok: true, regressions: data.ok === false ? (data.regressions ?? []) : [] };
+  } catch (err) {
+    const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? err.message);
+    return { ok: false, warning: reason };
+  }
+}

package/src/reporters/human.js

@@ -1,4 +1,5 @@
 import { styleText } from "node:util";
+import { fieldDataView } from "../crux.js";
 
 const RATING_ICON = {
   good: "🟢",
@@ -164,12 +165,30 @@ function renderResult(r, verbose) {
   return out;
 }
 
-export function reportHuman({ url, navMs, results, pageErrors, verbose }) {
+function renderFieldData(crux, results) {
+  if (crux.unavailable) return [styleText("dim", `Field data: not available (${crux.unavailable})`)];
+  const { title, rows } = fieldDataView(crux, results);
+  const lines = [styleText("bold", title)];
+  for (const row of rows) {
+    const icon = RATING_ICON[row.rating] ?? "·";
+    const synthetic = row.synthetic == null ? "n/a" : formatValue(row.synthetic, row.unit);
+    lines.push(
+      `  ${icon} ${pad(row.metric, 6)} ${pad(paint(row.rating, formatValue(row.p75, row.unit)), 10)} ${pad(styleText("dim", row.rating), 20)} ${styleText("dim", `(synthetic: ${synthetic})`)}`
+    );
+  }
+  return lines;
+}
+
+export function reportHuman({ url, navMs, results, pageErrors, verbose, crux }) {
   const lines = [];
   lines.push(styleText(["bold"], `WebPerf Snippets — ${url}`));
   lines.push(styleText("dim", `Navigated in ${navMs}ms`));
   lines.push("");
   for (const r of results) lines.push(renderResult(r, verbose));
+  if (crux) {
+    lines.push("");
+    lines.push(...renderFieldData(crux, results));
+  }
   if (pageErrors?.length) {
     lines.push("");
     lines.push(styleText("yellow", "Page errors during run:"));

package/src/reporters/markdown.js

@@ -1,3 +1,5 @@
+import { fieldDataView } from "../crux.js";
+
 const RATING_ICON = {
   good: "✅",
   "needs-improvement": "⚠️",
@@ -50,7 +52,21 @@ function renderSection(title, results) {
   ].join("\n");
 }
 
-export function reportMarkdown({ url, navMs, results, pageErrors }) {
+function renderFieldData(crux, results) {
+  if (crux.unavailable) return [`> Field data: not available (${crux.unavailable})`];
+  const { title, rows } = fieldDataView(crux, results);
+  return [
+    `### ${title}`,
+    "| Metric | Field p75 | Status | Synthetic |",
+    "|--------|-----------|--------|-----------|",
+    ...rows.map((row) => {
+      const synthetic = row.synthetic == null ? "n/a" : formatValue(row.synthetic, row.unit);
+      return `| ${row.metric} | ${formatValue(row.p75, row.unit)} | ${RATING_ICON[row.rating] ?? "·"} ${row.rating} | ${synthetic} |`;
+    }),
+  ];
+}
+
+export function reportMarkdown({ url, navMs, results, pageErrors, crux }) {
   const lines = [];
   lines.push(`## WebPerf Results — ${url}`);
   lines.push(`> Navigated in ${navMs}ms`);
@@ -72,6 +88,11 @@ export function reportMarkdown({ url, navMs, results, pageErrors }) {
     lines.push(renderSection(`Follow-up *(${reason})*`, group));
   }
 
+  if (crux) {
+    lines.push("");
+    lines.push(...renderFieldData(crux, results));
+  }
+
   if (pageErrors?.length) {
     lines.push("");
     lines.push("### ⚠ Page Errors");

package/src/runner.js

@@ -46,10 +46,11 @@ export async function runSnippets({
   viewport = VIEWPORT_PRESETS.mobile,
   navTimeout = DEFAULT_NAV_TIMEOUT,
   interactScript,
+  storageState,
 }) {
   const browser = await chromium.launch({ headless });
   try {
-    const context = await browser.newContext({ viewport });
+    const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
     const pageErrors = [];
     page.on("pageerror", (err) => pageErrors.push(err.message));
@@ -74,10 +75,11 @@ export async function runMeasurement({
   viewport = VIEWPORT_PRESETS.mobile,
   navTimeout = DEFAULT_NAV_TIMEOUT,
   interactScript,
+  storageState,
 }) {
   const browser = await chromium.launch({ headless });
   try {
-    const context = await browser.newContext({ viewport });
+    const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
     const pageErrors = [];
     page.on("pageerror", (err) => pageErrors.push(err.message));