@itmetsam/samurai-framework 0.21.5 → 0.22.1

package/dist/api.d.ts

@@ -1,8 +1,13 @@
 export { test, describe, beforeEach, afterEach, beforeAll, afterAll, } from "./runner/registry.js";
+export { request, type NewRequestContextOptions } from "./request/request.js";
+export type { APIRequestContext, RequestOptions, } from "./request/api-request-context.js";
+export type { APIResponse } from "./request/api-response.js";
+export type { FilePayload } from "./request/request-body.js";
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
+export type { GlobalHookConfig, WebServerConfig } from "./types/config.js";
 export { defineStep, type StepDefinition, type StepResult, type StepRunInput, } from "./flows/steps/index.js";
-export type { AllHookFixtures, TestAnnotation, TestAttachment, TestDetails, TestFixtures, TestInfo, TestOptions, TestOutputs, TestStepEntry, } from "./types/test.js";
-export type { FixtureOptions } from "./types/extend.js";
-export type { ColorScheme, StorageState, StorageStateCookie, UseOptions, } from "./types/use.js";
+export type { AllHookFixtures, TestAnnotation, TestAttachment, TestDetails, TestFixtures, TestInfo, TestOptions, TestOutputs, TestFixtureEntry, TestStepEntry, } from "./types/test.js";
+export type { FixtureField, FixtureOptions, FixtureOutput, } from "./types/extend.js";
+export type { ColorScheme, StorageState, StorageStateCookie, RuntimeUseOptions, UseOptions, FixtureUse, } from "./types/use.js";
 export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/api.js

@@ -1,4 +1,5 @@
 export { test, describe, beforeEach, afterEach, beforeAll, afterAll, } from "./runner/registry.js";
+export { request } from "./request/request.js";
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export { defineStep, } from "./flows/steps/index.js";

package/dist/browser/browser-context.d.ts

