supercov 2.0.0 → 3.0.0

package/runtime/javascript/launchSupervisor.mjs

@@ -54,6 +54,10 @@ function executionLogPath(path, token = executionLog.token) {
         ? `${path.slice(0, -".jsonl".length)}${suffix}`
         : `${path}${suffix}`;
 }
+/** Append one event to the run's execution log, as the supervisor does. */
+export function recordExecution(value) {
+    record(value);
+}
 function record(value) {
     const configuredPath = process.env["SUPERCOV_EXECUTION_LOG"];
     if (!configuredPath)
@@ -254,15 +258,32 @@ function launchArgv(value) {
         return value.cmd;
     return [String(value.command)];
 }
+// A plain map of environment variables, as `run(argv, { ...process.env })`
+// passes one: string values under variable names, at least one of them in
+// capitals, and nothing an options object would carry. A name is anything
+// without `=`: Windows' own environment has `ProgramFiles(x86)`, and a map
+// copied from it was taken for options and its guest left unconfigured.
+function environmentMap(value) {
+    const entries = Object.entries(value);
+    return (entries.length > 0 &&
+        entries.every(([name, item]) => typeof item === "string" && /^[^=\0]+$/.test(name)) &&
+        entries.some(([name]) => /^[A-Z_][A-Z0-9_]*$/.test(name)) &&
+        !launchOptions(value));
+}
 function injectRemoteLaunch(options, mapping) {
-    const environmentKey = "environment" in options && !("env" in options) ? "environment" : "env";
+    const coverage = {
+        ...process.env,
+        SUPERCOV_EXECUTION_LOG_SHARD: `${process.pid}-${++remoteLaunchSequence}`,
+    };
+    if (environmentMap(options))
+        return guestCoverageEnvironment(mapping, coverage, options);
+    // The SDK's own name for a command's environment: `env`, `environment`
+    // or, as E2B spells it, `envs`. A new one is called `env`.
+    const environmentKey = ["env", "environment", "envs"].find((key) => key in options) ?? "env";
     const existing = options[environmentKey];
     return {
         ...options,
-        [environmentKey]: guestCoverageEnvironment(mapping, {
-            ...process.env,
-            SUPERCOV_EXECUTION_LOG_SHARD: `${process.pid}-${++remoteLaunchSequence}`,
-        }, existing && typeof existing === "object"
+        [environmentKey]: guestCoverageEnvironment(mapping, coverage, existing && typeof existing === "object"
             ? existing
             : {}),
     };
@@ -418,6 +439,21 @@ export function wrapCapabilityObject(value, mapping) {
                         guestRoot: mapping.guestRoot,
                     });
                 }
+                else if (typeof property === "string" &&
+                    /env/i.test(property) &&
+                    args.length === 1 &&
+                    args[0] &&
+                    typeof args[0] === "object" &&
+                    environmentMap(args[0])) {
+                    // A builder that takes the command's environment by itself
+                    // (`withEnvironment(env)`) before it starts the command.
+                    callArguments = [injectRemoteLaunch(args[0], mapping)];
+                    record({
+                        event: "remote-launch",
+                        command: commandSummary([property]),
+                        guestRoot: mapping.guestRoot,
+                    });
+                }
                 return wrapResult(Reflect.apply(member, target, callArguments), mapping);
             };
         },
@@ -435,6 +471,7 @@ export function wrapImportedCapability(value) {
         return value;
     if (isClassConstructor(value)) {
         patchBuilder(value);
+        patchMountMethods(value);
         return value;
     }
     const object = value;
@@ -489,6 +526,49 @@ export function wrapImportedCapability(value) {
     importedCapabilityProxies.set(object, proxy);
     return proxy;
 }
+const patchedMountMethods = new WeakSet();
+/**
+ * A builder made with `new` (`new GenericContainer(image)`) takes its mounts
+ * on an instance method, `withBindMounts([{ source, target }])`. The class
+ * itself must stay the exact value it is -- registries compare constructors
+ * -- so its mount methods are patched in place instead: called with a mount
+ * of the workspace, the builder they return is followed, and its later calls
+ * (`withEnvironment`, `start`) see the mapping. Called without one, they do
+ * what they always did.
+ */
+function patchMountMethods(builder) {
+    for (let prototype = builder.prototype; prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+        for (const name of Object.getOwnPropertyNames(prototype)) {
+            if (!/mount/i.test(name))
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+            if (!descriptor ||
+                typeof descriptor.value !== "function" ||
+                !descriptor.writable ||
+                patchedMountMethods.has(descriptor.value))
+                continue;
+            const original = descriptor.value;
+            const patched = function supercovMountMethod(...args) {
+                const hostRoot = process.env["SUPERCOV_PROJECT_ROOT"];
+                const mapping = hostRoot
+                    ? args.map((argument) => discoverWorkspaceMapping(argument, hostRoot)).find(Boolean)
+                    : undefined;
+                const result = Reflect.apply(original, this, args);
+                if (!mapping)
+                    return result;
+                record({
+                    event: "workspace-capability",
+                    hostRoot: mapping.hostRoot,
+                    guestRoot: mapping.guestRoot,
+                    cacheIdentities: [],
+                });
+                return wrapResult(result, mapping);
+            };
+            patchedMountMethods.add(patched);
+            Object.defineProperty(prototype, name, { ...descriptor, value: patched });
+        }
+    }
+}
 function patchBuilder(builder) {
     if (patchedBuilders.has(builder))
         return;
@@ -545,20 +625,52 @@ function inspectExports(value, depth = 0) {
         }
     }
 }
