@itmetsam/samurai-framework 0.10.0 → 0.12.1

package/dist/runner/worker-pool.js

@@ -0,0 +1,275 @@
+/** How long a busy worker may take to wind down after an abort before it is killed */
+const GRACE_MS = 2000;
+/** Workers that die before they are ready this many times in a row fail the run, instead of being replaced for ever */
+const STARTUP_ATTEMPTS = 3;
+/**
+ * A fixed cap of worker processes that take items from one shared queue.
+ * Workers start when there is work; `run()` can be called several times at
+ * once and all calls share the cap.
+ */
+export class WorkerPool {
+    constructor(options) {
+        this.options = options;
+        this.queue = [];
+        this.slots = new Map();
+        this.calls = new Set();
+        this.timers = new Set();
+        this.nextId = 0;
+        /** Workers in a row that exited before they were ready */
+        this.startupFailures = 0;
+        this.disposed = false;
+    }
+    /** Results in item order; may be called several times at once (flows): all calls share the cap */
+    run(items, hooks = {}) {
+        if (this.disposed) {
+            return Promise.reject(new Error("WorkerPool.run(): the pool is disposed"));
+        }
+        return new Promise((resolve, reject) => {
+            const call = {
+                results: new Array(items.length),
+                left: items.length,
+                hooks,
+                aborted: false,
+                resolve,
+                reject,
+                cleanup: () => { },
+            };
+            if (items.length === 0)
+                return resolve([]);
+            this.calls.add(call);
+            items.forEach((item, at) => this.queue.push({ item, call, at }));
+            const { signal } = hooks;
+            if (signal) {
+                const onAbort = () => this.abort(call);
+                signal.addEventListener("abort", onAbort, { once: true });
+                call.cleanup = () => signal.removeEventListener("abort", onAbort);
+                if (signal.aborted)
+                    return this.abort(call);
+            }
+            this.pump();
+        });
+    }
+    /** Tells every worker to exit and kills it; safe to call twice */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.queue.length = 0;
+        this.stopWorkers(true);
+        this.rejectAll(new Error("WorkerPool.dispose(): the pool was disposed during a run"));
+    }
+    /** Hands queued items to ready workers, then starts workers for what is left */
+    pump() {
+        if (this.disposed)
+            return;
+        for (const slot of [...this.slots.values()]) {
+            if (!slot.ready || slot.busy)
+                continue;
+            const at = this.nextEligible();
+            if (at < 0)
+                break;
+            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();
+        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))
+            index++;
+        return index;
+    }
+    start(index) {
+        const init = { ...this.options.init, workerIndex: index };
+        let handle;
+        try {
+            handle = this.options.factory(init);
+        }
+        catch (error) {
+            this.fatal(error instanceof Error ? error.message : String(error));
+            return false;
+        }
+        const slot = { index, handle, ready: false };
+        this.slots.set(index, slot);
+        handle.onMessage((message) => this.onMessage(slot, message));
+        handle.onExit((code) => this.onExit(slot, code));
+        handle.send({ type: "init", init });
+        return true;
+    }
+    dispatch(slot, entry) {
+        const id = this.nextId++;
+        slot.busy = { id, entry, startTime: Date.now() };
+        slot.handle.send({ type: "run", id, item: entry.item });
+    }
+    onMessage(slot, message) {
+        if (this.slots.get(slot.index) !== slot)
+            return;
+        const { busy } = slot;
+        switch (message.type) {
+            case "ready":
+                slot.ready = true;
+                this.startupFailures = 0;
+                return this.pump();
+            case "fatal":
+                return this.fatal(message.message);
+            case "test-start":
+                if (busy?.id !== message.id)
+                    return;
+                busy.startTime = Date.now();
+                return this.emit(busy.entry.call, {
+                    type: "test-start",
+                    item: busy.entry.item,
+                    worker: slot.index,
+                });
+            case "test-end":
+                if (busy?.id !== message.id)
+                    return;
+                slot.busy = undefined;
+                return this.finish(slot, busy.entry, message.result);
+        }
+    }
+    onExit(slot, code) {
+        if (this.slots.get(slot.index) !== slot)
+            return;
+        this.slots.delete(slot.index);
+        const { busy } = slot;
+        if (!slot.ready && ++this.startupFailures >= STARTUP_ATTEMPTS) {
+            return this.fatal(`The worker process exited before it was ready (code ${code})`);
+        }
+        if (busy) {
+            const { item, call } = busy.entry;
+            const message = call.aborted
+                ? "Run aborted"
+                : `The worker process exited (code ${code})`;
+            this.finish(slot, busy.entry, failure(item, message, busy.startTime));
+        }
+        else {
+            this.pump();
+        }
+    }
+    /** 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 };
+        this.emit(entry.call, {
+            type: "test-end",
+            item: entry.item,
+            worker: slot.index,
+            result: stamped,
+        });
+        this.settle(entry, stamped);
+        this.pump();
+    }
+    settle({ call, at }, result) {
+        call.results[at] = result;
+        if (--call.left > 0)
+            return;
+        call.cleanup();
+        this.calls.delete(call);
+        call.resolve(call.results);
+    }
+    emit(call, event) {
+        try {
+            call.hooks.onEvent?.(event);
+        }
+        catch {
+            // a listener's failure must not stop the run
+        }
+    }
+    /** 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 (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"));
+        }
+        for (const slot of this.slots.values()) {
+            const busy = slot.busy;
+            if (busy?.entry.call !== call)
+                continue;
+            slot.handle.send({ type: "abort" });
+            const timer = setTimeout(() => {
+                this.timers.delete(timer);
+                if (slot.busy === busy)
+                    slot.handle.kill();
+            }, this.options.graceMs ?? GRACE_MS);
+            timer.unref();
+            this.timers.add(timer);
+        }
+    }
+    fatal(message) {
+        this.queue.length = 0;
+        this.stopWorkers(false);
+        this.rejectAll(new Error(message));
+    }
+    rejectAll(error) {
+        const calls = [...this.calls];
+        this.calls.clear();
+        for (const call of calls) {
+            call.cleanup();
+            call.reject(error);
+        }
+    }
+    /** Forgets every worker, then kills it, so their exits are not taken for crashes */
+    stopWorkers(sayExit) {
+        for (const timer of this.timers)
+            clearTimeout(timer);
+        this.timers.clear();
+        const slots = [...this.slots.values()];
+        this.slots.clear();
+        for (const { handle } of slots) {
+            if (sayExit)
+                handle.send({ type: "exit" });
+            handle.kill();
+        }
+    }
+}
+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-process.d.ts

