@itmetsam/samurai-framework 0.21.5 → 0.22.1

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

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

package/dist/browser/use-applier.js

@@ -1,6 +1,8 @@
 import { warnOnce } from "../logger/warn-once.js";
 import { cdpSend, sendRaw } from "./cdp.js";
-import { cookiesOf, loadStorageState } from "./storage-state.js";
+import { applyUse, RUNTIME_OPTIONS } from "./use-commands.js";
+import { cookiesOf } from "./storage-state.js";
+import { loadStorageState } from "../config/storage-state-file.js";
 /** The `use` options a browser applies to its contexts and pages, by what each browser can do (see the wiki's support matrix) */
 export class UseApplier {
     constructor(connector, browserName, options, projectDir) {
@@ -30,21 +32,17 @@ export class UseApplier {
         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).
+     * Sets up a context: the run-time options (`page.use()`'s) through BiDi, the extra headers, then the storage state.
+     * An option the browser does not support is skipped with a one-time warning (`page.use()` throws instead).
+     * Firefox gets JavaScript and the colour scheme when it starts (a profile setting).
      */
     async context(context) {
         const { options } = this;
-        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);
+        await applyUse(this.connector, { userContexts: [context.id] }, this.startUp(), (option) => warnOnce(`use.${option}`, `use.${option} is not supported by this browser: it is ignored`));
+        context.setRequestDefaults({
+            extraHTTPHeaders: options.extraHTTPHeaders,
+            ignoreHTTPSErrors: options.acceptInsecureCerts,
+        });
         if (options.extraHTTPHeaders)
             await sendRaw(this.connector, "network.setExtraHeaders", {
                 headers: Object.entries(options.extraHTTPHeaders).map(([name, value]) => ({ name, value: { type: "string", value } })),
@@ -53,12 +51,41 @@ export class UseApplier {
         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) */
+    /**
+     * Sets up a page of a context this applier set up: Chrome's phone layout and colour scheme (CDP, so per page), and
+     * the viewport a group asked for (after the phone layout, so the size keeps it)
+     */
     async page(page) {
-        if (!this.chrome)
-            return;
+        if (this.chrome)
+            await this.chromePage(page);
+        if (this.options.viewport !== undefined)
+            await page.setViewport(this.options.viewport);
+    }
+    /**
+     * The declared options that go through BiDi. Left out: those that are not set (or `null`), the ones that change
+     * nothing (`offline: false`), Chrome-only touch on Firefox (warned once in the constructor) and JavaScript on
+     * Firefox (a profile setting).
+     */
+    startUp() {
+        const { options } = this;
+        const wanted = {};
+        for (const name of RUNTIME_OPTIONS) {
+            const value = options[name];
+            if (value === undefined || value === null)
+                continue;
+            if (name === "offline" && value === false)
+                continue;
+            if (name === "hasTouch" && !this.hasTouch)
+                continue;
+            if (name === "javaScriptEnabled" && !(this.chrome && value === false))
+                continue;
+            wanted[name] = value;
+        }
+        return wanted;
+    }
+    async chromePage(page) {
         if (this.isMobile)
-            await page.emulateMobile();
+            await page.setMobileLayout();
         if (this.options.colorScheme !== undefined)
             await cdpSend(this.connector, page.contextId, "Emulation.setEmulatedMedia", {
                 features: [

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/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,10 +2,13 @@ import path from "path";
 import logger from "../logger/index.js";
 import { pathToFileURL } from "url";
 import { validateBrowserConfig } from "./browsers.js";
+import { validateEnvironmentUse, 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) {
@@ -31,7 +34,11 @@ export function validateConfig(config) {
     validateWorkersConfig(config);
     validateForbidOnlyConfig(config);
     validateRetriesConfig(config);
+    validateFullyParallelConfig(config);
     validateUseConfig(config);
+    validateGroupUse(config);
+    validateEnvironmentUse(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/fixture-use.d.ts

@@ -0,0 +1,19 @@
+/** The key of `use` that attaches fixtures by name (`true`) or removes them (`false`) */
+export declare const FIXTURES_KEY = "fixtures";
+/** Whether `key` of a `use` object is about fixtures: `fixtures`, or an option fixture (`orderOptions`) */
+export declare function isFixtureUseKey(key: string): boolean;
+/** The fixture keys of one `use` layer */
+export declare function pickFixtureUse(layer: object | undefined): Record<string, unknown>;
+/** The layer without its fixture keys: what is left is for the browser */
+export declare function omitFixtureUse<T extends object>(layer: T | undefined): T;
+/** Checks the fixture keys of one `use` layer; throws `use(): what is wrong` */
+export declare function checkFixtureUse(options: Record<string, unknown>): void;
+/** What the fixture keys of the layers come to, later layers winning key by key */
+export interface MergedFixtureUse {
+    /** Fixture name to attached (`true`) or removed (`false`) */
+    fixtures: Record<string, boolean>;
+    /** Option fixture name to its values from `use`, over the fixture's own default */
+    options: Record<string, Record<string, unknown>>;
+}
+/** Merges the fixture keys of the `use` layers in order (config, environment, group, `test.use()`) */
+export declare function mergeFixtureUse(layers: readonly object[]): MergedFixtureUse;

package/dist/config/fixture-use.js

@@ -0,0 +1,44 @@
+/** The key of `use` that attaches fixtures by name (`true`) or removes them (`false`) */
+export const FIXTURES_KEY = "fixtures";
+const OPTION_FIXTURE_KEY = /^[a-z][A-Za-z0-9]*Options$/;
+/** Whether `key` of a `use` object is about fixtures: `fixtures`, or an option fixture (`orderOptions`) */
+export function isFixtureUseKey(key) {
+    return key === FIXTURES_KEY || OPTION_FIXTURE_KEY.test(key);
+}
+/** The fixture keys of one `use` layer */
+export function pickFixtureUse(layer) {
+    return Object.fromEntries(Object.entries(layer ?? {}).filter(([key]) => isFixtureUseKey(key)));
+}
+/** The layer without its fixture keys: what is left is for the browser */
+export function omitFixtureUse(layer) {
+    return Object.fromEntries(Object.entries(layer ?? {}).filter(([key]) => !isFixtureUseKey(key)));
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Checks the fixture keys of one `use` layer; throws `use(): what is wrong` */
+export function checkFixtureUse(options) {
+    const attached = options[FIXTURES_KEY];
+    if (attached !== undefined) {
+        if (!isObject(attached))
+            throw new TypeError("use(): fixtures must be an object of fixture names and true or false");
+        for (const [name, on] of Object.entries(attached))
+            if (typeof on !== "boolean")
+                throw new TypeError(`use(): fixtures.${name} must be true or false, got ${JSON.stringify(on)}`);
+    }
+    for (const [key, value] of Object.entries(options))
+        if (key !== FIXTURES_KEY && isFixtureUseKey(key) && !isObject(value))
+            throw new TypeError(`use(): ${key} must be an object`);
+}
+/** Merges the fixture keys of the `use` layers in order (config, environment, group, `test.use()`) */
+export function mergeFixtureUse(layers) {
+    const merged = { fixtures: {}, options: {} };
+    for (const layer of layers)
+        for (const [key, value] of Object.entries(pickFixtureUse(layer)))
+            if (key === FIXTURES_KEY)
+                Object.assign(merged.fixtures, value);
+            else
+                merged.options[key] = {
+                    ...merged.options[key],
+                    ...value,
+                };
+    return merged;
+}

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,10 @@
+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`),
+ * and the fixture keys. Throws `config.groups[1].use.locale: what is wrong`.
+ */
+export declare function validateGroupUse(config: SamuraiTestConfig): void;
+/** Checks the `use` of every environment the same way: `config.environments.production.use.locale: what is wrong` */
+export declare function validateEnvironmentUse(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,51 @@
+import { isFixtureUseKey } from "./fixture-use.js";
+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) ||
+            isFixtureUseKey(name));
+    throw new TypeError(`${place}${known ? `.${name}` : ""}: ${problem}`);
+}
+/** Checks one `use` of a group or an environment; throws `<place>.locale: what is wrong` */
+function validateUseAt(place, use) {
+    try {
+        const isObject = typeof use === "object" && use !== null && !Array.isArray(use);
+        const { viewport, ...options } = (isObject ? use : {});
+        // Anything but an object is refused here, with the message `test.use()` gives
+        validateUseOptions(isObject ? options : use);
+        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);
+    }
+}
+/**
+ * Checks the `use` of every group of the config: the options of config `use` (`test.use()` ones, and `viewport`),
+ * and the fixture keys. Throws `config.groups[1].use.locale: what is wrong`.
+ */
+export function validateGroupUse(config) {
+    config.groups?.forEach((group, index) => {
+        if (group.use !== undefined)
+            validateUseAt(`config.groups[${index}].use`, group.use);
+    });
+}
+/** Checks the `use` of every environment the same way: `config.environments.production.use.locale: what is wrong` */
+export function validateEnvironmentUse(config) {
+    for (const [name, environment] of Object.entries(config.environments ?? {}))
+        if (environment?.use !== undefined)
+            validateUseAt(`config.environments.${name}.use`, environment.use);
+}
+/** 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),