@specific.dev/spectest 0.56.2 → 0.58.0

package/src/index.ts

@@ -252,6 +252,27 @@ export interface ServiceConfig {
   tls?: readonly ServiceTls[];
   /** Bind-mounted volumes for state that survives snapshot/fork. */
   volumes?: readonly VolumeMount[];
+  /**
+   * 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.
+   *
+   * - `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.
+   *
+   * 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
+   * `spectest docs /services/coverage`.
+   */
+  coverage?: ServiceCoverage;
   /**
    * Files seeded into the container's filesystem **before it starts**.
    * Each entry's `content` is written to a VM-host staging path and
@@ -1017,6 +1038,32 @@ export type ServiceImage =
       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
@@ -1236,6 +1283,39 @@ export interface FakeContext {
   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 function validateCoverage(service: string, cov: unknown): void {
+  if (cov === undefined || cov === true) 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\`, \`{ 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 {
@@ -1281,6 +1361,7 @@ function validateEnvironmentConfig<S extends ServicesMap>(
         );
       }
     }
+    validateCoverage(name, svc.coverage);
     for (const raw of svc.hostnames ?? []) {
       const h = raw.toLowerCase();
       if (!HOSTNAME_RE.test(hostPatternBody(h))) {