@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/recorder/session.js

@@ -0,0 +1,113 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { Browser } from "../browser/browser.js";
+import { projectDir } from "../config/config.js";
+import { withProject } from "../runner/project.js";
+import { parseSpec } from "../steps/parse.js";
+import { applyRecorderEvent } from "./apply.js";
+const NEW_SPEC_HEADER = `import { expect, test } from "@itmetsam/samurai-framework";\n\n`;
+function addTest(source, title) {
+    const header = source.trim() === ""
+        ? NEW_SPEC_HEADER
+        : `${source.replace(/\s*$/, "")}\n\n`;
+    return `${header}test(${JSON.stringify(title)}, async ({ page }) => {\n});\n`;
+}
+/** The index of the test `selector` names (see `RecordSpecOptions.test`) */
+export function pickTest(tests, selector) {
+    if (tests.length === 0)
+        throw new Error("The file has no tests; give a title with --new to add one");
+    if (selector === undefined) {
+        if (tests.length === 1)
+            return 0;
+        throw new Error(`The file has ${tests.length} tests; choose one with --test:\n${tests.map((t) => `  ${t.name}`).join("\n")}`);
+    }
+    if (typeof selector === "number") {
+        if (!Number.isInteger(selector) ||
+            selector < 0 ||
+            selector >= tests.length) {
+            throw new Error(`There is no test ${selector}; the file has ${tests.length}`);
+        }
+        return selector;
+    }
+    const exact = tests.findIndex((t) => t.name === selector);
+    if (exact !== -1)
+        return exact;
+    const partial = tests.flatMap((t, index) => t.name.includes(selector) ? [index] : []);
+    if (partial.length === 1)
+        return partial[0];
+    throw new Error(partial.length === 0
+        ? `No test matches "${selector}". Tests:\n${tests.map((t) => `  ${t.name}`).join("\n")}`
+        : `"${selector}" matches ${partial.length} tests; use the full name`);
+}
+/**
+ * Opens a browser window and records what the person does into a spec file, step by step, until `signal`
+ * aborts or the window is closed. Every step is written to the file as it happens, as a minimal edit.
+ * @example
+ *  await recordSpec({ file: "tests/login.spec.ts", create: "signs in", environment: "staging" });
+ */
+export async function recordSpec(options) {
+    return withProject(options, async ({ settings }) => {
+        const file = path.resolve(projectDir(), options.file);
+        let source = existsSync(file) ? readFileSync(file, "utf8") : undefined;
+        if (source === undefined && options.create === undefined) {
+            throw new Error(`${options.file} does not exist; give a title with --new to create it`);
+        }
+        source ??= "";
+        if (options.create !== undefined &&
+            !parseSpec(source).some((t) => t.name === options.create)) {
+            source = addTest(source, options.create);
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, source);
+        }
+        const tests = parseSpec(source);
+        const testIndex = pickTest(tests, options.create ?? options.test);
+        const test = tests[testIndex];
+        const at = options.at ?? test.steps.length;
+        if (!Number.isInteger(at) || at < 0 || at > test.steps.length) {
+            throw new RangeError(`--at must be between 0 and ${test.steps.length} (the test has ${test.steps.length} steps)`);
+        }
+        const { browser, page } = await Browser.launch("firefox", { port: options.port ?? 9223, headless: false }, options.signal);
+        const events = [];
+        try {
+            const start = options.url ?? settings.baseURL;
+            if (options.url !== undefined)
+                await page.goto(options.url);
+            else if (settings.baseURL !== undefined)
+                await page.navigateTo(settings.baseURL);
+            const recorder = await page.record({
+                at,
+                initialGoto: at === 0 && start !== undefined,
+                ...(settings.baseURL !== undefined && { baseURL: settings.baseURL }),
+                onEvent: (event) => {
+                    source = applyRecorderEvent(source, testIndex, event);
+                    writeFileSync(file, source);
+                    events.push(event);
+                    options.onEvent?.(event, source);
+                },
+            });
+            await options.onStarted?.({ page, browser });
+            let windowClosed = false;
+            void browser.exited.then(() => (windowClosed = true));
+            await new Promise((resolve) => {
+                if (options.signal?.aborted)
+                    return resolve();
+                options.signal?.addEventListener("abort", () => resolve(), {
+                    once: true,
+                });
+                void browser.exited.then(resolve);
+            });
+            // With the window gone there is nothing to ask: what was reported before is in the file
+            if (!windowClosed)
+                await recorder.stop().catch(() => undefined);
+        }
+        finally {
+            await browser.close().catch(() => undefined);
+        }
+        const secrets = [
+            ...new Set(events.flatMap(({ step }) => step.kind === "fill" && step.value.kind === "secret"
+                ? [step.value.name]
+                : [])),
+        ];
+        return { file, test: test.name, events, secrets };
+    });
+}

