@itmetsam/samurai-framework 0.5.0 → 0.7.0

package/dist/recorder/toolbar/styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The toolbar's styles, scoped to its shadow root: the rail, the collapsed chip, the panels, the picker
+ * outline and the toast, as in the approved mockups. Everything inside is `position: fixed` against the
+ * viewport; the host itself takes no space.
+ */
+export declare const TOOLBAR_CSS = "\n:host { all: initial; }\n* { box-sizing: border-box; }\n.ui { font: 12px/1.3 system-ui, -apple-system, \"Segoe UI\", sans-serif; color: #222; color-scheme: light; }\nbutton, input, select { font: inherit; color: inherit; margin: 0; }\nbutton { appearance: none; background: none; border: 0; padding: 0; cursor: pointer; text-align: left; }\nbutton:disabled { cursor: default; }\ncode { font: 11.5px ui-monospace, SFMono-Regular, Menlo, monospace; }\n\n.rail, .chip { position: fixed; z-index: 3; box-shadow: 0 6px 20px rgba(0,0,0,.28); background: #17181c; color: #e9eaee; user-select: none; }\n.rail { display: flex; flex-direction: column; gap: 2px; border-radius: 10px; padding: 5px; width: 112px; }\n.rail.wide { width: 150px; }\n.top { display: flex; align-items: center; justify-content: space-between; color: #6b6e78; padding: 0 2px 2px; }\n[data-grip] { cursor: grab; flex: 1; touch-action: none; }\n[data-grip]:active { cursor: grabbing; }\n.chev { color: #6b6e78; padding: 0 3px; border-radius: 4px; }\n.chev:hover { color: #e9eaee; }\n.st { display: flex; align-items: center; gap: 6px; padding: 4px 6px; font-weight: 600; }\n.dot { width: 8px; height: 8px; border-radius: 50%; background: #ff4d4f; box-shadow: 0 0 0 3px rgba(255,77,79,.25); flex: none; }\n.dot.pause { background: #f5b301; box-shadow: 0 0 0 3px rgba(245,179,1,.25); }\n.b { padding: 5px 7px; border-radius: 6px; display: flex; align-items: center; gap: 6px; width: 100%; }\n.b:hover:not(:disabled) { background: #2a2c33; }\n.b.on, .b.on:hover:not(:disabled) { background: #2f6fed; color: #fff; }\n.b:disabled { opacity: .38; }\n.sep { height: 1px; background: #34363d; margin: 2px 3px; }\n.stop { color: #ff8a8c; }\n.ico { width: 14px; text-align: center; flex: none; }\n.note { font-size: 10.5px; color: #c9cbd2; padding: 4px 6px 2px; line-height: 1.35; }\n.ask { display: flex; gap: 4px; padding: 2px 6px 4px; }\n.ask button { flex: 1; text-align: center; border-radius: 5px; padding: 3px 0; background: #2a2c33; }\n.ask button.yes { background: #2f6fed; color: #fff; font-weight: 600; }\n\n.chip { display: flex; align-items: center; gap: 7px; border-radius: 999px; padding: 6px 10px 6px 8px; font-weight: 600; }\n.chip [data-grip] { color: #6b6e78; flex: none; }\n.chip .chev { color: #9a9ca5; }\n\n.panel { position: fixed; z-index: 2; width: 230px; max-height: calc(100vh - 16px); overflow: auto; background: #fff; border: 1px solid #d9dce1; border-radius: 10px; box-shadow: 0 10px 28px rgba(0,0,0,.18); color: #222; }\n.panel.wide { width: 236px; }\n.h { padding: 8px 10px; border-bottom: 1px solid #eceef1; font-weight: 600; display: flex; justify-content: space-between; gap: 8px; }\n.h.stack { display: block; }\n.h code { font-size: 11px; color: #555; font-weight: 400; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.h small { display: block; font-weight: 400; color: #777; margin-top: 2px; }\n.msg { padding: 10px; color: #555; }\n.err { padding: 6px 10px; color: #c22b2e; }\n.opts { padding: 6px; display: grid; grid-template-columns: 1fr 1fr; gap: 4px; }\n.o { border: 1px solid #e3e5e8; border-radius: 6px; padding: 5px 6px; }\n.o:hover:not(:disabled) { border-color: #b9c6e4; }\n.o.sel { border-color: #2f6fed; background: #eef3fe; color: #1d4fc4; font-weight: 600; }\n.o:disabled { opacity: .45; }\n.val { margin: 2px 8px 8px; display: flex; flex-direction: column; gap: 4px; }\n.in { width: 100%; border: 1px solid #cfd3d8; border-radius: 4px; padding: 5px 6px; background: #fff; outline: none; }\n.in:focus { border-color: #2f6fed; box-shadow: 0 0 0 2px rgba(47,111,237,.15); }\n.in.code { font: 11.5px ui-monospace, SFMono-Regular, Menlo, monospace; }\n.row { display: flex; justify-content: space-between; align-items: center; padding: 0 8px 8px; }\n.neg { color: #555; display: flex; align-items: center; gap: 4px; }\n.add { background: #2f6fed; color: #fff; border-radius: 6px; padding: 5px 12px; font-weight: 600; text-align: center; }\n.add:disabled { opacity: .5; }\n.cancel { padding: 5px 10px; color: #555; }\n.foot { display: flex; justify-content: flex-end; gap: 8px; padding: 8px 10px; border-top: 1px solid #eceef1; }\n.foot.plain { border-top: 0; padding-top: 10px; }\n\n.search { display: block; margin: 6px 8px; width: calc(100% - 16px); }\n.grp { font-size: 10px; text-transform: uppercase; letter-spacing: .04em; color: #888; padding: 6px 10px 2px; }\n.it { display: flex; justify-content: space-between; gap: 8px; padding: 5px 10px; width: 100%; }\n.it:hover, .it.sel { background: #eef3fe; }\n.it .v { color: #777; max-width: 110px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.warn { color: #b26a00; }\n.empty { padding: 4px 10px; color: #777; }\n.act { padding: 6px 10px; color: #1d4fc4; font-weight: 600; width: 100%; }\n.act:hover { background: #eef3fe; }\n\n.seg { display: flex; margin: 8px 10px 0; border: 1px solid #cfd3d8; border-radius: 6px; overflow: hidden; }\n.seg button { flex: 1; text-align: center; padding: 4px; }\n.seg .sel { background: #eef3fe; color: #1d4fc4; font-weight: 600; }\n.lbl { font-size: 11px; color: #666; padding: 6px 10px 2px; }\n.f { padding: 0 10px; }\n.field-error { color: #c22b2e; font-size: 11px; padding: 3px 10px 0; }\n.hint { padding: 6px 10px 0; color: #666; font-size: 11px; line-height: 1.35; }\n.hint code { font-size: 10.5px; }\n\n.radio { padding: 6px 10px; display: flex; gap: 7px; align-items: center; }\n.radio input[type=radio] { accent-color: #2f6fed; margin: 0; }\n.sub { color: #777; font-size: 11px; padding: 0 10px 2px 30px; margin-top: -4px; }\n.num { width: 52px; border: 1px solid #cfd3d8; border-radius: 4px; padding: 3px 5px; }\n\n.outline { position: fixed; z-index: 1; pointer-events: none; outline: 2px solid #2f6fed; outline-offset: 2px; border-radius: 4px; background: rgba(47,111,237,.06); }\n.toast { position: fixed; z-index: 4; left: 50%; bottom: 14px; transform: translateX(-50%); background: #17181c; color: #e9eaee; border-radius: 8px; padding: 6px 12px; box-shadow: 0 6px 20px rgba(0,0,0,.28); pointer-events: none; transition: opacity .3s; }\n.toast.gone { opacity: 0; }\n.frame { position: fixed; inset: 0; pointer-events: none; visibility: hidden; }\n";

