@itmetsam/samurai-framework 0.21.4 → 0.22.0

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

@@ -0,0 +1,36 @@
+import { UnsupportedOperationError } from "../transport/unsupported.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { RuntimeUseOptions } from "../types/use.js";
+export type UseTarget = {
+    contexts: string[];
+} | {
+    userContexts: string[];
+};
+/** A part of the options could not be applied; what was applied before it stays applied */
+export declare class UseError extends Error {
+    /** The options that were applied before the failure, in the order they were applied */
+    readonly applied: string[];
+    readonly failed: string;
+    readonly cause: unknown;
+    constructor(failed: string, applied: string[], cause: unknown);
+}
+/** The browser does not implement the command an option needs */
+export declare class UseUnsupportedError extends UnsupportedOperationError {
+    readonly option: string;
+    readonly applied: string[];
+    constructor(option: string, applied: string[]);
+}
+/** The options that can change while the browser runs, in the order they are applied */
+export declare const RUNTIME_OPTIONS: readonly ["locale", "timezone", "userAgent", "geolocation", "offline", "orientation", "screen", "hasTouch", "javaScriptEnabled"];
+/**
+ * Checks the options of `page.use()` / `context.use()` / `newContext()`: the values like config `use` does, and
+ * only the options that can change at run time. Throws `use(): what is wrong`, before anything is sent.
+ */
+export declare function validateRuntimeUse(options: RuntimeUseOptions): void;
+/**
+ * Applies the options to `target`, one command after the other, after checking all of them. Nothing is rolled
+ * back when one fails: the error says what was applied. An option the browser does not support throws
+ * `UseUnsupportedError`, unless `onUnsupported` is given: then it is reported there and skipped (how `use` in
+ * config behaves: it warns, `page.use()` throws).
+ */
+export declare function applyUse(connector: BiDiConnector, target: UseTarget, options: RuntimeUseOptions, onUnsupported?: (option: string) => void): Promise<void>;

package/dist/browser/use-commands.js