+// spawn, fork and execFile take (file, args?, options?, callback?): options
+// follow an argument list, or an explicit null or undefined in its place. exec
+// takes (command, options?, callback?), and calls execFile as (file, options,
+// callback) itself -- that object is the options, not an argument list.
 function childOptionsIndex(method, args) {
-    if (method === "spawn" || method === "spawnSync" || method === "fork")
-        return Array.isArray(args[1]) || (args.length > 2 && args[2] !== undefined)
-            ? 2
-            : 1;
-    if (method === "exec" ||
-        method === "execSync" ||
+    if (method === "spawn" ||
+        method === "spawnSync" ||
+        method === "fork" ||
         method === "execFile" ||
         method === "execFileSync")
-        return Array.isArray(args[1]) || (args.length > 2 && args[2] !== undefined)
-            ? 2
-            : 1;
+        return Array.isArray(args[1]) || (args[1] == null && args.length > 2) ? 2 : 1;
+    if (method === "exec" || method === "execSync")
+        return 1;
     return undefined;
 }
+// util.promisify(exec) and util.promisify(execFile) resolve { stdout, stderr }
+// through a function Node keeps on the original, and that function calls the
+// original. A wrapper carries its own, which calls the wrapper, or a promisified
+// call resolves the bare stdout string and skips the wrapper.
+const promisifyCustom = Symbol.for("nodejs.util.promisify.custom");
+function keepPromisifiedShape(original, wrapper) {
+    if (typeof original[promisifyCustom] !== "function")
+        return wrapper;
+    Object.defineProperty(wrapper, promisifyCustom, {
+        configurable: true,
+        value: (...args) => {
+            let settle;
+            let reject;
+            const promise = new Promise((ok, fail) => {
+                settle = ok;
+                reject = fail;
+            });
+            promise.child = wrapper(...args, (error, stdout, stderr) => {
+                if (error !== null) {
+                    error.stdout = stdout;
+                    error.stderr = stderr;
+                    reject(error);
+                }
+                else
+                    settle({ stdout, stderr });
+            });
+            return promise;
+        },
+    });
+    return wrapper;
+}
 function injectChildEnvironment(method, args) {
     const index = childOptionsIndex(method, args);
     if (index === undefined)
@@ -617,7 +729,7 @@ function patchChildProcesses() {
             configurable: true,
             enumerable: true,
             writable: true,
-            value: (...args) => Reflect.apply(original, childProcess, injectChildEnvironment(method, args)),
+            value: keepPromisifiedShape(original, (...args) => Reflect.apply(original, childProcess, injectChildEnvironment(method, args))),
         });
     }
     syncBuiltinESMExports();

package/runtime/javascript/mocha.mjs

