@itmetsam/samurai-framework 0.12.1 → 0.15.1

package/dist/flows/run/project.js

@@ -2,7 +2,8 @@ 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 { resolveRetries } from "../../runner/retries-option.js";
 import { resolveWorkers } from "../../runner/workers-option.js";
 import { withProject } from "../../runner/project.js";
 import { browsersFor } from "../../runner/browsers.js";
@@ -12,17 +13,12 @@ import TestRunner from "../../runner/test-runner.js";
 import { WorkerPool } from "../../runner/worker-pool.js";
 import { processWorkerFactory } from "../../runner/worker-process.js";
 import { readFlow } from "./files.js";
+import { itemsOf, runOnPool } from "./node-pool.js";
+import { FlowCheckError, } from "./project-options.js";
 import { projectSteps } from "../steps/set.js";
 import { HANDLERS } from "./handlers/index.js";
 import { runFlow } from "./run.js";
-/** The flow has errors; nothing was run */
-export class FlowCheckError extends Error {
-    constructor(problems) {
-        super(`This flow can't run:\n${problems.map((p) => `  - ${p.message}`).join("\n")}`);
-        this.problems = problems;
-        this.name = "FlowCheckError";
-    }
-}
+export { FlowCheckError };
 /** Whether the project's config defines an environment of this name */
 function hasEnvironment(config, name) {
     return Object.prototype.hasOwnProperty.call(config.environments ?? {}, name);
@@ -36,28 +32,6 @@ export function chooseEnvironment(config, flow, option) {
         return flow.envDefault;
     return config.defaultEnvironment ?? names[0] ?? "default";
 }
-/** The work items of a node: each test in each browser, the browsers one after the other */
-function itemsOf(tests, browsers) {
-    return browsers
-        .flatMap((browser) => tests.map((t) => ({ file: t.file, testName: t.name, browser })))
-        .map((item, index) => ({ ...item, index }));
-}
-/** Runs the tests of a node on the pool and reports them as a run would */
-async function runOnPool(pool, items, onEvent, signal) {
-    const results = await pool.run(items, {
-        signal,
-        onEvent: (event) => onEvent({
-            type: event.type,
-            name: event.item.testName,
-            file: event.item.file,
-            browser: event.item.browser,
-            ...(event.type === "test-end" && { result: event.result }),
-        }),
-    });
-    if (signal.aborted)
-        return "cancelled";
-    return results.every((r) => r.status === "success") ? "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) {
     const byId = new Map(tests.map((t) => [t.id, t]));
@@ -152,13 +126,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)
@@ -185,6 +153,12 @@ export async function runFlowInProject(options) {
     const files = [
         ...new Set(Object.values(nodeTests).flatMap((list) => list.map((t) => t.file))),
     ];
+    // A failing test is run again as often as the project says, in a node as in a plain run
+    const retries = resolveRetries({
+        flag: options.retries,
+        env: options.retriesEnv,
+        config: config.retries,
+    });
     // One pool for the whole run: the nodes, and the branches of a Parallel node, share its workers
     const pool = workers > 1
         ? (options.createPool ?? ((o) => new WorkerPool(o)))({
@@ -203,6 +177,7 @@ export async function runFlowInProject(options) {
                 }),
                 files,
                 basePort: options.port ?? DEFAULT_PORT,
+                ...(retries > 0 && { retries }),
             },
         })
         : undefined;
@@ -233,6 +208,7 @@ export async function runFlowInProject(options) {
                         expectTimeout: options.expectTimeout,
                     }),
                     ...(options.port !== undefined && { port: options.port }),
+                    ...(retries > 0 && { retries }),
                     ...(browsers && { browsers }),
                     files: [...new Set(tests.map((t) => t.file))],
                     testNames: tests.map((t) => t.name),
@@ -250,3 +226,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/recorder/candidates.d.ts

