@itmetsam/samurai-framework 0.21.5 → 0.22.1

package/dist/runner/wait-for-url.js

@@ -0,0 +1,65 @@
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+/** Pause between two probes */
+const POLL_MS = 100;
+/** Resolves true once `url` answers with a status from 200 to 403 (a server that is up but wants a login counts) */
+function urlAnswers(url, options = {}) {
+    return new Promise((resolve) => {
+        const secure = new URL(url).protocol === "https:";
+        const request = (secure ? https : http).get(url, {
+            timeout: 2000,
+            headers: { Accept: "text/html,application/json,*/*;q=0.8" },
+            ...(secure && { rejectUnauthorized: !options.ignoreHTTPSErrors }),
+        }, (response) => {
+            response.resume();
+            const status = response.statusCode ?? 0;
+            resolve(status >= 200 && status <= 403);
+        });
+        request.on("timeout", () => request.destroy());
+        request.on("error", () => resolve(false));
+    });
+}
+/** Resolves true when something on this machine accepts a TCP connection on `port` (IPv4 or IPv6 `localhost`) */
+function portAnswers(port) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ port, host: "localhost", timeout: 2000 });
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("timeout", () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.once("error", () => resolve(false));
+    });
+}
+/** One probe of `target` */
+export function answers(target) {
+    return "url" in target
+        ? urlAnswers(target.url, {
+            ...(target.ignoreHTTPSErrors && { ignoreHTTPSErrors: true }),
+        })
+        : portAnswers(target.port);
+}
+/** The target as text for messages: the URL, or `localhost:<port>` */
+export function describeTarget(target) {
+    return "url" in target ? target.url : `localhost:${target.port}`;
+}
+/**
+ * Probes `target` until it answers. Resolves "ready", or "timeout" after `timeout` ms, or "aborted" when `signal`
+ * fires or `stopped()` turns true (the caller saw the server die)
+ */
+export async function waitUntilReady(target, options) {
+    const deadline = Date.now() + options.timeout;
+    for (;;) {
+        if (options.signal?.aborted || options.stopped?.())
+            return "aborted";
+        if (await answers(target))
+            return "ready";
+        if (Date.now() >= deadline)
+            return "timeout";
+        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+    }
+}

package/dist/runner/web-server.d.ts

@@ -0,0 +1,16 @@
+import type { WebServerConfig } from "../types/config.js";
+/** The servers of a run, started */
+export interface RunningServers {
+    /** Where the first server with a `url` or `port` answers: the base URL when none is configured */
+    baseURL?: string;
+    /** Stops every server this run started (not the ones it reused). Safe to call twice */
+    stop(): Promise<void>;
+}
+/**
+ * Starts the servers one after the other and waits for each. A server that fails to start stops the ones already
+ * started and throws `webServer(): what is wrong`, with the last lines of its output.
+ */
+export declare function startWebServers(servers: readonly WebServerConfig[], context: {
+    projectDir: string;
+    signal?: AbortSignal | undefined;
+}): Promise<RunningServers>;

package/dist/runner/web-server.js

