@rightkit/qa 0.4.6 → 0.4.7

package/README.md

@@ -105,6 +105,29 @@ try {
 
 `freePort()` returns a free `127.0.0.1` port by binding port 0 and releasing it. Another process can take the port before use.
 
+## Dev-server launcher
+
+`startDevServer({ command, args?, cwd?, env?, shell?, windowsHide?, ports?, portFloor?, portEnv?, maxPortAttempts?, readiness })` starts a dev server hidden, gives it a port, and waits until it answers.
+
+- The port goes to the process as the environment variable `portEnv` (default `PORT`), and every `{port}` in `args` is replaced with it.
+- `readiness`: `urls` (an array, or a function of the port) that must each answer 2xx, or a `check(port)` predicate. `attemptTimeoutMs` bounds one request, `totalTimeoutMs` one launch's wait, `intervalMs` the delay between rounds.
+- Port choice: `ports` in order (a held port is skipped before anything is spawned on it); otherwise the first free port at or above `portFloor`, probed by binding; otherwise `freePort()`. A collision (EADDRINUSE in the output) moves to the next candidate.
+- Result: `{ pid, port, url, attempts, stop(), output() }`. `stop()` kills the whole process tree the launch started and reports `leftoverPids`.
+- A failed launch stops its whole tree before it throws `DevServerError` (`reason`, `pid`, `port`, `attempts`, `leftoverPids`, and a bounded `output` tail). The message includes the last 2 KB of output.
+
+```ts
+const dev = await startDevServer({
+  command: process.execPath,
+  args: [viteBin, "--host", "127.0.0.1", "--port", "{port}", "--strictPort"],
+  portFloor: 5173,
+  cwd: root,
+  env: { VITE_MAILRIGHT_QA: "1" },
+  readiness: { urls: (port) => [`http://127.0.0.1:${port}/`], attemptTimeoutMs: 2500, totalTimeoutMs: 20_000, intervalMs: 300 },
+});
+// ... run the tests against dev.url ...
+await dev.stop();
+```
+
 ## Keyboard keys
 
 `page.keyboard.press(chord)` accepts named keys (`Enter`, `Tab`, `Escape`, arrows, `Home`, `End`, `PageUp`, `PageDown`, `Backspace`, `Delete`, `Space`, `Shift`, `Control`, `Alt`, `Meta`), function keys `F1` through `F24`, letters, digits, and every printable US-layout symbol, including backslash.

package/dist/devserver.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Why a dev server failed to become ready. `port-in-use`: every candidate port was taken.
+ * `exited`: the process ended first. `timeout`: the total budget passed. `check-failed`: the
+ * caller's check threw. `start-failed`: the command could not be started.
+ */
+export type DevServerFailure = 'exited' | 'timeout' | 'port-in-use' | 'check-failed' | 'start-failed';
+export interface DevServerReadiness {
+    /**
+     * URLs that must each answer 2xx to a GET. Required unless `check` is given. A function receives
+     * the chosen port.
+     */
+    urls?: string[] | ((port: number) => string[]);
+    /** Bound for one request (or one `check` call). */
+    attemptTimeoutMs: number;
+    /** Bound for the readiness wait of one launch attempt. */
+    totalTimeoutMs: number;
+    /** Delay between rounds of probes. */
+    intervalMs: number;
+    /** Caller predicate used instead of the URL probe. True means ready. A throw fails the launch. */
+    check?: (port: number) => boolean | Promise<boolean>;
+}
+export interface DevServerOptions {
+    /** Executable to start, hidden by default. */
+    command: string;
+    /** Arguments; every `{port}` is replaced with the chosen port. */
+    args?: string[];
+    cwd?: string;
+    /** Merged over process.env. The chosen port is set under `portEnv`. */
+    env?: NodeJS.ProcessEnv;
+    /** Run through the platform shell (for .cmd shims such as npm on Windows). Default false. */
+    shell?: boolean;
+    /** Default true: no visible console window on Windows. */
+    windowsHide?: boolean;
+    /** Candidate ports, tried in order. A collision moves to the next one. */
+    ports?: number[];
+    /** Without `ports`: the first free port at or above this one is chosen (probed by binding). */
+    portFloor?: number;
+    /** Environment variable that receives the port. Default `PORT`. */
+    portEnv?: string;
+    /** Launch attempts before giving up on port collisions. Default 5. With `ports`, at most the list length. */
+    maxPortAttempts?: number;
+    readiness: DevServerReadiness;
+}
+export interface DevServerStopReport {
+    /** Pids this launch started that are still running after the stop. Empty when the tree is gone. */
+    leftoverPids: number[];
+}
+/** A dev server that is ready. The process was launched by this package and is stopped by `stop()`. */
+export interface DevServer {
+    pid: number;
+    port: number;
+    /** `http://127.0.0.1:<port>`. */
+    url: string;
+    /** Launch attempts it took, including the successful one. */
+    attempts: number;
+    /** Stops the whole process tree this launch started. Idempotent. */
+    stop(): Promise<DevServerStopReport>;
+    /** The bounded tail of stdout and stderr so far. */
+    output(): string;
+}
+/** A failed launch. Its process tree has already been stopped; `leftoverPids` lists what remained. */
+export declare class DevServerError extends Error {
+    readonly reason: DevServerFailure;
+    readonly pid?: number;
+    readonly port?: number;
+    readonly attempts: number;
+    /** Bounded tail of the server's output. */
+    readonly output: string;
+    readonly leftoverPids: number[];
+    constructor(reason: DevServerFailure, detail: string, fields: {
+        pid?: number;
+        port?: number;
+        attempts: number;
+        output: string;
+        leftoverPids: number[];
+    });
+}
+/**
+ * Starts a dev server hidden, chooses its port, and waits until it is ready. Failure, including a
+ * port collision that exhausts the candidates, stops the whole process tree this launch started and
+ * reports leftovers. A port collision (EADDRINUSE in the output) moves to the next candidate.
+ *
+ * A probe cannot take a floor, so `portFloor` probes upward from the floor with the same bind test
+ * that `freePort` uses; another process can still take the port before the server binds it.
+ */
+export declare function startDevServer(options: DevServerOptions): Promise<DevServer>;

