@specific.dev/spectest 0.127.0 → 0.129.0

package/src/browser-navigation.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from "bun:test";
+import { openBrowser } from "./browser.js";
+import { startRecording, stopRecording } from "./recorder.js";
+
+const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"));
+
+test.skipIf(!available)("public navigation options control goto/reload and remain visible in recordings", async () => {
+  // The document commits immediately but load waits for an image. This
+  // distinguishes waitUntil behavior from simply extending a deadline.
+  const server = Bun.serve({port:0,hostname:"127.0.0.1", async fetch(request) {
+    if (new URL(request.url).pathname === "/slow.png") {
+      await Bun.sleep(500);
+      return new Response("", {status:404});
+    }
+    return new Response('<title>Navigation options</title><img src="/slow.png">',
+      {headers:{"content-type":"text/html","cache-control":"no-store"}});
+  }});
+  const browser = await openBrowser({recorder:{sessionId:"navigation",recordStep() {}}});
+  startRecording();
+  try {
+    await browser.goto(server.url.href, {waitUntil:"domcontentloaded",timeout:2000});
+    expect(await browser.title()).toBe("Navigation options");
+    await expect(browser.reload({waitUntil:"load",timeout:50})).rejects.toThrow(/Timeout/);
+    await browser.reload({waitUntil:"load",timeout:2000});
+    const events = stopRecording().filter(e => e.kind === "browser");
+    expect(events.filter(e => e.action === "goto" || e.action === "reload")).toMatchObject([
+      {action:"goto",waitUntil:"domcontentloaded",timeout:2000},
+      {action:"reload",waitUntil:"load",timeout:50,error:expect.any(String)},
+      {action:"reload",waitUntil:"load",timeout:2000},
+    ]);
+  } finally {
+    stopRecording();
+    await browser.close();
+    server.stop(true);
+  }
+}, 15000);

package/src/browser.ts

@@ -208,6 +208,12 @@ export interface Mouse {
   wheel(dx: number, dy: number): Promise<void>;
 }
 
+export interface NavigationOptions {
+  /** Playwright navigation timeout in milliseconds; 0 disables the deadline. */
+  timeout?: number;
+  waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+}
+
 /**
  * Headless browser session — Playwright `Page`-shaped. Select elements with
  * the `getBy*`/`locator` roots (returning a {@link Locator}) and act on them;
@@ -220,14 +226,14 @@ export interface Browser {
   url(): string;
   /** Current page `<title>` (async, like Playwright's `page.title()`). */
   title(): Promise<string>;
-  /** Navigate to a URL; resolves when the main frame's load completes. */
-  goto(url: string): Promise<void>;
+  /** Navigate to a URL; waits for the main frame load unless waitUntil is supplied. */
+  goto(url: string, options?: NavigationOptions): Promise<void>;
   /** Navigate back in session history. */
-  goBack(): Promise<void>;
+  goBack(options?: NavigationOptions): Promise<void>;
   /** Navigate forward in session history. */
-  goForward(): Promise<void>;
+  goForward(options?: NavigationOptions): Promise<void>;
   /** Reload the current page. */
-  reload(): Promise<void>;
+  reload(options?: NavigationOptions): Promise<void>;
 
   readonly keyboard: Keyboard;
   readonly mouse: Mouse;
