webperf-snippets 1.0.0 → 1.2.0

package/src/runner.js

@@ -1,8 +1,11 @@
-import { chromium } from "playwright";
+import { launchChromium } from "./browser.js";
 import { loadSnippet } from "./load-snippet.js";
 import { runInteractions, loadInteractionSteps, isInputStep, settle } from "./interactions.js";
 import { isTrackingSnippet } from "./tracking.js";
 import { nextSteps } from "./decision-tree.js";
+import { sendHeadersToOrigin } from "./headers.js";
+import { withOwnDomains } from "./own-domains.js";
+import { applyThrottling, throttlingOf } from "./throttling.js";
 
 export const VIEWPORT_PRESETS = {
   mobile: { width: 375, height: 812 },
@@ -12,6 +15,12 @@ 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.
+const LATE_ENTRIES_MS = 2000;
+const POLL_MS = 100;
+
 // Snippets are IIFEs. Playwright evaluates a string as an expression, so we
 // trim trailing semicolons to keep the IIFE call as a single expression and
 // recover its return value in Node.
@@ -19,7 +28,7 @@ function toExpression(source) {
   return source.trim().replace(/;\s*$/, "");
 }
 
-async function evaluateItems(page, items) {
+export async function evaluateItems(page, items) {
   const results = [];
   for (const item of items) {
     try {
@@ -56,17 +65,24 @@ async function evaluateAroundInteractions(page, items, interactions) {
     page,
     items.filter((item) => !tracking.includes(item))
   );
+  const hasInput = loadInteractionSteps(interactions).some(isInputStep);
   const collected = [];
-  for (const result of installed) collected.push(await collectTrackingData(page, result));
+  for (const result of installed) collected.push(await collectTrackingData(page, result, hasInput));
 
   const byId = new Map([...collected, ...others].map((r) => [r.id, r]));
   return items.map((item) => byId.get(item.id));
 }
 
-async function collectTrackingData(page, result) {
+export async function collectTrackingData(page, result, hasInput) {
   if (result.status !== "tracking" || !result.getDataFn) return result;
   try {
-    const data = await page.evaluate(`(async () => await ${result.getDataFn}())()`);
+    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) {
+      await page.waitForTimeout(POLL_MS);
+      data = await read();
+    }
     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) {
@@ -84,19 +100,31 @@ export async function runSnippets({
   interactScript,
   interactions = interactScript,
   storageState,
+  headers,
+  cpu,
+  network,
+  ownDomains,
+  // Called at each of the three stages of a run, for callers that report progress (the MCP server)
+  onProgress = () => {},
 }) {
-  const browser = await chromium.launch({ headless });
+  await onProgress(1, "Opening Chromium");
+  const browser = await launchChromium({ headless });
   try {
     const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
+    await sendHeadersToOrigin(context, page, url, headers);
+    await applyThrottling(context, page, { cpu, network });
     const pageErrors = [];
     page.on("pageerror", (err) => pageErrors.push(err.message));
     const navStart = Date.now();
     await page.goto(url, { waitUntil: "load", timeout: navTimeout });
     if (waitMs > 0) await page.waitForTimeout(waitMs);
     const navMs = Date.now() - navStart;
-    const results = await evaluateAroundInteractions(page, items, interactions);
-    return { url, navMs, results, pageErrors };
+    await onProgress(2, "Page loaded, running the snippets");
+    const prepared = items.map((item) => ({ ...item, source: withOwnDomains(item.source, ownDomains) }));
+    const results = await evaluateAroundInteractions(page, prepared, interactions);
+    await onProgress(3, "Snippets evaluated");
+    return { url, navMs, results, pageErrors, throttling: throttlingOf({ cpu, network }) };
   } finally {
     await browser.close();
   }
@@ -113,11 +141,19 @@ export async function runMeasurement({
   interactScript,
   interactions = interactScript,
   storageState,
+  headers,
+  cpu,
+  network,
+  ownDomains,
+  onProgress = () => {},
 }) {
-  const browser = await chromium.launch({ headless });
+  await onProgress(1, "Opening Chromium");
+  const browser = await launchChromium({ headless });
   try {
     const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
+    await sendHeadersToOrigin(context, page, url, headers);
+    await applyThrottling(context, page, { cpu, network });
     const pageErrors = [];
     page.on("pageerror", (err) => pageErrors.push(err.message));
 
@@ -125,6 +161,7 @@ export async function runMeasurement({
     await page.goto(url, { waitUntil: "load", timeout: navTimeout });
     if (waitMs > 0) await page.waitForTimeout(waitMs);
     const navMs = Date.now() - navStart;
+    await onProgress(2, "Page loaded, running the workflow");
 
     // 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.
@@ -137,7 +174,7 @@ export async function runMeasurement({
       .map((step) => ({
         id: step.id,
         path: step.path,
-        source: loadSnippet(step.path),
+        source: withOwnDomains(loadSnippet(step.path), ownDomains),
       }));
     const measured = await evaluateAroundInteractions(page, items, steps);
     const initialResults = workflow.steps.map(
@@ -160,7 +197,7 @@ export async function runMeasurement({
       const followItems = followUps.map((f) => ({
         id: f.id,
         path: f.path,
-        source: loadSnippet(f.path),
+        source: withOwnDomains(loadSnippet(f.path), ownDomains),
       }));
       const raw = await evaluateItems(page, followItems);
       // A tracking snippet answers through its data function, which is read right away here
@@ -172,7 +209,8 @@ export async function runMeasurement({
       });
     }
 
-    return { url, navMs, results: [...initialResults, ...followUpResults], pageErrors };
+    await onProgress(3, "Workflow and follow-ups evaluated");
+    return { url, navMs, results: [...initialResults, ...followUpResults], pageErrors, throttling: throttlingOf({ cpu, network }) };
   } finally {
     await browser.close();
   }

package/src/snippet-names.js

@@ -3,7 +3,7 @@ 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"];
+export 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 = {
@@ -42,6 +42,15 @@ const SNIPPET_ALIASES = {
 };
 let cache = null;
 
+// The short names of a snippet, such as "render-blocking" for Loading/Find-render-blocking-resources.
+// Its own name always works too, so it is not listed.
+export function aliasesOf(path) {
+  const own = path.split("/")[1];
+  return Object.entries(SNIPPET_ALIASES)
+    .filter(([alias, target]) => target === path && alias !== own)
+    .map(([alias]) => alias);
+}
+
 // Every runnable snippet as "Category/Name", read from the bundled copy or the workspace.
 export function listSnippets() {
   if (cache) return cache;

package/src/throttling.js

@@ -0,0 +1,43 @@
+// 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.
+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 },
+  "3g": { title: "3G", download: (500 * 1000) / 8 * 0.8, upload: (500 * 1000) / 8 * 0.8, latency: 400 * 5 },
+};
+
+// The factor given to --cpu, or null when it is not a number of at least 1
+export function parseCpuFactor(raw) {
+  const factor = Number(raw);
+  return raw.trim() !== "" && Number.isFinite(factor) && factor >= 1 ? factor : null;
+}
+
+// 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
+export function describeThrottling({ cpu, network }) {
+  return [cpu != null ? `CPU ${cpu}x` : null, network != null ? (NETWORK_PRESETS[network]?.title ?? network) : null]
+    .filter(Boolean)
+    .join(", ");
+}
+
+export async function applyThrottling(context, page, { cpu, network }) {
+  if (cpu == null && network == null) return;
+  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];
+    await cdp.send("Network.enable");
+    await cdp.send("Network.emulateNetworkConditions", {
+      offline: false,
+      latency,
+      downloadThroughput: download,
+      uploadThroughput: upload,
+    });
+  }
+}

package/src/workflows/index.js

@@ -0,0 +1,12 @@
+import { cwvWorkflow } from "./cwv.js";
+import { auditWorkflow } from "./audit.js";
+import { loadingWorkflow } from "./loading.js";
+import { interactionWorkflow } from "./interaction.js";
+
+// The workflows by the name --workflow and the run_workflow tool of the MCP server take
+export const WORKFLOWS = {
+  "core-web-vitals": cwvWorkflow,
+  audit: auditWorkflow,
+  loading: loadingWorkflow,
+  interaction: interactionWorkflow,
+};