@itmetsam/samurai-framework 0.21.3 → 0.21.5

package/dist/assert/value-matchers.js

@@ -0,0 +1,53 @@
+import { format } from "./assertion-error.js";
+/** Calls `fn` and says whether it threw */
+export function callAndCatch(fn) {
+    try {
+        fn();
+        return { threw: false };
+    }
+    catch (error) {
+        return { threw: true, error };
+    }
+}
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "object" && error !== null && "message" in error)
+        return String(error.message);
+    return String(error);
+}
+/** Whether what was thrown fits `expected`; with no expectation, throwing at all fits */
+export function thrownMatches(outcome, expected) {
+    if (!outcome.threw)
+        return false;
+    if (expected === undefined)
+        return true;
+    if (typeof expected === "string")
+        return messageOf(outcome.error).includes(expected);
+    if (expected instanceof RegExp)
+        return messageOf(outcome.error).search(expected) !== -1;
+    if (expected instanceof Error)
+        return messageOf(outcome.error) === expected.message;
+    return outcome.error instanceof expected;
+}
+/** What a `toThrow` failure shows as the received value */
+export function describeOutcome(outcome) {
+    return outcome.threw ? `threw ${format(outcome.error)}` : "did not throw";
+}
+/** Jest's rule: the difference is under half a unit of the last digit asked for */
+export function isCloseTo(actual, expected, digits) {
+    if (actual === expected)
+        return true;
+    return Math.abs(expected - actual) < Math.pow(10, -digits) / 2;
+}
+/** The `length` of a string, array or array-like; undefined for anything else */
+export function lengthOf(value) {
+    if (typeof value === "string")
+        return value.length;
+    if (typeof value === "object" && value !== null && "length" in value) {
+        const length = value.length;
+        if (typeof length === "number")
+            return length;
+    }
+    return undefined;
+}

package/dist/browser/browser.d.ts

@@ -5,6 +5,8 @@ import { type BrowserProcess } from "./chrome-launch.js";
 import { BrowserContext } from "./browser-context.js";
 import type { UserPromptHandler } from "../types/bidi-modules/session.js";
 import { type EmulationOptions } from "./emulation.js";
+import { UseApplier } from "./use-applier.js";
+import type { UseOptions } from "../types/use.js";
 import { ChromeDownloadFolders } from "./download-folders.js";
 import { type BrowserLaunchOptions } from "./launch-flags.js";
 import type { BiDiCommands } from "../types/bidi.js";
