@e2edev/e2e 0.5.0 → 0.6.0

package/dist/run/managed-process.js

@@ -1,5 +1,6 @@
-/** Spawned-process management for `app.command`, `app.services`, and their teardowns (spec 05-config.md). */
+/** Spawned-process management for the commands and services engines declare, and their teardowns. */
 import { spawn } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { InfrastructureError } from '../internal/errors.js';
 import { sleep } from '../internal/time.js';
@@ -9,37 +10,114 @@ const READY_POLL_MIN_MS = 25;
 const READY_POLL_MAX_MS = 250;
 /** One readiness probe never outlives this, so a half-open server cannot stall the deadline check. */
 const READY_PROBE_TIMEOUT_MS = 2_000;
+/** Every spawned process group still running, for the forced exit that cannot wait on `stop`. */
+const live = new Set();
+/**
+ * Sends `signal` to the whole process group behind `child` (the child alone
+ * on Windows, which has no process groups); a group already gone is fine.
+ */
+function signalProcessGroup(child, signal) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    try {
+        if (process.platform !== 'win32')
+            process.kill(-pid, signal);
+        else
+            child.kill(signal);
+    }
+    catch {
+        // process already gone
+    }
+}
+/**
+ * Kills every process group this module spawned and has not yet seen exit,
+ * synchronously and without waiting: the last resort before the process
+ * exits on the spot, so nothing it started outlives it. A reused process was
+ * never spawned here and is left alone.
+ */
+export function killManagedProcessGroups() {
+    for (const child of live)
+        signalProcessGroup(child, 'SIGKILL');
+}
 function describeExit(exit) {
     return exit.code === null ? `was terminated by ${exit.signal}` : `exited with code ${exit.code}`;
 }
