@itmetsam/samurai-framework 0.8.0 → 0.9.0

package/dist/network/network-tracker.js

@@ -1,6 +1,8 @@
 import EventEmitter from "node:events";
 import logger from "../logger/index.js";
 import { WaitTimeoutError } from "../wait/wait-until.js";
+/** The error text of a request that the page left before it finished, when the browser says none */
+const ABORTED_BY_NAVIGATION = "aborted by navigation";
 /** How many URLs a timeout message names */
 const URLS_IN_MESSAGE = 5;
 /** waitForIdle ran out of time with requests still in flight; `last` holds (up to five of) their URLs */
@@ -24,6 +26,8 @@ export class NetworkTracker {
         this.connector = connector;
         this.events = new EventEmitter();
         this.active = new Map();
+        /** The context each request in flight belongs to, by the same key */
+        this.contexts = new Map();
         /** Requests that may still be the source of a redirect, by hop key */
         this.hops = new Map();
         this.waiters = new Set();
@@ -41,6 +45,8 @@ export class NetworkTracker {
                 return;
             this.hops.set(key, request);
             this.active.set(key, request.url);
+            if (params.context)
+                this.contexts.set(key, params.context);
             this.emit("request", request);
             this.events.emit("change");
         };
@@ -51,6 +57,7 @@ export class NetworkTracker {
             const request = this.hops.get(key);
             if (!this.active.delete(key) || !request)
                 return;
+            this.contexts.delete(key);
             const { response } = params;
             // A redirect response keeps its request around: the next hop links back to it
             if (response.status < 300 || response.status >= 400)
@@ -72,10 +79,34 @@ export class NetworkTracker {
             const request = this.hops.get(key);
             if (!this.active.delete(key) || !request)
                 return;
+            this.contexts.delete(key);
             this.hops.delete(key);
             this.emit("requestfailed", Object.assign(request, { errorText: params.errorText }));
             this.events.emit("change");
         };
+        /**
+         * A document replaced another: the requests of the old one that are still in flight are over. Firefox reports each
+         * as failed (NS_BINDING_ABORTED); Chrome says nothing, which would keep the page "busy" for good.
+         */
+        this.onNavigationCommitted = (params) => {
+            if (!this.owns(params.context))
+                return;
+            let changed = false;
+            for (const [key, requestContext] of [...this.contexts]) {
+                const request = this.hops.get(key);
+                if (!request || request.navigation === params.navigation)
+                    continue;
+                if (!this.tree.isWithin(requestContext, params.context))
+                    continue;
+                this.contexts.delete(key);
+                this.active.delete(key);
+                this.hops.delete(key);
+                this.emit("requestfailed", Object.assign(request, { errorText: ABORTED_BY_NAVIGATION }));
+                changed = true;
+            }
+            if (changed)
+                this.events.emit("change");
+        };
     }
     static async start(connector, tree, contextId, options = {}) {
         const tracker = new NetworkTracker(tree, contextId, options.ignore ?? (() => false), connector);
@@ -83,11 +114,13 @@ export class NetworkTracker {
         connector.onEvent("network.beforeRequestSent", tracker.onBeforeRequestSent);
         connector.onEvent("network.responseCompleted", tracker.onResponseCompleted);
         connector.onEvent("network.fetchError", tracker.onFetchError);
+        connector.onEvent("browsingContext.navigationCommitted", tracker.onNavigationCommitted);
         try {
             tracker.subscription = await connector.subscribe([
                 "network.beforeRequestSent",
                 "network.responseCompleted",
                 "network.fetchError",
+                "browsingContext.navigationCommitted",
             ]);
         }
         catch (err) {
@@ -118,10 +151,12 @@ export class NetworkTracker {
      * Resolves once no request has been in flight for `idleTime` ms. A quiet page resolves after `idleTime`.
      * Rejects with NetworkIdleTimeoutError after `timeout` ms, or with "page closed" when disposed.
      */
-    waitForIdle({ idleTime, timeout }) {
+    waitForIdle({ idleTime, timeout, }) {
         return new Promise((resolve, reject) => {
             let idleTimer;
-            const waiter = { reject: (reason) => finish(() => reject(reason)) };
+            const waiter = {
+                reject: (reason) => finish(() => reject(reason)),
+            };
             const finish = (settle) => {
                 clearTimeout(idleTimer);
                 clearTimeout(deadline);
@@ -147,6 +182,7 @@ export class NetworkTracker {
         this.disposed = true;
         this.removeListeners();
         this.active.clear();
+        this.contexts.clear();
         this.hops.clear();
         [...this.waiters].forEach((waiter) => waiter.reject(new Error("page closed")));
         await this.subscription?.unsubscribe();
@@ -155,6 +191,7 @@ export class NetworkTracker {
         this.connector.offEvent("network.beforeRequestSent", this.onBeforeRequestSent);
         this.connector.offEvent("network.responseCompleted", this.onResponseCompleted);
         this.connector.offEvent("network.fetchError", this.onFetchError);
+        this.connector.offEvent("browsingContext.navigationCommitted", this.onNavigationCommitted);
     }
     owns(context) {
         return context !== null && this.tree.isWithin(context, this.contextId);
@@ -190,7 +227,9 @@ export function toRequest(data, navigation, isBlocked, redirectedFrom) {
 export function toHeaders(headers) {
     const result = {};
     for (const { name, value } of headers) {
-        const text = value.type === "base64" ? Buffer.from(value.value, "base64").toString("utf8") : value.value;
+        const text = value.type === "base64"
+            ? Buffer.from(value.value, "base64").toString("utf8")
+            : value.value;
         const key = name.toLowerCase();
         result[key] = key in result ? `${result[key]}, ${text}` : text;
     }

package/dist/network/router.d.ts

@@ -35,6 +35,11 @@ interface RouteDeps {
     next: () => Promise<void>;
     /** Called once the route is answered, whichever way */
     settled: (route: Route) => void;
+    /**
+     * Whether a replaced body needs a `content-length` of its own. Firefox keeps the old one and cuts the new body
+     * off; Chrome sets the right one itself and hangs the request when it is given one.
+     */
+    sendsContentLength: boolean;
 }
 /**
  * A request the browser holds until it is answered. Answer it exactly once with `fulfill`, `continue`,

package/dist/network/router.js

@@ -2,13 +2,16 @@ import { STATUS_CODES } from "node:http";
 import logger from "../logger/index.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { toRequest } from "./network-tracker.js";
-import { isExactString, matchUrl, samePattern } from "./url-match.js";
+import { isExactString, matchUrl, samePattern, } from "./url-match.js";
 /** Time (ms) a handler may take to answer a request before the router lets it continue */
 const DEFAULT_ROUTE_TIMEOUT = 30000;
 /** How many handler errors the router keeps */
 const MAX_ERRORS = 100;
 function toHeaders(headers) {
-    return Object.entries(headers).map(([name, value]) => ({ name, value: { type: "string", value } }));
+    return Object.entries(headers).map(([name, value]) => ({
+        name,
+        value: { type: "string", value },
+    }));
 }
 function toBytes(data) {
     return typeof data === "string"
@@ -44,7 +47,8 @@ export class Route {
         const text = options.json !== undefined ? JSON.stringify(options.json) : undefined;
         const body = options.body ?? text;
         const headers = { ...options.headers };
-        const contentType = options.contentType ?? (text !== undefined ? "application/json" : undefined);
+        const contentType = options.contentType ??
+            (text !== undefined ? "application/json" : undefined);
         if (contentType && !hasHeader(headers, "content-type"))
             headers["content-type"] = contentType;
         if (!hasHeader(headers, "content-length")) {
@@ -67,14 +71,21 @@ export class Route {
         let headers = options.headers;
         if (options.postData !== undefined) {
             const withoutLength = Object.fromEntries(Object.entries(headers ?? this.info.headers).filter(([name]) => name.toLowerCase() !== "content-length"));
-            headers = { ...withoutLength, "content-length": String(Buffer.byteLength(options.postData)) };
+            headers = this.deps.sendsContentLength
+                ? {
+                    ...withoutLength,
+                    "content-length": String(Buffer.byteLength(options.postData)),
+                }
+                : withoutLength;
         }
         await this.answer("network.continueRequest", {
             request: this.info.id,
             ...(options.url !== undefined && { url: options.url }),
             ...(options.method !== undefined && { method: options.method }),
             ...(headers !== undefined && { headers: toHeaders(headers) }),
-            ...(options.postData !== undefined && { body: toBytes(options.postData) }),
+            ...(options.postData !== undefined && {
+                body: toBytes(options.postData),
+            }),
         });
     }
     /** Makes the request fail (the browser reports a network error to the page) */
@@ -146,7 +157,9 @@ export class Router {
             if (!(params.intercepts ?? []).some((id) => this.interceptIds.has(id)))
                 return;
             const info = toRequest(params.request, params.navigation, params.isBlocked, null);
-            const matching = this.routes.filter((entry) => matchUrl(entry.pattern, info.url)).reverse();
+            const matching = this.routes
+                .filter((entry) => matchUrl(entry.pattern, info.url))
+                .reverse();
             this.dispatch(info, matching, 0).catch((err) => logger.error("Handling the request to %s failed", info.url, { err }));
         };
         this.routeTimeout = options.routeTimeout ?? DEFAULT_ROUTE_TIMEOUT;
@@ -171,7 +184,8 @@ export class Router {
     }
     /** Removes the routes for `pattern` (only the one with `handler`, when given) */
     async unroute(pattern, handler) {
-        const removed = this.routes.filter((route) => samePattern(route.pattern, pattern) && (handler === undefined || route.handler === handler));
+        const removed = this.routes.filter((route) => samePattern(route.pattern, pattern) &&
+            (handler === undefined || route.handler === handler));
         await this.remove(removed);
     }
     async unrouteAll() {
@@ -189,7 +203,9 @@ export class Router {
             return;
         this.routes = this.routes.filter((route) => !removed.includes(route));
         // Requests a removed route still holds would wait for nobody
-        await Promise.all([...this.pending].filter((route) => removed.includes(route.entry)).map((route) => route.release()));
+        await Promise.all([...this.pending]
+            .filter((route) => removed.includes(route.entry))
+            .map((route) => route.release()));
         await this.enqueue(() => this.sync());
     }
     enqueue(work) {
@@ -209,7 +225,8 @@ export class Router {
         const id = await this.addIntercept(patterns);
         const previous = this.currentId;
         this.currentId = id;
-        this.currentKey = patterns && !patternsUnsupported.has(this.connector) ? key : "all";
+        this.currentKey =
+            patterns && !patternsUnsupported.has(this.connector) ? key : "all";
         this.interceptIds.add(id);
         // The new intercept is in place before the old one goes: nothing slips through in between
         if (previous !== undefined)
@@ -243,7 +260,9 @@ export class Router {
             return intercept;
         }
         catch (err) {
-            if (patterns && err instanceof BiDiError && err.code === "invalid argument") {
+            if (patterns &&
+                err instanceof BiDiError &&
+                err.code === "invalid argument") {
                 patternsUnsupported.add(this.connector);
                 return this.addIntercept(undefined);
             }
@@ -267,7 +286,9 @@ export class Router {
             return;
         this.connector.onEvent("network.beforeRequestSent", this.onBeforeRequestSent);
         try {
-            this.subscription = await this.connector.subscribe(["network.beforeRequestSent"]);
+            this.subscription = await this.connector.subscribe([
+                "network.beforeRequestSent",
+            ]);
         }
         catch (err) {
             this.connector.offEvent("network.beforeRequestSent", this.onBeforeRequestSent);
@@ -296,6 +317,7 @@ export class Router {
             settled: (settled) => {
                 this.pending.delete(settled);
             },
+            sendsContentLength: this.connector.browserName !== "chrome",
         };
         if (!entry) {
             // Nobody (left) to ask: an unmatched request, or every route fell back

package/dist/recorder/session.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { Browser } from "../browser/browser.js";
 import { ensureWarm } from "../browser/warm-up.js";
-import { loadConfig, projectDir } from "../config/config.js";
+import { loadConfig, projectDir, readConfig } from "../config/config.js";
 import { loadSecrets } from "../config/secrets.js";
 import { filesFolder, isFolderIgnored, isGitIgnored, } from "../project/index.js";
 import { withProject } from "../runner/project.js";
@@ -101,7 +101,8 @@ export async function recordSpec(options) {
             throw new Error(`${options.file} does not exist; give a title with --new to create it`);
         }
         // Before the spec is touched: a recording without its browser changes nothing
-        await ensureWarm("firefox", { port: options.port ?? 9223 }, options.signal);
+        const browserName = (await readConfig("browser")) ?? "firefox";
+        await ensureWarm(browserName, { port: options.port ?? 9223 }, options.signal);
         options.signal?.throwIfAborted();
         source ??= "";
         if (options.create !== undefined &&
@@ -117,7 +118,7 @@ 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", {
+        const { browser, page } = await Browser.launch(browserName, {
             port: options.port ?? 9223,
             headless: options.headless ?? settings.headless,
         }, options.signal);

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

@@ -46,11 +46,6 @@ export interface ControllerOptions {
 type Message = ToolbarMessage & {
     target?: ElementHandle;
 };
-/**
- * The recorder's side of the toolbar: owns its state (pause, the rail, the environment's variables and
- * secrets) and turns its messages into observations. Secret values stay here; the page only ever gets
- * their names and whether they are set.
- */
 export declare class ToolbarController {
     private readonly deps;
     private readonly options;
@@ -79,6 +74,8 @@ export declare class ToolbarController {
     private readonly done;
     /** Bumped on every page load: work started for an older page is not answered */
     private page;
+    /** Wake-ups for the work that is waiting on the current page: called, and forgotten, when the page changes */
+    private pageGone;
     private toolbar;
     /** A `ready` arrived since the last load: it counts for the next one */
     private readySinceLoad;
@@ -104,6 +101,10 @@ export declare class ToolbarController {
      * and doesn't count for the coming load
      */
     navigating(): void;
+    /** Lets what waits on the current document stop waiting: its commands may never be answered once it is gone */
+    private leavePage;
+    /** Runs `work`, but stops waiting for it when the page is left; resolves `gone` then */
+    private whileOnPage;
     /** A step was emitted (any source): count it */
     stepAdded(step: Step): void;
     /** A recorded step was taken out again (a cancelled file picker's click) */

package/dist/recorder/toolbar/controller.js

@@ -22,6 +22,8 @@ const fail = (error, field) => ({
  * secrets) and turns its messages into observations. Secret values stay here; the page only ever gets
  * their names and whether they are set.
  */
+/** What a wait on the page ends with when the page was left first */
+const LEFT = Symbol("left the page");
 export class ToolbarController {
     constructor(deps, options) {
         this.deps = deps;
@@ -41,6 +43,8 @@ export class ToolbarController {
         this.done = new Set();
         /** Bumped on every page load: work started for an older page is not answered */
         this.page = 0;
+        /** Wake-ups for the work that is waiting on the current page: called, and forgotten, when the page changes */
+        this.pageGone = new Set();
         this.toolbar = true;
         /** A `ready` arrived since the last load: it counts for the next one */
         this.readySinceLoad = false;
@@ -173,6 +177,7 @@ export class ToolbarController {
         if (this.disposed)
             return;
         this.page++;
+        this.leavePage();
         this.pick = undefined;
         this.toast = undefined;
         this.push();
@@ -197,6 +202,28 @@ export class ToolbarController {
      */
     navigating() {
         this.readySinceLoad = false;
+        this.leavePage();
+    }
+    /** Lets what waits on the current document stop waiting: its commands may never be answered once it is gone */
+    leavePage() {
+        const waiting = [...this.pageGone];
+        this.pageGone.clear();
+        for (const wake of waiting)
+            wake();
+    }
+    /** Runs `work`, but stops waiting for it when the page is left; resolves `gone` then */
+    async whileOnPage(work, gone) {
+        let wake;
+        const left = new Promise((resolve) => {
+            wake = () => resolve(gone);
+            this.pageGone.add(wake);
+        });
+        try {
+            return await Promise.race([work(), left]);
+        }
+        finally {
+            this.pageGone.delete(wake);
+        }
     }
     /** A step was emitted (any source): count it */
     stepAdded(step) {
@@ -310,19 +337,24 @@ export class ToolbarController {
             return this.reply(message.id, fail(PAUSED));
         let found;
         try {
-            const locator = message.target &&
-                (await this.deps.rank(message.target, message.candidates));
-            if (locator) {
-                found = await this.deps.inspect(message.target, locator, message.candidates);
+            // Chrome never answers a command into a document that is being replaced, so a pick of the old page must not
+            // keep the messages behind it waiting
+            found = await this.whileOnPage(async () => {
+                const locator = message.target &&
+                    (await this.deps.rank(message.target, message.candidates));
+                if (!locator)
+                    return undefined;
+                const inspected = await this.deps.inspect(message.target, locator, message.candidates);
                 if (page === this.page)
-                    this.pick = { id: message.id, locator, counts: found.counts };
-            }
+                    this.pick = { id: message.id, locator, counts: inspected.counts };
+                return inspected;
+            }, LEFT);
         }
         catch {
             found = undefined; // the element went away while it was inspected
         }
         // The page that asked is gone: its successor's toolbar isn't waiting for this
-        if (page !== this.page)
+        if (found === LEFT || page !== this.page)
             return;
         this.reply(message.id, found ? this.withoutSecrets(found.info) : fail(UNIDENTIFIABLE));
     }

package/dist/script/preload.js

@@ -16,11 +16,24 @@ export async function addPreload(connector, options) {
             arguments: options.arguments.map((arg) => toLocalValue(arg)),
         }),
     });
+    let stopRerun;
+    if (needsRerun(connector, options)) {
+        try {
+            stopRerun = await rerunInNewRealms(connector, options);
+        }
+        catch (err) {
+            await connector
+                .send("script.removePreloadScript", { script })
+                .catch(() => undefined);
+            throw err;
+        }
+    }
     let removed = false;
     const dispose = async () => {
         if (removed)
             return;
         removed = true;
+        await stopRerun?.();
         try {
             await connector.send("script.removePreloadScript", { script });
         }
@@ -42,6 +55,58 @@ export async function addPreload(connector, options) {
     }
     return { id: script, dispose };
 }
+/**
+ * Chrome drops the messages of a channel that a preload script in a sandbox was given, while a channel handed to a
+ * call into the same sandbox works. So there the script is also run, with its channels, in every new sandbox realm.
+ */
+function needsRerun(connector, options) {
+    return (connector.browserName === "chrome" &&
+        options.sandbox !== undefined &&
+        (options.arguments?.length ?? 0) > 0);
+}
+async function rerunInNewRealms(connector, options) {
+    const { contexts, sandbox, source } = options;
+    const inScope = async (context) => {
+        if (!contexts)
+            return true;
+        if (contexts.includes(context))
+            return true;
+        const trees = await Promise.all(contexts.map((root) => connector.send("browsingContext.getTree", { root })));
+        return trees.some((tree) => tree.contexts.flatMap(flatten).includes(context));
+    };
+    const onRealm = (realm) => {
+        if (realm.type !== "window" || realm.sandbox !== sandbox || !realm.context)
+            return;
+        const context = realm.context;
+        void (async () => {
+            try {
+                if (!(await inScope(context)))
+                    return;
+                await callFunction(connector, context, source, options.arguments ?? [], {
+                    awaitPromise: false,
+                    ...(sandbox !== undefined && { sandbox }),
+                });
+            }
+            catch (err) {
+                // The document went away again, or the script threw: the registration covers what it can
+                logger.debug("Could not run a preload script in a new realm", { err });
+            }
+        })();
+    };
+    connector.onEvent("script.realmCreated", onRealm);
+    let subscription;
+    try {
+        subscription = await connector.subscribe(["script.realmCreated"]);
+    }
+    catch (err) {
+        connector.offEvent("script.realmCreated", onRealm);
+        throw err;
+    }
+    return async () => {
+        connector.offEvent("script.realmCreated", onRealm);
+        await subscription.unsubscribe().catch(() => undefined);
+    };
+}
 /** Runs `source` once in every loaded context (iframes included) under `contexts` */
 export async function runInLoadedContexts(connector, { source, contexts, sandbox, onRunError = "throw", arguments: args = [], }) {
     const trees = contexts

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

@@ -25,12 +25,18 @@ export declare class BiDiConnector {
     private currentId;
     /** Set once the socket closed or failed: nothing sent after that gets an answer */
     private closed;
+    /** Which browser is on the other end, when the launcher says; code that must treat browsers apart asks this */
+    browserName?: "firefox" | "chrome";
     private webSocket;
     private eventEmitter;
     private commandTimeout;
     private subscriptions;
     constructor(ws: WebSocket, options?: ConnectorOptions);
     static connect(url: string, options?: ConnectorOptions): Promise<BiDiConnector>;
+    /** Calls `listener` once when the socket closes or fails (not when `kill()` ends it) */
+    onClosed(listener: () => void): void;
+    private closeListeners;
+    private notifyClosed;
     private onWebsocketClose;
     private onWebsocketError;
     private get isClosed();

package/dist/transport/bidi-connection.js

@@ -22,12 +22,15 @@ export class BiDiConnector {
         this.currentId = 0;
         /** Set once the socket closed or failed: nothing sent after that gets an answer */
         this.closed = false;
+        this.closeListeners = new Set();
         this.onWebsocketClose = () => {
             this.closed = true;
+            this.notifyClosed();
             this.rejectAll((pending) => new ConnectionClosedError(`Websocket closed${pendingSuffix(pending)}`));
         };
         this.onWebsocketError = (ev) => {
             this.closed = true;
+            this.notifyClosed();
             this.rejectAll((pending) => new ConnectionClosedError(`Websocket error${pendingSuffix(pending)}`, {
                 cause: ev,
             }));
@@ -84,6 +87,16 @@ export class BiDiConnector {
             });
         });
     }
+    /** Calls `listener` once when the socket closes or fails (not when `kill()` ends it) */
+    onClosed(listener) {
+        this.closeListeners.add(listener);
+    }
+    notifyClosed() {
+        const listeners = [...this.closeListeners];
+        this.closeListeners.clear();
+        for (const listener of listeners)
+            listener();
+    }
     get isClosed() {
         // A socket that is closing or closed (readyState 2 or 3) has already lost the browser
         const state = this.webSocket.readyState;

package/dist/types/browser.d.ts

@@ -1 +1 @@
-export type SupportedBrowser = "firefox";
+export type SupportedBrowser = "firefox" | "chrome";

package/dist/types/config.d.ts

@@ -45,7 +45,7 @@ export interface SamuraiTestConfig {
    */
   srcDir?: string;
   /**
-   * The browser to use for all tests. Only "firefox" can launch today
+   * The browser to use for all tests: "firefox" or "chrome"
    * @default "firefox"
    */
   browser?: SupportedBrowser;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.8.0",
+  "version": "0.9.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": {
@@ -54,7 +54,8 @@
     "dev": "tsx src/index.ts",
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/copy-types.mjs",
     "test": "tsx --test --test-timeout=10000 \"src/**/*.test.ts\"",
-    "test:browser": "tsx --test --test-concurrency=1 \"src/**/*.browser-test.ts\"",
+    "test:browser": "tsx --test --test-concurrency=1 --test-timeout=60000 \"src/**/*.browser-test.ts\"",
+    "test:browser:chrome": "SAMURAI_TEST_BROWSER=chrome npm run test:browser",
     "test:cli": "tsx --test --test-concurrency=1 \"src/**/*.cli-test.ts\""
   },
   "keywords": [