@@ -0,0 +1,120 @@
+import { isUnsupported, UnsupportedOperationError, } from "../transport/unsupported.js";
+import { USE_OPTION_NAMES, validateUseOptions } from "../config/use-options.js";
+/** A part of the options could not be applied; what was applied before it stays applied */
+export class UseError extends Error {
+    constructor(failed, applied, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`use(): ${failed} failed${applied.length ? ` after applying ${applied.join(", ")}` : ""}: ${detail}`);
+        this.name = "UseError";
+        this.failed = failed;
+        this.applied = applied;
+        this.cause = cause;
+    }
+}
+/** The browser does not implement the command an option needs */
+export class UseUnsupportedError extends UnsupportedOperationError {
+    constructor(option, applied) {
+        super(`use(): ${option} is not supported by the browser${AT_START_ONLY.has(option) ? ` at run time; set it in config use, a group's use or test.use()` : ""}`);
+        this.name = "UseUnsupportedError";
+        this.option = option;
+        this.applied = applied;
+    }
+}
+/** Options Firefox can only take when it starts (a profile setting), so run time is unsupported there */
+const AT_START_ONLY = new Set(["javaScriptEnabled"]);
+/** The options that can change while the browser runs, in the order they are applied */
+export const RUNTIME_OPTIONS = [
+    "locale",
+    "timezone",
+    "userAgent",
+    "geolocation",
+    "offline",
+    "orientation",
+    "screen",
+    "hasTouch",
+    "javaScriptEnabled",
+];
+/**
+ * Checks the options of `page.use()` / `context.use()` / `newContext()`: the values like config `use` does, and
+ * only the options that can change at run time. Throws `use(): what is wrong`, before anything is sent.
+ */
+export function validateRuntimeUse(options) {
+    validateUseOptions(options);
+    for (const key of Object.keys(options))
+        if (!RUNTIME_OPTIONS.includes(key))
+            throw new TypeError(`use(): ${USE_OPTION_NAMES.includes(key) ? `${key} can only be set before the browser starts: in config use, a group's use or test.use()` : `unknown option "${key}"`}`);
+}
+/** Turns validated options into BiDi commands, in a fixed order */
+function plan(options) {
+    const steps = [];
+    const add = (option, method, params) => steps.push({ option, method, params });
+    if (options.locale !== undefined)
+        add("locale", "emulation.setLocaleOverride", { locale: options.locale });
+    if (options.timezone !== undefined)
+        add("timezone", "emulation.setTimezoneOverride", {
+            timezone: options.timezone,
+        });
+    if (options.userAgent !== undefined)
+        add("userAgent", "emulation.setUserAgentOverride", {
+            userAgent: options.userAgent,
+        });
+    if (options.geolocation !== undefined)
+        add("geolocation", "emulation.setGeolocationOverride", {
+            coordinates: options.geolocation,
+        });
+    if (options.offline !== undefined)
+        add("offline", "emulation.setNetworkConditions", {
+            networkConditions: options.offline ? { type: "offline" } : null,
+        });
+    if (options.orientation !== undefined) {
+        const type = options.orientation === null
+            ? null
+            : options.orientation === "portrait" ||
+                options.orientation === "landscape"
+                ? `${options.orientation}-primary`
+                : options.orientation;
+        add("orientation", "emulation.setScreenOrientationOverride", {
+            screenOrientation: type && {
+                natural: type.startsWith("portrait") ? "portrait" : "landscape",
+                type,
+            },
+        });
+    }
+    if (options.screen !== undefined)
+        add("screen", "emulation.setScreenSettingsOverride", {
+            screenArea: options.screen,
+        });
+    if (options.hasTouch !== undefined)
+        add("hasTouch", "emulation.setTouchOverride", {
+            maxTouchPoints: options.hasTouch ? 1 : null,
+        });
+    if (options.javaScriptEnabled !== undefined)
+        add("javaScriptEnabled", "emulation.setScriptingEnabled", {
+            enabled: options.javaScriptEnabled === false ? false : null,
+        });
+    return steps;
+}
+/**
+ * Applies the options to `target`, one command after the other, after checking all of them. Nothing is rolled
+ * back when one fails: the error says what was applied. An option the browser does not support throws
+ * `UseUnsupportedError`, unless `onUnsupported` is given: then it is reported there and skipped (how `use` in
+ * config behaves: it warns, `page.use()` throws).
+ */
+export async function applyUse(connector, target, options, onUnsupported) {
+    validateRuntimeUse(options);
+    const applied = [];
+    for (const step of plan(options)) {
+        try {
+            await connector.send(step.method, { ...step.params, ...target });
+        }
+        catch (err) {
+            if (!isUnsupported(err))
+                throw new UseError(step.option, applied, err);
+            if (!onUnsupported)
+                throw new UseUnsupportedError(step.option, applied);
+            onUnsupported(step.option);
+            continue;
+        }
+        applied.push(step.option);
+    }
+}

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

@@ -1,4 +1,4 @@
-import { type ProjectOptions, type RunnerOptions } from "../runner/run.js";
+import { type ProjectOptions, type RunnerOptions, type Shard } from "../runner/run.js";
 /** `firefox` or `chrome` */
 type SupportedBrowser = NonNullable<RunnerOptions["browsers"]>[number];
 /** The values a command line can override for one run: the environment and the two timeouts */
@@ -13,8 +13,9 @@ export declare function parseCommandLine(argv: string[]): {
         port?: string | undefined;
         workers?: string | undefined;
         retries?: string | undefined;
+        shard?: string | undefined;
         grep?: string | undefined;
-        group?: string | undefined;
+        group?: string[] | undefined;
         browser?: string[] | undefined;
         file?: string[] | undefined;
         json?: boolean | undefined;
@@ -43,13 +44,16 @@ export interface RunnerFlags {
     workers?: string;
     /** `--retries`: a whole number from 0, as typed */
     retries?: string;
+    /** `--shard=current/total`, parsed */
+    shard?: Shard;
     grep?: string;
-    group?: string;
+    /** `--group`: one name as typed, or the list when it is repeated */
+    group?: string | string[];
     files?: string[];
     /** `--browser`, repeated for more than one; replaces the config's `browsers` for this run */
     browsers?: SupportedBrowser[];
 }
-/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--retries <n>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv`, or from values that were parsed already */
+/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--retries <n>`, `--shard <current/total>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (all three repeatable) from `argv`, or from values that were parsed already */
 export declare function parseRunnerFlags(source: string[] | CommandValues): RunnerFlags;
 /** Reads `--env`, `--timeout` and `--expect-timeout` from `argv` (or values parsed already); the environment falls back to SAMURAI_ENV */
 export declare function parseRunOverrides(source: string[] | CommandValues, env?: Partial<NodeJS.ProcessEnv>): EnvAndTimeouts;

package/dist/cli/args.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { checkBrowserList, parseRetries, parseWorkers, } from "../runner/run.js";
+import { checkBrowserList, parseRetries, parseShard, parseWorkers, } from "../runner/run.js";
 const FLAGS = {
     env: { type: "string" },
     timeout: { type: "string" },
@@ -8,8 +8,9 @@ const FLAGS = {
     port: { type: "string" },
     workers: { type: "string" },
     retries: { type: "string" },
+    shard: { type: "string" },
     grep: { type: "string" },
-    group: { type: "string" },
+    group: { type: "string", multiple: true },
     browser: { type: "string", multiple: true },
     file: { type: "string", multiple: true },
     json: { type: "boolean" },
@@ -35,7 +36,7 @@ export function parseCommandLine(argv) {
     });
 }
 const valuesOf = (source) => Array.isArray(source) ? parseCommandLine(source).values : source;
-/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--retries <n>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv`, or from values that were parsed already */
+/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--retries <n>`, `--shard <current/total>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (all three repeatable) from `argv`, or from values that were parsed already */
 export function parseRunnerFlags(source) {
     const values = valuesOf(source);
     const flags = {};
@@ -56,10 +57,12 @@ export function parseRunnerFlags(source) {
         parseRetries(values.retries, "--retries");
         flags.retries = values.retries;
     }
+    if (values.shard !== undefined)
+        flags.shard = parseShard(values.shard, "--shard");
     if (values.grep !== undefined)
         flags.grep = values.grep;
-    if (values.group !== undefined)
-        flags.group = values.group;
+    if (values.group?.length)
+        flags.group = values.group.length === 1 ? values.group[0] : values.group;
     if (values.file?.length)
         flags.files = values.file;
     if (values.browser?.length) {

package/dist/cli/console-reporter.js

@@ -20,7 +20,7 @@ export class ConsoleReporter {
         switch (event.type) {
             case "run-start":
                 this.labelled = event.browsers.length > 1;
-                this.write(`Running ${event.total} ${event.total === 1 ? "test" : "tests"}${event.workers ? ` with ${event.workers} workers` : ""} against ${event.environment}${this.labelled ? ` in ${event.browsers.join(", ")}` : ""}\n`);
+                this.write(`Running ${event.total} ${event.total === 1 ? "test" : "tests"}${event.shard ? ` (shard ${event.shard.current}/${event.shard.total})` : ""}${event.workers ? ` with ${event.workers} workers` : ""} against ${event.environment}${this.labelled ? ` in ${event.browsers.join(", ")}` : ""}\n`);
                 return;
             case "test-end":
                 this.write(`  ${this.line(event.name, event.result, event.browser)}\n`);
@@ -47,6 +47,10 @@ export class ConsoleReporter {
             : `${this.paint(31, "✖")} ${name}${this.tag(browser)}${took}`;
     }
     summary(summary) {
+        if (summary.shard && summary.tests.length === 0) {
+            this.write(`\n${this.paint(90, `Shard ${summary.shard.current}/${summary.shard.total} has no tests to run`)}\n`);
+            return;
+        }
         const skipped = summary.tests.filter((test) => test.status === "skipped");
         const failed = summary.tests.filter((test) => test.status !== "success" && test.status !== "skipped");
         for (const test of failed) {

package/dist/cli/main.js

@@ -49,6 +49,7 @@ export async function main(argv, io) {
             ...(flags.port !== undefined && { port: flags.port }),
             ...(flags.workers !== undefined && { workers: flags.workers }),
             ...(flags.retries !== undefined && { retries: flags.retries }),
+            ...(flags.shard && { shard: flags.shard }),
             ...(flags.grep !== undefined && { grep: flags.grep }),
             ...(flags.group !== undefined && { group: flags.group }),
             ...(flags.files && { files: flags.files }),

package/dist/cli/usage.d.ts

@@ -1 +1 @@
-export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups\n  --browser <name>            Run in this browser (firefox or chrome) instead of the config's\n                              browsers; repeat it for more than one\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n  --workers <n|n%>            Tests that run at the same time, each in a worker process: a number\n                              from 1, or a share of the CPUs like 50%. Default: the config's\n                              workers (or SAMURAI_WORKERS), else half the CPUs\n  --retries <n>               Run a failing test again up to n times, each with a fresh browser\n                              (or SAMURAI_RETRIES; default 0)\n\nOptions for record (also --env, --port, --json, --headless, --no-headless):\n  --browser <name>            Record in this browser (default: the first of the config's browsers)\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";
+export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups; repeat it for several\n  --browser <name>            Run in this browser (firefox or chrome) instead of the config's\n                              browsers; repeat it for more than one\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n  --workers <n|n%>            Tests that run at the same time, each in a worker process: a number\n                              from 1, or a share of the CPUs like 50%. Default: the config's\n                              workers (or SAMURAI_WORKERS), else half the CPUs\n  --retries <n>               Run a failing test again up to n times, each with a fresh browser\n                              (or SAMURAI_RETRIES; default 0)\n  --shard <current/total>     Run one slice of the selected tests, to split a run over machines:\n                              --shard=2/4 runs the second of four. Whole files (and serial\n                              blocks) go to one shard; an empty shard succeeds\n\nOptions for record (also --env, --port, --json, --headless, --no-headless):\n  --browser <name>            Record in this browser (default: the first of the config's browsers)\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";

package/dist/cli/usage.js

@@ -13,7 +13,7 @@ Options for run and list:
   --env <name>                Environment to run against (or SAMURAI_ENV)
   --file <spec>               Only this spec file; repeatable
   --grep <text>               Only tests whose full name contains the text
-  --group <name>              Only the tests of this group of the config's groups
+  --group <name>              Only the tests of this group of the config's groups; repeat it for several
   --browser <name>            Run in this browser (firefox or chrome) instead of the config's
                               browsers; repeat it for more than one
   --json                      Machine-readable output: JSON lines for run, one array for list
@@ -29,6 +29,9 @@ Options for run:
                               workers (or SAMURAI_WORKERS), else half the CPUs
   --retries <n>               Run a failing test again up to n times, each with a fresh browser
                               (or SAMURAI_RETRIES; default 0)
+  --shard <current/total>     Run one slice of the selected tests, to split a run over machines:
+                              --shard=2/4 runs the second of four. Whole files (and serial
+                              blocks) go to one shard; an empty shard succeeds
 
 Options for record (also --env, --port, --json, --headless, --no-headless):
   --browser <name>            Record in this browser (default: the first of the config's browsers)

package/dist/config/base-url.d.ts

@@ -0,0 +1,4 @@
+/** A URL starting with "/", "./" or "../" */
+export declare const RELATIVE_URL: RegExp;
+/** Resolves a slash-led `url` against `base`; any other URL is returned as given */
+export declare function resolveRelativeURL(url: string, base: string): string;

package/dist/config/base-url.js

@@ -0,0 +1,6 @@
+/** A URL starting with "/", "./" or "../" */
+export 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;
+}

package/dist/config/config.js

@@ -2,9 +2,13 @@ import path from "path";
 import logger from "../logger/index.js";
 import { pathToFileURL } from "url";
 import { validateBrowserConfig } from "./browsers.js";
+import { validateGroupUse } from "./group-use.js";
+import { validateUseConfig } from "./use-options.js";
 import { validateForbidOnlyConfig } from "./forbid-only.js";
 import { validateRetriesConfig } from "./retries.js";
+import { validateFullyParallelConfig } from "./fully-parallel.js";
 import { validateWorkersConfig } from "./workers.js";
+import { validateWebServerConfig } from "./web-server-options.js";
 let activeProject;
 /** Makes `project` the one config, secrets, reports and downloads are resolved for; `undefined` ends it */
 export function setActiveProject(project) {
@@ -30,6 +34,10 @@ export function validateConfig(config) {
     validateWorkersConfig(config);
     validateForbidOnlyConfig(config);
     validateRetriesConfig(config);
+    validateFullyParallelConfig(config);
+    validateUseConfig(config);
+    validateGroupUse(config);
+    validateWebServerConfig(config);
 }
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
 export async function loadRawConfig() {

package/dist/config/fully-parallel.d.ts

@@ -0,0 +1,3 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+/** Checks the `fullyParallel` key of a config. Throws an Error that names the key */
+export declare function validateFullyParallelConfig(config: SamuraiTestConfig): void;

package/dist/config/fully-parallel.js

@@ -0,0 +1,6 @@
+/** Checks the `fullyParallel` key of a config. Throws an Error that names the key */
+export function validateFullyParallelConfig(config) {
+    if (config.fullyParallel !== undefined &&
+        typeof config.fullyParallel !== "boolean")
+        throw new Error(`fullyParallel must be true or false, got ${JSON.stringify(config.fullyParallel)}`);
+}

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

@@ -0,0 +1,8 @@
+import type { GroupUse, SamuraiGroup, SamuraiTestConfig } from "../types/config.js";
+/**
+ * Checks the `use` of every group of the config: the options of config `use` (`test.use()` ones, and `viewport`).
+ * Throws `config.groups[1].use.locale: what is wrong`.
+ */
+export declare function validateGroupUse(config: SamuraiTestConfig): void;
+/** The `use` of the group called `name`; nothing when there is no such group or it has none */
+export declare function groupUseOf(groups: readonly SamuraiGroup[] | undefined, name: string): GroupUse;

package/dist/config/group-use.js

@@ -0,0 +1,41 @@
+import { USE_OPTION_NAMES, validateUseOptions } from "./use-options.js";
+const isSize = (value) => typeof value === "number" && Number.isInteger(value) && value > 0;
+/** Rewrites `use(): locale must ...` as `config.groups[1].use.locale: locale must ...` */
+function atGroup(place, err) {
+    if (!(err instanceof TypeError))
+        throw err;
+    const problem = err.message.replace(/^use\(\): /, "");
+    const name = /^(?:invalid |unknown )?(\w+)/.exec(problem)?.[1];
+    const known = name !== undefined &&
+        (name === "viewport" || USE_OPTION_NAMES.includes(name));
+    throw new TypeError(`${place}${known ? `.${name}` : ""}: ${problem}`);
+}
+/**
+ * Checks the `use` of every group of the config: the options of config `use` (`test.use()` ones, and `viewport`).
+ * Throws `config.groups[1].use.locale: what is wrong`.
+ */
+export function validateGroupUse(config) {
+    config.groups?.forEach((group, index) => {
+        if (group.use === undefined)
+            return;
+        const place = `config.groups[${index}].use`;
+        try {
+            const raw = group.use;
+            const isObject = typeof raw === "object" && raw !== null && !Array.isArray(raw);
+            const { viewport, ...options } = (isObject ? raw : {});
+            // Anything but an object is refused here, with the message `test.use()` gives
+            validateUseOptions(isObject ? options : raw);
+            if (viewport !== undefined &&
+                viewport !== null &&
+                !(isSize(viewport.width) && isSize(viewport.height)))
+                throw new TypeError(`viewport must be { width, height } with whole numbers above 0, or null, got ${JSON.stringify(viewport)}`);
+        }
+        catch (err) {
+            atGroup(place, err);
+        }
+    });
+}
+/** The `use` of the group called `name`; nothing when there is no such group or it has none */
+export function groupUseOf(groups, name) {
+    return groups?.find((group) => group.name === name)?.use ?? {};
+}

package/dist/config/resolved-config.d.ts

@@ -45,6 +45,8 @@ export interface ResolvedConfig {
     workers?: number | string;
     /** The workers a run without `--workers` and `SAMURAI_WORKERS` uses on this machine */
     workersResolved: number;
+    /** The config's `fullyParallel` as written; absent when not set */
+    fullyParallel?: boolean;
     retries: number;
     forbidOnly: boolean;
     headless: boolean;

package/dist/config/resolved-config.js

@@ -62,6 +62,9 @@ export function resolveConfig(config, options) {
         bidiCommandTimeout: config.bidi?.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT,
         ...(config.workers !== undefined && { workers: config.workers }),
         workersResolved: resolveWorkers({ config: config.workers }),
+        ...(config.fullyParallel !== undefined && {
+            fullyParallel: config.fullyParallel,
+        }),
         // Matches the runner's `resolveRetries` without the command line flag and the environment (config/ cannot import runner/)
         retries: config.retries ?? DEFAULT_RETRIES,
         forbidOnly: forbidsOnly(config, env),

package/dist/config/storage-state-file.d.ts

@@ -0,0 +1,3 @@
+import type { StorageState } from "../types/use.js";
+/** The state itself, or the JSON file (relative to `baseDir`) that holds it. Throws `<who>: what is wrong` (`use()` unless told otherwise). */
+export declare function loadStorageState(source: string | StorageState, baseDir: string, who?: string): StorageState;

package/dist/config/storage-state-file.js

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { checkStorageStateObject } from "./use-options.js";
+/** The state itself, or the JSON file (relative to `baseDir`) that holds it. Throws `<who>: what is wrong` (`use()` unless told otherwise). */
+export function loadStorageState(source, baseDir, who = "use()") {
+    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(`${who}: 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(`${who}: storageState file ${JSON.stringify(source)} must hold an object`);
+    checkStorageStateObject(state);
+    return state;
+}

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

@@ -0,0 +1,18 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+import type { UseOptions } from "../types/use.js";
+/** The options of `use`: config, group, `test.use()` and (those that can change at run time) `page.use()` */
+export declare const USE_OPTION_NAMES: readonly string[];
+/**
+ * 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<T extends UseOptions>(layers: readonly T[]): T;
+/** 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;