@@ -27,6 +29,8 @@ export declare class Browser {
     readonly downloadsDir: string | undefined;
     private exitedPromise;
     private downloadFolders;
+    /** The `use` options of the run, once `setUse` has been called: what every context and page gets */
+    private use;
     constructor({ browserProc, biDiConnector, downloadsDir, downloadFolders, }: {
         browserProc: BrowserProcess;
         biDiConnector: BiDiConnector;
@@ -43,6 +47,11 @@ export declare class Browser {
     }>;
     /** Sets up a browser whose BiDi session is open: downloads folder, the first page and what it tracks */
     private static attach;
+    /**
+     * @internal The runner calls this after launch: the `use` options now apply to the default context and its pages,
+     * and to every context and page created later. Options passed to `newContext` win over them.
+     */
+    setUse(options: UseOptions, projectDir: string): Promise<UseApplier>;
     /** Closes the browser via BiDi browser.close, then makes sure the process has exited */
     close(): Promise<void>;
     /** Alias of close() */

package/dist/browser/browser.js

@@ -6,6 +6,7 @@ import Page from "./page.js";
 import { launchChrome } from "./chrome-launch.js";
 import { BrowserContext } from "./browser-context.js";
 import { validateEmulation } from "./emulation.js";
+import { UseApplier } from "./use-applier.js";
 import { prepareDownloadsDir, removeIfEmpty } from "./downloads-dir.js";
 import { ChromeDownloadFolders } from "./download-folders.js";
 import { launchFirefox } from "./launch-firefox.js";
@@ -46,7 +47,7 @@ export class Browser {
         const resolved = await projectBrowser(browserName);
         logger.debug("Found browser install location at: %s", resolved.executablePath);
         ensureBrowserProfile(browserName, launchOptions.profileDir &&
-            path.join(launchOptions.profileDir, "user.js"));
+            path.join(launchOptions.profileDir, "user.js"), launchOptions.use);
         const commandTimeout = await readCommandTimeout();
         // Both launchers hand back an open BiDi session: Firefox after session.new, Chrome with the one
         // its chromedriver created
@@ -58,6 +59,7 @@ export class Browser {
                     defaultLaunchOptions("chrome").profileDir,
                 headless: launchOptions.headless ?? defaultLaunchOptions("chrome").headless,
                 commandTimeout,
+                use: launchOptions.use,
                 signal,
             })
             : await launchFirefox({
@@ -122,6 +124,19 @@ export class Browser {
         await page.startTracking();
         return { browser, page };
     }
+    /**
+     * @internal The runner calls this after launch: the `use` options now apply to the default context and its pages,
+     * and to every context and page created later. Options passed to `newContext` win over them.
+     */
+    async setUse(options, projectDir) {
+        const name = this.biDiConnector.browserName ?? "firefox";
+        const applier = new UseApplier(this.biDiConnector, name, options, projectDir);
+        this.use = applier;
+        await applier.context(this.defaultContext);
+        for (const page of this.defaultContext.pages())
+            await applier.page(page);
+        return applier;
+    }
     /** Closes the browser via BiDi browser.close, then makes sure the process has exited */
     async close() {
         await this.downloadFolders?.dispose();
@@ -163,6 +178,7 @@ export class Browser {
         const page = new Page(this.biDiConnector, createBrowserContext.context);
         this.contextFor(userContext).register(page);
         await page.startTracking();
+        await this.use?.page(page);
         return page;
     }
     /**
@@ -173,18 +189,22 @@ export class Browser {
      *  const page = await alice.newPage();
      */
     async newContext(options = {}) {
-        const { acceptInsecureCerts, unhandledPromptBehavior, ...emulation } = options;
+        const { unhandledPromptBehavior, ...emulation } = options;
+        const insecure = options.acceptInsecureCerts ?? this.use?.acceptInsecureCerts;
+        delete emulation.acceptInsecureCerts;
         // A wrong value must not leave a context behind, so it is refused before one is created
         validateEmulation(emulation);
         const { userContext } = await this.biDiConnector.send("browser.createUserContext", {
-            ...(acceptInsecureCerts !== undefined && { acceptInsecureCerts }),
+            ...(insecure !== undefined && { acceptInsecureCerts: insecure }),
             ...(unhandledPromptBehavior && { unhandledPromptBehavior }),
         });
         const context = new BrowserContext(this.host, userContext, false);
         this.userContexts.set(userContext, context);
-        if (Object.keys(emulation).length > 0) {
+        if (this.use || Object.keys(emulation).length > 0) {
             try {
-                await context.emulate(emulation);
+                await this.use?.context(context);
+                if (Object.keys(emulation).length > 0)
+                    await context.emulate(emulation);
             }
             catch (err) {
                 // Firefox keeps a context in its profile until it is removed

package/dist/browser/cdp.d.ts

@@ -0,0 +1,11 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/**
+ * Sends a command the generated BiDi types do not list: `network.setExtraHeaders` (both browsers answer it) and
+ * the `goog:cdp.*` commands of Chrome
+ */
+export declare function sendRaw(connector: BiDiConnector, method: string, params: object): Promise<any>;
+/**
+ * Runs a Chrome DevTools Protocol command on the page `context` through the BiDi connection (`goog:cdp`, Chrome
+ * only). Use it where BiDi has no command yet; CDP state belongs to one page, so it is set per page.
+ */
+export declare function cdpSend(connector: BiDiConnector, context: string, method: string, params: object): Promise<void>;

package/dist/browser/cdp.js

@@ -0,0 +1,28 @@
+/** The CDP session of each page, per connection: `goog:cdp.getSession` attaches on every call */
+const sessions = new WeakMap();
+/**
+ * Sends a command the generated BiDi types do not list: `network.setExtraHeaders` (both browsers answer it) and
+ * the `goog:cdp.*` commands of Chrome
+ */
+export function sendRaw(connector, method, params) {
+    return connector.send(method, params);
+}
+/**
+ * Runs a Chrome DevTools Protocol command on the page `context` through the BiDi connection (`goog:cdp`, Chrome
+ * only). Use it where BiDi has no command yet; CDP state belongs to one page, so it is set per page.
+ */
+export async function cdpSend(connector, context, method, params) {
+    let known = sessions.get(connector);
+    if (!known)
+        sessions.set(connector, (known = new Map()));
+    let session = known.get(context);
+    if (session === undefined) {
+        const reply = await sendRaw(connector, "goog:cdp.getSession", { context });
+        known.set(context, (session = reply.session));
+    }
+    await sendRaw(connector, "goog:cdp.sendCommand", {
+        method,
+        params,
+        session,
+    });
+}

package/dist/browser/chrome-launch.d.ts

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import EventEmitter from "node:events";
 import { BiDiConnector } from "../transport/bidi-connection.js";
+import type { UseOptions } from "../types/use.js";
 /** What `Browser` needs of the thing it launched: the browser process, or for Chrome the chromedriver in front of it */
 export interface BrowserProcess {
     readonly exitCode: number | null;
@@ -14,6 +15,8 @@ interface ChromeLaunch {
     profileDir: string;
     headless: boolean;
     commandTimeout: number | undefined;
+    /** The `use` options that are fixed when the browser starts */
+    use?: UseOptions | undefined;
     signal?: AbortSignal | undefined;
 }
 export declare const chromeFlags: ({ headless, profileDir, }: Pick<ChromeLaunch, "headless" | "profileDir">) => string[];
@@ -25,6 +28,7 @@ export declare const chromeCapabilities: (launch: ChromeLaunch) => {
                 binary: string;
                 args: string[];
             };
+            acceptInsecureCerts?: boolean | undefined;
             unhandledPromptBehavior: {
                 default: string;
             };

package/dist/browser/chrome-launch.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import logger from "../logger/index.js";
 import { BiDiConnector } from "../transport/bidi-connection.js";
-import { SESSION_CAPABILITIES } from "./session-capabilities.js";
+import { sessionCapabilities } from "./session-capabilities.js";
 export const chromeFlags = ({ headless, profileDir, }) => [
     "--no-sandbox",
     "--no-first-run",
@@ -21,7 +21,7 @@ export const chromeCapabilities = (launch) => ({
         alwaysMatch: {
             browserName: "chrome",
             webSocketUrl: true,
-            ...SESSION_CAPABILITIES.alwaysMatch,
+            ...sessionCapabilities(launch.use).alwaysMatch,
             "goog:chromeOptions": {
                 binary: launch.executablePath,
                 args: chromeFlags(launch),

package/dist/browser/index.d.ts

@@ -2,5 +2,10 @@ export { Browser, type BrowserLaunchOptions, type ContextOptions, } from "./brow
 export { BrowserContext } from "./browser-context.js";
 export { default as Page } from "./page.js";
 export { DownloadTimeoutError } from "./download.js";
+export { UrlTimeoutError } from "./navigation-error.js";
+export { ScriptError, ScriptSerializationError, type PageFunction, } from "../script/call-function.js";
+export { ElementHandle } from "../script/element-handle.js";
+export { RemoteObject } from "../script/serialize.js";
+export type { BoundingBox } from "../locator/element-reads.js";
 export { EmulationUnsupportedError } from "./emulation.js";
 export { findBrowser } from "./browser-finder.js";

package/dist/browser/index.js

@@ -2,5 +2,9 @@ export { Browser, } from "./browser.js";
 export { BrowserContext } from "./browser-context.js";
 export { default as Page } from "./page.js";
 export { DownloadTimeoutError } from "./download.js";
+export { UrlTimeoutError } from "./navigation-error.js";
+export { ScriptError, ScriptSerializationError, } from "../script/call-function.js";
+export { ElementHandle } from "../script/element-handle.js";
+export { RemoteObject } from "../script/serialize.js";
 export { EmulationUnsupportedError } from "./emulation.js";
 export { findBrowser } from "./browser-finder.js";

package/dist/browser/launch-firefox.js

@@ -51,7 +51,7 @@ export function launchFirefox(launch) {
                 connector = await BiDiConnector.connect(url, { commandTimeout });
                 const status = await connector.send("session.status", {});
                 logger.verbose("Session status", status);
-                await startSession(connector, label, commandTimeout);
+                await startSession(connector, label, commandTimeout, launchOptions.use);
                 logger.verbose("Session started successfully");
                 settled();
                 resolve({ proc, connector });

package/dist/browser/launch-flags.d.ts

@@ -1,4 +1,5 @@
 import type { SupportedBrowser } from "../types/browser.js";
+import type { UseOptions } from "../types/use.js";
 export interface BrowserLaunchOptions {
     /** Which port to use for the WebDeveloper tools */
     port: number;
@@ -6,6 +7,8 @@ export interface BrowserLaunchOptions {
     profileDir: string;
     /** Start the browser in headless mode or in UI mode */
     headless: boolean;
+    /** The `use` options that can only be set when the browser starts (certificates, and Firefox's JavaScript and colour scheme) */
+    use?: UseOptions;
 }
 /** The profile folder of a worker: worker 0 keeps the browser's own folder, worker N gets `<browser>-wN` beside it */
 export declare const workerProfileDir: (browserName: SupportedBrowser, workerIndex: number) => string;
@@ -15,4 +18,4 @@ export declare const browserLaunchFlag: (browserName: SupportedBrowser, launchOp
 /** Env added to a browser's process */
 export declare const browserLaunchEnv: (browserName: SupportedBrowser, appDataPath?: string) => Record<string, string>;
 /** Writes the browser's user.js unless it already holds the current prefs; an outdated one is replaced */
-export declare function ensureBrowserProfile(browserName: SupportedBrowser, profilePath?: string | undefined): void;
+export declare function ensureBrowserProfile(browserName: SupportedBrowser, profilePath?: string | undefined, use?: UseOptions): void;

package/dist/browser/launch-flags.js

@@ -71,15 +71,28 @@ const browserProfiles = {
     user_pref("browser.newtabpage.enabled", false);
   `,
 };
+/**
+ * The prefs a Firefox run chooses. Always written, with the browser's own values when nothing is chosen: Firefox
+ * keeps a pref a user.js set in the profile, so a run without `use` would otherwise inherit the one before it.
+ */
+function usePrefs(use) {
+    const scheme = { light: 1, dark: 0, "no-preference": 2 }[use?.colorScheme ?? "no-preference"];
+    return `
+    user_pref("javascript.enabled", ${use?.javaScriptEnabled !== false});
+    user_pref("layout.css.prefers-color-scheme.content-override", ${scheme});
+  `;
+}
+const profileText = (browserName, use) => browserProfiles[browserName] +
+    (browserName === "firefox" ? usePrefs(use) : "");
 /** Writes the browser's user.js unless it already holds the current prefs; an outdated one is replaced */
-export function ensureBrowserProfile(browserName, profilePath = browserProfilePath(browserName)) {
+export function ensureBrowserProfile(browserName, profilePath = browserProfilePath(browserName), use) {
     logger.verbose("Checking browser profile for: %s", browserName);
     if (!profilePath) {
         logger.verbose("No browser profile path declared, skipping...");
         return;
     }
     if (existsSync(profilePath)) {
-        if (readFileSync(profilePath, "utf8") === browserProfiles[browserName]) {
+        if (readFileSync(profilePath, "utf8") === profileText(browserName, use)) {
             logger.verbose("Browser profile is up to date at: %s", profilePath);
             return;
         }
@@ -88,12 +101,12 @@ export function ensureBrowserProfile(browserName, profilePath = browserProfilePa
     else {
         logger.verbose("No browser profile created yet for %s", browserName);
     }
-    createBrowserProfile(browserName, profilePath);
+    createBrowserProfile(browserName, profilePath, use);
 }
-function createBrowserProfile(browserName, profilePath) {
+function createBrowserProfile(browserName, profilePath, use) {
     logger.verbose("Creating browser profile for %s at %s", browserName, profilePath);
     mkdirSync(path.dirname(profilePath), { recursive: true });
-    writeFileSync(profilePath, browserProfiles[browserName], {
+    writeFileSync(profilePath, profileText(browserName, use), {
         encoding: "utf8",
     });
     logger.verbose("Browser profile created");

package/dist/browser/navigation-error.d.ts

@@ -9,5 +9,9 @@ export declare class NavigationError extends Error {
 }
 /** The page did not reach the awaited load state in time */
 export declare class LoadStateTimeoutError extends WaitTimeoutError<undefined> {
-    constructor(state: string, timeout: number);
+    constructor(state: string, timeout: number, operation?: string);
+}
+/** The page's URL did not match in time */
+export declare class UrlTimeoutError extends WaitTimeoutError<string> {
+    constructor(expected: string, timeout: number, lastUrl: string | undefined);
 }

package/dist/browser/navigation-error.js

@@ -11,9 +11,17 @@ export class NavigationError extends Error {
 }
 /** The page did not reach the awaited load state in time */
 export class LoadStateTimeoutError extends WaitTimeoutError {
-    constructor(state, timeout) {
+    constructor(state, timeout, operation = "waitForLoadState") {
         super(timeout, undefined);
         this.name = "LoadStateTimeoutError";
-        this.message = `waitForLoadState("${state}") did not finish within ${timeout}ms`;
+        this.message = `${operation}("${state}") did not finish within ${timeout}ms`;
+    }
+}
+/** The page's URL did not match in time */
+export class UrlTimeoutError extends WaitTimeoutError {
+    constructor(expected, timeout, lastUrl) {
+        super(timeout, lastUrl);
+        this.name = "UrlTimeoutError";
+        this.message = `waitForURL(): the URL did not match ${expected} within ${timeout}ms (last URL: ${lastUrl ?? "unknown"})`;
     }
 }

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

@@ -0,0 +1,5 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** The page's markup now, with its doctype */
+export declare function readContent(connector: BiDiConnector, context: string): Promise<string>;
+/** Writes `html` as the page's document; true when the document reached `state` within `timeout` ms */
+export declare function writeContent(connector: BiDiConnector, context: string, html: string, state: "load" | "domcontentloaded", timeout: number): Promise<boolean>;

package/dist/browser/page-content.js

@@ -0,0 +1,43 @@
+import { callFunction } from "../script/call-function.js";
+/** The document as markup: the doctype (when there is one) followed by the document element */
+const READ_CONTENT = `() => {
+  const type = document.doctype;
+  const doctype = type
+    ? "<!DOCTYPE " + type.name +
+      (type.publicId ? ' PUBLIC "' + type.publicId + '"' : "") +
+      (!type.publicId && type.systemId ? " SYSTEM" : "") +
+      (type.systemId ? ' "' + type.systemId + '"' : "") + ">"
+    : "";
+  return doctype + document.documentElement.outerHTML;
+}`;
+/**
+ * Replaces the document in place with `document.open()`, `write()` and `close()`: scripts and styles in `html` run and
+ * apply, and the page keeps its URL and origin. The listeners are added after `open()` because it removes the old ones.
+ * Resolves true once the `load` (or `DOMContentLoaded`) event fired, false when `timeout` ms passed first.
+ */
+const WRITE_CONTENT = `async (html, state, timeout) => {
+  document.open();
+  const reached = new Promise((resolve) => {
+    const done = () => resolve(true);
+    if (state === "domcontentloaded") document.addEventListener("DOMContentLoaded", done, { once: true });
+    else window.addEventListener("load", done, { once: true });
+    setTimeout(() => resolve(false), timeout);
+  });
+  document.write(html);
+  document.close();
+  return reached;
+}`;
+/** The page's markup now, with its doctype */
+export function readContent(connector, context) {
+    return callFunction(connector, context, READ_CONTENT, [], {
+        awaitPromise: false,
+    });
+}
+/** Writes `html` as the page's document; true when the document reached `state` within `timeout` ms */
+export function writeContent(connector, context, html, state, timeout) {
+    return callFunction(connector, context, WRITE_CONTENT, [
+        html,
+        state,
+        timeout,
+    ]);
+}

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

@@ -0,0 +1,9 @@
+import { type PageFunction } from "../script/call-function.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/** Whether a string is the source of a function (called with the argument) rather than an expression (evaluated) */
+export declare function isFunctionSource(source: string): boolean;
+/**
+ * Runs a function, or a string, in the page and returns the result as plain JavaScript (see `fromRemoteValue`).
+ * A function (or a string holding a function's source) is called with `arg`; any other string is an expression.
+ */
+export declare function evaluateInPage<R, A>(connector: BiDiConnector, context: string, fn: PageFunction<[A], R>, arg?: A): Promise<R>;

package/dist/browser/page-evaluate.js

@@ -0,0 +1,20 @@
+import { callFunction, evaluateExpression, } from "../script/call-function.js";
+/** A function (or arrow function, async or not) written out as source, as opposed to an expression */
+const FUNCTION_SOURCE = /^\s*(?:async\s+)?(?:function\b|(?:\((?:[^()]|\([^()]*\))*\)|[\w$]+)\s*=>)/;
+/** Whether a string is the source of a function (called with the argument) rather than an expression (evaluated) */
+export function isFunctionSource(source) {
+    return FUNCTION_SOURCE.test(source);
+}
+/**
+ * Runs a function, or a string, in the page and returns the result as plain JavaScript (see `fromRemoteValue`).
+ * A function (or a string holding a function's source) is called with `arg`; any other string is an expression.
+ */
+export async function evaluateInPage(connector, context, fn, arg) {
+    if (typeof fn === "string" && !isFunctionSource(fn)) {
+        if (arg !== undefined) {
+            throw new TypeError("evaluate(): an expression takes no argument; pass a function to use one");
+        }
+        return evaluateExpression(connector, context, fn);
+    }
+    return callFunction(connector, context, fn, arg === undefined ? [] : [arg]);
+}

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

@@ -13,6 +13,6 @@ export declare class PageLocators {
     private strictOverride;
     constructor(biDiConnector: BiDiConnector, id: BrowsingContext, helperRealm: HelperRealm, pageConfig: PageConfig, assertOpen: () => void);
     locate(selector: ConstructorParameters<typeof Locator>[0]): Locator;
-    /** `undefined` goes back to config `use.strictSelectors`; applies to locators already made, too */
+    /** `undefined` goes back to config `use.strictSelectors`; a locator asks once, at its first action or read, so earlier ones that already ran keep their answer */
     setStrictSelectors(enabled: boolean | undefined): void;
 }

package/dist/browser/page-locators.js

@@ -12,7 +12,7 @@ export class PageLocators {
         this.assertOpen();
         return new Locator(selector, this.biDiConnector, this.id, this.helperRealm, [], () => this.pageConfig.strictSelectors(this.strictOverride));
     }
-    /** `undefined` goes back to config `use.strictSelectors`; applies to locators already made, too */
+    /** `undefined` goes back to config `use.strictSelectors`; a locator asks once, at its first action or read, so earlier ones that already ran keep their answer */
     setStrictSelectors(enabled) {
         this.strictOverride = enabled;
     }

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

@@ -1,4 +1,5 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { type UrlPattern } from "../network/url-match.js";
 import type { DocumentWatcher } from "./document-watcher.js";
 import type { PageConfig, ReadinessState } from "./page-settings.js";
 export type LoadState = "load" | "domcontentloaded" | "networkidle";
@@ -54,6 +55,23 @@ export declare class PageNavigation {
     waitForLoadState(state?: LoadState, options?: {
         timeout?: number;
     }): Promise<void>;
+    /**
+     * Waits until the page's URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then waits for `waitUntil` (default "load"). A string starting with "/", "./" or
+     * "../" resolves against the base URL, as in `goto`. `timeout` applies to the URL, then again to the load state.
+     */
+    waitForURL(url: UrlPattern | ((url: URL) => boolean), options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
+    /**
+     * Replaces the document with `html` (see `writeContent`) and waits for `waitUntil` (default "load"); "networkidle" is
+     * "load" plus a quiet network. The page keeps its URL.
+     */
+    setContent(html: string, options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
     /**
      * 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.

package/dist/browser/page-navigation.js

@@ -1,8 +1,11 @@
+import logger from "../logger/index.js";
 import { peekRunSettings } from "../config/run-settings.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { UnsupportedOperationError } from "../transport/unsupported.js";
-import { WaitTimeoutError } from "../wait/wait-until.js";
-import { LoadStateTimeoutError, NavigationError } from "./navigation-error.js";
+import { matchUrl } from "../network/url-match.js";
+import { waitUntil, WaitTimeoutError } from "../wait/wait-until.js";
+import { LoadStateTimeoutError, NavigationError, UrlTimeoutError, } from "./navigation-error.js";
+import { writeContent } from "./page-content.js";
 /** A URL starting with "/", "./" or "../" */
 const RELATIVE_URL = /^\.{0,2}\//;
 /** Resolves a slash-led `url` against `base`; any other URL is returned as given */
@@ -88,6 +91,53 @@ export class PageNavigation {
         if (state === "networkidle")
             await this.deps.waitForNetworkIdle({ timeout });
     }
+    /**
+     * Waits until the page's URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then waits for `waitUntil` (default "load"). A string starting with "/", "./" or
+     * "../" resolves against the base URL, as in `goto`. `timeout` applies to the URL, then again to the load state.
+     */
+    async waitForURL(url, options = {}) {
+        this.deps.assertOpen();
+        const timeout = await this.deps.config.navigationTimeout(options.timeout);
+        const pattern = typeof url === "string" ? this.resolveURL(url, "waitForURL") : url;
+        const matches = typeof pattern === "function"
+            ? (current) => pattern(new URL(current))
+            : (current) => matchUrl(pattern, current);
+        // A read that fails while the page navigates counts as no URL yet
+        const read = () => this.deps.url().catch((err) => {
+            this.deps.assertOpen();
+            logger.debug("waitForURL could not read the URL", { err });
+            return undefined;
+        });
+        try {
+            await waitUntil(read, (current) => current !== undefined && matches(current), { timeout });
+        }
+        catch (err) {
+            if (!(err instanceof WaitTimeoutError))
+                throw err;
+            const wanted = typeof pattern === "function"
+                ? "the predicate"
+                : typeof pattern === "string"
+                    ? `"${pattern}"`
+                    : String(pattern);
+            throw new UrlTimeoutError(wanted, timeout, err.last);
+        }
+        await this.waitForLoadState(options.waitUntil, { timeout });
+    }
+    /**
+     * Replaces the document with `html` (see `writeContent`) and waits for `waitUntil` (default "load"); "networkidle" is
+     * "load" plus a quiet network. The page keeps its URL.
+     */
+    async setContent(html, options = {}) {
+        this.deps.assertOpen();
+        const timeout = await this.deps.config.navigationTimeout(options.timeout);
+        const state = options.waitUntil ?? "load";
+        const reached = await writeContent(this.connector, this.contextId, html, state === "domcontentloaded" ? "domcontentloaded" : "load", timeout);
+        if (!reached)
+            throw new LoadStateTimeoutError(state, timeout, "setContent");
+        if (state === "networkidle")
+            await this.deps.waitForNetworkIdle({ timeout });
+    }
     /**
      * 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.

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

@@ -19,7 +19,7 @@ export declare class PageConfig {
         timeout?: number;
         waitUntil?: "none" | "interactive" | "complete";
     }>;
-    use(): Promise<{
+    use(): Promise<import("../api.js").UseOptions & {
         viewport?: {
             width: number;
             height: number;