@@ -1,6 +1,7 @@
 /**
  * Declarations that turn an element into locator candidates (test id, role and name, label, text, css and
- * an absolute xpath), plus `inToolbar(event)`, which is true for events from the recorder toolbar. A string
+ * an absolute xpath), `uniqueOf(el, candidates)`, the candidates that match only that element right now, and
+ * `inToolbar(event)`, which is true for events from the recorder toolbar. A string
  * of plain declarations, interpolated into the capture script (page realm) and the toolbar script
  * (sandbox realm), so no transpiler helper can end up in it.
  */

package/dist/recorder/candidates.js

@@ -1,6 +1,7 @@
 /**
  * Declarations that turn an element into locator candidates (test id, role and name, label, text, css and
- * an absolute xpath), plus `inToolbar(event)`, which is true for events from the recorder toolbar. A string
+ * an absolute xpath), `uniqueOf(el, candidates)`, the candidates that match only that element right now, and
+ * `inToolbar(event)`, which is true for events from the recorder toolbar. A string
  * of plain declarations, interpolated into the capture script (page realm) and the toolbar script
  * (sandbox realm), so no transpiler helper can end up in it.
  */
@@ -100,6 +101,48 @@ const candidatesOf = (el) => {
   return found;
 };
 
+// Not searched by text, as the framework's text locator skips them
+const UNTEXTED = ["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "HEAD", "TITLE", "META", "LINK"];
+
+// The elements a candidate matches in this document, found the way the framework's locators find them
+const matchesOf = (call) => {
+  const all = () => Array.prototype.slice.call(document.querySelectorAll("*"));
+  switch (call.method) {
+    case "getByTestId":
+      return all().filter((node) => node.getAttribute("data-testid") === call.testId);
+    case "getByRole":
+      return all().filter((node) => roleOf(node) === call.role && nameOf(node, call.role) === call.name);
+    case "getByLabel":
+      return all().filter((node) => labelTexts(node).indexOf(call.text) >= 0);
+    case "getByText": {
+      const matches = all().filter((node) => UNTEXTED.indexOf(node.tagName) < 0 && textOf(node) === call.text);
+      // Only the innermost count: a wrapper around the matching element is not a match
+      return matches.filter((node) => !matches.some((other) => other !== node && node.contains(other)));
+    }
+    case "getByCss":
+      try {
+        return Array.prototype.slice.call(document.querySelectorAll(call.css));
+      } catch (error) {
+        return [];
+      }
+    case "locator": {
+      const found = document.evaluate(call.xpath, document, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+      const nodes = [];
+      for (let i = 0; i < found.snapshotLength; i++) nodes.push(found.snapshotItem(i));
+      return nodes;
+    }
+    default:
+      return [];
+  }
+};
+
+// The candidates that match only el right now: what the recorder falls back to once the page has removed el
+const uniqueOf = (el, candidates) =>
+  candidates.filter((call) => {
+    const found = matchesOf(call);
+    return found.length === 1 && found[0] === el;
+  });
+
 const isTextEntry = (el) => {
   const tag = el.tagName.toLowerCase();
   if (tag === "textarea") return true;

package/dist/recorder/capture.d.ts

@@ -5,17 +5,19 @@
  * listeners; those of the earlier run go quiet, as their run is no longer the current one.
  * Reports what the tester does in the top-level document:
  *
- * - `{ type: "click", target, candidates, textEntry }`: a click, retargeted to the nearest interactive
+ * - `{ type: "click", target, candidates, unique, textEntry }`: a click, retargeted to the nearest interactive
  *   element (a label click reports its control; the click the browser forwards to the control is dropped).
  * - `{ type: "input", target, candidates, value, secret, secretName }`: text typed into a field. Password
  *   values never leave the page: `secret` is set and `value` is left out.
- * - `{ type: "press", target, candidates, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
+ * - `{ type: "press", target, candidates, unique, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
  *   click or typing, which are reported as such).
  * - `{ type: "assert", target, candidates, text, value }`: an Alt+click, which does not reach the page.
  *   While Alt is held, the element under the pointer is outlined.
  *
  * `candidates` are locator calls for the element, most stable first (test id, role and name, label,
  * text, css, and an absolute xpath that always exists). The recorder checks each one against the page.
+ * `unique` lists the candidates that matched only the element when it was clicked or pressed, before the
+ * page's own handlers ran: a button the click removes (Sign in, Delete) is gone by the time the recorder checks.
  * Runs in the page's own realm; a string, so no transpiler helper can end up in it.
  */
 export declare const CAPTURE_SOURCE: string;

package/dist/recorder/capture.js

@@ -12,17 +12,19 @@ const RUN_KEY = "samurai.recorder.run";
  * listeners; those of the earlier run go quiet, as their run is no longer the current one.
  * Reports what the tester does in the top-level document:
  *
- * - `{ type: "click", target, candidates, textEntry }`: a click, retargeted to the nearest interactive
+ * - `{ type: "click", target, candidates, unique, textEntry }`: a click, retargeted to the nearest interactive
  *   element (a label click reports its control; the click the browser forwards to the control is dropped).
  * - `{ type: "input", target, candidates, value, secret, secretName }`: text typed into a field. Password
  *   values never leave the page: `secret` is set and `value` is left out.
- * - `{ type: "press", target, candidates, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
+ * - `{ type: "press", target, candidates, unique, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
  *   click or typing, which are reported as such).
  * - `{ type: "assert", target, candidates, text, value }`: an Alt+click, which does not reach the page.
  *   While Alt is held, the element under the pointer is outlined.
  *
  * `candidates` are locator calls for the element, most stable first (test id, role and name, label,
  * text, css, and an absolute xpath that always exists). The recorder checks each one against the page.
+ * `unique` lists the candidates that matched only the element when it was clicked or pressed, before the
+ * page's own handlers ran: a button the click removes (Sign in, Delete) is gone by the time the recorder checks.
  * Runs in the page's own realm; a string, so no transpiler helper can end up in it.
  */
 export const CAPTURE_SOURCE = String.raw `(send) => {
@@ -39,6 +41,7 @@ export const CAPTURE_SOURCE = String.raw `(send) => {
   const MUTED = Symbol.for("${MUTED_KEY}");
   const off = () => window[RUN] !== run || window[OFF] === true || window[MUTED] === true;
   let lastClick = { el: null, at: 0 };
+  let lastEnter = { form: null, at: 0 };
   let outlined = null;
   let outlinedStyle = "";
   const unhighlight = () => {
@@ -69,8 +72,11 @@ export const CAPTURE_SOURCE = String.raw `(send) => {
     const now = Date.now();
     // The browser forwards a label click to its control as a second click
     if (lastClick.el === el && now - lastClick.at < 150) return;
+    // An Enter in a field submits its form with a click on the submit button: the Enter is the step
+    if (event.detail === 0 && el.form && el.form === lastEnter.form && now - lastEnter.at < 150) return;
     lastClick = { el, at: now };
-    report({ type: "click", target: el, candidates: candidatesOf(el), textEntry: isTextEntry(el) });
+    const candidates = candidatesOf(el);
+    report({ type: "click", target: el, candidates, unique: uniqueOf(el, candidates), textEntry: isTextEntry(el) });
   }, true);
 
   document.addEventListener("input", (event) => {
@@ -98,7 +104,9 @@ export const CAPTURE_SOURCE = String.raw `(send) => {
     if (RECORDED_KEYS.indexOf(event.key) < 0 || !(event.target instanceof Element)) return;
     const el = event.target;
     if (event.key === "Enter" && (el.closest(ACTIVATES) || el.tagName === "TEXTAREA" || el.isContentEditable)) return;
-    report({ type: "press", target: el, candidates: candidatesOf(el), pressed: event.key });
+    const candidates = candidatesOf(el);
+    report({ type: "press", target: el, candidates, unique: uniqueOf(el, candidates), pressed: event.key });
+    if (event.key === "Enter") lastEnter = { form: el.form || null, at: Date.now() };
   }, true);
 
   document.addEventListener("mousemove", (event) => {

package/dist/recorder/page-messages.d.ts

@@ -23,6 +23,8 @@ export interface PageMessage {
     type: "click" | "input" | "press" | "assert";
     target: ElementHandle;
     candidates: LocatorCall[];
+    /** Of a click or press: the candidates that matched only the target when it happened, checked in the page */
+    unique?: LocatorCall[];
     textEntry?: boolean;
     /** The key of a `press` message */
     pressed?: string;

package/dist/recorder/ranking.d.ts

@@ -7,3 +7,5 @@ import type { LocatorCall, LocatorSpec } from "../steps/model.js";
  * become its fallbacks. Returns undefined when no candidate qualifies.
  */
 export declare function rankLocator(page: Page, target: ElementHandle, candidates: readonly LocatorCall[], maxFallbacks?: number): Promise<LocatorSpec | undefined>;
+/** The first of `verified` as the primary, up to `maxFallbacks` more as its fallbacks; undefined when empty */
+export declare function specOf(verified: readonly LocatorCall[], maxFallbacks?: number): LocatorSpec | undefined;

package/dist/recorder/ranking.js

@@ -17,6 +17,13 @@ export async function rankLocator(page, target, candidates, maxFallbacks = 2) {
         if (found.length === 1 && found[0].sharedId === target.sharedId)
             verified.push(candidate);
     }
+    return specOf(verified, maxFallbacks);
+}
+/** The first of `verified` as the primary, up to `maxFallbacks` more as its fallbacks; undefined when empty */
+export function specOf(verified, maxFallbacks = 2) {
     const [primary, ...fallbacks] = verified;
-    return (primary && { chain: [primary], fallbacks: fallbacks.map((call) => [call]) });
+    return (primary && {
+        chain: [primary],
+        fallbacks: fallbacks.slice(0, maxFallbacks).map((call) => [call]),
+    });
 }

package/dist/recorder/recorder.js

@@ -9,7 +9,7 @@ import { FilesRecorder, missingFileText } from "./files-recorder.js";
 import { Normaliser } from "./normalise.js";
 import { observationFor, } from "./page-messages.js";
 import { listSandboxRealms } from "./realms.js";
-import { rankLocator } from "./ranking.js";
+import { rankLocator, specOf } from "./ranking.js";
 import { TOOLBAR_HOOK, ToolbarBridge } from "./toolbar-bridge.js";
 import { TOOLBAR_SANDBOX } from "./toolbar/protocol.js";
 import { TOOLBAR_SOURCE } from "./toolbar/source.js";
@@ -216,7 +216,10 @@ export class Recorder {
         const { sharedId } = message.target;
         if (this.known.has(sharedId))
             return this.known.get(sharedId);
-        const spec = await rankLocator(this.page, message.target, message.candidates);
+        // The page may have removed the element by now (a Sign in that leaves the form): then what matched
+        // only it when it was used is the best there is
+        const spec = (await rankLocator(this.page, message.target, message.candidates)) ??
+            specOf(message.unique ?? []);
         this.known.set(sharedId, spec);
         return spec;
     }

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

@@ -18,6 +18,12 @@ export interface RunnerOptions {
      * @default the config's `workers`, else half the CPUs
      */
     workers?: number | string;
+    /**
+     * How many times a failing test is run again, each time with a fresh browser (the command line's `--retries`).
+     * Beats `SAMURAI_RETRIES` and the config's `retries`.
+     * @default the config's `retries`, else 0
+     */
+    retries?: number | string;
     /** Run the browser without a window. @default false */
     headless?: boolean;
     /** Remote debugging port of the browser. @default DEFAULT_PORT (9223) */