@@ -0,0 +1,165 @@
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+import { DEFAULT_GRACEFUL_TIMEOUT, DEFAULT_WEB_SERVER_TIMEOUT, } from "../config/web-server-options.js";
+import logger from "../logger/index.js";
+import { OutputTail } from "./output-tail.js";
+import { answers, describeTarget, waitUntilReady, } from "./wait-for-url.js";
+const fail = (problem) => {
+    throw new Error(`webServer(): ${problem}`);
+};
+const windows = process.platform === "win32";
+function targetOf(server) {
+    return server.url !== undefined
+        ? {
+            url: server.url,
+            ...(server.ignoreHTTPSErrors && { ignoreHTTPSErrors: true }),
+        }
+        : { port: server.port };
+}
+/** The base URL a server stands for: its URL's origin, or `http://localhost:<port>` */
+function baseURLOf(server) {
+    return server.url !== undefined
+        ? new URL(server.url).origin
+        : `http://localhost:${server.port}`;
+}
+function signalGroup(pid, signal, child) {
+    try {
+        if (windows) {
+            if (signal !== 0)
+                spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"]);
+            return child?.exitCode === null;
+        }
+        process.kill(-pid, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+class StartedServer {
+    constructor(child, server) {
+        this.child = child;
+        this.server = server;
+        this.exited = false;
+        this.exitText = "";
+        this.onProcessExit = () => {
+            if (this.child.pid !== undefined)
+                signalGroup(this.child.pid, "SIGKILL", this.child);
+        };
+        this.tail = new OutputTail(20, Object.values(server.env ?? {}));
+        for (const [stream, mode, out] of [
+            [child.stdout, server.stdout ?? "ignore", process.stdout],
+            [child.stderr, server.stderr ?? "pipe", process.stderr],
+        ])
+            stream?.on("data", (chunk) => {
+                this.tail.add(chunk);
+                if (mode === "pipe")
+                    out.write(chunk);
+            });
+        this.exitPromise = new Promise((resolve) => {
+            child.once("exit", (code, signal) => {
+                this.exited = true;
+                this.exitText =
+                    code !== null ? `code ${code}` : `signal ${String(signal)}`;
+                resolve();
+            });
+            child.once("error", (error) => {
+                this.exited = true;
+                this.exitText = `error: ${error.message}`;
+                resolve();
+            });
+        });
+        process.once("exit", this.onProcessExit);
+    }
+    hasExited() {
+        return this.exited;
+    }
+    describeExit() {
+        return this.exitText;
+    }
+    /** SIGTERM-style signal to the group, then SIGKILL for what is left after the grace period */
+    stop() {
+        this.stopping ??= this.stopNow();
+        return this.stopping;
+    }
+    async stopNow() {
+        const pid = this.child.pid;
+        const { signal = "SIGTERM", timeout = DEFAULT_GRACEFUL_TIMEOUT } = this.server.gracefulShutdown ?? {};
+        if (pid !== undefined) {
+            if (timeout > 0 && !windows) {
+                signalGroup(pid, signal);
+                const deadline = Date.now() + timeout;
+                while (Date.now() < deadline &&
+                    (!this.exited || signalGroup(pid, 0, this.child)))
+                    await new Promise((resolve) => setTimeout(resolve, 50));
+            }
+            signalGroup(pid, "SIGKILL", this.child);
+            await Promise.race([
+                this.exitPromise,
+                new Promise((resolve) => setTimeout(resolve, 2000)),
+            ]);
+        }
+        process.off("exit", this.onProcessExit);
+    }
+}
+async function startOne(server, context) {
+    const target = targetOf(server);
+    const name = describeTarget(target);
+    if (await answers(target)) {
+        if (server.reuseExistingServer)
+            return undefined;
+        fail(`${name} is already in use: stop what runs there, or set reuseExistingServer: true`);
+    }
+    logger.verbose("Starting web server for %s", name);
+    const child = spawn(server.command, {
+        shell: true,
+        cwd: path.resolve(context.projectDir, server.cwd ?? "."),
+        env: { ...process.env, ...server.env },
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: !windows,
+    });
+    const started = new StartedServer(child, server);
+    const timeout = server.timeout ?? DEFAULT_WEB_SERVER_TIMEOUT;
+    const verdict = await waitUntilReady(target, {
+        timeout,
+        ...(context.signal && { signal: context.signal }),
+        stopped: () => started.hasExited(),
+    });
+    if (verdict === "ready")
+        return started;
+    // Capture what the server printed before it is stopped
+    const exited = started.hasExited();
+    const how = exited ? started.describeExit() : "";
+    await started.stop();
+    const output = started.tail.text();
+    const log = output === "" ? "" : `\nLast output:\n${output}`;
+    if (verdict === "aborted" && !exited)
+        return fail(`aborted while waiting for ${name}`);
+    if (exited)
+        fail(`the process exited (${how}) before ${name} was ready${log}`);
+    return fail(`timed out after ${timeout}ms waiting for ${name}${log}`);
+}
+/**
+ * Starts the servers one after the other and waits for each. A server that fails to start stops the ones already
+ * started and throws `webServer(): what is wrong`, with the last lines of its output.
+ */
+export async function startWebServers(servers, context) {
+    const started = [];
+    const stop = async () => {
+        await Promise.all([...started].reverse().map((s) => s.stop()));
+    };
+    let baseURL;
+    try {
+        for (const server of servers) {
+            const running = await startOne(server, context);
+            if (running)
+                started.push(running);
+            baseURL ??= baseURLOf(server);
+        }
+    }
+    catch (error) {
+        await stop();
+        throw error;
+    }
+    return { ...(baseURL !== undefined && { baseURL }), stop };
+}

package/dist/runner/worker-pool.d.ts

@@ -36,6 +36,7 @@ export declare class WorkerPool {
     private readonly slots;
     private readonly calls;
     private readonly timers;
+    private readonly units;
     private nextId;
     /** Workers in a row that exited before they were ready */
     private startupFailures;
@@ -52,18 +53,25 @@ export declare class WorkerPool {
     private sendHome;
     /** Hands queued items to ready workers, then starts workers for what is left */
     private pump;
-    private busyKeys;
-    /** The queue position of the first item whose serial key is not running */
-    private nextEligible;
-    /** How many queued items could run at the same time right now */
-    private eligibleCount;
     private freeIndex;
     private start;
     private dispatch;
     private onMessage;
     private onExit;
+    /** The attempt a started item is on: the worker's own retry, or the attempt at its serial block */
+    private retryOf;
     /** Records an item's result, tells the listener, and gives the worker its next item */
     private finish;
+    private report;
+    /**
+     * An item of a serial block ended. After a failure the rest of the block is skipped; with retries the block
+     * starts over on a new worker first, and what its tests ended with is held until the last attempt is known.
+     */
+    private finishInBlock;
+    /** Reports what a block's tests ended with in its last attempt */
+    private release;
+    /** Puts the block back in the queue, from its first test, and tells the worker that ran it to leave */
+    private restartBlock;
     private settle;
     private emit;
     /** Fails the queued items of a call, asks its busy workers to stop, and kills the ones that do not */

package/dist/runner/worker-pool.js

@@ -1,3 +1,5 @@
+import { failedResult, serialSkipped, UnitState } from "./pool-units.js";
+import { eligibleCount, nextEligible } from "./pool-schedule.js";
 /** How long a busy worker may take to wind down after an abort before it is killed */
 const GRACE_MS = 2000;
 const SHUTDOWN_MS = 60000;
@@ -15,6 +17,7 @@ export class WorkerPool {
         this.slots = new Map();
         this.calls = new Set();
         this.timers = new Set();
+        this.units = new Map();
         this.nextId = 0;
         /** Workers in a row that exited before they were ready */
         this.startupFailures = 0;
@@ -95,51 +98,23 @@ export class WorkerPool {
         if (this.disposed)
             return;
         for (const slot of [...this.slots.values()]) {
-            if (!slot.ready || slot.busy)
+            if (!slot.ready || slot.busy || slot.retiring)
                 continue;
-            const at = this.nextEligible();
+            const at = nextEligible(this.queue, [...this.slots.values()], slot);
             if (at < 0)
-                break;
+                continue;
             const [entry] = this.queue.splice(at, 1);
             if (entry)
                 this.dispatch(slot, entry);
         }
         let starting = [...this.slots.values()].filter((s) => !s.ready).length;
-        const wanted = this.eligibleCount();
+        const wanted = eligibleCount(this.queue, [...this.slots.values()]);
         while (this.slots.size < this.options.workers && starting < wanted) {
             if (!this.start(this.freeIndex()))
                 return;
             starting++;
         }
     }
-    busyKeys() {
-        const keys = new Set();
-        for (const { busy } of this.slots.values()) {
-            const key = busy?.entry.item.serialKey;
-            if (key)
-                keys.add(key);
-        }
-        return keys;
-    }
-    /** The queue position of the first item whose serial key is not running */
-    nextEligible() {
-        const busy = this.busyKeys();
-        return this.queue.findIndex(({ item }) => !item.serialKey || !busy.has(item.serialKey));
-    }
-    /** How many queued items could run at the same time right now */
-    eligibleCount() {
-        const taken = this.busyKeys();
-        let count = 0;
-        for (const { item } of this.queue) {
-            if (item.serialKey) {
-                if (taken.has(item.serialKey))
-                    continue;
-                taken.add(item.serialKey);
-            }
-            count++;
-        }
-        return count;
-    }
     freeIndex() {
         let index = 0;
         while (this.slots.has(index))
@@ -165,6 +140,13 @@ export class WorkerPool {
     }
     dispatch(slot, entry) {
         const id = this.nextId++;
+        const { unit, serialKey } = entry.item;
+        if (unit) {
+            slot.unit = unit;
+            slot.unitKey = serialKey;
+            if (!this.units.has(unit))
+                this.units.set(unit, new UnitState(entry.call));
+        }
         slot.busy = { id, entry, startTime: Date.now() };
         slot.handle.send({ type: "run", id, item: entry.item });
     }
@@ -187,7 +169,7 @@ export class WorkerPool {
                     type: "test-start",
                     item: busy.entry.item,
                     worker: slot.index,
-                    ...(message.retry && { retry: message.retry }),
+                    ...this.retryOf(busy.entry, message.retry),
                 });
             case "test-end":
                 if (busy?.id !== message.id)
@@ -209,23 +191,84 @@ export class WorkerPool {
             const message = call.aborted
                 ? "Run aborted"
                 : `The worker process exited (code ${code})`;
-            this.finish(slot, busy.entry, failure(item, message, busy.startTime));
+            this.finish(slot, busy.entry, failedResult(item, message, busy.startTime));
         }
         else {
             this.pump();
         }
     }
+    /** The attempt a started item is on: the worker's own retry, or the attempt at its serial block */
+    retryOf({ item }, workerRetry) {
+        const retry = workerRetry || (item.serial ? this.units.get(item.unit)?.attempt : 0);
+        return retry ? { retry } : {};
+    }
     /** Records an item's result, tells the listener, and gives the worker its next item */
     finish(slot, entry, result) {
         const stamped = { ...result, worker: slot.index };
+        if (entry.item.serial)
+            this.finishInBlock(slot, entry, stamped);
+        else
+            this.report(entry, slot.index, stamped);
+        this.pump();
+    }
+    report(entry, worker, result) {
         this.emit(entry.call, {
             type: "test-end",
             item: entry.item,
-            worker: slot.index,
-            result: stamped,
+            worker,
+            result,
         });
-        this.settle(entry, stamped);
-        this.pump();
+        this.settle(entry, result);
+    }
+    /**
+     * An item of a serial block ended. After a failure the rest of the block is skipped; with retries the block
+     * starts over on a new worker first, and what its tests ended with is held until the last attempt is known.
+     */
+    finishInBlock(slot, entry, result) {
+        const state = this.units.get(entry.item.unit);
+        const retries = this.options.init.retries ?? 0;
+        if (retries === 0)
+            this.report(entry, slot.index, result);
+        else
+            state.hold(entry, result);
+        if (result.status !== "failed") {
+            const last = !this.queue.some((e) => e.item.unit === entry.item.unit);
+            if (last)
+                this.release(state);
+            return;
+        }
+        const aborted = entry.call.aborted || result.message === "Run aborted";
+        if (state.attempt < retries && !aborted && !this.disposed) {
+            return this.restartBlock(slot, state, entry, result);
+        }
+        this.release(state);
+        for (let i = 0; i < this.queue.length; i++) {
+            const next = this.queue[i];
+            if (next.item.unit !== entry.item.unit)
+                continue;
+            this.queue.splice(i--, 1);
+            this.report(next, slot.index, serialSkipped(next.item));
+        }
+    }
+    /** Reports what a block's tests ended with in its last attempt */
+    release(state) {
+        for (const { entry, result } of state.release())
+            this.report(entry, result.worker ?? 0, result);
+    }
+    /** Puts the block back in the queue, from its first test, and tells the worker that ran it to leave */
+    restartBlock(slot, state, failed, result) {
+        this.queue.unshift(...state.restart(failed, result));
+        slot.unit = slot.unitKey = undefined;
+        if (this.slots.get(slot.index) !== slot)
+            return;
+        slot.retiring = true;
+        slot.handle.send({ type: "exit" });
+        const timer = setTimeout(() => {
+            this.timers.delete(timer);
+            slot.handle.kill();
+        }, this.options.shutdownMs ?? SHUTDOWN_MS);
+        timer.unref();
+        this.timers.add(timer);
     }
     settle({ call, at }, result) {
         call.results[at] = result;
@@ -246,12 +289,15 @@ export class WorkerPool {
     /** Fails the queued items of a call, asks its busy workers to stop, and kills the ones that do not */
     abort(call) {
         call.aborted = true;
+        for (const state of this.units.values())
+            if (state.call === call)
+                this.release(state);
         for (let i = this.queue.length - 1; i >= 0; i--) {
             const entry = this.queue[i];
             if (entry?.call !== call)
                 continue;
             this.queue.splice(i, 1);
-            this.settle(entry, failure(entry.item, "Run aborted"));
+            this.settle(entry, failedResult(entry.item, "Run aborted"));
         }
         for (const slot of this.slots.values()) {
             const busy = slot.busy;
@@ -294,15 +340,3 @@ export class WorkerPool {
         }
     }
 }
-function failure(item, message, startTime = Date.now()) {
-    return {
-        name: item.testName,
-        file: item.file,
-        browser: item.browser,
-        status: "failed",
-        type: "error",
-        message,
-        startTime,
-        duration: Date.now() - startTime,
-    };
-}

package/dist/runner/worker-protocol.d.ts

@@ -9,8 +9,14 @@ export interface WorkItem {
     /** The test's full name */
     testName: string;
     browser: SupportedBrowser;
+    /** The group this run of the test is for (`--group`): its `use` applies and the result names it */
+    group?: string;
     /** Items with the same key never run at the same time */
     serialKey?: string;
+    /** Items with the same unit run one after the other on the same worker, in the order they are queued */
+    unit?: string;
+    /** The unit is a serial block: a failure skips the rest, and `retries` run the whole block again (the pool does it, not the worker) */
+    serial?: boolean;
     /** Where this test's screenshots go, instead of the run's `outputDir` (a flow gives each node its own) */
     outputDir?: string;
     /** The values the run supplies for the inputs tests declare (`runTests({ inputs })`) */
@@ -21,6 +27,8 @@ export interface WorkerInit {
     projectDir: string;
     dataDir?: string;
     environment?: string;
+    /** The run's base URL when no config sets one (it came from a web server): used where the config has none */
+    baseURL?: string;
     timeout?: number;
     expectTimeout?: number;
     headless?: boolean;

package/dist/runner/worker-session.js

@@ -3,6 +3,7 @@ import logger from "../logger/index.js";
 import { withProject } from "./project.js";
 import TestReporter from "./reporter.js";
 import { AllHooks } from "./all-hooks.js";
+import { WorkerFixtures } from "./fixture-worker.js";
 import { allHookFixtures } from "./fixtures.js";
 import { runOneTest } from "./run-test.js";
 import { runWithRetries } from "./retry.js";
@@ -29,12 +30,16 @@ export function openSession(init) {
             }),
             ...(headless !== undefined && { headless }),
         }, async (run) => {
+            if (run.settings.baseURL === undefined && init.baseURL !== undefined)
+                run.settings.baseURL = init.baseURL;
             const loaded = await loadSpecs(init.files);
             // The `beforeAll` hooks this worker ran: their `afterAll` hooks run when it closes
             const allHooks = new AllHooks({
                 timeout: run.settings.timeout,
                 fixtures: (browser) => allHookFixtures(run, browser, workerIndex),
             });
+            // The worker-scoped fixtures this worker set up: torn down when it closes
+            const workerFixtures = new WorkerFixtures(run.settings.timeout);
             resolve({
                 tests: loaded.all,
                 async runTest(test, browser, signal, onEvent, perTest = {}) {
@@ -56,17 +61,20 @@ export function openSession(init) {
                         port,
                         signal,
                     };
-                    await runWithRetries(test, browser, init.retries ?? 0, signal, (sink, attempt) => runOneTest(test, browser, run, options, loaded.srcDir, sink, {
+                    await runWithRetries(test, browser, perTest.retries ?? init.retries ?? 0, signal, (sink, attempt) => runOneTest(test, browser, run, options, loaded.srcDir, sink, {
                         port,
                         profileDir: workerProfileDir(browser, workerIndex),
                         workerIndex,
                         allHooks,
+                        workerFixtures,
                         attempt,
                     }), reporter);
                 },
                 async close() {
                     for (const error of await allHooks.closeAll())
                         logger.error("%s", error.message);
+                    for (const error of await workerFixtures.closeAll())
+                        logger.error("%s", error.message);
                     release();
                     await finished;
                 },

package/dist/runner/worker.d.ts

@@ -9,6 +9,8 @@ export interface WorkerSession {
     runTest(test: RegisteredTestCase, browser: SupportedBrowser, signal: AbortSignal, onEvent: (event: RunEvent) => void, options?: {
         outputDir?: string;
         inputs?: Record<string, string>;
+        /** Instead of the run's `retries` */
+        retries?: number;
     }): Promise<void>;
     /** Ends the project's session */
     close(): Promise<void>;

package/dist/runner/worker.js

@@ -3,6 +3,7 @@ const failedResult = (item, worker, message) => ({
     name: item.testName,
     file: item.file,
     browser: item.browser,
+    ...(item.group !== undefined && { group: item.group }),
     worker,
     status: "failed",
     startTime: performance.now(),
@@ -29,7 +30,10 @@ export function handleMessages(channel, { open, exit }) {
         if (!session)
             throw new Error("The worker was sent a test before it was initialised");
         channel.send({ type: "test-start", id });
-        const test = session.tests.find(({ file, name }) => file === item.file && name === item.testName);
+        const found = session.tests.find(({ file, name }) => file === item.file && name === item.testName);
+        const test = found && item.group !== undefined
+            ? { ...found, group: item.group }
+            : found;
         if (!test) {
             const message = `Test "${item.testName}" was not found in ${item.file}`;
             channel.send({
@@ -57,6 +61,8 @@ export function handleMessages(channel, { open, exit }) {
             }, {
                 ...(item.outputDir !== undefined && { outputDir: item.outputDir }),
                 ...(item.inputs !== undefined && { inputs: item.inputs }),
+                // The pool runs a whole serial block again, not the test
+                ...(item.serial && { retries: 0 }),
             });
         }
         finally {