package/dist/runner/module-type.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Specs must load as ES modules. A spec in a project whose package.json lacks `"type": "module"` is loaded as
+ * CommonJS, which gives it second copies of the framework's modules: `expect(locator)` then no longer
+ * recognises a locator, and its tests land in a registry the runner never reads. Fail early instead.
+ */
+export declare function assertModuleProject(specFile: string): void;

package/dist/runner/module-type.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Specs must load as ES modules. A spec in a project whose package.json lacks `"type": "module"` is loaded as
+ * CommonJS, which gives it second copies of the framework's modules: `expect(locator)` then no longer
+ * recognises a locator, and its tests land in a registry the runner never reads. Fail early instead.
+ */
+export function assertModuleProject(specFile) {
+    if (specFile.endsWith(".mts"))
+        return;
+    for (let dir = path.dirname(specFile);; dir = path.dirname(dir)) {
+        const manifest = path.join(dir, "package.json");
+        if (existsSync(manifest)) {
+            let type;
+            try {
+                type = JSON.parse(readFileSync(manifest, "utf8")).type;
+            }
+            catch {
+                throw new Error(`Cannot read ${manifest}`);
+            }
+            if (type === "module")
+                return;
+            throw new Error(`${manifest} must set "type": "module": specs are ES modules (needed to run ${path.basename(specFile)})`);
+        }
+        if (path.dirname(dir) === dir)
+            break;
+    }
+    throw new Error(`No package.json with "type": "module" found above ${specFile}: specs are ES modules`);
+}

package/dist/runner/page-logs-report.d.ts

@@ -0,0 +1,40 @@
+import type { LogRecord, PageError } from "../browser/page-logs.js";
+import type { SamuraiTestConfig } from "../types/config.js";
+import type { TestError } from "../types/test.js";
+/** Config `logs` */
+export type LogsConfig = NonNullable<SamuraiTestConfig["logs"]>;
+/** The page threw exceptions nobody caught, and config `logs.failOnPageError` says that fails the test */
+export declare class PageErrorsError extends Error {
+    readonly errors: readonly PageError[];
+    constructor(errors: readonly PageError[]);
+}
+/** A route handler threw: the test's mocks did not do what the test meant */
+export declare class RouteErrorsError extends Error {
+    readonly errors: readonly Error[];
+    constructor(errors: readonly Error[]);
+}
+export interface PageLogsInput {
+    config: LogsConfig | undefined;
+    entries: readonly LogRecord[];
+    errors: readonly PageError[];
+    /** How many entries the page's buffer dropped */
+    dropped: number;
+    /** The test body already failed (or timed out) */
+    testFailed: boolean;
+    /** The test called `page.allowPageErrors()` */
+    allowPageErrors: boolean;
+    /** Errors thrown by `page.route` handlers; they fail a passing test */
+    routeErrors?: readonly Error[];
+}
+export interface PageLogsVerdict {
+    /** Set when a test that passed has to fail because of page errors */
+    error?: TestError;
+    /** The entries to put in the report, per `logs.capture` */
+    logs?: LogRecord[];
+    logsDropped?: number;
+}
+/**
+ * Decides, once a test body is done, whether page errors fail it and which log entries go in the report:
+ * `capture` "failures" (default) attaches them to failed tests, "all" always, "off" never.
+ */
+export declare function judgePageLogs(input: PageLogsInput): PageLogsVerdict;

package/dist/runner/page-logs-report.js

