@specific.dev/spectest 0.127.0 → 0.129.0

package/README.md

@@ -24,6 +24,60 @@ work; do not replace readiness with sleeps or arbitrary `.first()` selections.
 SDK 0.123.0 uses native Playwright assertions while retaining Spectest's API and
 recording. Ambiguous single-element selectors fail immediately; make them unique.
 
+For terminal readiness, use `terminal.waitFor` directly. It retries the condition
+and throws on timeout, so neither an outer `ctx.wait` nor an extra assertion is
+needed to check that text appears:
+
+```ts
+await terminal.waitFor("Rack is initialized", /Current rack status:\s*Initialized/, {
+  timeoutMs: 35 * 60_000,
+  intervalMs: 5_000,
+  failOn: [
+    { description: "Setup was rejected", matcher: "Start Rack Setup Failed" },
+    { description: "Initialization failed", matcher: "Initialization Failed" },
+    { description: "Initialization panicked", matcher: "Initialization Panicked" },
+  ],
+});
+await terminal.press("Ctrl+C"); // Separate cleanup after the condition succeeds.
+```
+
+SDK 0.129.0 records the string/regex matcher (or identifies a custom predicate),
+timeout, and start/end positions for this wait. The dashboard shows its condition
+and outcome and replays up to the result. Later inputs belong to their own steps;
+the full terminal session can be opened separately. `ctx.wait` remains useful
+when a retry must repeat actions, rather than just observe terminal state.
+
+Terminal waits record matched, timed-out, failure-condition, predicate-error,
+process-exit and cancelled outcomes. `failOn` checks the rendered screen before
+checking success; string and regex conditions are recorded explicitly. For a
+custom predicate, provide `condition: "Expected sled has a valid bootstrap IPv6 address"`
+to explain the actual check separately from its step title. Async predicates are
+awaited, and their rejection is recorded. A final matching screen succeeds even
+if the process has exited; otherwise exit fails the wait after final output is
+drained. No `Promise.race` with `terminal.exited` is needed.
+
+Pass `signal: controller.signal` to cancel a wait without closing its terminal.
+Cancellation stops SDK polling; it cannot forcibly stop work started inside a
+custom predicate. `terminal.close({ timeoutMs: 10_000 })` cancels pending waits,
+sends EOF, escalates to a kill, and bounds cleanup including output drain. The
+default close deadline is 10 seconds; repeated calls share the same result or
+failure. `terminal.exited` records the exit when observed after completion, not
+when its promise is first read. A stalled output drain fails after 5 seconds
+instead of hanging indefinitely. Test code should preserve its original failure
+if diagnostic or cleanup operations also fail.
+
+Browser navigation accepts public Playwright-style options, without a backend
+cast or `pageOp` call:
+
+```ts
+await browser.goto(consoleUrl, { timeout: 120_000, waitUntil: "domcontentloaded" });
+await browser.reload({ timeout: 120_000 });
+```
+
+These options also apply to `goBack` and `goForward`. Navigation deadlines do not
+cancel a surrounding `ctx.poll`, and retrying a navigation after a visible error
+is a recovery action that should remain visible in the test results.
+
 Pub/Sub integrations are project-owned as of SDK 0.98.0. The former
 `pubsub`/`pubsubClient` exports and `/components/gcp` entry point are removed.
 Use a local service definition or `serviceGroup()` wrapper; the repository’s

package/dist/browser.d.ts

@@ -124,6 +124,11 @@ export interface Mouse {
     /** Wheel-scroll by a pixel delta. */
     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;
@@ -136,14 +141,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;
     /** Root CSS query. */
@@ -363,6 +368,8 @@ export declare function acquirePersistentDesktop(endpoint: string, windowIndex:
     desktopChrome?: DesktopChrome;
 }>;
 export interface RecordableFields {
+    timeout: number;
+    waitUntil: NonNullable<NavigationOptions["waitUntil"]>;
     target: RecordedBrowserLocatorPart[];
     destinationTarget: RecordedBrowserLocatorPart[];
     url: string;

package/dist/browser.js

@@ -1491,11 +1491,11 @@ function buildBackend(holder, recorder, buildOpts) {
         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
@@ -1508,23 +1508,23 @@ function buildBackend(holder, recorder, buildOpts) {
                     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);
             });
         },
         locator: (css) => makeLocator(backend, strategy, { steps: [{ m: "locator", args: [css] }] }),

package/dist/components/k3s-coverage.d.ts

