@rightkit/qa 0.4.5 → 0.4.7

package/README.md

@@ -93,7 +93,7 @@ try {
 - `page.fill(target, value, { replace?, verify? })`. The default inserts at the caret, as `type()` does. `replace: true` selects the whole field first; an empty value then deletes it. `verify: true` (requires `replace`) reads the value back once and throws `FillMismatchError` on a difference. The error gives lengths, not values.
 - `page.mouse.wheel({ deltaX?, deltaY? })` sends one `mouseWheel` event at the tracked pointer position. The pointer does not move.
 - `page.setUserAgent(ua, { platform?, acceptLanguage? })` overrides the user agent for the page and its later navigations. Each call replaces the whole override. `page.resetUserAgent()` restores the `navigator.userAgent` captured before the first override.
-- `waitForFunction(fn, { failureArtifacts: { directory, label? } })` and `waitForSelector(...)` write a screenshot and a JSON state dump (url, title, predicate text, timeout, console entries) when they time out. Paths are on `error.artifacts` (`json`, `screenshot?`). `directory` must be absolute and must not lie inside `RIGHTKIT_RUN_ROOT`: `disposeQaWorkspace` deletes that tree. A failed write is appended to the error message; the timeout still throws.
+- `waitForFunction(fn, { failureArtifacts: { directory, label?, extra?, allowInsideRunRoot? } })` and `waitForSelector(...)` write a screenshot and a JSON state dump on timeout: url, title, bounded page text (`pageText`), the focused element's descriptor without its value (`activeElement`), console entries, and `extra()` if given (`extra`, or `extraError` when it throws, never settles or cannot serialise). Paths are on `error.artifacts` (`json`, `screenshot?`). `directory` must be absolute and must not lie inside `RIGHTKIT_RUN_ROOT`, which `disposeQaWorkspace` deletes; `allowInsideRunRoot: true` opts in, and those files then go with the workspace, so copy them out before dispose. A failed write is appended to the error message; the timeout still throws.
 
 - `page.send(method, params?, timeout?)` is a page-scoped raw CDP escape hatch: unsupported surface, with Chrome's names, params and results. Prefer the typed methods. `page.setFocusEmulation(enabled)` sends `Emulation.setFocusEmulationEnabled`.
 - Navigation and reloads: `evaluate`, `waitForFunction` and `waitForSelector` re-resolve the main-frame context when Chrome reports it missing, and retry within the caller's timeout.
@@ -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.
@@ -143,5 +166,5 @@ This package launches no native app and no WebView2 window; it never replaces th
 
 ## Known issues
 
-- `@rightkit/qa-chrome` is pinned exactly to `0.1.4`. A qa-chrome release therefore needs a `@rightkit/qa` republish to reach consumers (npm audit 2026-10-08, qa finding).
+- `@rightkit/qa-chrome` is pinned exactly to `0.1.5`. A qa-chrome release therefore needs a `@rightkit/qa` republish to reach consumers (npm audit 2026-10-08, qa finding).
 - Three consumers pin three different versions of `@rightkit/qa-chrome` as dev dependencies (npm audit 2026-10-08).

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/page.d.ts

@@ -16,10 +16,24 @@ export interface ViewportOptions {
 }
 /** Where a timed-out wait writes its screenshot and JSON state dump. */
 export interface FailureArtifactOptions {
-    /** Absolute directory, created if missing. Must lie outside RIGHTKIT_RUN_ROOT, which disposeQaWorkspace deletes. */
+    /**
+     * Absolute directory, created if missing. Must lie outside RIGHTKIT_RUN_ROOT, which
+     * disposeQaWorkspace deletes, unless allowInsideRunRoot is set.
+     */
     directory: string;
     /** Short name used in the file names and the dump. Default 'wait'. */
     label?: string;
+    /**
+     * Opt-in: the directory may lie inside RIGHTKIT_RUN_ROOT. These files are deleted with the
+     * workspace by disposeQaWorkspace; copy them out before dispose. Default false.
+     */
+    allowInsideRunRoot?: boolean;
+    /**
+     * Host state to embed in the JSON dump under `extra` (bounded to 64 KiB, cut off after 1 s). A
+     * throw, a timeout or an unserialisable result is recorded under `extraError` and never masks the
+     * timeout.
+     */
+    extra?: () => unknown | Promise<unknown>;
 }
 /** Called once per poll, before the predicate. A throw rejects the wait with that error. */
 export type PollHook = () => void | Promise<void>;
@@ -263,9 +277,10 @@ export declare class QaPage {
     private selectAll;
     /** Throws ElementOccludedError naming the element on top unless the target itself or a composed descendant is hit. */
     private assertUnoccluded;
+    /** URL, title, bounded page text and the active element. Each part is null when unreadable; never throws. */
+    private failureState;
     /** Writes a PNG and a JSON state dump for a timed-out wait into the caller directory. */
     private captureFailure;
-    /** Attaches artifact paths to a timeout error. A write failure is appended to its message; the timeout still throws. */
     /**
      * Writes the failure artifacts for a timed-out wait or a failed onPoll hook. The paths are attached as
      * `artifacts` only on a TimeoutError; for other errors the files are written and the paths are not attached.

package/dist/page.js

@@ -96,22 +96,53 @@ function exceptionEntry(event) {
 function failureTarget(options) {
     if (!options)
         return undefined;
-    const { directory, label } = options;
+    const { directory, label, extra, allowInsideRunRoot } = options;
     if (typeof directory !== 'string' || !path.isAbsolute(directory))
         throw new Error('failureArtifacts.directory must be an absolute path');
     if (label !== undefined && typeof label !== 'string')
         throw new Error('failureArtifacts.label must be a string');
+    if (extra !== undefined && typeof extra !== 'function')
+        throw new Error('failureArtifacts.extra must be a function');
     const resolved = path.resolve(directory);
     const runRoot = process.env.RIGHTKIT_RUN_ROOT;
-    if (runRoot) {
+    if (runRoot && !allowInsideRunRoot) {
         const relative = path.relative(path.resolve(runRoot), resolved);
         const inside = relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
         if (inside)
             throw new Error('failureArtifacts.directory must be outside RIGHTKIT_RUN_ROOT: disposeQaWorkspace deletes that tree');
     }
-    return { directory: resolved, label: (label ?? 'wait').replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 60) || 'wait' };
+    return { directory: resolved, label: (label ?? 'wait').replace(/[^A-Za-z0-9._-]+/g, '-').slice(0, 60) || 'wait', extra };
 }
 let failureSequence = 0;
+/** Bounds for the failure dump: extra state, page text, and the time a host callback may take. */
+const EXTRA_LIMIT = 64 * 1024;
+const EXTRA_TIMEOUT_MS = 1_000;
+const PAGE_TEXT_LIMIT = 20_000;
+function errorText(error) { return error instanceof Error ? error.message : String(error); }
+/** Runs the host's extra callback under a bound, and keeps its JSON within EXTRA_LIMIT. Never throws. */
+async function runExtra(extra) {
+    if (!extra)
+        return { value: null, error: null };
+    let timer;
+    try {
+        const value = await Promise.race([
+            Promise.resolve().then(() => extra()),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`extra timed out after ${EXTRA_TIMEOUT_MS}ms`)), EXTRA_TIMEOUT_MS); }),
+        ]);
+        const json = JSON.stringify(value);
+        if (json === undefined)
+            return { value: null, error: null };
+        if (json.length > EXTRA_LIMIT)
+            return { value: { truncated: true, length: json.length, preview: json.slice(0, EXTRA_LIMIT) }, error: null };
+        return { value: JSON.parse(json), error: null };
+    }
+    catch (error) {
+        return { value: null, error: errorText(error) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function functionSource(fn) {
     const source = fn.toString();
@@ -949,12 +980,38 @@ export class QaPage {
         if (occluder !== null)
             throw new ElementOccludedError(occluder, point);
     }
+    /** URL, title, bounded page text and the active element. Each part is null when unreadable; never throws. */
+    async failureState() {
+        try {
+            const raw = resultValue(await this.run(() => {
+                const el = document.activeElement;
+                const attr = (name) => el?.getAttribute(name) || undefined;
+                return {
+                    url: location.href,
+                    title: document.title,
+                    text: document.body ? document.body.innerText : '',
+                    // Descriptor only: never the value, which may be a secret.
+                    active: el ? { tag: el.tagName.toLowerCase(), id: el.id || undefined, name: attr('name'), type: attr('type'), role: attr('role'), ariaLabel: attr('aria-label') } : null,
+                };
+            }, [], true, 2_000)) ?? {};
+            const text = typeof raw.text === 'string' ? raw.text : '';
+            return {
+                url: typeof raw.url === 'string' ? raw.url : null,
+                title: typeof raw.title === 'string' ? raw.title : null,
+                pageText: { text: text.slice(0, PAGE_TEXT_LIMIT), truncated: text.length > PAGE_TEXT_LIMIT, length: text.length },
+                activeElement: raw.active ?? null,
+            };
+        }
+        catch {
+            return { url: null, title: null, pageText: null, activeElement: null };
+        }
+    }
     /** Writes a PNG and a JSON state dump for a timed-out wait into the caller directory. */
-    async captureFailure(directory, label, predicate, timeout) {
-        await mkdir(directory, { recursive: true });
-        const stem = `${label}-${Date.now()}-${++failureSequence}`;
-        const json = path.join(directory, `${stem}.json`);
-        const png = path.join(directory, `${stem}.png`);
+    async captureFailure(target, predicate, timeout) {
+        await mkdir(target.directory, { recursive: true });
+        const stem = `${target.label}-${Date.now()}-${++failureSequence}`;
+        const json = path.join(target.directory, `${stem}.json`);
+        const png = path.join(target.directory, `${stem}.png`);
         let screenshot;
         let screenshotError;
         try {
@@ -962,28 +1019,28 @@ export class QaPage {
             screenshot = png;
         }
         catch (error) {
-            screenshotError = error instanceof Error ? error.message : String(error);
-        }
-        let where = {};
-        try {
-            where = resultValue(await this.run(() => ({ url: location.href, title: document.title }), [], true, 2_000)) ?? {};
+            screenshotError = errorText(error);
         }
-        catch { /* page gone or stuck: the dump records no url or title */ }
+        const state = await this.failureState();
+        const extra = await runExtra(target.extra);
         const dump = {
-            label,
+            label: target.label,
             predicate,
             timeoutMs: timeout,
             timestamp: new Date().toISOString(),
-            url: where.url ?? null,
-            title: where.title ?? null,
+            url: state.url,
+            title: state.title,
+            pageText: state.pageText,
+            activeElement: state.activeElement,
             screenshot: screenshot ? path.basename(screenshot) : null,
             screenshotError: screenshotError ?? null,
             console: this.consoleEntries(),
+            extra: extra.value,
+            extraError: extra.error,
         };
         await writeFile(json, JSON.stringify(dump, null, 2));
         return screenshot ? { json, screenshot } : { json };
     }
-    /** Attaches artifact paths to a timeout error. A write failure is appended to its message; the timeout still throws. */
     /**
      * Writes the failure artifacts for a timed-out wait or a failed onPoll hook. The paths are attached as
      * `artifacts` only on a TimeoutError; for other errors the files are written and the paths are not attached.
@@ -991,7 +1048,7 @@ export class QaPage {
      */
     async attachFailureArtifacts(error, target, predicate, timeout) {
         try {
-            const written = await this.captureFailure(target.directory, target.label, predicate, timeout);
+            const written = await this.captureFailure(target, predicate, timeout);
             if (error instanceof TimeoutError)
                 error.artifacts = written;
         }

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.5",
+  "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",
@@ -24,7 +24,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@rightkit/qa-chrome": "0.1.4"
+    "@rightkit/qa-chrome": "0.1.5"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",