@itmetsam/samurai-framework 0.15.0 → 0.15.2

package/dist/api.d.ts

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

package/dist/cli/args.d.ts

@@ -12,6 +12,7 @@ export declare function parseCommandLine(argv: string[]): {
         headless?: boolean | undefined;
         port?: string | undefined;
         workers?: string | undefined;
+        retries?: string | undefined;
         grep?: string | undefined;
         group?: string | undefined;
         browser?: string[] | undefined;
@@ -40,13 +41,15 @@ export interface RunnerFlags {
     port?: number;
     /** `--workers`: a whole number or a percentage like `50%`, as typed */
     workers?: string;
+    /** `--retries`: a whole number from 0, as typed */
+    retries?: string;
     grep?: string;
     group?: string;
     files?: string[];
     /** `--browser`, repeated for more than one; replaces the config's `browsers` for this run */
     browsers?: SupportedBrowser[];
 }
-/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv`, or from values that were parsed already */
+/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--retries <n>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv`, or from values that were parsed already */
 export declare function parseRunnerFlags(source: string[] | CommandValues): RunnerFlags;
 /** Reads `--env`, `--timeout` and `--expect-timeout` from `argv` (or values parsed already); the environment falls back to SAMURAI_ENV */
 export declare function parseRunOverrides(source: string[] | CommandValues, env?: Partial<NodeJS.ProcessEnv>): EnvAndTimeouts;

package/dist/cli/args.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { checkBrowserList, parseWorkers, } from "../runner/run.js";
+import { checkBrowserList, parseRetries, parseWorkers, } from "../runner/run.js";
 const FLAGS = {
     env: { type: "string" },
     timeout: { type: "string" },
@@ -7,6 +7,7 @@ const FLAGS = {
     headless: { type: "boolean" },
     port: { type: "string" },
     workers: { type: "string" },
+    retries: { type: "string" },
     grep: { type: "string" },
     group: { type: "string" },
     browser: { type: "string", multiple: true },
@@ -34,7 +35,7 @@ export function parseCommandLine(argv) {
     });
 }
 const valuesOf = (source) => Array.isArray(source) ? parseCommandLine(source).values : source;
-/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv`, or from values that were parsed already */
+/** Reads `--headless`, `--port <n>`, `--workers <n|n%>`, `--retries <n>`, `--grep <text>`, `--group <name>`, `--file <spec>` and `--browser <name>` (both repeatable) from `argv`, or from values that were parsed already */
 export function parseRunnerFlags(source) {
     const values = valuesOf(source);
     const flags = {};
@@ -51,6 +52,10 @@ export function parseRunnerFlags(source) {
         parseWorkers(values.workers, "--workers");
         flags.workers = values.workers;
     }
+    if (values.retries !== undefined) {
+        parseRetries(values.retries, "--retries");
+        flags.retries = values.retries;
+    }
     if (values.grep !== undefined)
         flags.grep = values.grep;
     if (values.group !== undefined)

package/dist/cli/console-reporter.js

@@ -1,5 +1,13 @@
 import { painter } from "./paint.js";
 const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+/** What a result says about its retries: `passed on retry 2`, `failed after 2 retries`, or nothing */
+function retried(result) {
+    if (!("retry" in result) || !result.retry)
+        return undefined;
+    if (result.status === "success")
+        return `passed on retry ${result.retry}`;
+    return `failed after ${result.retry} ${result.retry === 1 ? "retry" : "retries"}`;
+}
 /** Prints a run for a person: one line per test as it ends, then every failure in full and a count */
 export class ConsoleReporter {
     constructor({ write, color }) {
@@ -30,7 +38,7 @@ export class ConsoleReporter {
     }
     line(name, result, browser) {
         const took = "duration" in result
-            ? ` ${this.paint(90, `(${seconds(result.duration)})`)}`
+            ? ` ${this.paint(90, `(${[seconds(result.duration), retried(result)].filter(Boolean).join(", ")})`)}`
             : "";
         if (result.status === "skipped")
             return this.paint(90, `- ${name}${this.tag(browser)} (${result.annotation === "fixme" ? "fixme" : "skipped"}${result.reason ? `: ${result.reason}` : ""})`);
@@ -54,9 +62,10 @@ export class ConsoleReporter {
                 this.write(`    ${this.paint(90, test.file)}\n`);
         }
         const passed = summary.tests.length - failed.length - skipped.length;
+        const flaky = summary.tests.filter((test) => "flaky" in test && test.flaky).length;
         const parts = [
             failed.length > 0 && this.paint(31, `${failed.length} failed`),
-            this.paint(32, `${passed} passed`),
+            this.paint(32, `${passed} passed${flaky > 0 ? ` (${flaky} flaky)` : ""}`),
             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/flow.js

@@ -25,6 +25,7 @@ Options for run:
   --headless, --no-headless   Run the browser without a window, or with one
   --port <n>                  Browser debugging port (default ${DEFAULT_PORT})
   --workers <n|n%>            Worker processes the tests share (or SAMURAI_WORKERS; default half the CPUs)
+  --retries <n>               Run a failing test again up to n times, each with a fresh browser (or SAMURAI_RETRIES; default 0)
 
 Each run writes result/flows/<id>.json.
 Exit code: 0 when every node that should run passed, 1 when a node failed or the run was cancelled,
@@ -228,6 +229,10 @@ export async function flowCommand(argv, io) {
                     ...(io.env.SAMURAI_WORKERS && {
                         workersEnv: io.env.SAMURAI_WORKERS,
                     }),
+                    ...(flags.retries !== undefined && { retries: flags.retries }),
+                    ...(io.env.SAMURAI_RETRIES && {
+                        retriesEnv: io.env.SAMURAI_RETRIES,
+                    }),
                 },
             });
         }

package/dist/cli/main.js

@@ -48,6 +48,7 @@ export async function main(argv, io) {
             ...(flags.headless !== undefined && { headless: flags.headless }),
             ...(flags.port !== undefined && { port: flags.port }),
             ...(flags.workers !== undefined && { workers: flags.workers }),
+            ...(flags.retries !== undefined && { retries: flags.retries }),
             ...(flags.grep !== undefined && { grep: flags.grep }),
             ...(flags.group !== undefined && { group: flags.group }),
             ...(flags.files && { files: flags.files }),
@@ -59,7 +60,7 @@ export async function main(argv, io) {
                 io.out(`${JSON.stringify(tests, null, 2)}\n`);
             else
                 for (const found of tests)
-                    io.out(`${found.name}${found.modifier ? ` [${found.modifier}]` : ""}\n    ${found.file}\n`);
+                    io.out(`${found.name}${found.modifier ? ` [${found.modifier}${found.reason ? `: ${found.reason}` : ""}]` : ""}\n    ${found.file}\n`);
             return 0;
         }
         const human = values.json

package/dist/cli/usage.d.ts

@@ -1 +1 @@
-export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups\n  --browser <name>            Run in this browser (firefox or chrome) instead of the config's\n                              browsers; repeat it for more than one\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n  --workers <n|n%>            Tests that run at the same time, each in a worker process: a number\n                              from 1, or a share of the CPUs like 50%. Default: the config's\n                              workers (or SAMURAI_WORKERS), else half the CPUs\n\nOptions for record (also --env, --port, --json, --headless, --no-headless):\n  --browser <name>            Record in this browser (default: the first of the config's browsers)\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";
+export declare const USAGE = "samurai: browser tests over WebDriver BiDi\n\nUsage:\n  samurai run [options]       Run the tests (the default command)\n  samurai list [options]      List the tests without running them\n  samurai record <spec>       Open a browser and record what you do into a spec file\n  samurai init [folder]       Scaffold a project: config, an example test, .env.example\n  samurai flow <command>      List, check and run the flows in ./flows (see below)\n  samurai browsers [command]  List, install and remove the browsers SAMURAI launches\n\nOptions for run and list:\n  --env <name>                Environment to run against (or SAMURAI_ENV)\n  --file <spec>               Only this spec file; repeatable\n  --grep <text>               Only tests whose full name contains the text\n  --group <name>              Only the tests of this group of the config's groups\n  --browser <name>            Run in this browser (firefox or chrome) instead of the config's\n                              browsers; repeat it for more than one\n  --json                      Machine-readable output: JSON lines for run, one array for list\n\nOptions for run:\n  --timeout <ms>              Time one test may take\n  --expect-timeout <ms>       Time actions and assertions retry\n  --headless, --no-headless   Run the browser without a window, or with one.\n                              Default: the config's use.headless, else headless when CI is set\n  --port <n>                  Browser debugging port (default 9223)\n  --workers <n|n%>            Tests that run at the same time, each in a worker process: a number\n                              from 1, or a share of the CPUs like 50%. Default: the config's\n                              workers (or SAMURAI_WORKERS), else half the CPUs\n  --retries <n>               Run a failing test again up to n times, each with a fresh browser\n                              (or SAMURAI_RETRIES; default 0)\n\nOptions for record (also --env, --port, --json, --headless, --no-headless):\n  --browser <name>            Record in this browser (default: the first of the config's browsers)\n  --new <title>               Add a test with this title (creates the spec file if needed)\n  --test <name|index>         Record into this test; not needed when the file has one\n  --at <n>                    Insert from step n (default: after the last step)\n  --url <url>                 Page to start on (default: the environment's baseURL)\n  Stop with Ctrl+C or by closing the browser window.\n\n  -h, --help                  Show this help\n  -v, --version               Show the version\n\nExit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.\n\nsamurai flow:\n  list                        The flows in ./flows\n  check [<flow>...]           Check flows without running them\n  run <flow>... | --all       Run flows; each writes result/flows/<id>.json\n  Options for run: --env, --headless, --timeout, --expect-timeout, --port, --json, --allow-unsupported\n  Run `samurai flow` alone for the details.\n\nsamurai browsers:\n  list                        The pinned browsers and every build in the cache (the default)\n  install [firefox|chrome|all]\n                              Download the pinned builds (default: all)\n  uninstall <name> [--build <id>] | --unused\n\nRun it in the project folder, the one holding samurai.config.ts.\n";

package/dist/cli/usage.js

@@ -27,6 +27,8 @@ Options for run:
   --workers <n|n%>            Tests that run at the same time, each in a worker process: a number
                               from 1, or a share of the CPUs like 50%. Default: the config's
                               workers (or SAMURAI_WORKERS), else half the CPUs
+  --retries <n>               Run a failing test again up to n times, each with a fresh browser
+                              (or SAMURAI_RETRIES; default 0)
 
 Options for record (also --env, --port, --json, --headless, --no-headless):
   --browser <name>            Record in this browser (default: the first of the config's browsers)

package/dist/config/config.js

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

@@ -0,0 +1,8 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+/**
+ * Reads a `retries` value: a whole number from 0, as a number or as text. `where` names the source (`--retries`,
+ * `SAMURAI_RETRIES`, a config key) in the error.
+ */
+export declare function parseRetries(value: unknown, where: string): number;
+/** Checks the `retries` key of a config. Throws an Error that names the key */
+export declare function validateRetriesConfig(config: SamuraiTestConfig): void;

package/dist/config/retries.js

@@ -0,0 +1,19 @@
+/**
+ * Reads a `retries` value: a whole number from 0, as a number or as text. `where` names the source (`--retries`,
+ * `SAMURAI_RETRIES`, a config key) in the error.
+ */
+export function parseRetries(value, where) {
+    if (typeof value === "number" && Number.isInteger(value) && value >= 0)
+        return value;
+    if (typeof value === "string" && /^\s*\d+\s*$/.test(value))
+        return Number(value.trim());
+    throw new Error(`${where} must be a whole number from 0, got "${String(value)}"`);
+}
+/** Checks the `retries` key of a config. Throws an Error that names the key */
+export function validateRetriesConfig(config) {
+    if (config.retries === undefined)
+        return;
+    if (typeof config.retries !== "number")
+        throw new Error(`retries must be a whole number from 0, got "${String(config.retries)}"`);
+    parseRetries(config.retries, "retries");
+}

package/dist/flows/run/node-pool.d.ts

@@ -0,0 +1,9 @@
+import type { RunEvent } from "../../runner/reporter.js";
+import type { WorkerPool } from "../../runner/worker-pool.js";
+import type { WorkItem } from "../../runner/worker-protocol.js";
+import type { SupportedBrowser } from "../../types/browser.js";
+import type { NodeTest } from "./events.js";
+/** The work items of a node: each test in each browser, the browsers one after the other */
+export declare function itemsOf(tests: NodeTest[], browsers: readonly SupportedBrowser[]): WorkItem[];
+/** Runs the tests of a node on the pool and reports them as a run would */
+export declare function runOnPool(pool: Pick<WorkerPool, "run">, items: WorkItem[], onEvent: (event: RunEvent) => void, signal: AbortSignal): Promise<"passed" | "failed" | "cancelled">;

package/dist/flows/run/node-pool.js

@@ -0,0 +1,27 @@
+/** The work items of a node: each test in each browser, the browsers one after the other */
+export 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 */
+export 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-start" &&
+                event.retry && { retry: event.retry }),
+            ...(event.type === "test-end" && { result: event.result }),
+        }),
+    });
+    if (signal.aborted)
+        return "cancelled";
+    // A skipped test is not a failure
+    return results.every((r) => r.status === "success" || r.status === "skipped")
+        ? "passed"
+        : "failed";
+}

package/dist/flows/run/project-options.d.ts

@@ -0,0 +1,44 @@
+import type { ProjectOptions } from "../../runner/project.js";
+import type { PoolOptions, WorkerPool } from "../../runner/worker-pool.js";
+import type { runTests } from "../../runner/run.js";
+import type { FlowFile, FlowProblem } from "../core/index.js";
+import type { FlowEvent } from "./events.js";
+/** The flow has errors; nothing was run */
+export declare class FlowCheckError extends Error {
+    readonly problems: FlowProblem[];
+    constructor(problems: FlowProblem[]);
+}
+export interface RunFlowInProjectOptions extends ProjectOptions {
+    /** The flow to run... */
+    flow?: FlowFile;
+    /** ...or the id of one in `<project>/flows` */
+    flowId?: string;
+    /** Beats the flow's `envDefault`, the config's `defaultEnvironment` and the first environment */
+    environment?: string;
+    signal?: AbortSignal;
+    onEvent?: (event: FlowEvent) => void;
+    /** `"fail"` (default): a flow with a node that can't run is refused. `"skip"`: those nodes are skipped. */
+    unsupported?: "fail" | "skip";
+    port?: number;
+    /**
+     * How many worker processes the tests of the whole run share: a number, or a percentage like `"50%"`. Unset
+     * takes `SAMURAI_WORKERS` (`workersEnv`), then the config's `workers`, then half the CPUs. 1 runs each Test
+     * and Group node through `runTests` in this process; more starts one pool that every node, and every branch
+     * of a Parallel node, takes its workers from
+     */
+    workers?: number | string;
+    /** The value of `SAMURAI_WORKERS`, when set */
+    workersEnv?: string;
+    /** How many times a failing test is run again: a number, or numeric text like the command line's `--retries`. Unset takes `SAMURAI_RETRIES` (`retriesEnv`), then the config's `retries`, then 0 */
+    retries?: number | string;
+    /** The value of `SAMURAI_RETRIES`, when set */
+    retriesEnv?: string;
+    /** @internal Replaces the worker pool (tests) */
+    createPool?: (options: PoolOptions) => Pick<WorkerPool, "run" | "dispose">;
+    /** @internal Replaces the runner of each Test and Group node (tests) */
+    testRunner?: typeof runTests;
+    /** @internal */
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/** What `runFlowInProject` takes when the flow itself is given separately: everything but `flow` and `flowId` */
+export type FlowRunOptions = Omit<RunFlowInProjectOptions, "flow" | "flowId">;

package/dist/flows/run/project-options.js

@@ -0,0 +1,8 @@
+/** 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";
+    }
+}

package/dist/flows/run/project.d.ts

@@ -1,46 +1,11 @@
 import { type FlowFile, type FlowProblem } from "../core/index.js";
 import { type ResolvedGroup } from "../../runner/groups.js";
-import { type ProjectOptions } from "../../runner/project.js";
-import { runTests } from "../../runner/run.js";
-import { WorkerPool, type PoolOptions } from "../../runner/worker-pool.js";
 import type { SamuraiTestConfig } from "../../types/config.js";
-import type { FlowEvent, FlowSummary, NodeTest } from "./events.js";
+import type { FlowSummary, NodeTest } from "./events.js";
+import { FlowCheckError, type FlowRunOptions, type RunFlowInProjectOptions } from "./project-options.js";
 import type { SupportedBrowser } from "../../types/browser.js";
-/** The flow has errors; nothing was run */
-export declare class FlowCheckError extends Error {
-    readonly problems: FlowProblem[];
-    constructor(problems: FlowProblem[]);
-}
-export interface RunFlowInProjectOptions extends ProjectOptions {
-    /** The flow to run... */
-    flow?: FlowFile;
-    /** ...or the id of one in `<project>/flows` */
-    flowId?: string;
-    /** Beats the flow's `envDefault`, the config's `defaultEnvironment` and the first environment */
-    environment?: string;
-    signal?: AbortSignal;
-    onEvent?: (event: FlowEvent) => void;
-    /** `"fail"` (default): a flow with a node that can't run is refused. `"skip"`: those nodes are skipped. */
-    unsupported?: "fail" | "skip";
-    port?: number;
-    /**
-     * How many worker processes the tests of the whole run share: a number, or a percentage like `"50%"`. Unset
-     * takes `SAMURAI_WORKERS` (`workersEnv`), then the config's `workers`, then half the CPUs. 1 runs each Test
-     * and Group node through `runTests` in this process; more starts one pool that every node, and every branch
-     * of a Parallel node, takes its workers from
-     */
-    workers?: number | string;
-    /** The value of `SAMURAI_WORKERS`, when set */
-    workersEnv?: string;
-    /** @internal Replaces the worker pool (tests) */
-    createPool?: (options: PoolOptions) => Pick<WorkerPool, "run" | "dispose">;
-    /** @internal Replaces the runner of each Test and Group node (tests) */
-    testRunner?: typeof runTests;
-    /** @internal */
-    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
-}
-/** What `runFlowInProject` takes when the flow itself is given separately: everything but `flow` and `flowId` */
-export type FlowRunOptions = Omit<RunFlowInProjectOptions, "flow" | "flowId">;
+export { FlowCheckError };
+export type { FlowRunOptions, RunFlowInProjectOptions };
 /** The environment: the option, else the flow's `envDefault` (when the project has it), else the config's default, else the first, else "default" */
 export declare function chooseEnvironment(config: SamuraiTestConfig, flow: FlowFile, option?: string): string;
 /** A test of the project as flows see it */
@@ -71,4 +36,3 @@ export declare function checkFlowInProject(options: Pick<RunFlowInProjectOptions
  * One at a time per process.
  */
 export declare function runFlowInProject(options: RunFlowInProjectOptions): Promise<FlowSummary>;
-export {};

package/dist/flows/run/project.js

@@ -3,6 +3,7 @@ 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, { 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,31 +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";
-    // 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) {
     const byId = new Map(tests.map((t) => [t.id, t]));
@@ -182,6 +153,12 @@ async function walkFlowInProject(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)))({
@@ -200,6 +177,7 @@ async function walkFlowInProject(options) {
                 }),
                 files,
                 basePort: options.port ?? DEFAULT_PORT,
+                ...(retries > 0 && { retries }),
             },
         })
         : undefined;
@@ -230,6 +208,7 @@ async function walkFlowInProject(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),

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;