@@ -0,0 +1,44 @@
+import { toTestError } from "./test-error.js";
+/** The page threw exceptions nobody caught, and config `logs.failOnPageError` says that fails the test */
+export class PageErrorsError extends Error {
+    constructor(errors) {
+        super(`${errors.length} uncaught page error(s): ${errors.map((error) => error.message).join("\n")}`);
+        this.name = "PageErrorsError";
+        this.errors = errors;
+    }
+}
+/** A route handler threw: the test's mocks did not do what the test meant */
+export class RouteErrorsError extends Error {
+    constructor(errors) {
+        super(`${errors.length} route handler error(s): ${errors.map((error) => error.message).join("\n")}`);
+        this.name = "RouteErrorsError";
+        this.errors = errors;
+    }
+}
+function isIgnored(error, ignore) {
+    return ignore.some((pattern) => typeof pattern === "string" ? error.message.includes(pattern) : pattern.test(error.message));
+}
+/**
+ * Decides, once a test body is done, whether page errors fail it and which log entries go in the report:
+ * `capture` "failures" (default) attaches them to failed tests, "all" always, "off" never.
+ */
+export function judgePageLogs(input) {
+    const { config, entries, errors, dropped, testFailed, allowPageErrors, routeErrors = [] } = input;
+    const capture = config?.capture ?? "failures";
+    let error;
+    if (routeErrors.length > 0 && !testFailed) {
+        error = toTestError(new RouteErrorsError(routeErrors));
+    }
+    else if (config?.failOnPageError && !testFailed && !allowPageErrors) {
+        const counted = errors.filter((pageError) => !isIgnored(pageError, config.ignoreErrors ?? []));
+        if (counted.length > 0)
+            error = toTestError(new PageErrorsError(counted));
+    }
+    const failed = testFailed || error !== undefined;
+    const attach = capture === "all" || (capture === "failures" && failed);
+    return {
+        ...(error && { error }),
+        ...(attach && { logs: [...entries] }),
+        ...(attach && dropped > 0 && { logsDropped: dropped }),
+    };
+}

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

@@ -0,0 +1,14 @@
+import { type RunOverrides, type RunSettings } from "../config/run-settings.js";
+import type { SamuraiTestConfig } from "../types/config.js";
+export interface PreparedRun {
+    settings: RunSettings;
+    secrets: ReadonlyMap<string, string>;
+}
+/**
+ * Starts a run: picks the environment, loads its secrets and registers every value for masking
+ * (all of them, not only the ones a test reads), then makes the settings active.
+ */
+export declare function prepareRun(config: SamuraiTestConfig, overrides: RunOverrides, options?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): PreparedRun;

package/dist/runner/prepare-run.js

@@ -0,0 +1,20 @@
+import { isShortSecret, registerSecret } from "../config/mask.js";
+import { resolveRunSettings, setRunSettings, } from "../config/run-settings.js";
+import { loadSecrets } from "../config/secrets.js";
+import logger from "../logger/index.js";
+/**
+ * Starts a run: picks the environment, loads its secrets and registers every value for masking
+ * (all of them, not only the ones a test reads), then makes the settings active.
+ */
+export function prepareRun(config, overrides, options = {}) {
+    const settings = resolveRunSettings(config, overrides);
+    const secrets = loadSecrets(settings.environment, options);
+    for (const [name, value] of secrets) {
+        registerSecret(name, value);
+        if (isShortSecret(value)) {
+            logger.warn(`Secret "${name}" is short; masking it may hide unrelated text in logs`);
+        }
+    }
+    setRunSettings(settings);
+    return { settings, secrets };
+}

package/dist/runner/project.d.ts

@@ -0,0 +1,17 @@
+import { type RunOverrides } from "../config/run-settings.js";
+import type { SamuraiTestConfig } from "../types/config.js";
+import { type PreparedRun } from "./prepare-run.js";
+/** Which project an operation works on, and in which environment */
+export interface ProjectOptions extends RunOverrides {
+    /** The project folder: `samurai.config.ts`, `.env.<environment>`, specs and `result/`. @default the working directory */
+    projectDir?: string;
+    /** Use this config instead of reading `samurai.config.ts` */
+    config?: SamuraiTestConfig;
+    /** Where the framework keeps browser profiles. @default `SAMURAI_DATA_DIR`, else `browsers/` in the project folder */
+    dataDir?: string;
+}
+/**
+ * Runs `work` with the project's config, folders, environment and secrets in place, and cleans up afterwards.
+ * One at a time per process: these are process-wide, so a second call throws.
+ */
+export declare function withProject<T>(options: ProjectOptions, work: (run: PreparedRun) => Promise<T>): Promise<T>;

package/dist/runner/project.js

