@itmetsam/samurai-framework 0.2.1 → 0.2.3

package/README.md

@@ -2,6 +2,8 @@
 
 A browser test framework written in TypeScript. It drives a real browser over the [WebDriver BiDi](https://www.w3.org/TR/webdriver-bidi/) protocol, with no WebDriver server and no Playwright or Puppeteer underneath.
 
+[![CI](https://github.com/degrootsam/samurai-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/degrootsam/samurai-framework/actions/workflows/ci.yml)
+
 ```ts
 import { expect, test } from "../api.js";
 
@@ -86,7 +88,7 @@ bun run dev --timeout 60000    # per-test timeout in ms; also --expect-timeout
 
 Once the package is installed in a project, `samurai run` does the same with a readable summary and a proper exit code, and `samurai init` scaffolds a new project (see [Command line](docs/cli.md)).
 
-A browser window opens for each test and closes when the test ends. The result is written to `result/report.json` (status, duration and error per test); nothing summarises it on the console yet. The process exits with code 0 when every test passed and 1 otherwise (add `--headless` to hide the window). Framework logs go to the console and `logs/`.
+A browser window opens for each test and closes when the test ends. The result is written to `result/report.json` (status, duration and error per test); nothing summarises it on the console yet. The process exits with code 0 when every test passed and 1 otherwise (`--headless` hides the window; on CI it is the default, see [Configuration](docs/configuration.md#headless)). Framework logs go to the console and `logs/`.
 
 > `src/tests/index.spec.ts` is an example that submits a real contact form. Delete it or replace it before running everything.
 

package/dist/cli/args.js

@@ -21,6 +21,7 @@ export function parseCommandLine(argv) {
         args: argv,
         options: FLAGS,
         strict: true,
+        allowNegative: true,
         allowPositionals: true,
     });
 }
@@ -31,8 +32,8 @@ function parseFlags(argv) {
 export function parseRunnerFlags(argv) {
     const values = parseFlags(argv);
     const flags = {};
-    if (values.headless)
-        flags.headless = true;
+    if (values.headless !== undefined)
+        flags.headless = values.headless;
     if (values.port !== undefined) {
         const port = Number(values.port);
         if (!Number.isInteger(port) || port < 1 || port > 65535) {

package/dist/cli/init.js

@@ -1,6 +1,12 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 const PACKAGE = "@itmetsam/samurai-framework";
+/** The version of this package, so a new project asks for the release that scaffolded it */
+function frameworkVersion() {
+    const manifest = new URL("../../package.json", import.meta.url);
+    return JSON.parse(readFileSync(manifest, "utf8"))
+        .version;
+}
 /** The files `samurai init` writes, by path relative to the project folder */
 export function scaffold(name) {
     return {
@@ -10,7 +16,7 @@ export function scaffold(name) {
             private: true,
             type: "module",
             scripts: { test: "samurai run" },
-            dependencies: { [PACKAGE]: "^0.1.0" },
+            dependencies: { [PACKAGE]: `^${frameworkVersion()}` },
             devDependencies: { tsx: "^4.21.0" },
         }, null, 2) + "\n",
         "samurai.config.ts": `import { defineConfig } from "${PACKAGE}";

package/dist/cli/main.d.ts

@@ -1,4 +1,4 @@
-export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless                  Run the browser without a window\n  --port <n>                  Browser debugging port (default 9223)\n\nOptions for record (also --env, --port, --json):\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\nRun it in the project folder, the one holding samurai.config.ts.\n";
+export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n\nOptions for record (also --env, --port, --json):\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\nRun it in the project folder, the one holding samurai.config.ts.\n";
 export interface Io {
     out: (text: string) => void;
     err: (text: string) => void;

package/dist/cli/main.js

@@ -22,7 +22,8 @@ Options for run and list:
 Options for run:
   --timeout <ms>              Time one test may take
   --expect-timeout <ms>       Time actions and assertions retry
-  --headless                  Run the browser without a window
+  --headless, --no-headless   Run the browser without a window, or with one.
+                              Default: the config's use.headless, else headless when CI is set
   --port <n>                  Browser debugging port (default 9223)
 
 Options for record (also --env, --port, --json):

package/dist/config/run-settings.d.ts

@@ -5,6 +5,8 @@ export interface RunOverrides {
     environment?: string;
     timeout?: number;
     expectTimeout?: number;
+    /** Beats the config's `headless`; the command line's `--headless` and `--no-headless` */
+    headless?: boolean;
 }
 /** Everything about a run that depends on the chosen environment */
 export interface RunSettings {
@@ -15,12 +17,18 @@ export interface RunSettings {
     /** Time (ms) actions and assertions retry */
     expectTimeout: number;
     variables: Variables;
+    /** Whether the browser runs without a window */
+    headless: boolean;
 }
 export declare class UnknownEnvironmentError extends Error {
     constructor(message: string);
 }
 /** Picks the environment and applies precedence: run override > environment > project > built-in default */
-export declare function resolveRunSettings(config: SamuraiTestConfig, overrides?: RunOverrides): RunSettings;
+/** True when the `CI` environment variable says this is a CI run (set, and not "", "0" or "false") */
+export declare function isCI(env?: Partial<NodeJS.ProcessEnv>): boolean;
+export declare function resolveRunSettings(config: SamuraiTestConfig, overrides?: RunOverrides, 
+/** Where `CI` is read from */
+env?: Partial<NodeJS.ProcessEnv>): RunSettings;
 /** Makes `settings` the run's settings; `undefined` ends the run (tests use this to reset) */
 export declare function setRunSettings(settings: RunSettings | undefined): void;
 /** The active run's settings, or undefined outside a run (unit and browser tests) */

package/dist/config/run-settings.js

@@ -9,7 +9,14 @@ export class UnknownEnvironmentError extends Error {
     }
 }
 /** Picks the environment and applies precedence: run override > environment > project > built-in default */
-export function resolveRunSettings(config, overrides = {}) {
+/** True when the `CI` environment variable says this is a CI run (set, and not "", "0" or "false") */
+export function isCI(env = process.env) {
+    const value = env.CI?.trim().toLowerCase();
+    return (value !== undefined && value !== "" && value !== "0" && value !== "false");
+}
+export function resolveRunSettings(config, overrides = {}, 
+/** Where `CI` is read from */
+env = process.env) {
     const environments = config.environments ?? {};
     const names = Object.keys(environments);
     const available = `Available: ${names.join(", ")}`;
@@ -43,6 +50,10 @@ export function resolveRunSettings(config, overrides = {}) {
             config.expect?.timeout ??
             DEFAULT_EXPECT_TIMEOUT,
         variables: { ...(environment?.variables ?? {}) },
+        headless: overrides.headless ??
+            environment?.headless ??
+            config.use?.headless ??
+            isCI(env),
     };
 }
 let active;

package/dist/locator/locator.d.ts

@@ -163,6 +163,14 @@ export default class Locator {
     isEditable(): Promise<boolean>;
     /** Wait for certain time (ms). Default: 300ms  */
     wait(duration?: number): Promise<void>;
+    /**
+     * Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input.
+     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Home`, `End`, `PageUp`, `PageDown` and the arrows;
+     * any other key must be a single character.
+     * @example
+     *  await page.getByLabel("New todo").press("Enter");
+     */
+    press(key: string, options?: ActionOptions): Promise<void>;
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     fill(value: string, options?: ActionOptions): Promise<void>;
 }

package/dist/locator/locator.js

@@ -42,7 +42,25 @@ const FILL_CHECKS = [
     "editable",
     "hit target",
 ];
+const PRESS_CHECKS = ["attached", "visible", "enabled"];
 const ATTACHED_ONLY = ["attached"];
+/** WebDriver code points of the named keys `press()` accepts; any other single character is typed as is */
+const NAMED_KEYS = {
+    Backspace: "\uE003",
+    Tab: "\uE004",
+    Enter: "\uE007",
+    Escape: "\uE00C",
+    Space: " ",
+    ArrowLeft: "\uE012",
+    ArrowUp: "\uE013",
+    ArrowRight: "\uE014",
+    ArrowDown: "\uE015",
+    Delete: "\uE017",
+    Home: "\uE011",
+    End: "\uE010",
+    PageUp: "\uE00E",
+    PageDown: "\uE00F",
+};
 /** Unicode code point WebDriver uses for the Backspace key */
 const BACKSPACE = "";
 export default class Locator {
@@ -556,6 +574,34 @@ export default class Locator {
             ],
         });
     }
+    /**
+     * Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input.
+     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Home`, `End`, `PageUp`, `PageDown` and the arrows;
+     * any other key must be a single character.
+     * @example
+     *  await page.getByLabel("New todo").press("Enter");
+     */
+    async press(key, options) {
+        const code = NAMED_KEYS[key] ?? (Array.from(key).length === 1 ? key : "");
+        if (code === "") {
+            throw new Error(`press(): unknown key "${key}". Use one of ${Object.keys(NAMED_KEYS).join(", ")} or a single character`);
+        }
+        await this.waitForActionable("press", PRESS_CHECKS, { scroll: true, hitTest: false }, options);
+        await this.callOnElement(undefined, `el.focus();`);
+        await this.biDiConnector.send("input.performActions", {
+            context: this.contextId,
+            actions: [
+                {
+                    type: "key",
+                    id: "samurai-keyboard",
+                    actions: [
+                        { type: "keyDown", value: code },
+                        { type: "keyUp", value: code },
+                    ],
+                },
+            ],
+        });
+    }
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     async fill(value, options) {
         const state = await this.waitForActionable("fill", FILL_CHECKS, { scroll: true, hitTest: true }, options);

package/dist/recorder/capture.d.ts

@@ -6,6 +6,8 @@
  *   element (a label click reports its control; the click the browser forwards to the control is dropped).
  * - `{ type: "input", target, candidates, value, secret, secretName }`: text typed into a field. Password
  *   values never leave the page: `secret` is set and `value` is left out.
+ * - `{ type: "press", target, candidates, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
+ *   click or typing, which are reported as such).
  * - `{ type: "assert", target, candidates, text, value }`: an Alt+click, which does not reach the page.
  *   While Alt is held, the element under the pointer is outlined.
  *

package/dist/recorder/capture.js

@@ -8,6 +8,8 @@ const OFF_KEY = "samurai.recorder.off";
  *   element (a label click reports its control; the click the browser forwards to the control is dropped).
  * - `{ type: "input", target, candidates, value, secret, secretName }`: text typed into a field. Password
  *   values never leave the page: `secret` is set and `value` is left out.
+ * - `{ type: "press", target, candidates, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
+ *   click or typing, which are reported as such).
  * - `{ type: "assert", target, candidates, text, value }`: an Alt+click, which does not reach the page.
  *   While Alt is held, the element under the pointer is outlined.
  *
@@ -184,6 +186,18 @@ export const CAPTURE_SOURCE = String.raw `(send) => {
     });
   }, true);
 
+  // Enter, Tab and Escape change what the page does next (an Enter adds a todo and clears the field), so they are steps
+  const RECORDED_KEYS = ["Enter", "Tab", "Escape"];
+  // Enter on these is a click, which is recorded as one
+  const ACTIVATES = "a[href],button,summary,select,input[type=button],input[type=submit],input[type=reset],input[type=checkbox],input[type=radio]";
+  document.addEventListener("keydown", (event) => {
+    if (off() || !event.isTrusted || event.isComposing || event.ctrlKey || event.altKey || event.metaKey || event.shiftKey) return;
+    if (RECORDED_KEYS.indexOf(event.key) < 0 || !(event.target instanceof Element)) return;
+    const el = event.target;
+    if (event.key === "Enter" && (el.closest(ACTIVATES) || el.tagName === "TEXTAREA" || el.isContentEditable)) return;
+    report({ type: "press", target: el, candidates: candidatesOf(el), pressed: event.key });
+  }, true);
+
   document.addEventListener("mousemove", (event) => {
     if (off() || !event.altKey || !(event.target instanceof Element) || event.target === outlined) return;
     unhighlight();

package/dist/recorder/normalise.d.ts

@@ -22,6 +22,11 @@ export type Observation = {
     value?: string;
     secret?: boolean;
     secretName?: string;
+} | {
+    type: "press";
+    key: string;
+    locator: LocatorSpec;
+    pressed: string;
 } | {
     type: "assert";
     key: string;

package/dist/recorder/normalise.js

@@ -60,6 +60,18 @@ export class Normaliser {
             this.lastAction = at;
             return [this.insert({ kind: "click", locator: observation.locator })];
         }
+        if (observation.type === "press") {
+            // The page may react by clearing the field: what is typed next is a new fill, not a rewrite of this one
+            this.lastFill = undefined;
+            this.lastAction = at;
+            return [
+                this.insert({
+                    kind: "press",
+                    locator: observation.locator,
+                    key: observation.pressed,
+                }),
+            ];
+        }
         if (observation.type === "assert") {
             this.lastFill = undefined;
             return [

package/dist/recorder/recorder.js

@@ -99,24 +99,26 @@ export class Recorder {
         const key = message.target.sharedId;
         const observation = message.type === "click"
             ? { type: "click", key, locator, textEntry: message.textEntry === true }
-            : message.type === "assert"
-                ? {
-                    type: "assert",
-                    key,
-                    locator,
-                    text: message.text ?? "",
-                    ...(message.value !== undefined && { value: message.value }),
-                }
-                : {
-                    type: "input",
-                    key,
-                    locator,
-                    ...(message.value !== undefined && { value: message.value }),
-                    ...(message.secret && { secret: true }),
-                    ...(message.secretName !== undefined && {
-                        secretName: message.secretName,
-                    }),
-                };
+            : message.type === "press"
+                ? { type: "press", key, locator, pressed: message.pressed ?? "" }
+                : message.type === "assert"
+                    ? {
+                        type: "assert",
+                        key,
+                        locator,
+                        text: message.text ?? "",
+                        ...(message.value !== undefined && { value: message.value }),
+                    }
+                    : {
+                        type: "input",
+                        key,
+                        locator,
+                        ...(message.value !== undefined && { value: message.value }),
+                        ...(message.secret && { secret: true }),
+                        ...(message.secretName !== undefined && {
+                            secretName: message.secretName,
+                        }),
+                    };
         this.emit(this.normaliser.observe(observation, Date.now()));
     }
     async release() {

package/dist/recorder/session.d.ts

@@ -18,6 +18,8 @@ export interface RecordSpecOptions extends ProjectOptions {
     url?: string;
     /** The browser's debugging port. @default 9223 */
     port?: number;
+    /** Run the browser without a window. A person can't use it then; for tests and machines without a display. @default the config's `use.headless`, else headless on CI and a window otherwise */
+    headless?: boolean;
     /** Aborting ends the recording, like closing the browser window */
     signal?: AbortSignal;
     /** Called after each step is written to the file, with the file's new content */

package/dist/recorder/session.js

@@ -66,7 +66,10 @@ export async function recordSpec(options) {
         if (!Number.isInteger(at) || at < 0 || at > test.steps.length) {
             throw new RangeError(`--at must be between 0 and ${test.steps.length} (the test has ${test.steps.length} steps)`);
         }
-        const { browser, page } = await Browser.launch("firefox", { port: options.port ?? 9223, headless: false }, options.signal);
+        const { browser, page } = await Browser.launch("firefox", {
+            port: options.port ?? 9223,
+            headless: options.headless ?? settings.headless,
+        }, options.signal);
         const events = [];
         try {
             const start = options.url ?? settings.baseURL;

package/dist/runner/project.js

@@ -11,7 +11,7 @@ export async function withProject(options, work) {
     if (active)
         throw new Error("A test run is already active in this process");
     active = true;
-    const { projectDir: dir, config, dataDir, environment, timeout, expectTimeout, } = options;
+    const { projectDir: dir, config, dataDir, environment, timeout, expectTimeout, headless, } = options;
     const previousDir = projectDir();
     try {
         setActiveProject({ dir: dir ?? previousDir, config, dataDir });
@@ -22,6 +22,7 @@ export async function withProject(options, work) {
             ...(environment !== undefined && { environment }),
             ...(timeout !== undefined && { timeout }),
             ...(expectTimeout !== undefined && { expectTimeout }),
+            ...(headless !== undefined && { headless }),
         });
         return await work(run);
     }

package/dist/runner/test-runner.js

@@ -13,6 +13,7 @@ import TestReporter, {} from "./reporter.js";
 import Page from "../browser/page.js";
 import { takePendingAssertions } from "../assert/expect.js";
 import { toTestError } from "./test-error.js";
+import { ConnectionClosedError } from "../transport/bidi-connection.js";
 import { judgePageLogs } from "./page-logs-report.js";
 /** Whether a test with this full name is selected by the options */
 export function isSelected(name, { grep, testNames }) {
@@ -97,6 +98,17 @@ export default class TestRunner {
     async executeTestCase(test, reporter) {
         logger.verbose("Starting test: %s", test.name);
         reporter.onTestStart(test);
+        // A test ends once, whichever of finishing, failing, timing out, an abort or a closed browser comes first
+        let ended = false;
+        const finish = (error, logs) => {
+            if (ended)
+                return;
+            ended = true;
+            reporter.onTestEnd(test, error, logs);
+        };
+        let browserClosed = false;
+        /** Set once the runner itself closes the browser */
+        let closing = false;
         const selectedBrowser = (await readConfig("browser")) ?? "firefox";
         const { settings, secrets } = this.run;
         const timeout = settings.timeout;
@@ -108,7 +120,7 @@ export default class TestRunner {
         await Promise.race([
             new Promise((resolve) => {
                 timeoutTimer = setTimeout(() => {
-                    reporter.onTestEnd(test, {
+                    finish({
                         message: `Test timed out after ${timeout / 1000} seconds`,
                         type: "timeout",
                     });
@@ -118,7 +130,7 @@ export default class TestRunner {
                 onRunAborted = () => {
                     if (timeoutController.signal.aborted)
                         return;
-                    reporter.onTestEnd(test, { message: "Run aborted", type: "error" });
+                    finish({ message: "Run aborted", type: "error" });
                     timeoutController.abort(new Error("Run aborted"));
                     resolve();
                 };
@@ -130,9 +142,22 @@ export default class TestRunner {
                 try {
                     const launched = await Browser.launch(selectedBrowser, {
                         port: this.options.port ?? 9223,
-                        headless: this.options.headless ?? false,
+                        headless: this.options.headless ?? settings.headless,
                     }, timeoutController.signal);
                     browser = launched.browser;
+                    // A person closing the window, or the browser crashing: end the test now instead of waiting for a
+                    // command to time out
+                    void launched.browser.exited.then(() => {
+                        if (ended || closing)
+                            return;
+                        browserClosed = true;
+                        finish({
+                            message: "The browser was closed while the test was running",
+                            type: "error",
+                        });
+                        timeoutController.abort(new Error("Browser closed"));
+                        resolve();
+                    });
                     page = launched.page;
                     const fixtures = {
                         page: launched.page,
@@ -146,7 +171,7 @@ export default class TestRunner {
                         return resolve();
                     const unawaited = takePendingAssertions();
                     if (unawaited.length > 0) {
-                        reporter.onTestEnd(test, {
+                        finish({
                             message: unawaited
                                 .map((matcher) => `expect(locator).${matcher}() was not awaited`)
                                 .join("\n"),
@@ -155,13 +180,18 @@ export default class TestRunner {
                         return resolve();
                     }
                     const verdict = await judgeLogs(page, false);
-                    reporter.onTestEnd(test, verdict.error, verdict);
+                    finish(verdict.error, verdict);
                     resolve();
                 }
                 catch (err) {
                     if (timeoutController.signal.aborted)
                         return resolve();
-                    reporter.onTestEnd(test, toTestError(err), await judgeLogs(page, true));
+                    finish(browserClosed || err instanceof ConnectionClosedError
+                        ? {
+                            message: "The browser was closed while the test was running",
+                            type: "error",
+                        }
+                        : toTestError(err), await judgeLogs(page, true));
                     resolve();
                 }
             }),
@@ -171,6 +201,7 @@ export default class TestRunner {
             this.options.signal?.removeEventListener("abort", onRunAborted);
         takePendingAssertions();
         logger.verbose("Closing browser for test: %s", test.name);
+        closing = true;
         await browser?.close();
     }
 }

package/dist/steps/emit.js

@@ -63,6 +63,8 @@ export function stepToSource(step) {
             return `await ${locatorToSource(step.locator)}.click();`;
         case "fill":
             return `await ${locatorToSource(step.locator)}.fill(${valueToSource(step.value)});`;
+        case "press":
+            return `await ${locatorToSource(step.locator)}.press(${str(step.key)});`;
         case "expect":
             return `await expect(${locatorToSource(step.locator)})${step.not ? ".not" : ""}.${expectationToSource(step.expectation)};`;
         case "waitForNetworkIdle":

package/dist/steps/model.d.ts

@@ -75,6 +75,12 @@ export type Step = {
     locator: LocatorSpec;
     not: boolean;
     expectation: Expectation;
+}
+/** A key pressed while the element has focus, e.g. `Enter` to submit a field. Named as Playwright names keys */
+ | {
+    kind: "press";
+    locator: LocatorSpec;
+    key: string;
 } | {
     kind: "waitForNetworkIdle";
 }

package/dist/steps/parse.js

@@ -214,6 +214,10 @@ function readStep(statement) {
         return undefined;
     if (name.text === "click" && args.length === 0)
         return { kind: "click", locator };
+    if (name.text === "press" && args.length === 1) {
+        const key = stringOf(args[0]);
+        return key === undefined ? undefined : { kind: "press", locator, key };
+    }
     if (name.text === "fill" && args.length === 1) {
         const value = readValue(args[0]);
         return value ? { kind: "fill", locator, value } : undefined;

package/dist/transport/bidi-connection.d.ts

@@ -8,9 +8,21 @@ export interface SendOptions {
     /** Overrides the connector's commandTimeout for this command */
     timeout?: number;
 }
+/**
+ * The connection to the browser is gone (the browser exited or was closed, or the socket dropped). Commands that
+ * were waiting fail with it, and so does every command sent afterwards: a closed socket would swallow them silently.
+ */
+export declare class ConnectionClosedError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 export declare class BiDiConnector {
     private resolveMap;
     private currentId;
+    /** Set once the socket closed or failed: nothing sent after that gets an answer */
+    private closed;
     private webSocket;
     private eventEmitter;
     private commandTimeout;
@@ -19,6 +31,7 @@ export declare class BiDiConnector {
     static connect(url: string, options?: ConnectorOptions): Promise<BiDiConnector>;
     private onWebsocketClose;
     private onWebsocketError;
+    private get isClosed();
     /** Rejects every pending command; `reason` gets the pending method names for its message */
     private rejectAll;
     private getId;

package/dist/transport/bidi-connection.js

@@ -5,15 +5,30 @@ import { BiDiError } from "./bidi-error.js";
 import { SubscriptionManager, } from "./subscriptions.js";
 /** Time (ms) a command may wait for its reply before it fails with code "timeout" */
 const DEFAULT_COMMAND_TIMEOUT = 30000;
+/**
+ * The connection to the browser is gone (the browser exited or was closed, or the socket dropped). Commands that
+ * were waiting fail with it, and so does every command sent afterwards: a closed socket would swallow them silently.
+ */
+export class ConnectionClosedError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = "ConnectionClosedError";
+        this.cause = options?.cause;
+    }
+}
 export class BiDiConnector {
     constructor(ws, options = {}) {
         this.resolveMap = new Map();
         this.currentId = 0;
+        /** Set once the socket closed or failed: nothing sent after that gets an answer */
+        this.closed = false;
         this.onWebsocketClose = () => {
-            this.rejectAll((pending) => new Error(`Websocket closed${pendingSuffix(pending)}`));
+            this.closed = true;
+            this.rejectAll((pending) => new ConnectionClosedError(`Websocket closed${pendingSuffix(pending)}`));
         };
         this.onWebsocketError = (ev) => {
-            this.rejectAll((pending) => Object.assign(new Error(`Websocket error${pendingSuffix(pending)}`), {
+            this.closed = true;
+            this.rejectAll((pending) => new ConnectionClosedError(`Websocket error${pendingSuffix(pending)}`, {
                 cause: ev,
             }));
         };
@@ -69,6 +84,11 @@ export class BiDiConnector {
             });
         });
     }
+    get isClosed() {
+        // A socket that is closing or closed (readyState 2 or 3) has already lost the browser
+        const state = this.webSocket.readyState;
+        return this.closed || (typeof state === "number" && state > 1);
+    }
     /** Rejects every pending command; `reason` gets the pending method names for its message */
     rejectAll(reason) {
         const entries = [...this.resolveMap.values()];
@@ -82,6 +102,10 @@ export class BiDiConnector {
     send(method, params, options = {}) {
         return new Promise((resolve, reject) => {
             try {
+                if (this.isClosed) {
+                    // Sending on a closed socket is silently dropped: without this the command waits out its timeout
+                    throw new ConnectionClosedError(`Websocket closed: cannot send ${method}`);
+                }
                 const id = this.getId();
                 const timeout = options.timeout ?? this.commandTimeout;
                 const timer = setTimeout(() => {
@@ -166,7 +190,8 @@ export class BiDiConnector {
         this.webSocket.removeEventListener("message", this.messageListener);
         this.webSocket.removeEventListener("close", this.onWebsocketClose);
         this.webSocket.removeEventListener("error", this.onWebsocketError);
-        this.rejectAll((pending) => new Error(`BiDiConnector killed${pendingSuffix(pending)}`));
+        this.closed = true;
+        this.rejectAll((pending) => new ConnectionClosedError(`BiDiConnector killed${pendingSuffix(pending)}`));
         this.eventEmitter.removeAllListeners();
         this.webSocket.close();
     }

package/dist/types/config.d.ts

@@ -31,6 +31,8 @@ export interface SamuraiEnvironment {
   /** Overrides the project timeout (ms) for this environment */
   timeout?: number;
   expect?: { timeout?: number };
+  /** Overrides `use.headless` for this environment, e.g. `true` for a `ci` environment */
+  headless?: boolean;
   /** Test data, used in steps as ${name}. Never put secrets here. */
   variables?: Record<string, string | number | boolean>;
 }
@@ -90,6 +92,11 @@ export interface SamuraiTestConfig {
      * @default { width: 1280, height: 720 }
      */
     viewport?: { width: number; height: number } | null;
+    /**
+     * Run the browser without a window. Needed on machines without a display, such as CI runners.
+     * Left out, a run is headless when the `CI` environment variable is set and shows a window otherwise
+     */
+    headless?: boolean;
   };
   /** What to do with the browser's console output and uncaught page exceptions */
   logs?: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.2.1",
-  "description": "",
+  "version": "0.2.3",
+  "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {
     ".": {
@@ -37,7 +37,14 @@
     "test:browser": "tsx --test --test-concurrency=1 \"src/**/*.browser-test.ts\"",
     "test:cli": "tsx --test --test-concurrency=1 \"src/**/*.cli-test.ts\""
   },
-  "keywords": [],
+  "keywords": [
+    "testing",
+    "browser",
+    "e2e",
+    "webdriver-bidi",
+    "firefox",
+    "recorder"
+  ],
   "author": "",
   "license": "ISC",
   "type": "module",
@@ -64,5 +71,19 @@
     "tsx": {
       "optional": true
     }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/degrootsam/samurai-framework.git"
+  },
+  "homepage": "https://github.com/degrootsam/samurai-framework#readme",
+  "bugs": {
+    "url": "https://github.com/degrootsam/samurai-framework/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
   }
 }

package/dist/cli/cli.cli-test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/cli/cli.cli-test.js

@@ -1,170 +0,0 @@
-import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import path from "node:path";
-import { describe, it } from "node:test";
-import { ConsoleReporter } from "./console-reporter.js";
-import { initProject, scaffold } from "./init.js";
-import { main, USAGE } from "./main.js";
-function io() {
-    const out = [];
-    const err = [];
-    const target = {
-        out: (t) => out.push(t),
-        err: (t) => err.push(t),
-        color: false,
-        env: {},
-    };
-    return { target, out: () => out.join(""), err: () => err.join("") };
-}
-describe("main", () => {
-    it("prints the usage for --help, -h and help", async () => {
-        for (const argv of [["--help"], ["-h"], ["help"], ["run", "--help"]]) {
-            const { target, out } = io();
-            assert.equal(await main(argv, target), 0);
-            assert.equal(out(), USAGE);
-        }
-    });
-    it("prints the version", async () => {
-        const { target, out } = io();
-        assert.equal(await main(["--version"], target), 0);
-        assert.match(out(), /^\d+\.\d+\.\d+/);
-    });
-    it("exits 2 for an unknown command, with the usage", async () => {
-        const { target, err } = io();
-        assert.equal(await main(["bogus"], target), 2);
-        assert.match(err(), /Unknown command "bogus"/);
-        assert.match(err(), /Usage:/);
-    });
-    it("exits 2 for an unknown flag or a bad value, with a message", async () => {
-        const flag = io();
-        assert.equal(await main(["run", "--nope"], flag.target), 2);
-        assert.match(flag.err(), /nope/);
-        const port = io();
-        assert.equal(await main(["run", "--port", "abc"], port.target), 2);
-        assert.match(port.err(), /--port/);
-    });
-    it("exits 2 when the project has no config", async () => {
-        const dir = mkdtempSync(path.join(tmpdir(), "samurai-cli-"));
-        const previous = process.cwd();
-        process.chdir(dir);
-        try {
-            const { target, err } = io();
-            assert.equal(await main(["list"], target), 2);
-            assert.ok(err().length > 0);
-        }
-        finally {
-            process.chdir(previous);
-        }
-    });
-    it("record needs a spec and a sensible --at", async () => {
-        const none = io();
-        assert.equal(await main(["record"], none.target), 2);
-        assert.match(none.err(), /Which spec/);
-        const bad = io();
-        assert.equal(await main(["record", "a.spec.ts", "--at", "x"], bad.target), 2);
-        assert.match(bad.err(), /--at/);
-    });
-    it("record refuses a spec that does not exist unless --new is given", async () => {
-        const dir = mkdtempSync(path.join(tmpdir(), "samurai-cli-"));
-        writeFileSync(path.join(dir, "samurai.config.ts"), "export default {};");
-        const previous = process.cwd();
-        process.chdir(dir);
-        try {
-            const { target, err } = io();
-            assert.equal(await main(["record", "tests/none.spec.ts"], target), 2);
-            assert.match(err(), /does not exist/);
-        }
-        finally {
-            process.chdir(previous);
-        }
-    });
-    it("init scaffolds a project and never overwrites", async () => {
-        const dir = mkdtempSync(path.join(tmpdir(), "samurai-init-"));
-        writeFileSync(path.join(dir, "package.json"), '{"name":"mine"}');
-        const { target, out } = io();
-        assert.equal(await main(["init", dir], target), 0);
-        assert.match(out(), /kept\s+package\.json/);
-        assert.match(out(), /created samurai\.config\.ts/);
-        assert.equal(readFileSync(path.join(dir, "package.json"), "utf8"), '{"name":"mine"}');
-        for (const file of [
-            "samurai.config.ts",
-            "tests/example.spec.ts",
-            ".env.example",
-            ".gitignore",
-        ]) {
-            assert.ok(existsSync(path.join(dir, file)), file);
-        }
-    });
-});
-describe("scaffold", () => {
-    it("is an ES module project with a test script", () => {
-        const manifest = JSON.parse(scaffold("shop")["package.json"]);
-        assert.equal(manifest.type, "module");
-        assert.equal(manifest.scripts.test, "samurai run");
-        assert.equal(manifest.name, "shop");
-    });
-    it("names the package after the folder, safely", () => {
-        const dir = mkdtempSync(path.join(tmpdir(), "My Shop!-"));
-        initProject(dir);
-        const manifest = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
-        assert.match(manifest.name, /^[a-z0-9-]+$/);
-    });
-});
-describe("ConsoleReporter", () => {
-    const summary = {
-        status: "failed",
-        duration: 2300,
-        startTime: 0,
-        environment: "staging",
-        tests: [
-            {
-                name: "a",
-                file: "/x/a.spec.ts",
-                startTime: 0,
-                status: "success",
-                duration: 1000,
-            },
-            {
-                name: "b > c",
-                file: "/x/a.spec.ts",
-                startTime: 0,
-                status: "failed",
-                duration: 1300,
-                type: "error",
-                message: "boom\nsecond line",
-            },
-        ],
-    };
-    it("prints a line per test, the failures in full and a count", () => {
-        let text = "";
-        const reporter = new ConsoleReporter({
-            write: (t) => (text += t),
-            color: false,
-        });
-        reporter.handle({ type: "run-start", environment: "staging", total: 2 });
-        reporter.handle({ type: "test-start", name: "a", file: "/x/a.spec.ts" });
-        for (const result of summary.tests)
-            reporter.handle({
-                type: "test-end",
-                name: "name" in result ? result.name : "",
-                file: "/x/a.spec.ts",
-                result,
-            });
-        reporter.handle({ type: "run-end", summary });
-        assert.match(text, /Running 2 tests against staging/);
-        assert.match(text, /✔ a \(1\.0s\)/);
-        assert.match(text, /✖ b > c \(1\.3s\)/);
-        assert.match(text, /\n {4}boom\n {4}second line\n/);
-        assert.match(text, /1 failed, 1 passed \(2\.3s\)/);
-        assert.ok(!text.includes("\u001b"), "no colour codes when colour is off");
-    });
-    it("colours when asked to", () => {
-        let text = "";
-        new ConsoleReporter({ write: (t) => (text += t), color: true }).handle({
-            type: "run-end",
-            summary,
-        });
-        assert.ok(text.includes("\u001b[31m"));
-    });
-});