@@ -0,0 +1,6 @@
+import type { WorkerFactory } from "./worker-protocol.js";
+/**
+ * Starts each worker as a child process of this one and talks to it over the IPC channel; the pool sends `init`.
+ * A worker leads its own process group (not on Windows), so that when it exits, its browser goes with it.
+ */
+export declare function processWorkerFactory(): WorkerFactory;

package/dist/runner/worker-process.js

@@ -0,0 +1,54 @@
+import { fork } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/** The worker entry: `worker.js` in `dist/`, `worker.ts` when running from the sources under tsx */
+function workerEntry() {
+    const compiled = fileURLToPath(new URL("./worker.js", import.meta.url));
+    if (existsSync(compiled))
+        return { file: compiled, execArgv: [] };
+    return {
+        file: fileURLToPath(new URL("./worker.ts", import.meta.url)),
+        // Resolved from here, not from the project folder: the sources run from a checkout that has tsx
+        execArgv: ["--import", import.meta.resolve("tsx")],
+    };
+}
+/** Ends a worker and everything it started (its browser, chromedriver) that is still running: a worker that dies leaves them behind */
+function killGroup(pid) {
+    if (pid === undefined || process.platform === "win32")
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // nothing of the group is left
+    }
+}
+/**
+ * Starts each worker as a child process of this one and talks to it over the IPC channel; the pool sends `init`.
+ * A worker leads its own process group (not on Windows), so that when it exits, its browser goes with it.
+ */
+export function processWorkerFactory() {
+    return () => {
+        const { file, execArgv } = workerEntry();
+        // A worker's logs go to the same stderr; stdout stays the main process's (the `--json` output)
+        const child = fork(file, [], {
+            execArgv,
+            detached: process.platform !== "win32",
+            stdio: ["ignore", "inherit", "inherit", "ipc"],
+        });
+        // A write to a worker that already died fails here; its `exit` event follows and is what the pool acts on
+        child.on("error", () => { });
+        return {
+            send: (message) => void child.send(message),
+            onMessage: (listener) => void child.on("message", (message) => listener(message)),
+            onExit: (listener) => void child.on("exit", (code) => {
+                killGroup(child.pid);
+                listener(code);
+            }),
+            kill: () => {
+                killGroup(child.pid);
+                child.kill("SIGKILL");
+            },
+        };
+    };
+}

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