@@ -0,0 +1,33 @@
+import { loadConfig, projectDir, setActiveProject } from "../config/config.js";
+import { resetSecrets } from "../config/mask.js";
+import { setRunSettings } from "../config/run-settings.js";
+import { prepareRun } from "./prepare-run.js";
+let active = false;
+/**
+ * Runs `work` with the project's config, folders, environment and secrets in place, and cleans up afterwards.
+ * One at a time per process: these are process-wide, so a second call throws.
+ */
+export async function withProject(options, work) {
+    if (active)
+        throw new Error("A test run is already active in this process");
+    active = true;
+    const { projectDir: dir, config, dataDir, environment, timeout, expectTimeout, } = options;
+    const previousDir = projectDir();
+    try {
+        setActiveProject({ dir: dir ?? previousDir, config, dataDir });
+        const loaded = config ?? (await loadConfig());
+        setActiveProject({ dir: dir ?? previousDir, config: loaded, dataDir });
+        resetSecrets();
+        const run = prepareRun(loaded, {
+            ...(environment !== undefined && { environment }),
+            ...(timeout !== undefined && { timeout }),
+            ...(expectTimeout !== undefined && { expectTimeout }),
+        });
+        return await work(run);
+    }
+    finally {
+        setRunSettings(undefined);
+        setActiveProject(undefined);
+        active = false;
+    }
+}

package/dist/runner/registry.d.ts

@@ -0,0 +1,7 @@
+import type { RegisteredTestCase, TestCaseBase } from "../types/test.js";
+/** Groups the tests registered inside `fn` under `title`. `fn` runs immediately and must be synchronous. */
+export declare function describe(title: string, fn: () => void): void;
+export declare function test(title: string, fn: TestCaseBase["function"]): void;
+export declare function registeredTests(): readonly RegisteredTestCase[];
+/** Forgets every registered test (tests only) */
+export declare function clearRegistry(): void;

package/dist/runner/registry.js

@@ -0,0 +1,40 @@
+import { fileURLToPath } from "node:url";
+import logger from "../logger/index.js";
+const registered = [];
+/** Titles of the describe blocks being registered, outermost first */
+const titleStack = [];
+/** Groups the tests registered inside `fn` under `title`. `fn` runs immediately and must be synchronous. */
+export function describe(title, fn) {
+    titleStack.push(title);
+    try {
+        const result = fn();
+        if (result instanceof Promise) {
+            result.catch(() => { });
+            throw new Error("describe() callback must be synchronous; it only registers tests");
+        }
+    }
+    finally {
+        titleStack.pop();
+    }
+}
+export function test(title, fn) {
+    const titlePath = [...titleStack, title];
+    const name = titlePath.join(" > ");
+    registered.push({ name, titlePath, function: fn, file: callerFile() });
+    logger.debug("Registered test %s", name);
+}
+export function registeredTests() {
+    return registered;
+}
+/** Forgets every registered test (tests only) */
+export function clearRegistry() {
+    registered.length = 0;
+    titleStack.length = 0;
+}
+/** File of the code that called test(): stack lines are Error, callerFile, test, caller */
+function callerFile() {
+    const caller = new Error().stack?.split("\n")[3] ?? "";
+    const match = caller.match(/\((.+?):\d+:\d+\)$/) ?? caller.match(/at (.+?):\d+:\d+$/);
+    const location = match?.[1] ?? "";
+    return location.startsWith("file://") ? fileURLToPath(location) : location;
+}

package/dist/runner/reporter.d.ts

@@ -0,0 +1,43 @@
+import type { RegisteredTestCase, TestError, TestLogEntry, TestResult, TestSummary } from "../types/test.js";
+/** What a run reports while it happens */
+export type RunEvent = {
+    type: "run-start";
+    environment: string;
+    total: number;
+} | {
+    type: "test-start";
+    name: string;
+    file: string;
+} | {
+    type: "test-end";
+    name: string;
+    file: string;
+    result: TestResult;
+} | {
+    type: "run-end";
+    summary: TestSummary;
+};
+export interface ReporterOptions {
+    /** The environment the run uses, recorded in the report */
+    environment: string;
+    /** Where the report is written. @default <cwd>/result/report.json */
+    output?: string | false;
+    /** Called with every event, in order. A throwing listener is ignored */
+    onEvent?: (event: RunEvent) => void;
+}
+export default class TestReporter {
+    private testResults;
+    private summary;
+    private environment;
+    private output;
+    private listener;
+    constructor(options: ReporterOptions);
+    private emit;
+    onStart(total?: number): void;
+    onEnd(): Promise<TestSummary>;
+    onTestStart(test: RegisteredTestCase): void;
+    onTestEnd(test: RegisteredTestCase, error?: TestError, logs?: {
+        logs?: TestLogEntry[];
+        logsDropped?: number;
+    }): void;
+}

package/dist/runner/reporter.js

