@rightkit/qa 0.4.2 → 0.4.3

package/README.md

@@ -86,6 +86,28 @@ 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.
 
+## 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/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/page.d.ts

@@ -85,6 +85,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 {

package/dist/page.js

@@ -211,6 +211,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;

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.3",
   "description": "Shared QA evidence, ownership, browser helpers, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",