@itmetsam/samurai-framework 0.22.0 → 0.22.1

package/dist/api.d.ts

@@ -7,7 +7,7 @@ export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export type { GlobalHookConfig, WebServerConfig } from "./types/config.js";
 export { defineStep, type StepDefinition, type StepResult, type StepRunInput, } from "./flows/steps/index.js";
-export type { AllHookFixtures, TestAnnotation, TestAttachment, TestDetails, TestFixtures, TestInfo, TestOptions, TestOutputs, TestStepEntry, } from "./types/test.js";
-export type { FixtureOptions } from "./types/extend.js";
-export type { ColorScheme, StorageState, StorageStateCookie, RuntimeUseOptions, UseOptions, } from "./types/use.js";
+export type { AllHookFixtures, TestAnnotation, TestAttachment, TestDetails, TestFixtures, TestInfo, TestOptions, TestOutputs, TestFixtureEntry, TestStepEntry, } from "./types/test.js";
+export type { FixtureField, FixtureOptions, FixtureOutput, } from "./types/extend.js";
+export type { ColorScheme, StorageState, StorageStateCookie, RuntimeUseOptions, UseOptions, FixtureUse, } from "./types/use.js";
 export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/browser/page-content.d.ts

@@ -3,3 +3,7 @@ import type { BiDiConnector } from "../transport/bidi-connection.js";
 export declare function readContent(connector: BiDiConnector, context: string): Promise<string>;
 /** Writes `html` as the page's document; true when the document reached `state` within `timeout` ms */
 export declare function writeContent(connector: BiDiConnector, context: string, html: string, state: "load" | "domcontentloaded", timeout: number): Promise<boolean>;
+/** The URL of the document now */
+export declare function readUrl(connector: BiDiConnector, context: string): Promise<string>;
+/** The title of the document now */
+export declare function readTitle(connector: BiDiConnector, context: string): Promise<string>;

package/dist/browser/page-content.js

@@ -41,3 +41,15 @@ export function writeContent(connector, context, html, state, timeout) {
         timeout,
     ]);
 }
+/** The URL of the document now */
+export function readUrl(connector, context) {
+    return callFunction(connector, context, "() => location.href", [], {
+        awaitPromise: false,
+    });
+}
+/** The title of the document now */
+export function readTitle(connector, context) {
+    return callFunction(connector, context, "() => document.title", [], {
+        awaitPromise: false,
+    });
+}

package/dist/browser/page-events.d.ts

@@ -42,3 +42,14 @@ export declare function sourcesFor(event: PageEventName): EventSource[];
  * wait that ran out after `timeout` ms.
  */
 export declare function waitForPageEvent<E extends PageEventName>(emitter: EventEmitter, event: E, matches: (item: PageEvents[E][0]) => boolean, options: Pick<WaitOptions, "trigger">, timeout: number, onTimeout: (timeout: number) => Error): Promise<PageEvents[E][0]>;
+/** The waits `waitForEvent` hands its event to; `download` and `filechooser` take the predicate too */
+export interface EventWaiters {
+    request(accepts: (item: unknown) => boolean, options: WaitOptions): Promise<unknown>;
+    response(accepts: (item: unknown) => boolean, options: WaitOptions): Promise<unknown>;
+    download(options: WaitOptions, accepts: (item: unknown) => boolean): Promise<unknown>;
+    filechooser(options: WaitOptions, accepts: (item: unknown) => boolean): Promise<unknown>;
+}
+/** `page.waitForEvent`: picks the named wait for `event`, with the predicate given as a function or in the options */
+export declare function waitForEventOn<E extends WaitableEventName>(waiters: EventWaiters, event: E, optionsOrPredicate: ((item: PageEvents[E][0]) => boolean) | WaitForEventOptions<PageEvents[E][0]>): Promise<PageEvents[E][0]>;
+/** Starts the parts `event` needs; a failure is reported to `onError`, not thrown */
+export declare function startSources(event: PageEventName, start: Record<EventSource, () => Promise<unknown>>, onError: (err: unknown) => void): void;

