@itmetsam/samurai-framework 0.15.0 → 0.15.2

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/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) */

package/dist/runner/pooled-run.js

@@ -70,18 +70,19 @@ export function poolMode(input) {
 export async function runPooled(pool, planned, items, reporter, signal) {
     reporter.setOrder(planned);
     for (const { test, browser } of planned) {
-        const annotation = staticSkip(test);
-        if (annotation)
-            reporter.onTestSkipped(test, browser, { annotation });
+        const skip = staticSkip(test);
+        if (skip)
+            reporter.onTestSkipped(test, browser, skip);
     }
     const started = new Set();
     const ended = new Set();
-    const begin = (index) => {
-        if (started.has(index))
+    const begin = (index, retry) => {
+        // A test run again starts again; the first start is reported once however it arrives
+        if (started.has(index) && !retry)
             return;
         started.add(index);
         const { test, browser } = planned[index];
-        reporter.onTestStart(test, browser);
+        reporter.onTestStart(test, browser, retry);
     };
     const end = (index, result) => {
         begin(index);
@@ -92,7 +93,7 @@ export async function runPooled(pool, planned, items, reporter, signal) {
     const results = await pool.run(items, {
         ...(signal && { signal }),
         onEvent: (event) => event.type === "test-start"
-            ? begin(event.item.index)
+            ? begin(event.item.index, event.retry)
             : end(event.item.index, event.result),
     });
     results.forEach((result, position) => {

package/dist/runner/registry.d.ts

@@ -1,4 +1,4 @@
-import type { AllHook, EachHook, RegisteredTestCase, TestCaseBase } from "../types/test.js";
+import type { AllHook, EachHook, RegisteredTestCase, TestCaseBase, TestDetails } from "../types/test.js";
 type Body = TestCaseBase["function"];
 /** `test(title, fn)`, `test.skip(title, fn)`, `test.skip(condition, reason)` and the other forms */
 export interface TestFunction {
@@ -10,16 +10,25 @@ export interface TestFunction {
     /** Runs only this test (and the other `only` ones) */
     only(title: string, fn: Body): void;
 }
-/** With a title and a body it registers a skipped test; with a condition it skips the running test when the condition is true */
+/**
+ * With a title and a body it registers a skipped test, `{ reason }` saying why; with a condition it skips the
+ * running test when the condition is true
+ */
 interface SkipFunction {
     (title: string, fn: Body): void;
+    (title: string, details: TestDetails, fn: Body): void;
     (condition: boolean, reason?: string): void;
 }
+/** `describe.skip` and `describe.fixme`: every test inside gets the modifier, and `{ reason }` says why */
+interface DescribeSkipFunction {
+    (title: string, fn: () => void): void;
+    (title: string, details: TestDetails, fn: () => void): void;
+}
 /** `describe(title, fn)` and the same with a modifier on every test inside */
 export interface DescribeFunction {
     (title: string, fn: () => void): void;
-    skip(title: string, fn: () => void): void;
-    fixme(title: string, fn: () => void): void;
+    skip: DescribeSkipFunction;
+    fixme: DescribeSkipFunction;
     only(title: string, fn: () => void): void;
 }
 export declare const test: TestFunction;

package/dist/runner/registry.js

@@ -4,8 +4,8 @@ import { SkipSignal } from "./skip.js";
 import { addHook, currentSuite, enterSuite, leaveSuite, modifierOf, resetSuites, } from "./suite.js";
 const registered = [];
 /** Runs `fn` as the `describe` block `title`, under `modifier` when there is one. `fn` runs immediately and must be synchronous. */
-function openDescribe(file, title, fn, modifier) {
-    enterSuite(file, title, modifier);
+function openDescribe(file, title, fn, modifier, reason) {
+    enterSuite(file, title, modifier, reason);
     try {
         const result = fn();
         if (result instanceof Promise) {
@@ -17,18 +17,17 @@ function openDescribe(file, title, fn, modifier) {
         leaveSuite();
     }
 }
-function add(file, title, fn, modifier) {
+function add(file, title, fn, modifier, reason) {
     const suite = currentSuite(file);
     const titlePath = [...titlesOf(suite), title];
     const name = titlePath.join(" > ");
-    const effective = modifierOf(modifier, suite);
     registered.push({
         name,
         titlePath,
         function: fn,
         file,
         suite,
-        ...(effective && { modifier: effective }),
+        ...modifierOf({ modifier, ...(reason !== undefined && { reason }) }, suite),
     });
     logger.debug("Registered test %s", name);
 }
@@ -40,26 +39,44 @@ function titlesOf(suite) {
             titles.unshift(s.title);
     return titles;
 }
+/** The body and `{ reason }` of `(title, fn)` and `(title, details, fn)` */
+function bodyAndReason(call, title, second, third) {
+    const [details, fn] = typeof second === "function"
+        ? [undefined, second]
+        : [second, third];
+    if (typeof fn !== "function")
+        throw new TypeError(`${call}(${JSON.stringify(title)}) needs a function as its last argument`);
+    const reason = details?.reason;
+    return { fn: fn, ...(reason !== undefined && { reason }) };
+}
 /** `test.skip` and `test.fixme`: a title and a body register a test with the modifier; a condition skips the running test */
 function skipping(annotation) {
-    return ((first, second) => {
+    return ((first, second, third) => {
         if (typeof first === "string") {
+            const { fn, reason } = bodyAndReason(`test.${annotation}`, first, second, third);
             // Frames: Error, callerFile, this function, the spec
-            add(callerFile(), first, second, annotation);
+            add(callerFile(), first, fn, annotation, reason);
             return;
         }
         if (first)
             throw new SkipSignal(annotation, second);
     });
 }
+/** `describe.skip` and `describe.fixme`, with or without `{ reason }` */
+function describeSkipping(annotation) {
+    return ((title, second, third) => {
+        const { fn, reason } = bodyAndReason(`describe.${annotation}`, title, second, third);
+        openDescribe(callerFile(), title, fn, annotation, reason);
+    });
+}
 export const test = Object.assign((title, fn) => add(callerFile(), title, fn), {
     skip: skipping("skip"),
     fixme: skipping("fixme"),
     only: (title, fn) => add(callerFile(), title, fn, "only"),
 });
 export const describe = Object.assign((title, fn) => openDescribe(callerFile(), title, fn), {
-    skip: (title, fn) => openDescribe(callerFile(), title, fn, "skip"),
-    fixme: (title, fn) => openDescribe(callerFile(), title, fn, "fixme"),
+    skip: describeSkipping("skip"),
+    fixme: describeSkipping("fixme"),
     only: (title, fn) => openDescribe(callerFile(), title, fn, "only"),
 });
 /** Runs before each test of the `describe` block it is written in (of the file, at the top level) */

package/dist/runner/reporter.d.ts

@@ -1,4 +1,4 @@
-import type { RegisteredTestCase, TestError, TestLogEntry, TestResult, TestSummary } from "../types/test.js";
+import type { RegisteredTestCase, TestError, TestLogEntry, TestResult, TestRetries, TestSummary } from "../types/test.js";
 import type { SupportedBrowser } from "../types/browser.js";
 /** What a run reports while it happens */
 export type RunEvent = {
@@ -14,6 +14,8 @@ export type RunEvent = {
     name: string;
     file: string;
     browser: SupportedBrowser;
+    /** The attempt, counting from 1, when the test is run again after a failure; absent for the first */
+    retry?: number;
 } | {
     type: "test-end";
     name: string;
@@ -36,7 +38,7 @@ export interface ReporterOptions {
 }
 /** What `runOneTest` reports a test to: the reporter of a run, or a worker that relays it */
 export interface TestSink {
-    onTestStart(test: RegisteredTestCase, browser: SupportedBrowser): void;
+    onTestStart(test: RegisteredTestCase, browser: SupportedBrowser, retry?: number): void;
     onTestEnd(test: RegisteredTestCase, browser: SupportedBrowser, error?: TestError, extras?: TestEndExtras): void;
     /** A test that does not run: reported as started and ended at once */
     onTestSkipped(test: RegisteredTestCase, browser: SupportedBrowser, skip: TestSkip): void;
@@ -47,7 +49,7 @@ export interface TestSkip {
     reason?: string | undefined;
 }
 /** What a test's report entry lists besides its status */
-export interface TestEndExtras {
+export interface TestEndExtras extends TestRetries {
     logs?: TestLogEntry[];
     logsDropped?: number;
     screenshots?: {
@@ -73,7 +75,7 @@ export default class TestReporter implements TestSink {
     }[]): void;
     onStart(total: number, workers?: number): void;
     onEnd(): Promise<TestSummary>;
-    onTestStart(test: RegisteredTestCase, browser: SupportedBrowser): void;
+    onTestStart(test: RegisteredTestCase, browser: SupportedBrowser, retry?: number): void;
     onTestSkipped(test: RegisteredTestCase, browser: SupportedBrowser, { annotation, reason }: TestSkip): void;
     /**
      * Ends a test that ran in a worker: the worker built the result (masked, with its own duration), this keeps the

package/dist/runner/reporter.js

@@ -75,7 +75,7 @@ export default class TestReporter {
         this.emit({ type: "run-end", summary: this.summary });
         return this.summary;
     }
-    onTestStart(test, browser) {
+    onTestStart(test, browser, retry) {
         const key = keyOf(test, browser);
         const t = performance.mark(`${key}-start`);
         this.testResults.set(key, {
@@ -90,6 +90,7 @@ export default class TestReporter {
             name: test.name,
             file: test.file,
             browser,
+            ...(retry ? { retry } : {}),
         });
     }
     onTestSkipped(test, browser, { annotation, reason }) {
@@ -145,6 +146,11 @@ export default class TestReporter {
             ...(extras?.logs && { logs: extras.logs }),
             ...(extras?.logsDropped && { logsDropped: extras.logsDropped }),
             ...(extras?.screenshots?.length && { screenshots: extras.screenshots }),
+            ...(extras?.retry && { retry: extras.retry }),
+            ...(extras?.flaky && { flaky: true }),
+            ...(extras?.previousAttempts?.length && {
+                previousAttempts: extras.previousAttempts,
+            }),
         });
         this.testResults.set(key, result);
         this.emit({

package/dist/runner/retries-option.d.ts

@@ -0,0 +1,10 @@
+export interface RetriesInput {
+    /** The command line's `--retries` (or the `retries` run option) */
+    flag?: number | string | undefined;
+    /** `SAMURAI_RETRIES` */
+    env?: string | undefined;
+    /** The config's `retries` */
+    config?: number | string | undefined;
+}
+/** How many times a failing test is run again: the flag, else `SAMURAI_RETRIES`, else the config's `retries`, else 0 */
+export declare function resolveRetries({ flag, env, config }: RetriesInput): number;

package/dist/runner/retries-option.js

@@ -0,0 +1,12 @@
+import { parseRetries } from "../config/retries.js";
+/** How many times a failing test is run again: the flag, else `SAMURAI_RETRIES`, else the config's `retries`, else 0 */
+export function resolveRetries({ flag, env, config }) {
+    const fromEnv = env?.trim() ? env : undefined;
+    if (flag !== undefined)
+        return parseRetries(flag, "--retries");
+    if (fromEnv !== undefined)
+        return parseRetries(fromEnv, "SAMURAI_RETRIES");
+    if (config !== undefined)
+        return parseRetries(config, "retries");
+    return 0;
+}

package/dist/runner/retry.d.ts

@@ -0,0 +1,13 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { RegisteredTestCase } from "../types/test.js";
+import type { TestSink } from "./reporter.js";
+/** One attempt at a test: it reports to `sink` and `attempt` counts from 0 */
+export type Attempt = (sink: TestSink, attempt: number) => Promise<void>;
+/**
+ * Runs a test, and again after a failure with a fresh browser, up to `retries` more times. The test starts once
+ * per attempt (`retry` counts from 1), and ends once, with the last attempt's result: `retry` says which attempt
+ * that was, `previousAttempts` holds the errors before it, and `flaky` marks a pass after a failure.
+ *
+ * An aborted run is never run again. A test that skips itself ends there and then.
+ */
+export declare function runWithRetries(test: RegisteredTestCase, browser: SupportedBrowser, retries: number, signal: AbortSignal | undefined, attempt: Attempt, sink: TestSink): Promise<void>;

package/dist/runner/retry.js

@@ -0,0 +1,43 @@
+/**
+ * Runs a test, and again after a failure with a fresh browser, up to `retries` more times. The test starts once
+ * per attempt (`retry` counts from 1), and ends once, with the last attempt's result: `retry` says which attempt
+ * that was, `previousAttempts` holds the errors before it, and `flaky` marks a pass after a failure.
+ *
+ * An aborted run is never run again. A test that skips itself ends there and then.
+ */
+export async function runWithRetries(test, browser, retries, signal, attempt, sink) {
+    if (retries <= 0)
+        return attempt(sink, 0);
+    const previous = [];
+    for (let n = 0;; n++) {
+        let held;
+        const attemptSink = {
+            onTestStart: (t, b) => sink.onTestStart(t, b, n > 0 ? n : undefined),
+            onTestEnd: (_t, _b, error, extras) => {
+                held = { error, extras };
+            },
+            onTestSkipped: (t, b, skip) => sink.onTestSkipped(t, b, skip),
+        };
+        await attempt(attemptSink, n);
+        // Skipped: already reported, and nothing is run again
+        if (!held)
+            return;
+        const { error, extras } = held;
+        if (error &&
+            n < retries &&
+            !signal?.aborted &&
+            error.message !== "Run aborted") {
+            previous.push(error);
+            continue;
+        }
+        sink.onTestEnd(test, browser, error, {
+            ...extras,
+            ...(n > 0 && {
+                retry: n,
+                previousAttempts: [...previous],
+                ...(!error && { flaky: true }),
+            }),
+        });
+        return;
+    }
+}

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

@@ -12,6 +12,8 @@ export interface WorkerResources {
     profileDir?: string;
     /** The `workerIndex` fixture. @default 0 */
     workerIndex?: number;
+    /** Which attempt this is, counting from 0: screenshots of a retry go to a `retry-<n>` folder of their own. @default 0 */
+    attempt?: number;
     /** The `beforeAll` / `afterAll` hooks of this worker: kept across tests, closed when the worker is done */
     allHooks?: AllHooks;
 }

package/dist/runner/run-test.js

@@ -10,7 +10,7 @@ import { ConnectionClosedError } from "../transport/bidi-connection.js";
 import { judgePageLogs } from "./page-logs-report.js";
 import { DEFAULT_PORT } from "./ports.js";
 import { runWithEachHooks } from "./hooks.js";
-import { isSkipSignal } from "./skip.js";
+import { isSkipSignal, staticSkip } from "./skip.js";
 import { testDirOf } from "./test-dir.js";
 import { toTestError } from "./test-error.js";
 /**
@@ -64,6 +64,12 @@ export function allHookFixtures(run, browserName, workerIndex = 0) {
 }
 /** Runs one test in one browser and reports it: launch, run the body, judge the page's logs, close the browser */
 export async function runOneTest(test, browserName, run, options, srcDir, reporter, resources = {}) {
+    // A test marked skip or fixme never runs, whoever asked for it (a flow's test node, a worker)
+    const marked = staticSkip(test);
+    if (marked) {
+        reporter.onTestSkipped(test, browserName, marked);
+        return;
+    }
     logger.verbose("Starting test: %s in %s", test.name, browserName);
     reporter.onTestStart(test, browserName);
     const outcome = new TestOutcome(reporter, test, browserName);
@@ -125,7 +131,7 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
                 browserGone();
             });
             page = launched.page;
-            outcome.evidence = new Evidence(resultDir, `${browserName}/${testDirOf(test, srcDir)}`);
+            outcome.evidence = new Evidence(resultDir, `${browserName}/${testDirOf(test, srcDir)}${resources.attempt ? `/retry-${resources.attempt}` : ""}`);
             launched.page.setEvidence(outcome.evidence);
             const fixtures = {
                 page: launched.page,

package/dist/runner/run.d.ts

@@ -21,6 +21,8 @@ export interface FoundTest {
     file: string;
     /** `skip` or `fixme` (not run), or `only` (focused); absent for a plain test. A modifier on a `describe` counts. */
     modifier?: Modifier;
+    /** The `{ reason }` given with the `skip` or `fixme` that applies */
+    reason?: string;
 }
 /** Imports the project's specs without running anything and lists the tests the options select */
 export declare function listTests(options?: RunTestsOptions): Promise<FoundTest[]>;
@@ -28,6 +30,7 @@ export declare function listTests(options?: RunTestsOptions): Promise<FoundTest[
 export declare function listGroups(options?: RunTestsOptions): Promise<ResolvedGroup[]>;
 export { BROWSER_NAMES, checkBrowserList } from "../config/browsers.js";
 export { parseWorkers } from "../config/workers.js";
+export { parseRetries } from "../config/retries.js";
 export type { RunEvent } from "./reporter.js";
 export type { Modifier, TestError, TestResult, TestSummary, } from "../types/test.js";
 export type { ResolvedGroup } from "./groups.js";

package/dist/runner/run.js

@@ -35,10 +35,11 @@ export async function runTests(options = {}) {
 }
 /** Imports the project's specs without running anything and lists the tests the options select */
 export async function listTests(options = {}) {
-    return inProject(options, async (runner) => (await runner.register()).map(({ name, file, modifier }) => ({
+    return inProject(options, async (runner) => (await runner.register()).map(({ name, file, modifier, reason }) => ({
         name,
         file,
         ...(modifier && { modifier }),
+        ...(reason !== undefined && { reason }),
     })));
 }
 /** Imports the project's specs without running anything and lists the config's groups with the tests each holds */
@@ -47,4 +48,5 @@ export async function listGroups(options = {}) {
 }
 export { BROWSER_NAMES, checkBrowserList } from "../config/browsers.js";
 export { parseWorkers } from "../config/workers.js";
+export { parseRetries } from "../config/retries.js";
 export { DEFAULT_PORT } from "./ports.js";

package/dist/runner/skip.d.ts

@@ -1,4 +1,5 @@
 import type { RegisteredTestCase } from "../types/test.js";
+import type { TestSkip } from "./reporter.js";
 /** Thrown by `test.skip(condition, reason)` and `test.fixme(condition, reason)` inside a test: the test ends as skipped */
 export declare class SkipSignal extends Error {
     readonly annotation: "skip" | "fixme";
@@ -7,4 +8,4 @@ export declare class SkipSignal extends Error {
 }
 export declare function isSkipSignal(error: unknown): error is SkipSignal;
 /** Why a test does not run at all: it is marked `skip` or `fixme`, itself or by a `describe` around it */
-export declare function staticSkip(test: Pick<RegisteredTestCase, "modifier">): "skip" | "fixme" | undefined;
+export declare function staticSkip(test: Pick<RegisteredTestCase, "modifier" | "reason">): TestSkip | undefined;

package/dist/runner/skip.js

@@ -12,7 +12,8 @@ export function isSkipSignal(error) {
 }
 /** Why a test does not run at all: it is marked `skip` or `fixme`, itself or by a `describe` around it */
 export function staticSkip(test) {
-    return test.modifier === "skip" || test.modifier === "fixme"
-        ? test.modifier
+    const { modifier, reason } = test;
+    return modifier === "skip" || modifier === "fixme"
+        ? { annotation: modifier, ...(reason !== undefined && { reason }) }
         : undefined;
 }

package/dist/runner/suite.d.ts

@@ -1,19 +1,25 @@
 import type { EachHook, Modifier, Suite } from "../types/test.js";
 /** The four hook lists a suite can hold */
 export type HookKind = "beforeEach" | "afterEach" | "beforeAll" | "afterAll";
-export declare function newSuite(title?: string, parent?: Suite, modifier?: Modifier): Suite;
+export declare function newSuite(title?: string, parent?: Suite, modifier?: Modifier, reason?: string): Suite;
 /** The suite a test or hook written now belongs to: the innermost open `describe`, else the file's own */
 export declare function currentSuite(file: string): Suite;
 /** Opens a `describe` block under the current suite; `leaveSuite` closes it */
-export declare function enterSuite(file: string, title: string, modifier?: Modifier): Suite;
+export declare function enterSuite(file: string, title: string, modifier?: Modifier, reason?: string): Suite;
 export declare function leaveSuite(): void;
 /** Forgets every suite: a run registers its specs afresh */
 export declare function resetSuites(): void;
 /**
  * What applies to a test: the innermost `skip` or `fixme` (the test's own, then its suites', inside out), else
- * `only` when the test or any suite around it is focused. A skip beats a focus.
+ * `only` when the test or any suite around it is focused. A skip beats a focus. The reason comes with the skip
+ * or fixme that applies.
  */
-export declare function modifierOf(own: Modifier | undefined, suite: Suite): Modifier | undefined;
+export declare function modifierOf(own: Mark, suite: Suite): Mark;
+/** A modifier and the reason given with it */
+export interface Mark {
+    modifier?: Modifier;
+    reason?: string;
+}
 /** The suites from the file's root down to `suite` */
 export declare function suiteChain(suite: Suite): Suite[];
 /** The `beforeEach` hooks of a test: outermost suite first, in the order they were written */

package/dist/runner/suite.js

@@ -2,11 +2,12 @@
 const roots = new Map();
 /** The `describe` blocks being registered, outermost first */
 const open = [];
-export function newSuite(title, parent, modifier) {
+export function newSuite(title, parent, modifier, reason) {
     return {
         ...(title !== undefined && { title }),
         ...(parent && { parent }),
         ...(modifier && { modifier }),
+        ...(reason !== undefined && { reason }),
     };
 }
 /** The suite a test or hook written now belongs to: the innermost open `describe`, else the file's own */
@@ -22,8 +23,8 @@ export function currentSuite(file) {
     return root;
 }
 /** Opens a `describe` block under the current suite; `leaveSuite` closes it */
-export function enterSuite(file, title, modifier) {
-    const suite = newSuite(title, currentSuite(file), modifier);
+export function enterSuite(file, title, modifier, reason) {
+    const suite = newSuite(title, currentSuite(file), modifier, reason);
     open.push(suite);
     return suite;
 }
@@ -37,18 +38,26 @@ export function resetSuites() {
 }
 /**
  * What applies to a test: the innermost `skip` or `fixme` (the test's own, then its suites', inside out), else
- * `only` when the test or any suite around it is focused. A skip beats a focus.
+ * `only` when the test or any suite around it is focused. A skip beats a focus. The reason comes with the skip
+ * or fixme that applies.
  */
 export function modifierOf(own, suite) {
-    let focused = own === "only";
-    let found = own === "only" ? undefined : own;
-    for (let s = suite; s && !found; s = s.parent) {
+    if (own.modifier === "skip" || own.modifier === "fixme")
+        return markOf(own);
+    let focused = own.modifier === "only";
+    for (let s = suite; s; s = s.parent) {
         if (s.modifier === "only")
             focused = true;
-        else
-            found = s.modifier;
+        else if (s.modifier)
+            return markOf(s);
     }
-    return found ?? (focused ? "only" : undefined);
+    return focused ? { modifier: "only" } : {};
+}
+function markOf({ modifier, reason }) {
+    return {
+        ...(modifier && { modifier }),
+        ...(reason !== undefined && { reason }),
+    };
 }
 /** The suites from the file's root down to `suite` */
 export function suiteChain(suite) {

package/dist/runner/test-runner.js

@@ -14,6 +14,8 @@ import { concurrency, planItems, poolMode, runPooled, serialKeyOf, } from "./poo
 import { allHookFixtures, runOneTest } from "./run-test.js";
 import { staticSkip } from "./skip.js";
 import { browsersOfRun, loadSpecs, selectTests } from "./select.js";
+import { resolveRetries } from "./retries-option.js";
+import { runWithRetries } from "./retry.js";
 import { resolveWorkers } from "./workers-option.js";
 import { WorkerPool } from "./worker-pool.js";
 import { processWorkerFactory } from "./worker-process.js";
@@ -75,6 +77,12 @@ export default class TestRunner {
             env: process.env.SAMURAI_WORKERS,
             config: config.workers,
         });
+        // A bad `retries` is an error here too, before any browser starts
+        const retries = resolveRetries({
+            flag: this.options.retries,
+            env: process.env.SAMURAI_RETRIES,
+            config: config.retries,
+        });
         const plan = planItems(selected, browsers, serialKeyOf(loaded.groups, config.groups, loaded.srcDir));
         // A pool larger than what can overlap would only hold idle workers: a group that runs one at a time needs one
         const lanes = concurrency(plan.items);
@@ -97,7 +105,7 @@ export default class TestRunner {
         if (mode === "pool") {
             const workers = Math.min(requested, lanes);
             reporter.onStart(plan.planned.length, workers);
-            const pool = this.createPool(workers);
+            const pool = this.createPool(workers, retries);
             try {
                 await runPooled(pool, plan.planned, plan.items, reporter, signal);
             }
@@ -115,9 +123,9 @@ export default class TestRunner {
         try {
             for (const browser of browsers) {
                 for (const test of selected) {
-                    const annotation = staticSkip(test);
-                    if (annotation) {
-                        reporter.onTestSkipped(test, browser, { annotation });
+                    const skip = staticSkip(test);
+                    if (skip) {
+                        reporter.onTestSkipped(test, browser, skip);
                         continue;
                     }
                     if (signal?.aborted) {
@@ -128,7 +136,7 @@ export default class TestRunner {
                         });
                         continue;
                     }
-                    await runOneTest(test, browser, this.run, this.options, loaded.srcDir, reporter, { allHooks });
+                    await runWithRetries(test, browser, retries, signal, (sink, attempt) => runOneTest(test, browser, this.run, this.options, loaded.srcDir, sink, { allHooks, attempt }), reporter);
                 }
             }
         }
@@ -145,7 +153,7 @@ export default class TestRunner {
             fromConfig !== undefined);
     }
     /** The pool of a run: up to `workers` worker processes that read the same project and settings as this run */
-    createPool(workers) {
+    createPool(workers, retries) {
         const { settings } = this.run;
         const { reportPath, headless, port } = this.options;
         const options = {
@@ -163,6 +171,7 @@ export default class TestRunner {
                 ...(typeof reportPath === "string" && { reportPath }),
                 files: this.testFiles,
                 basePort: port ?? DEFAULT_PORT,
+                ...(retries > 0 && { retries }),
             },
         };
         return (this.project.createPool ?? ((o) => new WorkerPool(o)))(options);

package/dist/runner/worker-pool.d.ts

@@ -4,6 +4,7 @@ export type PoolEvent = {
     type: "test-start";
     item: WorkItem;
     worker: number;
+    retry?: number;
 } | {
     type: "test-end";
     item: WorkItem;

package/dist/runner/worker-pool.js

@@ -187,6 +187,7 @@ export class WorkerPool {
                     type: "test-start",
                     item: busy.entry.item,
                     worker: slot.index,
+                    ...(message.retry && { retry: message.retry }),
                 });
             case "test-end":
                 if (busy?.id !== message.id)