@@ -0,0 +1,180 @@
+// Supercov Mocha adapter. The preload imports it in every Mocha process --
+// the CLI, the child the CLI forks for Node options, and each --parallel
+// worker -- and it patches Mocha's own Runner, so a suite runs exactly as
+// written: no reporter, --require or configuration is added. Each test
+// attempt gets its exact scope when Mocha announces it, before its
+// beforeEach hooks, and its coverage, assertion phases and outcome are
+// written after its afterEach hooks. Code that runs outside any test --
+// loading the test files, before/after all hooks -- is written as setup. It
+// computes no coverage.
+import { realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { appendEvidenceRecord } from "./atomic.mjs";
+import { inferTestProvenance } from "./provenance.mjs";
+import { runnerExecutionScope } from "./runnerEvidence.mjs";
+
+const SETUP_HOOK = /^"(?:before|after) all" hook/;
+
+function localFile(path) {
+    return path ? relative(process.cwd(), path).split(sep).join("/") : undefined;
+}
+
+// The installed mocha package the entrypoint belongs to.
+function mochaRoot(entrypoint) {
+    let real;
+    try {
+        real = realpathSync(entrypoint).replaceAll("\\", "/");
+    }
+    catch {
+        return undefined;
+    }
+    const at = real.lastIndexOf("/node_modules/mocha/");
+    return at < 0 ? undefined : real.slice(0, at + "/node_modules/mocha".length);
+}
+
+export async function adaptMocha(entrypoint) {
+    const runtime = globalThis.__SUPERCOV_DIRECT_RUNTIME__ ?? process.__SUPERCOV_DIRECT_RUNTIME__;
+    const evidenceDirectory = process.env.SUPERCOV_EVIDENCE_DIR;
+    const root = mochaRoot(entrypoint);
+    if (!runtime || !evidenceDirectory || !root)
+        return;
+    // Mocha 12 is ESM and exports { Runner }; 10 and 11 are CommonJS and
+    // export the class itself. Either way this is the instance Mocha uses.
+    let loaded;
+    try {
+        loaded = await import(pathToFileURL(join(root, "lib", "runner.js")).href);
+    }
+    catch {
+        return;
+    }
+    const Runner = loaded.Runner ?? loaded.default?.Runner ?? loaded.default;
+    const run = Runner?.prototype?.run;
+    if (typeof run !== "function" || run.supercovMocha)
+        return;
+    // One snapshot per test, as under Jest; the server transport would only
+    // repeat it, unattributed.
+    runtime.enableRuntimeSnapshotEvidence();
+    const directory = resolve(process.cwd(), evidenceDirectory);
+    const write = (payload) => appendEvidenceRecord(directory, "mocha", payload);
+    // A --parallel parent overrides run() and never reaches this: its workers
+    // run the tests, each with a Runner of its own.
+    Runner.prototype.run = function supercovMochaRun(...args) {
+        observe(this, runtime, write);
+        return Reflect.apply(run, this, args);
+    };
+    Runner.prototype.run.supercovMocha = true;
+}
+
+function observe(runner, runtime, write) {
+    // Tests that share a file and a full title are told apart by the order in
+    // which their first attempts ran; a retry keeps its test's identity.
+    const firstAttempts = new Map();
+    const identities = new WeakMap();
+    let active;
+    let setups = 0;
+    function identity(test) {
+        const known = identities.get(test);
+        if (known)
+            return known;
+        const file = test.file;
+        const name = test.titlePath().join(" > ");
+        const key = `${file ?? ""}\0${name}`;
+        let occurrence = firstAttempts.get(key) ?? 0;
+        if (test.currentRetry() > 0)
+            occurrence = Math.max(occurrence - 1, 0);
+        else
+            firstAttempts.set(key, occurrence + 1);
+        const value = {
+            runner: "mocha",
+            file,
+            name,
+            ...(occurrence ? { registrationOrdinal: occurrence } : {}),
+            retry: test.currentRetry(),
+        };
+        identities.set(test, value);
+        return value;
+    }
+    function record(id, status, scope, snapshot) {
+        const testFile = localFile(id.file);
+        write({
+            testId: scope ? scope.testId : runnerExecutionScope(id).testId,
+            ...(scope ? { scope } : {}),
+            test: id.name,
+            ...(testFile ? { testFile } : {}),
+            title: id.name.split(" > ").at(-1) ?? id.name,
+            retry: id.retry ?? 0,
+            status,
+            ...(id.role ? { role: id.role } : {}),
+            provenance: inferTestProvenance({
+                runner: "mocha",
+                file: testFile,
+                explicitKind: process.env.SUPERCOV_TEST_KIND,
+            }),
+            ...(scope ? { phases: runtime.takeNodeAssertionPhases(scope) } : {}),
+            runtime: snapshot ? [snapshot] : [],
+            browser: [],
+            server: [],
+        });
+    }
+    // What ran since the last test or setup ended, outside any test.
+    function flushSetup(name) {
+        const snapshot = runtime.coverageSnapshot();
+        runtime.resetCoverage();
+        if (!snapshot.hits.length && !snapshot.decisions.length)
+            return;
+        setups += 1;
+        const id = { runner: "mocha", name, role: "setup", registrationOrdinal: setups };
+        record(id, "passed", runnerExecutionScope(id), snapshot);
+    }
+    function flushActive() {
+        const current = active;
+        active = undefined;
+        if (!current)
+            return;
+        record(current.id, current.status, current.scope, runtime.coverageSnapshot());
+        runtime.resetCoverage();
+        runtime.activateCoverageScope();
+    }
+    runner.on("start", () => flushSetup("module setup"));
+    runner.on("test", (test) => {
+        flushActive();
+        flushSetup(`${test.parent?.fullTitle() || "root suite"} > hooks`);
+        const id = identity(test);
+        const scope = runnerExecutionScope(id);
+        active = { test, id, scope, status: "unknown" };
+        runtime.activateCoverageScope(scope);
+        runtime.resetCoverage(scope.testId);
+    });
+    runner.on("pass", (test) => {
+        if (active?.test === test)
+            active.status = "passed";
+    });
+    // A failed attempt Mocha will run again, and a failing beforeEach or
+    // afterEach hook, fail the attempt that is running.
+    runner.on("retry", (test) => {
+        if (active?.test === test)
+            active.status = "failed";
+    });
+    runner.on("fail", (runnable) => {
+        if (active && (active.test === runnable || runnable.type === "hook"))
+            active.status = "failed";
+        else if (runnable.type === "test")
+            record(identity(runnable), "failed");
+    });
+    runner.on("pending", (test) => {
+        if (active?.test === test)
+            active.status = "skipped";
+        else
+            record(identity(test), "skipped");
+    });
+    runner.on("hook", (hook) => {
+        if (SETUP_HOOK.test(hook.title ?? ""))
+            flushActive();
+    });
+    runner.on("suite end", flushActive);
+    runner.on("end", () => {
+        flushActive();
+        flushSetup("hooks");
+    });
+}

package/runtime/javascript/nodeTest.mjs

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import * as native from "node:test";
 import { fileURLToPath } from "node:url";
 import vm from "node:vm";
@@ -86,6 +87,43 @@ function restoreUserError(error, depth = 0) {
     }
     return error;
 }
