@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/network/router.d.ts

@@ -0,0 +1,120 @@
+import type { ContextTree } from "../browser/context-tree.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { type NetworkRequest } from "./network-tracker.js";
+import { type UrlPattern } from "./url-match.js";
+export type RouteHandler = (route: Route) => void | Promise<void>;
+export interface FulfillOptions {
+    /** @default 200 */
+    status?: number;
+    headers?: Record<string, string>;
+    /** Sets `content-type` unless `headers` has one; `json` implies "application/json" */
+    contentType?: string;
+    body?: string | Buffer;
+    /** Sent as JSON text; cannot be combined with `body` */
+    json?: unknown;
+}
+export interface ContinueOptions {
+    /**
+     * Sends the request to another URL. Firefox applies this to navigations only: the page's `fetch`, XHR and
+     * image requests fail when their URL is changed, so mock those with `fulfill` instead
+     */
+    url?: string;
+    method?: string;
+    /** Replaces all request headers */
+    headers?: Record<string, string>;
+    postData?: string | Buffer;
+}
+interface RouteEntry {
+    pattern: UrlPattern;
+    handler: RouteHandler;
+}
+/** Answers `network.*` commands for one blocked request */
+interface RouteDeps {
+    send: BiDiConnector["send"];
+    /** Passes the request to the next matching route, or lets it continue */
+    next: () => Promise<void>;
+    /** Called once the route is answered, whichever way */
+    settled: (route: Route) => void;
+}
+/**
+ * A request the browser holds until it is answered. Answer it exactly once with `fulfill`, `continue`,
+ * `abort` or `fallback`; a second call throws.
+ */
+export declare class Route {
+    private readonly info;
+    /** @internal */
+    readonly entry: RouteEntry;
+    private readonly deps;
+    private answered;
+    /** @internal */
+    timer: ReturnType<typeof setTimeout> | undefined;
+    constructor(info: NetworkRequest, 
+    /** @internal */
+    entry: RouteEntry, deps: RouteDeps);
+    request(): NetworkRequest;
+    /** @internal */
+    get isAnswered(): boolean;
+    /** Answers the request without sending it: status 200 and no body unless told otherwise */
+    fulfill(options?: FulfillOptions): Promise<void>;
+    /**
+     * Lets the request go on, optionally changed. `headers` replaces all request headers. A new `postData` brings its
+     * own `content-length` (the request's old one would cut the new body off or leave the server waiting).
+     */
+    continue(options?: ContinueOptions): Promise<void>;
+    /** Makes the request fail (the browser reports a network error to the page) */
+    abort(): Promise<void>;
+    /** Hands the request to the next route that matches it, or lets it continue when there is none */
+    fallback(): Promise<void>;
+    /** @internal Lets the request continue unchanged; failures are logged, not thrown */
+    release(): Promise<void>;
+    /** @internal Fails the request; failures are logged, not thrown */
+    failQuietly(): Promise<void>;
+    private claim;
+    private answer;
+}
+/**
+ * Lets a page mock, block and change requests. One `network.addIntercept` serves all routes; matching
+ * happens here. Every request the browser holds is answered exactly once, so nothing hangs.
+ */
+export declare class Router {
+    private connector;
+    private tree;
+    private contextId;
+    private routes;
+    private pending;
+    private failures;
+    private queue;
+    private interceptIds;
+    private currentKey;
+    private currentId;
+    private subscription;
+    private disposed;
+    private routeTimeout;
+    constructor(connector: BiDiConnector, tree: ContextTree, contextId: string, options?: {
+        routeTimeout?: number;
+    });
+    /** Errors thrown by route handlers, oldest first */
+    get errors(): readonly Error[];
+    /** Sends matching requests to `handler`. Later routes are asked first */
+    route(pattern: UrlPattern, handler: RouteHandler): Promise<void>;
+    /** Removes the routes for `pattern` (only the one with `handler`, when given) */
+    unroute(pattern: UrlPattern, handler?: RouteHandler): Promise<void>;
+    unrouteAll(): Promise<void>;
+    /** Lets held requests continue, removes the intercept and stops listening. Idempotent */
+    dispose(): Promise<void>;
+    private remove;
+    private enqueue;
+    /** Makes the browser-side intercept match the routes: none, one for everything, or one for exact URLs */
+    private sync;
+    /** The exact URLs to block, or undefined to block everything and match here */
+    private urlPatterns;
+    private addIntercept;
+    private removeIntercept;
+    private listen;
+    private stop;
+    private onBeforeRequestSent;
+    /** Runs the `index`-th matching route; past the last one the request continues unchanged */
+    private dispatch;
+    private record;
+}
+export {};

