@specific.dev/spectest 0.58.0 → 0.59.1

package/dist/daemon.js

@@ -21,9 +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, 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 { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, proxy as makeProxyDecl, } from "./index.js";
+import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, } from "./harness/coverage.js";
+import { configureBrowserCoverage } from "./browser-coverage.js";
+import { applyCoverageAdapters, coverageAdapters, validateCoverage, } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
 import { acquirePersistentBrowser, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
@@ -525,10 +526,6 @@ 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);
@@ -1428,7 +1425,11 @@ 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);
+    BROWSER_COVERAGE_SERVICES.clear();
+    void runCoverageLoadHooks(namedServices(project.environment)).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn("[coverage] load hook failed:", err);
+    });
     if (!project.fakes)
         return;
     for (const [name, def] of Object.entries(project.fakes)) {
@@ -2313,7 +2314,9 @@ const RUNTIME_SERVICES = new Map();
 // the orchestration helpers want a NamedService, which is the same shape.
 function specToNamedService(spec) {
     const { name, ...rest } = spec;
-    return { name, ...rest };
+    // A runtime spec skipped `defineEnvironment`, so its coverage adapters
+    // get their config-time pass here.
+    return { name, ...applyCoverageAdapters(name, rest) };
 }
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
  *  Prepares the image (pulling on first use through the host cache), runs
@@ -2326,6 +2329,7 @@ async function startRuntimeService(spec) {
     const t0 = Date.now();
     const resv = reserveEvent();
     const svc = specToNamedService(spec);
+    await runCoverageLoadHooks([svc]);
     const aliases = (spec.hostnames ?? []).map((h) => h.toLowerCase());
     const imageRef = svc.image.type === "registry" ? svc.image.reference : "(dockerfile)";
     try {
@@ -2977,33 +2981,50 @@ async function captureServiceLogDeltas() {
     }));
 }
 // ────────────────────────────────────────────────────────────────────────
-// Coverage capture (opt-in per service; see harness/coverage.ts)
+// Coverage capture (opt-in per service; see coverage.ts + harness/coverage.ts)
 // ────────────────────────────────────────────────────────────────────────
 //