+// The describe/suite blocks a test is registered in, outermost first. A test
+// is named by them as Vitest, Jest and Playwright name theirs, so two tests
+// with one name in different suites stay apart, and `tests affected --names`
+// gives what --test-name-pattern matches. A store rather than a stack: an
+// async suite registers tests after it awaits.
+const suitePath = new AsyncLocalStorage();
+function suiteName(args, callback) {
+    return typeof args[0] === "string" ? args[0] : callback.name || "<anonymous>";
+}
+function wrappedSuite(original) {
+    const wrapped = function supercovNodeSuite(...args) {
+        const index = callbackIndex(args);
+        if (index < 0)
+            return Reflect.apply(original, this, args);
+        const callback = args[index];
+        const path = [...(suitePath.getStore() ?? []), suiteName(args, callback)];
+        const next = [...args];
+        next[index] = function supercovNodeSuiteCallback(...callbackArgs) {
+            return suitePath.run(path, () => Reflect.apply(callback, this, callbackArgs));
+        };
+        // node:test reports a suite at its direct caller, as it does a test.
+        const registration = registrationAt(callerLocation(supercovNodeSuite));
+        if (registration)
+            return registration(this === undefined ? original : original.bind(this), next);
+        return Reflect.apply(original, this, next);
+    };
+    for (const property of ["skip", "todo", "only"]) {
+        const member = original[property];
+        if (typeof member === "function")
+            Object.defineProperty(wrapped, property, {
+                configurable: true,
+                enumerable: true,
+                value: wrappedSuite(member),
+            });
+    }
+    return wrapped;
+}
 const registrationCounts = new Map();
 function wrappedRegistration(original, parentTestId, forcedStatus) {
     const wrapped = function supercovNodeTest(...args) {
@@ -96,7 +134,9 @@ function wrappedRegistration(original, parentTestId, forcedStatus) {
         const location = callerLocation(supercovNodeTest);
         const identity = {
             runner: "node:test",
-            name: testName(args, callback),
+            name: parentTestId
+                ? testName(args, callback)
+                : [...(suitePath.getStore() ?? []), testName(args, callback)].join(" > "),
             ...(parentTestId ? { parentTestId } : {}),
             ...location,
             // Source-map producers disagree about whether a call expression maps to
@@ -260,8 +300,8 @@ function restoringHook(original, scope, hookName = "hook") {
 }
 export const test = wrappedRegistration(native.test);
 export const it = wrappedRegistration(native.it);
-export const suite = native.suite;
-export const describe = native.describe;
+export const suite = wrappedSuite(native.suite);
+export const describe = wrappedSuite(native.describe);
 export const before = restoringHook(native.before, undefined, "before");
 export const after = restoringHook(native.after, undefined, "after");
 export const beforeEach = restoringHook(native.beforeEach, undefined, "beforeEach");
@@ -270,4 +310,18 @@ export const mock = native.mock;
 export const snapshot = native.snapshot;
 export const run = native.run;
 export const assert = native.assert;
+// node:test hangs its whole API off `test` (test.mock, test.describe,
+// test.expectFailure, test.getTestContext...). What the adapter does not wrap
+// stays the runtime's own.
+const adapted = { it, describe, suite, before, after, beforeEach, afterEach, test };
+for (const property of Object.keys(native.test)) {
+    if (property in test && !(property in adapted))
+        continue;
+    Object.defineProperty(test, property, {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: adapted[property] ?? native.test[property],
+    });
+}
 export default test;