package/dist/recorder/toolbar/styles.js

@@ -0,0 +1,95 @@
+/**
+ * The toolbar's styles, scoped to its shadow root: the rail, the collapsed chip, the panels, the picker
+ * outline and the toast, as in the approved mockups. Everything inside is `position: fixed` against the
+ * viewport; the host itself takes no space.
+ */
+export const TOOLBAR_CSS = `
+:host { all: initial; }
+* { box-sizing: border-box; }
+.ui { font: 12px/1.3 system-ui, -apple-system, "Segoe UI", sans-serif; color: #222; color-scheme: light; }
+button, input, select { font: inherit; color: inherit; margin: 0; }
+button { appearance: none; background: none; border: 0; padding: 0; cursor: pointer; text-align: left; }
+button:disabled { cursor: default; }
+code { font: 11.5px ui-monospace, SFMono-Regular, Menlo, monospace; }
+
+.rail, .chip { position: fixed; z-index: 3; box-shadow: 0 6px 20px rgba(0,0,0,.28); background: #17181c; color: #e9eaee; user-select: none; }
+.rail { display: flex; flex-direction: column; gap: 2px; border-radius: 10px; padding: 5px; width: 112px; }
+.rail.wide { width: 150px; }
+.top { display: flex; align-items: center; justify-content: space-between; color: #6b6e78; padding: 0 2px 2px; }
+[data-grip] { cursor: grab; flex: 1; touch-action: none; }
+[data-grip]:active { cursor: grabbing; }
+.chev { color: #6b6e78; padding: 0 3px; border-radius: 4px; }
+.chev:hover { color: #e9eaee; }
+.st { display: flex; align-items: center; gap: 6px; padding: 4px 6px; font-weight: 600; }
+.dot { width: 8px; height: 8px; border-radius: 50%; background: #ff4d4f; box-shadow: 0 0 0 3px rgba(255,77,79,.25); flex: none; }
+.dot.pause { background: #f5b301; box-shadow: 0 0 0 3px rgba(245,179,1,.25); }
+.b { padding: 5px 7px; border-radius: 6px; display: flex; align-items: center; gap: 6px; width: 100%; }
+.b:hover:not(:disabled) { background: #2a2c33; }
+.b.on, .b.on:hover:not(:disabled) { background: #2f6fed; color: #fff; }
+.b:disabled { opacity: .38; }
+.sep { height: 1px; background: #34363d; margin: 2px 3px; }
+.stop { color: #ff8a8c; }
+.ico { width: 14px; text-align: center; flex: none; }
+.note { font-size: 10.5px; color: #c9cbd2; padding: 4px 6px 2px; line-height: 1.35; }
+.ask { display: flex; gap: 4px; padding: 2px 6px 4px; }
+.ask button { flex: 1; text-align: center; border-radius: 5px; padding: 3px 0; background: #2a2c33; }
+.ask button.yes { background: #2f6fed; color: #fff; font-weight: 600; }
+
+.chip { display: flex; align-items: center; gap: 7px; border-radius: 999px; padding: 6px 10px 6px 8px; font-weight: 600; }
+.chip [data-grip] { color: #6b6e78; flex: none; }
+.chip .chev { color: #9a9ca5; }
+
+.panel { position: fixed; z-index: 2; width: 230px; max-height: calc(100vh - 16px); overflow: auto; background: #fff; border: 1px solid #d9dce1; border-radius: 10px; box-shadow: 0 10px 28px rgba(0,0,0,.18); color: #222; }
+.panel.wide { width: 236px; }
+.h { padding: 8px 10px; border-bottom: 1px solid #eceef1; font-weight: 600; display: flex; justify-content: space-between; gap: 8px; }
+.h.stack { display: block; }
+.h code { font-size: 11px; color: #555; font-weight: 400; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.h small { display: block; font-weight: 400; color: #777; margin-top: 2px; }
+.msg { padding: 10px; color: #555; }
+.err { padding: 6px 10px; color: #c22b2e; }
+.opts { padding: 6px; display: grid; grid-template-columns: 1fr 1fr; gap: 4px; }
+.o { border: 1px solid #e3e5e8; border-radius: 6px; padding: 5px 6px; }
+.o:hover:not(:disabled) { border-color: #b9c6e4; }
+.o.sel { border-color: #2f6fed; background: #eef3fe; color: #1d4fc4; font-weight: 600; }
+.o:disabled { opacity: .45; }
+.val { margin: 2px 8px 8px; display: flex; flex-direction: column; gap: 4px; }
+.in { width: 100%; border: 1px solid #cfd3d8; border-radius: 4px; padding: 5px 6px; background: #fff; outline: none; }
+.in:focus { border-color: #2f6fed; box-shadow: 0 0 0 2px rgba(47,111,237,.15); }
+.in.code { font: 11.5px ui-monospace, SFMono-Regular, Menlo, monospace; }
+.row { display: flex; justify-content: space-between; align-items: center; padding: 0 8px 8px; }
+.neg { color: #555; display: flex; align-items: center; gap: 4px; }
+.add { background: #2f6fed; color: #fff; border-radius: 6px; padding: 5px 12px; font-weight: 600; text-align: center; }
+.add:disabled { opacity: .5; }
+.cancel { padding: 5px 10px; color: #555; }
+.foot { display: flex; justify-content: flex-end; gap: 8px; padding: 8px 10px; border-top: 1px solid #eceef1; }
+.foot.plain { border-top: 0; padding-top: 10px; }
+
+.search { display: block; margin: 6px 8px; width: calc(100% - 16px); }
+.grp { font-size: 10px; text-transform: uppercase; letter-spacing: .04em; color: #888; padding: 6px 10px 2px; }
+.it { display: flex; justify-content: space-between; gap: 8px; padding: 5px 10px; width: 100%; }
+.it:hover, .it.sel { background: #eef3fe; }
+.it .v { color: #777; max-width: 110px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.warn { color: #b26a00; }
+.empty { padding: 4px 10px; color: #777; }
+.act { padding: 6px 10px; color: #1d4fc4; font-weight: 600; width: 100%; }
+.act:hover { background: #eef3fe; }
+
+.seg { display: flex; margin: 8px 10px 0; border: 1px solid #cfd3d8; border-radius: 6px; overflow: hidden; }
+.seg button { flex: 1; text-align: center; padding: 4px; }
+.seg .sel { background: #eef3fe; color: #1d4fc4; font-weight: 600; }
+.lbl { font-size: 11px; color: #666; padding: 6px 10px 2px; }
+.f { padding: 0 10px; }
+.field-error { color: #c22b2e; font-size: 11px; padding: 3px 10px 0; }
+.hint { padding: 6px 10px 0; color: #666; font-size: 11px; line-height: 1.35; }
+.hint code { font-size: 10.5px; }
+
+.radio { padding: 6px 10px; display: flex; gap: 7px; align-items: center; }
+.radio input[type=radio] { accent-color: #2f6fed; margin: 0; }
+.sub { color: #777; font-size: 11px; padding: 0 10px 2px 30px; margin-top: -4px; }
+.num { width: 52px; border: 1px solid #cfd3d8; border-radius: 4px; padding: 3px 5px; }
+
+.outline { position: fixed; z-index: 1; pointer-events: none; outline: 2px solid #2f6fed; outline-offset: 2px; border-radius: 4px; background: rgba(47,111,237,.06); }
+.toast { position: fixed; z-index: 4; left: 50%; bottom: 14px; transform: translateX(-50%); background: #17181c; color: #e9eaee; border-radius: 8px; padding: 6px 12px; box-shadow: 0 6px 20px rgba(0,0,0,.28); pointer-events: none; transition: opacity .3s; }
+.toast.gone { opacity: 0; }
+.frame { position: fixed; inset: 0; pointer-events: none; visibility: hidden; }
+`;

