@itmetsam/samurai-framework 0.21.4 → 0.22.0

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/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-navigation.d.ts

@@ -29,8 +29,6 @@ export interface NavigationDeps {
         timeout: number;
     }): Promise<void>;
 }
-/** Resolves a slash-led `url` against `base`; any other URL is returned as given */
-export declare function resolveRelativeURL(url: string, base: string): string;
 /** Navigating one page: `goto`, `navigateTo`, `reload` and the wait for a load state */
 export declare class PageNavigation {
     private connector;

package/dist/browser/page-navigation.js

@@ -1,4 +1,5 @@
 import logger from "../logger/index.js";
+import { RELATIVE_URL, resolveRelativeURL } from "../config/base-url.js";
 import { peekRunSettings } from "../config/run-settings.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { UnsupportedOperationError } from "../transport/unsupported.js";
@@ -6,12 +7,6 @@ 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 */
-export function resolveRelativeURL(url, base) {
-    return RELATIVE_URL.test(url) ? new URL(url, base).href : url;
-}
 /** Navigating one page: `goto`, `navigateTo`, `reload` and the wait for a load state */
 export class PageNavigation {
     constructor(connector, contextId, deps) {

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;

package/dist/browser/page.d.ts

@@ -1,3 +1,4 @@
+import type { APIRequestContext } from "../request/api-request-context.js";
 import Locator from "../locator/locator.js";
 import type { FilterOptions } from "../locator/filter-step.js";
 import type { RoleOptions } from "../locator/role-locator.js";
@@ -7,7 +8,7 @@ import type { Recorder, RecorderOptions } from "../recorder/recorder.js";
 import { ContextTree } from "./context-tree.js";
 import type { BrowserContext } from "./browser-context.js";
 import { type PdfOptions } from "./pdf.js";
-import { type EmulationOptions } from "./emulation.js";
+import type { RuntimeUseOptions } from "../types/use.js";
 import type { Download } from "./download.js";
 import type { FileChooser } from "./file-chooser.js";
 import { type ScreenshotOptions } from "./screenshot.js";
@@ -18,6 +19,8 @@ import { Response } from "../network/response.js";
 import type { NetworkMatch } from "../network/network-wait.js";
 import type { UrlPattern } from "../network/url-match.js";
 import type { LoadState, NavigateOptions, NavigationResult } from "./page-navigation.js";
+import Keyboard from "./keyboard.js";
+import Mouse from "./mouse.js";
 import { type PageEventName, type PageEvents, type WaitableEventName, type WaitForEventOptions, type WaitOptions } from "./page-events.js";
 export type { PageEventName, WaitableEventName, WaitForEventOptions, WaitOptions, };
 import { type PageSettings, type ReadinessState } from "./page-settings.js";
@@ -36,6 +39,10 @@ export default class Page {
     private initScripts;
     private pageConfig;
     private locators;
+    /** Real key input to whatever has focus: `press` (also chords such as `Control+a`), `down`, `up`, `type`, `insertText` */
+    readonly keyboard: Keyboard;
+    /** Real pointer input at viewport coordinates: `move`, `down`, `up`, `click`, `dblclick`, `wheel` */
+    readonly mouse: Mouse;
     private pageEvents;
     private documents;
     private nav;
@@ -48,6 +55,8 @@ export default class Page {
     private transfers;
     private evidence;
     private knownViewport;
+    /** Chrome's phone layout is on (`setMobileLayout`): viewport changes keep it */
+    private mobile;
     /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
     constructor(biDiConnector: BiDiConnector, contextId: string, settings?: PageSettings);
     /** The BiDi browsing context id of this page's top-level context */
@@ -178,6 +187,8 @@ export default class Page {
      *  await page.setViewport({ width: 390, height: 844, devicePixelRatio: 3 });
      */
     setViewport(viewport: Viewport | null): Promise<void>;
+    /** @internal Chrome: lays this page out like a phone from now on (`use.isMobile`), including the size it has now */
+    setMobileLayout(): Promise<void>;
     /** Playwright's name for `setViewport` */
     setViewportSize(size: Viewport): Promise<void>;
     /**
@@ -209,20 +220,23 @@ export default class Page {
     pdf(options?: PdfOptions): Promise<Buffer>;
     /** The browser context (cookies, storage) this page belongs to */
     context(): BrowserContext;
+    /** Makes HTTP requests from the test with this page's cookies; the same as `page.context().request` */
+    get request(): APIRequestContext;
     /** @internal Called when the page is opened in a context */
     setContext(context: BrowserContext): void;
     /** @internal Marks the page closed after its tab is gone (its context was removed) and releases what it registered */
     detach(): Promise<void>;
     /**
-     * Pretends things about this page only: locale, timezone, user agent, geolocation, offline, orientation, screen
-     * size. It wins over what the page's context says; `null` puts the real (or the context's) value back.
+     * Changes the `use` options that can change while the browser runs for this page only: locale, timezone, user
+     * agent, geolocation, offline, orientation, screen, hasTouch, javaScriptEnabled. It wins over what the page's
+     * context says; `null` puts the real (or the context's) value back. Same options as `test.use()`, applied now.
      * @example
-     *  await page.emulate({ locale: "nl-NL", offline: true });
+     *  await page.use({ locale: "nl-NL", offline: true });
      */
-    emulate(options: EmulationOptions): Promise<void>;
+    use(options: RuntimeUseOptions): Promise<void>;
     /**
      * Grants a browser permission ("geolocation", "notifications", "camera", …) to the origin this page is on,
-     * or to `options.origin`. Geolocation emulation only answers once this is granted.
+     * or to `options.origin`. A geolocation override only answers once this is granted.
      */
     grantPermission(name: string, options?: {
         origin?: string;

package/dist/browser/page.js

@@ -7,7 +7,7 @@ import { DEFAULT_VIEWPORT } from "../config/defaults.js";
 import logger from "../logger/index.js";
 import { ContextTree } from "./context-tree.js";
 import { printPdf } from "./pdf.js";
-import { applyEmulation } from "./emulation.js";
+import { applyUse } from "./use-commands.js";
 import { takeScreenshot, writeOutput, } from "./screenshot.js";
 import { Evidence } from "./evidence.js";
 import { PageLogs } from "./page-logs.js";
@@ -22,6 +22,8 @@ import { PageTransfers } from "./page-transfers.js";
 import { InitScripts } from "./init-script.js";
 import { grantPermission } from "./page-permissions.js";
 import { PageLocators } from "./page-locators.js";
+import Keyboard from "./keyboard.js";
+import Mouse from "./mouse.js";
 import { sourcesFor, waitForPageEvent, } from "./page-events.js";
 import { PageConfig, } from "./page-settings.js";
 import { applyViewport } from "./viewport.js";
@@ -40,11 +42,15 @@ export default class Page {
         this.errorsAllowed = false;
         this.isClosed = false;
         this.knownViewport = null;
+        /** Chrome's phone layout is on (`setMobileLayout`): viewport changes keep it */
+        this.mobile = false;
         this.biDiConnector = biDiConnector;
         this.id = contextId;
         this.pageConfig = new PageConfig(settings);
         this.helperRealm = new HelperRealm(biDiConnector, contextId);
         this.locators = new PageLocators(biDiConnector, contextId, this.helperRealm, this.pageConfig, () => this.assertOpen());
+        this.keyboard = new Keyboard(biDiConnector, contextId, () => this.assertOpen());
+        this.mouse = new Mouse(biDiConnector, contextId, () => this.assertOpen());
         this.documents = new DocumentWatcher(biDiConnector, contextId);
         this.net = new PageNetwork(biDiConnector, contextId, {
             config: this.pageConfig,
@@ -274,12 +280,17 @@ export default class Page {
      */
     async setViewport(viewport) {
         this.assertOpen();
-        await applyViewport(this.biDiConnector, this.id, viewport);
+        await applyViewport(this.biDiConnector, this.id, viewport, this.mobile);
         this.knownViewport = viewport && {
             width: viewport.width,
             height: viewport.height,
         };
     }
+    /** @internal Chrome: lays this page out like a phone from now on (`use.isMobile`), including the size it has now */
+    async setMobileLayout() {
+        this.mobile = true;
+        await this.setViewport(this.knownViewport);
+    }
     /** Playwright's name for `setViewport` */
     setViewportSize(size) {
         return this.setViewport(size);
@@ -345,6 +356,10 @@ export default class Page {
             throw new Error("this page has no browser context: open it with browser.newPage() or context.newPage()");
         return this.browserContext;
     }
+    /** Makes HTTP requests from the test with this page's cookies; the same as `page.context().request` */
+    get request() {
+        return this.context().request;
+    }
     /** @internal Called when the page is opened in a context */
     setContext(context) {
         this.browserContext = context;
@@ -355,18 +370,19 @@ export default class Page {
         await this.dispose().catch((err) => logger.debug("Releasing a detached page failed", { err }));
     }
     /**
-     * Pretends things about this page only: locale, timezone, user agent, geolocation, offline, orientation, screen
-     * size. It wins over what the page's context says; `null` puts the real (or the context's) value back.
+     * Changes the `use` options that can change while the browser runs for this page only: locale, timezone, user
+     * agent, geolocation, offline, orientation, screen, hasTouch, javaScriptEnabled. It wins over what the page's
+     * context says; `null` puts the real (or the context's) value back. Same options as `test.use()`, applied now.
      * @example
-     *  await page.emulate({ locale: "nl-NL", offline: true });
+     *  await page.use({ locale: "nl-NL", offline: true });
      */
-    async emulate(options) {
+    async use(options) {
         this.assertOpen();
-        await applyEmulation(this.biDiConnector, { contexts: [this.id] }, options);
+        await applyUse(this.biDiConnector, { contexts: [this.id] }, options);
     }
     /**
      * Grants a browser permission ("geolocation", "notifications", "camera", …) to the origin this page is on,
-     * or to `options.origin`. Geolocation emulation only answers once this is granted.
+     * or to `options.origin`. A geolocation override only answers once this is granted.
      */
     async grantPermission(name, options = {}) {
         this.assertOpen();

package/dist/browser/session-capabilities.d.ts

@@ -1,3 +1,4 @@
+import type { UseOptions } from "../types/use.js";
 /**
  * Sent with session.new (Firefox) or as capabilities of the chromedriver session (Chrome). With "ignore" the browser
  * leaves a JavaScript dialog open and reports it (`browsingContext.userPromptOpened`), so the framework decides how
@@ -10,3 +11,12 @@ export declare const SESSION_CAPABILITIES: {
         };
     };
 };
+/** The session capabilities for a launch: the ones above, plus the `use` option that has to be set when the browser starts */
+export declare function sessionCapabilities(use?: Pick<UseOptions, "acceptInsecureCerts">): {
+    alwaysMatch: {
+        acceptInsecureCerts?: boolean | undefined;
+        unhandledPromptBehavior: {
+            default: string;
+        };
+    };
+};

package/dist/browser/session-capabilities.js

@@ -6,3 +6,14 @@
 export const SESSION_CAPABILITIES = {
     alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } },
 };
+/** The session capabilities for a launch: the ones above, plus the `use` option that has to be set when the browser starts */
+export function sessionCapabilities(use) {
+    return {
+        alwaysMatch: {
+            ...SESSION_CAPABILITIES.alwaysMatch,
+            ...(use?.acceptInsecureCerts !== undefined && {
+                acceptInsecureCerts: use.acceptInsecureCerts,
+            }),
+        },
+    };
+}

package/dist/browser/session.d.ts

@@ -1,10 +1,11 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { UseOptions } from "../types/use.js";
 /** session.new got no reply in time */
 export declare class BrowserStartTimeoutError extends Error {
     constructor(label: string, timeout: number);
 }
 /** Sends session.new with its own, longer timeout; `label` names the browser in the timeout error */
-export declare function startSession(connector: Pick<BiDiConnector, "send">, label: string, commandTimeout: number | undefined): Promise<void>;
+export declare function startSession(connector: Pick<BiDiConnector, "send">, label: string, commandTimeout: number | undefined, use?: UseOptions): Promise<void>;
 /**
  * Stops what a failed launch started. A browser left running holds the profile (the next launch
  * fails with "already open") and keeps the test process alive.

package/dist/browser/session.js

@@ -1,6 +1,6 @@
 import { DEFAULT_COMMAND_TIMEOUT } from "../config/defaults.js";
 import { BiDiError } from "../transport/bidi-error.js";
-import { SESSION_CAPABILITIES } from "./session-capabilities.js";
+import { sessionCapabilities } from "./session-capabilities.js";
 /** session.new waits at least this long (ms): the first start after an install can take a while (macOS checks the new app) */
 const SESSION_START_TIMEOUT = 120_000;
 /** session.new got no reply in time */
@@ -11,10 +11,10 @@ export class BrowserStartTimeoutError extends Error {
     }
 }
 /** Sends session.new with its own, longer timeout; `label` names the browser in the timeout error */
-export async function startSession(connector, label, commandTimeout) {
+export async function startSession(connector, label, commandTimeout, use) {
     const timeout = Math.max(commandTimeout ?? DEFAULT_COMMAND_TIMEOUT, SESSION_START_TIMEOUT);
     try {
-        await connector.send("session.new", { capabilities: SESSION_CAPABILITIES }, { timeout });
+        await connector.send("session.new", { capabilities: sessionCapabilities(use) }, { timeout });
     }
     catch (err) {
         if (err instanceof BiDiError && err.code === "timeout")

package/dist/browser/storage-state.d.ts

@@ -0,0 +1,4 @@
+import type { StorageState } from "../types/use.js";
+import type { CookieInput } from "./browser-context.js";
+/** The state's cookies as `context.addCookies()` takes them; `expires` of -1 (or none) is a session cookie */
+export declare function cookiesOf(state: StorageState): CookieInput[];

package/dist/browser/storage-state.js

@@ -0,0 +1,17 @@
+const SAME_SITE = { Strict: "strict", Lax: "lax", None: "none" };
+/** The state's cookies as `context.addCookies()` takes them; `expires` of -1 (or none) is a session cookie */
+export function cookiesOf(state) {
+    return (state.cookies ?? []).map((cookie) => ({
+        name: cookie.name,
+        value: cookie.value,
+        domain: cookie.domain,
+        ...(cookie.path !== undefined && { path: cookie.path }),
+        ...(cookie.expires !== undefined &&
+            cookie.expires > 0 && { expiry: cookie.expires }),
+        ...(cookie.httpOnly !== undefined && { httpOnly: cookie.httpOnly }),
+        ...(cookie.secure !== undefined && { secure: cookie.secure }),
+        ...(cookie.sameSite !== undefined && {
+            sameSite: SAME_SITE[cookie.sameSite],
+        }),
+    }));
+}

package/dist/browser/use-applier.d.ts

@@ -0,0 +1,38 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { GroupUse } from "../types/config.js";
+import type { BrowserContext } from "./browser-context.js";
+import type Page from "./page.js";
+/** The `use` options a browser applies to its contexts and pages, by what each browser can do (see the wiki's support matrix) */
+export declare class UseApplier {
+    private readonly connector;
+    private readonly options;
+    private readonly state;
+    private readonly chrome;
+    constructor(connector: BiDiConnector, browserName: SupportedBrowser, options: GroupUse, projectDir: string);
+    /** What new contexts accept unless they are told otherwise */
+    get acceptInsecureCerts(): boolean | undefined;
+    /** Whether pages are laid out like a phone: Chrome only */
+    get isMobile(): boolean;
+    /** Whether pages have touch input: Chrome only */
+    get hasTouch(): boolean;
+    /**
+     * Sets up a context: the run-time options (`page.use()`'s) through BiDi, the extra headers, then the storage state.
+     * An option the browser does not support is skipped with a one-time warning (`page.use()` throws instead).
+     * Firefox gets JavaScript and the colour scheme when it starts (a profile setting).
+     */
+    context(context: BrowserContext): Promise<void>;
+    /**
+     * Sets up a page of a context this applier set up: Chrome's phone layout and colour scheme (CDP, so per page), and
+     * the viewport a group asked for (after the phone layout, so the size keeps it)
+     */
+    page(page: Page): Promise<void>;
+    /**
+     * The declared options that go through BiDi. Left out: those that are not set (or `null`), the ones that change
+     * nothing (`offline: false`), Chrome-only touch on Firefox (warned once in the constructor) and JavaScript on
+     * Firefox (a profile setting).
+     */
+    private startUp;
+    private chromePage;
+    private restore;
+}

package/dist/browser/use-applier.js

@@ -0,0 +1,121 @@
+import { warnOnce } from "../logger/warn-once.js";
+import { cdpSend, sendRaw } from "./cdp.js";
+import { applyUse, RUNTIME_OPTIONS } from "./use-commands.js";
+import { cookiesOf } from "./storage-state.js";
+import { loadStorageState } from "../config/storage-state-file.js";
+/** The `use` options a browser applies to its contexts and pages, by what each browser can do (see the wiki's support matrix) */
+export class UseApplier {
+    constructor(connector, browserName, options, projectDir) {
+        this.connector = connector;
+        this.options = options;
+        this.chrome = browserName === "chrome";
+        // Read now: a wrong path fails the test before it starts
+        if (options.storageState !== undefined)
+            this.state = loadStorageState(options.storageState, projectDir);
+        if (!this.chrome) {
+            if (options.isMobile)
+                warnOnce("use.isMobile", "use.isMobile only works on Chrome: it is ignored on Firefox");
+            if (options.hasTouch)
+                warnOnce("use.hasTouch", "use.hasTouch only works on Chrome: it is ignored on Firefox");
+        }
+    }
+    /** What new contexts accept unless they are told otherwise */
+    get acceptInsecureCerts() {
+        return this.options.acceptInsecureCerts;
+    }
+    /** Whether pages are laid out like a phone: Chrome only */
+    get isMobile() {
+        return this.chrome && this.options.isMobile === true;
+    }
+    /** Whether pages have touch input: Chrome only */
+    get hasTouch() {
+        return this.chrome && this.options.hasTouch === true;
+    }
+    /**
+     * Sets up a context: the run-time options (`page.use()`'s) through BiDi, the extra headers, then the storage state.
+     * An option the browser does not support is skipped with a one-time warning (`page.use()` throws instead).
+     * Firefox gets JavaScript and the colour scheme when it starts (a profile setting).
+     */
+    async context(context) {
+        const { options } = this;
+        await applyUse(this.connector, { userContexts: [context.id] }, this.startUp(), (option) => warnOnce(`use.${option}`, `use.${option} is not supported by this browser: it is ignored`));
+        context.setRequestDefaults({
+            extraHTTPHeaders: options.extraHTTPHeaders,
+            ignoreHTTPSErrors: options.acceptInsecureCerts,
+        });
+        if (options.extraHTTPHeaders)
+            await sendRaw(this.connector, "network.setExtraHeaders", {
+                headers: Object.entries(options.extraHTTPHeaders).map(([name, value]) => ({ name, value: { type: "string", value } })),
+                userContexts: [context.id],
+            });
+        if (this.state)
+            await this.restore(context, this.state);
+    }
+    /**
+     * Sets up a page of a context this applier set up: Chrome's phone layout and colour scheme (CDP, so per page), and
+     * the viewport a group asked for (after the phone layout, so the size keeps it)
+     */
+    async page(page) {
+        if (this.chrome)
+            await this.chromePage(page);
+        if (this.options.viewport !== undefined)
+            await page.setViewport(this.options.viewport);
+    }
+    /**
+     * The declared options that go through BiDi. Left out: those that are not set (or `null`), the ones that change
+     * nothing (`offline: false`), Chrome-only touch on Firefox (warned once in the constructor) and JavaScript on
+     * Firefox (a profile setting).
+     */
+    startUp() {
+        const { options } = this;
+        const wanted = {};
+        for (const name of RUNTIME_OPTIONS) {
+            const value = options[name];
+            if (value === undefined || value === null)
+                continue;
+            if (name === "offline" && value === false)
+                continue;
+            if (name === "hasTouch" && !this.hasTouch)
+                continue;
+            if (name === "javaScriptEnabled" && !(this.chrome && value === false))
+                continue;
+            wanted[name] = value;
+        }
+        return wanted;
+    }
+    async chromePage(page) {
+        if (this.isMobile)
+            await page.setMobileLayout();
+        if (this.options.colorScheme !== undefined)
+            await cdpSend(this.connector, page.contextId, "Emulation.setEmulatedMedia", {
+                features: [
+                    { name: "prefers-color-scheme", value: this.options.colorScheme },
+                ],
+            });
+    }
+    async restore(context, state) {
+        const cookies = cookiesOf(state);
+        if (cookies.length > 0)
+            await context.addCookies(cookies);
+        for (const { origin, localStorage } of state.origins ?? []) {
+            if (localStorage.length === 0)
+                continue;
+            await writeLocalStorage(context, origin, localStorage);
+        }
+    }
+}
+/**
+ * Local storage belongs to an origin, so the browser has to be on it: a scratch tab opens the origin (the request is
+ * answered here, it never reaches the network), writes the entries and closes again.
+ */
+async function writeLocalStorage(context, origin, entries) {
+    const tab = await context.newPage();
+    try {
+        await tab.route(`${origin}/**`, (route) => route.fulfill({ contentType: "text/html", body: "<!doctype html>" }));
+        await tab.navigateTo(`${origin}/`);
+        await tab.evaluate((items) => items.forEach(({ name, value }) => localStorage.setItem(name, value)), entries);
+    }
+    finally {
+        await tab.close();
+    }
+}