@itmetsam/samurai-framework 0.15.1 → 0.16.0

package/dist/api.d.ts

@@ -2,5 +2,5 @@ export { test, describe, beforeEach, afterEach, beforeAll, afterAll, } from "./r
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export { defineStep, type StepDefinition, type StepResult, type StepRunInput, } from "./flows/steps/index.js";
-export type { AllHookFixtures, TestFixtures } from "./types/test.js";
+export type { AllHookFixtures, TestDetails, TestFixtures, } from "./types/test.js";
 export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/browser/browser.js

@@ -1,5 +1,6 @@
 import { setTimeout as sleep } from "node:timers/promises";
 import path from "node:path";
+import { DEFAULT_DOWNLOADS_DIR } from "../config/defaults.js";
 import { projectBrowser } from "../browsers/resolve.js";
 import Page from "./page.js";
 import { launchChrome } from "./chrome-launch.js";
@@ -77,7 +78,7 @@ export class Browser {
     /** Sets up a browser whose BiDi session is open: downloads folder, the first page and what it tracks */
     static async attach(browserProc, biDiConnector, browserName) {
         biDiConnector.browserName = browserName;
-        const downloadsDir = await prepareDownloadsDir(biDiConnector, path.resolve(projectDir(), (await readDownloadsDir()) ?? "result/downloads"));
+        const downloadsDir = await prepareDownloadsDir(biDiConnector, path.resolve(projectDir(), (await readDownloadsDir()) ?? DEFAULT_DOWNLOADS_DIR));
         // Chrome replaces a file that has the name of a download; this keeps every download
         const downloadFolders = browserName === "chrome" && downloadsDir
             ? new ChromeDownloadFolders(biDiConnector, downloadsDir)

package/dist/browser/page-network.js

@@ -1,3 +1,4 @@
+import { DEFAULT_COLLECT_BODIES, DEFAULT_TRACK_NETWORK, } from "../config/defaults.js";
 import { DataCollector, ResponseBodyUnavailableError, } from "../network/data-collector.js";
 import { NetworkTracker } from "../network/network-tracker.js";
 import { RequestTimeoutError, ResponseTimeoutError, toPredicate, } from "../network/network-wait.js";
@@ -36,14 +37,14 @@ export class PageNetwork {
     tracker() {
         return this.lazyTracker.get(async () => {
             const settings = await this.deps.config.network();
-            if (settings.track === false)
+            if ((settings.track ?? DEFAULT_TRACK_NETWORK) === false)
                 throw new NetworkTrackingDisabledError();
             const tracker = await NetworkTracker.start(this.connector, await this.deps.tree.ensure(), this.contextId);
             const { emitter } = this.deps;
             tracker.on("request", (request) => emitter.emit("request", request));
             tracker.on("response", (response) => emitter.emit("response", this.responseFor(response)));
             tracker.on("requestfailed", (failed) => emitter.emit("requestfailed", failed));
-            if (settings.collectBodies)
+            if (settings.collectBodies ?? DEFAULT_COLLECT_BODIES)
                 await this.startBodyCollection();
             return tracker;
         }, (err) => err instanceof NetworkTrackingDisabledError);

package/dist/browser/page-settings.js

@@ -1,9 +1,6 @@
 import { readConfig } from "../config/config.js";
+import { DEFAULT_IDLE_TIME, DEFAULT_NAVIGATION_TIMEOUT, DEFAULT_WAIT_UNTIL, } from "../config/defaults.js";
 import logger from "../logger/index.js";
-/** Time (ms) a navigation or a wait for a load state may take */
-const DEFAULT_NAVIGATION_TIMEOUT = 30000;
-/** Time (ms) without requests in flight that counts as idle */
-const DEFAULT_IDLE_TIME = 500;
 /** A section of the config, or `{}` when it cannot be read (a page can be used without a project) */
 async function readSection(key) {
     try {
@@ -42,7 +39,7 @@ export class PageConfig {
     }
     /** What a navigation waits for: the call's, else config `navigation.waitUntil`, else the load event */
     async navigationWait(override) {
-        return override ?? (await this.navigation()).waitUntil ?? "complete";
+        return (override ?? (await this.navigation()).waitUntil ?? DEFAULT_WAIT_UNTIL);
     }
     /** Time (ms) without requests in flight that counts as idle: the call's, else config `network.idleTime`, else 500 */
     async idleTime(override) {

package/dist/browser/page.js

@@ -3,6 +3,7 @@ import { cssSelector, labelSelector, roleSelector, testIdSelector, textSelector,
 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";
@@ -21,7 +22,7 @@ import { PageTransfers } from "./page-transfers.js";
 import { initScriptSource } from "./init-script.js";
 import { sourcesFor, waitForPageEvent, } from "./page-events.js";
 import { PageConfig, } from "./page-settings.js";
-import { applyViewport, DEFAULT_VIEWPORT } from "./viewport.js";
+import { applyViewport } from "./viewport.js";
 import { HelperRealm } from "../locator/helper-realm.js";
 import { addPreload } from "../script/preload.js";
 import { BiDiError } from "../transport/bidi-error.js";

package/dist/browser/session.d.ts

@@ -1,4 +1,4 @@
-import { type BiDiConnector } from "../transport/bidi-connection.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
 /** session.new got no reply in time */
 export declare class BrowserStartTimeoutError extends Error {
     constructor(label: string, timeout: number);

package/dist/browser/session.js

@@ -1,4 +1,4 @@
-import { DEFAULT_COMMAND_TIMEOUT, } from "../transport/bidi-connection.js";
+import { DEFAULT_COMMAND_TIMEOUT } from "../config/defaults.js";
 import { BiDiError } from "../transport/bidi-error.js";
 import { SESSION_CAPABILITIES } from "./session-capabilities.js";
 /** session.new waits at least this long (ms): the first start after an install can take a while (macOS checks the new app) */

package/dist/browser/viewport.d.ts

@@ -1,9 +1,4 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
-/** The size a page gets unless config `use.viewport` says otherwise */
-export declare const DEFAULT_VIEWPORT: {
-    width: number;
-    height: number;
-};
 /** A viewport as `page.setViewport` takes it: a size and optionally a device pixel ratio */
 export interface Viewport {
     width: number;

package/dist/browser/viewport.js

@@ -1,6 +1,4 @@
 import { callFunction } from "../script/call-function.js";
-/** The size a page gets unless config `use.viewport` says otherwise */
-export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
 /** Time (ms) without a `resize` event after which a viewport reset counts as done */
 const RESIZE_QUIET_TIME = 50;
 /** Time (ms) a viewport reset waits for a `resize` event that may never come (the size did not change) */

package/dist/capabilities.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What this framework can do, as plain data. The SAMURAI app reads it from a project's own copy
+ * of the framework to know which features that copy supports, so it asks instead of guessing.
+ * Imports nothing, so it is cheap to load; a key that is missing means the copy is too old to
+ * support it. Every value must survive `JSON.stringify`.
+ */
+export declare const CAPABILITIES: {
+    /** Test groups: a group name on a test and running one group. */
+    readonly groups: true;
+    /** The toolbar the recorder shows in the page it records. */
+    readonly recorderToolbar: true;
+    /** The recorder writing its recording to files in the project. */
+    readonly recorderFiles: true;
+    /** The flows contract version; a test keeps it equal to `FLOWS_API`. */
+    readonly flowsApi: 2;
+    /** Steps that flows can run, including project steps made with `defineStep`. */
+    readonly flowSteps: true;
+    /** Browsers the framework downloads and manages itself. */
+    readonly managedBrowsers: true;
+    /** Modifiers on tests, such as `skip`, `only` and `fixme`. */
+    readonly modifiers: true;
+    /** A reason given with a skipped test, shown in the results. */
+    readonly skipReason: true;
+    /** An id and a relative file on each test `listTests` finds, the same ids the groups use. */
+    readonly testIds: true;
+    /** `loadConfig` from `./project`: the config with every default applied, the way a run uses it. */
+    readonly resolvedConfig: true;
+    /** The recorder's first `onStatus` call, `{ state: "recording", toolbar }`, right after it starts, and a `RecordResult` with every field always present. */
+    readonly recorderStartStatus: true;
+};
+/** The shape of {@link CAPABILITIES}. */
+export type Capabilities = typeof CAPABILITIES;

package/dist/capabilities.js

@@ -0,0 +1,30 @@
+/**
+ * What this framework can do, as plain data. The SAMURAI app reads it from a project's own copy
+ * of the framework to know which features that copy supports, so it asks instead of guessing.
+ * Imports nothing, so it is cheap to load; a key that is missing means the copy is too old to
+ * support it. Every value must survive `JSON.stringify`.
+ */
+export const CAPABILITIES = {
+    /** Test groups: a group name on a test and running one group. */
+    groups: true,
+    /** The toolbar the recorder shows in the page it records. */
+    recorderToolbar: true,
+    /** The recorder writing its recording to files in the project. */
+    recorderFiles: true,
+    /** The flows contract version; a test keeps it equal to `FLOWS_API`. */
+    flowsApi: 2,
+    /** Steps that flows can run, including project steps made with `defineStep`. */
+    flowSteps: true,
+    /** Browsers the framework downloads and manages itself. */
+    managedBrowsers: true,
+    /** Modifiers on tests, such as `skip`, `only` and `fixme`. */
+    modifiers: true,
+    /** A reason given with a skipped test, shown in the results. */
+    skipReason: true,
+    /** An id and a relative file on each test `listTests` finds, the same ids the groups use. */
+    testIds: true,
+    /** `loadConfig` from `./project`: the config with every default applied, the way a run uses it. */
+    resolvedConfig: true,
+    /** The recorder's first `onStatus` call, `{ state: "recording", toolbar }`, right after it starts, and a `RecordResult` with every field always present. */
+    recorderStartStatus: true,
+};

package/dist/cli/main.js

@@ -60,7 +60,7 @@ export async function main(argv, io) {
                 io.out(`${JSON.stringify(tests, null, 2)}\n`);
             else
                 for (const found of tests)
-                    io.out(`${found.name}${found.modifier ? ` [${found.modifier}]` : ""}\n    ${found.file}\n`);
+                    io.out(`${found.name}${found.modifier ? ` [${found.modifier}${found.reason ? `: ${found.reason}` : ""}]` : ""}\n    ${found.file}\n`);
             return 0;
         }
         const human = values.json

package/dist/{runner/browsers.js → config/browsers-for.js}

@@ -1,5 +1,4 @@
-/** The browsers of a run that names none */
-const DEFAULT_BROWSERS = ["firefox"];
+import { DEFAULT_BROWSERS } from "./defaults.js";
 /**
  * The browsers a run uses, the first that is set winning: the command line, the group being run, the project, then
  * Firefox. An empty list counts as not given.

package/dist/config/config.d.ts

@@ -17,8 +17,10 @@ export declare function projectDir(): string;
  * An embedding app points it at a folder it may write to.
  */
 export declare function browsersDir(): string;
+/** Throws the error a run throws for a config with a bad key */
+export declare function validateConfig(config: SamuraiTestConfig): void;
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
-export declare function loadConfig(): Promise<SamuraiTestConfig>;
+export declare function loadRawConfig(): Promise<SamuraiTestConfig>;
 /** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
 export declare function projectConfig(options: {
     projectDir?: string;

package/dist/config/config.js

@@ -24,13 +24,17 @@ export function browsersDir() {
         activeProject?.dataDir ??
         path.join(projectDir(), "browsers"));
 }
+/** Throws the error a run throws for a config with a bad key */
+export function validateConfig(config) {
+    validateBrowserConfig(config);
+    validateWorkersConfig(config);
+    validateForbidOnlyConfig(config);
+    validateRetriesConfig(config);
+}
 /** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
-export async function loadConfig() {
+export async function loadRawConfig() {
     if (activeProject?.config) {
-        validateBrowserConfig(activeProject.config);
-        validateWorkersConfig(activeProject.config);
-        validateForbidOnlyConfig(activeProject.config);
-        validateRetriesConfig(activeProject.config);
+        validateConfig(activeProject.config);
         return activeProject.config;
     }
     const configUrl = path.join(projectDir(), "samurai.config.ts");
@@ -39,10 +43,7 @@ export async function loadConfig() {
     if (!config.default) {
         throw new Error("samurai.config.ts does not export defineConfig as default!");
     }
-    validateBrowserConfig(config.default);
-    validateWorkersConfig(config.default);
-    validateForbidOnlyConfig(config.default);
-    validateRetriesConfig(config.default);
+    validateConfig(config.default);
     return config.default;
 }
 /** A project's config without keeping the project active (`withProject` is one at a time): the given one, else its samurai.config.ts */
@@ -52,14 +53,14 @@ export async function projectConfig(options) {
     const previous = activeProject;
     setActiveProject({ dir: path.resolve(options.projectDir ?? process.cwd()) });
     try {
-        return await loadConfig();
+        return await loadRawConfig();
     }
     finally {
         setActiveProject(previous);
     }
 }
 export async function readConfig(key) {
-    const value = (await loadConfig())[key];
+    const value = (await loadRawConfig())[key];
     logger.debug("Resolved config value: ", { value });
     return value;
 }

package/dist/config/defaults.d.ts

@@ -0,0 +1,41 @@
+/** The test folder when the config names none */
+export declare const DEFAULT_SRC_DIR = "./src";
+/** The spec pattern when a group names none */
+export declare const DEFAULT_TEST_MATCH = "**/*.spec.ts";
+/** The browsers of a run that names none */
+export declare const DEFAULT_BROWSERS: readonly ["firefox"];
+/** Time (ms) a test may take */
+export declare const DEFAULT_TIMEOUT = 30000;
+/** The retry time of actions and assertions when nothing sets one (ms) */
+export declare const DEFAULT_EXPECT_TIMEOUT = 5000;
+/** Time (ms) a navigation or a wait for a load state may take */
+export declare const DEFAULT_NAVIGATION_TIMEOUT = 30000;
+/** What a navigation waits for when nothing says otherwise: the load event */
+export declare const DEFAULT_WAIT_UNTIL = "complete";
+/** Time (ms) a command may wait for its reply before it fails with code "timeout" */
+export declare const DEFAULT_COMMAND_TIMEOUT = 30000;
+/** Time (ms) without requests in flight that counts as idle */
+export declare const DEFAULT_IDLE_TIME = 500;
+/** Time (ms) a handler may take to answer a request before the router lets it continue */
+export declare const DEFAULT_ROUTE_TIMEOUT = 30000;
+/** How large a response body may be to be kept: 10 MiB */
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+/** Whether response bodies are collected for every request */
+export declare const DEFAULT_COLLECT_BODIES = false;
+/** Whether the network of a page is tracked */
+export declare const DEFAULT_TRACK_NETWORK = true;
+/** The size a page gets unless config `use.viewport` says otherwise */
+export declare const DEFAULT_VIEWPORT: {
+    width: number;
+    height: number;
+};
+/** Where downloads are saved, relative to the project */
+export declare const DEFAULT_DOWNLOADS_DIR = "result/downloads";
+/** The files folder, relative to the project */
+export declare const DEFAULT_FILES_DIR = "files";
+/** How many times a failing test is run again */
+export declare const DEFAULT_RETRIES = 0;
+/** Which page log entries go in the report: those of failed tests */
+export declare const DEFAULT_LOGS_CAPTURE = "failures";
+/** Whether uncaught page errors fail a test */
+export declare const DEFAULT_FAIL_ON_PAGE_ERROR = false;

package/dist/config/defaults.js

@@ -0,0 +1,38 @@
+/** The test folder when the config names none */
+export const DEFAULT_SRC_DIR = "./src";
+/** The spec pattern when a group names none */
+export const DEFAULT_TEST_MATCH = "**/*.spec.ts";
+/** The browsers of a run that names none */
+export const DEFAULT_BROWSERS = ["firefox"];
+/** Time (ms) a test may take */
+export const DEFAULT_TIMEOUT = 30000;
+/** The retry time of actions and assertions when nothing sets one (ms) */
+export const DEFAULT_EXPECT_TIMEOUT = 5000;
+/** Time (ms) a navigation or a wait for a load state may take */
+export const DEFAULT_NAVIGATION_TIMEOUT = 30000;
+/** What a navigation waits for when nothing says otherwise: the load event */
+export const DEFAULT_WAIT_UNTIL = "complete";
+/** Time (ms) a command may wait for its reply before it fails with code "timeout" */
+export const DEFAULT_COMMAND_TIMEOUT = 30000;
+/** Time (ms) without requests in flight that counts as idle */
+export const DEFAULT_IDLE_TIME = 500;
+/** Time (ms) a handler may take to answer a request before the router lets it continue */
+export const DEFAULT_ROUTE_TIMEOUT = 30000;
+/** How large a response body may be to be kept: 10 MiB */
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
+/** Whether response bodies are collected for every request */
+export const DEFAULT_COLLECT_BODIES = false;
+/** Whether the network of a page is tracked */
+export const DEFAULT_TRACK_NETWORK = true;
+/** The size a page gets unless config `use.viewport` says otherwise */
+export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+/** Where downloads are saved, relative to the project */
+export const DEFAULT_DOWNLOADS_DIR = "result/downloads";
+/** The files folder, relative to the project */
+export const DEFAULT_FILES_DIR = "files";
+/** How many times a failing test is run again */
+export const DEFAULT_RETRIES = 0;
+/** Which page log entries go in the report: those of failed tests */
+export const DEFAULT_LOGS_CAPTURE = "failures";
+/** Whether uncaught page errors fail a test */
+export const DEFAULT_FAIL_ON_PAGE_ERROR = false;

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

@@ -0,0 +1,106 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { SamuraiGroup, SamuraiTestConfig } from "../types/config.js";
+import { type Variables } from "./run-settings.js";
+/** Where the environment variables come from: `CI` and the like */
+type Env = Record<string, string | undefined>;
+/** One environment with the project's values and the built-in defaults merged in, as a run without overrides uses it */
+export interface ResolvedEnvironment {
+    baseURL?: string;
+    /** Time (ms) one test may take */
+    timeout: number;
+    /** Time (ms) actions and assertions retry */
+    expectTimeout: number;
+    /** Whether the browser runs without a window */
+    headless: boolean;
+    variables: Variables;
+}
+/** An entry of `logs.ignoreErrors` as data: a `RegExp` keeps its source and flags */
+export interface ResolvedIgnoreError {
+    text: string;
+    regexp: boolean;
+    flags?: string;
+}
+/**
+ * A project's config with every default applied and the run-level precedence resolved: what a run without command
+ * line flags uses. Plain JSON data, so it survives `process.send`.
+ */
+export interface ResolvedConfig {
+    /** The project folder, absolute */
+    projectDir: string;
+    /** The test folder, absolute and not resolved through symlinks: use `FoundTest.relativeFile` rather than computing paths against it */
+    srcDir: string;
+    /** The test folder as the config writes it */
+    srcDirRelative: string;
+    browsers: SupportedBrowser[];
+    browserPaths: {
+        firefox?: string;
+        chrome?: string;
+    };
+    timeout: number;
+    expectTimeout: number;
+    navigationTimeout: number;
+    waitUntil: "none" | "interactive" | "complete";
+    bidiCommandTimeout: number;
+    /** The config's `workers` as written */
+    workers?: number | string;
+    /** The workers a run without `--workers` and `SAMURAI_WORKERS` uses on this machine */
+    workersResolved: number;
+    retries: number;
+    forbidOnly: boolean;
+    headless: boolean;
+    /** `null` keeps the browser's own size */
+    viewport: {
+        width: number;
+        height: number;
+    } | null;
+    downloadsDir: string;
+    filesDir: string;
+    logs: {
+        capture: "off" | "failures" | "all";
+        failOnPageError: boolean;
+        ignoreErrors: ResolvedIgnoreError[];
+    };
+    network: {
+        track: boolean;
+        idleTime: number;
+        routeTimeout: number;
+        collectBodies: boolean;
+        maxBodySize: number;
+    };
+    /** The project's `baseURL` */
+    baseURL?: string;
+    /** The config's `defaultEnvironment` as written */
+    defaultEnvironment?: string;
+    /** Why a run without `--env` would stop: no environment chosen, or an unknown `defaultEnvironment` */
+    environmentProblem?: string;
+    /** Every environment by name; a config without `environments` has one, `"default"` */
+    environments: Record<string, ResolvedEnvironment>;
+    /** The groups as written, each with the browsers it runs in */
+    groups: (SamuraiGroup & {
+        browsers: SupportedBrowser[];
+    })[];
+    /** The kinds of the project's own flow steps */
+    steps: string[];
+}
+/**
+ * The config with every default applied, from the same constants and functions a run uses. Throws the errors a run
+ * throws for a bad config; an environment a run could not choose is reported in `environmentProblem` instead.
+ * Pure: reads no files.
+ */
+export declare function resolveConfig(config: SamuraiTestConfig, options: {
+    projectDir: string;
+    env: Env;
+}): ResolvedConfig;
+/**
+ * A project's `samurai.config.ts` with every default applied, the way a run uses it (see {@link ResolvedConfig}).
+ * Leaves no project active. The caller registers `tsx` first (the framework does not), so the config file can be
+ * imported; an app does that in the child process that calls this. The config module is imported once per process
+ * (Node caches it): a later edit to `samurai.config.ts` is seen only in a new process.
+ * @param options.projectDir The project folder. @default the working directory
+ * @param options.env Where `CI` is read from. @default `process.env`
+ */
+export declare function loadConfig(options?: {
+    projectDir?: string;
+    env?: Env;
+}): Promise<ResolvedConfig>;
+export {};

package/dist/config/resolved-config.js

@@ -0,0 +1,112 @@
+import path from "node:path";
+import { browsersFor } from "./browsers-for.js";
+import { projectConfig, validateConfig } from "./config.js";
+import { DEFAULT_COLLECT_BODIES, DEFAULT_COMMAND_TIMEOUT, DEFAULT_DOWNLOADS_DIR, DEFAULT_FAIL_ON_PAGE_ERROR, DEFAULT_FILES_DIR, DEFAULT_IDLE_TIME, DEFAULT_LOGS_CAPTURE, DEFAULT_MAX_BODY_SIZE, DEFAULT_NAVIGATION_TIMEOUT, DEFAULT_RETRIES, DEFAULT_ROUTE_TIMEOUT, DEFAULT_SRC_DIR, DEFAULT_TRACK_NETWORK, DEFAULT_VIEWPORT, DEFAULT_WAIT_UNTIL, } from "./defaults.js";
+import { forbidsOnly } from "./forbid-only.js";
+import { IMPLICIT_ENVIRONMENT, resolveRunSettings, UnknownEnvironmentError, } from "./run-settings.js";
+import { resolveWorkers } from "./workers-option.js";
+/** The message a run without `--env` throws for this config, if any */
+function environmentProblem(config, env) {
+    try {
+        resolveRunSettings(config, {}, env);
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof UnknownEnvironmentError)
+            return error.message;
+        throw error;
+    }
+}
+/** Every environment of the config merged the way `resolveRunSettings` merges it */
+function resolveEnvironments(config, env) {
+    const names = Object.keys(config.environments ?? {});
+    return Object.fromEntries((names.length > 0 ? names : [IMPLICIT_ENVIRONMENT]).map((name) => {
+        const { environment, ...settings } = resolveRunSettings(config, { environment: name }, env);
+        return [environment, settings];
+    }));
+}
+/** `logs.ignoreErrors` as JSON-safe data */
+function ignoreErrorsOf(list = []) {
+    return list.map((entry) => typeof entry === "string"
+        ? { text: entry, regexp: false }
+        : {
+            text: entry.source,
+            regexp: true,
+            ...(entry.flags !== "" && { flags: entry.flags }),
+        });
+}
+/**
+ * The config with every default applied, from the same constants and functions a run uses. Throws the errors a run
+ * throws for a bad config; an environment a run could not choose is reported in `environmentProblem` instead.
+ * Pure: reads no files.
+ */
+export function resolveConfig(config, options) {
+    validateConfig(config);
+    const { env } = options;
+    const projectDir = path.resolve(options.projectDir);
+    const srcDirRelative = config.srcDir ?? DEFAULT_SRC_DIR;
+    // The project level: the same precedence without an environment
+    const project = resolveRunSettings({ ...config, environments: undefined, defaultEnvironment: undefined }, {}, env);
+    const problem = environmentProblem(config, env);
+    const viewport = config.use?.viewport;
+    return {
+        projectDir,
+        srcDir: path.resolve(projectDir, srcDirRelative),
+        srcDirRelative,
+        browsers: browsersFor({ project: config.browsers }),
+        browserPaths: { ...config.browserPaths },
+        timeout: project.timeout,
+        expectTimeout: project.expectTimeout,
+        navigationTimeout: config.navigation?.timeout ?? DEFAULT_NAVIGATION_TIMEOUT,
+        waitUntil: config.navigation?.waitUntil ?? DEFAULT_WAIT_UNTIL,
+        bidiCommandTimeout: config.bidi?.commandTimeout ?? DEFAULT_COMMAND_TIMEOUT,
+        ...(config.workers !== undefined && { workers: config.workers }),
+        workersResolved: resolveWorkers({ config: config.workers }),
+        // 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),
+        headless: project.headless,
+        viewport: viewport === null ? null : { ...(viewport ?? DEFAULT_VIEWPORT) },
+        downloadsDir: config.downloadsDir ?? DEFAULT_DOWNLOADS_DIR,
+        filesDir: config.filesDir ?? DEFAULT_FILES_DIR,
+        logs: {
+            capture: config.logs?.capture ?? DEFAULT_LOGS_CAPTURE,
+            failOnPageError: config.logs?.failOnPageError ?? DEFAULT_FAIL_ON_PAGE_ERROR,
+            ignoreErrors: ignoreErrorsOf(config.logs?.ignoreErrors),
+        },
+        network: {
+            track: config.network?.track ?? DEFAULT_TRACK_NETWORK,
+            idleTime: config.network?.idleTime ?? DEFAULT_IDLE_TIME,
+            routeTimeout: config.network?.routeTimeout ?? DEFAULT_ROUTE_TIMEOUT,
+            collectBodies: config.network?.collectBodies ?? DEFAULT_COLLECT_BODIES,
+            maxBodySize: config.network?.maxBodySize ?? DEFAULT_MAX_BODY_SIZE,
+        },
+        ...(config.baseURL !== undefined && { baseURL: config.baseURL }),
+        ...(config.defaultEnvironment !== undefined && {
+            defaultEnvironment: config.defaultEnvironment,
+        }),
+        ...(problem !== undefined && { environmentProblem: problem }),
+        environments: resolveEnvironments(config, env),
+        groups: (config.groups ?? []).map((group) => ({
+            ...group,
+            browsers: browsersFor({
+                group: group.browsers,
+                project: config.browsers,
+            }),
+        })),
+        steps: (config.steps ?? []).map((step) => step.kind),
+    };
+}
+/**
+ * A project's `samurai.config.ts` with every default applied, the way a run uses it (see {@link ResolvedConfig}).
+ * Leaves no project active. The caller registers `tsx` first (the framework does not), so the config file can be
+ * imported; an app does that in the child process that calls this. The config module is imported once per process
+ * (Node caches it): a later edit to `samurai.config.ts` is seen only in a new process.
+ * @param options.projectDir The project folder. @default the working directory
+ * @param options.env Where `CI` is read from. @default `process.env`
+ */
+export async function loadConfig(options = {}) {
+    const projectDir = path.resolve(options.projectDir ?? process.cwd());
+    const config = await projectConfig({ projectDir });
+    return resolveConfig(config, { projectDir, env: options.env ?? process.env });
+}

package/dist/config/run-settings.d.ts

@@ -20,6 +20,8 @@ export interface RunSettings {
     /** Whether the browser runs without a window */
     headless: boolean;
 }
+/** The environment of a config without `environments` */
+export declare const IMPLICIT_ENVIRONMENT = "default";
 export declare class UnknownEnvironmentError extends Error {
     constructor(message: string);
 }

package/dist/config/run-settings.js

@@ -1,7 +1,6 @@
-const DEFAULT_TIMEOUT = 30000;
-const DEFAULT_EXPECT_TIMEOUT = 5000;
+import { DEFAULT_EXPECT_TIMEOUT, DEFAULT_TIMEOUT } from "./defaults.js";
 /** The environment of a config without `environments` */
-const IMPLICIT_ENVIRONMENT = "default";
+export const IMPLICIT_ENVIRONMENT = "default";
 export class UnknownEnvironmentError extends Error {
     constructor(message) {
         super(message);

package/dist/config/timeouts.js

@@ -1,7 +1,6 @@
 import { readConfig } from "./config.js";
+import { DEFAULT_EXPECT_TIMEOUT } from "./defaults.js";
 import { peekRunSettings } from "./run-settings.js";
-/** The retry time of actions and assertions when nothing sets one (ms) */
-const DEFAULT_EXPECT_TIMEOUT = 5000;
 /** Per-call timeout, else the active run's expect timeout, else config `expect.timeout`, else 5000 */
 export async function resolveTimeout(perCall) {
     if (perCall !== undefined)

package/dist/{runner → config}/workers-option.js

@@ -1,5 +1,5 @@
 import { availableParallelism } from "node:os";
-import { parseWorkers } from "../config/workers.js";
+import { parseWorkers } from "./workers.js";
 /**
  * How many workers a run uses: the flag, else `SAMURAI_WORKERS`, else the config's `workers`, else half the CPUs.
  * A percentage is a share of the CPUs. At least 1.

package/dist/flows/run/project.js

@@ -1,12 +1,13 @@
 import path from "node:path";
+import { DEFAULT_SRC_DIR } from "../../config/defaults.js";
 import { projectConfig } from "../../config/config.js";
 import { checkFlow, withKeys, } from "../core/index.js";
-import { DEFAULT_SRC_DIR, realPath, resolveGroups, testId, toPosix, } from "../../runner/groups.js";
+import { realPath, resolveGroups, testId, toPosix, } from "../../runner/groups.js";
 import logger, { keepLogFiles } from "../../logger/index.js";
 import { resolveRetries } from "../../runner/retries-option.js";
-import { resolveWorkers } from "../../runner/workers-option.js";
+import { resolveWorkers } from "../../config/workers-option.js";
 import { withProject } from "../../runner/project.js";
-import { browsersFor } from "../../runner/browsers.js";
+import { browsersFor } from "../../config/browsers-for.js";
 import { DEFAULT_PORT } from "../../runner/ports.js";
 import { runTests } from "../../runner/run.js";
 import TestRunner from "../../runner/test-runner.js";
@@ -84,7 +85,7 @@ async function prepare(options) {
         ...(options.dataDir !== undefined && { dataDir: options.dataDir }),
         environment: name,
     }, async (run) => {
-        const found = await (await TestRunner.init(run)).register();
+        const { tests: found } = await (await TestRunner.init(run)).list();
         const tests = found.map((t) => ({
             id: testId(toPosix(path.relative(srcDir, t.file)), t.name),
             file: t.file,

package/dist/network/data-collector.js

@@ -1,6 +1,5 @@
+import { DEFAULT_MAX_BODY_SIZE } from "../config/defaults.js";
 import { BiDiError } from "../transport/bidi-error.js";
-/** How large a response body may be to be kept: 10 MiB */
-const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
 /**
  * Chrome counts the headers of a response in the size it compares with the collector's limit (a 14-byte body
  * arrives as about 200 bytes), Firefox counts the body. Chrome's limit is raised by this much and the body is