@itmetsam/samurai-framework 0.12.1 → 0.15.0

package/README.md

@@ -19,12 +19,12 @@ test("Visitor can sign in", async ({ page, env, secrets }) => {
 - **Auto-waiting.** Actions wait until the element is attached, visible, stable, enabled and not covered. Assertions retry until they pass or time out.
 - **Semantic locators.** By role, label, text, test id, CSS or XPath, with ordered fallbacks.
 - **Environments and secrets.** One test file runs against `dev`, `staging` or `production`; secrets come from the environment or a `.env.<name>` file and are masked in logs and reports.
-- **Parallel runs.** Tests run side by side in worker processes (`--workers`, `workers` in the config; half the CPUs by default), and a flow's Parallel node runs its branches at the same time (see [Running tests and reports](docs/running-and-reports.md#parallel-runs)).
+- **Parallel runs.** Tests run side by side in worker processes (`--workers`, `workers` in the config; half the CPUs by default), and a flow's Parallel node runs its branches at the same time (see [Running tests and reports](https://github.com/degrootsam/samurai-framework/wiki/Running-tests-and-reports#parallel-runs)).
 - **Network control.** Mock, block or modify requests; wait for requests, responses and network idle; read response bodies.
-- **Flows.** Chain tests and groups into a graph with conditions, variables, waits and HTTP requests, and run it from the command line or CI (see [Flows](docs/flows.md)).
-- **Recorder building blocks.** Specs are parsed into steps and edited back with minimal diffs, and an engine records what a person does in the browser. A toolbar in the recorded page adds assertions, variables and secrets, waits, screenshots and pause (see [Steps and the recorder](docs/recorder.md)). The Electron app that ties them together lives in a separate repository (see the [roadmap](docs/roadmap.md)).
+- **Flows.** Chain tests and groups into a graph with conditions, variables, waits and HTTP requests, and run it from the command line or CI (see [Flows](https://github.com/degrootsam/samurai-framework/wiki/Flows)).
+- **Recorder building blocks.** Specs are parsed into steps and edited back with minimal diffs, and an engine records what a person does in the browser. A toolbar in the recorded page adds assertions, variables and secrets, waits, screenshots and pause (see [Steps and the recorder](https://github.com/degrootsam/samurai-framework/wiki/Steps-and-the-recorder)). The Electron app that ties them together lives in a separate repository (see the [roadmap](https://github.com/degrootsam/samurai-framework/wiki/Roadmap)).
 
-> **Status:** early. Firefox only. See [what is still open](docs/roadmap.md).
+> **Status:** early. Firefox only. See [what is still open](https://github.com/degrootsam/samurai-framework/wiki/Roadmap).
 
 ## Getting started
 
@@ -39,14 +39,14 @@ npx samurai browsers install firefox             # once per machine
 npx samurai run
 ```
 
-Specs and the config then import from `@itmetsam/samurai-framework` instead of the relative paths used below. See [Command line](docs/cli.md).
+Specs and the config then import from `@itmetsam/samurai-framework` instead of the relative paths used below. See [Command line](https://github.com/degrootsam/samurai-framework/wiki/Command-line).
 
 The rest of this section works in a checkout of this repository.
 
 ### 1. Requirements
 
 - [Node.js](https://nodejs.org) 24 or newer (`engines` in `package.json`; CI uses 26) and, to work on the framework, [Bun](https://bun.sh) 1.3 or newer
-- Firefox, downloaded by the framework: run `bun run dev browsers install firefox` once in this checkout (`npx samurai browsers install firefox` in a project; see [Which browser runs](docs/pages-and-browsers.md#which-browser-runs)). The Firefox installed on the machine is not used.
+- Firefox, downloaded by the framework: run `bun run dev browsers install firefox` once in this checkout (`npx samurai browsers install firefox` in a project; see [Which browser runs](https://github.com/degrootsam/samurai-framework/wiki/Pages-and-browsers#which-browser-runs)). The Firefox installed on the machine is not used.
 
 ### 2. Install
 
@@ -103,13 +103,13 @@ bun run dev --env production   # another environment (or SAMURAI_ENV=production)
 bun run dev --timeout 60000    # per-test timeout in ms; also --expect-timeout
 ```
 
-`bun run dev` is `samurai run` straight from the sources, so it takes the same options (`--grep`, `--file`, `--group`, `--headless`, `--json`, …) and the other commands too (`bun run dev list`, `bun run dev browsers install firefox`). See [Command line](docs/cli.md).
+`bun run dev` is `samurai run` straight from the sources, so it takes the same options (`--grep`, `--file`, `--group`, `--headless`, `--json`, …) and the other commands too (`bun run dev list`, `bun run dev browsers install firefox`). See [Command line](https://github.com/degrootsam/samurai-framework/wiki/Command-line).
 
-A browser window opens for each test and closes when the test ends (`--headless` hides it; on CI it is the default, see [Configuration](docs/configuration.md#headless)). Each test's result is printed as it finishes, followed by a summary, and the full report is written to `result/report.json`. The process exits with code 0 when every test passed, 1 otherwise and 2 for a usage or configuration error. Framework logs go to stderr and `logs/`.
+A browser window opens for each test and closes when the test ends (`--headless` hides it; on CI it is the default, see [Configuration](https://github.com/degrootsam/samurai-framework/wiki/Configuration#headless)). Each test's result is printed as it finishes, followed by a summary, and the full report is written to `result/report.json`. The process exits with code 0 when every test passed, 1 otherwise and 2 for a usage or configuration error. Framework logs go to stderr and `logs/`.
 
 ### Flows (optional)
 
-A project can also keep flows in `flows/*.flow.json` (edited in the Samurai app) that chain tests and groups with conditions and variables. `samurai flow check` validates them and `samurai flow run <flow>` runs them, with a report in `result/flows/`. See [Flows](docs/flows.md).
+A project can also keep flows in `flows/*.flow.json` (edited in the Samurai app) that chain tests and groups with conditions and variables. `samurai flow check` validates them and `samurai flow run <flow>` runs them, with a report in `result/flows/`. See [Flows](https://github.com/degrootsam/samurai-framework/wiki/Flows).
 
 ### 6. Secrets (optional)
 
@@ -119,29 +119,29 @@ cp .env.example .env.staging
 # SAMURAI_SECRET_TEST_PASSWORD=...
 ```
 
-Read it in a test as `secrets.TEST_PASSWORD`. Real environment variables win over the file, and `.env.*` files are git-ignored. See [Environments and secrets](docs/environments-and-secrets.md).
+Read it in a test as `secrets.TEST_PASSWORD`. Real environment variables win over the file, and `.env.*` files are git-ignored. See [Environments and secrets](https://github.com/degrootsam/samurai-framework/wiki/Environments-and-secrets).
 
 ## Documentation
 
-| Guide                                                        | What it covers                                                                                        |
-| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
-| [Writing tests](docs/writing-tests.md)                       | `test`, `describe`, fixtures, how a test passes or fails                                              |
-| [Locators](docs/locators.md)                                 | Finding elements, chaining, fallbacks, actions and their auto-waiting                                 |
-| [Assertions](docs/assertions.md)                             | `expect` for elements and for plain values                                                            |
-| [Pages and browsers](docs/pages-and-browsers.md)             | Navigation, waits, screenshots, PDF, viewport, emulation, dialogs, downloads, contexts, cookies       |
-| [Network](docs/network.md)                                   | Waiting for traffic, mocking, blocking, response bodies                                               |
-| [Configuration](docs/configuration.md)                       | Every option in `samurai.config.ts`, CLI flags and precedence                                         |
-| [Environments and secrets](docs/environments-and-secrets.md) | Per-environment settings, variables, secrets and masking                                              |
-| [Command line](docs/cli.md)                                  | `samurai run`, `list`, `record` and `init`, options, output, exit codes, `--json`                     |
-| [Flows](docs/flows.md)                                       | `samurai flow list`, `check` and `run`: graphs of tests, groups and steps, reports, CI                |
-| [Writing a step](docs/steps.md)                              | `defineStep`: flow steps of your own, the built-in steps                                              |
-| [Running tests and reports](docs/running-and-reports.md)     | What a run does, `report.json`, page logs, timeouts                                                   |
-| [Steps and the recorder](docs/recorder.md)                   | The step codec, the recording engine and the recorder toolbar                                         |
-| [Embedding the framework](docs/embedding.md)                 | Using the package from another app (such as the Electron UI): build, entry points, `runTests`, events |
-| [Contributing](docs/contributing.md)                         | Project layout, running the framework's own tests, conventions                                        |
-| [Roadmap](docs/roadmap.md)                                   | What is built and what is still open                                                                  |
-
-The [documentation index](docs/README.md) lists every guide by topic.
+| Guide                                                                                                       | What it covers                                                                                        |
+| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| [Writing tests](https://github.com/degrootsam/samurai-framework/wiki/Writing-tests)                         | `test`, `describe`, fixtures, how a test passes or fails                                              |
+| [Locators](https://github.com/degrootsam/samurai-framework/wiki/Locators)                                   | Finding elements, chaining, fallbacks, actions and their auto-waiting                                 |
+| [Assertions](https://github.com/degrootsam/samurai-framework/wiki/Assertions)                               | `expect` for elements and for plain values                                                            |
+| [Pages and browsers](https://github.com/degrootsam/samurai-framework/wiki/Pages-and-browsers)               | Navigation, waits, screenshots, PDF, viewport, emulation, dialogs, downloads, contexts, cookies       |
+| [Network](https://github.com/degrootsam/samurai-framework/wiki/Network)                                     | Waiting for traffic, mocking, blocking, response bodies                                               |
+| [Configuration](https://github.com/degrootsam/samurai-framework/wiki/Configuration)                         | Every option in `samurai.config.ts`, CLI flags and precedence                                         |
+| [Environments and secrets](https://github.com/degrootsam/samurai-framework/wiki/Environments-and-secrets)   | Per-environment settings, variables, secrets and masking                                              |
+| [Command line](https://github.com/degrootsam/samurai-framework/wiki/Command-line)                           | `samurai run`, `list`, `record` and `init`, options, output, exit codes, `--json`                     |
+| [Flows](https://github.com/degrootsam/samurai-framework/wiki/Flows)                                         | `samurai flow list`, `check` and `run`: graphs of tests, groups and steps, reports, CI                |
+| [Writing a step](https://github.com/degrootsam/samurai-framework/wiki/Writing-a-step)                       | `defineStep`: flow steps of your own, the built-in steps                                              |
+| [Running tests and reports](https://github.com/degrootsam/samurai-framework/wiki/Running-tests-and-reports) | What a run does, `report.json`, page logs, timeouts                                                   |
+| [Steps and the recorder](https://github.com/degrootsam/samurai-framework/wiki/Steps-and-the-recorder)       | The step codec, the recording engine and the recorder toolbar                                         |
+| [Embedding the framework](https://github.com/degrootsam/samurai-framework/wiki/Embedding-the-framework)     | Using the package from another app (such as the Electron UI): build, entry points, `runTests`, events |
+| [Contributing](docs/contributing.md)                                                                        | Project layout, running the framework's own tests, conventions                                        |
+| [Roadmap](https://github.com/degrootsam/samurai-framework/wiki/Roadmap)                                     | What is built and what is still open                                                                  |
+
+The [documentation index](https://github.com/degrootsam/samurai-framework/wiki/Home) lists every guide by topic.
 
 ## Scripts
 

package/dist/api.d.ts

@@ -1,6 +1,6 @@
-export { test, describe } from "./runner/registry.js";
+export { test, describe, beforeEach, afterEach, beforeAll, afterAll, } from "./runner/registry.js";
 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 { TestFixtures } from "./types/test.js";
+export type { AllHookFixtures, TestFixtures } from "./types/test.js";
 export { generatedFile, type GeneratedFile, type FileInput, } from "./browser/generated-files.js";

package/dist/api.js

@@ -1,4 +1,4 @@
-export { test, describe } from "./runner/registry.js";
+export { test, describe, beforeEach, afterEach, beforeAll, afterAll, } from "./runner/registry.js";
 export { expect } from "./assert/expect.js";
 export { defineConfig } from "./config/config.js";
 export { defineStep, } from "./flows/steps/index.js";

package/dist/cli/console-reporter.js

@@ -32,12 +32,15 @@ export class ConsoleReporter {
         const took = "duration" in result
             ? ` ${this.paint(90, `(${seconds(result.duration)})`)}`
             : "";
+        if (result.status === "skipped")
+            return this.paint(90, `- ${name}${this.tag(browser)} (${result.annotation === "fixme" ? "fixme" : "skipped"}${result.reason ? `: ${result.reason}` : ""})`);
         return result.status === "success"
             ? `${this.paint(32, "✔")} ${name}${this.tag(browser)}${took}`
             : `${this.paint(31, "✖")} ${name}${this.tag(browser)}${took}`;
     }
     summary(summary) {
-        const failed = summary.tests.filter((test) => test.status !== "success");
+        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) {
             if (!("name" in test))
                 continue;
@@ -50,10 +53,11 @@ export class ConsoleReporter {
             if ("file" in test)
                 this.write(`    ${this.paint(90, test.file)}\n`);
         }
-        const passed = summary.tests.length - failed.length;
+        const passed = summary.tests.length - failed.length - skipped.length;
         const parts = [
             failed.length > 0 && this.paint(31, `${failed.length} failed`),
             this.paint(32, `${passed} passed`),
+            skipped.length > 0 && this.paint(90, `${skipped.length} skipped`),
         ].filter(Boolean);
         this.write(`\n${parts.join(", ")} ${this.paint(90, `(${seconds(summary.duration)})`)}\n`);
     }

package/dist/cli/main.js

@@ -59,7 +59,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}\n    ${found.file}\n`);
+                    io.out(`${found.name}${found.modifier ? ` [${found.modifier}]` : ""}\n    ${found.file}\n`);
             return 0;
         }
         const human = values.json

package/dist/config/config.js

@@ -2,6 +2,7 @@ import path from "path";
 import logger from "../logger/index.js";
 import { pathToFileURL } from "url";
 import { validateBrowserConfig } from "./browsers.js";
+import { validateForbidOnlyConfig } from "./forbid-only.js";
 import { validateWorkersConfig } from "./workers.js";
 let activeProject;
 /** Makes `project` the one config, secrets, reports and downloads are resolved for; `undefined` ends it */
@@ -27,6 +28,7 @@ export async function loadConfig() {
     if (activeProject?.config) {
         validateBrowserConfig(activeProject.config);
         validateWorkersConfig(activeProject.config);
+        validateForbidOnlyConfig(activeProject.config);
         return activeProject.config;
     }
     const configUrl = path.join(projectDir(), "samurai.config.ts");
@@ -37,6 +39,7 @@ export async function loadConfig() {
     }
     validateBrowserConfig(config.default);
     validateWorkersConfig(config.default);
+    validateForbidOnlyConfig(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 */

package/dist/config/forbid-only.d.ts

@@ -0,0 +1,5 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+/** Checks the `forbidOnly` key of a config. Throws an Error that names the key */
+export declare function validateForbidOnlyConfig(config: SamuraiTestConfig): void;
+/** Whether `test.only` is refused: the config's `forbidOnly`, else on when `CI` is set */
+export declare function forbidsOnly(config: SamuraiTestConfig, env?: Partial<NodeJS.ProcessEnv>): boolean;

package/dist/config/forbid-only.js

@@ -0,0 +1,9 @@
+/** Checks the `forbidOnly` key of a config. Throws an Error that names the key */
+export function validateForbidOnlyConfig(config) {
+    if (config.forbidOnly !== undefined && typeof config.forbidOnly !== "boolean")
+        throw new Error(`forbidOnly must be true or false, got "${String(config.forbidOnly)}"`);
+}
+/** Whether `test.only` is refused: the config's `forbidOnly`, else on when `CI` is set */
+export function forbidsOnly(config, env = process.env) {
+    return config.forbidOnly ?? Boolean(env.CI);
+}

package/dist/flows/run/project.js

@@ -2,7 +2,7 @@ import path from "node:path";
 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 logger from "../../logger/index.js";
+import logger, { keepLogFiles } from "../../logger/index.js";
 import { resolveWorkers } from "../../runner/workers-option.js";
 import { withProject } from "../../runner/project.js";
 import { browsersFor } from "../../runner/browsers.js";
@@ -56,7 +56,10 @@ async function runOnPool(pool, items, onEvent, signal) {
     });
     if (signal.aborted)
         return "cancelled";
-    return results.every((r) => r.status === "success") ? "passed" : "failed";
+    // A skipped test is not a failure
+    return results.every((r) => r.status === "success" || r.status === "skipped")
+        ? "passed"
+        : "failed";
 }
 /** The tests, and the browsers, of each Test and Group node of a flow; a Test node uses the project's browsers */
 export function nodeTestsOf(flow, tests, groups) {
@@ -152,13 +155,7 @@ export async function checkFlowInProject(options) {
     const { flow, problems } = await prepare(options);
     return { flow, problems };
 }
-/**
- * Checks and runs a flow of a project: loads its config, lists its tests and groups, refuses to start
- * when `checkFlow` finds errors (`FlowCheckError`), then walks the flow; each Test and Group node runs
- * its tests through `runTests`, one after the other, or on one shared worker pool when `workers` is above 1.
- * One at a time per process.
- */
-export async function runFlowInProject(options) {
+async function walkFlowInProject(options) {
     const { projectDir, flow, unsupported, config, steps, name, environment, tests, groups, problems, } = await prepare(options);
     const errors = problems.filter((p) => p.level === "error");
     if (errors.length)
@@ -250,3 +247,19 @@ export async function runFlowInProject(options) {
         await pool?.dispose();
     }
 }
+/**
+ * Checks and runs a flow of a project: loads its config, lists its tests and groups, refuses to start
+ * when `checkFlow` finds errors (`FlowCheckError`), then walks the flow; each Test and Group node runs
+ * its tests through `runTests`, one after the other, or on one shared worker pool when `workers` is above 1.
+ * One at a time per process.
+ */
+export async function runFlowInProject(options) {
+    // One log for the whole run, across the project sessions it opens one after the other
+    const releaseLogs = keepLogFiles(path.resolve(options.projectDir ?? process.cwd()));
+    try {
+        return await walkFlowInProject(options);
+    }
+    finally {
+        releaseLogs();
+    }
+}

package/dist/logger/index.d.ts

@@ -5,4 +5,10 @@ export declare function consoleLine(entry: {
     meta?: Record<string, unknown> | undefined;
 }): string;
 declare const logger: import("winston").Logger;
+/**
+ * Writes the log to `error.log` and `combined.log` in `<projectDir>/logs/` until the returned function is called.
+ * Nothing is written to disk before a project is in use, so a command that has none (`samurai --version`) leaves
+ * no folder behind. Holders of the same project share the files; the files close with the last one.
+ */
+export declare function keepLogFiles(projectDir: string): () => void;
 export default logger;

package/dist/logger/index.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { createLogger, format, transports } from "winston";
 import { maskFormat } from "../config/mask.js";
 /** Metadata every line carries (`defaultMeta`): not worth printing on each console line */
@@ -15,7 +16,7 @@ const logger = createLogger({
     }), format.errors({ stack: true }), format.splat(), format.metadata({ key: "meta" }), maskFormat(), format.json({ space: 2 })),
     defaultMeta: { service: "samurai-framework" },
     transports: [
-        // The console shows the log; `logs/error.log` keeps errors and `logs/combined.log` everything
+        // The console shows the log; the files of a project's `logs/` folder are added while a project is in use (`keepLogFiles`)
         new transports.Console({
             // The `samurai` command quiets this to "warn"; the log files keep everything
             level: process.env.SAMURAI_LOG_LEVEL ?? "debug",
@@ -27,11 +28,51 @@ const logger = createLogger({
                 meta: meta,
             }))),
         }),
-        new transports.File({
-            filename: `logs/error.log`,
-            level: "error",
-        }),
-        new transports.File({ filename: `logs/combined.log` }),
     ],
 });
+/** The files the log is written to now: `error.log` keeps errors, `combined.log` everything */
+let files;
+/**
+ * Writes the log to `error.log` and `combined.log` in `<projectDir>/logs/` until the returned function is called.
+ * Nothing is written to disk before a project is in use, so a command that has none (`samurai --version`) leaves
+ * no folder behind. Holders of the same project share the files; the files close with the last one.
+ */
+export function keepLogFiles(projectDir) {
+    const dir = path.join(projectDir, "logs");
+    if (files && files.dir !== dir)
+        closeFiles();
+    files ??= {
+        dir,
+        transports: [
+            new transports.File({
+                filename: path.join(dir, "error.log"),
+                level: "error",
+            }),
+            new transports.File({ filename: path.join(dir, "combined.log") }),
+        ],
+        holders: 0,
+    };
+    const mine = files;
+    if (mine.holders === 0)
+        for (const t of mine.transports)
+            logger.add(t);
+    mine.holders++;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        if (--mine.holders === 0 && files === mine)
+            closeFiles();
+    };
+}
+function closeFiles() {
+    if (!files)
+        return;
+    for (const t of files.transports) {
+        logger.remove(t);
+        t.close?.();
+    }
+    files = undefined;
+}
 export default logger;

package/dist/runner/all-hooks.d.ts

@@ -0,0 +1,26 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { AllHookFixtures, RegisteredTestCase } from "../types/test.js";
+import { type HookError } from "./hooks.js";
+export interface AllHooksOptions {
+    /** The limit of each beforeAll / afterAll hook, in ms */
+    timeout: number;
+    /** The fixtures the hooks of a browser get */
+    fixtures(browser: SupportedBrowser): AllHookFixtures;
+}
+/**
+ * The `beforeAll` and `afterAll` hooks of one worker: each runs once per suite and browser, `beforeAll` when the
+ * first test of the suite arrives and `afterAll` when the worker is done
+ */
+export declare class AllHooks {
+    private readonly options;
+    private readonly scopes;
+    /** In the order the suites were entered */
+    private readonly entered;
+    constructor(options: AllHooksOptions);
+    /** Runs the `beforeAll` hooks of the suites around `test` that this worker has not run for `browser`. Rejects with the `HookError` of one that failed, now or earlier */
+    ensure(test: RegisteredTestCase, browser: SupportedBrowser): Promise<void>;
+    /** Runs the `afterAll` hooks of every suite entered, last entered first, and returns the errors; a second call has nothing to do */
+    closeAll(): Promise<HookError[]>;
+    private enter;
+    private runBefore;
+}

package/dist/runner/all-hooks.js

@@ -0,0 +1,61 @@
+import { runHook } from "./hooks.js";
+import { suiteChain } from "./suite.js";
+/**
+ * The `beforeAll` and `afterAll` hooks of one worker: each runs once per suite and browser, `beforeAll` when the
+ * first test of the suite arrives and `afterAll` when the worker is done
+ */
+export class AllHooks {
+    constructor(options) {
+        this.options = options;
+        this.scopes = new Map();
+        /** In the order the suites were entered */
+        this.entered = [];
+    }
+    /** Runs the `beforeAll` hooks of the suites around `test` that this worker has not run for `browser`. Rejects with the `HookError` of one that failed, now or earlier */
+    async ensure(test, browser) {
+        for (const suite of suiteChain(test.suite)) {
+            if (!suite.beforeAll?.length && !suite.afterAll?.length)
+                continue;
+            await this.enter(suite, browser).ready;
+        }
+    }
+    /** Runs the `afterAll` hooks of every suite entered, last entered first, and returns the errors; a second call has nothing to do */
+    async closeAll() {
+        const errors = [];
+        const entered = this.entered.splice(0).reverse();
+        this.scopes.clear();
+        for (const { suite, browser, ready } of entered) {
+            await ready.catch(() => undefined);
+            for (const hook of suite.afterAll ?? []) {
+                try {
+                    await runHook("afterAll", hook, this.options.fixtures(browser), this.options.timeout);
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+        }
+        return errors;
+    }
+    enter(suite, browser) {
+        const ofSuite = this.scopes.get(suite) ?? new Map();
+        this.scopes.set(suite, ofSuite);
+        const known = ofSuite.get(browser);
+        if (known)
+            return known;
+        const scope = {
+            suite,
+            browser,
+            ready: this.runBefore(suite, browser),
+        };
+        // Rejections are handled by the callers of `ensure`; one nobody waits for is not an error of the process
+        scope.ready.catch(() => undefined);
+        ofSuite.set(browser, scope);
+        this.entered.push(scope);
+        return scope;
+    }
+    async runBefore(suite, browser) {
+        for (const hook of suite.beforeAll ?? [])
+            await runHook("beforeAll", hook, this.options.fixtures(browser), this.options.timeout);
+    }
+}

package/dist/runner/focus.d.ts

@@ -0,0 +1,5 @@
+import type { RegisteredTestCase } from "../types/test.js";
+/** `test.only` is in the specs and the config refuses it: one error that lists every focused test */
+export declare function assertNoOnly(all: readonly RegisteredTestCase[], forbid: boolean, srcDir: string): void;
+/** When any of the selected tests is focused, only the focused ones; the others are not run and not reported */
+export declare function narrowToOnly(selected: RegisteredTestCase[]): RegisteredTestCase[];

package/dist/runner/focus.js

@@ -0,0 +1,19 @@
+import path from "path";
+import { toPosix } from "./groups.js";
+/** `test.only` is in the specs and the config refuses it: one error that lists every focused test */
+export function assertNoOnly(all, forbid, srcDir) {
+    if (!forbid)
+        return;
+    const focused = all.filter((test) => test.modifier === "only");
+    if (focused.length === 0)
+        return;
+    throw new Error(focused
+        .map((test) => `test.only is not allowed (forbidOnly): ${toPosix(path.relative(srcDir, test.file))}: ${test.name}`)
+        .join("\n"));
+}
+/** When any of the selected tests is focused, only the focused ones; the others are not run and not reported */
+export function narrowToOnly(selected) {
+    return selected.some((test) => test.modifier === "only")
+        ? selected.filter((test) => test.modifier === "only")
+        : selected;
+}

package/dist/runner/hooks.d.ts

@@ -0,0 +1,24 @@
+import type { Suite, TestFixtures } from "../types/test.js";
+import { type HookKind } from "./suite.js";
+/** A hook threw or ran out of time: the message names the hook (`beforeEach hook failed: <message>`) */
+export declare class HookError extends Error {
+    readonly kind: HookKind;
+    readonly cause: unknown;
+    constructor(kind: HookKind, cause: unknown);
+}
+/**
+ * Runs one hook with its fixtures and waits for it. Anything it throws, and a hook that is still running after
+ * `limitMs` (when given), becomes a `HookError` of that kind.
+ */
+export declare function runHook<F>(kind: HookKind, hook: (fixtures: F) => Promise<void> | void, fixtures: F, limitMs?: number): Promise<void>;
+/**
+ * Runs a test body between the `beforeEach` and `afterEach` hooks of its suites.
+ *
+ * - A failing `beforeEach` stops the other `beforeEach` hooks and the body; the `afterEach` hooks still run.
+ * - The `afterEach` hooks run when the body ended by itself (it passed, threw or skipped), not when `signal` says
+ *   the test was cut short (timeout, abort, closed browser): the time or the page is gone. They all run, even
+ *   after one fails.
+ * - What it throws: the `beforeEach` failure, else the body's error, else the first `afterEach` failure. A skip is
+ *   overruled by a failing `afterEach`.
+ */
+export declare function runWithEachHooks(suite: Suite, fixtures: TestFixtures, signal: AbortSignal, body: () => Promise<void>): Promise<void>;

package/dist/runner/hooks.js

@@ -0,0 +1,79 @@
+import { isSkipSignal } from "./skip.js";
+import { afterEachOf, beforeEachOf } from "./suite.js";
+/** A hook threw or ran out of time: the message names the hook (`beforeEach hook failed: <message>`) */
+export class HookError extends Error {
+    constructor(kind, cause) {
+        super(`${kind} hook failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.kind = kind;
+        this.cause = cause;
+        this.name = "HookError";
+    }
+}
+/**
+ * Runs one hook with its fixtures and waits for it. Anything it throws, and a hook that is still running after
+ * `limitMs` (when given), becomes a `HookError` of that kind.
+ */
+export async function runHook(kind, hook, fixtures, limitMs) {
+    let timer;
+    try {
+        const running = Promise.resolve().then(() => hook(fixtures));
+        if (limitMs === undefined)
+            return await running;
+        await Promise.race([
+            running,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`timed out after ${limitMs / 1000} seconds`)), limitMs);
+            }),
+        ]);
+    }
+    catch (error) {
+        // `test.skip(condition)` in a hook skips the test: it is not a failure of the hook
+        if (isSkipSignal(error))
+            throw error;
+        throw new HookError(kind, error);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Runs a test body between the `beforeEach` and `afterEach` hooks of its suites.
+ *
+ * - A failing `beforeEach` stops the other `beforeEach` hooks and the body; the `afterEach` hooks still run.
+ * - The `afterEach` hooks run when the body ended by itself (it passed, threw or skipped), not when `signal` says
+ *   the test was cut short (timeout, abort, closed browser): the time or the page is gone. They all run, even
+ *   after one fails.
+ * - What it throws: the `beforeEach` failure, else the body's error, else the first `afterEach` failure. A skip is
+ *   overruled by a failing `afterEach`.
+ */
+export async function runWithEachHooks(suite, fixtures, signal, body) {
+    let primary;
+    let failed = false;
+    try {
+        for (const hook of beforeEachOf(suite))
+            await runHook("beforeEach", hook, fixtures);
+        await body();
+    }
+    catch (error) {
+        primary = error;
+        failed = true;
+    }
+    let afterError;
+    let afterFailed = false;
+    if (!signal.aborted) {
+        for (const hook of afterEachOf(suite)) {
+            try {
+                await runHook("afterEach", hook, fixtures);
+            }
+            catch (error) {
+                if (!afterFailed)
+                    afterError = error;
+                afterFailed = true;
+            }
+        }
+    }
+    if (afterFailed && (!failed || isSkipSignal(primary)))
+        throw afterError;
+    if (failed)
+        throw primary;
+}

package/dist/runner/pooled-run.d.ts

@@ -27,6 +27,11 @@ export declare function planItems(selected: RegisteredTestCase[], browsers: Supp
  * and `configGroups` are the same list, resolved and as written.
  */
 export declare function serialKeyOf(groups: ResolvedGroup[], configGroups: SamuraiGroup[] | undefined, srcDir: string): (test: RegisteredTestCase) => string | undefined;
+/**
+ * How many items can run at the same time: each item alone counts one, and the items of one serial key together
+ * count one. More workers than this would only sit idle.
+ */
+export declare function concurrency(items: WorkItem[]): number;
 /**
  * How a run goes: through the pool, in this process, or in this process because the workers could not read the
  * config (it was given as an object; a worker reads `samurai.config.ts` from the project folder)
@@ -37,7 +42,8 @@ export declare function poolMode(input: {
     inlineConfig: boolean;
 }): "pool" | "in-process" | "inline-config";
 /**
- * Runs the planned items on the pool and reports them as they happen. An item the pool answers without events
+ * Runs the planned items on the pool and reports them as they happen. Tests that do not run (skip, fixme) are
+ * reported first, here, and never reach a worker. An item the pool answers without events
  * (a queued one cut short by an abort, or one whose worker died before it began) is reported here at the end.
  */
 export declare function runPooled(pool: PooledRunner, planned: PlannedTest[], items: WorkItem[], reporter: TestReporter, signal?: AbortSignal): Promise<void>;