@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/cli/main.js

@@ -0,0 +1,156 @@
+import { readFileSync } from "node:fs";
+import { parseCommandLine, parseRunnerFlags, parseRunOverrides } from "./args.js";
+import { recordSpec } from "../recorder/index.js";
+import { listTests, runTests } from "../runner/run.js";
+import { stepToSource } from "../steps/index.js";
+import { ConsoleReporter } from "./console-reporter.js";
+import { initProject } from "./init.js";
+export const USAGE = `samurai: browser tests over WebDriver BiDi
+
+Usage:
+  samurai run [options]       Run the tests (the default command)
+  samurai list [options]      List the tests without running them
+  samurai record <spec>       Open a browser and record what you do into a spec file
+  samurai init [folder]       Scaffold a project: config, an example test, .env.example
+
+Options for run and list:
+  --env <name>                Environment to run against (or SAMURAI_ENV)
+  --file <spec>               Only this spec file; repeatable
+  --grep <text>               Only tests whose full name contains the text
+  --json                      Machine-readable output: JSON lines for run, one array for list
+
+Options for run:
+  --timeout <ms>              Time one test may take
+  --expect-timeout <ms>       Time actions and assertions retry
+  --headless                  Run the browser without a window
+  --port <n>                  Browser debugging port (default 9223)
+
+Options for record (also --env, --port, --json):
+  --new <title>               Add a test with this title (creates the spec file if needed)
+  --test <name|index>         Record into this test; not needed when the file has one
+  --at <n>                    Insert from step n (default: after the last step)
+  --url <url>                 Page to start on (default: the environment's baseURL)
+  Stop with Ctrl+C or by closing the browser window.
+
+  -h, --help                  Show this help
+  -v, --version               Show the version
+
+Exit code: 0 when every test passed, 1 when a test failed, 2 for a usage or configuration error.
+Run it in the project folder, the one holding samurai.config.ts.
+`;
+function version() {
+    const manifest = new URL("../../package.json", import.meta.url);
+    return JSON.parse(readFileSync(manifest, "utf8"))
+        .version;
+}
+/** The command line as `samurai` runs it. Returns the exit code */
+export async function main(argv, io) {
+    try {
+        const first = argv[0];
+        const command = first !== undefined && !first.startsWith("-") ? first : "run";
+        const rest = command === first ? argv.slice(1) : argv;
+        const { values, positionals } = parseCommandLine(rest);
+        if (values.help || command === "help") {
+            io.out(USAGE);
+            return 0;
+        }
+        if (values.version) {
+            io.out(`${version()}\n`);
+            return 0;
+        }
+        if (command === "init") {
+            const { written, skipped } = initProject(positionals[0] ?? ".");
+            for (const file of written)
+                io.out(`created ${file}\n`);
+            for (const file of skipped)
+                io.out(`kept    ${file} (already there)\n`);
+            io.out("\nNext: install the dependencies, then `samurai run`.\n");
+            return 0;
+        }
+        if (command === "record") {
+            const file = positionals[0];
+            if (!file)
+                throw new Error("Which spec? Usage: samurai record <spec> [--new <title>]");
+            const at = values.at === undefined ? undefined : Number(values.at);
+            if (at !== undefined && (!Number.isInteger(at) || at < 0))
+                throw new Error(`--at must be a step number, got "${values.at}"`);
+            const flags = parseRunnerFlags(rest);
+            const test = values.test === undefined
+                ? undefined
+                : /^\d+$/.test(values.test)
+                    ? Number(values.test)
+                    : values.test;
+            let count = 0;
+            const result = await recordSpec({
+                ...parseRunOverrides(rest, io.env),
+                file,
+                ...(test !== undefined && { test }),
+                ...(values.new !== undefined && { create: values.new }),
+                ...(at !== undefined && { at }),
+                ...(values.url !== undefined && { url: values.url }),
+                ...(flags.port !== undefined && { port: flags.port }),
+                ...(io.signal && { signal: io.signal }),
+                onStarted: () => {
+                    if (!values.json)
+                        io.out("Recording. Alt+click an element to assert on it. Press Ctrl+C or close the window to stop.\n");
+                },
+                onEvent: (event) => {
+                    if (values.json)
+                        return void io.out(`${JSON.stringify(event)}\n`);
+                    if (event.op === "insert")
+                        io.out(`  + ${stepToSource(event.step)}\n`);
+                    else
+                        io.out(`  ~ ${stepToSource(event.step)}\n`);
+                    if (event.op === "insert")
+                        count++;
+                },
+            });
+            if (!values.json) {
+                io.out(`\nRecorded ${count} ${count === 1 ? "step" : "steps"} into "${result.test}" in ${result.file}\n`);
+                if (result.secrets.length > 0) {
+                    io.out(`Set ${result.secrets.map((name) => `SAMURAI_SECRET_${name}`).join(", ")} (environment variable or .env.<environment>) before running it.\n`);
+                }
+            }
+            return 0;
+        }
+        if (command !== "run" && command !== "list") {
+            io.err(`Unknown command "${command}"\n\n${USAGE}`);
+            return 2;
+        }
+        const flags = parseRunnerFlags(rest);
+        const options = {
+            ...parseRunOverrides(rest, io.env),
+            ...(flags.headless !== undefined && { headless: flags.headless }),
+            ...(flags.port !== undefined && { port: flags.port }),
+            ...(flags.grep !== undefined && { grep: flags.grep }),
+            ...(flags.files && { files: flags.files }),
+        };
+        if (command === "list") {
+            const tests = await listTests(options);
+            if (values.json)
+                io.out(`${JSON.stringify(tests, null, 2)}\n`);
+            else
+                for (const found of tests)
+                    io.out(`${found.name}\n    ${found.file}\n`);
+            return 0;
+        }
+        const human = values.json
+            ? undefined
+            : new ConsoleReporter({ write: io.out, color: io.color });
+        const summary = await runTests({
+            ...options,
+            ...(io.signal && { signal: io.signal }),
+            onEvent: (event) => {
+                if (values.json)
+                    io.out(`${JSON.stringify(event)}\n`);
+                else
+                    human?.handle(event);
+            },
+        });
+        return summary.status === "success" ? 0 : 1;
+    }
+    catch (err) {
+        io.err(`${err instanceof Error ? err.message : String(err)}\n`);
+        return 2;
+    }
+}