@@ -0,0 +1,24 @@
+import { type CoverageAdapter } from "../coverage.js";
+import { type KubernetesImage } from "../harness/component-images.js";
+import type { Patch, Pod } from "./k3s-trust.js";
+interface ImageInfo {
+    aliases: string[];
+    root: string;
+    env: Record<string, string>;
+}
+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 declare function k3sCoverage(images: readonly KubernetesImage[]): {
+    enabled: boolean;
+    volume(cluster: string): {
+        source: string;
+        target: string;
+        reachExempt: boolean;
+    };
+    mutate(cluster: string, podInput: Pod, namespace: string, dryRun: boolean, ephemeral: boolean, uid: string, deps: K3sCoverageDependencies): Promise<Patch[]>;
+    adapter(): CoverageAdapter;
+};
+export {};

package/dist/components/k3s-coverage.js

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { applyCoverageAdapters, coverageAdapters } from "../coverage.js";
+import { coverageHostDir, COVERAGE_MAX_BYTES_PER_SERVICE } from "../harness/coverage.js";
+import { captureCoverageTarget } from "../harness/coverage-target.js";
+import { canonicalImageReference } from "../harness/component-images.js";
+import { WORKSPACE } from "../project-files.js";
+const MOUNT = "/spectest/pod-coverage";
+const ANNOTATION = "spectest.dev/coverage";
+const hash = (value) => createHash("sha256").update(value).digest("hex").slice(0, 16);
+const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+/** One component-owned bridge; runtime adapters remain unaware of Kubernetes. */
+export function k3sCoverage(images) {
+    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();
+    const service = (cluster, reference) => `${cluster}/image-${hash(reference)}`;
+    return {
+        enabled: declarations.length > 0,
+        volume(cluster) {
+            return { source: coverageHostDir(WORKSPACE, cluster), target: MOUNT, reachExempt: true };
+        },
+        async mutate(cluster, podInput, namespace, dryRun, ephemeral, uid, deps) {
+            if (!declarations.length || ephemeral)
+                return [];
+            const pod = podInput;
+            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 = [];
+            const volumes = [...(pod.spec.volumes ?? [])];
+            const instances = [];
+            const namedVolume = (stem, volume) => {
+                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"]) {
+                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(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, mount) => {
+                        if (mounts.some(m => mountPath === m.mountPath || mountPath.startsWith(m.mountPath.replace(/\/$/, "") + "/")))
+                            throw new Error(`coverage mount conflicts with ${mountPath}`);
+                        mounts.push({ mountPath, ...mount });
+                    };
+                    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 = { 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() {
+            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;
+                    try {
+                        entries = await fs.readdir(root);
+                    }
+                    catch (error) {
+                        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;
+                    const findPod = async (id) => {
+                        pods ??= ctx.exec("kubectl get pods -A -o json --request-timeout=10s")
+                            .then(result => JSON.parse(result.stdout).items);
+                        return (await pods).find(p => {
+                            const ids = p.metadata?.annotations?.[ANNOTATION];
+                            return ids && JSON.parse(ids).instances.includes(id);
+                        });
+                    };
+                    const captures = new Map();
+                    const inventories = new Map();
+                    for (const declaration of declarations)
+                        captures.set(declaration.reference, { service: service(ctx.service, declaration.reference), reports: [] });
+                    const collectInstance = async (id) => {
+                        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"));
+                        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();
+                    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()];
+                },
+            };
+        },
+    };
+}

package/dist/components/k3s-trust.d.ts

@@ -12,7 +12,7 @@ interface Container {
         readOnly?: boolean;
     }[];
 }
-interface Pod {
+export interface Pod {
     metadata?: {
         annotations?: Record<string, string>;
     };
@@ -32,7 +32,7 @@ interface Pod {
         ephemeralContainers?: Container[];
     };
 }
-interface Patch {
+export interface Patch {
     op: "add";
     path: string;
     value: unknown;
@@ -43,6 +43,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[]>;
 }
 export declare function installPodTrust(options: {
     name: string;

package/dist/components/k3s-trust.js

@@ -75,6 +75,19 @@ export async function installPodTrust(options, deps) {
                 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, key) => value[key], pod);
+                    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);

package/dist/components/k3s.js

@@ -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";
@@ -1335,6 +1336,7 @@ export function k3s(opts = {}) {
 function createK3sCluster(opts, count) {
     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;
@@ -1497,6 +1499,7 @@ function createK3sCluster(opts, count) {
             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 },
@@ -1505,6 +1508,7 @@ function createK3sCluster(opts, count) {
             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.
@@ -1533,11 +1537,38 @@ function createK3sCluster(opts, count) {
             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) => { 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 {