-// Read after bring-up and after every test, on every case. The reports are
-// cumulative from process start and live on the rootfs, so what a child
-// fork reads already includes everything its ancestors ran — no markers,
-// no deltas (unlike the service logs above). A `command` runs in the
-// 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) {
+// Read after bring-up and after every test, on every case. A service's
+// adapters run first (each makes its report appear in the directory —
+// `nodeCoverage` asks the hook for a dump, `browserCoverage` writes the
+// harness's totals, `commandCoverage` runs the command), then the
+// directory is read the same way for every service, `coverage: true`
+// included. The reports live on the rootfs, so what a child fork reads
+// already includes everything its ancestors ran — no markers, no deltas
+// (unlike the service logs above). The reports ship verbatim; the server
+// derives what it needs from the stored bytes.
+/** Budget for one service's adapters at one capture, all of them. */
+const COVERAGE_CAPTURE_TIMEOUT_MS = 60_000;
+/** Services whose adapters asked for browser scripts at /load
+ *  (`CoverageLoadContext.collectBrowserScripts`). Cleared on every /load;
+ *  a runtime service's adapters add to it when it starts. */
+const BROWSER_COVERAGE_SERVICES = new Set();
+/** Run every adapter's `load` hook for `services`, then rebuild the
+ *  browser-coverage attribution from whoever asked. The attribution is a
+ *  host → service resolver over the lowered ingress, restricted to those
+ *  services, so a script from an uncovered service is ignored; null when
+ *  nobody asked, which costs nothing. */
+async function runCoverageLoadHooks(services) {
+    for (const svc of services) {
+        for (const a of coverageAdapters(svc.coverage)) {
+            if (!a.load)
+                continue;
+            await a.load({
+                service: svc.name,
+                collectBrowserScripts: () => {
+                    BROWSER_COVERAGE_SERVICES.add(svc.name);
+                },
+            });
+        }
+    }
+    rebuildBrowserCoverageResolver();
+}
+function rebuildBrowserCoverageResolver() {
+    if (BROWSER_COVERAGE_SERVICES.size === 0 || !loaded) {
         configureBrowserCoverage(null);
         return;
     }
-    const all = namedServices(env).map((s) => s.name);
+    const all = [...namedServices(loaded.project.environment).map((s) => s.name), ...RUNTIME_SERVICES.keys()];
     const table = {
         proxies: LOWERED.proxies,
         aliasesByService: LOWERED.aliasesByService,
@@ -3012,10 +3033,66 @@ function configureCoverageAttribution(project) {
     configureBrowserCoverage({
         serviceForHost(host) {
             const svc = hostToService(host, all, table);
-            return svc && browserServices.has(svc) ? svc : undefined;
+            return svc && BROWSER_COVERAGE_SERVICES.has(svc) ? svc : undefined;
         },
     });
 }
+/** The context one adapter's `capture` runs against. */
+function coverageCaptureContext(svc, signal) {
+    const reportDir = coverageHostDir(WORKSPACE, svc.name);
+    return {
+        service: svc.name,
+        reportDir,
+        signal,
+        async exec(command) {
+            const r = await docker(["exec", svc.name, "sh", "-c", command], COVERAGE_CAPTURE_TIMEOUT_MS);
+            if (r.code !== 0) {
+                const tail = capMiddle((r.stderr || r.stdout).trim(), 2000).value;
+                throw new Error(`${JSON.stringify(command)} exited ${r.code}${tail ? `\n${tail}` : ""}`);
+            }
+            return { stdout: r.stdout, stderr: r.stderr };
+        },
+        async writeReport(name, content) {
+            const file = path.join(reportDir, name);
+            if (path.relative(reportDir, file).startsWith("..")) {
+                throw new Error(`writeReport: ${JSON.stringify(name)} leaves the coverage directory`);
+            }
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            const tmp = path.join(path.dirname(file), `.${path.basename(file)}.tmp`);
+            await fs.writeFile(tmp, content);
+            await fs.rename(tmp, file);
+        },
+    };
+}
+/** Run one service's adapters in order under one budget. Returns the
+ *  error to fail the capture with, naming the adapter. */
+async function runCoverageAdapters(svc) {
+    const adapters = coverageAdapters(svc.coverage).filter((a) => a.capture);
+    if (adapters.length === 0)
+        return undefined;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), COVERAGE_CAPTURE_TIMEOUT_MS);
+    const ctx = coverageCaptureContext(svc, ac.signal);
+    try {
+        for (const a of adapters) {
+            try {
+                await Promise.race([
+                    a.capture(ctx),
+                    new Promise((_, reject) => {
+                        ac.signal.addEventListener("abort", () => reject(new Error(`no report within ${COVERAGE_CAPTURE_TIMEOUT_MS / 1000}s`)), { once: true });
+                    }),
+                ]);
+            }
+            catch (err) {
+                return `coverage adapter "${a.name}" on service "${svc.name}" failed: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function captureServiceCoverage() {
     const l = loaded;
     if (!l)
@@ -3026,45 +3103,11 @@ 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;
-        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 { service: svc.name, reports };
+        const error = await runCoverageAdapters(svc);
+        if (error)
+            return { service: svc.name, reports: [], error };
+        return readCoverageDir(svc.name, coverageHostDir(WORKSPACE, svc.name));
     }));
 }
 /**
@@ -5070,7 +5113,17 @@ export function harnessMethods(state) {
             // the control plane logs it.
             let coverage;
             try {
-                coverage = parkCoverageBundle(SETUP_CASE_ID, await captureServiceCoverage());
+                const captures = await captureServiceCoverage();
+                for (const c of captures) {
+                    // After bring-up the code that started the service has run, so a
+                    // report set that names no file at all is a misconfigured tool —
+                    // visible in the boot log, never a failure (there is no case).
+                    if (!c.error && c.reports.length > 0 && c.reports.every((r) => isEmptyReport(r.content))) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`[coverage] service "${c.service}": every report is empty after bring-up — is coverage enabled at process start?`);
+                    }
+                }
+                coverage = parkCoverageBundle(SETUP_CASE_ID, captures);
             }
             catch (err) {
                 // eslint-disable-next-line no-console

package/dist/harness/coverage.d.ts

@@ -1,7 +1,7 @@
 /** Where the directory is mounted inside an opted-in container. */
 export declare const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 /** Raw bytes of reports one service may ship per capture. Reports are
- *  cumulative and bounded by code size, so anything past this is a
+ *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
 export declare const COVERAGE_MAX_BYTES_PER_SERVICE: number;
 /** Root of the per-service host directories, under the workspace so the
@@ -44,14 +44,33 @@ export interface CoverageBundle {
 }
 /** True when `text` holds at least one lcov `SF:` record. */
 export declare function hasLcovSourceFile(text: string): boolean;
+/** True when `text` is lcov-shaped: at least one line, every non-blank
+ *  line an `XX:` record or `end_of_record`. An lcov with no `SF:` record
+ *  at all (`TN:` alone) is well-formed — it is a report that says
+ *  nothing ran. */
+export declare function isLcovShaped(text: string): boolean;
+/**
+ * True when `text` looks like a V8 coverage JSON document — what
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
+ * `result` array of scripts. A cheap shape check, not a parse (a report
+ * can be megabytes); the control plane parses for real.
+ */
+export declare function isV8CoverageJson(text: string): boolean;
+/** True when `text` is a report spectest stores: lcov or V8 JSON. */
+export declare function isWellFormedReport(text: string): boolean;
+/** True when a well-formed report names no source file at all (an lcov
+ *  with no `SF:`, a V8 document with an empty `result`). */
+export declare function isEmptyReport(text: string): boolean;
 /** Every regular file under `dir`, recursively, as paths relative to it.
  *  Hidden files are skipped (a tool's own bookkeeping — `.seq`, `.lock`,
  *  a tmp file mid-write — is not a report). */
 export declare function listReportFiles(dir: string): Promise<string[]>;
 /**
- * Read every report under `dir`, verbatim. An empty directory, or one with
- * no `SF:` record anywhere, is an error rather than an empty capture: the
- * contract is that an opted-in service always has a report to read.
+ * Read every report under `dir`, verbatim. An empty directory, or a file
+ * that is neither lcov nor V8 JSON, is an error rather than an empty
+ * capture: the contract is that an opted-in service always has a
+ * well-formed report to read. A report that names no file is fine — it
+ * says nothing ran.
  */
 export declare function readCoverageDir(service: string, dir: string): Promise<ServiceCoverageCapture>;
 /** Gzip a case's captures into the bundle `coverageChunk` serves. */

package/dist/harness/coverage.js

@@ -2,12 +2,15 @@
 //
 // A service that opts in (`coverage: true | { command }`) gets a writable
 // directory bind-mounted at `/spectest/coverage/` in its container. The
-// service's own tool writes lcov reports there. The daemon reads the
+// service's own tool, or its coverage adapters, write reports there —
+// lcov, or the V8 coverage JSON that `NODE_V8_COVERAGE` writes. The daemon reads the
 // directory from the VM side (no `docker exec` to fetch) after bring-up
 // and after each test, and ships the reports **verbatim** to the control
 // plane as a gzipped bundle. Nothing is interpreted here beyond the one
-// contract the harness must fail a case on: at least one report, and at
-// least one lcov `SF:` record among them. The server derives whatever it
+// contract the harness must fail a case on: at least one report, every
+// one well-formed. Counters may reset between dumps and a dump may be a
+// new file: the directory forks with the environment, so it accumulates
+// along the ancestor chain by itself. The server derives whatever it
 // needs (today the set of source files; later, finer things) from the
 // stored bytes, so a change in that derivation is a re-read of stored
 // runs, never a hole in the history.
@@ -19,7 +22,7 @@ import { gzipSync } from "node:zlib";
 /** Where the directory is mounted inside an opted-in container. */
 export const COVERAGE_CONTAINER_DIR = "/spectest/coverage";
 /** Raw bytes of reports one service may ship per capture. Reports are
- *  cumulative and bounded by code size, so anything past this is a
+ *  bounded by code size times chain depth, so anything past this is a
  *  runaway (a tool writing a new file per request), not coverage. */
 export const COVERAGE_MAX_BYTES_PER_SERVICE = 64 * 1024 * 1024;
 /** Root of the per-service host directories, under the workspace so the
@@ -31,6 +34,34 @@ export function coverageHostDir(workspace, service) {
 export function hasLcovSourceFile(text) {
     return /^SF:\S/m.test(text);
 }
+/** True when `text` is lcov-shaped: at least one line, every non-blank
+ *  line an `XX:` record or `end_of_record`. An lcov with no `SF:` record
+ *  at all (`TN:` alone) is well-formed — it is a report that says
+ *  nothing ran. */
+export function isLcovShaped(text) {
+    const lines = text.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    return lines.length > 0 && lines.every((l) => /^[A-Z]{2,5}:/.test(l) || l.trim() === "end_of_record");
+}
+/**
+ * True when `text` looks like a V8 coverage JSON document — what
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
+ * `result` array of scripts. A cheap shape check, not a parse (a report
+ * can be megabytes); the control plane parses for real.
+ */
+export function isV8CoverageJson(text) {
+    return /^\s*\{/.test(text) && /"result"\s*:\s*\[/.test(text);
+}
+/** True when `text` is a report spectest stores: lcov or V8 JSON. */
+export function isWellFormedReport(text) {
+    return isLcovShaped(text) || isV8CoverageJson(text);
+}
+/** True when a well-formed report names no source file at all (an lcov
+ *  with no `SF:`, a V8 document with an empty `result`). */
+export function isEmptyReport(text) {
+    if (isV8CoverageJson(text))
+        return /"result"\s*:\s*\[\s*\]/.test(text);
+    return !hasLcovSourceFile(text);
+}
 /** Every regular file under `dir`, recursively, as paths relative to it.
  *  Hidden files are skipped (a tool's own bookkeeping — `.seq`, `.lock`,
  *  a tmp file mid-write — is not a report). */
@@ -58,9 +89,11 @@ export async function listReportFiles(dir) {
     return out.sort();
 }
 /**
- * Read every report under `dir`, verbatim. An empty directory, or one with
- * no `SF:` record anywhere, is an error rather than an empty capture: the
- * contract is that an opted-in service always has a report to read.
+ * Read every report under `dir`, verbatim. An empty directory, or a file
+ * that is neither lcov nor V8 JSON, is an error rather than an empty
+ * capture: the contract is that an opted-in service always has a
+ * well-formed report to read. A report that names no file is fine — it
+ * says nothing ran.
  */
 export async function readCoverageDir(service, dir) {
     const names = await listReportFiles(dir);
@@ -68,12 +101,13 @@ export async function readCoverageDir(service, dir) {
         return {
             service,
             reports: [],
-            error: `service "${service}" opted in to coverage but ${COVERAGE_CONTAINER_DIR}/ holds no report — the service (or its coverage command) must write an lcov file there`,
+            error: `service "${service}" opted in to coverage but ${COVERAGE_CONTAINER_DIR}/ holds no report — the service (or its coverage command) must write an lcov or V8 coverage JSON file there`,
         };
     }
     const reports = [];
     let total = 0;
-    let anyLcov = false;
+    let anyReport = false;
+    const malformed = [];
     for (const name of names) {
         let content;
         try {
@@ -87,18 +121,20 @@ export async function readCoverageDir(service, dir) {
             return {
                 service,
                 reports: [],
-                error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — reports must be cumulative, not one file per dump`,
+                error: `service "${service}" has more than ${COVERAGE_MAX_BYTES_PER_SERVICE >> 20} MiB of reports in ${COVERAGE_CONTAINER_DIR}/ — that is a runaway, not coverage`,
             };
         }
-        if (hasLcovSourceFile(content))
-            anyLcov = true;
+        if (isWellFormedReport(content))
+            anyReport = true;
+        else
+            malformed.push(name);
         reports.push({ name, content });
     }
-    if (!anyLcov) {
+    if (!anyReport || malformed.length > 0) {
         return {
             service,
             reports,
-            error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but none holds an lcov \`SF:\` record — only lcov reports are read`,
+            error: `service "${service}" wrote ${reports.length} file(s) to ${COVERAGE_CONTAINER_DIR}/ but ${anyReport ? `${malformed.slice(0, 5).join(", ")} ${malformed.length === 1 ? "is" : "are"} neither` : "none is"} an lcov report or a V8 coverage JSON document — only those two formats are read`,
         };
     }
     return { service, reports };

package/dist/index.d.ts

@@ -20,6 +20,8 @@ export type { Mobile, MobileApp } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
 export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 import type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
+export { type CoverageAdapter, type CoverageCaptureContext, type CoverageConfigureInfo, type CoverageLoadContext, type ServiceCoverage, } from "./coverage.js";
+import { type ServiceCoverage } from "./coverage.js";
 export { certificate, dnsName, proxy, provides, lowerIngress, isWildcard, SELF_SERVICE_TOKEN, } from "./ingress.js";
 export type { CertificateDecl, DnsDecl, ProxyDecl, IngressDecl, DnsTarget, LoweredIngress, } from "./ingress.js";
 import type { DnsTarget } from "./ingress.js";
@@ -119,20 +121,24 @@ export interface ServiceConfig {
      * Opt this service in to **code coverage collection** (experimental).
      *
      * The service gets a writable directory bind-mounted at
-     * `/spectest/coverage/`. The service's own coverage tool writes **lcov**
-     * reports there — cumulative from process start, never reset. After
-     * bring-up and after every test, spectest runs `command` (if given) inside
-     * the container, then reads every file in the directory and records the
-     * set of source files that ran. Only the `SF:` records are read.
+     * `/spectest/coverage/`. After bring-up and after every test, spectest
+     * reads every file in it — **lcov** or **V8 coverage JSON**, verbatim —
+     * and stores them with the test; the control plane derives what ran.
      *
-     * - `true`: the service writes its reports by itself (a dump on a timer,
-     *   an exit-time dump for short-lived processes).
-     * - `{ command }`: run this (via `sh -c`) in the container to make the
-     *   service write a report, before the directory is read.
+     * - `true`: the program writes its own reports there (an exit-time dump
+     *   for a short-lived process, a dump on a timer, its own hook).
+     * - `{ adapters: [...] }`: spectest gets the reports out. From
+     *   `@specific.dev/spectest/coverage`: `node()` (V8 JSON from a node
+     *   service, through a hook spectest mounts), `browser()` (the frontend
+     *   this service serves, collected from the guest browser),
+     *   `command(cmd)` (run a command in the container first), or your own
+     *   via `defineAdapter`.
      *
-     * The directory must hold at least one lcov report each time it is read;
-     * an empty directory or a failed command fails the test with a clear
-     * error, so a hole in the coverage data is never silent. See
+     * The directory must hold at least one well-formed report each time it
+     * is read; an empty directory or a failing adapter fails the test with a
+     * clear error, so a hole in the coverage data is never silent. Reports
+     * accumulate along the test's ancestor chain by themselves (the
+     * directory forks with the environment). See
      * `spectest docs /services/coverage`.
      */
     coverage?: ServiceCoverage;
@@ -663,29 +669,6 @@ export type ServiceImage = {
     /** Extra glob patterns to exclude from the build context. */
     exclude?: readonly string[];
 };
-/**
- * A service's opt-in to coverage collection — see `ServiceConfig.coverage`.
- * `true` when the service writes its own reports; `{ command }` when
- * spectest must run a command in the container to produce one.
- */
-export type ServiceCoverage = true | {
-    /** 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 {
     /**
      * Named shared volume. Two services mounting the same `name` share one
@@ -898,17 +881,6 @@ export interface FakeContext {
      *  for a TLS-provisioning provider hands back to the app under test. */
     certificate(hostnames: readonly string[]): Promise<CertificateMaterial>;
 }
-/**
- * Check one service's `coverage` field. Exported so the daemon applies the
- * 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

@@ -40,6 +40,7 @@ export { McpHttpError, McpRpcError, McpAuthDeniedError, } from "./mcp.js";
 import { isLocator, getLocatorProbe, isBrowserSession, getBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, } from "./locator.js";
 import { formatWaited, locatorFailureMessage } from "./locator-errors.js";
 import { describeUrlPattern, matchesUrl } from "./url-match.js";
+import { applyCoverageAdapters, validateCoverage } from "./coverage.js";
 // Low-level ingress primitives + the framework lowering that the friendly
 // `tls` / `hostnames` fields and `defineFake(...)` are built on. See
 // `ingress.ts`.
@@ -215,37 +216,6 @@ function expandServiceGroups(input) {
     }
     return out;
 }
-/**
- * Check one service's `coverage` field. Exported so the daemon applies the
- * same rule to a runtime `startService` spec.
- */
-export function validateCoverage(service, cov) {
-    if (cov === undefined || cov === true)
-        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\`, \`{ 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);
     const serviceNames = new Set(entries.map(([n]) => n));
@@ -353,9 +323,13 @@ export function defineEnvironment(input) {
     // { name, services, timeoutSecs } — with plain, fully-expanded services —
     // is stored as `config` and shipped to the control plane.
     const { fakes, services: rawServices, ...rest } = input;
+    const expanded = expandServiceGroups(rawServices);
+    for (const [key, svc] of Object.entries(expanded)) {
+        expanded[key] = applyCoverageAdapters(key, svc);
+    }
     const config = {
         ...rest,
-        services: expandServiceGroups(rawServices),
+        services: expanded,
     };
     validateEnvironmentConfig(config);
     if (fakes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,6 +16,11 @@
       "bun": "./src/components/index.ts",
       "default": "./dist/components/index.js"
     },
+    "./coverage": {
+      "types": "./dist/coverage.d.ts",
+      "bun": "./src/coverage.ts",
+      "default": "./dist/coverage.js"
+    },
     "./browser": {
       "types": "./dist/browser.d.ts",
       "bun": "./src/browser.ts",