@itmetsam/samurai-framework 0.21.4 → 0.21.5

package/dist/api.d.ts

@@ -2,5 +2,7 @@ export { test, describe, beforeEach, afterEach, beforeAll, afterAll, } from "./r
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/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, UseOptions, } from "./types/use.js";
 export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/browser/browser.d.ts

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

package/dist/browser/browser.js

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

package/dist/browser/cdp.d.ts

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

package/dist/browser/cdp.js

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

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

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

package/dist/browser/chrome-launch.js

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

package/dist/browser/index.d.ts

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

package/dist/browser/index.js

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

package/dist/browser/launch-firefox.js

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

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

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

package/dist/browser/launch-flags.js

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

package/dist/browser/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

@@ -48,6 +48,8 @@ export default class Page {
     private transfers;
     private evidence;
     private knownViewport;
+    /** Chrome's phone layout is on (`emulateMobile`): 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 +180,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 */
+    emulateMobile(): Promise<void>;
     /** Playwright's name for `setViewport` */
     setViewportSize(size: Viewport): Promise<void>;
     /**

package/dist/browser/page.js

@@ -40,6 +40,8 @@ export default class Page {
         this.errorsAllowed = false;
         this.isClosed = false;
         this.knownViewport = null;
+        /** Chrome's phone layout is on (`emulateMobile`): viewport changes keep it */
+        this.mobile = false;
         this.biDiConnector = biDiConnector;
         this.id = contextId;
         this.pageConfig = new PageConfig(settings);
@@ -274,12 +276,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 emulateMobile() {
+        this.mobile = true;
+        await this.setViewport(this.knownViewport);
+    }
     /** Playwright's name for `setViewport` */
     setViewportSize(size) {
         return this.setViewport(size);

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,6 @@
+import type { StorageState } from "../types/use.js";
+import type { CookieInput } from "./browser-context.js";
+/** The state itself, or the JSON file (relative to `baseDir`) that holds it. Throws `use(): what is wrong`. */
+export declare function loadStorageState(source: string | StorageState, baseDir: string): StorageState;
+/** 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,37 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { checkStorageStateObject } from "../config/use-options.js";
+/** The state itself, or the JSON file (relative to `baseDir`) that holds it. Throws `use(): what is wrong`. */
+export function loadStorageState(source, baseDir) {
+    if (typeof source !== "string")
+        return source;
+    const file = path.resolve(baseDir, source);
+    let state;
+    try {
+        state = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`use(): storageState file ${JSON.stringify(source)} could not be read: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof state !== "object" || state === null || Array.isArray(state))
+        throw new Error(`use(): storageState file ${JSON.stringify(source)} must hold an object`);
+    checkStorageStateObject(state);
+    return state;
+}
+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,27 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { UseOptions } from "../types/use.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: UseOptions, 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: locale, timezone, user agent, touch and JavaScript through BiDi emulation, the extra headers,
+     * then the storage state. 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) */
+    page(page: Page): Promise<void>;
+    private restore;
+}

package/dist/browser/use-applier.js

@@ -0,0 +1,94 @@
+import { warnOnce } from "../logger/warn-once.js";
+import { cdpSend, sendRaw } from "./cdp.js";
+import { cookiesOf, loadStorageState } from "./storage-state.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: locale, timezone, user agent, touch and JavaScript through BiDi emulation, the extra headers,
+     * then the storage state. Firefox gets JavaScript and the colour scheme when it starts (a profile setting).
+     */
+    async context(context) {
+        const { options } = this;
+        const emulation = {
+            ...(options.locale !== undefined && { locale: options.locale }),
+            ...(options.timezoneId !== undefined && { timezone: options.timezoneId }),
+            ...(options.userAgent !== undefined && { userAgent: options.userAgent }),
+            ...(this.hasTouch && { touch: 1 }),
+            ...(this.chrome &&
+                options.javaScriptEnabled === false && { javaScriptEnabled: false }),
+        };
+        if (Object.keys(emulation).length > 0)
+            await context.emulate(emulation);
+        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) */
+    async page(page) {
+        if (!this.chrome)
+            return;
+        if (this.isMobile)
+            await page.emulateMobile();
+        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();
+    }
+}

package/dist/browser/viewport.d.ts

@@ -9,6 +9,7 @@ export interface Viewport {
 export declare function validateViewport({ width, height, devicePixelRatio, }: Viewport): void;
 /**
  * Gives the context this size (and optionally this device pixel ratio); `null` puts the browser's own size back
- * and waits until the page has really got it.
+ * and waits until the page has really got it. A `mobile` page (Chrome's phone layout, `use.isMobile`) is sized
+ * through CDP, as BiDi's `setViewport` would turn the phone layout off again.
  */
-export declare function applyViewport(connector: BiDiConnector, context: string, viewport: Viewport | null): Promise<void>;
+export declare function applyViewport(connector: BiDiConnector, context: string, viewport: Viewport | null, mobile?: boolean): Promise<void>;

package/dist/browser/viewport.js

@@ -1,4 +1,5 @@
 import { callFunction } from "../script/call-function.js";
+import { cdpSend } from "./cdp.js";
 /** Time (ms) without a `resize` event after which a viewport reset counts as done */
 const RESIZE_QUIET_TIME = 50;
 /** Time (ms) a viewport reset waits for a `resize` event that may never come (the size did not change) */
@@ -20,9 +21,21 @@ export function validateViewport({ width, height, devicePixelRatio, }) {
 }
 /**
  * Gives the context this size (and optionally this device pixel ratio); `null` puts the browser's own size back
- * and waits until the page has really got it.
+ * and waits until the page has really got it. A `mobile` page (Chrome's phone layout, `use.isMobile`) is sized
+ * through CDP, as BiDi's `setViewport` would turn the phone layout off again.
  */
-export async function applyViewport(connector, context, viewport) {
+export async function applyViewport(connector, context, viewport, mobile = false) {
+    if (mobile) {
+        if (viewport)
+            validateViewport(viewport);
+        await cdpSend(connector, context, "Emulation.setDeviceMetricsOverride", {
+            width: viewport?.width ?? 0,
+            height: viewport?.height ?? 0,
+            deviceScaleFactor: viewport ? (viewport.devicePixelRatio ?? 1) : 0,
+            mobile: true,
+        });
+        return;
+    }
     if (viewport === null) {
         await untilResized(connector, context, () => connector.send("browsingContext.setViewport", {
             context,