webperf-snippets 0.3.0 → 0.4.1

package/src/reporters/markdown.js

@@ -31,7 +31,12 @@ function renderErrorRow(r) {
   return `| ${r.id} | ❌ error | ${r.error} |`;
 }
 
+function renderSkippedRow(r) {
+  return `| ${r.id} | ⏭ skipped | ${r.reason} |`;
+}
+
 function renderRow(r) {
+  if (r.status === "skipped") return renderSkippedRow(r);
   if (r.status === "error") return renderErrorRow(r);
   if (Array.isArray(r.issues)) return renderAuditRow(r);
   return renderMetricRow(r);

package/src/runner.js

@@ -1,6 +1,8 @@
 import { chromium } from "playwright";
 import { loadSnippet } from "./load-snippet.js";
-import { runInteractions } from "./interactions.js";
+import { runInteractions, loadInteractionSteps, isInputStep, settle } from "./interactions.js";
+import { isTrackingSnippet } from "./tracking.js";
+import { nextSteps } from "./decision-tree.js";
 
 export const VIEWPORT_PRESETS = {
   mobile: { width: 375, height: 812 },
@@ -38,6 +40,40 @@ async function evaluateItems(page, items) {
   return results;
 }
 
+// Runs the items around a set of interactions. A tracking snippet is installed first, so it sees
+// the interactions, and answers through its getDataFn afterwards. The other items run after the
+// interactions, as before. The browser reports the timing of an interaction after the frame that
+// follows it, so the runner lets it settle before it reads anything. Results keep the order of the
+// items. Without interactions every item runs once, as it always did.
+async function evaluateAroundInteractions(page, items, interactions) {
+  if (!interactions) return evaluateItems(page, items);
+
+  const tracking = items.filter((item) => isTrackingSnippet(item.path ?? "", item.source));
+  const installed = await evaluateItems(page, tracking);
+  await runInteractions(page, interactions);
+  await settle(page);
+  const others = await evaluateItems(
+    page,
+    items.filter((item) => !tracking.includes(item))
+  );
+  const collected = [];
+  for (const result of installed) collected.push(await collectTrackingData(page, result));
+
+  const byId = new Map([...collected, ...others].map((r) => [r.id, r]));
+  return items.map((item) => byId.get(item.id));
+}
+
+async function collectTrackingData(page, result) {
+  if (result.status !== "tracking" || !result.getDataFn) return result;
+  try {
+    const data = await page.evaluate(`(async () => await ${result.getDataFn}())()`);
+    if (data && typeof data === "object") return { id: result.id, ...data };
+    return { id: result.id, status: "error", error: `${result.getDataFn}() did not return an object` };
+  } catch (err) {
+    return { id: result.id, status: "error", error: `${result.getDataFn}() failed: ${err.message}` };
+  }
+}
+
 export async function runSnippets({
   url,
   items,
@@ -46,6 +82,7 @@ export async function runSnippets({
   viewport = VIEWPORT_PRESETS.mobile,
   navTimeout = DEFAULT_NAV_TIMEOUT,
   interactScript,
+  interactions = interactScript,
   storageState,
 }) {
   const browser = await chromium.launch({ headless });
@@ -58,8 +95,7 @@ export async function runSnippets({
     await page.goto(url, { waitUntil: "load", timeout: navTimeout });
     if (waitMs > 0) await page.waitForTimeout(waitMs);
     const navMs = Date.now() - navStart;
-    if (interactScript) await runInteractions(page, interactScript);
-    const results = await evaluateItems(page, items);
+    const results = await evaluateAroundInteractions(page, items, interactions);
     return { url, navMs, results, pageErrors };
   } finally {
     await browser.close();
@@ -75,6 +111,7 @@ export async function runMeasurement({
   viewport = VIEWPORT_PRESETS.mobile,
   navTimeout = DEFAULT_NAV_TIMEOUT,
   interactScript,
+  interactions = interactScript,
   storageState,
 }) {
   const browser = await chromium.launch({ headless });
@@ -88,21 +125,35 @@ export async function runMeasurement({
     await page.goto(url, { waitUntil: "load", timeout: navTimeout });
     if (waitMs > 0) await page.waitForTimeout(waitMs);
     const navMs = Date.now() - navStart;
-    if (interactScript) await runInteractions(page, interactScript);
-
-    const items = workflow.steps.map((step) => ({
-      id: step.id,
-      path: step.path,
-      source: loadSnippet(step.path),
-    }));
-    const initialResults = await evaluateItems(page, items);
-
-    const followUps = [];
-    for (const result of initialResults) {
-      for (const rule of rules) {
-        if (rule.when(result)) followUps.push({ ...rule.append, reason: rule.reason });
-      }
-    }
+
+    // The steps of the user's script, or the workflow's own. A step that needs a click or a key press
+    // is skipped when the interactions have none, so it does not fail for lack of data.
+    const steps = interactions ?? workflow.defaultInteractions;
+    const hasInput = steps ? loadInteractionSteps(steps).some(isInputStep) : false;
+    const skip = (step) => step.needsInput && !hasInput;
+
+    const items = workflow.steps
+      .filter((step) => !skip(step))
+      .map((step) => ({
+        id: step.id,
+        path: step.path,
+        source: loadSnippet(step.path),
+      }));
+    const measured = await evaluateAroundInteractions(page, items, steps);
+    const initialResults = workflow.steps.map(
+      (step) =>
+        measured.find((r) => r.id === step.id) ?? {
+          id: step.id,
+          status: "skipped",
+          reason: "The interactions have no click or type step; add one with --interact-script",
+        }
+    );
+
+    const followUps = nextSteps(
+      initialResults,
+      rules,
+      workflow.steps.map((step) => step.path)
+    );
 
     let followUpResults = [];
     if (followUps.length > 0) {
@@ -112,7 +163,10 @@ export async function runMeasurement({
         source: loadSnippet(f.path),
       }));
       const raw = await evaluateItems(page, followItems);
-      followUpResults = raw.map((r) => {
+      // A tracking snippet answers through its data function, which is read right away here
+      const collected = [];
+      for (const r of raw) collected.push(await collectTrackingData(page, r));
+      followUpResults = collected.map((r) => {
         const f = followUps.find((x) => x.id === r.id);
         return f ? { ...r, reason: f.reason } : r;
       });

package/src/snippet-names.js

@@ -0,0 +1,89 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { SNIPPET_DIRS } from "./load-snippet.js";
+
+// The categories whose snippets run headlessly. DevTools-Overrides pairs are pasted by hand.
+const CATEGORIES = ["CoreWebVitals", "Loading", "Interaction", "Media", "Resources"];
+
+// Short names for the snippets people run most. Any snippet also answers to its own name.
+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":
+    "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold",
+  // Tier 1 — Loading
+  "render-blocking": "Loading/Find-render-blocking-resources",
+  "Find-render-blocking-resources": "Loading/Find-render-blocking-resources",
+  "resource-hints": "Loading/Resource-Hints-Validation",
+  "Resource-Hints-Validation": "Loading/Resource-Hints-Validation",
+  "preload-scripts": "Loading/Validate-Preload-Async-Defer-Scripts",
+  "Validate-Preload-Async-Defer-Scripts": "Loading/Validate-Preload-Async-Defer-Scripts",
+  "priority-hints": "Loading/Priority-Hints-Audit",
+  "Priority-Hints-Audit": "Loading/Priority-Hints-Audit",
+  "critical-css": "Loading/Critical-CSS-Detection",
+  "Critical-CSS-Detection": "Loading/Critical-CSS-Detection",
+  ttfb: "Loading/TTFB-Sub-Parts",
+  "TTFB-Sub-Parts": "Loading/TTFB-Sub-Parts",
+  "script-parties": "Loading/First-And-Third-Party-Script-Info",
+  "First-And-Third-Party-Script-Info": "Loading/First-And-Third-Party-Script-Info",
+  "script-loading": "Loading/Script-Loading",
+  "Script-Loading": "Loading/Script-Loading",
+  // Tier 2 — Media
+  "lazy-atf": "Loading/Find-Above-The-Fold-Lazy-Loaded-Images",
+  "Find-Above-The-Fold-Lazy-Loaded-Images": "Loading/Find-Above-The-Fold-Lazy-Loaded-Images",
+  "lazy-conflict": "Loading/Find-Images-With-Lazy-and-Fetchpriority",
+  "Find-Images-With-Lazy-and-Fetchpriority": "Loading/Find-Images-With-Lazy-and-Fetchpriority",
+  "eager-below-fold": "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport",
+  "Find-non-Lazy-Loaded-Images-outside-of-the-viewport":
+    "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport",
+};
+let cache = null;
+
+// Every runnable snippet as "Category/Name", read from the bundled copy or the workspace.
+export function listSnippets() {
+  if (cache) return cache;
+  const dir = SNIPPET_DIRS.find((d) => existsSync(join(d, CATEGORIES[0])));
+  cache = dir
+    ? CATEGORIES.flatMap((category) =>
+        readdirSync(join(dir, category))
+          .filter((file) => file.endsWith(".js"))
+          .map((file) => `${category}/${file.slice(0, -3)}`)
+      ).sort()
+    : [];
+  return cache;
+}
+
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const current = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = current;
+    }
+  }
+  return row[b.length];
+}
+
+// Turns an alias, a bare snippet name or a Category/Name path into a Category/Name path.
+// Only a listed snippet resolves, so a name can never point at a file outside the snippets.
+export function resolveSnippetName(name) {
+  if (Object.hasOwn(SNIPPET_ALIASES, name)) return SNIPPET_ALIASES[name];
+  const all = listSnippets();
+  const wanted = name.toLowerCase();
+  const found = all.find((path) => path.toLowerCase() === wanted || path.split("/")[1].toLowerCase() === wanted);
+  if (found) return found;
+
+  const bare = wanted.split("/").pop();
+  const closest = all
+    .map((path) => ({ path, score: distance(bare, path.split("/")[1].toLowerCase()) }))
+    .sort((a, b) => a.score - b.score)
+    .slice(0, 3)
+    .map((c) => c.path);
+  throw new Error(`Unknown snippet "${name}". Closest: ${closest.join(", ")}. Run with a snippet name such as Compression-Audit, or a Category/Name path.`);
+}

package/src/tracking.js

@@ -0,0 +1,6 @@
+// A tracking snippet installs observers and answers later through a window function named in its
+// result (getDataFn). The Interaction snippets work this way, and so does INP, whose value only
+// comes out of getINP(). CLS also names a getDataFn but answers with its value in one go.
+export function isTrackingSnippet(path, source) {
+  return (path.startsWith("Interaction/") || path === "CoreWebVitals/INP") && source.includes("getDataFn");
+}

package/src/workflows/audit.js

@@ -1,5 +1,9 @@
 // Structural audit workflow — deterministic checks suitable for CI.
 // These snippets return binary pass/fail results with no timing noise.
+//
+// Every step runs on the same page, one after the other. The steps that make requests of their
+// own (an image probe, a fetch to read a Content-Type) go last, because those requests add Resource
+// Timing entries that the steps before them would count.
 export const auditWorkflow = {
   id: "audit",
   title: "Structural Audit",
@@ -13,9 +17,22 @@ export const auditWorkflow = {
     { id: "ttfb", path: "Loading/TTFB-Sub-Parts" },
     { id: "script-parties", path: "Loading/First-And-Third-Party-Script-Info" },
     { id: "script-loading", path: "Loading/Script-Loading" },
+    { id: "compression", path: "Loading/Compression-Audit" },
+    { id: "inline-scripts", path: "Loading/Inline-Script-Info-and-Size" },
+    { id: "inline-css", path: "Loading/Inline-CSS-Info-and-Size" },
+    { id: "webfonts", path: "Loading/Webfont-Usage-Analyzer" },
+    { id: "content-visibility", path: "Loading/Content-Visibility" },
+    { id: "prefetch", path: "Loading/Prefetch-Resource-Validation" },
     // Tier 2 — Media determinista
     { id: "lazy-atf", path: "Loading/Find-Above-The-Fold-Lazy-Loaded-Images" },
     { id: "lazy-conflict", path: "Loading/Find-Images-With-Lazy-and-Fetchpriority" },
     { id: "eager-below-fold", path: "Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport" },
+    { id: "video", path: "Media/Video-Element-Audit" },
+    // Tier 3 — DOM
+    { id: "dom-size", path: "Interaction/DOM-Size-and-Depth" },
+    // Steps that make their own requests, last
+    { id: "oversized-images", path: "Media/Oversized-Images" },
+    { id: "image-audit", path: "Media/Image-Element-Audit" },
+    { id: "svg-bitmaps", path: "Media/SVG-Embedded-Bitmap-Analysis" },
   ],
 };

package/src/workflows/interaction.js

@@ -0,0 +1,30 @@
+// Interaction performance workflow. The Interaction snippets record what happens while the page is
+// used, so this workflow runs a set of interactions (the steps of --interact-script, or a scroll of
+// its own) and reads the snippets afterwards.
+//
+// A step flagged needsInput measures clicks and key presses; when the interactions have neither, the
+// step is skipped with a reason instead of failing for lack of data.
+export const interactionWorkflow = {
+  id: "interaction",
+  title: "Interaction Performance",
+  // Used without --interact-script. Clicks belong to each site, so the default only scrolls.
+  defaultInteractions: [
+    { action: "scroll", y: 600 },
+    { action: "wait", ms: 300 },
+    { action: "scroll", y: 600 },
+    { action: "wait", ms: 300 },
+    { action: "scroll", y: 600 },
+    { action: "wait", ms: 300 },
+    { action: "scroll", y: -1800 },
+    { action: "wait", ms: 500 },
+  ],
+  steps: [
+    { id: "long-tasks", path: "Interaction/LongTask" },
+    { id: "long-frames", path: "Interaction/Long-Animation-Frames" },
+    { 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: "interactions", path: "Interaction/Interactions", needsInput: true },
+    { id: "input-latency", path: "Interaction/Input-Latency-Breakdown", needsInput: true },
+  ],
+};

package/src/workflows/loading.js

@@ -1,5 +1,9 @@
 // Loading performance workflow — timing-sensitive measurements requiring a real page load.
 // Complements the audit workflow (deterministic structural checks) with live metrics.
+//
+// Every step runs on the same page, one after the other. The step that makes requests of its own
+// (the HEAD requests that read the cache headers) goes last, because those requests add Resource
+// Timing entries that the steps before it would read.
 export const loadingWorkflow = {
   id: "loading",
   title: "Loading Performance",
@@ -9,6 +13,11 @@ export const loadingWorkflow = {
     { id: "render-blocking", path: "Loading/Find-render-blocking-resources" },
     { id: "resource-hints", path: "Loading/Resource-Hints-Validation" },
     { id: "scripts", path: "Loading/Script-Loading" },
+    { id: "script-timings", path: "Loading/First-And-Third-Party-Script-Timings" },
+    { id: "ttfb-resources", path: "Loading/TTFB-Resources" },
+    { id: "js-execution", path: "Loading/JS-Execution-Time-Breakdown" },
+    { id: "third-party-impact", path: "Loading/Third-Party-Impact-by-Domain" },
     { id: "fonts", path: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold" },
+    { id: "cache-strategy", path: "Loading/Cache-Strategy-Analysis" },
   ],
 };