@rightkit/qa 0.4.5 → 0.4.6

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.
@@ -143,5 +143,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "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",