@specific.dev/spectest 0.57.0 → 0.58.0

package/dist/browser-coverage.d.ts

@@ -0,0 +1,20 @@
+import type { CDPSession } from "playwright-core";
+export interface BrowserCoverageConfig {
+    /** Which covered service (if any) serves scripts from this host. */
+    serviceForHost(host: string): string | undefined;
+}
+/** Set (or clear, with `null`) at /load. */
+export declare function configureBrowserCoverage(config: BrowserCoverageConfig | null): void;
+export declare function browserCoverageActive(): boolean;
+/** Turn coverage on for a page's CDP session. Idempotent; a no-op when no
+ *  service opted in. */
+export declare function attachBrowserCoverage(cdp: CDPSession): Promise<void>;
+/**
+ * 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 declare function harvestBrowserCoverage(cdp: CDPSession): Promise<void>;
+/** One lcov document per service that has any browser coverage. */
+export declare function browserCoverageReports(): Map<string, string>;

package/dist/browser-coverage.js

@@ -0,0 +1,185 @@
+// 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 { decodeSourceMap, lcovDocument, mapToOriginal, mergeFileCounts, rangesToLineCounts, } from "./harness/browser-coverage.js";
+import { rawFetch } from "./harness/raw-fetch.js";
+let CONFIG = null;
+/** Set (or clear, with `null`) at /load. */
+export function configureBrowserCoverage(config) {
+    CONFIG = config;
+}
+export function browserCoverageActive() {
+    return CONFIG !== null;
+}
+/** service → file → line → count, summed over every harvest. */
+const TOTALS = new Map();
+const COLLECTORS = new WeakMap();
+/** Decoded maps by URL (or content hash for inline `data:` maps). */
+const SOURCE_MAPS = new Map();
+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) {
+    if (!CONFIG || COLLECTORS.has(cdp))
+        return;
+    const collector = { cdp, scripts: new Map(), inFlight: null };
+    COLLECTORS.set(cdp, collector);
+    cdp.on("Debugger.scriptParsed", (ev) => {
+        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) {
+    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, config) {
+    const { result } = (await c.cdp.send("Profiler.takePreciseCoverage"));
+    for (const script of result) {
+        const info = c.scripts.get(script.scriptId) ?? (script.url ? { url: script.url } : undefined);
+        if (!info)
+            continue;
+        let 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,
+                }));
+                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 = 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, scriptUrl) {
+    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;
+    try {
+        mapUrl = new URL(ref, scriptUrl).toString();
+    }
+    catch {
+        return null;
+    }
+    const cached = SOURCE_MAPS.get(mapUrl);
+    if (cached !== undefined)
+        return cached;
+    let map = 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) {
+    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() {
+    const out = new Map();
+    for (const [service, files] of TOTALS) {
+        if (files.size > 0)
+            out.set(service, lcovDocument(files));
+    }
+    return out;
+}

package/dist/browser.js

@@ -35,6 +35,7 @@ import { generateId } from "./ids.js";
 import { recordBrowser, reserveBackdated, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import { attachBrowserCoverage, browserCoverageActive, harvestBrowserCoverage, } from "./browser-coverage.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
 import { chromium } from "playwright-core";
 /** Decoded byte count of a base64 string, without decoding it. */
@@ -792,6 +793,14 @@ async function spawnPage(context) {
             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 };
 }
 /** Create a default-desktop view (plus its context) for the pool. */
@@ -1080,6 +1089,14 @@ async function rebuildView(holder) {
     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;
@@ -1164,6 +1181,17 @@ function buildBackend(holder, recorder, buildOpts) {
                 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.
@@ -1193,6 +1221,14 @@ function buildBackend(holder, recorder, buildOpts) {
             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;
     }
     const strategy = holder.device ? mobileStrategy : desktopStrategy;

package/dist/daemon.js

@@ -21,8 +21,10 @@ import { existsSync, promises as fs, readFileSync } from "node:fs";
 import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, validateCoverage, } from "./index.js";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, validateCoverage, coverageUsesBrowser, coverageUsesContainer, } from "./index.js";
 import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, readCoverageDir, } from "./harness/coverage.js";