+/** One readiness probe: true when `url` answers 200 through 499 within `timeoutMs`. */
+async function answers(url, timeoutMs) {
+    try {
+        const response = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+        return response.status >= 200 && response.status <= 499;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * One command the runner owns: spawned as a process group, waited on until
  * its readiness contract holds, and terminated signal-then-force. `label`
- * names it in every error (`app.command`, `app.services[0] (docker ...)`).
+ * names it in every error (`target "web" command`, `service "postgres"`).
  */
 export class ManagedProcess {
     label;
     command;
     projectRoot;
     readiness;
+    hooks;
     child = null;
-    constructor(label, command, projectRoot, readiness) {
+    reusedExisting = false;
+    constructor(label, command, projectRoot, readiness, hooks = {}) {
         this.label = label;
         this.command = command;
         this.projectRoot = projectRoot;
         this.readiness = readiness;
+        this.hooks = hooks;
+    }
+    /** True once `start` found the readiness URL already answering and attached to it instead of spawning. */
+    get reused() {
+        return this.reusedExisting;
     }
     /**
      * Spawns the process group and waits for readiness. An already aborted
      * `signal` spawns nothing; one that aborts during the wait ends it early and
      * takes the process down with it. The caller reads the signal to learn the
      * run was interrupted.
+     *
+     * A readiness URL that already answers before the spawn belongs to a
+     * process this run did not start, and HTTP readiness cannot tell which
+     * process answered later. So the preflight probe decides up front: with
+     * `reuseExisting` (outside CI) nothing is spawned and `stop` leaves the
+     * process alone; otherwise the launch fails with `APP_ALREADY_RUNNING`
+     * rather than letting the old server pass as the new command's readiness.
+     * The probe spends from the same `startupTimeout` budget as the wait.
      */
     async start(signal) {
         // A function, not a narrowed local: the signal flips while the loop awaits.
         const aborted = () => signal?.aborted === true;
         if (aborted())
             return;
+        // Without a URL to probe, the process exiting 0 is the readiness event.
+        const readyUrl = 'readyUrl' in this.readiness ? this.readiness.readyUrl : undefined;
+        const startupTimeout = this.command.startupTimeout ?? 60_000;
+        const deadline = Date.now() + startupTimeout;
+        if (readyUrl !== undefined) {
+            const reuse = this.command.reuseExisting === true && this.hooks.ci !== true;
+            if (this.command.reuseExisting === true && !reuse) {
+                this.hooks.notice?.(`${this.label}: reuseExisting is ignored in CI, starting the command`);
+            }
+            if (await answers(readyUrl, Math.min(READY_PROBE_TIMEOUT_MS, startupTimeout))) {
+                if (reuse) {
+                    this.reusedExisting = true;
+                    this.hooks.notice?.(`${this.label}: reusing the process already serving ${readyUrl}`);
+                    return;
+                }
+                throw new InfrastructureError('APP_ALREADY_RUNNING', `${readyUrl} already answered before ${this.label} started; ${this.hooks.ci === true
+                    ? 'stop that process (reuseExisting is ignored in CI)'
+                    : 'stop that process or set reuseExisting: true'}`);
+            }
+            if (aborted())
+                return;
+        }
         const env = {};
         for (const key of INHERITED_ENV) {
             const value = process.env[key];
@@ -47,13 +125,25 @@ export class ManagedProcess {
                 env[key] = value;
         }
         Object.assign(env, this.command.env ?? {});
-        const child = spawn(this.command.executable, [...(this.command.args ?? [])], {
-            cwd: path.resolve(this.projectRoot, this.command.cwd ?? '.'),
-            env,
-            detached: process.platform !== 'win32',
-            stdio: 'ignore',
-        });
+        const logFd = this.openLog();
+        let child;
+        try {
+            child = spawn(this.command.executable, [...(this.command.args ?? [])], {
+                cwd: path.resolve(this.projectRoot, this.command.cwd ?? '.'),
+                env,
+                detached: process.platform !== 'win32',
+                stdio: logFd === undefined ? 'ignore' : ['ignore', logFd, logFd],
+            });
+        }
+        finally {
+            // The child holds its own copy of the descriptor once spawn returns
+            // (a spawn failure surfaces as the 'error' event, not here), so the
+            // parent's copy would only be a leak for the life of the run.
+            if (logFd !== undefined)
+                fs.closeSync(logFd);
+        }
         this.child = child;
+        live.add(child);
         let spawnError;
         child.on('error', (error) => {
             spawnError = error;
@@ -61,14 +151,11 @@ export class ManagedProcess {
         let exit;
         const exited = new Promise((resolve) => {
             child.once('exit', (code, exitSignal) => {
+                live.delete(child);
                 exit = { code, signal: exitSignal };
                 resolve();
             });
         });
-        // Without a URL to probe, the process exiting 0 is the readiness event.
-        const readyUrl = 'readyUrl' in this.readiness ? this.readiness.readyUrl : undefined;
-        const startupTimeout = this.command.startupTimeout ?? 60_000;
-        const deadline = Date.now() + startupTimeout;
         let pollMs = READY_POLL_MIN_MS;
         for (;;) {
             if (aborted()) {
@@ -90,18 +177,8 @@ export class ManagedProcess {
                     ? `${this.label} did not exit within ${startupTimeout} ms`
                     : `${this.label} was not reachable at ${readyUrl} within ${startupTimeout} ms`);
             }
-            if (readyUrl !== undefined) {
-                try {
-                    const response = await fetch(readyUrl, {
-                        redirect: 'manual',
-                        signal: AbortSignal.timeout(Math.min(READY_PROBE_TIMEOUT_MS, remaining)),
-                    });
-                    if (response.status >= 200 && response.status <= 499)
-                        return;
-                }
-                catch {
-                    // not ready yet
-                }
+            if (readyUrl !== undefined && (await answers(readyUrl, Math.min(READY_PROBE_TIMEOUT_MS, remaining)))) {
+                return;
             }
             // The exit event wakes the wait early so an exit is seen at once, not on the next poll.
             await Promise.race([
@@ -111,51 +188,59 @@ export class ManagedProcess {
             pollMs = Math.min(pollMs * 2, READY_POLL_MAX_MS);
         }
     }
-    /** Gracefully terminates the whole process group, then force-kills. */
+    /**
+     * Opens `command.log` for appending, creating its directory, and returns
+     * the descriptor the child writes stdout and stderr to. No `log` means the
+     * output is discarded as before. The same file across services and runs
+     * accumulates, which is what a developer reading a failed boot wants.
+     */
+    openLog() {
+        if (this.command.log === undefined)
+            return undefined;
+        const logPath = path.resolve(this.projectRoot, this.command.log);
+        try {
+            fs.mkdirSync(path.dirname(logPath), { recursive: true });
+            return fs.openSync(logPath, 'a');
+        }
+        catch (cause) {
+            throw new InfrastructureError('APP_UNREACHABLE', `${this.label} could not open its log file ${logPath}: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        }
+    }
+    /** Gracefully terminates the whole process group, then force-kills. A reused process was never ours to stop. */
     async stop() {
+        if (this.reusedExisting)
+            return;
         const child = this.child;
         this.child = null;
         if (child === null || child.exitCode !== null || child.signalCode !== null)
             return;
         const shutdownTimeout = this.command.shutdownTimeout ?? 10_000;
-        const pid = child.pid;
-        const signalGroup = (signal) => {
-            if (pid === undefined)
-                return;
-            try {
-                if (process.platform !== 'win32')
-                    process.kill(-pid, signal);
-                else
-                    child.kill(signal);
-            }
-            catch {
-                // process already gone
-            }
-        };
-        signalGroup('SIGTERM');
+        signalProcessGroup(child, 'SIGTERM');
         const exited = new Promise((resolve) => {
             child.once('exit', () => resolve());
         });
         const timer = sleep(shutdownTimeout).then(() => 'timeout');
         const winner = await Promise.race([exited.then(() => 'exited'), timer]);
         if (winner === 'timeout') {
-            signalGroup('SIGKILL');
+            signalProcessGroup(child, 'SIGKILL');
             await exited.catch(() => undefined);
         }
     }
 }
 /**
- * The dependency processes of `app.services`: started sequentially in
- * declaration order, each ready before the next starts, and torn down in
- * reverse.
+ * The dependency processes the engines declared as `services`: started
+ * sequentially in declaration order, each ready before the next starts, and
+ * torn down in reverse.
  */
 export class ServiceStack {
     services;
     projectRoot;
+    hooks;
     started = [];
-    constructor(services, projectRoot) {
+    constructor(services, projectRoot, hooks = {}) {
         this.services = services;
         this.projectRoot = projectRoot;
+        this.hooks = hooks;
     }
     /**
      * Starts every service in order. Stops early once `signal` aborts; the
@@ -165,7 +250,7 @@ export class ServiceStack {
         for (const { label, command, readiness, teardown } of this.services) {
             if (signal?.aborted === true)
                 return;
-            const service = new ManagedProcess(label, command, this.projectRoot, readiness);
+            const service = new ManagedProcess(label, command, this.projectRoot, readiness, this.hooks);
             this.started.push({
                 service,
                 teardown: teardown === undefined
@@ -181,14 +266,15 @@ export class ServiceStack {
      * Stops the started services in reverse order, then runs each of their
      * teardown commands in reverse order and waits for it to exit. A failing
      * teardown is reported through `onFailure` and never skips the rest, so one
-     * failing `docker compose down` cannot leave the others running.
+     * failing `docker compose down` cannot leave the others running. A reused
+     * service was not started by this run, so its teardown does not run either.
      */
     async stop(onFailure) {
         const started = this.started.splice(0).toReversed();
         for (const { service } of started)
             await service.stop();
-        for (const { teardown } of started) {
-            if (teardown === undefined)
+        for (const { service, teardown } of started) {
+            if (teardown === undefined || service.reused)
                 continue;
             try {
                 await teardown.start();

package/dist/run/managed-process.js.map

@@ -1 +1 @@
-{"version":3,"file":"managed-process.js","sourceRoot":"","sources":["../../src/run/managed-process.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"managed-process.js","sourceRoot":"","sources":["../../src/run/managed-process.ts"],"names":[],"mappings":"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"}

package/dist/run/realm.d.ts

@@ -56,7 +56,7 @@ export declare class RealmManager {
      */
     adopt(registration: ModuleRegistration): Realm;
     /**
-     * A test's hooks of one kind in execution order (spec 11-lifecycle.md).
+     * A test's hooks of one kind in execution order.
      * `beforeEach` runs outer scope to inner, each scope's hooks in declaration
      * order, wherever in the file a scope's hooks were declared relative to the
      * test or to nested groups. `afterEach` mirrors it: inner scope to outer,
@@ -69,7 +69,7 @@ export declare class RealmManager {
      * Closes every entered scope that none of `remaining` (the pairs still to
      * run in this realm) belongs to, innermost first, running its afterAll
      * hooks in reverse declaration order. A scope's afterAll therefore runs
-     * when its last runnable member leaves it (spec 11-lifecycle.md), not when
+     * when its last runnable member leaves it, not when
      * the file ends: one describe's teardown never runs after a sibling's tests.
      *
      * Returns the first afterAll failure. Every failure is a run error, and the

package/dist/run/realm.js

@@ -46,7 +46,7 @@ export class RealmManager {
         return { registration, testsByKey, entered: new Map() };
     }
     /**
-     * A test's hooks of one kind in execution order (spec 11-lifecycle.md).
+     * A test's hooks of one kind in execution order.
      * `beforeEach` runs outer scope to inner, each scope's hooks in declaration
      * order, wherever in the file a scope's hooks were declared relative to the
      * test or to nested groups. `afterEach` mirrors it: inner scope to outer,
@@ -87,7 +87,7 @@ export class RealmManager {
      * Closes every entered scope that none of `remaining` (the pairs still to
      * run in this realm) belongs to, innermost first, running its afterAll
      * hooks in reverse declaration order. A scope's afterAll therefore runs
-     * when its last runnable member leaves it (spec 11-lifecycle.md), not when
+     * when its last runnable member leaves it, not when
      * the file ends: one describe's teardown never runs after a sibling's tests.
      *
      * Returns the first afterAll failure. Every failure is a run error, and the

package/dist/run/runner.d.ts

@@ -34,7 +34,7 @@ export interface RunOptions {
     /** Cancellation: the running test ends, its teardown runs, the run finishes as `interrupted`. */
     interruptSignal?: AbortSignal | undefined;
     /**
-     * Forced cancellation: every worker disposes its backend at once instead
+     * Forced cancellation: every worker disposes its engine at once instead
      * of finishing its test, and is killed after the cleanup budget. Counts as
      * an interrupt on its own. The runner never handles process signals itself;
      * the CLI's Ctrl-C ladder (`cli/signals.ts`) feeds these two.
@@ -43,6 +43,28 @@ export interface RunOptions {
     /** Structured, JSON-serializable run events for embedding hosts. */
     onEvent?: RunEventSink | undefined;
 }
+/** The selection flags of `run`, without anything that would start a process. */
+export type ListOptions = Pick<RunOptions, 'cwd' | 'configPath' | 'files' | 'tags' | 'tagMode' | 'targetIds' | 'passWithNoTests' | 'rawConfig' | 'env'>;
+/** One test-target pair the runner would report, as `e2e list` prints it. */
+export interface ListedPair {
+    readonly file: string;
+    readonly title: string;
+    readonly titlePath: readonly string[];
+    readonly kind: 'test' | 'setup';
+    readonly target: string;
+    readonly disposition: 'run' | 'skip';
+    readonly skipReason?: string;
+}
+/**
+ * Collects and selects like `run` and stops there: no app process, no engine
+ * prepare, no worker. The pairs are the ones `run` would report, in report
+ * order; pairs the selection filtered out are left out, as the list reporter
+ * leaves them out. Config, collection, and selection failures throw the same
+ * classified error `run` would record.
+ */
+export declare function list(options?: ListOptions): Promise<{
+    pairs: ListedPair[];
+}>;
 export interface RunOutcome {
     exitCode: RunExitCode;
     status: 'passed' | 'failed' | 'error' | 'interrupted';

package/dist/run/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/run/runner.ts"],"names":[],"mappings":"AAAA,8EAA8E;AA4B9E,OAAO,EAA+B,KAAK,eAAe,EAAyB,MAAM,oBAAoB,CAAC;AAM9G,OAAO,EAAwC,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAExG,OAAO,KAAK,EAAE,YAAY,EAA+B,MAAM,cAAc,CAAC;AAK9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACtC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrC,OAAO,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;IACpC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC1C,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,GAAG,SAAS,CAAC;IAC/D,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IACpC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,iGAAiG;IACjG,eAAe,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C;;;;;OAKG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,oEAAoE;IACpE,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAC;IACtD,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,2FAA2F;IAC3F,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,gFAAgF;IAChF,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;CAClC;AASD,yEAAyE;AACzE,wBAAsB,GAAG,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAyavE"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/run/runner.ts"],"names":[],"mappings":"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"}