@itmetsam/samurai-framework 0.21.3 → 0.21.5

package/dist/browser/page.d.ts

@@ -25,6 +25,7 @@ export type { PageSettings, ReadinessState };
 import { type Viewport } from "./viewport.js";
 import type { PreloadHandle } from "../script/preload.js";
 import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { type PageFunction } from "../script/call-function.js";
 import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
 export type { LoadState, NavigateOptions, NavigationResult };
 export default class Page {
@@ -46,6 +47,9 @@ export default class Page {
     private browserContext;
     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 */
@@ -61,7 +65,8 @@ export default class Page {
     /**
      * Makes this page's locators strict (or not): an action or read on a locator matching several elements then
      * throws `name(): strict mode violation, N elements match ...` instead of using the first. `undefined` goes back
-     * to config `use.strictSelectors` (off unless set). Applies to locators already made, too
+     * to config `use.strictSelectors` (off unless set). Applies to locators made afterwards and to earlier ones that have not
+     * run an action or read yet: a locator keeps the answer it got at its first one
      */
     setStrictSelectors(enabled: boolean | undefined): void;
     /** Locates elements with a CSS selector */
@@ -133,14 +138,60 @@ export default class Page {
     goForward(): Promise<boolean>;
     /** The URL of the page now */
     url(): Promise<string>;
+    /**
+     * Waits until the URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then until the page reached `waitUntil` (default "load"). Also sees `pushState`.
+     * @example
+     *  await page.getByRole("button", { name: "Sign in" }).click();
+     *  await page.waitForURL("**\/dashboard");
+     */
+    waitForURL(url: UrlPattern | ((url: URL) => boolean), options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
+    /** The markup of the document now, doctype included */
+    content(): Promise<string>;
+    /**
+     * Replaces the document with `html` and waits for `waitUntil` (default "load"). Scripts and styles in it run and apply;
+     * the page keeps its URL and origin (it is not a `data:` page).
+     * @example
+     *  await page.setContent("<button>Go</button><script>document.title = 'x'</script>");
+     */
+    setContent(html: string, options?: {
+        timeout?: number;
+        waitUntil?: LoadState;
+    }): Promise<void>;
     /** The title of the document now */
     title(): Promise<string>;
+    /**
+     * Runs `fn` in the page, with `arg` as its only argument, and returns the result (a promise is awaited). `fn` is a function,
+     * the source of one (`"async () => ..."`), or any other string, which is an expression (`"document.title"`; it takes no argument).
+     * Values come back as plain JavaScript: Date, Map, Set, RegExp, BigInt, NaN, undefined, nested objects and arrays;
+     * an element as an `ElementHandle`; what cannot be copied (a function, window, error, promise) as a `RemoteObject` with its `type`.
+     * The page's own error message is kept (`ScriptError`). A function written under tsx must not contain named inner functions
+     * (the transpiler adds a `__name` helper the page lacks); a string always works.
+     * @example
+     *  const count = await page.evaluate((min) => document.querySelectorAll("li").length > min, 3);
+     */
+    evaluate<R = unknown, A = unknown>(fn: PageFunction<[A], R>, arg?: A): Promise<R>;
     /**
      * Sets the size of the viewport (and, optionally, the device pixel ratio); `null` puts the browser's own size back.
      * @example
      *  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>;
+    /**
+     * The size this page was last given (`setViewport`, `setViewportSize`, or the default from config `use.viewport` when the
+     * browser opened it), read at once; null before one is known, after `setViewport(null)` and when config turns the viewport off.
+     */
+    viewportSize(): {
+        width: number;
+        height: number;
+    } | null;
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     applyDefaultViewport(): Promise<void>;
     /**

package/dist/browser/page.js

@@ -28,6 +28,8 @@ import { applyViewport } from "./viewport.js";
 import { HelperRealm } from "../locator/helper-realm.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { callFunction } from "../script/call-function.js";
+import { readContent } from "./page-content.js";
+import { evaluateInPage } from "./page-evaluate.js";
 export default class Page {
     /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
     constructor(biDiConnector, contextId, settings) {
@@ -37,6 +39,9 @@ export default class Page {
         this.lazyLogs = new Lazy();
         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);
@@ -84,7 +89,8 @@ export default class Page {
     /**
      * Makes this page's locators strict (or not): an action or read on a locator matching several elements then
      * throws `name(): strict mode violation, N elements match ...` instead of using the first. `undefined` goes back
-     * to config `use.strictSelectors` (off unless set). Applies to locators already made, too
+     * to config `use.strictSelectors` (off unless set). Applies to locators made afterwards and to earlier ones that have not
+     * run an action or read yet: a locator keeps the answer it got at its first one
      */
     setStrictSelectors(enabled) {
         this.locators.setStrictSelectors(enabled);
@@ -220,11 +226,49 @@ export default class Page {
         this.assertOpen();
         return callFunction(this.biDiConnector, this.id, "() => location.href", [], { awaitPromise: false });
     }
+    /**
+     * Waits until the URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
+     * a function gets it as a `URL`), then until the page reached `waitUntil` (default "load"). Also sees `pushState`.
+     * @example
+     *  await page.getByRole("button", { name: "Sign in" }).click();
+     *  await page.waitForURL("**\/dashboard");
+     */
+    waitForURL(url, options) {
+        return this.nav.waitForURL(url, options);
+    }
+    /** The markup of the document now, doctype included */
+    async content() {
+        this.assertOpen();
+        return readContent(this.biDiConnector, this.id);
+    }
+    /**
+     * Replaces the document with `html` and waits for `waitUntil` (default "load"). Scripts and styles in it run and apply;
+     * the page keeps its URL and origin (it is not a `data:` page).
+     * @example
+     *  await page.setContent("<button>Go</button><script>document.title = 'x'</script>");
+     */
+    async setContent(html, options) {
+        return this.nav.setContent(html, options);
+    }
     /** The title of the document now */
     async title() {
         this.assertOpen();
         return callFunction(this.biDiConnector, this.id, "() => document.title", [], { awaitPromise: false });
     }
+    /**
+     * Runs `fn` in the page, with `arg` as its only argument, and returns the result (a promise is awaited). `fn` is a function,
+     * the source of one (`"async () => ..."`), or any other string, which is an expression (`"document.title"`; it takes no argument).
+     * Values come back as plain JavaScript: Date, Map, Set, RegExp, BigInt, NaN, undefined, nested objects and arrays;
+     * an element as an `ElementHandle`; what cannot be copied (a function, window, error, promise) as a `RemoteObject` with its `type`.
+     * The page's own error message is kept (`ScriptError`). A function written under tsx must not contain named inner functions
+     * (the transpiler adds a `__name` helper the page lacks); a string always works.
+     * @example
+     *  const count = await page.evaluate((min) => document.querySelectorAll("li").length > min, 3);
+     */
+    async evaluate(fn, arg) {
+        this.assertOpen();
+        return evaluateInPage(this.biDiConnector, this.id, fn, arg);
+    }
     /**
      * Sets the size of the viewport (and, optionally, the device pixel ratio); `null` puts the browser's own size back.
      * @example
@@ -232,7 +276,27 @@ 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);
+    }
+    /**
+     * The size this page was last given (`setViewport`, `setViewportSize`, or the default from config `use.viewport` when the
+     * browser opened it), read at once; null before one is known, after `setViewport(null)` and when config turns the viewport off.
+     */
+    viewportSize() {
+        return this.knownViewport && { ...this.knownViewport };
     }
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     async applyDefaultViewport() {

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,

package/dist/config/config.js

@@ -2,6 +2,7 @@ import path from "path";
 import logger from "../logger/index.js";
 import { pathToFileURL } from "url";
 import { validateBrowserConfig } from "./browsers.js";
+import { validateUseConfig } from "./use-options.js";
 import { validateForbidOnlyConfig } from "./forbid-only.js";
 import { validateRetriesConfig } from "./retries.js";
 import { validateWorkersConfig } from "./workers.js";
@@ -30,6 +31,7 @@ export function validateConfig(config) {
     validateWorkersConfig(config);
     validateForbidOnlyConfig(config);
     validateRetriesConfig(config);
+    validateUseConfig(config);
 }
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export async function loadRawConfig() {

package/dist/config/use-options.d.ts

@@ -0,0 +1,16 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+import type { UseOptions } from "../types/use.js";
+/**
+ * Checks the options of `test.use()` or of the config's `use` and returns them. The config's `use` also holds
+ * options that are not these (`viewport`, `headless`, ...), so it passes `allowOthers`; `test.use()` refuses
+ * a key it does not know. Throws `use(): what is wrong`.
+ */
+export declare function validateUseOptions(options: unknown, allowOthers?: boolean): UseOptions;
+/** Checks a storage state object, whether it came from the options or from a file */
+export declare function checkStorageStateObject(state: Record<string, unknown>): void;
+/** The options after `layers` are applied in order: a later layer wins, key by key */
+export declare function mergeUse(layers: readonly UseOptions[]): UseOptions;
+/** Checks the new options of a config's `use` */
+export declare function validateUseConfig(config: SamuraiTestConfig): void;
+/** The options of `test.use()` that a config's `use` holds, without the rest (`viewport`, `headless`, ...) */
+export declare function useOptionsOf(configUse: object | undefined): UseOptions;

package/dist/config/use-options.js

@@ -0,0 +1,128 @@
+const NAMES = [
+    "locale",
+    "timezoneId",
+    "userAgent",
+    "javaScriptEnabled",
+    "acceptInsecureCerts",
+    "hasTouch",
+    "isMobile",
+    "storageState",
+    "extraHTTPHeaders",
+    "colorScheme",
+];
+const BOOLEANS = [
+    "javaScriptEnabled",
+    "acceptInsecureCerts",
+    "hasTouch",
+    "isMobile",
+];
+const COLOR_SCHEMES = ["light", "dark", "no-preference"];
+const HEADER_NAME = /^[\w!#$%&'*+.^`|~-]+$/;
+const fail = (problem) => {
+    throw new TypeError(`use(): ${problem}`);
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Checks the options of `test.use()` or of the config's `use` and returns them. The config's `use` also holds
+ * options that are not these (`viewport`, `headless`, ...), so it passes `allowOthers`; `test.use()` refuses
+ * a key it does not know. Throws `use(): what is wrong`.
+ */
+export function validateUseOptions(options, allowOthers = false) {
+    if (!isObject(options))
+        return fail("the options must be an object");
+    for (const key of Object.keys(options))
+        if (!allowOthers && !NAMES.includes(key))
+            fail(`unknown option "${key}"`);
+    const use = options;
+    for (const name of BOOLEANS)
+        if (use[name] !== undefined && typeof use[name] !== "boolean")
+            fail(`${name} must be true or false, got ${JSON.stringify(use[name])}`);
+    checkLocale(use.locale);
+    checkTimezone(use.timezoneId);
+    if (use.userAgent !== undefined && !nonEmpty(use.userAgent))
+        fail("userAgent must be a non-empty string");
+    if (use.colorScheme !== undefined && !COLOR_SCHEMES.includes(use.colorScheme))
+        fail(`colorScheme must be "light", "dark" or "no-preference", got ${JSON.stringify(use.colorScheme)}`);
+    checkHeaders(use.extraHTTPHeaders);
+    checkStorageState(use.storageState);
+    return use;
+}
+const nonEmpty = (value) => typeof value === "string" && value !== "";
+function checkLocale(locale) {
+    if (locale === undefined)
+        return;
+    try {
+        if (!nonEmpty(locale) || Intl.getCanonicalLocales(locale).length !== 1)
+            throw new RangeError();
+    }
+    catch {
+        fail(`invalid locale ${JSON.stringify(locale)}`);
+    }
+}
+function checkTimezone(timezone) {
+    if (timezone === undefined)
+        return;
+    try {
+        if (!nonEmpty(timezone))
+            throw new RangeError();
+        new Intl.DateTimeFormat(undefined, { timeZone: timezone });
+    }
+    catch {
+        fail(`unknown timezoneId ${JSON.stringify(timezone)}`);
+    }
+}
+function checkHeaders(headers) {
+    if (headers === undefined)
+        return;
+    if (!isObject(headers))
+        fail("extraHTTPHeaders must be an object of header names and values");
+    for (const [name, value] of Object.entries(headers))
+        if (!HEADER_NAME.test(name))
+            fail(`extraHTTPHeaders has an invalid header name "${name}"`);
+        else if (typeof value !== "string")
+            fail(`extraHTTPHeaders "${name}" must be a string`);
+}
+function checkStorageState(state) {
+    if (state === undefined)
+        return;
+    if (typeof state === "string") {
+        if (state === "")
+            fail("storageState must not be an empty path");
+        return;
+    }
+    if (!isObject(state))
+        return fail("storageState must be a file path or an object");
+    checkStorageStateObject(state);
+}
+/** Checks a storage state object, whether it came from the options or from a file */
+export function checkStorageStateObject(state) {
+    for (const key of ["cookies", "origins"])
+        if (state[key] !== undefined && !Array.isArray(state[key]))
+            fail(`storageState.${key} must be an array`);
+    for (const cookie of (state.cookies ?? [])) {
+        if (!isObject(cookie) ||
+            !nonEmpty(cookie.name) ||
+            typeof cookie.value !== "string" ||
+            !nonEmpty(cookie.domain))
+            fail("every storageState cookie needs a name, a value and a domain");
+    }
+    for (const origin of (state.origins ?? [])) {
+        if (!isObject(origin) ||
+            !nonEmpty(origin.origin) ||
+            !Array.isArray(origin.localStorage ?? []))
+            fail("every storageState origin needs an origin and a localStorage list");
+    }
+}
+/** The options after `layers` are applied in order: a later layer wins, key by key */
+export function mergeUse(layers) {
+    return Object.assign({}, ...layers);
+}
+/** Checks the new options of a config's `use` */
+export function validateUseConfig(config) {
+    if (config.use !== undefined)
+        validateUseOptions(config.use, true);
+}
+/** The options of `test.use()` that a config's `use` holds, without the rest (`viewport`, `headless`, ...) */
+export function useOptionsOf(configUse) {
+    return Object.fromEntries(Object.entries(configUse ?? {}).filter(([key]) => NAMES.includes(key)));
+}

package/dist/locator/element-access.d.ts

@@ -8,6 +8,8 @@ export interface ElementAccess extends ElementContext {
      * throw instead (`method` is the public method that asked, for the message)
      */
     resolveOne(method?: string): Promise<ElementHandle | null>;
+    /** Every element the locator matches now, in document order; never strict, never waits */
+    resolveAll(): Promise<ElementHandle[]>;
 }
 /** Calls `fn` in the page; a throwing function becomes a "Failed to locate element" error */
 export declare function callInPage<T>(access: Pick<ElementAccess, "connector" | "contextId" | "selector">, fn: string, args: Arg[], sandbox?: string): Promise<T>;