@@ -0,0 +1,67 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { TestResult } from "../types/test.js";
+/** One test in one browser: what a worker is asked to run */
+export interface WorkItem {
+    /** Position in the run, so results can be listed in the order the tests were selected */
+    index: number;
+    /** The spec file, absolute */
+    file: string;
+    /** The test's full name */
+    testName: string;
+    browser: SupportedBrowser;
+    /** Items with the same key never run at the same time */
+    serialKey?: string;
+}
+/** What a worker needs to start: the project and the settings that are the same for every test */
+export interface WorkerInit {
+    projectDir: string;
+    dataDir?: string;
+    environment?: string;
+    timeout?: number;
+    expectTimeout?: number;
+    headless?: boolean;
+    /** Where the run's report goes when it is not the default; screenshots are kept beside it */
+    reportPath?: string;
+    /** Spec files to import, absolute */
+    files: string[];
+    /** 0 for the first worker; picks the worker's browser port and profile folder */
+    workerIndex: number;
+    /** The debugging port of worker 0; worker N uses this plus N */
+    basePort: number;
+}
+/** Messages from the pool to a worker */
+export type ToWorker = {
+    type: "init";
+    init: WorkerInit;
+} | {
+    type: "run";
+    id: number;
+    item: WorkItem;
+} | {
+    type: "abort";
+} | {
+    type: "exit";
+};
+/** Messages from a worker to the pool */
+export type FromWorker = {
+    type: "ready";
+} | {
+    type: "test-start";
+    id: number;
+} | {
+    type: "test-end";
+    id: number;
+    result: TestResult;
+} | {
+    type: "fatal";
+    message: string;
+};
+/** A running worker, whatever it is made of (a child process, or a fake in tests) */
+export interface WorkerHandle {
+    send(message: ToWorker): void;
+    onMessage(listener: (message: FromWorker) => void): void;
+    onExit(listener: (code: number | null) => void): void;
+    kill(): void;
+}
+/** Starts a worker; the pool sends the same `init` as a message once the handle exists */
+export type WorkerFactory = (init: WorkerInit) => WorkerHandle;

package/dist/runner/worker-protocol.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,7 @@
+import type { WorkerSession } from "./worker.js";
+import type { WorkerInit } from "./worker-protocol.js";
+/**
+ * Opens the project for a worker and keeps it open until `close`: `withProject` holds the config, environment
+ * and secrets in place for as long as its callback runs, so the callback waits for the close
+ */
+export declare function openSession(init: WorkerInit): Promise<WorkerSession>;

package/dist/runner/worker-session.js

@@ -0,0 +1,60 @@
+import { workerProfileDir } from "../browser/launch-flags.js";
+import { withProject } from "./project.js";
+import TestReporter from "./reporter.js";
+import { runOneTest } from "./run-test.js";
+import { loadSpecs } from "./select.js";
+/**
+ * Opens the project for a worker and keeps it open until `close`: `withProject` holds the config, environment
+ * and secrets in place for as long as its callback runs, so the callback waits for the close
+ */
+export function openSession(init) {
+    const { workerIndex, basePort, headless } = init;
+    const port = basePort + workerIndex;
+    let release = () => { };
+    const released = new Promise((resolve) => (release = resolve));
+    return new Promise((resolve, reject) => {
+        const finished = withProject({
+            projectDir: init.projectDir,
+            ...(init.dataDir !== undefined && { dataDir: init.dataDir }),
+            ...(init.environment !== undefined && {
+                environment: init.environment,
+            }),
+            ...(init.timeout !== undefined && { timeout: init.timeout }),
+            ...(init.expectTimeout !== undefined && {
+                expectTimeout: init.expectTimeout,
+            }),
+            ...(headless !== undefined && { headless }),
+        }, async (run) => {
+            const loaded = await loadSpecs(init.files);
+            resolve({
+                tests: loaded.all,
+                async runTest(test, browser, signal, onEvent) {
+                    const reporter = new TestReporter({
+                        environment: run.settings.environment,
+                        browsers: [browser],
+                        output: false,
+                        onEvent,
+                    });
+                    await runOneTest(test, browser, run, {
+                        ...(headless !== undefined && { headless }),
+                        ...(init.reportPath !== undefined && {
+                            reportPath: init.reportPath,
+                        }),
+                        port,
+                        signal,
+                    }, loaded.srcDir, reporter, {
+                        port,
+                        profileDir: workerProfileDir(browser, workerIndex),
+                        workerIndex,
+                    });
+                },
+                async close() {
+                    release();
+                    await finished;
+                },
+            });
+            await released;
+        });
+        finished.catch(reject);
+    });
+}

