@itmetsam/samurai-framework 0.21.5 → 0.22.0

package/dist/browser/page.d.ts

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

package/dist/browser/page.js

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

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

@@ -1,6 +1,4 @@
 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

@@ -1,23 +1,3 @@
-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) {

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;
+}