package/dist/browser/page-events.js

@@ -56,3 +56,26 @@ export function waitForPageEvent(emitter, event, matches, options, timeout, onTi
         }
     });
 }
+/** `page.waitForEvent`: picks the named wait for `event`, with the predicate given as a function or in the options */
+export async function waitForEventOn(waiters, event, optionsOrPredicate) {
+    const { predicate, ...options } = typeof optionsOrPredicate === "function"
+        ? { predicate: optionsOrPredicate }
+        : optionsOrPredicate;
+    const accepts = (predicate ?? (() => true));
+    switch (event) {
+        case "request":
+            return waiters.request(accepts, options);
+        case "response":
+            return waiters.response(accepts, options);
+        case "download":
+            return waiters.download(options, accepts);
+        case "filechooser":
+            return waiters.filechooser(options, accepts);
+        default:
+            throw new Error(`waitForEvent(): "${String(event)}" is not supported; use page.on()`);
+    }
+}
+/** Starts the parts `event` needs; a failure is reported to `onError`, not thrown */
+export function startSources(event, start, onError) {
+    Promise.all(sourcesFor(event).map((source) => start[source]())).catch(onError);
+}

package/dist/browser/page-logging.d.ts

@@ -0,0 +1,24 @@
+import type EventEmitter from "node:events";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+import type { ContextTree } from "./context-tree.js";
+import { PageLogs, type LogRecord, type PageError } from "./page-logs.js";
+/** A page's console and error collection: started on demand, read at once, and whether the runner may fail on its errors */
+export declare class PageLogging {
+    private readonly connector;
+    private readonly contextId;
+    private readonly tree;
+    private readonly emitter;
+    private lazyLogs;
+    private errorsAllowed;
+    constructor(connector: BiDiConnector, contextId: BrowsingContext, tree: () => Promise<ContextTree>, emitter: EventEmitter);
+    start(): Promise<void>;
+    /** Forgets the collection and hands back its start, for the caller to dispose; undefined when it never started */
+    take(): Promise<PageLogs> | undefined;
+    entries(): readonly LogRecord[];
+    errors(): readonly PageError[];
+    get dropped(): number;
+    clear(): void;
+    allowErrors(): void;
+    get errorsAreAllowed(): boolean;
+}

package/dist/browser/page-logging.js

@@ -0,0 +1,43 @@
+import { Lazy } from "./lazy.js";
+import { PageLogs } from "./page-logs.js";
+/** A page's console and error collection: started on demand, read at once, and whether the runner may fail on its errors */
+export class PageLogging {
+    constructor(connector, contextId, tree, emitter) {
+        this.connector = connector;
+        this.contextId = contextId;
+        this.tree = tree;
+        this.emitter = emitter;
+        this.lazyLogs = new Lazy();
+        this.errorsAllowed = false;
+    }
+    async start() {
+        await this.lazyLogs.get(async () => {
+            const logs = await PageLogs.start(this.connector, await this.tree(), this.contextId);
+            logs.on("console", (message) => this.emitter.emit("console", message));
+            logs.on("pageerror", (error) => this.emitter.emit("pageerror", error));
+            return logs;
+        });
+    }
+    /** Forgets the collection and hands back its start, for the caller to dispose; undefined when it never started */
+    take() {
+        return this.lazyLogs.take();
+    }
+    entries() {
+        return this.lazyLogs.peek()?.entries ?? [];
+    }
+    errors() {
+        return this.lazyLogs.peek()?.errors ?? [];
+    }
+    get dropped() {
+        return this.lazyLogs.peek()?.dropped ?? 0;
+    }
+    clear() {
+        this.lazyLogs.peek()?.clear();
+    }
+    allowErrors() {
+        this.errorsAllowed = true;
+    }
+    get errorsAreAllowed() {
+        return this.errorsAllowed;
+    }
+}

package/dist/browser/page-settings.d.ts

@@ -19,7 +19,7 @@ export declare class PageConfig {
         timeout?: number;
         waitUntil?: "none" | "interactive" | "complete";
     }>;