package/dist/runner/worker.d.ts

@@ -0,0 +1,26 @@
+import type { RegisteredTestCase } from "../types/test.js";
+import type { SupportedBrowser } from "../types/browser.js";
+import type { RunEvent } from "./reporter.js";
+import type { FromWorker, ToWorker, WorkerInit } from "./worker-protocol.js";
+/** A project opened in this process, with its specs imported once */
+export interface WorkerSession {
+    tests: readonly RegisteredTestCase[];
+    /** Runs one test; `onEvent` gets the reporter's events for it. Aborting `signal` ends the test as aborted */
+    runTest(test: RegisteredTestCase, browser: SupportedBrowser, signal: AbortSignal, onEvent: (event: RunEvent) => void): Promise<void>;
+    /** Ends the project's session */
+    close(): Promise<void>;
+}
+export interface WorkerDeps {
+    open(init: WorkerInit): Promise<WorkerSession>;
+    exit(): void;
+}
+/** Where messages come from and go to: the IPC channel of the process, or a stand-in in tests */
+export interface WorkerChannel {
+    send(message: FromWorker): void;
+    onMessage(listener: (message: ToWorker) => void): void;
+}
+/**
+ * Answers the pool's messages: opens the project on `init`, runs the tests it is sent one at a time, aborts
+ * the running one on `abort` and leaves on `exit`. Whatever goes wrong outside a test is reported as `fatal`.
+ */
+export declare function handleMessages(channel: WorkerChannel, { open, exit }: WorkerDeps): void;

package/dist/runner/worker.js

@@ -0,0 +1,121 @@
+import { fileURLToPath } from "node:url";
+const failedResult = (item, worker, message) => ({
+    name: item.testName,
+    file: item.file,
+    browser: item.browser,
+    worker,
+    status: "failed",
+    startTime: performance.now(),
+    duration: 0,
+    message,
+    type: "error",
+});
+/**
+ * Answers the pool's messages: opens the project on `init`, runs the tests it is sent one at a time, aborts
+ * the running one on `abort` and leaves on `exit`. Whatever goes wrong outside a test is reported as `fatal`.
+ */
+export function handleMessages(channel, { open, exit }) {
+    let session;
+    let workerIndex = 0;
+    let current;
+    // Messages other than `abort` are handled in the order they arrive, each after the one before it
+    let queue = Promise.resolve();
+    const init = async (message) => {
+        workerIndex = message.workerIndex;
+        session = await open(message);
+        channel.send({ type: "ready" });
+    };
+    const run = async (id, item) => {
+        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);
+        if (!test) {
+            const message = `Test "${item.testName}" was not found in ${item.file}`;
+            channel.send({
+                type: "test-end",
+                id,
+                result: failedResult(item, workerIndex, message),
+            });
+            return;
+        }
+        let ended = false;
+        current = new AbortController();
+        try {
+            await session.runTest(test, item.browser, current.signal, (event) => {
+                if (event.type !== "test-end")
+                    return;
+                ended = true;
+                channel.send({
+                    type: "test-end",
+                    id,
+                    result: { ...event.result, worker: workerIndex },
+                });
+            });
+        }
+        finally {
+            current = undefined;
+        }
+        if (!ended) {
+            const message = "The test ended without a result";
+            channel.send({
+                type: "test-end",
+                id,
+                result: failedResult(item, workerIndex, message),
+            });
+        }
+    };
+    const leave = async () => {
+        await session?.close();
+        exit();
+    };
+    const enqueue = (work) => {
+        queue = queue.then(work).catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            channel.send({ type: "fatal", message });
+        });
+    };
+    channel.onMessage((message) => {
+        switch (message.type) {
+            case "init":
+                return enqueue(() => init(message.init));
+            case "run":
+                return enqueue(() => run(message.id, message.item));
+            case "abort":
+                return current?.abort(new Error("Run aborted"));
+            case "exit":
+                return enqueue(leave);
+        }
+    });
+}
+/** Runs as the child process the pool forks: messages arrive over the IPC channel */
+async function main() {
+    // Specs are TypeScript. Under tsx (from the sources) this is already so; from `dist/` tsx is registered here
+    if (!process.execArgv.some((arg) => arg.includes("tsx"))) {
+        try {
+            const { register } = await import("tsx/esm/api");
+            register();
+        }
+        catch (err) {
+            if (err.code !== "ERR_MODULE_NOT_FOUND")
+                throw err;
+            process.stderr.write("samurai loads TypeScript specs with tsx\n");
+            process.exit(2);
+        }
+    }
+    const { openSession } = await import("./worker-session.js");
+    let listener = () => { };
+    handleMessages({
+        send: (message) => void process.send?.(message),
+        onMessage: (next) => (listener = next),
+    }, { open: openSession, exit: () => process.exit(0) });
+    process.on("message", (message) => listener(message));
+    // The main process is gone: end the running test, close and leave
+    process.on("disconnect", () => {
+        listener({ type: "abort" });
+        listener({ type: "exit" });
+    });
+}
+if (process.send && process.argv[1] === fileURLToPath(import.meta.url)) {
+    void main();
+}