@@ -0,0 +1,83 @@
+import { mkdir, writeFile } from "fs/promises";
+import path from "path";
+import { projectDir } from "../config/config.js";
+import { maskDeep } from "../config/mask.js";
+/** Results are keyed by file and full title, so equal titles in different files or describe blocks stay apart */
+function keyOf(test) {
+    return `${test.file}::${test.name}`;
+}
+export default class TestReporter {
+    constructor(options) {
+        this.testResults = new Map();
+        this.environment = options.environment;
+        this.output =
+            options.output ?? path.join(projectDir(), "result/report.json");
+        this.listener = options.onEvent;
+    }
+    emit(event) {
+        try {
+            this.listener?.(event);
+        }
+        catch {
+            // A listener must not break the run
+        }
+    }
+    onStart(total = 0) {
+        const t = performance.mark(`group-start`);
+        this.summary = {
+            duration: 0,
+            status: "failed",
+            startTime: t.startTime,
+            environment: this.environment,
+            tests: [],
+        };
+        this.emit({ type: "run-start", environment: this.environment, total });
+    }
+    async onEnd() {
+        performance.mark(`group-finish`);
+        const duration = performance.measure("test-duration", `group-start`, `group-finish`).duration;
+        this.summary = {
+            ...this.summary,
+            duration,
+            environment: this.environment,
+            tests: Array.from(this.testResults.values()),
+            status: Array.from(this.testResults.values()).every((r) => r.status === "success")
+                ? "success"
+                : "failed",
+        };
+        if (this.output !== false) {
+            await mkdir(path.dirname(this.output), { recursive: true });
+            await writeFile(this.output, JSON.stringify(this.summary, null, 2), {
+                encoding: "utf8",
+            });
+        }
+        this.emit({ type: "run-end", summary: this.summary });
+        return this.summary;
+    }
+    onTestStart(test) {
+        const key = keyOf(test);
+        const t = performance.mark(`${key}-start`);
+        this.testResults.set(key, {
+            name: test.name,
+            file: test.file,
+            status: "started",
+            startTime: t.startTime,
+        });
+        this.emit({ type: "test-start", name: test.name, file: test.file });
+    }
+    onTestEnd(test, error, logs) {
+        const key = keyOf(test);
+        performance.mark(`${key}-finish`);
+        const duration = performance.measure("test-duration", `${key}-start`, `${key}-finish`).duration;
+        const result = maskDeep({
+            ...this.testResults.get(key),
+            duration,
+            status: error ? "failed" : "success",
+            ...(error ? error : undefined),
+            ...(logs?.logs && { logs: logs.logs }),
+            ...(logs?.logsDropped && { logsDropped: logs.logsDropped }),
+        });
+        this.testResults.set(key, result);
+        this.emit({ type: "test-end", name: test.name, file: test.file, result });
+    }
+}

package/dist/runner/run.d.ts

@@ -0,0 +1,27 @@
+import type { TestSummary } from "../types/test.js";
+import { type ProjectOptions } from "./project.js";
+import { type RunnerOptions } from "./test-runner.js";
+export interface RunTestsOptions extends RunnerOptions, ProjectOptions {
+}
+/**
+ * Runs the project's tests, one after the other, and resolves with the summary (also written to the report).
+ * Spec files are TypeScript: the process must be able to import them (run under `tsx`, or with Node's own
+ * type stripping). One run at a time per process: config, secrets and the test registry are shared state;
+ * use a child process per run for more.
+ * @example
+ *  const summary = await runTests({ projectDir: "/work/shop", environment: "staging", headless: true,
+ *    onEvent: (event) => console.log(event.type) });
+ */
+export declare function runTests(options?: RunTestsOptions): Promise<TestSummary>;
+/** A test found in a spec file */
+export interface FoundTest {
+    /** Full name: `describe` titles and the test title joined with " > " */
+    name: string;
+    file: string;
+}
+/** Imports the project's specs without running anything and lists the tests the options select */
+export declare function listTests(options?: RunTestsOptions): Promise<FoundTest[]>;
+export type { RunEvent } from "./reporter.js";
+export type { TestError, TestResult, TestSummary } from "../types/test.js";
+export type { RunnerOptions } from "./test-runner.js";
+export type { ProjectOptions } from "./project.js";

package/dist/runner/run.js