package/dist/config/config.d.ts

@@ -0,0 +1,24 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+/** The project a run belongs to; without one, everything is relative to the working directory */
+interface ActiveProject {
+    dir: string;
+    /** Used instead of reading `samurai.config.ts` */
+    config?: SamuraiTestConfig | undefined;
+    /** Where the framework keeps browser profiles; see `browsersDir` */
+    dataDir?: string | undefined;
+}
+/** Makes `project` the one config, secrets, reports and downloads are resolved for; `undefined` ends it */
+export declare function setActiveProject(project: ActiveProject | undefined): void;
+/** The folder of the project being run: the active project's, else the working directory */
+export declare function projectDir(): string;
+/**
+ * Where the framework keeps what it generates for browsers (profile preferences, Firefox app data):
+ * `SAMURAI_DATA_DIR`, else the active project's `dataDir`, else `browsers/` in the project folder.
+ * An embedding app points it at a folder it may write to.
+ */
+export declare function browsersDir(): string;
+/** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
+export declare function loadConfig(): Promise<SamuraiTestConfig>;
+export declare function readConfig<K extends keyof SamuraiTestConfig>(key: K): Promise<SamuraiTestConfig[K]>;
+export declare function defineConfig(config: SamuraiTestConfig): SamuraiTestConfig;
+export {};

package/dist/config/config.js

@@ -0,0 +1,42 @@
+import path from "path";
+import logger from "../logger/index.js";
+import { pathToFileURL } from "url";
+let activeProject;
+/** Makes `project` the one config, secrets, reports and downloads are resolved for; `undefined` ends it */
+export function setActiveProject(project) {
+    activeProject = project && { ...project, dir: path.resolve(project.dir) };
+}
+/** The folder of the project being run: the active project's, else the working directory */
+export function projectDir() {
+    return activeProject?.dir ?? process.cwd();
+}
+/**
+ * Where the framework keeps what it generates for browsers (profile preferences, Firefox app data):
+ * `SAMURAI_DATA_DIR`, else the active project's `dataDir`, else `browsers/` in the project folder.
+ * An embedding app points it at a folder it may write to.
+ */
+export function browsersDir() {
+    return path.resolve(process.env.SAMURAI_DATA_DIR ??
+        activeProject?.dataDir ??
+        path.join(projectDir(), "browsers"));
+}
+/** The whole `samurai.config.ts` of the project (the working directory unless a project is active) */
+export async function loadConfig() {
+    if (activeProject?.config)
+        return activeProject.config;
+    const configUrl = path.join(projectDir(), "samurai.config.ts");
+    logger.debug("Reading config from: %s", configUrl);
+    const config = (await import(pathToFileURL(configUrl).href));
+    if (!config.default) {
+        throw new Error("samurai.config.ts does not export defineConfig as default!");
+    }
+    return config.default;
+}
+export async function readConfig(key) {
+    const value = (await loadConfig())[key];
+    logger.debug("Resolved config value: ", { value });
+    return value;
+}
+export function defineConfig(config) {
+    return config;
+}