@@ -1995,11 +2001,11 @@ function buildBackend(
     keyboard,
     mouse,
     touchscreen,
-    goto(url) {
+    goto(url, options) {
       recorder?.noteNavigation?.(url);
-      return instrumented("goto", { url }, async () => {
+      return instrumented("goto", { url, ...options }, async () => {
         try {
-          await holder.page.goto(url, { waitUntil: "load" });
+          await holder.page.goto(url, { waitUntil: "load", ...options });
         } catch (err) {
           // Restored-renderer DNS bug (see `rebuildView`): only when the
           // view is persistent (so it may have lived through a snapshot
@@ -2009,23 +2015,23 @@ function buildBackend(
           if (!buildOpts.persistent || !isNameNotResolved(err)) throw err;
           if (!(await daemonResolves(url))) throw err;
           await rebuildView(holder);
-          await holder.page.goto(url, { waitUntil: "load" });
+          await holder.page.goto(url, { waitUntil: "load", ...options });
         }
       });
     },
-    goBack() {
-      return instrumented("goBack", {}, async () => {
-        await holder.page.goBack();
+    goBack(options) {
+      return instrumented("goBack", { ...options }, async () => {
+        await holder.page.goBack(options);
       });
     },
-    goForward() {
-      return instrumented("goForward", {}, async () => {
-        await holder.page.goForward();
+    goForward(options) {
+      return instrumented("goForward", { ...options }, async () => {
+        await holder.page.goForward(options);
       });
     },
-    reload() {
-      return instrumented("reload", {}, async () => {
-        await holder.page.reload();
+    reload(options) {
+      return instrumented("reload", { ...options }, async () => {
+        await holder.page.reload(options);
       });
     },
 
@@ -2325,6 +2331,8 @@ function buildBackend(
 }
 
 export interface RecordableFields {
+  timeout: number;
+  waitUntil: NonNullable<NavigationOptions["waitUntil"]>;
   target: RecordedBrowserLocatorPart[];
   destinationTarget: RecordedBrowserLocatorPart[];
   url: string;

package/src/components/k3s-coverage.test.ts

@@ -0,0 +1,160 @@
+import { expect, test } from "bun:test";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { k3sCoverage } from "./k3s-coverage";
+import { k3s } from "./k3s";
+import { node, browser, rust, type CoverageAdapter } from "../coverage";
+import { defineEnvironment } from "../index";
+import type { Pod, Patch } from "./k3s-trust";
+import { podTrustPatch } from "./k3s-trust";
+
+function apply(pod: any, patches: Patch[]): any {
+  const out = structuredClone(pod);
+  for (const operation of patches) {
+    const keys = operation.path.slice(1).split("/");
+    const key = keys.pop()!;
+    const parent = keys.reduce((value, key) => value[key], out);
+    if (key === "-") parent.push(operation.value); else parent[key] = operation.value;
+  }
+  return out;
+}
+const digest = `images.test/api@sha256:${"a".repeat(64)}`;
+const image = { reference: "images.test/api:test", content: "FROM node:24", coverage: { adapters: [node({ sourceRoot: "packages" })] } };
+const dependencies = {
+  image: async () => ({ aliases: [digest], root: "/app", env: { NODE_OPTIONS: "--max-old-space-size=512" } }),
+  files: async () => {},
+};
+
+test("admission recognizes prepared digest, preserves trust/user settings, covers init containers, and is idempotent", async () => {
+  const coverage = k3sCoverage([image]);
+  const pod = { metadata: { name: "api", annotations: { other: "value" } }, spec: {
+    containers: [{ name: "api", image: digest, env: [{ name: "FOO", value: "bar" }], securityContext: { runAsUser: 1000, readOnlyRootFilesystem: true } },
+      { name: "db", image: "postgres:17" }], initContainers: [{ name: "migrate", image: image.reference }],
+  } };
+  const trusted = apply(pod, podTrustPatch(pod, "ca-bundle"));
+  const patches = await coverage.mutate("k8s", trusted, "app", true, false, "admission", dependencies);
+  const result = apply(trusted, patches);
+  expect(result.spec.containers[0].image).toBe(digest);
+  expect(result.spec.containers[0].securityContext).toEqual(pod.spec.containers[0].securityContext);
+  expect(result.spec.containers[0].env).toContainEqual({ name: "NODE_OPTIONS", value: "--max-old-space-size=512 --require /spectest/coverage-hook.cjs" });
+  expect(result.spec.containers[0].env).toContainEqual({ name: "FOO", value: "bar" });
+  expect(result.spec.containers[0].volumeMounts.some((m: any) => m.mountPath === "/spectest/ca-bundle.crt")).toBe(true);
+  expect(result.spec.containers[1]).toEqual(trusted.spec.containers[1]);
+  const ids = JSON.parse(result.metadata.annotations["spectest.dev/coverage"]).instances;
+  expect(new Set(ids).size).toBe(2);
+  expect(await coverage.mutate("k8s", result, "app", true, false, "admission", dependencies)).toEqual([]);
+  await expect(coverage.mutate("k8s", result, "app", true, false, "another-pod", dependencies)).rejects.toThrow("inherited");
+  expect(await coverage.mutate("k8s", trusted, "app", true, true, "ephemeral", dependencies)).toEqual([]);
+  const other = structuredClone(pod);
+  other.spec.containers[0].image = `images.test/api@sha256:${"b".repeat(64)}`;
+  other.spec.initContainers = [];
+  expect(await coverage.mutate("k8s", other, "app", true, false, "other", dependencies)).toEqual([]);
+});
+
+test("coverage refuses colliding mounts and dynamic NODE_OPTIONS", async () => {
+  const coverage = k3sCoverage([image]);
+  for (const extra of [{ volumeMounts: [{ name: "user", mountPath: "/spectest" }] }, { env: [{ name: "NODE_OPTIONS", valueFrom: { secretKeyRef: { name: "options", key: "flags" } } }] }]) {
+    const pod = { metadata: {}, spec: { containers: [{ name: "api", image: digest, ...extra }] } };
+    await expect(coverage.mutate("k8s", pod as Pod, "app", true, false, "id", dependencies)).rejects.toThrow();
+  }
+});
+
+test("k3s mounts fork-local storage on every node and preserves image collectors when browser coverage is added", () => {
+  const environment = defineEnvironment({ name: "coverage", services: { k8s: {
+    ...k3s({ nodes: 3, images: [image], ingressDomains: ["app.test"] }),
+    coverage: { adapters: [browser()] },
+  } } });
+  const services = environment.config.services;
+  for (const service of Object.values(services)) {
+    const volume = service.volumes?.find(v => v.target === "/spectest/pod-coverage");
+    expect(volume?.source).toEndWith("/.spectest/coverage/k8s");
+    expect(volume?.reachExempt).toBe(true);
+  }
+  const wire = JSON.parse(JSON.stringify(services.k8s));
+  expect(wire.coverage.adapters.map((a: any) => a.adapter)).toEqual(["k3s-containers", "browser"]);
+  expect(wire.coverage.adapters[0].images[0].config.env.NODE_OPTIONS).toContain("--require");
+  expect(wire.imageBuilds[0].image.coverage).toBeUndefined();
+  const changed = defineEnvironment({ name: "coverage", services: { k8s: k3s({ images: [{ ...image, coverage: { adapters: [rust()] } }] }) } });
+  expect(JSON.stringify(changed.config)).not.toBe(JSON.stringify(environment.config));
+});
+
+test("replica counters are independent, reports survive pod deletion, and capture errors remain visible", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "k3s-cov-"));
+  try {
+    const adapter: CoverageAdapter = { name: "lcov", reports: "cumulative", sourceOptions: { sourceRoot: "packages" }, ownsReport: n => n.endsWith(".lcov"),
+      async inventory(ctx) { await ctx.exec("inventory-probe"); return ["npm:api@1.0.0", "npm:unused@2.0.0"]; },
+    };
+    const coverage = k3sCoverage([{ ...image, coverage: { adapters: [adapter] } }]);
+    const ids = ["a".repeat(16), "b".repeat(16)];
+    for (const id of ids) {
+      const dir = path.join(root, ".pods", id);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(path.join(dir, ".instance.json"), JSON.stringify({ id, image: image.reference, container: "api", namespace: "app", root: "/app" }));
+      await fs.writeFile(path.join(dir, "app.lcov"), "TN:\nSF:/app/src/api.ts\nDA:1,2\nend_of_record\n");
+    }
+    let pods = ids.map(id => ({ metadata: { name: `api-${id}`, annotations: { "spectest.dev/coverage": JSON.stringify({ instances: [id] }) } },
+      status: { containerStatuses: [{ name: "api", state: { running: {} } }] } }));
+    const commands: string[] = [];
+    const ctx = { service: "k8s", reportDir: root, signal: AbortSignal.timeout(5000), exec: async (command: string) => {
+      commands.push(command); return { stdout: command.startsWith("kubectl get") ? JSON.stringify({ items: pods }) : "", stderr: "" };
+    },
+      projectFiles: async () => [], readProjectFile: async () => null, writeReport: async () => {} };
+    const first = await coverage.adapter().collect!(ctx, true);
+    expect(first).toHaveLength(1);
+    expect(first[0].error).toBeUndefined();
+    expect(first[0].reports).toHaveLength(3);
+    expect(first[0].reports.filter(r => r.name.endsWith(".lcov")).every(r => r.sourceOptions?.sourceRoot === "packages")).toBe(true);
+    // The consumer recognizes this exact name; per-replica prefixes would hide it.
+    expect(first[0].reports.find(r => r.name === "inventory.units")?.content).toBe("npm:api@1.0.0\nnpm:unused@2.0.0");
+    expect(commands.filter(command => command.includes("inventory-probe")).sort()).toEqual(ids.map(id => `kubectl exec -n 'app' 'api-${id}' -c 'api' -- sh -c 'inventory-probe'`));
+    expect(commands.filter(command => command.startsWith("kubectl get"))).toHaveLength(1);
+    // No pod exists any longer. Reports remain on fork-local node storage.
+    pods = [];
+    commands.length = 0;
+    await fs.writeFile(path.join(root, ".pods", ids[1], "app.lcov"), "TN:\nSF:/app/src/api.ts\nDA:1,3\nend_of_record\n");
+    const next = await coverage.adapter().collect!(ctx, false);
+    expect(next[0].reports[0].content).toBe("TN:\n");
+    expect(next[0].reports[1].content).toContain("DA:1,1");
+    expect(commands).toEqual([]); // Native collection needs neither API discovery nor exec.
+    await fs.writeFile(path.join(root, ".pods", ids[0], "failed.txt"), "lost report");
+    expect((await coverage.adapter().collect!(ctx, false))[0].error).toContain("neither");
+  } finally { await fs.rm(root, { recursive: true, force: true }); }
+});
+
+test("collection bounds parallel targets and shares lazy discovery for command adapters", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "k3s-cov-parallel-"));
+  try {
+    let active = 0;
+    let peak = 0;
+    let release!: () => void;
+    const gate = new Promise<void>(resolve => { release = resolve; });
+    const adapter: CoverageAdapter = { name: "command", async capture(ctx) {
+      peak = Math.max(peak, ++active);
+      if (active === 8) release();
+      await gate;
+      await ctx.exec("capture-probe");
+      await ctx.writeReport("app.lcov", "TN:\nSF:/app/main.rs\nDA:1,1\nend_of_record\n");
+      active--;
+    } };
+    const ids = Array.from({ length: 11 }, (_, index) => index.toString(16).padStart(16, "0"));
+    for (const id of ids) {
+      const dir = path.join(root, ".pods", id);
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(path.join(dir, ".instance.json"), JSON.stringify({ id, image: image.reference, container: "api", namespace: "app", root: "/app" }));
+    }
+    const pods = ids.map(id => ({ metadata: { name: `api-${id}`, annotations: { "spectest.dev/coverage": JSON.stringify({ instances: [id] }) } },
+      status: { containerStatuses: [{ name: "api", state: { running: {} } }] } }));
+    const commands: string[] = [];
+    const ctx = { service: "k8s", reportDir: root, signal: AbortSignal.timeout(5000), exec: async (command: string) => {
+      commands.push(command); return { stdout: command.startsWith("kubectl get") ? JSON.stringify({ items: pods }) : "", stderr: "" };
+    }, projectFiles: async () => [], readProjectFile: async () => null, writeReport: async () => {} };
+    const capture = (await k3sCoverage([{ ...image, coverage: { adapters: [adapter] } }]).adapter().collect!(ctx, false))[0];
+    expect(capture.error).toBeUndefined();
+    expect(capture.reports.map(report => report.name)).toEqual(ids.map(id => `${id}/app.lcov`));
+    expect(active).toBe(0);
+    expect(peak).toBe(8);
+    expect(commands.filter(command => command.startsWith("kubectl get"))).toHaveLength(1);
+    expect(commands.filter(command => command.includes("capture-probe"))).toHaveLength(11);
+  } finally { await fs.rm(root, { recursive: true, force: true }); }
+}, 10000);

package/src/components/k3s-coverage.ts

@@ -0,0 +1,234 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { applyCoverageAdapters, coverageAdapters, type CoverageAdapter, type ServiceCoverage } from "../coverage.js";
+import { coverageHostDir, COVERAGE_MAX_BYTES_PER_SERVICE, type ServiceCoverageCapture } from "../harness/coverage.js";
+import { captureCoverageTarget } from "../harness/coverage-target.js";
+import { canonicalImageReference, type KubernetesImage } from "../harness/component-images.js";
+import type { ServiceConfig } from "../index.js";
+import { WORKSPACE } from "../project-files.js";
+import type { Patch, Pod } from "./k3s-trust.js";
+
+const MOUNT = "/spectest/pod-coverage";
+const ANNOTATION = "spectest.dev/coverage";
+const hash = (value: string) => createHash("sha256").update(value).digest("hex").slice(0, 16);
+const quote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
+interface ImageInfo { aliases: string[]; root: string; env: Record<string, string> }
+interface Instance { id: string; image: string; container: string; root: string; namespace: string }
+interface Container {
+  name: string; image: string; workingDir?: string;
+  env?: { name: string; value?: string; valueFrom?: unknown }[];
+  volumeMounts?: { name: string; mountPath: string; [key: string]: unknown }[];
+}
+interface CoveragePod {
+  metadata?: { name?: string; annotations?: Record<string, string> };
+  spec?: { containers?: Container[]; initContainers?: Container[]; volumes?: { name: string; [key: string]: unknown }[] };
+  status?: { containerStatuses?: { name: string; state?: { running?: unknown } }[]; initContainerStatuses?: { name: string; state?: { running?: unknown } }[] };
+}
+export interface K3sCoverageDependencies {
+  image(reference: string): Promise<ImageInfo>;
+  files(namespace: string, name: string, data: Record<string, string>): Promise<void>;
+}
+
+/** One component-owned bridge; runtime adapters remain unaware of Kubernetes. */
+export function k3sCoverage(images: readonly KubernetesImage[]) {
+  const declarations = images.flatMap(image => typeof image === "string" || image.coverage === undefined ? [] : [{
+    reference: canonicalImageReference(image.reference), coverage: image.coverage,
+  }]);
+  for (const image of declarations) {
+    const adapters = coverageAdapters(image.coverage);
+    if (adapters.some(adapter => adapter.load || adapter.collect)) throw new Error("k3s image coverage accepts container adapters; put browser coverage on the cluster service");
+    applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage });
+  }
+  const metadata = new Map<string, ImageInfo>();
+  const service = (cluster: string, reference: string) => `${cluster}/image-${hash(reference)}`;
+  return {
+    enabled: declarations.length > 0,
+    volume(cluster: string) {
+      return { source: coverageHostDir(WORKSPACE, cluster), target: MOUNT, reachExempt: true };
+    },
+    async mutate(cluster: string, podInput: Pod, namespace: string, dryRun: boolean, ephemeral: boolean, uid: string, deps: K3sCoverageDependencies): Promise<Patch[]> {
+      if (!declarations.length || ephemeral) return [];
+      const pod = podInput as CoveragePod;
+      if (!pod.spec) return [];
+      const existing = pod.metadata?.annotations?.[ANNOTATION];
+      if (existing) {
+        if (JSON.parse(existing).admission === uid) return [];
+        throw new Error("remove inherited spectest.dev/coverage annotations before creating another Pod");
+      }
+      const patch: Patch[] = [];
+      const volumes = [...(pod.spec.volumes ?? [])];
+      const instances: Instance[] = [];
+      const namedVolume = (stem: string, volume: Record<string, unknown>) => {
+        let name = stem;
+        for (let i = 1; volumes.some(v => v.name === name); i++) name = `${stem}-${i}`;
+        volumes.push({ name, ...volume }); return name;
+      };
+      for (const group of ["initContainers", "containers"] as const) {
+        for (const [index, container] of (pod.spec[group] ?? []).entries()) {
+          const requested = canonicalImageReference(container.image);
+          let declaration = declarations.find(image => image.reference === requested);
+          // Tangent deploys the prepared image by digest. Resolve aliases from
+          // CRI's actual image record, never by stripping a repository tag.
+          if (!declaration && requested.includes("@")) {
+            for (const candidate of declarations) {
+              let info = metadata.get(candidate.reference);
+              if (!info) metadata.set(candidate.reference, info = await deps.image(candidate.reference));
+              if (info.aliases.includes(requested)) { declaration = candidate; break; }
+            }
+          }
+          if (!declaration) continue;
+          let info = metadata.get(declaration.reference);
+          if (!info) metadata.set(declaration.reference, info = await deps.image(declaration.reference));
+          const id = hash(`${uid}/${group}/${container.name}`);
+          const name = service(cluster, declaration.reference);
+          const env = { ...info.env };
+          for (const entry of container.env ?? []) if (entry.value !== undefined) env[entry.name] = entry.value;
+          const configured = applyCoverageAdapters<ServiceConfig>(name, { image: { type: "registry", reference: container.image }, env, coverage: declaration.coverage });
+          if (Object.keys(configured).some(key => !["image", "env", "coverage", "files"].includes(key))) {
+            throw new Error("Kubernetes coverage adapters may inject env and files only; configure the workload's command and mounts in its manifest");
+          }
+          const changed = Object.entries(configured.env ?? {}).filter(([key, value]) => env[key] !== value);
+          for (const [key] of changed) if (container.env?.some(e => e.name === key && e.valueFrom)) throw new Error(`cannot inject coverage into dynamic ${key}`);
+          const mounts = [...(container.volumeMounts ?? [])];
+          const addMount = (mountPath: string, mount: Record<string, unknown>) => {
+            if (mounts.some(m => mountPath === m.mountPath || mountPath.startsWith(m.mountPath.replace(/\/$/, "") + "/"))) throw new Error(`coverage mount conflicts with ${mountPath}`);
+            mounts.push({ mountPath, ...mount } as typeof mounts[number]);
+          };
+          const volume = namedVolume(`spectest-cov-${id}`, { hostPath: { path: `${MOUNT}/.pods/${id}`, type: "Directory" } });
+          addMount("/spectest/coverage", { name: volume });
+          const files = configured.files ?? [];
+          if (files.some(file => file.user !== undefined || file.group !== undefined || (file.mode !== undefined && !["444", "0444", "644", "0644"].includes(file.mode)))) {
+            throw new Error("Kubernetes coverage hook files must be world-readable and need no custom ownership");
+          }
+          if (files.length) {
+            const data = Object.fromEntries(files.map((file, index) => [`file${index}`, file.content]));
+            const configMap = `spectest-coverage-${hash(JSON.stringify(data))}`;
+            if (!dryRun) await deps.files(namespace, configMap, data);
+            const fileVolume = namedVolume(`spectest-hooks-${id}`, { configMap: { name: configMap, defaultMode: 0o444 } });
+            files.forEach((file, index) => addMount(file.path, { name: fileVolume, subPath: `file${index}`, readOnly: true }));
+          }
+          const instance: Instance = { id, image: declaration.reference, namespace, container: container.name, root: container.workingDir || info.root || "/" };
+          if (!dryRun) {
+            const dir = path.join(coverageHostDir(WORKSPACE, cluster), ".pods", id);
+            await fs.mkdir(dir, { recursive: true, mode: 0o777 });
+            await fs.chmod(dir, 0o777);
+            await fs.writeFile(path.join(dir, ".instance.json"), JSON.stringify(instance));
+          }
+          instances.push(instance);
+          patch.push({ op: "add", path: `/spec/${group}/${index}/env`, value: [
+            ...(container.env ?? []).filter(e => !changed.some(([key]) => key === e.name)),
+            ...changed.map(([name, value]) => ({ name, value })),
+          ] }, { op: "add", path: `/spec/${group}/${index}/volumeMounts`, value: mounts });
+        }
+      }
+      if (!instances.length) return [];
+      patch.push({ op: "add", path: "/spec/volumes", value: volumes });
+      patch.push({ op: "add", path: "/metadata/annotations", value: { ...pod.metadata?.annotations,
+        [ANNOTATION]: JSON.stringify({ admission: uid, instances: instances.map(i => i.id) }),
+      } });
+      return patch;
+    },
+    adapter(): CoverageAdapter {
+      return {
+        name: "k3s-containers",
+        // Include nested policy AND injected hooks in the warm identity. An
+        // adapter's functions would otherwise disappear from JSON.stringify.
+        toJSON() { return { adapter: "k3s-containers", images: declarations.map(image => ({
+          reference: image.reference,
+          config: applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage }),
+        })) }; },
+        async collect(ctx, baseline) {
+          const root = path.join(ctx.reportDir, ".pods");
+          let entries: string[];
+          try { entries = await fs.readdir(root); } catch (error: any) { if (error.code !== "ENOENT") throw error; entries = []; }
+          // Native adapters flush through the shared Unix sockets, including
+          // after Pod deletion. Only inventory or command adapters need the API.
+          let pods: Promise<CoveragePod[]> | undefined;
+          const findPod = async (id: string) => {
+            pods ??= ctx.exec("kubectl get pods -A -o json --request-timeout=10s")
+              .then(result => JSON.parse(result.stdout).items as CoveragePod[]);
+            return (await pods).find(p => {
+              const ids = p.metadata?.annotations?.[ANNOTATION];
+              return ids && (JSON.parse(ids).instances as string[]).includes(id);
+            });
+          };
+          const captures = new Map<string, ServiceCoverageCapture>();
+          const inventories = new Map<string, Set<string>>();
+          for (const declaration of declarations) captures.set(declaration.reference, { service: service(ctx.service, declaration.reference), reports: [] });
+          const collectInstance = async (id: string) => {
+            ctx.signal.throwIfAborted();
+            if (!/^[a-f0-9]{16}$/.test(id)) throw new Error("invalid coverage instance directory");
+            const dir = path.join(root, id);
+            const instance = JSON.parse(await fs.readFile(path.join(dir, ".instance.json"), "utf8")) as Instance;
+            const declaration = declarations.find(d => d.reference === instance.image);
+            if (!declaration) throw new Error(`coverage image no longer declared: ${instance.image}`);
+            const adapters = coverageAdapters(declaration.coverage);
+            const livePod = async () => {
+              const pod = await findPod(id);
+              const statuses = [...(pod?.status?.containerStatuses ?? []), ...(pod?.status?.initContainerStatuses ?? [])];
+              return statuses.some(status => status.name === instance.container && status.state?.running) ? pod : undefined;
+            };
+            for (const adapter of adapters) {
+              if (adapter.name === "node") {
+                try { await fs.access(path.join(dir, `.attached-${adapter.name}`)); }
+                catch { throw new Error(`coverage hook never attached to ${instance.namespace}/${instance.container} (${adapter.name})`); }
+              }
+            }
+            const captured = await captureCoverageTarget({
+              coverage: declaration.coverage, root: instance.root, baseline,
+              inventoryAvailable: baseline && adapters.some(a => a.inventory) ? !!await livePod() : false,
+              counterKey: `${service(ctx.service, instance.image)}/${id}`,
+              context: { ...ctx, service: service(ctx.service, instance.image), reportDir: dir,
+                exec: async command => {
+                  const pod = await livePod();
+                  if (!pod?.metadata?.name) throw new Error(`coverage command requires live container ${instance.container}`);
+                  return ctx.exec(`kubectl exec -n ${quote(instance.namespace)} ${quote(pod.metadata.name)} -c ${quote(instance.container)} -- sh -c ${quote(command)}`);
+                },
+              },
+            });
+            return { id, instance, captured };
+          };
+          // Bound simultaneous LLVM exports and API execs. Drain all workers
+          // even on error so no collector can race the following VM snapshot.
+          const pending = entries.sort();
+          const results = new Map<string, Awaited<ReturnType<typeof collectInstance>>>();
+          let cursor = 0;
+          const workers = await Promise.allSettled(Array.from({ length: Math.min(8, pending.length) }, async () => {
+            while (cursor < pending.length) {
+              const id = pending[cursor++];
+              results.set(id, await collectInstance(id));
+            }
+          }));
+          const failure = workers.find(worker => worker.status === "rejected");
+          if (failure?.status === "rejected") throw failure.reason;
+          for (const id of pending) {
+            const { instance, captured } = results.get(id)!;
+            const aggregate = captures.get(instance.image)!;
+            if (captured.error) aggregate.error = [aggregate.error, `${instance.namespace}/${instance.container}: ${captured.error}`].filter(Boolean).join("; ");
+            if (aggregate.root && aggregate.root !== instance.root) {
+              aggregate.error = "coverage containers from one image have different working directories; use a common workingDir for this image's covered containers";
+            }
+            aggregate.root = instance.root;
+            for (const report of captured.reports) {
+              if (report.name === "inventory.units") {
+                let units = inventories.get(instance.image);
+                if (!units) inventories.set(instance.image, units = new Set());
+                for (const unit of report.content.split("\n")) if (unit) units.add(unit);
+              } else aggregate.reports.push({ ...report, name: `${id}/${report.name}` });
+            }
+          }
+          for (const [image, units] of inventories) captures.get(image)!.reports.push({ name: "inventory.units", content: [...units].sort().join("\n") });
+          for (const capture of captures.values()) {
+            if (!capture.reports.length && !capture.error) capture.reports.push({ name: "empty.lcov", content: "TN:\n" });
+            if (capture.reports.reduce((bytes, report) => bytes + Buffer.byteLength(report.content), 0) > COVERAGE_MAX_BYTES_PER_SERVICE) {
+              capture.reports = [];
+              capture.error = "Kubernetes image coverage exceeds the per-service report size limit";
+            }
+          }
+          return [...captures.values()];
+        },
+      } as CoverageAdapter;
+    },
+  };
+}

package/src/components/k3s-trust.ts

@@ -14,7 +14,7 @@ interface Container {
   env?: { name: string; value?: string; valueFrom?: unknown }[];
   volumeMounts?: { name: string; mountPath: string; subPath?: string; readOnly?: boolean }[];
 }
-interface Pod {
+export interface Pod {
   metadata?: { annotations?: Record<string, string> };
   spec?: {
     os?: { name: string };
@@ -22,7 +22,7 @@ interface Pod {
     containers?: Container[]; initContainers?: Container[]; ephemeralContainers?: Container[];
   };
 }
-interface Patch { op: "add"; path: string; value: unknown }
+export interface Patch { op: "add"; path: string; value: unknown }
 export const TRUST_OPT_OUT = "spectest.dev/inject-ca";
 
 export function podTrustPatch(pod: Pod, configMap: string, ephemeral = false): Patch[] {
@@ -67,6 +67,8 @@ export interface TrustDependencies {
   /** Ensure this immutable ConfigMap exists in the requesting namespace. */
   ensureBundle(namespace: string, name: string, bundle: string): Promise<void>;
   apply(configuration: unknown): Promise<void>;
+  /** Component-owned pod instrumentation runs after trust patching. */
+  mutatePod?(pod: Pod, namespace: string, dryRun: boolean, ephemeral: boolean, uid: string): Promise<Patch[]>;
 }
 const servers = new Map<string, Server>();
 
@@ -91,6 +93,16 @@ export async function installPodTrust(options: {
         res.writeHead(400).end("invalid Pod admission request"); return;
       }
       const patch = podTrustPatch(request.object, configMap, request.subResource === "ephemeralcontainers");
+      if (deps.mutatePod) {
+        const pod = structuredClone(request.object);
+        for (const operation of patch) {
+          const keys = operation.path.slice(1).split("/");
+          const key = keys.pop()!;
+          const parent = keys.reduce((value: any, key) => value[key], pod as any);
+          if (key === "-") parent.push(operation.value); else parent[key] = operation.value;
+        }
+        patch.push(...await deps.mutatePod(pod, request.namespace, !!request.dryRun, request.subResource === "ephemeralcontainers", request.uid));
+      }
       // Dry runs return the same patch but perform no API writes.
       if (patch.length && !request.dryRun) await deps.ensureBundle(request.namespace, configMap, options.bundle);
       res.setHeader("Content-Type", "application/json");

package/src/components/k3s.ts

@@ -1,6 +1,7 @@
 import { isIP } from "node:net";
 import { waitForK3sNodes } from "./k3s-nodes.js";
 import { installPodTrust } from "./k3s-trust.js";
+import { k3sCoverage } from "./k3s-coverage.js";
 import { waitForAll } from "../harness/concurrency.js";
 import { CONTENT_BLOBS, REGISTRY_CONTENT, REGISTRY_DATA, REGISTRY_IMAGE, registryDirectory, seedRegistry } from "../harness/registry-seed.js";
 import { loadK3sBuildImages } from "../harness/k3s-image-loader.js";
@@ -1969,6 +1970,7 @@ export function k3s(opts: K3sOptions = {}) {
 function createK3sCluster(opts: K3sOptions, count: number) {
   const version = opts.version ?? DEFAULT_K3S_VERSION;
   const images = kubernetesImages(opts.images ?? []);
+  const coverage = k3sCoverage(opts.images ?? []);
   const extra = opts.extraArgs ?? [];
   assertUsableExtraArgs(extra);
   const registryEnabled = opts.registry !== false;
@@ -2132,6 +2134,7 @@ function createK3sCluster(opts: K3sOptions, count: number) {
       volumes: [{ name: `spectest-k3s-${cluster}-join`, target: JOIN_DIRECTORY }, ...(sticky
         ? [{ source: `${stickyKubernetesDirectory(SELF_SERVICE_TOKEN, version)}/containerd`, target: CLUSTER_STORE_TARGET }]
         : [{ target: CLUSTER_STORE_TARGET }]),
+        ...(coverage.enabled ? [coverage.volume(cluster)] : []),
         ...(server && publishBuilds.length ? [
           { source: registryDirectory(SELF_SERVICE_TOKEN), target: REGISTRY_DATA },
           { source: contentDirectory, target: REGISTRY_CONTENT, readOnly: true },
@@ -2140,6 +2143,7 @@ function createK3sCluster(opts: K3sOptions, count: number) {
       files: [
         ...(registriesYaml ? [{ path: "/etc/rancher/k3s/registries.yaml", content: registriesYaml }] : []),
       ],
+      ...(server && coverage.enabled ? { coverage: { adapters: [coverage.adapter()] } } : {}),
       // Agents start before the server and wait for its join token. The group
       // setup below gates readiness on every actual Kubernetes Node, including
       // the server, rather than treating container startup as cluster readiness.
@@ -2167,11 +2171,33 @@ function createK3sCluster(opts: K3sOptions, count: number) {
       const nodes = nodeNames(name);
       if (images.builds.length && !runtime) throw new Error(`k3s(${name}): prepared image inputs are missing`);
       const admission = (async () => {
+        if (coverage.enabled && (!runtime?.caBundle || !caPresent())) throw new Error(`k3s(${name}): coverage injection requires the environment CA`);
         if (runtime?.caBundle && caPresent()) {
           const { cert, key } = await issueIngressCert([runtime.gateway]);
           await installPodTrust({ name, gateway: runtime.gateway, cert, key,
             ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
           }, {
+            mutatePod: (pod, namespace, dryRun, ephemeral, uid) => coverage.mutate(name, pod, namespace, dryRun, ephemeral, uid, {
+              async image(reference) {
+                const result = await exec(name, ["crictl", "--runtime-endpoint", "unix:///run/k3s/containerd/containerd.sock", "inspecti", reference]);
+                if (result.exitCode !== 0) throw new Error(`coverage image metadata: ${result.stderr}`);
+                const record = JSON.parse(result.stdout);
+                const config = record.info?.imageSpec?.config;
+                if (!config) throw new Error(`coverage image ${reference} has no OCI configuration`);
+                return { aliases: record.status?.repoDigests ?? [], root: config.WorkingDir || "/",
+                  env: Object.fromEntries((config.Env ?? []).map((entry: string) => { const split = entry.indexOf("="); return [entry.slice(0, split), entry.slice(split + 1)]; })),
+                };
+              },
+              async files(namespace, name, data) {
+                try {
+                  await helpers.client.core.createNamespacedConfigMap({ namespace, body: { metadata: { name, namespace }, immutable: true, data } });
+                } catch (error) {
+                  const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name })).unwrap();
+                  if (!existing.immutable || Object.keys(existing.data ?? {}).length !== Object.keys(data).length ||
+                    Object.entries(data).some(([key, value]) => existing.data?.[key] !== value)) throw error;
+                }
+              },
+            }),
             apply: async configuration => { await helpers.apply(JSON.stringify(configuration)); },
             ensureBundle: async (namespace, configMap, bundle) => {
               try {