package/dist/runner/workers-option.d.ts

@@ -0,0 +1,15 @@
+export interface WorkersInput {
+    /** The command line's `--workers` (or the `workers` run option) */
+    flag?: number | string | undefined;
+    /** `SAMURAI_WORKERS` */
+    env?: string | undefined;
+    /** The config's `workers` */
+    config?: number | string | undefined;
+    /** The number of CPUs; for tests. @default the machine's */
+    cpus?: number;
+}
+/**
+ * How many workers a run uses: the flag, else `SAMURAI_WORKERS`, else the config's `workers`, else half the CPUs.
+ * A percentage is a share of the CPUs. At least 1.
+ */
+export declare function resolveWorkers({ flag, env, config, cpus, }: WorkersInput): number;

package/dist/runner/workers-option.js

@@ -0,0 +1,22 @@
+import { availableParallelism } from "node:os";
+import { parseWorkers } from "../config/workers.js";
+/**
+ * How many workers a run uses: the flag, else `SAMURAI_WORKERS`, else the config's `workers`, else half the CPUs.
+ * A percentage is a share of the CPUs. At least 1.
+ */
+export function resolveWorkers({ flag, env, config, cpus = availableParallelism(), }) {
+    const fromEnv = env?.trim() ? env : undefined;
+    const [value, where] = flag !== undefined
+        ? [flag, "--workers"]
+        : fromEnv !== undefined
+            ? [fromEnv, "SAMURAI_WORKERS"]
+            : config !== undefined
+                ? [config, "workers"]
+                : [undefined, ""];
+    if (value === undefined)
+        return Math.max(1, Math.floor(cpus / 2));
+    const parsed = parseWorkers(value, where);
+    return "count" in parsed
+        ? parsed.count
+        : Math.max(1, Math.floor((cpus * parsed.percent) / 100));
+}

package/dist/script/call-function.d.ts

@@ -4,14 +4,8 @@ import { type Arg } from "./serialize.js";
 export interface CallOptions {
     /** @default true. The auto-wait probes pass false */
     awaitPromise?: boolean;
-    /**
-     * "root" keeps a handle alive in the browser; the result then comes back as a `RemoteObject`
-     * carrying it, and the caller must `disown` it. @default "none"
-     */
-    ownership?: "none" | "root";
-    /** Named sandbox realm to run in (see the preload-scripts spec) */
+    /** Named sandbox realm to run in */
     sandbox?: string;
-    thisArg?: Arg;
 }
 /** The page function threw */
 export declare class ScriptError extends Error {
@@ -30,5 +24,3 @@ export declare class ScriptSerializationError extends Error {
 export declare function toFunctionDeclaration(fn: string | ((...args: any[]) => unknown)): string;
 /** Calls `fn` in the page with serialized arguments and returns its deserialized result */
 export declare function callFunction<T = unknown>(connector: BiDiConnector, context: string, fn: string | ((...args: any[]) => unknown), args?: Arg[], options?: CallOptions): Promise<T>;
-/** Releases handles obtained with `ownership: "root"`; a handle that is already gone is fine */
-export declare function disown(connector: BiDiConnector, context: string, handles: string[]): Promise<void>;