package/dist/runner/reporter.d.ts

@@ -36,8 +36,12 @@ export default class TestReporter {
     onStart(total?: number): void;
     onEnd(): Promise<TestSummary>;
     onTestStart(test: RegisteredTestCase): void;
-    onTestEnd(test: RegisteredTestCase, error?: TestError, logs?: {
+    onTestEnd(test: RegisteredTestCase, error?: TestError, extras?: {
         logs?: TestLogEntry[];
         logsDropped?: number;
+        screenshots?: {
+            name: string;
+            path: string;
+        }[];
     }): void;
 }

package/dist/runner/reporter.js

@@ -65,7 +65,7 @@ export default class TestReporter {
         });
         this.emit({ type: "test-start", name: test.name, file: test.file });
     }
-    onTestEnd(test, error, logs) {
+    onTestEnd(test, error, extras) {
         const key = keyOf(test);
         performance.mark(`${key}-finish`);
         const duration = performance.measure("test-duration", `${key}-start`, `${key}-finish`).duration;
@@ -74,8 +74,9 @@ export default class TestReporter {
             duration,
             status: error ? "failed" : "success",
             ...(error ? error : undefined),
-            ...(logs?.logs && { logs: logs.logs }),
-            ...(logs?.logsDropped && { logsDropped: logs.logsDropped }),
+            ...(extras?.logs && { logs: extras.logs }),
+            ...(extras?.logsDropped && { logsDropped: extras.logsDropped }),
+            ...(extras?.screenshots?.length && { screenshots: extras.screenshots }),
         });
         this.testResults.set(key, result);
         this.emit({ type: "test-end", name: test.name, file: test.file, result });

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

@@ -31,6 +31,8 @@ export default class TestRunner {
     private run;
     private group?;
     private options;
+    /** The real `srcDir` of this run, set by `start`; test screenshots are saved under paths relative to it */
+    private srcDir;
     constructor(testFiles: string[], run: PreparedRun, group?: SamuraiGroup, options?: RunnerOptions);
     static init(run: PreparedRun, group?: SamuraiGroup, options?: RunnerOptions): Promise<TestRunner>;
     /**
@@ -51,4 +53,11 @@ export default class TestRunner {
     start(): Promise<import("../types/test.js").TestSummary>;
     private executeTestCase;
 }
+/**
+ * The folder of a test's screenshots below `screenshots/`: its spec file without extension, then its cleaned
+ * name. A spec outside srcDir loses the `..` (and a drive or root) its relative path starts with, so it stays
+ * below `screenshots/`.
+ * @internal Exported for tests
+ */
+export declare function testDirOf(test: RegisteredTestCase, srcDir: string): string;
 export { describe, test } from "./registry.js";

package/dist/runner/test-runner.js

@@ -3,6 +3,7 @@ import { glob } from "node:fs/promises";
 import path from "path";
 import { pathToFileURL } from "url";
 import { Browser } from "../browser/browser.js";
+import { ensureWarm } from "../browser/warm-up.js";
 import { loadConfig, projectDir, readConfig } from "../config/config.js";
 import logger from "../logger/index.js";
 import { assertModuleProject } from "./module-type.js";
@@ -11,6 +12,7 @@ import { createEnvFixture } from "../config/variables.js";
 import { createSecretsFixture } from "../config/secrets.js";
 import TestReporter, {} from "./reporter.js";
 import Page from "../browser/page.js";
+import { cleanName, Evidence } from "../browser/evidence.js";
 import { takePendingAssertions } from "../assert/expect.js";
 import { toTestError } from "./test-error.js";
 import { ConnectionClosedError } from "../transport/bidi-connection.js";
@@ -29,6 +31,8 @@ export function isSelected(name, { grep, testNames }) {
 }
 export default class TestRunner {
     constructor(testFiles, run, group, options = {}) {
+        /** The real `srcDir` of this run, set by `start`; test screenshots are saved under paths relative to it */
+        this.srcDir = "";
         this.testFiles = testFiles;
         this.run = run;
         this.group = group;
@@ -81,9 +85,7 @@ export default class TestRunner {
     /** The config's groups, resolved against the tests the specs register */
     async resolveAll(tests) {
         const config = await loadConfig();
-        // Real paths: registered test files come from stack traces, which resolve symlinks
-        const dir = realPath(projectDir());
-        const srcDir = realPath(path.resolve(dir, config.srcDir ?? DEFAULT_SRC_DIR));
+        const { dir, srcDir } = realDirs(config.srcDir);
         const groups = resolveGroups(config, tests.map(({ file, name }) => ({
             file: toPosix(path.relative(srcDir, file)),
             name,
@@ -115,6 +117,11 @@ export default class TestRunner {
             ...(onEvent && { onEvent }),
         });
         const selected = await this.register();
+        this.srcDir = realDirs((await loadConfig()).srcDir).srcDir;
+        // A missing browser is one clear error before the run, not a failure per test; a fresh build's slow
+        // first start happens here, outside any test's timeout
+        if (selected.length > 0)
+            await ensureWarm((await readConfig("browser")) ?? "firefox", { port: this.options.port ?? 9223 }, signal);
         reporter.onStart(selected.length);
         for (const test of selected) {
             if (signal?.aborted) {
@@ -131,11 +138,15 @@ export default class TestRunner {
         reporter.onTestStart(test);
         // A test ends once, whichever of finishing, failing, timing out, an abort or a closed browser comes first
         let ended = false;
+        let evidence;
         const finish = (error, logs) => {
             if (ended)
                 return;
             ended = true;
-            reporter.onTestEnd(test, error, logs);
+            reporter.onTestEnd(test, error, {
+                ...logs,
+                screenshots: evidence?.screenshots,
+            });
         };
         let browserClosed = false;
         /** Set once the runner itself closes the browser */
@@ -143,6 +154,10 @@ export default class TestRunner {
         const selectedBrowser = (await readConfig("browser")) ?? "firefox";
         const { settings, secrets } = this.run;
         const timeout = settings.timeout;
+        const { reportPath } = this.options;
+        const resultDir = typeof reportPath === "string"
+            ? path.dirname(reportPath)
+            : path.join(projectDir(), "result");
         let browser;
         let page;
         let timeoutTimer;
@@ -190,6 +205,8 @@ export default class TestRunner {
                         resolve();
                     });
                     page = launched.page;
+                    evidence = new Evidence(resultDir, testDirOf(test, this.srcDir));
+                    launched.page.setEvidence(evidence);
                     const fixtures = {
                         page: launched.page,
                         browser: launched.browser,
@@ -236,6 +253,29 @@ export default class TestRunner {
         await browser?.close();
     }
 }
+/** The project and source folders as real paths: registered test files come from stack traces, which resolve symlinks */
+function realDirs(configuredSrcDir) {
+    const dir = realPath(projectDir());
+    const srcDir = realPath(path.resolve(dir, configuredSrcDir ?? DEFAULT_SRC_DIR));
+    return { dir, srcDir };
+}
+/**
+ * The folder of a test's screenshots below `screenshots/`: its spec file without extension, then its cleaned
+ * name. A spec outside srcDir loses the `..` (and a drive or root) its relative path starts with, so it stays
+ * below `screenshots/`.
+ * @internal Exported for tests
+ */
+export function testDirOf(test, srcDir) {
+    const file = toPosix(path.relative(srcDir, test.file))
+        .replace(/\.[cm]?[jt]sx?$/, "")
+        .split("/")
+        .filter((segment) => segment !== "" &&
+        segment !== "." &&
+        segment !== ".." &&
+        !/^[A-Za-z]:$/.test(segment))
+        .join("/");
+    return `${file}/${cleanName(test.name)}`;
+}
 /** Reads the page's log once the test body is done and applies config `logs` (see judgePageLogs) */
 async function judgeLogs(page, testFailed) {
     if (!page)

package/dist/steps/emit.js

@@ -69,6 +69,10 @@ export function stepToSource(step) {
             return `await expect(${locatorToSource(step.locator)})${step.not ? ".not" : ""}.${expectationToSource(step.expectation)};`;
         case "waitForNetworkIdle":
             return "await page.waitForNetworkIdle();";
+        case "waitForTimeout":
+            return `await page.waitForTimeout(${step.ms});`;
+        case "screenshot":
+            return `await page.screenshot({ name: ${str(step.name)}${step.fullPage ? ", fullPage: true" : ""} });`;
         case "custom":
             return step.code;
     }

package/dist/steps/model.d.ts

@@ -84,6 +84,17 @@ export type Step = {
 } | {
     kind: "waitForNetworkIdle";
 }
+/** A fixed pause, in milliseconds */
+ | {
+    kind: "waitForTimeout";
+    ms: number;
+}
+/** Saves the page as evidence under the run's results; never compares */
+ | {
+    kind: "screenshot";
+    name: string;
+    fullPage: boolean;
+}
 /** A statement the codec does not understand, kept verbatim */
  | {
     kind: "custom";

package/dist/steps/parse.js

@@ -190,9 +190,28 @@ function readStep(statement) {
             const url = stringOf(args[0]);
             return url === undefined ? undefined : { kind: "goto", url };
         }
-        return name.text === "waitForNetworkIdle" && args.length === 0
-            ? { kind: "waitForNetworkIdle" }
-            : undefined;
+        if (name.text === "waitForNetworkIdle" && args.length === 0)
+            return { kind: "waitForNetworkIdle" };
+        if (name.text === "waitForTimeout" &&
+            args.length === 1 &&
+            ts.isNumericLiteral(args[0])) {
+            const ms = Number(args[0].text);
+            return Number.isInteger(ms) ? { kind: "waitForTimeout", ms } : undefined;
+        }
+        if (name.text === "screenshot" && args.length === 1) {
+            const options = readObject(args[0], ["name", "fullPage"]);
+            if (!options || typeof options.name !== "string")
+                return undefined;
+            if (options.fullPage !== undefined &&
+                typeof options.fullPage !== "boolean")
+                return undefined;
+            return {
+                kind: "screenshot",
+                name: options.name,
+                fullPage: options.fullPage === true,
+            };
+        }
+        return undefined;
     }
     // expect(locator).matcher(…) and expect(locator).not.matcher(…)
     const negated = ts.isPropertyAccessExpression(target) && target.name.text === "not";

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

@@ -1,5 +1,7 @@
 import type { BiDiCommands, BiDiEvents } from "../types/bidi.js";
 import { type EventName, type Subscription, type SubscribeOptions } from "./subscriptions.js";
+/** Time (ms) a command may wait for its reply before it fails with code "timeout" */
+export declare const DEFAULT_COMMAND_TIMEOUT = 30000;
 export interface ConnectorOptions {
     /** @default 30000 */
     commandTimeout?: number;

package/dist/transport/bidi-connection.js

@@ -4,7 +4,7 @@ import { WaitTimeoutError } from "../wait/wait-until.js";
 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;
+export 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.
@@ -34,7 +34,7 @@ export class BiDiConnector {
         };
         this.messageListener = (ev) => {
             const message = JSON.parse(ev.data);
-            logger.debug("Received message from BiDi Websocket: ", message);
+            logger.debug("Received message from BiDi Websocket: ", forLog(message));
             if (message.type === "success" && message.id !== undefined) {
                 const targetToResolve = this.resolveMap.get(message.id);
                 if (targetToResolve) {
@@ -196,6 +196,37 @@ export class BiDiConnector {
         this.webSocket.close();
     }
 }
+/** Channels whose messages carry what the tester typed (the recorder's) or adds as a secret (its toolbar's) */
+const PRIVATE_CHANNEL = /^samurai-(recorder|toolbar)-/;
+/**
+ * The message as the debug log gets it: a `script.message` on a private channel is logged by channel and
+ * action only, so a value the tester types or a secret added from the recorder toolbar never reaches the log
+ * (an added secret is only registered for masking after it is saved).
+ */
+function forLog(message) {
+    const channel = message.params?.channel;
+    if (message.type !== "event" ||
+        message.method !== "script.message" ||
+        typeof channel !== "string" ||
+        !PRIVATE_CHANNEL.test(channel))
+        return message;
+    const entries = message.params?.data
+        ?.value;
+    const field = (key) => {
+        if (!Array.isArray(entries))
+            return undefined;
+        const entry = entries.find((pair) => Array.isArray(pair) && pair[0] === key);
+        const value = entry?.[1]?.value;
+        return typeof value === "string" ? value : undefined;
+    };
+    return {
+        ...message,
+        params: {
+            ...message.params,
+            data: { type: field("type"), action: field("action"), redacted: true },
+        },
+    };
+}
 function pendingSuffix(pending) {
     return pending.length > 0 ? ` (pending: ${pending.join(", ")})` : "";
 }

package/dist/types/bidi-modules/script.d.ts

@@ -35,6 +35,14 @@ export interface ScriptCommands {
     params: { handles: Handle[]; target: Target };
     result: DisownResult;
   };
+  /** Lists the realms that match, e.g. every window realm (sandboxes included) of a context. */
+  "script.getRealms": {
+    params: {
+      context?: BrowsingContext | undefined;
+      type?: RealmInfo["type"] | undefined;
+    };
+    result: GetRealmsResult;
+  };
   /** Registers a function to run before any page script in every matching new document. */
   "script.addPreloadScript": {
     params: {
@@ -54,13 +62,22 @@ export interface ScriptCommands {
 }
 
 /** A serialized value sent to the browser as a function argument or `this`. */
-export type LocalValue = { type: string; value?: unknown; [key: string]: unknown };
+export type LocalValue = {
+  type: string;
+  value?: unknown;
+  [key: string]: unknown;
+};
 /** A reference to a node or object that already lives in the browser. */
-export type RemoteReference = { sharedId: string; handle?: string | undefined } | { handle: string };
+export type RemoteReference =
+  { sharedId: string; handle?: string | undefined } | { handle: string };
 /** A channel the browser can use to send messages back through `script.message`. */
 export interface ChannelValue {
   type: "channel";
-  value: { channel: Channel; serializationOptions?: SerializationOptions; ownership?: ResultOwnership };
+  value: {
+    channel: Channel;
+    serializationOptions?: SerializationOptions;
+    ownership?: ResultOwnership;
+  };
 }
 export type ArgumentValue = LocalValue | RemoteReference | ChannelValue;
 

package/dist/types/config.d.ts

@@ -49,6 +49,11 @@ export interface SamuraiTestConfig {
    * Is overwritten by the 'browser' in a group's config
    */
   browser?: SupportedBrowser;
+  /**
+   * Browser binaries to launch instead of the builds SAMURAI downloads, relative to the project.
+   * `SAMURAI_FIREFOX_PATH` / `SAMURAI_CHROME_PATH` win over these.
+   */
+  browserPaths?: { firefox?: string; chrome?: string };
   /**
    * The timeout (in ms) to use for all tests
    * @default 30000

package/dist/types/test.d.ts

@@ -39,6 +39,8 @@ interface TestResultSuccess extends TestResultIdentity {
   logs?: TestLogEntry[];
   /** Entries that fell out of the page's log buffer */
   logsDropped?: number;
+  /** Named screenshots the test saved, relative to the result folder */
+  screenshots?: { name: string; path: string }[];
 }
 
 /** The error sits flat on the entry, as in the report: `message`, `type`, `stack`, and for assertions `expected` and `actual` */
@@ -47,6 +49,8 @@ interface TestResultFailed extends TestResultIdentity, TestError {
   duration: number;
   logs?: TestLogEntry[];
   logsDropped?: number;
+  /** Named screenshots the test saved, relative to the result folder */
+  screenshots?: { name: string; path: string }[];
 }
 
 /** One line of the browser's log, as stored in the report */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {
@@ -24,6 +24,10 @@
       "types": "./dist/cli/init.d.ts",
       "default": "./dist/cli/init.js"
     },
+    "./browsers": {
+      "types": "./dist/browsers/index.d.ts",
+      "default": "./dist/browsers/index.js"
+    },
     "./browser": {
       "types": "./dist/browser/index.d.ts",
       "default": "./dist/browser/index.js"
@@ -40,6 +44,10 @@
       "types": "./dist/flows/steps/index.d.ts",
       "default": "./dist/flows/steps/index.js"
     },
+    "./project": {
+      "types": "./dist/project/index.d.ts",
+      "default": "./dist/project/index.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -65,6 +73,7 @@
     "tsx": "^4.21.0"
   },
   "dependencies": {
+    "@puppeteer/browsers": "^3.2.4",
     "typescript": "^6.0.2",
     "winston": "^3.19.0"
   },