+import { browserCoverageReports, configureBrowserCoverage, } from "./browser-coverage.js";
+import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
 // Pure ingress hostname matching, ported out of this file (see
@@ -523,6 +525,10 @@ async function ensureCoverage(svc) {
     if (svc.coverage === undefined)
         return [];
     validateCoverage(svc.name, svc.coverage);
+    // A browser-only opt-in has no container process to write reports, so it
+    // gets no mount — its coverage comes from the guest browser.
+    if (!coverageUsesContainer(svc.coverage))
+        return [];
     const host = coverageHostDir(WORKSPACE, svc.name);
     await fs.mkdir(host, { recursive: true });
     await fs.chmod(host, 0o777);
@@ -1422,6 +1428,7 @@ function buildIngress(project) {
     // generic decl set the daemon executes. The special-casing lives in the
     // SDK's lowerIngress, not here.
     LOWERED = lowerIngress(project);
+    configureCoverageAttribution(project);
     if (!project.fakes)
         return;
     for (const [name, def] of Object.entries(project.fakes)) {
@@ -2980,6 +2987,35 @@ async function captureServiceLogDeltas() {
 // container first so the service writes a fresh report. The reports ship
 // verbatim; the server derives what it needs from the stored bytes.
 const COVERAGE_COMMAND_TIMEOUT_MS = 60_000;
+/** Set the browser-coverage host→service attribution from the loaded
+ *  project: only services that opted in to `coverage: { browser: true }`
+ *  are attributed, so a script from an uncovered service is ignored. Null
+ *  when no service opted in — coverage then attaches nothing. Called on
+ *  every /load. */
+function configureCoverageAttribution(project) {
+    const env = project.environment;
+    const browserServices = new Set();
+    for (const svc of namedServices(env)) {
+        if (coverageUsesBrowser(svc.coverage))
+            browserServices.add(svc.name);
+    }
+    if (browserServices.size === 0) {
+        configureBrowserCoverage(null);
+        return;
+    }
+    const all = namedServices(env).map((s) => s.name);
+    const table = {
+        proxies: LOWERED.proxies,
+        aliasesByService: LOWERED.aliasesByService,
+        wildcards: LOWERED.wildcards,
+    };
+    configureBrowserCoverage({
+        serviceForHost(host) {
+            const svc = hostToService(host, all, table);
+            return svc && browserServices.has(svc) ? svc : undefined;
+        },
+    });
+}
 async function captureServiceCoverage() {
     const l = loaded;
     if (!l)
@@ -2990,20 +3026,45 @@ async function captureServiceCoverage() {
     for (const [name, s] of RUNTIME_SERVICES)
         byName.set(name, s);
     const services = [...byName.values()].filter((s) => s.coverage !== undefined);
+    // Browser coverage is per-service lcov, accumulated in module memory
+    // (browser-coverage.ts) across every harvest; read it once here.
+    const browser = browserCoverageReports();
     return Promise.all(services.map(async (svc) => {
         const cov = svc.coverage;
-        if (typeof cov === "object" && cov !== null) {
-            const r = await docker(["exec", svc.name, "sh", "-c", cov.command], COVERAGE_COMMAND_TIMEOUT_MS);
-            if (r.code !== 0) {
-                const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
-                return {
-                    service: svc.name,
-                    reports: [],
-                    error: `coverage command for service "${svc.name}" failed (exit ${r.code}): ${JSON.stringify(cov.command)}${tail ? `\n${tail}` : ""}`,
-                };
+        const reports = [];
+        // Container reports (a `command` runs first to flush a fresh dump).
+        if (coverageUsesContainer(cov)) {
+            if (typeof cov === "object" && cov !== null && cov.command) {
+                const r = await docker(["exec", svc.name, "sh", "-c", cov.command], COVERAGE_COMMAND_TIMEOUT_MS);
+                if (r.code !== 0) {
+                    const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
+                    return {
+                        service: svc.name,
+                        reports: [],
+                        error: `coverage command for service "${svc.name}" failed (exit ${r.code}): ${JSON.stringify(cov.command)}${tail ? `\n${tail}` : ""}`,
+                    };
+                }
+            }
+            const dir = await readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+            // A service that ALSO does browser coverage may legitimately have
+            // an empty container dir for a test — don't fail if the browser
+            // side has something. Otherwise the container contract stands.
+            if (dir.error && !(coverageUsesBrowser(cov) && browser.has(svc.name))) {
+                return dir;
             }
+            reports.push(...dir.reports);
+        }
+        // Browser report for this service, when any script it served ran.
+        const lcov = browser.get(svc.name);
+        if (lcov)
+            reports.push({ name: "browser.lcov", content: lcov });
+        if (reports.length === 0 && coverageUsesBrowser(cov) && !coverageUsesContainer(cov)) {
+            // Browser-only service, no browser activity yet this branch. Not an
+            // error — a test needn't open a browser; the report appears once
+            // one does (and forks to descendants from there).
+            return { service: svc.name, reports: [] };
         }
-        return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
+        return { service: svc.name, reports };
     }));
 }
 /**

package/dist/harness/browser-coverage.d.ts

@@ -0,0 +1,95 @@
+/** Per-line hit counts, 1-based line numbers. */
+export type LineCounts = Map<number, number>;
+/** Per-file line counts. Keys are source paths as the source map (or the
+ *  script URL, when there is no map) reports them. */
+export type FileCounts = Map<string, LineCounts>;
+/** Byte offset at which each line starts. */
+export declare function lineStartsOf(source: string): number[];
+/** 1-based line holding `offset`. */
+export declare function lineOf(starts: number[], offset: number): number;
+/** One V8 `FunctionCoverage` as `Profiler.takePreciseCoverage` reports it. */
+export interface V8FunctionCoverage {
+    functionName?: string;
+    ranges: {
+        startOffset: number;
+        endOffset: number;
+        count: number;
+    }[];
+    isBlockCoverage?: boolean;
+}
+/**
+ * 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 declare function rangesToLineCounts(source: string, functions: readonly V8FunctionCoverage[]): LineCounts;
+/** One mapping segment: generated column → original (source, line). */
+export interface Segment {
+    col: number;
+    src: number;
+    line: number;
+}
+export interface DecodedSourceMap {
+    /** Normalised source paths, indexed by segment `src`. */
+    sources: string[];
+    /** Segments per generated line (0-based), sorted by column. */
+    lines: Segment[][];
+}
+/** Decode one VLQ-encoded segment into its fields. */
+export declare function decodeVlq(segment: string): number[];
+/**
+ * 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 declare function normalizeSourcePath(src: string, sourceRoot?: string): string;
+/** Sources nobody's change can be attributed to: dependencies and bundler
+ *  runtime shims. */
+export declare function isForeignSource(path: string): boolean;
+/**
+ * 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 declare function decodeSourceMap(doc: unknown): DecodedSourceMap | null;
+/**
+ * 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 declare function mapToOriginal(map: DecodedSourceMap, generated: LineCounts): FileCounts;
+/** Add `from` into `into` (sums — takes reset V8's counters). */
+export declare function mergeLineCounts(into: LineCounts, from: LineCounts): void;
+export declare function mergeFileCounts(into: FileCounts, from: FileCounts): void;
+/** One lcov document for a set of files. */
+export declare function lcovDocument(files: FileCounts): string;
+/** The slice of the lowered ingress that names hosts. */
+export interface HostTable {
+    proxies: readonly {
+        hostname: string;
+        service: string;
+    }[];
+    aliasesByService: Readonly<Record<string, readonly string[]>>;
+    wildcards: readonly {
+        pattern: string;
+        target: {
+            service?: string;
+        } | {
+            ingress?: boolean;
+        } | Record<string, unknown>;
+    }[];
+}
+/**
+ * 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 declare function serviceForHost(host: string, services: readonly string[], table: HostTable): string | undefined;