@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/browser/page-logs.js

@@ -0,0 +1,149 @@
+import EventEmitter from "node:events";
+import logger from "../logger/index.js";
+import { fromRemoteValue } from "../script/serialize.js";
+/** How many entries a page keeps before the oldest are dropped */
+const DEFAULT_MAX_ENTRIES = 1000;
+/** A call to `console.log`, `console.warn`, … in the page */
+export class ConsoleMessage {
+    constructor(
+    /** "debug" | "info" | "warn" | "error" */
+    level, method, message, 
+    /** The arguments as plain values; DOM nodes and functions stay opaque (ElementHandle, RemoteObject) */
+    args, timestamp, stackTrace) {
+        this.level = level;
+        this.method = method;
+        this.message = message;
+        this.args = args;
+        this.timestamp = timestamp;
+        this.stackTrace = stackTrace;
+    }
+    /** The console method: "log", "warn", "error", "info", "debug", … */
+    type() {
+        return this.method;
+    }
+    /** What the browser prints for the call */
+    text() {
+        return this.message;
+    }
+    /** Where the call was made, when the browser says */
+    location() {
+        const frame = this.stackTrace?.callFrames[0];
+        return frame && { url: frame.url, lineNumber: frame.lineNumber, columnNumber: frame.columnNumber };
+    }
+}
+/** An exception nobody caught in the page */
+export class PageError extends Error {
+    constructor(text, timestamp, stackTrace) {
+        super(text);
+        this.name = "PageError";
+        this.timestamp = timestamp;
+        this.stack = [text, ...(stackTrace?.callFrames ?? []).map(formatFrame)].join("\n");
+    }
+}
+function formatFrame({ functionName, url, lineNumber, columnNumber }) {
+    const where = `${url}:${lineNumber}:${columnNumber}`;
+    return functionName ? `    at ${functionName} (${where})` : `    at ${where}`;
+}
+/**
+ * Collects the browser's log (`console.*` calls and uncaught exceptions) of one page, frames included,
+ * in a ring buffer, and emits `console` and `pageerror` events.
+ */
+export class PageLogs {
+    constructor(connector, tree, contextId, maxEntries) {
+        this.connector = connector;
+        this.tree = tree;
+        this.contextId = contextId;
+        this.maxEntries = maxEntries;
+        this.events = new EventEmitter();
+        this.buffer = [];
+        this.uncaught = [];
+        this.droppedCount = 0;
+        this.disposed = false;
+        this.onEntry = (entry) => {
+            const context = entry.source.context;
+            // Worker realms have no context; entries of other pages are not ours
+            if (!context || !this.tree.isWithin(context, this.contextId))
+                return;
+            const text = entry.text ?? "";
+            const record = {
+                level: entry.level,
+                type: entry.type,
+                ...(entry.type === "console" && { method: entry.method }),
+                text,
+                timestamp: entry.timestamp,
+            };
+            this.buffer.push(record);
+            if (this.buffer.length > this.maxEntries) {
+                this.buffer.shift();
+                this.droppedCount++;
+            }
+            if (entry.type === "console") {
+                const consoleEntry = entry;
+                this.emit("console", new ConsoleMessage(entry.level, consoleEntry.method, text, (consoleEntry.args ?? []).map((arg) => fromRemoteValue(arg)), entry.timestamp, entry.stackTrace));
+            }
+            else if (entry.type === "javascript") {
+                const error = new PageError(text, entry.timestamp, entry.stackTrace);
+                this.uncaught.push(error);
+                if (this.uncaught.length > this.maxEntries)
+                    this.uncaught.shift();
+                this.emit("pageerror", error);
+            }
+        };
+    }
+    static async start(connector, tree, contextId, options = {}) {
+        const logs = new PageLogs(connector, tree, contextId, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+        connector.onEvent("log.entryAdded", logs.onEntry);
+        try {
+            logs.subscription = await connector.subscribe(["log.entryAdded"]);
+        }
+        catch (err) {
+            connector.offEvent("log.entryAdded", logs.onEntry);
+            throw err;
+        }
+        return logs;
+    }
+    /** The newest entries, oldest first (a copy) */
+    get entries() {
+        return [...this.buffer];
+    }
+    /** Uncaught exceptions seen since the start or the last `clear()` */
+    get errors() {
+        return [...this.uncaught];
+    }
+    /** How many entries fell out of the buffer */
+    get dropped() {
+        return this.droppedCount;
+    }
+    on(event, listener) {
+        this.events.on(event, listener);
+    }
+    off(event, listener) {
+        this.events.off(event, listener);
+    }
+    clear() {
+        this.buffer = [];
+        this.uncaught = [];
+        this.droppedCount = 0;
+    }
+    /** Idempotent */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.connector.offEvent("log.entryAdded", this.onEntry);
+        this.buffer = [];
+        this.uncaught = [];
+        await this.subscription?.unsubscribe();
+    }
+    /** A listener that throws must not stop the recording or the other listeners */
+    emit(event, ...args) {
+        for (const listener of this.events.rawListeners(event)) {
+            try {
+                listener(...args);
+            }
+            catch (err) {
+                logger.error("A %s listener threw", event, { err });
+            }
+        }
+    }
+}

