@rightkit/qa 0.4.2 → 0.4.4

package/README.md

@@ -13,7 +13,7 @@ Shared browser and QA primitives for Right Suite apps: run storage and evidence
 
 | Import | Contents |
 |---|---|
-| `@rightkit/qa` | `export *` from evidence, frames, guard, loopback, ownership, paint, panes, process, workspace, storage, page and chrome modules. Includes `QaBrowserSession`, `QaPage`, `QaElement`, `QaKeyboard`, `QaMouse`, `TimeoutError`. |
+| `@rightkit/qa` | `export *` from evidence, frames, guard, loopback, ownership, paint, panes, process, workspace, storage, page and chrome modules. Includes `QaBrowserSession`, `QaPage`, `QaElement`, `QaKeyboard`, `QaMouse`, `TimeoutError`, `ElementOccludedError`, `FillMismatchError`, `freePort`. |
 | `@rightkit/qa/chrome` | Re-export of `@rightkit/qa-chrome` |
 
 Dependency: `@rightkit/qa-chrome` (exact `0.1.3`).
@@ -86,6 +86,39 @@ try {
 
 `evaluate` throws the page's JavaScript exception (or a `TimeoutError`) rather than returning an error value. Wrap the call if you need the error as data.
 
+## Console, occlusion, fill, wheel, user agent and failure artifacts
+
+- `page.consoleEntries()` returns the newest 200 console calls and uncaught exceptions of the page, oldest first, as `{ type, text, url?, line?, timestamp }`. `type` is the console method (`log`, `error`, ...) or `exception`. Capture is always on; `clearConsoleEntries()` empties the buffer. Entries may contain page data, so do not write them to shared logs.
+- `page.click(target, { checkOccluded: true })` checks, after the pointer moves and before it presses, that `elementFromPoint` at the click point is the target or one of its descendants. Otherwise it throws `ElementOccludedError`, whose `occluder` names the element on top (tag, id, class; never text). The check walks into open shadow roots to name the element on top; a cover inside a closed shadow root is named by its host. The default is `false`.
+- `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.
+
+`freePort()` returns a free `127.0.0.1` port by binding port 0 and releasing it. Another process can take the port before use.
+
+## 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.
+
+- Shifted symbols send Shift. `?` is Shift+`/`, `+` is Shift+`=`, `!` is Shift+`1`. Such a key carries `modifiers` 8 and its shifted `key` and `text`; no separate Shift key-down is sent.
+- Chords join parts with `+`. A literal plus key goes last: `+` and `Control++`.
+- `code` follows the US layout (`?` has code `Slash`). Other layouts are not modelled.
+
+## Browser escape hatch (unsupported surface)
+
+These methods expose Chrome's own DevTools protocol. Their names, params and results follow the browser version, not this package, and may break when Chrome changes. Use the typed `QaPage` API where it exists.
+
+- `browser.send(method, params?)` sends one browser-scoped command with no `sessionId` and resolves with its raw result.
+- `browser.version()` returns `Browser.getVersion`.
+- `browser.commandLine()` returns the browser argv from `Browser.getBrowserCommandLine` as `string[]`.
+
+`commandLine()` needs the browser launched with `--enable-automation`. `launchChromeForTesting` does not pass that flag, so launch with `launchChromeForTesting({ args: ["--enable-automation"] })`. Without it, the call rejects with an error that names the requirement; the browser is unchanged.
+
+## Run root and workspace disposal
+
+`createQaWorkspace` sets `RIGHTKIT_RUN_ROOT` to the workspace `home`. `disposeQaWorkspace` deletes that home, and deletes the workspace root too unless `keepEvidence` is set. A host must never map a directory that holds artifacts it wants to keep onto `RIGHTKIT_RUN_ROOT`, or onto the workspace root or home. Copy artifacts out before disposal, or use `keepEvidence: true` and keep anything written under `evidence` or `captures`.
+
 ## Ownership: this package versus the Rust `rightkit-qa` crate
 
 Both runners stay. Pick by what the test drives.

package/dist/cdp.d.ts

@@ -1,5 +1,10 @@
 /** Minimal flattened-session CDP transport using Node's built-in WebSocket. */
 export declare class TimeoutError extends Error {
+    /** Set when the wait was given failureArtifacts and the artifacts were written. */
+    artifacts?: {
+        json: string;
+        screenshot?: string;
+    };
     constructor(message: string);
 }
 export interface QaConnectOptions {

package/dist/cdp.js

@@ -1,5 +1,7 @@
 /** Minimal flattened-session CDP transport using Node's built-in WebSocket. */
 export class TimeoutError extends Error {
+    /** Set when the wait was given failureArtifacts and the artifacts were written. */
+    artifacts;
     constructor(message) { super(message); this.name = 'TimeoutError'; }
 }
 /** @internal All operations use finite deadlines. */

package/dist/keyboard.d.ts

@@ -4,6 +4,9 @@ export declare function keyDefinition(key: string, modifiers: number): CdpParams
 export declare class QaKeyboard {
     private send;
     constructor(send: (method: string, params: CdpParams) => Promise<CdpParams>);
-    /** Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft. */
+    /**
+     * Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft, F3, ?, Control+/.
+     * Function keys F1-F24 and US-layout printable keys (shifted ones included) are supported.
+     */
     press(chord: string): Promise<void>;
 }

package/dist/keyboard.js

@@ -6,45 +6,89 @@ const special = {
     Shift: ['ShiftLeft', 16], Control: ['ControlLeft', 17], Alt: ['AltLeft', 18], Meta: ['MetaLeft', 91],
 };
 export const modifierBits = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+/** Function keys F1-F24: code "F<n>", Windows virtual key 111 + n (VK_F1 = 112 ... VK_F24 = 135). */
+const functionKey = /^F(?:[1-9]|1\d|2[0-4])$/;
+/** [base, shifted, code, Windows virtual key] for each US-layout punctuation key. */
+const punctuation = [
+    ['`', '~', 'Backquote', 192], ['-', '_', 'Minus', 189], ['=', '+', 'Equal', 187],
+    ['[', '{', 'BracketLeft', 219], [']', '}', 'BracketRight', 221], ['\\', '|', 'Backslash', 220],
+    [';', ':', 'Semicolon', 186], ["'", '"', 'Quote', 222], [',', '<', 'Comma', 188],
+    ['.', '>', 'Period', 190], ['/', '?', 'Slash', 191],
+];
+const shiftedDigits = ')!@#$%^&*(';
+/** Keyed by the character the key prints, so "?" and "/" both resolve, the first with Shift forced. */
+const printable = new Map();
+for (const [base, shifted, code, keyCode] of punctuation) {
+    printable.set(base, { base, shifted, code, keyCode, requiresShift: false });
+    printable.set(shifted, { base, shifted, code, keyCode, requiresShift: true });
+}
+for (let digit = 0; digit <= 9; digit++) {
+    const base = String(digit), code = `Digit${digit}`, keyCode = 48 + digit;
+    printable.set(base, { base, shifted: shiftedDigits[digit], code, keyCode, requiresShift: false });
+    printable.set(shiftedDigits[digit], { base, shifted: shiftedDigits[digit], code, keyCode, requiresShift: true });
+}
 export function keyDefinition(key, modifiers) {
     const named = special[key];
-    let code, windowsVirtualKeyCode, text;
-    if (named)
+    let code, windowsVirtualKeyCode, text, unmodifiedText;
+    let effective = modifiers;
+    if (named) {
         [code, windowsVirtualKeyCode, text] = named;
+        unmodifiedText = text;
+    }
+    else if (functionKey.test(key)) {
+        code = key;
+        windowsVirtualKeyCode = 111 + Number(key.slice(1));
+    }
     else if (/^[a-z]$/i.test(key)) {
         code = `Key${key.toUpperCase()}`;
         windowsVirtualKeyCode = key.toUpperCase().charCodeAt(0);
         key = modifiers & 8 ? key.toUpperCase() : modifiers & 7 ? key.toLowerCase() : key;
         text = key;
+        unmodifiedText = code.slice(3).toLowerCase();
     }
-    else if (/^[0-9]$/.test(key)) {
-        code = `Digit${key}`;
-        windowsVirtualKeyCode = key.charCodeAt(0);
-        key = modifiers & 8 ? ')!@#$%^&*('[Number(key)] : key;
+    else if (printable.has(key)) {
+        const symbol = printable.get(key);
+        code = symbol.code;
+        windowsVirtualKeyCode = symbol.keyCode;
+        if (symbol.requiresShift)
+            effective |= 8;
+        key = effective & 8 ? symbol.shifted : symbol.base;
         text = key;
+        unmodifiedText = symbol.base;
     }
     else if (key === ' ') {
         code = 'Space';
         windowsVirtualKeyCode = 32;
         text = ' ';
+        unmodifiedText = ' ';
     }
     else
         throw new Error(`Unsupported key: ${key}`);
     if (key === 'Space')
         key = ' ';
-    if (modifiers & (1 | 2 | 4))
+    if (effective & (1 | 2 | 4))
         text = undefined;
-    const unmodifiedText = code.startsWith('Key') ? code.slice(3).toLowerCase() : code.startsWith('Digit') ? code.slice(5) : text;
-    return { key, code, windowsVirtualKeyCode, modifiers, ...(text ? { text, unmodifiedText } : {}) };
+    return { key, code, windowsVirtualKeyCode, modifiers: effective, ...(text ? { text, unmodifiedText } : {}) };
+}
+/** Splits "Control+A" into parts. A literal plus key is the last part: "+" and "Control++". */
+function splitChord(chord) {
+    if (chord === '+')
+        return ['+'];
+    if (chord.endsWith('++'))
+        return [...chord.slice(0, -2).split('+'), '+'];
+    return chord.split('+');
 }
 export class QaKeyboard {
     send;
     constructor(send) {
         this.send = send;
     }
-    /** Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft. */
+    /**
+     * Single key or chord, e.g. Control+A, Meta+A, Shift+ArrowLeft, F3, ?, Control+/.
+     * Function keys F1-F24 and US-layout printable keys (shifted ones included) are supported.
+     */
     async press(chord) {
-        const parts = chord.split('+');
+        const parts = splitChord(chord);
         if (parts.some((part, i) => i < parts.length - 1 && !modifierBits[part]))
             throw new Error(`Invalid key chord: ${chord}`);
         keyDefinition(parts.at(-1), 0); // Validate before holding any modifier.

package/dist/mouse.d.ts

@@ -11,6 +11,10 @@ export interface MousePosition {
     x: number;
     y: number;
 }
+export interface MouseWheelOptions {
+    deltaX?: number; /** Vertical scroll delta in CSS pixels; positive scrolls down. Default 0. */
+    deltaY?: number;
+}
 /**
  * Pointer state for one page: position and held buttons, so a move while a button is held
  * sends the right `buttons` mask. Coordinates are CSS pixels of the viewport, as for `click`.
@@ -30,6 +34,11 @@ export declare class QaMouse {
     down(options?: MouseButtonOptions): Promise<void>;
     /** Release a held button at the current position. */
     up(options?: MouseButtonOptions): Promise<void>;
+    /**
+     * Wheel (scroll) at the tracked position. Sends one mouseWheel event with the given deltas;
+     * the pointer does not move. At least one delta must be non-zero.
+     */
+    wheel(options?: MouseWheelOptions): Promise<void>;
     /** @internal Called by page.click & page.hover after they dispatch at a point. */
     track(x: number, y: number): void;
     /** @internal Page-level click & hover send their own events without a held mask, so refuse to run while held. */

package/dist/mouse.js

@@ -62,6 +62,18 @@ export class QaMouse {
         await this.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: this.x, y: this.y, button, buttons, clickCount });
         this.held.delete(button);
     }
+    /**
+     * Wheel (scroll) at the tracked position. Sends one mouseWheel event with the given deltas;
+     * the pointer does not move. At least one delta must be non-zero.
+     */
+    async wheel(options = {}) {
+        const deltaX = options.deltaX ?? 0, deltaY = options.deltaY ?? 0;
+        if (!Number.isFinite(deltaX) || !Number.isFinite(deltaY))
+            throw new Error('Mouse wheel deltas must be finite numbers');
+        if (deltaX === 0 && deltaY === 0)
+            throw new Error('Mouse wheel needs a non-zero deltaX or deltaY');
+        await this.send('Input.dispatchMouseEvent', { type: 'mouseWheel', x: this.x, y: this.y, deltaX, deltaY });
+    }
     /** @internal Called by page.click & page.hover after they dispatch at a point. */
     track(x, y) { this.x = x; this.y = y; }
     /** @internal Page-level click & hover send their own events without a held mask, so refuse to run while held. */

package/dist/page.d.ts

@@ -3,7 +3,7 @@ import { QaKeyboard } from './keyboard.js';
 import { QaMouse } from './mouse.js';
 export { TimeoutError, type QaConnectOptions } from './cdp.js';
 export { QaKeyboard } from './keyboard.js';
-export { QaMouse, type MouseButton, type MouseButtonOptions, type MouseMoveOptions, type MousePosition } from './mouse.js';
+export { QaMouse, type MouseButton, type MouseButtonOptions, type MouseMoveOptions, type MousePosition, type MouseWheelOptions } from './mouse.js';
 export interface NavigationOptions {
     waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0';
     timeout?: number;
@@ -14,19 +14,48 @@ export interface ViewportOptions {
     deviceScaleFactor?: number;
     mobile?: boolean;
 }
+/** 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. */
+    directory: string;
+    /** Short name used in the file names and the dump. Default 'wait'. */
+    label?: string;
+}
 export interface WaitOptions {
     timeout?: number;
     polling?: 'raf' | number;
+    failureArtifacts?: FailureArtifactOptions;
 }
 export interface SelectorWaitOptions {
     visible?: boolean;
     hidden?: boolean;
     timeout?: number;
+    failureArtifacts?: FailureArtifactOptions;
 }
 export interface ClickOptions {
     button?: 'left' | 'right' | 'middle';
     clickCount?: number;
     delay?: number;
+    /** Default false. When true, after the pointer moves and before pressing, checks that the element at the click point is the target or its descendant; otherwise throws ElementOccludedError. */
+    checkOccluded?: boolean;
+}
+export interface FillOptions {
+    /** Default false: insert at the caret, exactly as type() does. True selects the whole field first, so the value replaces its content; an empty value then deletes the selection. */
+    replace?: boolean;
+    /** Default false. Reads the value back after insertion and throws FillMismatchError on a difference. Requires replace. */
+    verify?: boolean;
+}
+/** One console call or uncaught exception of a page. `line` is 1-based. */
+export interface ConsoleEntry {
+    type: string;
+    text: string;
+    url?: string;
+    line?: number;
+    timestamp: number;
+}
+export interface UserAgentOptions {
+    platform?: string;
+    acceptLanguage?: string;
 }
 export interface TypeOptions {
     delay?: number;
@@ -60,6 +89,25 @@ export interface QaAttachOptions extends QaConnectOptions {
     allowRemoteHost?: boolean;
 }
 type PageFunction<Args extends unknown[], Result> = (...args: Args) => Result;
+/** Thrown by click({ checkOccluded: true }) when another element is on top of the target at the click point. */
+export declare class ElementOccludedError extends Error {
+    readonly point: {
+        x: number;
+        y: number;
+    };
+    /** Short description of the element on top, e.g. <div id="toast">. Text content is never included. */
+    readonly occluder: string;
+    constructor(occluder: string, point: {
+        x: number;
+        y: number;
+    });
+}
+/** Thrown by fill({ verify: true }) when the field does not hold the requested value. The values are not included. */
+export declare class FillMismatchError extends Error {
+    readonly expectedLength: number;
+    readonly actualLength: number;
+    constructor(expectedLength: number, actualLength: number);
+}
 /** Owns only targets it creates; launcher owns browser process & profile cleanup. */
 export declare class QaBrowserSession {
     private client;
@@ -85,6 +133,21 @@ export declare class QaBrowserSession {
     private attachExisting;
     newPage(): Promise<QaPage>;
     private createPage;
+    /**
+     * UNSUPPORTED escape hatch: sends one browser-scoped CDP command (no sessionId) and resolves
+     * with its raw result. The protocol is Chrome's, not this package's: method names, params and
+     * results may change or disappear with a browser version. Prefer the typed QaPage API.
+     */
+    send(method: string, params?: CdpParams): Promise<CdpParams>;
+    /** Browser.getVersion (unsupported surface, see send). Read only. */
+    version(): Promise<CdpParams>;
+    /**
+     * Browser argv via Browser.getBrowserCommandLine (unsupported surface, see send). The browser
+     * answers only when it was launched with --enable-automation; launchChromeForTesting passes no
+     * such flag by default, so pass { args: ['--enable-automation'] } to use this. A refusal rejects
+     * with an error that names the requirement; the browser is not changed.
+     */
+    commandLine(): Promise<string[]>;
     close(): Promise<void>;
 }
 export declare class QaPage {
@@ -109,6 +172,9 @@ export declare class QaPage {
     private lastNetworkActivity;
     private generation;
     private navigating;
+    private consoleBuffer;
+    private userAgentBaseline?;
+    private userAgentOverridden;
     private get objectGroup();
     /** @internal Use QaBrowserSession.newPage() or attachPage(). `owned` pages are closed on close(); attached ones only detach. */
     constructor(client: CdpClient, targetId: string, sessionId: string, onClosed: () => void, owned?: boolean);
@@ -147,6 +213,31 @@ export declare class QaPage {
     private requireElement;
     private withElement;
     private point;
+    /** Recent console calls and uncaught exceptions of this page, oldest first. Bounded to the newest 200. Returns copies. */
+    consoleEntries(): ConsoleEntry[];
+    /** Empties the console buffer. */
+    clearConsoleEntries(): void;
+    private recordConsole;
+    /**
+     * Overrides the user agent (Emulation.setUserAgentOverride) for this page, including later navigations.
+     * Each call replaces the whole override, so platform & acceptLanguage are sent only when given.
+     */
+    setUserAgent(userAgent: string, options?: UserAgentOptions): Promise<void>;
+    /** Restores the navigator.userAgent captured before the first setUserAgent. A no-op when this page never overrode it. */
+    resetUserAgent(): Promise<void>;
+    /**
+     * Types a value into a field. Default: insert at the caret, exactly as type() does. With replace the
+     * whole content is selected first and replaced. With verify (requires replace) the value is read back
+     * once after insertion and FillMismatchError is thrown on a difference.
+     */
+    fill(target: string | QaElement, value: string, options?: FillOptions): Promise<void>;
+    private selectAll;
+    /** Throws ElementOccludedError naming the element on top unless the target itself or a composed descendant is hit. */
+    private assertUnoccluded;
+    /** 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. */
+    private attachFailureArtifacts;
     click(target: string | QaElement, options?: ClickOptions): Promise<void>;
     type(selector: string, text: string, options?: TypeOptions): Promise<void>;
     /** @internal */

package/dist/page.js

@@ -1,10 +1,92 @@
-import { writeFile } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { CdpClient, TimeoutError, validateTimeout } from './cdp.js';
 import { QaKeyboard } from './keyboard.js';
 import { QaMouse } from './mouse.js';
 export { TimeoutError } from './cdp.js';
 export { QaKeyboard } from './keyboard.js';
 export { QaMouse } from './mouse.js';
+/** Newest console entries kept per page. */
+const CONSOLE_LIMIT = 200;
+/** Thrown by click({ checkOccluded: true }) when another element is on top of the target at the click point. */
+export class ElementOccludedError extends Error {
+    point;
+    /** Short description of the element on top, e.g. <div id="toast">. Text content is never included. */
+    occluder;
+    constructor(occluder, point) {
+        super(`Click target is covered by ${occluder} at (${point.x}, ${point.y})`);
+        this.name = 'ElementOccludedError';
+        this.occluder = occluder;
+        this.point = point;
+    }
+}
+/** Thrown by fill({ verify: true }) when the field does not hold the requested value. The values are not included. */
+export class FillMismatchError extends Error {
+    expectedLength;
+    actualLength;
+    constructor(expectedLength, actualLength) {
+        super(`fill verification failed: field holds ${actualLength} characters, expected ${expectedLength}`);
+        this.name = 'FillMismatchError';
+        this.expectedLength = expectedLength;
+        this.actualLength = actualLength;
+    }
+}
+/** Text of one console argument, from its CDP RemoteObject. */
+function remoteText(object) {
+    if ('value' in object)
+        return typeof object.value === 'string' ? object.value : JSON.stringify(object.value) ?? String(object.value);
+    return String(object.unserializableValue ?? object.description ?? object.type ?? '');
+}
+/** url and 1-based line, present only when the event carries them. */
+function locationOf(url, zeroBasedLine) {
+    const location = {};
+    if (typeof url === 'string' && url)
+        location.url = url;
+    if (typeof zeroBasedLine === 'number' && zeroBasedLine >= 0)
+        location.line = zeroBasedLine + 1;
+    return location;
+}
+function consoleEntry(event) {
+    const frame = event.stackTrace?.callFrames?.[0];
+    return {
+        type: String(event.type),
+        text: (event.args ?? []).map(remoteText).join(' '),
+        ...locationOf(frame?.url, frame?.lineNumber),
+        timestamp: typeof event.timestamp === 'number' ? event.timestamp : Date.now(),
+    };
+}
+function exceptionEntry(event) {
+    const details = event.exceptionDetails ?? {};
+    return {
+        type: 'exception',
+        text: String(details.exception?.description ?? details.exception?.value ?? details.text ?? 'Uncaught exception'),
+        ...locationOf(details.url, details.lineNumber),
+        timestamp: typeof event.timestamp === 'number' ? event.timestamp : Date.now(),
+    };
+}
+/**
+ * Validates a failureArtifacts option before any CDP work: absolute, and never inside
+ * RIGHTKIT_RUN_ROOT (the workspace home that disposeQaWorkspace deletes).
+ */
+function failureTarget(options) {
+    if (!options)
+        return undefined;
+    const { directory, label } = 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');
+    const resolved = path.resolve(directory);
+    const runRoot = process.env.RIGHTKIT_RUN_ROOT;
+    if (runRoot) {
+        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' };
+}
+let failureSequence = 0;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function functionSource(fn) {
     const source = fn.toString();
@@ -211,6 +293,45 @@ export class QaBrowserSession {
             throw error;
         }
     }
+    /**
+     * UNSUPPORTED escape hatch: sends one browser-scoped CDP command (no sessionId) and resolves
+     * with its raw result. The protocol is Chrome's, not this package's: method names, params and
+     * results may change or disappear with a browser version. Prefer the typed QaPage API.
+     */
+    send(method, params = {}) {
+        if (this.closed)
+            return Promise.reject(new Error('Browser session closed'));
+        if (typeof method !== 'string' || !method)
+            return Promise.reject(new Error('CDP method must be a non-empty string'));
+        return this.client.send(method, params);
+    }
+    /** Browser.getVersion (unsupported surface, see send). Read only. */
+    version() {
+        return this.send('Browser.getVersion');
+    }
+    /**
+     * Browser argv via Browser.getBrowserCommandLine (unsupported surface, see send). The browser
+     * answers only when it was launched with --enable-automation; launchChromeForTesting passes no
+     * such flag by default, so pass { args: ['--enable-automation'] } to use this. A refusal rejects
+     * with an error that names the requirement; the browser is not changed.
+     */
+    async commandLine() {
+        let reply;
+        try {
+            reply = await this.send('Browser.getBrowserCommandLine');
+        }
+        catch (error) {
+            // CdpClient prefixes errors the browser itself returned with "CDP: "; timeouts and closed sockets pass through.
+            if (error instanceof Error && error.message.startsWith('CDP: ')) {
+                throw new Error(`Browser.getBrowserCommandLine was refused (${error.message.slice(5)}). It requires the browser to be launched with --enable-automation, e.g. launchChromeForTesting({ args: ['--enable-automation'] }).`, { cause: error });
+            }
+            throw error;
+        }
+        const argv = reply.arguments;
+        if (!Array.isArray(argv) || !argv.every((arg) => typeof arg === 'string'))
+            throw new Error('Browser.getBrowserCommandLine did not return an argument list');
+        return argv;
+    }
     close() {
         if (this.closing)
             return this.closing;
@@ -252,6 +373,9 @@ export class QaPage {
     lastNetworkActivity = 0;
     generation = 0;
     navigating = false;
+    consoleBuffer = [];
+    userAgentBaseline;
+    userAgentOverridden = false;
     get objectGroup() { return `qa-elements-${this.generation}`; }
     /** @internal Use QaBrowserSession.newPage() or attachPage(). `owned` pages are closed on close(); attached ones only detach. */
     constructor(client, targetId, sessionId, onClosed, owned = true) {
@@ -296,7 +420,7 @@ export class QaPage {
             for (const [id, request] of this.requests)
                 if (request.frameId && removed.has(request.frameId))
                     this.requests.delete(id);
-        }), this.on('Network.requestWillBeSent', ({ requestId, frameId, loaderId }) => { this.requests.set(requestId, { frameId, loaderId }); this.lastNetworkActivity = Date.now(); }), this.on('Network.loadingFinished', ({ requestId }) => { this.requests.delete(requestId); this.lastNetworkActivity = Date.now(); }), this.on('Network.loadingFailed', ({ requestId }) => { this.requests.delete(requestId); this.lastNetworkActivity = Date.now(); }), client.on('Disconnected', ({ error }) => this.markClosed(error)), client.on('Target.detachedFromTarget', ({ sessionId }) => { if (sessionId === this.sessionId)
+        }), this.on('Runtime.consoleAPICalled', (event) => this.recordConsole(consoleEntry(event))), this.on('Runtime.exceptionThrown', (event) => this.recordConsole(exceptionEntry(event))), this.on('Network.requestWillBeSent', ({ requestId, frameId, loaderId }) => { this.requests.set(requestId, { frameId, loaderId }); this.lastNetworkActivity = Date.now(); }), this.on('Network.loadingFinished', ({ requestId }) => { this.requests.delete(requestId); this.lastNetworkActivity = Date.now(); }), this.on('Network.loadingFailed', ({ requestId }) => { this.requests.delete(requestId); this.lastNetworkActivity = Date.now(); }), client.on('Disconnected', ({ error }) => this.markClosed(error)), client.on('Target.detachedFromTarget', ({ sessionId }) => { if (sessionId === this.sessionId)
             this.markClosed(); }), this.on('Inspector.detached', () => this.markClosed()));
     }
     chooseContext() {
@@ -550,35 +674,46 @@ export class QaPage {
         if (typeof polling === 'number' && (!(polling > 0) || !Number.isFinite(polling)))
             throw new Error('Polling interval must be positive');
         const source = typeof fn === 'string' ? `function() { return (${fn}); }` : functionSource(fn);
-        await this.bounded(`Predicate ${source}`, options.timeout ?? this.client.timeout, async (remaining, stopped) => {
-            while (!stopped()) {
-                try {
-                    if (resultValue(await this.runSourceFunction(source, args, remaining())))
-                        return;
-                    if (polling === 'raf') {
-                        // A browser animation frame, bounded fallback for background targets.
-                        await this.runSourceFunction('function() { return new Promise(resolve => { const timer = setTimeout(resolve, 100); requestAnimationFrame(() => { clearTimeout(timer); resolve(); }); }); }', [], remaining());
+        const artifacts = failureTarget(options.failureArtifacts);
+        const timeout = options.timeout ?? this.client.timeout;
+        try {
+            await this.bounded(`Predicate ${source}`, timeout, async (remaining, stopped) => {
+                while (!stopped()) {
+                    try {
+                        if (resultValue(await this.runSourceFunction(source, args, remaining())))
+                            return;
+                        if (polling === 'raf') {
+                            // A browser animation frame, bounded fallback for background targets.
+                            await this.runSourceFunction('function() { return new Promise(resolve => { const timer = setTimeout(resolve, 100); requestAnimationFrame(() => { clearTimeout(timer); resolve(); }); }); }', [], remaining());
+                        }
+                        else
+                            await sleep(Math.min(polling, remaining()));
                     }
-                    else
-                        await sleep(Math.min(polling, remaining()));
-                }
-                catch (error) {
-                    if (error instanceof TimeoutError) {
-                        await sleep(remaining());
-                        continue;
+                    catch (error) {
+                        if (error instanceof TimeoutError) {
+                            await sleep(remaining());
+                            continue;
+                        }
+                        if (!/context.*(destroyed|not found)|Cannot find context/i.test(String(error)))
+                            throw error;
+                        await sleep(Math.min(10, remaining()));
                     }
-                    if (!/context.*(destroyed|not found)|Cannot find context/i.test(String(error)))
-                        throw error;
-                    await sleep(Math.min(10, remaining()));
                 }
-            }
-        });
+            });
+        }
+        catch (error) {
+            if (artifacts && error instanceof TimeoutError)
+                await this.attachFailureArtifacts(error, artifacts, source, timeout);
+            throw error;
+        }
     }
     async waitForSelector(selector, options = {}) {
         if (options.visible && options.hidden)
             throw new Error('visible & hidden cannot both be true');
+        const artifacts = failureTarget(options.failureArtifacts);
+        const timeout = options.timeout ?? this.client.timeout;
         try {
-            return await this.bounded(`Selector ${selector}`, options.timeout ?? this.client.timeout, async (remaining) => {
+            return await this.bounded(`Selector ${selector}`, timeout, async (remaining) => {
                 await this.waitForFunction((selector, visible, hidden) => {
                     const element = document.querySelector(selector);
                     if (!element)
@@ -591,8 +726,12 @@ export class QaPage {
             });
         }
         catch (error) {
-            if (error instanceof TimeoutError)
-                throw new TimeoutError(`Selector ${selector} timed out after ${options.timeout ?? this.client.timeout}ms`);
+            if (error instanceof TimeoutError) {
+                const named = new TimeoutError(`Selector ${selector} timed out after ${timeout}ms`);
+                if (artifacts)
+                    await this.attachFailureArtifacts(named, artifacts, `waitForSelector ${JSON.stringify(selector)} visible=${!!options.visible} hidden=${!!options.hidden}`, timeout);
+                throw named;
+            }
             throw error;
         }
     }
@@ -621,12 +760,163 @@ export class QaPage {
             throw new Error('Element has no clickable box');
         return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
     }
+    /** Recent console calls and uncaught exceptions of this page, oldest first. Bounded to the newest 200. Returns copies. */
+    consoleEntries() { return this.consoleBuffer.map((entry) => ({ ...entry })); }
+    /** Empties the console buffer. */
+    clearConsoleEntries() { this.consoleBuffer.length = 0; }
+    recordConsole(entry) {
+        this.consoleBuffer.push(entry);
+        if (this.consoleBuffer.length > CONSOLE_LIMIT)
+            this.consoleBuffer.splice(0, this.consoleBuffer.length - CONSOLE_LIMIT);
+    }
+    /**
+     * Overrides the user agent (Emulation.setUserAgentOverride) for this page, including later navigations.
+     * Each call replaces the whole override, so platform & acceptLanguage are sent only when given.
+     */
+    async setUserAgent(userAgent, options = {}) {
+        if (typeof userAgent !== 'string' || !userAgent.trim())
+            throw new Error('User agent must be a non-empty string');
+        // The first override records the page's own navigator.userAgent so resetUserAgent can restore it.
+        if (!this.userAgentOverridden)
+            this.userAgentBaseline = await this.evaluate(() => navigator.userAgent);
+        await this.send('Emulation.setUserAgentOverride', {
+            userAgent,
+            ...(options.platform !== undefined ? { platform: options.platform } : {}),
+            ...(options.acceptLanguage !== undefined ? { acceptLanguage: options.acceptLanguage } : {}),
+        });
+        this.userAgentOverridden = true;
+    }
+    /** Restores the navigator.userAgent captured before the first setUserAgent. A no-op when this page never overrode it. */
+    async resetUserAgent() {
+        if (!this.userAgentOverridden || this.userAgentBaseline === undefined)
+            return;
+        await this.send('Emulation.setUserAgentOverride', { userAgent: this.userAgentBaseline });
+        this.userAgentOverridden = false;
+        this.userAgentBaseline = undefined;
+    }
+    /**
+     * Types a value into a field. Default: insert at the caret, exactly as type() does. With replace the
+     * whole content is selected first and replaced. With verify (requires replace) the value is read back
+     * once after insertion and FillMismatchError is thrown on a difference.
+     */
+    async fill(target, value, options = {}) {
+        if (typeof value !== 'string')
+            throw new Error('fill value must be a string');
+        if (options.verify && !options.replace)
+            throw new Error('fill verify requires replace: true; an insert-only fill has no fixed expected value');
+        await this.withElement(target, async (handle) => {
+            if (!options.replace) {
+                await this.typeElement(handle, value);
+                return;
+            }
+            await handle.focus();
+            await this.selectAll(handle);
+            if (value === '')
+                await this.keyboard.press('Backspace');
+            else
+                await this.send('Input.insertText', { text: value });
+            if (options.verify) {
+                const actual = await handle.evaluate((element) => (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement ? element.value : element.textContent) ?? '');
+                if (actual !== value)
+                    throw new FillMismatchError(value.length, actual.length);
+            }
+        });
+    }
+    async selectAll(handle) {
+        const selected = await handle.evaluate((element) => {
+            if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+                element.select();
+                return true;
+            }
+            if (element.isContentEditable) {
+                const range = element.ownerDocument.createRange();
+                range.selectNodeContents(element);
+                const selection = element.ownerDocument.getSelection();
+                selection?.removeAllRanges();
+                selection?.addRange(range);
+                return true;
+            }
+            return false;
+        });
+        if (!selected)
+            throw new Error('fill target is not an editable input, textarea or contenteditable element');
+    }
+    /** Throws ElementOccludedError naming the element on top unless the target itself or a composed descendant is hit. */
+    async assertUnoccluded(handle, point) {
+        const occluder = await handle.evaluate((element, x, y) => {
+            let hit = element.ownerDocument.elementFromPoint(x, y);
+            // The document reports a shadow host, not the element inside its open shadow root: descend.
+            while (hit?.shadowRoot) {
+                const inner = hit.shadowRoot.elementFromPoint(x, y);
+                if (!inner || inner === hit)
+                    break;
+                hit = inner;
+            }
+            // Composed ancestry: a shadow root's host counts as its parent, so shadow content inside the target passes.
+            for (let node = hit; node; node = node.parentNode ?? node.host ?? null) {
+                if (node === element)
+                    return null;
+            }
+            if (!hit)
+                return '(no element at the click point)';
+            const id = hit.id ? ` id="${hit.id}"` : '';
+            const className = typeof hit.className === 'string' ? hit.className.trim().slice(0, 80) : '';
+            return `<${hit.tagName.toLowerCase()}${id}${className ? ` class="${className}"` : ''}>`;
+        }, point.x, point.y);
+        if (occluder !== null)
+            throw new ElementOccludedError(occluder, point);
+    }
+    /** 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`);
+        let screenshot;
+        let screenshotError;
+        try {
+            await writeFile(png, await this.screenshot());
+            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)) ?? {};
+        }
+        catch { /* page gone or stuck: the dump records no url or title */ }
+        const dump = {
+            label,
+            predicate,
+            timeoutMs: timeout,
+            timestamp: new Date().toISOString(),
+            url: where.url ?? null,
+            title: where.title ?? null,
+            screenshot: screenshot ? path.basename(screenshot) : null,
+            screenshotError: screenshotError ?? null,
+            console: this.consoleEntries(),
+        };
+        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. */
+    async attachFailureArtifacts(error, target, predicate, timeout) {
+        try {
+            error.artifacts = await this.captureFailure(target.directory, target.label, predicate, timeout);
+        }
+        catch (captureError) {
+            error.message += ` (failure artifacts were not written: ${captureError instanceof Error ? captureError.message : String(captureError)})`;
+        }
+    }
     async click(target, options = {}) {
         this.mouse.assertReleased();
         await this.withElement(target, async (handle) => {
             const point = await this.point(handle), button = options.button ?? 'left', count = options.clickCount ?? 1;
             await this.send('Input.dispatchMouseEvent', { type: 'mouseMoved', ...point });
             this.mouse.track(point.x, point.y);
+            if (options.checkOccluded)
+                await this.assertUnoccluded(handle, point);
             for (let clickCount = 1; clickCount <= count; clickCount++) {
                 await this.send('Input.dispatchMouseEvent', { type: 'mousePressed', ...point, button, buttons: button === 'left' ? 1 : button === 'right' ? 2 : 4, clickCount });
                 if (options.delay)

package/dist/process.d.ts

@@ -18,5 +18,10 @@ export declare class ProcessTimeoutError extends Error {
     constructor(pid: number, timeoutMs: number, stdout: string, stderr: string);
 }
 export declare function runOwnedProcess(command: string, args?: string[], options?: RunOwnedProcessOptions): Promise<OwnedProcessResult>;
+/**
+ * A free TCP port on 127.0.0.1, found by binding port 0 and releasing it. Another process can take
+ * the port before the caller binds it; bind promptly or retry on EADDRINUSE.
+ */
+export declare function freePort(): Promise<number>;
 export declare function isProcessAlive(pid: number): boolean;
 export declare function killProcessTree(pid: number): Promise<void>;

package/dist/process.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { createServer } from 'node:net';
 export class ProcessTimeoutError extends Error {
     pid;
     stdout;
@@ -54,6 +55,26 @@ export function runOwnedProcess(command, args = [], options = {}) {
         });
     });
 }
+/**
+ * A free TCP port on 127.0.0.1, found by binding port 0 and releasing it. Another process can take
+ * the port before the caller binds it; bind promptly or retry on EADDRINUSE.
+ */
+export function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                server.close();
+                reject(new Error('freePort: no TCP address'));
+                return;
+            }
+            const port = address.port;
+            server.close((error) => (error ? reject(error) : resolve(port)));
+        });
+    });
+}
 export function isProcessAlive(pid) {
     if (!Number.isInteger(pid) || pid <= 0)
         return false;

package/dist/workspace.d.ts

@@ -31,6 +31,11 @@ export interface CreateQaWorkspaceOptions {
     leaseMs?: number;
     retention?: import('./storage.js').RetentionPolicy;
 }
+/**
+ * Create an isolated run home. `env.RIGHTKIT_RUN_ROOT` is set to `home`, which lives inside the
+ * workspace that {@link disposeQaWorkspace} deletes. A host must never map a directory holding
+ * artifacts it wants to keep onto RIGHTKIT_RUN_ROOT: disposal removes that tree.
+ */
 export declare function createQaWorkspace(options: CreateQaWorkspaceOptions): QaWorkspace;
 export interface DisposeOptions {
     /** Keep the recorded evidence and remove only the volatile profile. */
@@ -43,6 +48,11 @@ export interface DisposeOptions {
  * Remove the workspace, retrying through the brief window in which an exiting
  * app still holds its files open. Anything still present afterwards is returned,
  * never silently ignored.
+ *
+ * Deletes `workspace.home`, which is what RIGHTKIT_RUN_ROOT points at, and also
+ * `workspace.root` unless `keepEvidence` is set. Anything a host maps under
+ * RIGHTKIT_RUN_ROOT is deleted: never map a directory holding artifacts you want
+ * to keep onto it.
  */
 export declare function disposeQaWorkspace(workspace: QaWorkspace, options?: DisposeOptions): DisposeReport;
 /**

package/dist/workspace.js

@@ -18,6 +18,11 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createManagedRun, createManagedAppRoot, finishManagedRun, pruneManagedRuns, resolveManagedRoot, } from './storage.js';
+/**
+ * Create an isolated run home. `env.RIGHTKIT_RUN_ROOT` is set to `home`, which lives inside the
+ * workspace that {@link disposeQaWorkspace} deletes. A host must never map a directory holding
+ * artifacts it wants to keep onto RIGHTKIT_RUN_ROOT: disposal removes that tree.
+ */
 export function createQaWorkspace(options) {
     const appKey = requireText(options.appKey, 'appKey');
     const managed = createManagedRun({ managedRoot: options.root ? requireText(options.root, 'root') : resolveManagedRoot(), app: appKey, runId: options.runId ?? crypto.randomUUID(), leaseMs: options.leaseMs, retention: options.retention });
@@ -77,6 +82,11 @@ export function createQaWorkspace(options) {
  * Remove the workspace, retrying through the brief window in which an exiting
  * app still holds its files open. Anything still present afterwards is returned,
  * never silently ignored.
+ *
+ * Deletes `workspace.home`, which is what RIGHTKIT_RUN_ROOT points at, and also
+ * `workspace.root` unless `keepEvidence` is set. Anything a host maps under
+ * RIGHTKIT_RUN_ROOT is deleted: never map a directory holding artifacts you want
+ * to keep onto it.
  */
 export function disposeQaWorkspace(workspace, options = {}) {
     const attempts = Math.max(1, options.attempts ?? 5);

package/package.json

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