@specific.dev/spectest 0.57.0 → 0.58.0

package/dist/harness/browser-coverage.js

@@ -0,0 +1,257 @@
+// Browser coverage — the pure part.
+//
+// A frontend runs in the guest Chromium, which is spectest's own process,
+// so the user cannot write a coverage report for it the way a service
+// process can. A service declares `coverage: { browser: true }` and
+// spectest collects it: V8 precise coverage over CDP for every script the
+// browser loads from that service, mapped back to original sources
+// through the served source maps, and written as one lcov report per
+// service into the same `case-coverage` bundle the container path uses.
+//
+// This module has no CDP in it: source-map decoding, V8 range → line
+// counts, host → service attribution, lcov output. The collector that
+// talks to the page is `../browser-coverage.ts`.
+// ── V8 precise coverage → generated line counts ─────────────────────────
+/** Byte offset at which each line starts. */
+export function lineStartsOf(source) {
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source.charCodeAt(i) === 10)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** 1-based line holding `offset`. */
+export function lineOf(starts, offset) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo + 1;
+}
+/**
+ * Fold a script's block ranges onto its lines. Ranges come outer-first
+ * and a narrower range overrides the lines it spans, so a line inside an
+ * unexecuted branch ends at 0 even though its enclosing function ran.
+ * Blank lines are dropped. Approximate — a line holding two blocks gets
+ * the narrower one's count — which is exact at the file level, the only
+ * level anything reads today.
+ */
+export function rangesToLineCounts(source, functions) {
+    const starts = lineStartsOf(source);
+    const counts = new Map();
+    for (const fn of functions) {
+        for (const r of fn.ranges) {
+            const a = lineOf(starts, r.startOffset);
+            const b = lineOf(starts, Math.max(r.startOffset, r.endOffset - 1));
+            for (let l = a; l <= b; l++)
+                counts.set(l, r.count);
+        }
+    }
+    for (const l of [...counts.keys()]) {
+        const text = source.slice(starts[l - 1], starts[l] ?? source.length);
+        if (text.trim().length === 0)
+            counts.delete(l);
+    }
+    return counts;
+}
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const B64_INDEX = new Map([...B64].map((c, i) => [c, i]));
+/** Decode one VLQ-encoded segment into its fields. */
+export function decodeVlq(segment) {
+    const out = [];
+    let value = 0;
+    let shift = 0;
+    for (const ch of segment) {
+        const digit = B64_INDEX.get(ch);
+        if (digit === undefined)
+            throw new Error(`bad VLQ char ${JSON.stringify(ch)}`);
+        value += (digit & 31) << shift;
+        if (digit & 32) {
+            shift += 5;
+        }
+        else {
+            const negative = value & 1;
+            value >>>= 1;
+            out.push(negative ? -value : value);
+            value = 0;
+            shift = 0;
+        }
+    }
+    return out;
+}
+/**
+ * Normalise a source-map `sources` entry to a plain path. Bundlers prefix
+ * their own scheme (`webpack:///./src/a.ts`), dev servers serve absolute
+ * URLs paths (`/src/a.ts`), builds write relative ones (`../src/a.ts`).
+ * The server maps these onto the repo by suffix, so all that matters here
+ * is stripping what is not a path.
+ */
+export function normalizeSourcePath(src, sourceRoot) {
+    let s = src;
+    if (sourceRoot && !/^[a-z]+:/i.test(s)) {
+        s = sourceRoot.replace(/\/?$/, "/") + s;
+    }
+    s = s.replace(/^webpack:\/\/\/?/, "").replace(/^file:\/\//, "");
+    // A URL (`http://host/src/a.ts`, Vite's `/@fs/…`) keeps only its path.
+    const m = /^[a-z]+:\/\/[^/]*(\/.*)$/i.exec(s);
+    if (m)
+        s = m[1];
+    s = s.replace(/^\/@fs\//, "/");
+    s = s.replace(/\?.*$/, "");
+    while (s.startsWith("./"))
+        s = s.slice(2);
+    return s;
+}
+/** Sources nobody's change can be attributed to: dependencies and bundler
+ *  runtime shims. */
+export function isForeignSource(path) {
+    return (path.length === 0 ||
+        path.includes("node_modules/") ||
+        path.startsWith("webpack/") ||
+        path.startsWith("(webpack)") ||
+        path.startsWith("\0") ||
+        path.startsWith("vite/") ||
+        path.startsWith("@vite/"));
+}
+/**
+ * Decode a source map document. Index maps (`sections`) are not
+ * supported and decode to `null`, as does anything malformed — the
+ * caller then falls back to attributing the script to its own URL, which
+ * the repo mapping cannot resolve, which is the safe answer.
+ */
+export function decodeSourceMap(doc) {
+    if (!doc || typeof doc !== "object")
+        return null;
+    const m = doc;
+    if (m.sections || !Array.isArray(m.sources) || typeof m.mappings !== "string") {
+        return null;
+    }
+    const sourceRoot = typeof m.sourceRoot === "string" ? m.sourceRoot : undefined;
+    const sources = m.sources.map((s) => typeof s === "string" ? normalizeSourcePath(s, sourceRoot) : "");
+    const lines = [];
+    let src = 0;
+    let line = 0;
+    try {
+        for (const group of m.mappings.split(";")) {
+            const segs = [];
+            let col = 0;
+            if (group.length > 0) {
+                for (const seg of group.split(",")) {
+                    if (seg.length === 0)
+                        continue;
+                    const f = decodeVlq(seg);
+                    col += f[0];
+                    if (f.length >= 4) {
+                        src += f[1];
+                        line += f[2];
+                        segs.push({ col, src, line });
+                    }
+                }
+            }
+            lines.push(segs);
+        }
+    }
+    catch {
+        return null;
+    }
+    return { sources, lines };
+}
+/**
+ * Attribute generated line counts to original (file, line)s through the
+ * map. Every original line a generated line's segments name gets that
+ * line's count (max over the generated lines that touch it). Foreign
+ * sources are dropped.
+ */
+export function mapToOriginal(map, generated) {
+    const out = new Map();
+    for (const [genLine, count] of generated) {
+        const segs = map.lines[genLine - 1];
+        if (!segs || segs.length === 0)
+            continue;
+        for (const seg of segs) {
+            const file = map.sources[seg.src];
+            if (file === undefined || isForeignSource(file))
+                continue;
+            let lc = out.get(file);
+            if (!lc) {
+                lc = new Map();
+                out.set(file, lc);
+            }
+            const l = seg.line + 1;
+            lc.set(l, Math.max(lc.get(l) ?? 0, count));
+        }
+    }
+    return out;
+}
+// ── Accumulation + lcov ─────────────────────────────────────────────────
+/** Add `from` into `into` (sums — takes reset V8's counters). */
+export function mergeLineCounts(into, from) {
+    for (const [l, c] of from)
+        into.set(l, (into.get(l) ?? 0) + c);
+}
+export function mergeFileCounts(into, from) {
+    for (const [file, counts] of from) {
+        let target = into.get(file);
+        if (!target) {
+            target = new Map();
+            into.set(file, target);
+        }
+        mergeLineCounts(target, counts);
+    }
+}
+/** One lcov document for a set of files. */
+export function lcovDocument(files) {
+    let out = "TN:\n";
+    for (const [file, counts] of [...files].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+        out += `SF:${file}\n`;
+        let found = 0;
+        let hit = 0;
+        for (const [l, c] of [...counts].sort((a, b) => a[0] - b[0])) {
+            out += `DA:${l},${c}\n`;
+            found++;
+            if (c > 0)
+                hit++;
+        }
+        out += `LF:${found}\nLH:${hit}\nend_of_record\n`;
+    }
+    return out;
+}
+/**
+ * Which service a script URL's host belongs to: the service key itself,
+ * `<key>.internal`, its `hostnames`/`dnsName` aliases, a `tls`/`proxy`
+ * hostname routed to it, or a wildcard pointed at it. Exact first, then
+ * the longest wildcard suffix — the resolver's own precedence.
+ */
+export function serviceForHost(host, services, table) {
+    const h = host.toLowerCase().replace(/\.$/, "");
+    for (const s of services) {
+        if (h === s.toLowerCase() || h === `${s.toLowerCase()}.internal`)
+            return s;
+    }
+    for (const [svc, aliases] of Object.entries(table.aliasesByService)) {
+        if (aliases.some((a) => a.toLowerCase() === h))
+            return svc;
+    }
+    for (const p of table.proxies) {
+        if (p.hostname.toLowerCase() === h)
+            return p.service;
+    }
+    let best;
+    for (const w of table.wildcards) {
+        const service = w.target.service;
+        if (!service)
+            continue;
+        const suffix = w.pattern.toLowerCase().replace(/^\*/, "");
+        if (h.endsWith(suffix) && h.length > suffix.length) {
+            if (!best || suffix.length > best.len)
+                best = { len: suffix.length, service };
+        }
+    }
+    return best?.service;
+}

package/dist/index.d.ts

@@ -669,7 +669,22 @@ export type ServiceImage = {
  * spectest must run a command in the container to produce one.
  */
 export type ServiceCoverage = true | {
-    command: string;
+    /** Run this (via `sh -c`) in the container before the coverage
+     *  directory is read, so the service writes a fresh lcov report. */
+    command?: string;
+    /**
+     * Collect **frontend** coverage for the app this service serves.
+     * The code runs in the guest browser — spectest's own process — so
+     * the user cannot write a report for it: spectest turns on V8
+     * coverage for every script `ctx.browser()`/`ctx.mobile()` loads
+     * from this service's origin, maps it back to original sources
+     * through the served source maps, and adds one lcov report to this
+     * service's capture. Scripts a source map can't resolve are
+     * attributed to their served path (which the repo mapping then
+     * treats as unknown — the safe answer). Needs the app to serve
+     * source maps to the test environment.
+     */
+    browser?: boolean;
 };
 export interface VolumeMount {
     /**
@@ -888,6 +903,12 @@ export interface FakeContext {
  * same rule to a runtime `startService` spec.
  */
 export declare function validateCoverage(service: string, cov: unknown): void;
+/** Whether a `coverage` value collects reports from the container's own
+ *  filesystem (`/spectest/coverage/`). True for `true`, `{ command }`, and
+ *  any object that isn't browser-only. */
+export declare function coverageUsesContainer(cov: ServiceCoverage | undefined): boolean;
+/** Whether a `coverage` value collects frontend (browser) coverage. */
+export declare function coverageUsesBrowser(cov: ServiceCoverage | undefined): boolean;
 /**
  * A single test step. Created via `test(...)` or `createTest(services)`.
  * Tests are referenced (not named by string) when one test depends on

package/dist/index.js

@@ -222,13 +222,29 @@ function expandServiceGroups(input) {
 export function validateCoverage(service, cov) {
     if (cov === undefined || cov === true)
         return;
-    if (typeof cov === "object" &&
-        cov !== null &&
-        typeof cov.command === "string" &&
-        cov.command.trim().length > 0) {
-        return;
+    if (typeof cov === "object" && cov !== null) {
+        const o = cov;
+        const cmdOk = o.command === undefined ||
+            (typeof o.command === "string" && o.command.trim().length > 0);
+        const browserOk = o.browser === undefined || typeof o.browser === "boolean";
+        if (cmdOk && browserOk && (o.command !== undefined || o.browser === true))
+            return;
     }
-    throw new Error(`service "${service}" has an invalid \`coverage\` value — use \`true\` or \`{ command: "<shell command>" }\``);
+    throw new Error(`service "${service}" has an invalid \`coverage\` value — use \`true\`, \`{ command: "<shell command>" }\`, or \`{ browser: true }\``);
+}
+/** Whether a `coverage` value collects reports from the container's own
+ *  filesystem (`/spectest/coverage/`). True for `true`, `{ command }`, and
+ *  any object that isn't browser-only. */
+export function coverageUsesContainer(cov) {
+    if (cov === undefined)
+        return false;
+    if (cov === true)
+        return true;
+    return cov.command !== undefined || cov.browser !== true;
+}
+/** Whether a `coverage` value collects frontend (browser) coverage. */
+export function coverageUsesBrowser(cov) {
+    return typeof cov === "object" && cov.browser === true;
 }
 function validateEnvironmentConfig(config) {
     const entries = Object.entries(config.services);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser-coverage.ts

@@ -0,0 +1,209 @@
+// Browser coverage — the collector.
+//
+// One collector per CDP session (i.e. per page view). `attach` turns on
+// V8 precise coverage and tracks parsed scripts; `harvest` takes the
+// counters (which RESETS them — V8 reports nothing for a script that ran
+// nothing since the last take, so the counts are summed here across
+// takes), maps each script the browser loaded from a covered service back
+// to its original sources through the served source map, and folds the
+// result into a per-service total in module memory — which forks with the
+// daemon, so a child test inherits its ancestors' browser coverage exactly
+// as a container's counters are inherited.
+//
+// Harvest runs before every browser step (a click that navigates
+// cross-site replaces the renderer, and the old counters with it) and at
+// every coverage capture. `browserCoverageReports` renders the totals as
+// one lcov per service for the `case-coverage` bundle.
+//
+// Configured by the daemon at /load with the host → service table; a
+// project with no `coverage: { browser: true }` service never attaches
+// anything, so it costs nothing.
+
+import { createHash } from "node:crypto";
+import type { CDPSession } from "playwright-core";
+import {
+  type DecodedSourceMap,
+  type FileCounts,
+  decodeSourceMap,
+  lcovDocument,
+  mapToOriginal,
+  mergeFileCounts,
+  rangesToLineCounts,
+  type V8FunctionCoverage,
+} from "./harness/browser-coverage.js";
+import { rawFetch } from "./harness/raw-fetch.js";
+
+export interface BrowserCoverageConfig {
+  /** Which covered service (if any) serves scripts from this host. */
+  serviceForHost(host: string): string | undefined;
+}
+
+let CONFIG: BrowserCoverageConfig | null = null;
+
+/** Set (or clear, with `null`) at /load. */
+export function configureBrowserCoverage(config: BrowserCoverageConfig | null): void {
+  CONFIG = config;
+}
+
+export function browserCoverageActive(): boolean {
+  return CONFIG !== null;
+}
+
+/** service → file → line → count, summed over every harvest. */
+const TOTALS = new Map<string, FileCounts>();
+
+interface ScriptInfo {
+  url: string;
+  sourceMapURL?: string;
+  source?: string;
+  /** `undefined` = not looked up yet; `null` = none / unusable. */
+  map?: DecodedSourceMap | null;
+}
+
+interface Collector {
+  cdp: CDPSession;
+  scripts: Map<string, ScriptInfo>;
+  inFlight: Promise<void> | null;
+}
+
+const COLLECTORS = new WeakMap<CDPSession, Collector>();
+
+/** Decoded maps by URL (or content hash for inline `data:` maps). */
+const SOURCE_MAPS = new Map<string, DecodedSourceMap | null>();
+
+const SOURCE_MAP_FETCH_TIMEOUT_MS = 10_000;
+
+/** Turn coverage on for a page's CDP session. Idempotent; a no-op when no
+ *  service opted in. */
+export async function attachBrowserCoverage(cdp: CDPSession): Promise<void> {
+  if (!CONFIG || COLLECTORS.has(cdp)) return;
+  const collector: Collector = { cdp, scripts: new Map(), inFlight: null };
+  COLLECTORS.set(cdp, collector);
+  cdp.on("Debugger.scriptParsed", (ev: { scriptId: string; url: string; sourceMapURL?: string }) => {
+    if (!ev.url) return;
+    collector.scripts.set(ev.scriptId, {
+      url: ev.url,
+      sourceMapURL: ev.sourceMapURL || undefined,
+    });
+  });
+  await cdp.send("Debugger.enable");
+  await cdp.send("Profiler.enable");
+  await cdp.send("Profiler.startPreciseCoverage", { callCount: true, detailed: true });
+}
+
+/**
+ * Take the session's counters and fold them into the totals. Concurrent
+ * calls coalesce onto the in-flight one. Errors (a page mid-navigation,
+ * a closed view) are swallowed: the counters then stay in V8 for the next
+ * take, nothing is lost.
+ */
+export async function harvestBrowserCoverage(cdp: CDPSession): Promise<void> {
+  const c = COLLECTORS.get(cdp);
+  if (!c || !CONFIG) return;
+  if (c.inFlight) return c.inFlight;
+  c.inFlight = harvestInner(c, CONFIG).catch(() => {}).finally(() => {
+    c.inFlight = null;
+  });
+  return c.inFlight;
+}
+
+async function harvestInner(c: Collector, config: BrowserCoverageConfig): Promise<void> {
+  const { result } = (await c.cdp.send("Profiler.takePreciseCoverage")) as {
+    result: { scriptId: string; url: string; functions: V8FunctionCoverage[] }[];
+  };
+  for (const script of result) {
+    const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
+    if (!info) continue;
+    let url: URL;
+    try {
+      url = new URL(info.url);
+    } catch {
+      continue;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") continue;
+    const service = config.serviceForHost(url.hostname);
+    if (!service) continue;
+    if (info.source === undefined) {
+      try {
+        const r = (await c.cdp.send("Debugger.getScriptSource", {
+          scriptId: script.scriptId,
+        })) as { scriptSource: string };
+        info.source = r.scriptSource;
+      } catch {
+        continue; // script gone with its document
+      }
+      c.scripts.set(script.scriptId, info);
+    }
+    const generated = rangesToLineCounts(info.source, script.functions);
+    if (generated.size === 0) continue;
+    if (info.map === undefined) info.map = await sourceMapFor(info, url);
+    const files: FileCounts = info.map
+      ? mapToOriginal(info.map, generated)
+      : new Map([[url.pathname, generated]]);
+    let totals = TOTALS.get(service);
+    if (!totals) {
+      totals = new Map();
+      TOTALS.set(service, totals);
+    }
+    mergeFileCounts(totals, files);
+  }
+}
+
+/** Resolve, fetch (or inline-decode) and decode a script's source map. */
+async function sourceMapFor(info: ScriptInfo, scriptUrl: URL): Promise<DecodedSourceMap | null> {
+  let ref = info.sourceMapURL;
+  if (!ref && info.source) {
+    const m = /\/\/[#@]\s*sourceMappingURL=(\S+)\s*$/.exec(info.source.slice(-4096));
+    if (m) ref = m[1];
+  }
+  if (!ref) return null;
+  if (ref.startsWith("data:")) {
+    const key = "data:" + createHash("sha1").update(ref).digest("hex");
+    const cached = SOURCE_MAPS.get(key);
+    if (cached !== undefined) return cached;
+    const map = decodeSourceMap(parseDataUrl(ref));
+    SOURCE_MAPS.set(key, map);
+    return map;
+  }
+  let mapUrl: string;
+  try {
+    mapUrl = new URL(ref, scriptUrl).toString();
+  } catch {
+    return null;
+  }
+  const cached = SOURCE_MAPS.get(mapUrl);
+  if (cached !== undefined) return cached;
+  let map: DecodedSourceMap | null = null;
+  try {
+    const res = await rawFetch(mapUrl, { signal: AbortSignal.timeout(SOURCE_MAP_FETCH_TIMEOUT_MS) });
+    if (res.ok) map = decodeSourceMap(await res.json());
+  } catch {
+    map = null;
+  }
+  SOURCE_MAPS.set(mapUrl, map);
+  return map;
+}
+
+function parseDataUrl(ref: string): unknown {
+  const comma = ref.indexOf(",");
+  if (comma < 0) return null;
+  const meta = ref.slice(5, comma);
+  const payload = ref.slice(comma + 1);
+  try {
+    const text = /;base64$/i.test(meta)
+      ? Buffer.from(payload, "base64").toString("utf8")
+      : decodeURIComponent(payload);
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/** One lcov document per service that has any browser coverage. */
+export function browserCoverageReports(): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [service, files] of TOTALS) {
+    if (files.size > 0) out.set(service, lcovDocument(files));
+  }
+  return out;
+}

package/src/browser.ts

@@ -38,6 +38,11 @@ import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./r
 import { wrap } from "./inspect.js";
 import type { Wrapped } from "./inspect.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import {
+  attachBrowserCoverage,
+  browserCoverageActive,
+  harvestBrowserCoverage,
+} from "./browser-coverage.js";
 import type { UrlPattern } from "./url-match.js";
 export type { UrlPattern } from "./url-match.js";
 import {
@@ -1223,6 +1228,13 @@ async function spawnPage(context: BrowserContext): Promise<SpawnedPage> {
       console.warn("[spectest] failed to install rrweb recorder:", err);
     }
   }
+  // Frontend coverage (opt-in): turn on V8 precise coverage for this page.
+  // A no-op unless a service declared `coverage: { browser: true }`.
+  try {
+    await attachBrowserCoverage(cdp);
+  } catch {
+    /* coverage is best-effort; a page without it still works */
+  }
   return { page, cdp, recordingInstalled };
 }
 
@@ -1558,6 +1570,13 @@ async function rebuildView(holder: ViewHolder): Promise<void> {
   } catch {
     /* page may already be gone */
   }
+  // The old renderer's coverage counters die with its page; harvest what
+  // it had before the swap (rebuild is triggered on a fresh navigation).
+  try {
+    await harvestBrowserCoverage(holder.cdp);
+  } catch {
+    /* best-effort */
+  }
   const fresh = await spawnPage(holder.context);
   holder.page = fresh.page;
   holder.cdp = fresh.cdp;
@@ -1660,6 +1679,16 @@ function buildBackend(
         durationMs: endT - t,
       }, resv);
       await drain(action);
+      // Fold this page's V8 counters into the per-service totals now — a
+      // navigation to another origin replaces the renderer and its
+      // counters, so harvesting per op is what keeps them.
+      if (browserCoverageActive()) {
+        try {
+          await harvestBrowserCoverage(holder.cdp);
+        } catch {
+          /* best-effort */
+        }
+      }
       // Reads (`opts.wrap`) return user-visible JS values someone is likely to
       // assert on — provenance-wrap so `expect(...)` nests under this step.
       // Actions return void/internals; leave them raw to avoid Proxy surprises.
@@ -1688,6 +1717,13 @@ function buildBackend(
     if (recordingEnded) return;
     // Final drain before we stop writing to this recorder.
     await drain("close");
+    if (browserCoverageActive()) {
+      try {
+        await harvestBrowserCoverage(holder.cdp);
+      } catch {
+        /* best-effort */
+      }
+    }
     recordingEnded = true;
   }