@@ -0,0 +1,34 @@
+import { withProject } from "./project.js";
+import TestRunner, {} from "./test-runner.js";
+/**
+ * Runs the project's tests, one after the other, and resolves with the summary (also written to the report).
+ * Spec files are TypeScript: the process must be able to import them (run under `tsx`, or with Node's own
+ * type stripping). One run at a time per process: config, secrets and the test registry are shared state;
+ * use a child process per run for more.
+ * @example
+ *  const summary = await runTests({ projectDir: "/work/shop", environment: "staging", headless: true,
+ *    onEvent: (event) => console.log(event.type) });
+ */
+export async function runTests(options = {}) {
+    const { projectDir, config, dataDir, environment, timeout, expectTimeout, ...runner } = options;
+    return withProject({
+        projectDir,
+        config,
+        dataDir,
+        environment,
+        timeout,
+        expectTimeout,
+    }, async (run) => (await TestRunner.init(run, undefined, runner)).start());
+}
+/** Imports the project's specs without running anything and lists the tests the options select */
+export async function listTests(options = {}) {
+    const { projectDir, config, dataDir, environment, timeout, expectTimeout, ...runner } = options;
+    return withProject({
+        projectDir,
+        config,
+        dataDir,
+        environment,
+        timeout,
+        expectTimeout,
+    }, async (run) => (await (await TestRunner.init(run, undefined, runner)).register()).map(({ name, file }) => ({ name, file })));
+}

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

@@ -0,0 +1,3 @@
+import type { TestError } from "../types/test.js";
+/** Maps anything a test threw to the error stored in the report */
+export declare function toTestError(err: unknown): TestError;

package/dist/runner/test-error.js

@@ -0,0 +1,18 @@
+import { AssertionError, toReportValue } from "../assert/assertion-error.js";
+/** Maps anything a test threw to the error stored in the report */
+export function toTestError(err) {
+    if (err instanceof AssertionError) {
+        return {
+            message: err.message,
+            stack: err.stack,
+            type: "assertion",
+            expected: toReportValue(err.expected),
+            actual: toReportValue(err.actual),
+        };
+    }
+    return {
+        message: err instanceof Error ? err.message : String(err),
+        stack: err instanceof Error ? err.stack : undefined,
+        type: "error",
+    };
+}

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

@@ -0,0 +1,44 @@
+import type { RegisteredTestCase } from "../types/test.js";
+import type { PreparedRun } from "./prepare-run.js";
+import { type RunEvent } from "./reporter.js";
+import type { SamuraiGroup } from "../types/config.js";
+/** What decides which tests of the found files run, and how the browser starts */
+export interface RunnerOptions {
+    /** Spec files to run, absolute or relative to the project folder. Default: every `*.spec.ts` under `srcDir` */
+    files?: string[];
+    /** Only tests whose full name matches (a string must be contained in it) */
+    grep?: string | RegExp;
+    /** Only tests with exactly one of these full names (`describe` titles joined with " > ") */
+    testNames?: string[];
+    /** Run the browser without a window. @default false */
+    headless?: boolean;
+    /** Remote debugging port of the browser. @default 9223 */
+    port?: number;
+    /** Where the report is written; `false` writes none. @default `<project>/result/report.json` */
+    reportPath?: string | false;
+    /** Receives start and end of the run and of every test, as they happen */
+    onEvent?: (event: RunEvent) => void;
+    /** Aborting stops the running test (its browser is closed), skips the rest and reports the run as failed */
+    signal?: AbortSignal;
+}
+/** Whether a test with this full name is selected by the options */
+export declare function isSelected(name: string, { grep, testNames }: Pick<RunnerOptions, "grep" | "testNames">): boolean;
+export default class TestRunner {
+    private testFiles;
+    private run;
+    private group?;
+    private options;
+    constructor(testFiles: string[], run: PreparedRun, group?: SamuraiGroup, options?: RunnerOptions);
+    static init(run: PreparedRun, group?: SamuraiGroup, options?: RunnerOptions): Promise<TestRunner>;
+    /** Runs the selected tests and returns the summary that was also written to the report */
+    /**
+     * Imports the spec files and returns the tests the options select. A fresh registry and a fresh import of each
+     * file, so a second run in this process registers its tests again (and sees edited specs, for files loaded as
+     * ES modules; CommonJS files stay cached until the process ends)
+     */
+    register(): Promise<RegisteredTestCase[]>;
+    /** Runs the selected tests and returns the summary that was also written to the report */
+    start(): Promise<import("../types/test.js").TestSummary>;
+    private executeTestCase;
+}
+export { describe, test } from "./registry.js";