package/dist/config/default.d.ts

@@ -0,0 +1,2 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+export declare const config: SamuraiTestConfig;

package/dist/config/default.js

@@ -0,0 +1,3 @@
+export const config = {
+    srcDir: "./src",
+};

package/dist/config/mask.d.ts

@@ -0,0 +1,11 @@
+export declare const MASK = "\u2022\u2022\u2022\u2022";
+/** Registers a secret value; every later maskText/maskDeep/log line hides it */
+export declare function registerSecret(name: string, value: string): void;
+/** Forgets every registered secret (tests only) */
+export declare function resetSecrets(): void;
+export declare function isShortSecret(value: string): boolean;
+export declare function maskText(text: string): string;
+/** A copy of `value` with every string in it masked, following JSON.stringify semantics for objects */
+export declare function maskDeep<T>(value: T): T;
+/** Winston format that masks every string field of a log entry (message and metadata) */
+export declare const maskFormat: import("logform").FormatWrap;

package/dist/config/mask.js

@@ -0,0 +1,85 @@
+import { inspect } from "node:util";
+import { format } from "winston";
+export const MASK = "••••";
+/** Values shorter than this only match as a whole token, so "1" does not hide every digit */
+const SHORT_LENGTH = 4;
+const secrets = new Map();
+let patterns = [];
+/** Registers a secret value; every later maskText/maskDeep/log line hides it */
+export function registerSecret(name, value) {
+    if (value === "")
+        return;
+    secrets.set(name, value);
+    rebuild();
+}
+/** Forgets every registered secret (tests only) */
+export function resetSecrets() {
+    secrets.clear();
+    patterns = [];
+}
+export function isShortSecret(value) {
+    return value.length > 0 && value.length < SHORT_LENGTH;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** A value plus its JSON-escaped, inspect-escaped and percent-encoded spellings */
+function variants(value) {
+    const forms = [value, JSON.stringify(value).slice(1, -1), inspect(value).slice(1, -1), encodeURIComponent(value)];
+    return forms.filter((form) => form !== "");
+}
+function rebuild() {
+    // Longest first, so a secret that contains another one is hidden whole
+    const forms = [...new Set([...secrets.values()].flatMap(variants))].sort((a, b) => b.length - a.length);
+    patterns = forms.map((value) => isShortSecret(value)
+        ? new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(value)}(?![\\p{L}\\p{N}])`, "gu")
+        : new RegExp(escapeRegExp(value), "gu"));
+}
+export function maskText(text) {
+    let masked = text;
+    for (const pattern of patterns)
+        masked = masked.replace(pattern, MASK);
+    return masked;
+}
+/** A copy of `value` with every string in it masked, following JSON.stringify semantics for objects */
+export function maskDeep(value) {
+    if (patterns.length === 0)
+        return value;
+    return walk(value, new WeakSet());
+}
+function walk(value, path) {
+    if (typeof value === "string")
+        return maskText(value);
+    if (value === null || typeof value !== "object")
+        return value;
+    if (path.has(value))
+        return "[Circular]";
+    path.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((item) => walk(item, path));
+        const toJSON = value.toJSON;
+        if (typeof toJSON === "function")
+            return walk(toJSON.call(value), path);
+        const entries = Object.entries(value);
+        if (value instanceof Error) {
+            const own = new Set(entries.map(([key]) => key));
+            for (const key of ["name", "message", "stack"]) {
+                if (!own.has(key))
+                    entries.unshift([key, value[key]]);
+            }
+        }
+        return Object.fromEntries(entries.map(([key, item]) => [key, walk(item, path)]));
+    }
+    finally {
+        path.delete(value);
+    }
+}
+/** Winston format that masks every string field of a log entry (message and metadata) */
+export const maskFormat = format((info) => {
+    if (patterns.length === 0)
+        return info;
+    for (const key of Object.keys(info))
+        info[key] = walk(info[key], new WeakSet());
+    return info;
+});

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

@@ -0,0 +1,28 @@
+import type { SamuraiTestConfig } from "../types/config.js";
+export type Variables = Record<string, string | number | boolean>;
+/** Values given for one run (CLI flags, SAMURAI_ENV); they beat the config */
+export interface RunOverrides {
+    environment?: string;
+    timeout?: number;
+    expectTimeout?: number;
+}
+/** Everything about a run that depends on the chosen environment */
+export interface RunSettings {
+    environment: string;
+    baseURL?: string;
+    /** Time (ms) one test may take */
+    timeout: number;
+    /** Time (ms) actions and assertions retry */
+    expectTimeout: number;
+    variables: Variables;
+}
+export declare class UnknownEnvironmentError extends Error {
+    constructor(message: string);
+}
+/** Picks the environment and applies precedence: run override > environment > project > built-in default */
+export declare function resolveRunSettings(config: SamuraiTestConfig, overrides?: RunOverrides): RunSettings;
+/** Makes `settings` the run's settings; `undefined` ends the run (tests use this to reset) */
+export declare function setRunSettings(settings: RunSettings | undefined): void;
+/** The active run's settings, or undefined outside a run (unit and browser tests) */
+export declare function peekRunSettings(): RunSettings | undefined;
+export declare function getRunSettings(): RunSettings;

package/dist/config/run-settings.js

@@ -0,0 +1,61 @@
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_EXPECT_TIMEOUT = 5000;
+/** The environment of a config without `environments` */
+const IMPLICIT_ENVIRONMENT = "default";
+export class UnknownEnvironmentError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnknownEnvironmentError";
+    }
+}
+/** Picks the environment and applies precedence: run override > environment > project > built-in default */
+export function resolveRunSettings(config, overrides = {}) {
+    const environments = config.environments ?? {};
+    const names = Object.keys(environments);
+    const available = `Available: ${names.join(", ")}`;
+    let name = overrides.environment ?? config.defaultEnvironment;
+    if (name === undefined) {
+        if (names.length === 0)
+            name = IMPLICIT_ENVIRONMENT;
+        else if (names.length === 1)
+            name = names[0];
+        else
+            throw new UnknownEnvironmentError(`No environment chosen. ${available} (use --env or set defaultEnvironment)`);
+    }
+    const environment = Object.prototype.hasOwnProperty.call(environments, name)
+        ? environments[name]
+        : undefined;
+    if (!environment && !(names.length === 0 && name === IMPLICIT_ENVIRONMENT)) {
+        throw new UnknownEnvironmentError(names.length === 0
+            ? `Unknown environment "${name}". No environments are defined in samurai.config.ts`
+            : `Unknown environment "${name}". ${available}`);
+    }
+    const baseURL = environment?.baseURL ?? config.baseURL;
+    return {
+        environment: name,
+        ...(baseURL !== undefined && { baseURL }),
+        timeout: overrides.timeout ??
+            environment?.timeout ??
+            config.timeout ??
+            DEFAULT_TIMEOUT,
+        expectTimeout: overrides.expectTimeout ??
+            environment?.expect?.timeout ??
+            config.expect?.timeout ??
+            DEFAULT_EXPECT_TIMEOUT,
+        variables: { ...(environment?.variables ?? {}) },
+    };
+}
+let active;
+/** Makes `settings` the run's settings; `undefined` ends the run (tests use this to reset) */
+export function setRunSettings(settings) {
+    active = settings;
+}
+/** The active run's settings, or undefined outside a run (unit and browser tests) */
+export function peekRunSettings() {
+    return active;
+}
+export function getRunSettings() {
+    if (!active)
+        throw new Error("No test run is active; run settings are set when the runner starts");
+    return active;
+}

package/dist/config/secrets.d.ts

@@ -0,0 +1,10 @@
+export declare class MissingSecretError extends Error {
+    constructor(name: string, environment: string);
+}
+/** Secrets by name: `.env.<environment>` in `cwd` first, then env vars (which win) */
+export declare function loadSecrets(environment: string, options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Map<string, string>;
+/** The test's `secrets`: values by name, read-only; JSON and inspect show only masks */
+export declare function createSecretsFixture(environment: string, values: ReadonlyMap<string, string>): Readonly<Record<string, string>>;

package/dist/config/secrets.js

@@ -0,0 +1,67 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { inspect, parseEnv } from "node:util";
+import { projectDir } from "./config.js";
+import logger from "../logger/index.js";
+import { MASK } from "./mask.js";
+import { isPassthroughKey } from "./variables.js";
+const PREFIX = "SAMURAI_SECRET_";
+const NAME = /^[A-Z][A-Z0-9_]*$/;
+export class MissingSecretError extends Error {
+    constructor(name, environment) {
+        super(`Secret "${name}" is not set (expected env var ${PREFIX}${name} or .env.${environment})`);
+        this.name = "MissingSecretError";
+    }
+}
+/** Secrets by name: `.env.<environment>` in `cwd` first, then env vars (which win) */
+export function loadSecrets(environment, options = {}) {
+    const file = path.join(options.cwd ?? projectDir(), `.env.${environment}`);
+    const sources = [];
+    if (existsSync(file))
+        sources.push(parseEnv(readFileSync(file, "utf8")));
+    sources.push(options.env ?? process.env);
+    const secrets = new Map();
+    for (const source of sources) {
+        for (const [key, value] of Object.entries(source)) {
+            if (!key.startsWith(PREFIX) || value === undefined || value === "")
+                continue;
+            const name = key.slice(PREFIX.length);
+            if (!NAME.test(name)) {
+                logger.warn(`Ignoring ${key}: secret names must be UPPER_SNAKE_CASE`);
+                continue;
+            }
+            secrets.set(name, value);
+        }
+    }
+    return secrets;
+}
+/** The test's `secrets`: values by name, read-only; JSON and inspect show only masks */
+export function createSecretsFixture(environment, values) {
+    const masked = () => Object.fromEntries([...values.keys()].map((name) => [name, MASK]));
+    // Not frozen: the get trap returns the real value, which a frozen target's invariants forbid
+    const target = masked();
+    Object.defineProperty(target, "toJSON", { value: masked, enumerable: false });
+    Object.defineProperty(target, inspect.custom, {
+        value: masked,
+        enumerable: false,
+    });
+    const readOnly = () => {
+        throw new TypeError("secrets are read-only");
+    };
+    return new Proxy(target, {
+        get(target, key, receiver) {
+            if (isPassthroughKey(target, key))
+                return Reflect.get(target, key, receiver);
+            const name = String(key);
+            if (!NAME.test(name))
+                throw new Error(`Invalid secret name "${name}" (use UPPER_SNAKE_CASE)`);
+            const value = values.get(name);
+            if (value === undefined)
+                throw new MissingSecretError(name, environment);
+            return value;
+        },
+        set: readOnly,
+        defineProperty: readOnly,
+        deleteProperty: readOnly,
+    });
+}

package/dist/config/variables.d.ts

@@ -0,0 +1,11 @@
+import type { Variables } from "./run-settings.js";
+export declare class UnknownVariableError extends Error {
+    constructor(name: string, environment: string);
+}
+/**
+ * Keys that every object answers and that `await`, JSON.stringify and util.inspect probe:
+ * symbols, `then`, `toJSON` and Object.prototype members. Reading them never throws.
+ */
+export declare function isPassthroughKey(target: object, key: string | symbol): boolean;
+/** The test's `env`: the environment's variables, read-only; an unknown name throws */
+export declare function createEnvFixture(environment: string, variables: Variables): Readonly<Variables>;

package/dist/config/variables.js

@@ -0,0 +1,26 @@
+export class UnknownVariableError extends Error {
+    constructor(name, environment) {
+        super(`Variable "${name}" is not defined in environment "${environment}"`);
+        this.name = "UnknownVariableError";
+    }
+}
+/**
+ * Keys that every object answers and that `await`, JSON.stringify and util.inspect probe:
+ * symbols, `then`, `toJSON` and Object.prototype members. Reading them never throws.
+ */
+export function isPassthroughKey(target, key) {
+    return (typeof key === "symbol" ||
+        key === "then" ||
+        key === "toJSON" ||
+        (!Object.prototype.hasOwnProperty.call(target, key) && key in target));
+}
+/** The test's `env`: the environment's variables, read-only; an unknown name throws */
+export function createEnvFixture(environment, variables) {
+    return new Proxy(Object.freeze({ ...variables }), {
+        get(target, key, receiver) {
+            if (isPassthroughKey(target, key) || Object.prototype.hasOwnProperty.call(target, key))
+                return Reflect.get(target, key, receiver);
+            throw new UnknownVariableError(String(key), environment);
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,15 @@
+import { main } from "./cli/main.js";
+// Development entry (`bun run dev`): the same as `samurai run`, straight from the sources
+const interrupt = new AbortController();
+process.on("SIGINT", () => {
+    if (interrupt.signal.aborted)
+        process.exit(130);
+    interrupt.abort();
+});
+process.exit(await main(process.argv.slice(2), {
+    out: (text) => process.stdout.write(text),
+    err: (text) => process.stderr.write(text),
+    color: Boolean(process.stdout.isTTY) && !process.env.NO_COLOR,
+    env: process.env,
+    signal: interrupt.signal,
+}));

package/dist/locator/action-timeout-error.d.ts

@@ -0,0 +1,25 @@
+import type { CheckResults, WaitForState } from "./element-state.js";
+export type ActionTimeoutReason = "unreadable" | "not-attached" | "not-actionable" | "wrong-state";
+export interface ActionTimeoutDetails {
+    /** Locator method that timed out, e.g. "click" */
+    action: string;
+    selector: string;
+    timeout: number;
+    reason: ActionTimeoutReason;
+    /** Check results from the last probe, in check order */
+    checks?: CheckResults | undefined;
+    /** Description of the element covering the target, when the hit-target check failed */
+    coveredBy?: string | undefined;
+    /** Target state, for waitFor */
+    state?: WaitForState | undefined;
+}
+export declare class ActionTimeoutError extends Error {
+    readonly action: string;
+    readonly selector: string;
+    readonly timeout: number;
+    readonly reason: ActionTimeoutReason;
+    readonly checks: CheckResults | undefined;
+    readonly coveredBy: string | undefined;
+    readonly state: WaitForState | undefined;
+    constructor(details: ActionTimeoutDetails);
+}

package/dist/locator/action-timeout-error.js

@@ -0,0 +1,35 @@
+const SYMBOLS = { pass: "✓", fail: "✗", pending: "—" };
+function formatMessage({ action, selector, timeout, reason, checks, coveredBy, state, }) {
+    switch (reason) {
+        case "unreadable":
+            return `${action}(): could not read ${selector} within ${timeout}ms`;
+        case "not-attached":
+            return `${action}(): ${selector} was not attached within ${timeout}ms`;
+        case "wrong-state":
+            return `${action}(): ${selector} did not become ${state} within ${timeout}ms`;
+        case "not-actionable": {
+            const summary = Object.entries(checks ?? {})
+                .map(([name, result]) => {
+                const covered = name === "hit target" && result === "fail" && coveredBy
+                    ? ` (covered by ${coveredBy})`
+                    : "";
+                return `${name} ${SYMBOLS[result]}${covered}`;
+            })
+                .join("  ");
+            return `${action}(): ${selector} was not actionable within ${timeout}ms\n  ${summary}`;
+        }
+    }
+}
+export class ActionTimeoutError extends Error {
+    constructor(details) {
+        super(formatMessage(details));
+        this.name = "ActionTimeoutError";
+        this.action = details.action;
+        this.selector = details.selector;
+        this.timeout = details.timeout;
+        this.reason = details.reason;
+        this.checks = details.checks;
+        this.coveredBy = details.coveredBy;
+        this.state = details.state;
+    }
+}