package/dist/devserver.js

@@ -0,0 +1,205 @@
+import { createServer } from 'node:net';
+import { validateTimeout } from './cdp.js';
+import { freePort, ownedProcessReceipt, spawnOwnedProcess, stopOwnedProcess } from './process.js';
+/** Bounded tail of the server's stdout and stderr kept for error messages. */
+const OUTPUT_LIMIT = 16 * 1024;
+/** Output that means the server lost its port race. */
+const COLLISION = /EADDRINUSE|address already in use/i;
+/** A failed launch. Its process tree has already been stopped; `leftoverPids` lists what remained. */
+export class DevServerError extends Error {
+    reason;
+    pid;
+    port;
+    attempts;
+    /** Bounded tail of the server's output. */
+    output;
+    leftoverPids;
+    constructor(reason, detail, fields) {
+        const tail = fields.output.trim().slice(-2_000);
+        super(`dev server ${reason}: ${detail}${tail ? `\n--- output tail ---\n${tail}` : ''}`);
+        this.name = 'DevServerError';
+        this.reason = reason;
+        this.pid = fields.pid;
+        this.port = fields.port;
+        this.attempts = fields.attempts;
+        this.output = fields.output;
+        this.leftoverPids = fields.leftoverPids;
+    }
+}
+function validPort(port) { return Number.isInteger(port) && port >= 1 && port <= 65535; }
+function validateOptions(options) {
+    if (typeof options.command !== 'string' || !options.command)
+        throw new Error('command must be a non-empty string');
+    const { readiness } = options;
+    validateTimeout(readiness.attemptTimeoutMs);
+    validateTimeout(readiness.totalTimeoutMs);
+    if (!Number.isFinite(readiness.intervalMs) || readiness.intervalMs <= 0)
+        throw new Error('readiness.intervalMs must be a positive number');
+    if (readiness.urls === undefined && !readiness.check)
+        throw new Error('readiness needs urls or check');
+    if (options.ports !== undefined && (!Array.isArray(options.ports) || options.ports.length === 0 || !options.ports.every(validPort))) {
+        throw new Error('ports must be a non-empty list of ports from 1 to 65535');
+    }
+    if (options.portFloor !== undefined && !validPort(options.portFloor))
+        throw new Error('portFloor must be a port from 1 to 65535');
+    if (options.maxPortAttempts !== undefined && (!Number.isInteger(options.maxPortAttempts) || options.maxPortAttempts < 1))
+        throw new Error('maxPortAttempts must be a positive integer');
+    if (options.portEnv !== undefined && !options.portEnv)
+        throw new Error('portEnv must be a non-empty name');
+}
+/** Binds 127.0.0.1:<port> briefly; true when nothing else holds it. */
+function portFreeOn(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+    });
+}
+/** The first free port at or above `floor`, skipping `skip`. */
+async function probeFrom(floor, skip) {
+    for (let port = floor; port <= 65_535; port++) {
+        if (!skip.has(port) && (await portFreeOn(port)))
+            return port;
+    }
+    return undefined;
+}
+async function probeUrl(url, timeoutMs) {
+    try {
+        const response = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+        await response.body?.cancel().catch(() => { });
+        return response.status >= 200 && response.status < 300;
+    }
+    catch {
+        return false;
+    }
+}
+/** One round of readiness: every URL answers 2xx, or the check resolves true. A hung check counts as not ready. */
+async function roundReady(readiness, port, attemptTimeoutMs) {
+    if (readiness.check) {
+        let timer;
+        try {
+            return await Promise.race([
+                Promise.resolve().then(() => readiness.check(port)),
+                new Promise((resolve) => { timer = setTimeout(() => resolve(false), attemptTimeoutMs); }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    const urls = typeof readiness.urls === 'function' ? readiness.urls(port) : readiness.urls ?? [];
+    for (const url of urls)
+        if (!(await probeUrl(url, attemptTimeoutMs)))
+            return false;
+    return true;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Starts a dev server hidden, chooses its port, and waits until it is ready. Failure, including a
+ * port collision that exhausts the candidates, stops the whole process tree this launch started and
+ * reports leftovers. A port collision (EADDRINUSE in the output) moves to the next candidate.
+ *
+ * A probe cannot take a floor, so `portFloor` probes upward from the floor with the same bind test
+ * that `freePort` uses; another process can still take the port before the server binds it.
+ */
+export async function startDevServer(options) {
+    validateOptions(options);
+    const portEnv = options.portEnv ?? 'PORT';
+    const maxAttempts = Math.min(options.maxPortAttempts ?? 5, options.ports?.length ?? Number.POSITIVE_INFINITY);
+    const candidates = options.ports ? [...options.ports] : undefined;
+    const tried = new Set();
+    let floor = options.portFloor;
+    let attempts = 0;
+    for (;;) {
+        if (attempts >= maxAttempts)
+            throw new DevServerError('port-in-use', `no free port after ${attempts} attempt(s)`, { attempts, output: '', leftoverPids: [] });
+        let port;
+        if (candidates) {
+            port = candidates.shift();
+            // A listed port that is already held is skipped before anything is spawned on it. Probing a
+            // foreign listener's port would count its answers as readiness, and would keep sockets to it open.
+            attempts++;
+            if (port !== undefined && !(await portFreeOn(port))) {
+                tried.add(port);
+                continue;
+            }
+        }
+        else if (floor !== undefined)
+            port = await probeFrom(floor, tried);
+        else
+            port = await freePort();
+        if (port === undefined)
+            throw new DevServerError('port-in-use', candidates ? 'every listed port is in use' : `no free port at or above ${floor}`, { attempts, output: '', leftoverPids: [] });
+        tried.add(port);
+        floor = port + 1;
+        if (!candidates)
+            attempts++;
+        const launched = await launchOnce(options, port, portEnv, attempts);
+        if (launched)
+            return launched;
+    }
+}
+/** One launch on one port. Returns the ready server, or undefined after a port collision (already stopped). */
+async function launchOnce(options, port, portEnv, attempts) {
+    const { readiness } = options;
+    let handle;
+    try {
+        handle = spawnOwnedProcess(options.command, (options.args ?? []).map((arg) => arg.replaceAll('{port}', String(port))), {
+            cwd: options.cwd,
+            env: { ...process.env, ...options.env, [portEnv]: String(port) },
+            stdio: 'pipe',
+            windowsHide: options.windowsHide ?? true,
+            shell: options.shell ?? false,
+        });
+    }
+    catch (error) {
+        throw new DevServerError('start-failed', error instanceof Error ? error.message : String(error), { port, attempts, output: '', leftoverPids: [] });
+    }
+    let output = '';
+    const append = (chunk) => { output = (output + chunk).slice(-OUTPUT_LIMIT); };
+    handle.child.stdout?.setEncoding('utf8');
+    handle.child.stderr?.setEncoding('utf8');
+    handle.child.stdout?.on('data', append);
+    handle.child.stderr?.on('data', append);
+    let exit;
+    handle.child.once('exit', (code, signal) => { exit = { code, signal }; });
+    /** Stops this launch's tree, then fails, or reports a collision as a retry (undefined) when nothing leaked. */
+    const finish = async (reason, detail) => {
+        await stopOwnedProcess(handle).catch(() => { });
+        const leftoverPids = ownedProcessReceipt().leftoverPids.filter((pid) => pid === handle.pid);
+        if (reason === 'collision' && leftoverPids.length === 0)
+            return undefined;
+        throw new DevServerError(reason === 'collision' ? 'port-in-use' : reason, detail, { pid: handle.pid, port, attempts, output, leftoverPids });
+    };
+    const deadline = Date.now() + readiness.totalTimeoutMs;
+    for (;;) {
+        if (COLLISION.test(output))
+            return finish('collision', `port ${port} is in use`);
+        if (exit)
+            return finish('exited', `process exited before ready (code ${exit.code}, signal ${exit.signal})`);
+        let ready;
+        try {
+            ready = await roundReady(readiness, port, readiness.attemptTimeoutMs);
+        }
+        catch (error) {
+            return finish('check-failed', error instanceof Error ? error.message : String(error));
+        }
+        if (ready) {
+            let stopping;
+            return {
+                pid: handle.pid,
+                port,
+                url: `http://127.0.0.1:${port}`,
+                attempts,
+                stop: () => (stopping ??= (async () => {
+                    await stopOwnedProcess(handle);
+                    return { leftoverPids: ownedProcessReceipt().leftoverPids.filter((pid) => pid === handle.pid) };
+                })()),
+                output: () => output,
+            };
+        }
+        if (Date.now() >= deadline)
+            return finish('timeout', `not ready after ${readiness.totalTimeoutMs}ms on port ${port}`);
+        await sleep(Math.max(1, Math.min(readiness.intervalMs, deadline - Date.now())));
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './chrome.js';
 export * from './evidence.js';
+export * from './devserver.js';
 export * from './frames.js';
 export * from './guard.js';
 export * from './loopback.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './chrome.js';
 export * from './evidence.js';
+export * from './devserver.js';
 export * from './frames.js';
 export * from './guard.js';
 export * from './loopback.js';

package/dist/process.d.ts

@@ -32,6 +32,8 @@ export interface SpawnOwnedProcessOptions {
     /** Default 'ignore'. 'pipe' exposes child.stdout and child.stderr. */
     stdio?: 'ignore' | 'pipe';
     windowsHide?: boolean;
+    /** Run through the platform shell (needed for .cmd shims such as npm on Windows). Default false. */
+    shell?: boolean;
 }
 /**
  * A process this package launched. Only the object returned by spawnOwnedProcess is accepted by

package/dist/process.js

@@ -147,6 +147,7 @@ export function spawnOwnedProcess(command, args = [], options = {}) {
         stdio: options.stdio === 'pipe' ? ['ignore', 'pipe', 'pipe'] : 'ignore',
         windowsHide: options.windowsHide ?? true,
         detached: process.platform !== 'win32',
+        shell: options.shell ?? false,
     });
     // Spawn failures arrive as 'error'; surface them through the missing pid, not as an unhandled event.
     child.on('error', () => { });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",