@@ -1,6 +1,7 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 import type { SameSite } from "../types/bidi-modules/network.js";
-import { type EmulationOptions } from "./emulation.js";
+import { APIRequestContext, type RequestContextOptions } from "../request/api-request-context.js";
+import type { RuntimeUseOptions } from "../types/use.js";
 import type Page from "./page.js";
 /** A cookie as `context.cookies()` returns it */
 export interface Cookie {
@@ -54,6 +55,8 @@ export declare class BrowserContext {
     readonly isDefault: boolean;
     private opened;
     private isClosed;
+    private requestContext;
+    private readonly requestDefaults;
     constructor(host: ContextHost, 
     /** The BiDi user context id; "default" for the browser's own */
     id: string, isDefault: boolean);
@@ -65,6 +68,14 @@ export declare class BrowserContext {
     pages(): Page[];
     /** @internal Called when a page is opened in this context */
     register(page: Page): void;
+    /**
+     * Makes HTTP requests from the test that share this context's cookies: they send the cookies the pages hold,
+     * and the cookies the responses set are in the pages' `document.cookie` afterwards. Its `extraHTTPHeaders`
+     * and `ignoreHTTPSErrors` follow the run's `use` options.
+     */
+    get request(): APIRequestContext;
+    /** @internal What `request` starts from: the run's `use.extraHTTPHeaders` and `acceptInsecureCerts` */
+    setRequestDefaults(defaults: RequestContextOptions): void;
     /** Adds cookies to this context's storage. Every cookie is checked before any is stored */
     addCookies(cookies: CookieInput[]): Promise<void>;
     /** The cookies of this context, optionally only those matching `filter` */
@@ -72,15 +83,16 @@ export declare class BrowserContext {
     /** Deletes all cookies of this context, or those matching `filter` */
     clearCookies(filter?: CookieFilter): Promise<void>;
     /**
-     * Pretends things about every page of this context, including pages opened later: locale, timezone, user agent,
-     * geolocation, offline, orientation, screen size. A page's own `emulate()` wins over the context's.
+     * Changes the `use` options that can change while the browser runs for every page of this context, including
+     * pages opened later: locale, timezone, user agent, geolocation, offline, orientation, screen, hasTouch,
+     * javaScriptEnabled. A page's own `use()` wins over the context's.
      * @example
-     *  await context.emulate({ locale: "nl-NL", timezone: "Europe/Amsterdam", offline: false });
+     *  await context.use({ locale: "nl-NL", timezone: "Europe/Amsterdam", offline: false });
      */
-    emulate(options: EmulationOptions): Promise<void>;
+    use(options: RuntimeUseOptions): Promise<void>;
     /**
      * Grants, denies or resets a browser permission ("geolocation", "notifications", "camera", …) for `origin`
-     * in this context. Geolocation emulation only answers once the permission is granted.
+     * in this context. A geolocation override only answers once the permission is granted.
      */
     setPermission(name: string, state: "granted" | "denied" | "prompt", origin: string): Promise<void>;
     /** Removes the context; the browser closes its pages. The default context cannot be closed */

package/dist/browser/browser-context.js

@@ -1,5 +1,7 @@
 import { BiDiError } from "../transport/bidi-error.js";
-import { applyEmulation } from "./emulation.js";
+import { APIRequestContext, } from "../request/api-request-context.js";
+import { ContextCookieStore } from "./context-cookie-store.js";
+import { applyUse } from "./use-commands.js";
 /**
  * An isolated browsing session inside one browser: its own cookies, storage and cache. Pages opened in it
  * share them; pages of other contexts see none of it.
@@ -13,6 +15,7 @@ export class BrowserContext {
         this.isDefault = isDefault;
         this.opened = [];
         this.isClosed = false;
+        this.requestDefaults = {};
     }
     /** True once `close()` has run */
     get closed() {
@@ -36,6 +39,19 @@ export class BrowserContext {
         this.opened.push(page);
         page.setContext(this);
     }
+    /**
+     * Makes HTTP requests from the test that share this context's cookies: they send the cookies the pages hold,
+     * and the cookies the responses set are in the pages' `document.cookie` afterwards. Its `extraHTTPHeaders`
+     * and `ignoreHTTPSErrors` follow the run's `use` options.
+     */
+    get request() {
+        this.assertOpen();
+        return (this.requestContext ??= new APIRequestContext(this.requestDefaults, new ContextCookieStore(this)));
+    }
+    /** @internal What `request` starts from: the run's `use.extraHTTPHeaders` and `acceptInsecureCerts` */
+    setRequestDefaults(defaults) {
+        Object.assign(this.requestDefaults, defaults);
+    }
     /** Adds cookies to this context's storage. Every cookie is checked before any is stored */
     async addCookies(cookies) {
         this.assertOpen();
@@ -65,18 +81,19 @@ export class BrowserContext {
         });
     }
     /**
-     * Pretends things about every page of this context, including pages opened later: locale, timezone, user agent,
-     * geolocation, offline, orientation, screen size. A page's own `emulate()` wins over the context's.
+     * Changes the `use` options that can change while the browser runs for every page of this context, including
+     * pages opened later: locale, timezone, user agent, geolocation, offline, orientation, screen, hasTouch,
+     * javaScriptEnabled. A page's own `use()` wins over the context's.
      * @example
-     *  await context.emulate({ locale: "nl-NL", timezone: "Europe/Amsterdam", offline: false });
+     *  await context.use({ locale: "nl-NL", timezone: "Europe/Amsterdam", offline: false });
      */
-    async emulate(options) {
+    async use(options) {
         this.assertOpen();
-        await applyEmulation(this.host.connector, { userContexts: [this.id] }, options);
+        await applyUse(this.host.connector, { userContexts: [this.id] }, options);
     }
     /**
      * Grants, denies or resets a browser permission ("geolocation", "notifications", "camera", …) for `origin`
-     * in this context. Geolocation emulation only answers once the permission is granted.
+     * in this context. A geolocation override only answers once the permission is granted.
      */
     async setPermission(name, state, origin) {
         this.assertOpen();
@@ -104,6 +121,7 @@ export class BrowserContext {
                 throw err;
         }
         this.isClosed = true;
+        await this.requestContext?.dispose();
         const pages = this.opened;
         this.opened = [];
         await Promise.all(pages.map((page) => page.detach()));

package/dist/browser/browser.d.ts

@@ -4,16 +4,16 @@ import Page from "./page.js";
 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 type { RuntimeUseOptions } from "../types/use.js";
 import { UseApplier } from "./use-applier.js";
-import type { UseOptions } from "../types/use.js";
+import type { GroupUse } from "../types/config.js";
 import { ChromeDownloadFolders } from "./download-folders.js";
 import { type BrowserLaunchOptions } from "./launch-flags.js";
 import type { BiDiCommands } from "../types/bidi.js";
 import type { CookieFilter, PartialCookie, PartitionDescriptor } from "../types/bidi-modules/storage.js";
 export type { BrowserLaunchOptions } from "./launch-flags.js";
 /** Options of `browser.newContext()` */
-export interface ContextOptions extends EmulationOptions {
+export interface ContextOptions extends RuntimeUseOptions {
     acceptInsecureCerts?: boolean;
     /** How this context's pages answer JavaScript dialogs; the session default is to leave them for the framework */
     unhandledPromptBehavior?: UserPromptHandler;
@@ -51,7 +51,7 @@ export declare class Browser {
      * @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>;
+    setUse(options: GroupUse, 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

@@ -5,7 +5,7 @@ import { projectBrowser } from "../browsers/resolve.js";
 import Page from "./page.js";
 import { launchChrome } from "./chrome-launch.js";
 import { BrowserContext } from "./browser-context.js";
-import { validateEmulation } from "./emulation.js";
+import { validateRuntimeUse } from "./use-commands.js";
 import { UseApplier } from "./use-applier.js";
 import { prepareDownloadsDir, removeIfEmpty } from "./downloads-dir.js";
 import { ChromeDownloadFolders } from "./download-folders.js";
@@ -189,31 +189,34 @@ export class Browser {
      *  const page = await alice.newPage();
      */
     async newContext(options = {}) {
-        const { unhandledPromptBehavior, ...emulation } = options;
+        const { unhandledPromptBehavior, ...settings } = options;
         const insecure = options.acceptInsecureCerts ?? this.use?.acceptInsecureCerts;
-        delete emulation.acceptInsecureCerts;
+        delete settings.acceptInsecureCerts;
         // A wrong value must not leave a context behind, so it is refused before one is created
-        validateEmulation(emulation);
+        validateRuntimeUse(settings);
         const { userContext } = await this.biDiConnector.send("browser.createUserContext", {
             ...(insecure !== undefined && { acceptInsecureCerts: insecure }),
             ...(unhandledPromptBehavior && { unhandledPromptBehavior }),
         });
         const context = new BrowserContext(this.host, userContext, false);
         this.userContexts.set(userContext, context);
-        if (this.use || Object.keys(emulation).length > 0) {
+        if (this.use || Object.keys(settings).length > 0) {
             try {
                 await this.use?.context(context);
-                if (Object.keys(emulation).length > 0)
-                    await context.emulate(emulation);
+                if (Object.keys(settings).length > 0)
+                    await context.use(settings);
             }
             catch (err) {
                 // Firefox keeps a context in its profile until it is removed
-                await context.close().catch((closeErr) => logger.debug("Could not remove a context whose emulation failed", {
+                await context.close().catch((closeErr) => logger.debug("Could not remove a context whose settings failed", {
                     closeErr,
                 }));
                 throw err;
             }
         }
+        // The option of this context wins over the run's `use.acceptInsecureCerts`
+        if (insecure !== undefined)
+            context.setRequestDefaults({ ignoreHTTPSErrors: insecure });
         return context;
     }
     /** The default context, then the contexts this browser created that are still open */

package/dist/browser/chrome-launch.js

@@ -118,18 +118,26 @@ export async function launchChrome(launch) {
         launch.signal?.removeEventListener("abort", onAbort);
     }
 }
+/** How many of chromedriver's last lines the error carries when it exits before it is ready */
+const OUTPUT_TAIL_LINES = 10;
 function driverPort(driver) {
     return new Promise((resolve, reject) => {
+        const tail = [];
         const onData = (data) => {
             logger.debug(`chromedriver: ${data}`);
             const match = String(data).match(/started successfully on port (\d+)/);
             if (match)
                 resolve(Number(match[1]));
+            for (const line of String(data).split("\n"))
+                if (line.trim() !== "")
+                    tail.push(line);
+            tail.splice(0, Math.max(0, tail.length - OUTPUT_TAIL_LINES));
         };
         driver.stdout?.on("data", onData);
         driver.stderr?.on("data", onData);
         driver.once("error", reject);
-        driver.once("exit", (code) => reject(new Error(`chromedriver exited with code ${code} before it was ready`)));
+        driver.once("exit", (code, signal) => reject(new Error(`chromedriver exited with code ${code ?? signal} before it was ready` +
+            (tail.length > 0 ? `. Its last output:\n${tail.join("\n")}` : ""))));
     });
 }
 /** chromedriver as the process of a Chrome launch: ending it ends Chrome, and so does deleting the session */

package/dist/browser/context-cookie-store.d.ts

@@ -0,0 +1,17 @@
+import { type CookieStore } from "../request/cookie-jar.js";
+import type { StorageStateCookie } from "../types/use.js";
+import type { BrowserContext } from "./browser-context.js";
+/**
+ * The cookies of a browser context as a request context's cookie store: requests send what the pages of the
+ * context hold, and the `Set-Cookie` headers of the responses go into the context, so both see one session.
+ */
+export declare class ContextCookieStore implements CookieStore {
+    private readonly context;
+    constructor(context: BrowserContext);
+    cookieHeader(url: URL): Promise<string | undefined>;
+    store(url: URL, setCookies: string[]): Promise<void>;
+    list(): Promise<StorageStateCookie[]>;
+    private add;
+    /** The site deleted the cookie: the browser keeps it under the host or, for a domain cookie, the dotted domain */
+    private remove;
+}

package/dist/browser/context-cookie-store.js

@@ -0,0 +1,90 @@
+import logger from "../logger/index.js";
+import { cookieHeaderOf, cookieMatches, isExpired, parseSetCookie, } from "../request/cookie-jar.js";
+const CAPITAL = { strict: "Strict", lax: "Lax", none: "None" };
+function stored(cookie) {
+    const sameSite = CAPITAL[cookie.sameSite];
+    return {
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.domain.replace(/^\./, "").toLowerCase(),
+        hostOnly: !cookie.domain.startsWith("."),
+        path: cookie.path,
+        secure: cookie.secure,
+        httpOnly: cookie.httpOnly,
+        ...(sameSite !== undefined && { sameSite }),
+        ...(cookie.expiry !== undefined && { expires: cookie.expiry }),
+    };
+}
+/**
+ * The cookies of a browser context as a request context's cookie store: requests send what the pages of the
+ * context hold, and the `Set-Cookie` headers of the responses go into the context, so both see one session.
+ */
+export class ContextCookieStore {
+    constructor(context) {
+        this.context = context;
+    }
+    async cookieHeader(url) {
+        const now = Date.now();
+        const matching = (await this.context.cookies())
+            .map(stored)
+            .filter((cookie) => cookieMatches(cookie, url, now));
+        return cookieHeaderOf(matching);
+    }
+    async store(url, setCookies) {
+        for (const header of setCookies) {
+            const cookie = parseSetCookie(header, url);
+            if (!cookie)
+                continue;
+            try {
+                if (isExpired(cookie))
+                    await this.remove(cookie);
+                else
+                    await this.add(cookie);
+            }
+            catch (err) {
+                // A browser refuses some cookies a server can send (Secure on a plain-http page, say): as a browser would
+                logger.debug("The browser did not take a Set-Cookie", {
+                    name: cookie.name,
+                    err,
+                });
+            }
+        }
+    }
+    async list() {
+        return (await this.context.cookies()).map((cookie) => ({
+            name: cookie.name,
+            value: cookie.value,
+            domain: cookie.domain,
+            path: cookie.path,
+            expires: cookie.expiry ?? -1,
+            httpOnly: cookie.httpOnly,
+            secure: cookie.secure,
+            sameSite: CAPITAL[cookie.sameSite] ?? "Lax",
+        }));
+    }
+    add(cookie) {
+        return this.context.addCookies([
+            {
+                name: cookie.name,
+                value: cookie.value,
+                domain: cookie.hostOnly ? cookie.domain : `.${cookie.domain}`,
+                path: cookie.path,
+                secure: cookie.secure,
+                httpOnly: cookie.httpOnly,
+                ...(cookie.sameSite !== undefined && {
+                    sameSite: cookie.sameSite.toLowerCase(),
+                }),
+                ...(cookie.expires !== undefined && { expiry: cookie.expires }),
+            },
+        ]);
+    }
+    /** The site deleted the cookie: the browser keeps it under the host or, for a domain cookie, the dotted domain */
+    async remove(cookie) {
+        for (const domain of [cookie.domain, `.${cookie.domain}`])
+            await this.context.clearCookies({
+                name: cookie.name,
+                domain,
+                path: cookie.path,
+            });
+    }
+}

package/dist/browser/index.d.ts

@@ -1,11 +1,13 @@
 export { Browser, type BrowserLaunchOptions, type ContextOptions, } from "./browser.js";
 export { BrowserContext } from "./browser-context.js";
 export { default as Page } from "./page.js";
+export type { default as Keyboard } from "./keyboard.js";
+export type { default as Mouse } from "./mouse.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 { UseError, UseUnsupportedError } from "./use-commands.js";
 export { findBrowser } from "./browser-finder.js";

package/dist/browser/index.js

@@ -6,5 +6,5 @@ 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 { UseError, UseUnsupportedError } from "./use-commands.js";
 export { findBrowser } from "./browser-finder.js";

package/dist/browser/keyboard.d.ts

@@ -0,0 +1,35 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/**
+ * The page's keyboard: real key input to whatever has focus. BiDi remembers which keys are down between calls,
+ * so `down("Shift")`, other input, then `up("Shift")` works, and a held `Shift` capitalizes `press("a")`.
+ */
+export default class Keyboard {
+    private connector;
+    private contextId;
+    private assertOpen;
+    constructor(connector: BiDiConnector, contextId: string, assertOpen: () => void);
+    /**
+     * Presses and releases a key, or a chord: modifiers (`Control`, `Shift`, `Alt`, `Meta`, `ControlOrMeta`) joined to
+     * the key by `+`. Named keys are `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `Space`, `Insert`, the arrows, `Home`, `End`,
+     * `PageUp`, `PageDown` and `F1` to `F12`; any other key is a single character. `delay` waits (ms) between press and release.
+     * @example
+     *  await page.keyboard.press("Control+a");
+     *  await page.keyboard.press("Shift+Tab");
+     */
+    press(key: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    /** Presses a key and keeps it down until `up`; a modifier stays in effect for the keys and clicks in between */
+    down(key: string): Promise<void>;
+    /** Releases a key pressed with `down`; a key that is not down is ignored */
+    up(key: string): Promise<void>;
+    /** Presses and releases one key per character of `text`, `delay` ms apart; a line break is Enter */
+    type(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    /**
+     * Inserts `text` at the caret of the focused element in one step, as a paste does: `input` fires, `keydown` and `keyup`
+     * do not. Does nothing when no editable element has focus.
+     */
+    insertText(text: string): Promise<void>;
+}

package/dist/browser/keyboard.js

@@ -0,0 +1,83 @@
+import { callFunction } from "../script/call-function.js";
+import { chordSteps, performKeys, textSteps } from "../locator/key-actions.js";
+import { parseKeyChord } from "../locator/key-map.js";
+/** Types into whatever has focus, replacing the selection: an input, a textarea or an editable element, also in a same-origin frame */
+const INSERT_TEXT = `(text) => {
+  let doc = document;
+  let el = doc.activeElement;
+  while (el && el.tagName === "IFRAME" && el.contentDocument && el.contentDocument.activeElement) {
+    doc = el.contentDocument;
+    el = doc.activeElement;
+  }
+  const selection = doc.getSelection();
+  // A freshly focused editable element can have no caret yet (Firefox): put it at the end
+  if (el && el.isContentEditable && selection && !el.contains(selection.anchorNode)) {
+    const range = doc.createRange();
+    range.selectNodeContents(el);
+    range.collapse(false);
+    selection.removeAllRanges();
+    selection.addRange(range);
+  }
+  doc.execCommand("insertText", false, text);
+}`;
+/** The key `down` and `up` take: one key, no chord, since a chord is several keys */
+function singleKey(key, method) {
+    const chord = parseKeyChord(key, method);
+    if (chord.modifiers.length > 0) {
+        throw new Error(`${method}(): "${key}" is a chord. Press its keys one at a time`);
+    }
+    return chord.key;
+}
+/**
+ * The page's keyboard: real key input to whatever has focus. BiDi remembers which keys are down between calls,
+ * so `down("Shift")`, other input, then `up("Shift")` works, and a held `Shift` capitalizes `press("a")`.
+ */
+export default class Keyboard {
+    constructor(connector, contextId, assertOpen) {
+        this.connector = connector;
+        this.contextId = contextId;
+        this.assertOpen = assertOpen;
+    }
+    /**
+     * Presses and releases a key, or a chord: modifiers (`Control`, `Shift`, `Alt`, `Meta`, `ControlOrMeta`) joined to
+     * the key by `+`. Named keys are `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`, `Space`, `Insert`, the arrows, `Home`, `End`,
+     * `PageUp`, `PageDown` and `F1` to `F12`; any other key is a single character. `delay` waits (ms) between press and release.
+     * @example
+     *  await page.keyboard.press("Control+a");
+     *  await page.keyboard.press("Shift+Tab");
+     */
+    async press(key, options) {
+        this.assertOpen();
+        const chord = parseKeyChord(key, "keyboard.press");
+        await performKeys(this.connector, this.contextId, chordSteps(chord, options?.delay));
+    }
+    /** Presses a key and keeps it down until `up`; a modifier stays in effect for the keys and clicks in between */
+    async down(key) {
+        this.assertOpen();
+        await performKeys(this.connector, this.contextId, [
+            { type: "keyDown", value: singleKey(key, "keyboard.down") },
+        ]);
+    }
+    /** Releases a key pressed with `down`; a key that is not down is ignored */
+    async up(key) {
+        this.assertOpen();
+        await performKeys(this.connector, this.contextId, [
+            { type: "keyUp", value: singleKey(key, "keyboard.up") },
+        ]);
+    }
+    /** Presses and releases one key per character of `text`, `delay` ms apart; a line break is Enter */
+    async type(text, options) {
+        this.assertOpen();
+        await performKeys(this.connector, this.contextId, textSteps(text, options?.delay));
+    }
+    /**
+     * Inserts `text` at the caret of the focused element in one step, as a paste does: `input` fires, `keydown` and `keyup`
+     * do not. Does nothing when no editable element has focus.
+     */
+    async insertText(text) {
+        this.assertOpen();
+        await callFunction(this.connector, this.contextId, INSERT_TEXT, [text], {
+            awaitPromise: false,
+        });
+    }
+}

package/dist/browser/mouse.d.ts

@@ -0,0 +1,42 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { type MouseButton } from "../locator/pointer-actions.js";
+/**
+ * The page's mouse: real pointer input at viewport coordinates (CSS pixels from the top left of the page's
+ * visible area). The pointer starts at 0, 0; `move` with `steps` runs from where the mouse last was through this object.
+ */
+export default class Mouse {
+    private connector;
+    private contextId;
+    private assertOpen;
+    private position;
+    constructor(connector: BiDiConnector, contextId: string, assertOpen: () => void);
+    /** Moves the pointer to `x`, `y` in a straight line of `steps` moves (default 1) */
+    move(x: number, y: number, options?: {
+        steps?: number;
+    }): Promise<void>;
+    /** Presses a button (default left) where the pointer is, and keeps it down until `up` */
+    down(options?: {
+        button?: MouseButton;
+    }): Promise<void>;
+    /** Releases a button pressed with `down` */
+    up(options?: {
+        button?: MouseButton;
+    }): Promise<void>;
+    /**
+     * Moves to `x`, `y` and clicks. `clickCount` presses in a row (2 is a double click), `delay` ms between each press and release.
+     * @example
+     *  await page.mouse.click(120, 80, { button: "right" });
+     */
+    click(x: number, y: number, options?: {
+        button?: MouseButton;
+        clickCount?: number;
+        delay?: number;
+    }): Promise<void>;
+    /** `click` with two presses */
+    dblclick(x: number, y: number, options?: {
+        button?: MouseButton;
+        delay?: number;
+    }): Promise<void>;
+    /** Turns the wheel where the pointer is by `deltaX` and `deltaY` pixels (positive is right and down) */
+    wheel(deltaX: number, deltaY: number): Promise<void>;
+}

package/dist/browser/mouse.js

@@ -0,0 +1,66 @@
+import { performPointer, wheelScroll, buttonCode, checkClick, clickSteps, moveSteps, } from "../locator/pointer-actions.js";
+/** Throws `mouse.method(): ...` unless every value is a finite number */
+function numbers(method, what, ...values) {
+    if (!values.every(Number.isFinite)) {
+        throw new Error(`mouse.${method}(): ${what} must be numbers`);
+    }
+}
+/**
+ * The page's mouse: real pointer input at viewport coordinates (CSS pixels from the top left of the page's
+ * visible area). The pointer starts at 0, 0; `move` with `steps` runs from where the mouse last was through this object.
+ */
+export default class Mouse {
+    constructor(connector, contextId, assertOpen) {
+        this.connector = connector;
+        this.contextId = contextId;
+        this.assertOpen = assertOpen;
+        this.position = { x: 0, y: 0 };
+    }
+    /** Moves the pointer to `x`, `y` in a straight line of `steps` moves (default 1) */
+    async move(x, y, options) {
+        this.assertOpen();
+        numbers("move", "x and y", x, y);
+        const to = { x, y };
+        await performPointer(this.connector, this.contextId, moveSteps(this.position, to, options?.steps));
+        this.position = to;
+    }
+    /** Presses a button (default left) where the pointer is, and keeps it down until `up` */
+    async down(options) {
+        this.assertOpen();
+        await performPointer(this.connector, this.contextId, [
+            {
+                type: "pointerDown",
+                button: buttonCode(options?.button, "mouse.down"),
+            },
+        ]);
+    }
+    /** Releases a button pressed with `down` */
+    async up(options) {
+        this.assertOpen();
+        await performPointer(this.connector, this.contextId, [
+            { type: "pointerUp", button: buttonCode(options?.button, "mouse.up") },
+        ]);
+    }
+    /**
+     * Moves to `x`, `y` and clicks. `clickCount` presses in a row (2 is a double click), `delay` ms between each press and release.
+     * @example
+     *  await page.mouse.click(120, 80, { button: "right" });
+     */
+    async click(x, y, options) {
+        this.assertOpen();
+        numbers("click", "x and y", x, y);
+        checkClick(options ?? {}, "mouse.click");
+        await performPointer(this.connector, this.contextId, clickSteps({ x, y }, options, "mouse.click"));
+        this.position = { x, y };
+    }
+    /** `click` with two presses */
+    async dblclick(x, y, options) {
+        await this.click(x, y, { ...options, clickCount: 2 });
+    }
+    /** Turns the wheel where the pointer is by `deltaX` and `deltaY` pixels (positive is right and down) */
+    async wheel(deltaX, deltaY) {
+        this.assertOpen();
+        numbers("wheel", "deltaX and deltaY", deltaX, deltaY);
+        await wheelScroll(this.connector, this.contextId, this.position, deltaX, deltaY);
+    }
+}

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

@@ -3,3 +3,7 @@ import type { BiDiConnector } from "../transport/bidi-connection.js";
 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>;
+/** The URL of the document now */
+export declare function readUrl(connector: BiDiConnector, context: string): Promise<string>;
+/** The title of the document now */
+export declare function readTitle(connector: BiDiConnector, context: string): Promise<string>;

package/dist/browser/page-content.js

@@ -41,3 +41,15 @@ export function writeContent(connector, context, html, state, timeout) {
         timeout,
     ]);
 }
+/** The URL of the document now */
+export function readUrl(connector, context) {
+    return callFunction(connector, context, "() => location.href", [], {
+        awaitPromise: false,
+    });
+}
+/** The title of the document now */
+export function readTitle(connector, context) {
+    return callFunction(connector, context, "() => document.title", [], {
+        awaitPromise: false,
+    });
+}