package/dist/browser/page-wait.d.ts

@@ -0,0 +1,9 @@
+import { WaitTimeoutError } from "../wait/wait-until.js";
+/** No download started in time */
+export declare class DownloadWaitTimeoutError extends WaitTimeoutError<undefined> {
+    constructor(timeout: number);
+}
+/** No file picker opened in time */
+export declare class FileChooserTimeoutError extends WaitTimeoutError<undefined> {
+    constructor(timeout: number);
+}

package/dist/browser/page-wait.js

@@ -0,0 +1,17 @@
+import { WaitTimeoutError } from "../wait/wait-until.js";
+/** No download started in time */
+export class DownloadWaitTimeoutError extends WaitTimeoutError {
+    constructor(timeout) {
+        super(timeout, undefined);
+        this.name = "DownloadWaitTimeoutError";
+        this.message = `waitForDownload(): no download started within ${timeout}ms`;
+    }
+}
+/** No file picker opened in time */
+export class FileChooserTimeoutError extends WaitTimeoutError {
+    constructor(timeout) {
+        super(timeout, undefined);
+        this.name = "FileChooserTimeoutError";
+        this.message = `waitForFileChooser(): no file chooser opened within ${timeout}ms`;
+    }
+}

package/dist/browser/page.d.ts

@@ -0,0 +1,370 @@
+import Locator, { type TextOptions } from "../locator/locator.js";
+import type { NetworkRequest, FailedRequest } from "../network/network-tracker.js";
+import { Recorder, type RecorderOptions } from "../recorder/recorder.js";
+import { ContextTree } from "./context-tree.js";
+import { Dialog } from "./dialog.js";
+import type { BrowserContext } from "./browser-context.js";
+import { type PdfOptions } from "./pdf.js";
+import { type EmulationOptions } from "./emulation.js";
+import { Download } from "./download.js";
+import { FileChooser } from "./file-chooser.js";
+import { type ScreenshotOptions } from "./screenshot.js";
+import { type ConsoleMessage, type LogRecord, type PageError } from "./page-logs.js";
+import { type RouteHandler } from "../network/router.js";
+import { Response } from "../network/response.js";
+import { type NetworkMatch } from "../network/network-wait.js";
+import type { UrlPattern } from "../network/url-match.js";
+import { type PreloadHandle } from "../script/preload.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BiDiCommands } from "../types/bidi.js";
+import type { SamuraiTestConfig } from "../types/config.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+/** Options that otherwise come from `samurai.config.ts` */
+export type PageSettings = Pick<SamuraiTestConfig, "network" | "navigation" | "use">;
+export type ReadinessState = NonNullable<BiDiCommands["browsingContext.navigate"]["params"]["wait"]>;
+export type LoadState = "load" | "domcontentloaded" | "networkidle";
+export interface NavigateOptions {
+    /** When navigateTo resolves. @default config `navigation.waitUntil`, then "complete" */
+    wait?: ReadinessState;
+    /** Time (ms) the navigation may take. @default config `navigation.timeout`, then 30000 */
+    timeout?: number;
+    /** Scheme added to a URL without one. @default "https" */
+    protocol?: "http" | "https";
+}
+interface NetworkEvents {
+    request: [NetworkRequest];
+    response: [Response];
+    requestfailed: [FailedRequest];
+}
+/** Everything `page.on` can listen for */
+interface PageEvents extends NetworkEvents {
+    download: [Download];
+    filechooser: [FileChooser];
+    dialog: [Dialog];
+    console: [ConsoleMessage];
+    pageerror: [PageError];
+}
+export type PageEventName = keyof PageEvents;
+export default class Page {
+    private biDiConnector;
+    private id;
+    private contextTree;
+    private helperRealm;
+    private initScripts;
+    private settings;
+    private networkTracker;
+    private pageEvents;
+    /** The navigation started by the last navigateTo; failures of it fail a wait */
+    private lastNavigation;
+    /** Base for relative page.goto URLs; falls back to the active run's baseURL */
+    private baseURL;
+    /** How far navigations that did not wait for the load got, by navigation id (the latest few) */
+    private navigationProgress;
+    private documentEvents;
+    private dialogHandling;
+    private pageLogs;
+    private loadedLogs;
+    private errorsAllowed;
+    private isClosed;
+    private browserContext;
+    private downloadTracker;
+    private fileChooserTracker;
+    private collectorPromise;
+    private responses;
+    private routerPromise;
+    private loadedRouter;
+    /** The context tree once loaded, for handlers that cannot wait for it */
+    private loadedTree;
+    private openDialogs;
+    /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
+    constructor(biDiConnector: BiDiConnector, contextId: string, settings?: PageSettings);
+    /** The BiDi browsing context id of this page's top-level context */
+    get contextId(): BrowsingContext;
+    /** The context tree, created on first use and shared by everything that needs to attribute frame events to this page */
+    tree(): Promise<ContextTree>;
+    /** Locates an element on the page and returns an interactable object */
+    locator(xpath: string): Locator;
+    /** Locates elements with a CSS selector */
+    getByCss(css: string): Locator;
+    /** Locates elements by their text: an exact match unless `match: "partial"` */
+    getByText(text: string, options?: TextOptions): Locator;
+    /** Locates form controls by their label text: an exact match unless `match: "partial"` */
+    getByLabel(text: string, options?: TextOptions): Locator;
+    /** Locates elements by their `data-testid` attribute */
+    getByTestId(testId: string): Locator;
+    /** Locates elements by ARIA role and, optionally, accessible name */
+    getByRole(role: string, options?: {
+        name?: string;
+    }): Locator;
+    /**
+     * Runs `script` before any page script in every document this page loads from now on, and once in
+     * the document that is loaded now. It runs in the page's own realm, so the page sees what it sets.
+     * A function receives `arg` (which must be JSON-serializable) as its only argument;
+     * a string is script source (statements) and takes no argument.
+     * @example
+     *  await page.addInitScript(() => { window.__testMode = true; });
+     *  await page.addInitScript((flags) => { window.flags = flags; }, { beta: true });
+     */
+    addInitScript(script: string | ((arg?: any) => void), arg?: unknown): Promise<PreloadHandle>;
+    /**
+     * Starts recording what a person does in the page as steps (see `Recorder`). The page must be driven by
+     * a person; stop with `recorder.stop()`.
+     */
+    record(options: RecorderOptions): Promise<Recorder>;
+    /** Removes everything the page registered in the browser: init scripts, framework helpers and event subscriptions */
+    dispose(): Promise<void>;
+    /** Sets the base that relative `goto` URLs resolve against; `undefined` falls back to the run's baseURL */
+    setBaseURL(url: string | undefined): void;
+    /**
+     * Navigates like `navigateTo`, but a URL starting with "/", "./" or "../" resolves against the base URL
+     * (`setBaseURL`, else the environment's `baseURL`).
+     * @example
+     *  await page.goto("/products");
+     *  await page.goto("https://example.com", { wait: "interactive" });
+     */
+    goto(url: string, options?: NavigateOptions): Promise<{
+        navigation: string | null;
+        url: string;
+    }>;
+    /**
+     * Navigates to `url` and resolves when the page reached `wait` (default "complete", the load event).
+     * A URL without a scheme gets `https://`. Throws NavigationError when the navigation fails or takes too long.
+     * The positional form `navigateTo(url, wait, protocol)` still works.
+     * @example
+     *  await page.navigateTo("example.com");
+     *  await page.navigateTo("localhost:3000", { wait: "interactive", protocol: "http" });
+     */
+    navigateTo(url: string, options?: NavigateOptions | ReadinessState, protocol?: "http" | "https"): Promise<{
+        navigation: string | null;
+        url: string;
+    }>;
+    /**
+     * Runs a navigation command and settles what waiting for it means: failures become NavigationErrors, and a
+     * navigation that did not wait for the load is watched so `waitForLoadState` can tell it from the old page.
+     */
+    private navigation;
+    /**
+     * Reloads the page and resolves when it reached `wait` (default like `navigateTo`). Firefox does not support
+     * `ignoreCache`; asking for it throws UnsupportedOperationError.
+     */
+    reload(options?: {
+        wait?: ReadinessState;
+        timeout?: number;
+        ignoreCache?: boolean;
+    }): Promise<{
+        navigation: string | null;
+        url: string;
+    }>;
+    /** Goes back one entry in the history. False when there is none to go back to */
+    goBack(): Promise<boolean>;
+    /** Goes forward one entry in the history. False when there is none */
+    goForward(): Promise<boolean>;
+    private traverse;
+    /** The URL of the page now */
+    url(): Promise<string>;
+    /** The title of the document now */
+    title(): Promise<string>;
+    /**
+     * Sets the size of the viewport (and, optionally, the device pixel ratio); `null` puts the browser's own size back.
+     * @example
+     *  await page.setViewport({ width: 390, height: 844, devicePixelRatio: 3 });
+     */
+    setViewport(viewport: {
+        width: number;
+        height: number;
+        devicePixelRatio?: number;
+    } | null): Promise<void>;
+    /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
+    applyDefaultViewport(): Promise<void>;
+    /**
+     * Takes a screenshot and returns the image (also written to `options.path`).
+     * @example
+     *  await page.screenshot({ path: "out/home.png", fullPage: true });
+     */
+    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    /** Renders the page as a PDF and returns it (also written to `options.path`) */
+    pdf(options?: PdfOptions): Promise<Buffer>;
+    /** The browser context (cookies, storage) this page belongs to */
+    context(): BrowserContext;
+    /** @internal Called when the page is opened in a context */
+    setContext(context: BrowserContext): void;
+    /** @internal Marks the page closed after its tab is gone (its context was removed) and releases what it registered */
+    detach(): Promise<void>;
+    /**
+     * Pretends things about this page only: locale, timezone, user agent, geolocation, offline, orientation, screen
+     * size. It wins over what the page's context says; `null` puts the real (or the context's) value back.
+     * @example
+     *  await page.emulate({ locale: "nl-NL", offline: true });
+     */
+    emulate(options: EmulationOptions): Promise<void>;
+    /**
+     * Grants a browser permission ("geolocation", "notifications", "camera", …) to the origin this page is on,
+     * or to `options.origin`. Geolocation emulation only answers once this is granted.
+     */
+    grantPermission(name: string, options?: {
+        origin?: string;
+    }): Promise<void>;
+    /** True once `close()` has run */
+    get closed(): boolean;
+    private assertOpen;
+    /**
+     * Closes the tab and releases everything the page registered. Later calls on the page throw "page closed".
+     * With `runBeforeUnload` the page's `beforeunload` handlers run first. Closing the browser's last tab may end the browser.
+     */
+    close(options?: {
+        runBeforeUnload?: boolean;
+    }): Promise<void>;
+    /**
+     * Waits until the page's document reached `state` (default "load"): "domcontentloaded" and "load" follow the
+     * document, "networkidle" is "load" plus a quiet network (see `waitForNetworkIdle`). Resolves at once when it
+     * is already there. Call it once the navigation has started; a document that is still the old one counts.
+     * @example
+     *  await page.locator("a[@id='next']").click();
+     *  await page.waitForLoadState("domcontentloaded");
+     */
+    waitForLoadState(state?: LoadState, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    private progressOf;
+    private onDocumentEvent;
+    private onDomContentLoaded;
+    private onLoad;
+    /** Starts recording which navigations reached DOMContentLoaded and load; kept until dispose */
+    private watchDocumentEvents;
+    private canBeAborted;
+    /** Subscribes to what a wait listens for; a browser that lacks the navigationAborted event (Firefox) is asked only once */
+    private subscribeToDocumentEvents;
+    private waitForDocumentState;
+    private networkSettings;
+    private navigationSettings;
+    /** The network tracker, created on first use. Rejects with NetworkTrackingDisabledError when config turned tracking off */
+    private network;
+    /**
+     * Starts following this page's requests now. Tracking only sees requests made after it started, so the
+     * browser calls this when it opens a page; without it, tracking starts on first use. Does nothing when
+     * config `network.track` is false.
+     */
+    startNetworkTracking(): Promise<void>;
+    /**
+     * Waits until no request has been in flight for `idleTime` ms (default config `network.idleTime`, then 500).
+     * Long-lived requests (server-sent events, long polling) keep the page busy until `timeout`.
+     */
+    waitForNetworkIdle(options?: {
+        idleTime?: number;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Listens for page events: `request`, `response`, `requestfailed` (network), `dialog` (a JavaScript dialog or
+     * `beforeunload` prompt opened; answer it with `dialog.accept()` / `dialog.dismiss()`), `console` (a `console.*` call)
+     * and `pageerror` (an uncaught exception). Starts what the event needs.
+     * A dialog nobody answers is dismissed automatically (a `beforeunload` prompt is accepted), so it cannot hang a test.
+     * @example
+     *  page.on("dialog", (dialog) => dialog.accept());
+     */
+    on<E extends PageEventName>(event: E, listener: (...args: PageEvents[E]) => void): this;
+    once<E extends PageEventName>(event: E, listener: (...args: PageEvents[E]) => void): this;
+    off<E extends PageEventName>(event: E, listener: (...args: PageEvents[E]) => void): this;
+    private trackInBackground;
+    /** Starts following downloads; the browser does this when it opens a page, `page.on("download")` and `waitForDownload` when needed */
+    startDownloadTracking(): Promise<void>;
+    /** Starts following file pickers; the browser does this when it opens a page, `page.on("filechooser")` and `waitForFileChooser` when needed */
+    startFileChooserTracking(): Promise<void>;
+    /**
+     * Resolves with the next download this page starts (when it starts, not when it ends: use `download.path()` for that).
+     * Call it before the download is triggered, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const download = await page.waitForDownload({ trigger: () => link.click() });
+     *  const file = await download.path();
+     */
+    waitForDownload(options?: {
+        timeout?: number;
+        trigger?: () => Promise<unknown>;
+    }): Promise<Download>;
+    /**
+     * Resolves with the next file picker the page opens (a click on an `<input type=file>` or its label). Nothing shows
+     * on screen: answer it with `chooser.setFiles(...)`.
+     * @example
+     *  const chooser = await page.waitForFileChooser({ trigger: () => page.locator("label[@for='avatar']").click() });
+     *  await chooser.setFiles("./fixtures/avatar.png");
+     */
+    waitForFileChooser(options?: {
+        timeout?: number;
+        trigger?: () => Promise<unknown>;
+    }): Promise<FileChooser>;
+    /**
+     * Starts keeping response bodies, which is what makes `response.body()` possible: the browser only keeps a body
+     * when this ran before the request started. `page.on("response")` and `waitForResponse` call it; config
+     * `network.collectBodies` calls it when the browser opens the page.
+     */
+    startBodyCollection(): Promise<void>;
+    /** One Response per network response, whoever asks, so a body is read from the browser once */
+    private responseFor;
+    private loadBody;
+    /**
+     * Resolves with the next response of this page whose URL matches (a pattern, see `route`) or that the function
+     * accepts. Call it before the request is made, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const response = await page.waitForResponse("**\/api/users", { trigger: () => button.click() });
+     *  const users = await response.json();
+     */
+    waitForResponse(match: NetworkMatch<Response>, options?: {
+        timeout?: number;
+        trigger?: () => Promise<unknown>;
+    }): Promise<Response>;
+    /** Like `waitForResponse`, for requests */
+    waitForRequest(match: NetworkMatch<NetworkRequest>, options?: {
+        timeout?: number;
+        trigger?: () => Promise<unknown>;
+    }): Promise<NetworkRequest>;
+    private waitForNetworkEvent;
+    /**
+     * Resolves with the first `event` `matches` accepts. Listens before `trigger` runs, so what the trigger causes cannot
+     * be missed; a trigger that throws rejects the wait with its error. `onTimeout` builds the error for a wait that ran out.
+     */
+    private waitForPageEvent;
+    /** Turns the browser's HTTP cache off (`true`) or back on for this page: every request then goes to the server */
+    setCacheDisabled(disabled: boolean): Promise<void>;
+    private router;
+    /**
+     * Sends requests whose URL matches to `handler`, which must answer with `route.fulfill()`, `route.continue()`,
+     * `route.abort()` or `route.fallback()` (await the answer: a handler that returns first lets the request continue).
+     * A string without `*` is an exact URL, with `*` / `**` a glob (`*` stops at `/`), a RegExp is tested on the URL.
+     * Routes added later are asked first. Errors a handler throws fail the request and, in the runner, the test.
+     * @example
+     *  await page.route("**\/api/users", (route) => route.fulfill({ json: [{ id: 1 }] }));
+     *  await page.route(/\.(png|jpg)$/, (route) => route.abort());
+     */
+    route(url: UrlPattern, handler: RouteHandler): Promise<void>;
+    /** Removes the routes for `url` (only the one with `handler`, when given) */
+    unroute(url: UrlPattern, handler?: RouteHandler): Promise<void>;
+    unrouteAll(): Promise<void>;
+    /** Errors thrown by route handlers so far */
+    routeErrors(): readonly Error[];
+    /**
+     * Starts collecting the page's console output and uncaught exceptions. The browser does this when it opens a page so
+     * early output is kept; `page.on("console" | "pageerror")` starts it when needed.
+     */
+    startLogging(): Promise<void>;
+    /** The newest console and error entries of this page (empty until logging started), oldest first */
+    getLogs(): readonly LogRecord[];
+    /** Uncaught exceptions of the page since logging started or `clearLogs()` */
+    pageErrors(): readonly PageError[];
+    /** How many entries fell out of the page's log buffer */
+    get logsDropped(): number;
+    clearLogs(): void;
+    /** Resolves once everything the page logged before the call has arrived: events and replies share one ordered connection */
+    syncLogs(): Promise<void>;
+    /** Tells the runner not to fail this test on uncaught page exceptions (config `logs.failOnPageError`) */
+    allowPageErrors(): void;
+    get pageErrorsAllowed(): boolean;
+    /** Starts watching for dialogs; the browser does this when it opens a page, `page.on("dialog")` when needed */
+    startDialogHandling(): Promise<void>;
+    private ownsContext;
+    private onPromptOpened;
+    private onPromptClosed;
+    /** Lets the listeners answer; a dialog still open afterwards gets the default answer, so nothing hangs */
+    private dispatchDialog;
+    /** Captures an image of the given navigable, and returns it as a Base64-encoded string */
+    captureScreenshot(clip?: BiDiCommands["browsingContext.captureScreenshot"]["params"]["clip"], format?: BiDiCommands["browsingContext.captureScreenshot"]["params"]["format"], origin?: BiDiCommands["browsingContext.captureScreenshot"]["params"]["origin"]): Promise<void>;
+}
+export {};