package/dist/network/router.js

@@ -0,0 +1,343 @@
+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";
+/** 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 } }));
+}
+function toBytes(data) {
+    return typeof data === "string"
+        ? { type: "string", value: data }
+        : { type: "base64", value: data.toString("base64") };
+}
+const hasHeader = (headers, name) => Object.keys(headers).some((key) => key.toLowerCase() === name);
+/**
+ * A request the browser holds until it is answered. Answer it exactly once with `fulfill`, `continue`,
+ * `abort` or `fallback`; a second call throws.
+ */
+export class Route {
+    constructor(info, 
+    /** @internal */
+    entry, deps) {
+        this.info = info;
+        this.entry = entry;
+        this.deps = deps;
+        this.answered = false;
+    }
+    request() {
+        return this.info;
+    }
+    /** @internal */
+    get isAnswered() {
+        return this.answered;
+    }
+    /** Answers the request without sending it: status 200 and no body unless told otherwise */
+    async fulfill(options = {}) {
+        if (options.json !== undefined && options.body !== undefined) {
+            throw new TypeError("route.fulfill(): use either json or body, not both");
+        }
+        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);
+        if (contentType && !hasHeader(headers, "content-type"))
+            headers["content-type"] = contentType;
+        if (!hasHeader(headers, "content-length")) {
+            headers["content-length"] = String(body === undefined ? 0 : Buffer.byteLength(body));
+        }
+        const status = options.status ?? 200;
+        await this.answer("network.provideResponse", {
+            request: this.info.id,
+            statusCode: status,
+            reasonPhrase: STATUS_CODES[status] ?? "",
+            headers: toHeaders(headers),
+            ...(body !== undefined && { body: toBytes(body) }),
+        });
+    }
+    /**
+     * Lets the request go on, optionally changed. `headers` replaces all request headers. A new `postData` brings its
+     * own `content-length` (the request's old one would cut the new body off or leave the server waiting).
+     */
+    async continue(options = {}) {
+        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)) };
+        }
+        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) }),
+        });
+    }
+    /** Makes the request fail (the browser reports a network error to the page) */
+    async abort() {
+        await this.answer("network.failRequest", { request: this.info.id });
+    }
+    /** Hands the request to the next route that matches it, or lets it continue when there is none */
+    async fallback() {
+        this.claim();
+        await this.deps.next();
+    }
+    /** @internal Lets the request continue unchanged; failures are logged, not thrown */
+    async release() {
+        if (this.answered)
+            return;
+        try {
+            await this.continue();
+        }
+        catch (err) {
+            logger.debug("Could not let %s continue", this.info.url, { err });
+        }
+    }
+    /** @internal Fails the request; failures are logged, not thrown */
+    async failQuietly() {
+        if (this.answered)
+            return;
+        try {
+            await this.abort();
+        }
+        catch (err) {
+            logger.debug("Could not fail %s", this.info.url, { err });
+        }
+    }
+    claim() {
+        if (this.answered)
+            throw new Error("route already handled");
+        this.answered = true;
+        clearTimeout(this.timer);
+        this.deps.settled(this);
+    }
+    async answer(method, params) {
+        this.claim();
+        await this.deps.send(method, params);
+    }
+}
+/** Whether a browser accepts `urlPatterns` in `network.addIntercept`; asked once per connection */
+const patternsUnsupported = new WeakSet();
+/**
+ * Lets a page mock, block and change requests. One `network.addIntercept` serves all routes; matching
+ * happens here. Every request the browser holds is answered exactly once, so nothing hangs.
+ */
+export class Router {
+    constructor(connector, tree, contextId, options = {}) {
+        this.connector = connector;
+        this.tree = tree;
+        this.contextId = contextId;
+        this.routes = [];
+        this.pending = new Set();
+        this.failures = [];
+        this.queue = Promise.resolve();
+        this.interceptIds = new Set();
+        this.disposed = false;
+        this.onBeforeRequestSent = (params) => {
+            if (!params.isBlocked || params.context === null)
+                return;
+            if (!this.tree.isWithin(params.context, this.contextId))
+                return;
+            // Held by an intercept of ours, not someone else's
+            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();
+            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;
+    }
+    /** Errors thrown by route handlers, oldest first */
+    get errors() {
+        return [...this.failures];
+    }
+    /** Sends matching requests to `handler`. Later routes are asked first */
+    async route(pattern, handler) {
+        if (this.disposed)
+            throw new Error("router disposed");
+        const entry = { pattern, handler };
+        this.routes.push(entry);
+        try {
+            await this.enqueue(() => this.sync());
+        }
+        catch (err) {
+            this.routes = this.routes.filter((route) => route !== entry);
+            throw err;
+        }
+    }
+    /** 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));
+        await this.remove(removed);
+    }
+    async unrouteAll() {
+        await this.remove([...this.routes]);
+    }
+    /** Lets held requests continue, removes the intercept and stops listening. Idempotent */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        await this.remove([...this.routes]);
+    }
+    async remove(removed) {
+        if (removed.length === 0)
+            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 this.enqueue(() => this.sync());
+    }
+    enqueue(work) {
+        const run = this.queue.then(work);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    /** Makes the browser-side intercept match the routes: none, one for everything, or one for exact URLs */
+    async sync() {
+        if (this.routes.length === 0)
+            return this.stop();
+        await this.listen();
+        const patterns = this.urlPatterns();
+        const key = patterns ? JSON.stringify(patterns) : "all";
+        if (key === this.currentKey)
+            return;
+        const id = await this.addIntercept(patterns);
+        const previous = this.currentId;
+        this.currentId = id;
+        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)
+            await this.removeIntercept(previous);
+    }
+    /** The exact URLs to block, or undefined to block everything and match here */
+    urlPatterns() {
+        if (patternsUnsupported.has(this.connector))
+            return undefined;
+        const patterns = [];
+        for (const { pattern } of this.routes) {
+            // The browser reads a URL string in normal form; anything else could mean something else to it
+            if (!isExactString(pattern) || !isNormalUrl(pattern))
+                return undefined;
+            if (!patterns.some((existing) => existing.type === "string" && existing.pattern === pattern)) {
+                patterns.push({ type: "string", pattern });
+            }
+        }
+        return patterns;
+    }
+    async addIntercept(patterns) {
+        const params = {
+            phases: ["beforeRequestSent"],
+            contexts: [this.contextId],
+        };
+        try {
+            const { intercept } = await this.connector.send("network.addIntercept", {
+                ...params,
+                ...(patterns && { urlPatterns: patterns }),
+            });
+            return intercept;
+        }
+        catch (err) {
+            if (patterns && err instanceof BiDiError && err.code === "invalid argument") {
+                patternsUnsupported.add(this.connector);
+                return this.addIntercept(undefined);
+            }
+            throw err;
+        }
+    }
+    async removeIntercept(id) {
+        try {
+            await this.connector.send("network.removeIntercept", { intercept: id });
+        }
+        catch (err) {
+            if (!(err instanceof BiDiError && err.code === "no such intercept"))
+                throw err;
+        }
+        finally {
+            this.interceptIds.delete(id);
+        }
+    }
+    async listen() {
+        if (this.subscription)
+            return;
+        this.connector.onEvent("network.beforeRequestSent", this.onBeforeRequestSent);
+        try {
+            this.subscription = await this.connector.subscribe(["network.beforeRequestSent"]);
+        }
+        catch (err) {
+            this.connector.offEvent("network.beforeRequestSent", this.onBeforeRequestSent);
+            throw err;
+        }
+    }
+    async stop() {
+        const id = this.currentId;
+        this.currentId = undefined;
+        this.currentKey = undefined;
+        if (id !== undefined)
+            await this.removeIntercept(id);
+        if (this.subscription) {
+            this.connector.offEvent("network.beforeRequestSent", this.onBeforeRequestSent);
+            const subscription = this.subscription;
+            this.subscription = undefined;
+            await subscription.unsubscribe();
+        }
+    }
+    /** Runs the `index`-th matching route; past the last one the request continues unchanged */
+    async dispatch(info, matching, index) {
+        const entry = matching[index];
+        const deps = {
+            send: (method, params) => this.connector.send(method, params),
+            next: () => this.dispatch(info, matching, index + 1),
+            settled: (settled) => {
+                this.pending.delete(settled);
+            },
+        };
+        if (!entry) {
+            // Nobody (left) to ask: an unmatched request, or every route fell back
+            await new Route(info, { pattern: "", handler: () => { } }, deps).release();
+            return;
+        }
+        const route = new Route(info, entry, deps);
+        this.pending.add(route);
+        route.timer = setTimeout(() => {
+            if (route.isAnswered)
+                return;
+            logger.error("A route for %s did not answer within %dms; letting the request continue", info.url, this.routeTimeout);
+            void route.release();
+        }, this.routeTimeout);
+        route.timer.unref?.();
+        try {
+            await entry.handler(route);
+        }
+        catch (err) {
+            this.record(info, err);
+            await route.failQuietly();
+            return;
+        }
+        if (!route.isAnswered) {
+            logger.warn("The route for %s did not answer the request; letting it continue", info.url);
+            await route.release();
+        }
+    }
+    record(info, err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const error = Object.assign(new Error(`route handler for ${info.url} threw: ${message}`), { cause: err });
+        this.failures.push(error);
+        if (this.failures.length > MAX_ERRORS)
+            this.failures.shift();
+        logger.error("A route handler threw for %s", info.url, { err });
+    }
+}
+function isNormalUrl(value) {
+    try {
+        return new URL(value).href === value;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/network/url-match.d.ts

@@ -0,0 +1,8 @@
+/** A URL to match: an exact string, a glob (`*` = anything but `/`, `**` = anything) or a RegExp */
+export type UrlPattern = string | RegExp;
+/** True for a string without `*`: it must equal the URL */
+export declare function isExactString(pattern: UrlPattern): pattern is string;
+/** Whether `url` matches `pattern` */
+export declare function matchUrl(pattern: UrlPattern, url: string): boolean;
+/** Same pattern, so `unroute` finds the route a `route` call made */
+export declare function samePattern(a: UrlPattern, b: UrlPattern): boolean;

package/dist/network/url-match.js

@@ -0,0 +1,38 @@
+/** True for a string without `*`: it must equal the URL */
+export function isExactString(pattern) {
+    return typeof pattern === "string" && !pattern.includes("*");
+}
+function globToRegExp(glob) {
+    let source = "";
+    for (let i = 0; i < glob.length; i++) {
+        const char = glob[i];
+        if (char === "*") {
+            if (glob[i + 1] === "*") {
+                source += ".*";
+                i++;
+            }
+            else {
+                source += "[^/]*";
+            }
+        }
+        else {
+            source += char.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(`^${source}$`);
+}
+/** Whether `url` matches `pattern` */
+export function matchUrl(pattern, url) {
+    if (typeof pattern === "string") {
+        return isExactString(pattern) ? pattern === url : globToRegExp(pattern).test(url);
+    }
+    // A global or sticky RegExp remembers where it stopped; every match must start fresh
+    pattern.lastIndex = 0;
+    return pattern.test(url);
+}
+/** Same pattern, so `unroute` finds the route a `route` call made */
+export function samePattern(a, b) {
+    if (typeof a === "string" || typeof b === "string")
+        return a === b;
+    return a.source === b.source && a.flags === b.flags;
+}

package/dist/recorder/apply.d.ts

@@ -0,0 +1,3 @@
+import type { RecorderEvent } from "./normalise.js";
+/** Writes a recorder event into the spec source, as an edit of test number `test` */
+export declare function applyRecorderEvent(source: string, test: number, event: RecorderEvent): string;

package/dist/recorder/apply.js

@@ -0,0 +1,10 @@
+import { applyEdit } from "../steps/edit.js";
+/** Writes a recorder event into the spec source, as an edit of test number `test` */
+export function applyRecorderEvent(source, test, event) {
+    return applyEdit(source, {
+        op: event.op,
+        test,
+        index: event.index,
+        step: event.step,
+    });
+}

package/dist/recorder/capture.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Function declaration installed as a preload script, called as `(send)` where `send` is the recorder's
+ * channel. Reports what the tester does in the top-level document:
+ *
+ * - `{ type: "click", target, candidates, textEntry }`: a click, retargeted to the nearest interactive
+ *   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: "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.
+ *
+ * `candidates` are locator calls for the element, most stable first (test id, role and name, label,
+ * text, css, and an absolute xpath that always exists). The recorder checks each one against the page.
+ * Runs in the page's own realm; a string, so no transpiler helper can end up in it.
+ */
+export declare const CAPTURE_SOURCE: string;
+/** Run in every loaded document to stop its capture script reporting and swallowing Alt+clicks */
+export declare const CAPTURE_OFF = "() => { window[Symbol.for(\"samurai.recorder.off\")] = true; }";