-    use(): Promise<import("../api.js").UseOptions & {
+    use(): Promise<import("../api.js").UseOptions & import("../api.js").FixtureUse & {
         viewport?: {
             width: number;
             height: number;

package/dist/browser/page-viewport.d.ts

@@ -0,0 +1,21 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+import type { PageConfig } from "./page-settings.js";
+import { type Viewport } from "./viewport.js";
+/** A page's viewport: the size it was last given and whether Chrome lays it out like a phone */
+export declare class PageViewport {
+    private readonly connector;
+    private readonly contextId;
+    private readonly config;
+    private known;
+    /** Chrome's phone layout is on (`setMobileLayout`): viewport changes keep it */
+    private mobile;
+    constructor(connector: BiDiConnector, contextId: BrowsingContext, config: PageConfig);
+    set(viewport: Viewport | null): Promise<void>;
+    setMobileLayout(): Promise<void>;
+    size(): {
+        width: number;
+        height: number;
+    } | null;
+    applyDefault(): Promise<void>;
+}

package/dist/browser/page-viewport.js

@@ -0,0 +1,33 @@
+import { DEFAULT_VIEWPORT } from "../config/defaults.js";
+import { applyViewport } from "./viewport.js";
+/** A page's viewport: the size it was last given and whether Chrome lays it out like a phone */
+export class PageViewport {
+    constructor(connector, contextId, config) {
+        this.connector = connector;
+        this.contextId = contextId;
+        this.config = config;
+        this.known = null;
+        /** Chrome's phone layout is on (`setMobileLayout`): viewport changes keep it */
+        this.mobile = false;
+    }
+    async set(viewport) {
+        await applyViewport(this.connector, this.contextId, viewport, this.mobile);
+        this.known = viewport && {
+            width: viewport.width,
+            height: viewport.height,
+        };
+    }
+    async setMobileLayout() {
+        this.mobile = true;
+        await this.set(this.known);
+    }
+    size() {
+        return this.known && { ...this.known };
+    }
+    async applyDefault() {
+        const { viewport } = await this.config.use();
+        if (viewport === null)
+            return;
+        await this.set(viewport ?? DEFAULT_VIEWPORT);
+    }
+}

package/dist/browser/page.d.ts

@@ -12,8 +12,8 @@ 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";
-import { Evidence } from "./evidence.js";
-import { type LogRecord, type PageError } from "./page-logs.js";
+import type { Evidence } from "./evidence.js";
+import type { LogRecord, PageError } from "./page-logs.js";
 import type { RouteHandler } from "../network/router.js";
 import { Response } from "../network/response.js";
 import type { NetworkMatch } from "../network/network-wait.js";
@@ -25,10 +25,10 @@ import { type PageEventName, type PageEvents, type WaitableEventName, type WaitF
 export type { PageEventName, WaitableEventName, WaitForEventOptions, WaitOptions, };
 import { type PageSettings, type ReadinessState } from "./page-settings.js";
 export type { PageSettings, ReadinessState };
-import { type Viewport } from "./viewport.js";
+import type { Viewport } from "./viewport.js";
 import type { PreloadHandle } from "../script/preload.js";
 import type { BiDiConnector } from "../transport/bidi-connection.js";
-import { type PageFunction } from "../script/call-function.js";
+import type { PageFunction } from "../script/call-function.js";
 import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
 export type { LoadState, NavigateOptions, NavigationResult };
 export default class Page {
@@ -48,15 +48,12 @@ export default class Page {
     private nav;
     private net;
     private dialogs;
-    private lazyLogs;
-    private errorsAllowed;
+    private logging;
     private isClosed;
     private browserContext;
     private transfers;
     private evidence;
-    private knownViewport;
-    /** Chrome's phone layout is on (`setMobileLayout`): viewport changes keep it */
-    private mobile;
+    private viewport;
     /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
     constructor(biDiConnector: BiDiConnector, contextId: string, settings?: PageSettings);
     /** The BiDi browsing context id of this page's top-level context */

package/dist/browser/page.js

@@ -1,16 +1,12 @@
 import Locator from "../locator/locator.js";
 import { attributeSelector, cssSelector, labelSelector, roleSelector, testIdSelector, textSelector, } from "../locator/selector.js";
 import EventEmitter from "node:events";
-import path from "node:path";
-import { projectDir } from "../config/config.js";
-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 { applyUse } from "./use-commands.js";
-import { takeScreenshot, writeOutput, } from "./screenshot.js";
-import { Evidence } from "./evidence.js";
-import { PageLogs } from "./page-logs.js";
+import { screenshotWithEvidence, } from "./screenshot.js";
+import { PageLogging } from "./page-logging.js";
 import { Lazy } from "./lazy.js";
 import { Response } from "../network/response.js";
 import { traverseHistory } from "./history.js";
@@ -24,13 +20,12 @@ 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 { startSources, waitForEventOn, waitForPageEvent, } from "./page-events.js";
 import { PageConfig, } from "./page-settings.js";
-import { applyViewport } from "./viewport.js";
+import { PageViewport } from "./page-viewport.js";
 import { HelperRealm } from "../locator/helper-realm.js";
 import { BiDiError } from "../transport/bidi-error.js";
-import { callFunction } from "../script/call-function.js";
-import { readContent } from "./page-content.js";
+import { readContent, readTitle, readUrl } from "./page-content.js";
 import { evaluateInPage } from "./page-evaluate.js";
 export default class Page {
     /** `settings` override what `samurai.config.ts` says; without them the config is read when needed */
@@ -38,12 +33,7 @@ export default class Page {
         this.lazyTree = new Lazy();
         this.initScripts = new InitScripts();
         this.pageEvents = new EventEmitter();
-        this.lazyLogs = new Lazy();
-        this.errorsAllowed = false;
         this.isClosed = false;
-        this.knownViewport = null;
-        /** 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);
@@ -52,6 +42,8 @@ export default class Page {
         this.keyboard = new Keyboard(biDiConnector, contextId, () => this.assertOpen());
         this.mouse = new Mouse(biDiConnector, contextId, () => this.assertOpen());
         this.documents = new DocumentWatcher(biDiConnector, contextId);
+        this.viewport = new PageViewport(biDiConnector, contextId, this.pageConfig);
+        this.logging = new PageLogging(biDiConnector, contextId, () => this.tree(), this.pageEvents);
         this.net = new PageNetwork(biDiConnector, contextId, {
             config: this.pageConfig,
             tree: { ensure: () => this.tree(), peek: () => this.lazyTree.peek() },
@@ -166,7 +158,7 @@ export default class Page {
             this.net.disposeTracker(),
         ]);
         const tree = this.lazyTree.take();
-        const pageLogs = this.lazyLogs.take();
+        const pageLogs = this.logging.take();
         results.push(...(await Promise.allSettled([
             tree?.then((resolved) => resolved.dispose()),
             this.documents.dispose(),
@@ -228,7 +220,7 @@ export default class Page {
     /** The URL of the page now */
     async url() {
         this.assertOpen();
-        return callFunction(this.biDiConnector, this.id, "() => location.href", [], { awaitPromise: false });
+        return readUrl(this.biDiConnector, this.id);
     }
     /**
      * Waits until the URL matches `url` (a string equals it, or with `*` / `**` is a glob; a RegExp is tested on it;
@@ -257,7 +249,7 @@ export default class Page {
     /** The title of the document now */
     async title() {
         this.assertOpen();
-        return callFunction(this.biDiConnector, this.id, "() => document.title", [], { awaitPromise: false });
+        return readTitle(this.biDiConnector, this.id);
     }
     /**
      * Runs `fn` in the page, with `arg` as its only argument, and returns the result (a promise is awaited). `fn` is a function,
@@ -280,16 +272,11 @@ export default class Page {
      */
     async setViewport(viewport) {
         this.assertOpen();
-        await applyViewport(this.biDiConnector, this.id, viewport, this.mobile);
-        this.knownViewport = viewport && {
-            width: viewport.width,
-            height: viewport.height,
-        };
+        await this.viewport.set(viewport);
     }
     /** @internal Chrome: lays this page out like a phone from now on (`use.isMobile`), including the size it has now */
     async setMobileLayout() {
-        this.mobile = true;
-        await this.setViewport(this.knownViewport);
+        await this.viewport.setMobileLayout();
     }
     /** Playwright's name for `setViewport` */
     setViewportSize(size) {
@@ -300,14 +287,11 @@ export default class Page {
      * browser opened it), read at once; null before one is known, after `setViewport(null)` and when config turns the viewport off.
      */
     viewportSize() {
-        return this.knownViewport && { ...this.knownViewport };
+        return this.viewport.size();
     }
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     async applyDefaultViewport() {
-        const { viewport } = await this.pageConfig.use();
-        if (viewport === null)
-            return;
-        await this.setViewport(viewport ?? DEFAULT_VIEWPORT);
+        await this.viewport.applyDefault();
     }
     /**
      * What the browser sets up on every page it opens: the default size, then everything that has to be listening
@@ -328,12 +312,7 @@ export default class Page {
      */
     async screenshot(options = {}) {
         this.assertOpen();
-        const image = await takeScreenshot(this.biDiConnector, this.id, options);
-        if (options.name !== undefined) {
-            const evidence = this.evidence ?? new Evidence(path.join(projectDir(), "result"));
-            await writeOutput(evidence.fileFor(options.name, options.type).file, image);
-        }
-        return image;
+        return screenshotWithEvidence(this.biDiConnector, this.id, options, this.evidence);
     }
     /** @internal The runner gives each test its own evidence folder */
     setEvidence(evidence) {
@@ -474,7 +453,7 @@ export default class Page {
             network: () => this.startNetworkTracking(),
             bodies: () => this.startBodyCollection(),
         };
-        Promise.all(sourcesFor(event).map((source) => start[source]())).catch((err) => logger.error("Could not start listening for %s", event, { err }));
+        startSources(event, start, (err) => logger.error("Could not start listening for %s", event, { err }));
     }
     /** Starts following downloads; the browser does this when it opens a page, `page.on("download")` and `waitForDownload` when needed */
     startDownloadTracking() {
@@ -515,24 +494,18 @@ export default class Page {
      *  await chooser.setFiles("./myfile.pdf");
      */
     async waitForEvent(event, optionsOrPredicate = {}) {
-        const { predicate, ...options } = typeof optionsOrPredicate === "function"
-            ? { predicate: optionsOrPredicate }
-            : optionsOrPredicate;
-        const accepts = (predicate ?? (() => true));
-        switch (event) {
-            case "request":
-                return this.waitForRequest(accepts, options);
-            case "response":
-                return this.waitForResponse(accepts, options);
-            case "download":
+        return waitForEventOn({
+            request: (accepts, options) => this.waitForRequest(accepts, options),
+            response: (accepts, options) => this.waitForResponse(accepts, options),
+            download: (options, accepts) => {
                 this.assertOpen();
                 return this.transfers.waitForDownload(options, accepts);
-            case "filechooser":
+            },
+            filechooser: (options, accepts) => {
                 this.assertOpen();
                 return this.transfers.waitForFileChooser(options, accepts);
-            default:
-                throw new Error(`waitForEvent(): "${String(event)}" is not supported; use page.on()`);
-        }
+            },
+        }, event, optionsOrPredicate);
     }
     /**
      * Starts keeping response bodies, which is what makes `response.body()` possible: the browser only keeps a body
@@ -597,27 +570,22 @@ export default class Page {
      * early output is kept; `page.on("console" | "pageerror")` starts it when needed.
      */
     async startLogging() {
-        await this.lazyLogs.get(async () => {
-            const logs = await PageLogs.start(this.biDiConnector, await this.tree(), this.id);
-            logs.on("console", (message) => this.pageEvents.emit("console", message));
-            logs.on("pageerror", (error) => this.pageEvents.emit("pageerror", error));
-            return logs;
-        });
+        await this.logging.start();
     }
     /** The newest console and error entries of this page (empty until logging started), oldest first */
     getLogs() {
-        return this.lazyLogs.peek()?.entries ?? [];
+        return this.logging.entries();
     }
     /** Uncaught exceptions of the page since logging started or `clearLogs()` */
     pageErrors() {
-        return this.lazyLogs.peek()?.errors ?? [];
+        return this.logging.errors();
     }
     /** How many entries fell out of the page's log buffer */
     get logsDropped() {
-        return this.lazyLogs.peek()?.dropped ?? 0;
+        return this.logging.dropped;
     }
     clearLogs() {
-        this.lazyLogs.peek()?.clear();
+        this.logging.clear();
     }
     /** Resolves once everything the page logged before the call has arrived: events and replies share one ordered connection */
     async syncLogs() {
@@ -625,10 +593,10 @@ export default class Page {
     }
     /** Tells the runner not to fail this test on uncaught page exceptions (config `logs.failOnPageError`) */
     allowPageErrors() {
-        this.errorsAllowed = true;
+        this.logging.allowErrors();
     }
     get pageErrorsAllowed() {
-        return this.errorsAllowed;
+        return this.logging.errorsAreAllowed;
     }
     /** Starts watching for dialogs; the browser does this when it opens a page, `page.on("dialog")` when needed */
     startDialogHandling() {

package/dist/browser/screenshot.d.ts

@@ -1,4 +1,5 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
+import { Evidence } from "./evidence.js";
 export interface ScreenshotOptions {
     /** Also write the image here (folders are created) */
     path?: string;
@@ -29,3 +30,8 @@ export declare function takeScreenshot(connector: BiDiConnector, context: string
 }): Promise<Buffer>;
 /** Writes `data` to `file`, creating the folders; nothing happens without a path */
 export declare function writeOutput(file: string | undefined, data: Buffer): Promise<void>;
+/**
+ * `page.screenshot`: `takeScreenshot`, then, with `options.name`, a copy in the evidence folder (the test's own,
+ * or `result/` of the project when the page has none)
+ */
+export declare function screenshotWithEvidence(connector: BiDiConnector, context: string, options: ScreenshotOptions, evidence: Evidence | undefined): Promise<Buffer>;

package/dist/browser/screenshot.js

@@ -2,6 +2,8 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { callFunction } from "../script/call-function.js";
 import { ElementHandle } from "../script/element-handle.js";
+import { projectDir } from "../config/config.js";
+import { Evidence } from "./evidence.js";
 const MIME = { png: "image/png", jpeg: "image/jpeg" };
 /** The `format` of a capture command; validates the type/quality combination */
 function imageFormat({ type, quality, }) {
@@ -57,3 +59,15 @@ export async function writeOutput(file, data) {
     await mkdir(path.dirname(file), { recursive: true });
     await writeFile(file, data);
 }
+/**
+ * `page.screenshot`: `takeScreenshot`, then, with `options.name`, a copy in the evidence folder (the test's own,
+ * or `result/` of the project when the page has none)
+ */
+export async function screenshotWithEvidence(connector, context, options, evidence) {
+    const image = await takeScreenshot(connector, context, options);
+    if (options.name !== undefined) {
+        const folder = evidence ?? new Evidence(path.join(projectDir(), "result"));
+        await writeOutput(folder.fileFor(options.name, options.type).file, image);
+    }
+    return image;
+}

package/dist/config/config.js

@@ -2,7 +2,7 @@ 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 { validateEnvironmentUse, validateGroupUse } from "./group-use.js";
 import { validateUseConfig } from "./use-options.js";
 import { validateForbidOnlyConfig } from "./forbid-only.js";
 import { validateRetriesConfig } from "./retries.js";
@@ -37,6 +37,7 @@ export function validateConfig(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) */

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/group-use.d.ts

@@ -1,8 +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`).
- * Throws `config.groups[1].use.locale: what is wrong`.
+ * 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;