@itmetsam/samurai-framework 0.21.4 → 0.22.0

package/dist/api.d.ts

@@ -1,6 +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, TestDetails, TestFixtures, TestOptions, TestOutputs, } from "./types/test.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, RuntimeUseOptions, UseOptions, } 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,14 +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 { 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;
@@ -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: 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,8 @@ 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";
 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,27 +189,34 @@ export class Browser {
      *  const page = await alice.newPage();
      */
     async newContext(options = {}) {
-        const { acceptInsecureCerts, unhandledPromptBehavior, ...emulation } = options;
+        const { unhandledPromptBehavior, ...settings } = options;
+        const insecure = options.acceptInsecureCerts ?? this.use?.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", {
-            ...(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(settings).length > 0) {
             try {
-                await context.emulate(emulation);
+                await this.use?.context(context);
+                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/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),
@@ -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,6 +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 { EmulationUnsupportedError } from "./emulation.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 { UseError, UseUnsupportedError } from "./use-commands.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 { EmulationUnsupportedError } from "./emulation.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 { 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,
+        });
+    }
+}