@specific.dev/spectest 0.57.0 → 0.58.0

package/src/daemon.ts

@@ -33,6 +33,8 @@ import {
   isWildcard,
   proxy as makeProxyDecl,
   validateCoverage,
+  coverageUsesBrowser,
+  coverageUsesContainer,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
 import {
@@ -42,8 +44,14 @@ import {
   encodeCoverageBundle,
   readCoverageDir,
   type CoverageBundleRef,
+  type CoverageReport,
   type ServiceCoverageCapture,
 } 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
@@ -777,6 +785,9 @@ async function ensureVolumes(svc: NamedService): Promise<string[]> {
 async function ensureCoverage(svc: NamedService): Promise<string[]> {
   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);
@@ -1802,6 +1813,7 @@ function buildIngress(project: Project): void {
   // 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)) {
     FAKES.set(name, {
@@ -3601,6 +3613,35 @@ async function captureServiceLogDeltas(): Promise<ServiceLogDelta[]> {
 
 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: Project): void {
+  const env = project.environment;
+  const browserServices = new Set<string>();
+  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: string): string | undefined {
+      const svc = hostToService(host, all, table);
+      return svc && browserServices.has(svc) ? svc : undefined;
+    },
+  });
+}
+
 async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   const l = loaded;
   if (!l) return [];
@@ -3608,24 +3649,48 @@ async function captureServiceCoverage(): Promise<ServiceCoverageCapture[]> {
   for (const s of namedServices(l.project.environment)) byName.set(s.name, s);
   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): Promise<ServiceCoverageCapture> => {
       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: CoverageReport[] = [];
+      // 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/src/harness/browser-coverage.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeSourceMap,
+  decodeVlq,
+  isForeignSource,
+  lcovDocument,
+  mapToOriginal,
+  mergeFileCounts,
+  normalizeSourcePath,
+  rangesToLineCounts,
+  serviceForHost,
+} from "./browser-coverage";
+
+describe("rangesToLineCounts", () => {
+  test("outer range sets lines, narrower ranges override, blanks dropped", () => {
+    const src = "function f() {\n  if (x) {\n    a();\n  }\n\n  b();\n}\n";
+    const fnRange = { startOffset: 0, endOffset: src.length, count: 3 };
+    const ifBlock = { startOffset: src.indexOf("{\n    a"), endOffset: src.indexOf("}\n\n") + 1, count: 0 };
+    const counts = rangesToLineCounts(src, [{ ranges: [fnRange, ifBlock] }]);
+    expect(counts.get(1)).toBe(3);
+    expect(counts.get(3)).toBe(0);
+    expect(counts.get(6)).toBe(3);
+    expect(counts.has(5)).toBe(false);
+  });
+});
+
+describe("source maps", () => {
+  test("decodeVlq", () => {
+    expect(decodeVlq("AAAA")).toEqual([0, 0, 0, 0]);
+    expect(decodeVlq("IACC")).toEqual([4, 0, 1, 1]);
+    expect(decodeVlq("D")).toEqual([-1]);
+  });
+
+  test("decode + map generated lines onto original files", () => {
+    // Two generated lines: line 1 maps to src/a.ts:1 and node_modules/x.js:1,
+    // line 2 maps to src/b.ts:5 (columns irrelevant for line attribution).
+    const map = decodeSourceMap({
+      version: 3,
+      sources: ["webpack:///./src/a.ts", "webpack:///./node_modules/x.js", "./src/b.ts"],
+      mappings: "AAAA,ICAA;ACIA",
+    });
+    expect(map).not.toBeNull();
+    expect(map!.sources).toEqual(["src/a.ts", "node_modules/x.js", "src/b.ts"]);
+    const files = mapToOriginal(map!, new Map([[1, 2], [2, 0]]));
+    expect([...files.keys()]).toEqual(["src/a.ts", "src/b.ts"]);
+    expect(files.get("src/a.ts")!.get(1)).toBe(2);
+    expect(files.get("src/b.ts")!.get(5)).toBe(0);
+  });
+
+  test("index maps and garbage decode to null", () => {
+    expect(decodeSourceMap({ version: 3, sections: [] })).toBeNull();
+    expect(decodeSourceMap({ version: 3, sources: ["a"], mappings: "!!" })).toBeNull();
+    expect(decodeSourceMap("nope")).toBeNull();
+  });
+
+  test("normalizeSourcePath strips schemes, roots and queries", () => {
+    expect(normalizeSourcePath("webpack:///./src/a.ts")).toBe("src/a.ts");
+    expect(normalizeSourcePath("http://app.test/src/a.ts?t=1")).toBe("/src/a.ts");
+    expect(normalizeSourcePath("/@fs/repo/src/a.ts")).toBe("/repo/src/a.ts");
+    expect(normalizeSourcePath("a.ts", "/app/src")).toBe("/app/src/a.ts");
+    expect(normalizeSourcePath("file:///app/src/a.ts")).toBe("/app/src/a.ts");
+    expect(isForeignSource("webpack/bootstrap")).toBe(true);
+    expect(isForeignSource("src/a.ts")).toBe(false);
+  });
+});
+
+test("lcovDocument is sorted, one record per file, merge sums", () => {
+  const files = new Map([["b.js", new Map([[2, 1]])], ["a.js", new Map([[1, 0], [3, 2]])]]);
+  mergeFileCounts(files, new Map([["a.js", new Map([[3, 1]])]]));
+  expect(lcovDocument(files)).toBe(
+    "TN:\nSF:a.js\nDA:1,0\nDA:3,3\nLF:2\nLH:1\nend_of_record\nSF:b.js\nDA:2,1\nLF:1\nLH:1\nend_of_record\n",
+  );
+});
+
+describe("serviceForHost", () => {
+  const table = {
+    proxies: [{ hostname: "app.test", service: "web" }],
+    aliasesByService: { api: ["api.todos.local"] },
+    wildcards: [
+      { pattern: "*.apps.test", target: { service: "k8s" } },
+      { pattern: "*.fake.test", target: { ingress: true } },
+    ],
+  };
+  const services = ["web", "api", "k8s"];
+  test("service key, .internal, alias, proxy, wildcard", () => {
+    expect(serviceForHost("web", services, table)).toBe("web");
+    expect(serviceForHost("WEB.internal", services, table)).toBe("web");
+    expect(serviceForHost("api.todos.local", services, table)).toBe("api");
+    expect(serviceForHost("app.test", services, table)).toBe("web");
+    expect(serviceForHost("a.b.apps.test", services, table)).toBe("k8s");
+    expect(serviceForHost("x.fake.test", services, table)).toBeUndefined();
+    expect(serviceForHost("example.com", services, table)).toBeUndefined();
+  });
+});

package/src/harness/browser-coverage.ts

@@ -0,0 +1,310 @@
+// 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`.
+
+/** 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>;
+
+// ── V8 precise coverage → generated line counts ─────────────────────────
+
+/** Byte offset at which each line starts. */
+export function lineStartsOf(source: string): number[] {
+  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: number[], offset: number): number {
+  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;
+}
+
+/** 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 function rangesToLineCounts(
+  source: string,
+  functions: readonly V8FunctionCoverage[],
+): LineCounts {
+  const starts = lineStartsOf(source);
+  const counts: LineCounts = 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;
+}
+
+// ── Source maps ─────────────────────────────────────────────────────────
+
+/** 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[][];
+}
+
+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: string): number[] {
+  const out: number[] = [];
+  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: string, sourceRoot?: string): string {
+  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: string): boolean {
+  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: unknown): DecodedSourceMap | null {
+  if (!doc || typeof doc !== "object") return null;
+  const m = doc as {
+    version?: number;
+    sources?: unknown;
+    sourceRoot?: unknown;
+    mappings?: unknown;
+    sections?: unknown;
+  };
+  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: Segment[][] = [];
+  let src = 0;
+  let line = 0;
+  try {
+    for (const group of m.mappings.split(";")) {
+      const segs: Segment[] = [];
+      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: DecodedSourceMap, generated: LineCounts): FileCounts {
+  const out: FileCounts = 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: LineCounts, from: LineCounts): void {
+  for (const [l, c] of from) into.set(l, (into.get(l) ?? 0) + c);
+}
+
+export function mergeFileCounts(into: FileCounts, from: FileCounts): void {
+  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: FileCounts): string {
+  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;
+}
+
+// ── Host → service ──────────────────────────────────────────────────────
+
+/** 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 function serviceForHost(
+  host: string,
+  services: readonly string[],
+  table: HostTable,
+): string | undefined {
+  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: { len: number; service: string } | undefined;
+  for (const w of table.wildcards) {
+    const service = (w.target as { service?: string }).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/src/index.ts

@@ -1043,7 +1043,26 @@ export type ServiceImage =
  * `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 | { command: string };
+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 {
   /**
@@ -1270,19 +1289,33 @@ export interface FakeContext {
  */
 export function validateCoverage(service: string, cov: unknown): void {
   if (cov === undefined || cov === true) return;
-  if (
-    typeof cov === "object" &&
-    cov !== null &&
-    typeof (cov as { command?: unknown }).command === "string" &&
-    (cov as { command: string }).command.trim().length > 0
-  ) {
-    return;
+  if (typeof cov === "object" && cov !== null) {
+    const o = cov as { command?: unknown; browser?: unknown };
+    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>" }\``,
+    `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: ServiceCoverage | undefined): boolean {
+  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: ServiceCoverage | undefined): boolean {
+  return typeof cov === "object" && cov.browser === true;
+}
+
 function validateEnvironmentConfig<S extends ServicesMap>(
   config: EnvironmentConfig<S>,
 ): void {