@itmetsam/samurai-framework 0.2.2 → 0.3.0

package/dist/flows/run/report.js

@@ -0,0 +1,46 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { maskDeep, maskText } from "../../config/mask.js";
+/** Follows a run's events and builds its report once it ends (or `finish` is given what is known) */
+export class FlowReportBuilder {
+    constructor(flow) {
+        this.flow = flow;
+        this.environment = "";
+        this.tests = [];
+        this.started = Date.now();
+        this.startedAt = new Date(this.started).toISOString();
+    }
+    handle(event) {
+        if (event.type === "flow-start")
+            this.environment = event.environment;
+        if (event.type === "test")
+            this.collect(event.nodeId, event.event);
+    }
+    collect(nodeId, event) {
+        if (event.type === "test-end")
+            this.tests.push({ nodeId, ...event.result });
+    }
+    finish(summary, environment = this.environment) {
+        return {
+            flow: this.flow.id,
+            name: this.flow.name,
+            environment,
+            status: summary.status,
+            startedAt: this.startedAt,
+            durationMs: Date.now() - this.started,
+            nodes: summary.nodes,
+            vars: summary.vars,
+            tests: this.tests,
+            ...(summary.error ? { error: summary.error } : {}),
+        };
+    }
+}
+/** Writes `<projectDir>/result/flows/<id>.json` with the registered secrets masked, as `report.json` is. Returns the path */
+export async function writeFlowReport(projectDir, report) {
+    const file = path.join(path.resolve(projectDir), "result", "flows", `${report.flow}.json`);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(maskDeep(report), null, 2), "utf8");
+    return file;
+}
+/** Hides the registered secrets in a line of output (a node's error) */
+export const maskSecrets = (text) => maskText(text);

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

@@ -0,0 +1,42 @@
+import { type AnyNodeDefinition, type FlowFile } from "../core/index.js";
+import type { RunEvent } from "../../runner/reporter.js";
+import type { FlowEvent, FlowSummary, NodeTest } from "./events.js";
+import { type Handler } from "./handlers/index.js";
+export interface RunFlowOptions {
+    flow: FlowFile;
+    /** The tests of each Test and Group node, by node id */
+    nodeTests: Record<string, NodeTest[]>;
+    environment: {
+        name: string;
+        variables: Record<string, string | number | boolean>;
+    };
+    /** @default "manual" */
+    trigger?: "manual";
+    /** @default now */
+    startedAt?: string;
+    signal?: AbortSignal;
+    onEvent?: (event: FlowEvent) => void;
+    runTests: (input: {
+        tests: NodeTest[];
+        onEvent: (e: RunEvent) => void;
+        signal: AbortSignal;
+    }) => Promise<"passed" | "failed" | "cancelled">;
+    sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+    /**
+     * What a node of a kind with no handler does:
+     *  - `"fail"` (default): the run does not start (an error is thrown)
+     *  - `"skip"`: the node is skipped with the note "Not supported yet"
+     */
+    unsupported?: "fail" | "skip";
+    /** The handlers by kind. @default HANDLERS */
+    handlers?: Readonly<Record<string, Handler>>;
+    /** Definitions of kinds beyond the ones `flows/core` registers (a handler needs one to be walked) */
+    nodes?: readonly AnyNodeDefinition[];
+}
+/**
+ * Walks the flow from Start by the shape of each node's kind: a step runs and
+ * follows its one way out; a node with a fixed list of branches follows the one its
+ * handler names and skips the others; a node with a dynamic list walks every branch in
+ * fill order; an end stops. Branches meet again at `meetOf`.
+ */
+export declare function runFlow(options: RunFlowOptions): Promise<FlowSummary>;

package/dist/flows/run/run.js

@@ -0,0 +1,244 @@
+import { inFillOrder, meetOf, nodeDef, } from "../core/index.js";
+import { HANDLERS } from "./handlers/index.js";
+const defaultSleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(new Error("aborted"));
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+class ShapeError extends Error {
+}
+const dynamicBranches = (def) => def.shape === "branches" && !!def.branches && !Array.isArray(def.branches);
+/**
+ * Walks the flow from Start by the shape of each node's kind: a step runs and
+ * follows its one way out; a node with a fixed list of branches follows the one its
+ * handler names and skips the others; a node with a dynamic list walks every branch in
+ * fill order; an end stops. Branches meet again at `meetOf`.
+ */
+export async function runFlow(options) {
+    const { flow, onEvent = () => { } } = options;
+    const signal = options.signal ?? new AbortController().signal;
+    const handlers = options.handlers ?? HANDLERS;
+    const defOf = (kind) => options.nodes?.find((d) => d.kind === kind) ??
+        (() => {
+            try {
+                return nodeDef(kind);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+    if ((options.unsupported ?? "fail") === "fail") {
+        const problems = flow.nodes
+            .map((n) => ({ n, def: defOf(n.kind) }))
+            .filter(({ n, def }) => def &&
+            (def.shape === "step" || def.shape === "branches") &&
+            !handlers[n.kind])
+            .map(({ def }) => `${def.label} can't run yet.`);
+        if (problems.length)
+            throw new Error(`This flow can't run: ${[...new Set(problems)].join(" ")}`);
+    }
+    const byId = new Map(flow.nodes.map((n) => [n.id, n]));
+    const results = {};
+    const context = {
+        env: { ...options.environment.variables },
+        vars: {},
+        nodes: {},
+        run: {
+            environment: options.environment.name,
+            trigger: options.trigger ?? "manual",
+            startedAt: options.startedAt ?? new Date().toISOString(),
+        },
+    };
+    const handlerRun = {
+        flow,
+        environment: options.environment,
+        context,
+        nodeTests: options.nodeTests,
+        signal,
+        sleep: options.sleep ?? defaultSleep,
+        runTests: (tests, onTestEvent) => options.runTests({ tests, onEvent: onTestEvent, signal }),
+        onTestEvent: (nodeId, event) => onEvent({ type: "test", nodeId, event }),
+    };
+    let stopped;
+    const visited = new Set();
+    const record = (node, result) => {
+        results[node.id] = result;
+        if (node.key)
+            context.nodes[node.key] = {
+                status: result.status,
+                durationMs: result.durationMs,
+                error: result.error,
+            };
+    };
+    const out = (id) => flow.edges.filter((e) => e.source === id);
+    /** Marks every node from `from` up to `stop` as skipped (a branch not taken) */
+    const skip = (from, stop) => {
+        const seen = new Set();
+        const visit = (id) => {
+            if (id === stop || seen.has(id))
+                return;
+            seen.add(id);
+            const node = byId.get(id);
+            if (node && !results[id]) {
+                record(node, { status: "skipped" });
+                onEvent({
+                    type: "node-end",
+                    nodeId: id,
+                    result: { status: "skipped" },
+                });
+            }
+            for (const e of out(id))
+                visit(e.target);
+        };
+        visit(from);
+    };
+    const shapeError = (message) => new ShapeError(`This flow's shape can't run: ${message}`);
+    async function runNode(node, def) {
+        if (visited.has(node.id))
+            throw shapeError(`${node.key ?? node.id} is reached twice.`);
+        visited.add(node.id);
+        if (signal.aborted) {
+            stopped = "cancelled";
+            return undefined;
+        }
+        onEvent({ type: "node-start", nodeId: node.id });
+        const began = Date.now();
+        const handler = handlers[node.kind];
+        const outcome = handler
+            ? await handler(node, handlerRun)
+            : { status: "skipped", note: "Not supported yet" };
+        if (outcome === "cancelled" || signal.aborted) {
+            stopped = "cancelled";
+            return undefined;
+        }
+        const result = { ...outcome, durationMs: Date.now() - began };
+        record(node, result);
+        // A node with a dynamic list of branches ends after them: walk() reports it then
+        if (dynamicBranches(def))
+            return result;
+        onEvent({ type: "node-end", nodeId: node.id, result });
+        if (result.status === "failed" && node.onFailure === "stop")
+            stopped = "failed";
+        return result;
+    }
+    /** Whether `target` is on the chain from `from` before `stop` */
+    const reachesBefore = (from, target, stop) => {
+        const seen = new Set();
+        const visit = (id) => {
+            if (id === stop || seen.has(id))
+                return false;
+            if (id === target)
+                return true;
+            seen.add(id);
+            return out(id).some((e) => visit(e.target));
+        };
+        return visit(from);
+    };
+    /** Runs the chain from `from` up to `stop` (undefined: through End) */
+    async function walk(from, stop) {
+        let at = from;
+        while (at !== undefined && at !== stop && !stopped) {
+            const node = byId.get(at);
+            if (!node)
+                throw shapeError("an edge leads to a missing node.");
+            const def = defOf(node.kind);
+            if (!def)
+                throw shapeError(`${node.key ?? node.id} has an unknown kind (${node.kind}).`);
+            const result = await runNode(node, def);
+            if (!result || stopped)
+                return;
+            if (def.shape === "end")
+                return;
+            const edges = out(node.id);
+            if (def.shape === "branches") {
+                const meet = meetOf(flow, node.id);
+                if (!meet)
+                    throw shapeError(`the branches of ${node.key ?? node.id} never meet.`);
+                if (!dynamicBranches(def)) {
+                    const taken = result.status === "passed"
+                        ? edges.find((e) => e.sourceHandle === result.branch)
+                        : undefined;
+                    for (const e of edges)
+                        if (e !== taken)
+                            skip(e.target, meet);
+                    if (taken)
+                        await walk(taken.target, meet);
+                }
+                else {
+                    const opened = Date.now();
+                    for (const e of inFillOrder(edges)) {
+                        if (stopped)
+                            break;
+                        if (e.target !== meet)
+                            await walk(e.target, meet);
+                    }
+                    if (stopped === "cancelled") {
+                        // Stopped inside its branches: like any node cut short, it didn't run to the end
+                        delete results[node.id];
+                        return;
+                    }
+                    // The node fails when anything in its branches failed
+                    const failed = flow.nodes.some((n) => results[n.id]?.status === "failed" &&
+                        edges.some((e) => e.target !== meet && reachesBefore(e.target, n.id, meet)));
+                    const durationMs = (result.durationMs ?? 0) + Date.now() - opened;
+                    const ended = failed
+                        ? {
+                            ...result,
+                            durationMs,
+                            status: "failed",
+                            error: "A branch failed.",
+                        }
+                        : { ...result, durationMs };
+                    record(node, ended);
+                    onEvent({ type: "node-end", nodeId: node.id, result: ended });
+                    if (failed && node.onFailure === "stop")
+                        stopped = "failed";
+                    if (stopped)
+                        return;
+                }
+                at = meet;
+                continue;
+            }
+            if (edges.length !== 1)
+                throw shapeError(`${node.key ?? node.id} has ${edges.length} ways out.`);
+            at = edges[0].target;
+        }
+    }
+    onEvent({ type: "flow-start", environment: options.environment.name });
+    let error;
+    const start = flow.nodes.find((n) => defOf(n.kind)?.shape === "start");
+    try {
+        if (!start)
+            throw shapeError("it has no Start.");
+        await walk(start.id);
+    }
+    catch (e) {
+        if (!(e instanceof ShapeError))
+            throw e;
+        error = e.message;
+    }
+    for (const node of flow.nodes)
+        if (!results[node.id])
+            results[node.id] = { status: "not-run" };
+    const status = stopped === "cancelled"
+        ? "cancelled"
+        : error || Object.values(results).some((r) => r.status === "failed")
+            ? "failed"
+            : "passed";
+    const summary = {
+        status,
+        nodes: results,
+        vars: context.vars,
+        ...(error ? { error } : {}),
+    };
+    onEvent({ type: "flow-end", summary });
+    return summary;
+}

package/dist/locator/locator.d.ts

@@ -163,6 +163,14 @@ export default class Locator {
     isEditable(): Promise<boolean>;
     /** Wait for certain time (ms). Default: 300ms  */
     wait(duration?: number): Promise<void>;
+    /**
+     * Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input.
+     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Home`, `End`, `PageUp`, `PageDown` and the arrows;
+     * any other key must be a single character.
+     * @example
+     *  await page.getByLabel("New todo").press("Enter");
+     */
+    press(key: string, options?: ActionOptions): Promise<void>;
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     fill(value: string, options?: ActionOptions): Promise<void>;
 }

package/dist/locator/locator.js

@@ -42,7 +42,25 @@ const FILL_CHECKS = [
     "editable",
     "hit target",
 ];
+const PRESS_CHECKS = ["attached", "visible", "enabled"];
 const ATTACHED_ONLY = ["attached"];
+/** WebDriver code points of the named keys `press()` accepts; any other single character is typed as is */
+const NAMED_KEYS = {
+    Backspace: "\uE003",
+    Tab: "\uE004",
+    Enter: "\uE007",
+    Escape: "\uE00C",
+    Space: " ",
+    ArrowLeft: "\uE012",
+    ArrowUp: "\uE013",
+    ArrowRight: "\uE014",
+    ArrowDown: "\uE015",
+    Delete: "\uE017",
+    Home: "\uE011",
+    End: "\uE010",
+    PageUp: "\uE00E",
+    PageDown: "\uE00F",
+};
 /** Unicode code point WebDriver uses for the Backspace key */
 const BACKSPACE = "";
 export default class Locator {
@@ -556,6 +574,34 @@ export default class Locator {
             ],
         });
     }
+    /**
+     * Waits until the element is attached, visible and enabled, focuses it and presses `key` with real keyboard input.
+     * Named keys are `Enter`, `Escape`, `Tab`, `Backspace`, `Delete`, `Space`, `Home`, `End`, `PageUp`, `PageDown` and the arrows;
+     * any other key must be a single character.
+     * @example
+     *  await page.getByLabel("New todo").press("Enter");
+     */
+    async press(key, options) {
+        const code = NAMED_KEYS[key] ?? (Array.from(key).length === 1 ? key : "");
+        if (code === "") {
+            throw new Error(`press(): unknown key "${key}". Use one of ${Object.keys(NAMED_KEYS).join(", ")} or a single character`);
+        }
+        await this.waitForActionable("press", PRESS_CHECKS, { scroll: true, hitTest: false }, options);
+        await this.callOnElement(undefined, `el.focus();`);
+        await this.biDiConnector.send("input.performActions", {
+            context: this.contextId,
+            actions: [
+                {
+                    type: "key",
+                    id: "samurai-keyboard",
+                    actions: [
+                        { type: "keyDown", value: code },
+                        { type: "keyUp", value: code },
+                    ],
+                },
+            ],
+        });
+    }
     /** Waits until the field is editable and not covered, then replaces its value by typing `value`; an empty string clears it */
     async fill(value, options) {
         const state = await this.waitForActionable("fill", FILL_CHECKS, { scroll: true, hitTest: true }, options);

package/dist/recorder/capture.d.ts

@@ -6,6 +6,8 @@
  *   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
+ *   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.
  *

package/dist/recorder/capture.js

@@ -8,6 +8,8 @@ const OFF_KEY = "samurai.recorder.off";
  *   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
+ *   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.
  *
@@ -184,6 +186,18 @@ export const CAPTURE_SOURCE = String.raw `(send) => {
     });
   }, true);
 
+  // Enter, Tab and Escape change what the page does next (an Enter adds a todo and clears the field), so they are steps
+  const RECORDED_KEYS = ["Enter", "Tab", "Escape"];
+  // Enter on these is a click, which is recorded as one
+  const ACTIVATES = "a[href],button,summary,select,input[type=button],input[type=submit],input[type=reset],input[type=checkbox],input[type=radio]";
+  document.addEventListener("keydown", (event) => {
+    if (off() || !event.isTrusted || event.isComposing || event.ctrlKey || event.altKey || event.metaKey || event.shiftKey) return;
+    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 });
+  }, true);
+
   document.addEventListener("mousemove", (event) => {
     if (off() || !event.altKey || !(event.target instanceof Element) || event.target === outlined) return;
     unhighlight();

package/dist/recorder/normalise.d.ts

@@ -22,6 +22,11 @@ export type Observation = {
     value?: string;
     secret?: boolean;
     secretName?: string;
+} | {
+    type: "press";
+    key: string;
+    locator: LocatorSpec;
+    pressed: string;
 } | {
     type: "assert";
     key: string;

package/dist/recorder/normalise.js

@@ -60,6 +60,18 @@ export class Normaliser {
             this.lastAction = at;
             return [this.insert({ kind: "click", locator: observation.locator })];
         }
+        if (observation.type === "press") {
+            // The page may react by clearing the field: what is typed next is a new fill, not a rewrite of this one
+            this.lastFill = undefined;
+            this.lastAction = at;
+            return [
+                this.insert({
+                    kind: "press",
+                    locator: observation.locator,
+                    key: observation.pressed,
+                }),
+            ];
+        }
         if (observation.type === "assert") {
             this.lastFill = undefined;
             return [

package/dist/recorder/recorder.js

@@ -99,24 +99,26 @@ export class Recorder {
         const key = message.target.sharedId;
         const observation = message.type === "click"
             ? { type: "click", key, locator, textEntry: message.textEntry === true }
-            : message.type === "assert"
-                ? {
-                    type: "assert",
-                    key,
-                    locator,
-                    text: message.text ?? "",
-                    ...(message.value !== undefined && { value: message.value }),
-                }
-                : {
-                    type: "input",
-                    key,
-                    locator,
-                    ...(message.value !== undefined && { value: message.value }),
-                    ...(message.secret && { secret: true }),
-                    ...(message.secretName !== undefined && {
-                        secretName: message.secretName,
-                    }),
-                };
+            : message.type === "press"
+                ? { type: "press", key, locator, pressed: message.pressed ?? "" }
+                : message.type === "assert"
+                    ? {
+                        type: "assert",
+                        key,
+                        locator,
+                        text: message.text ?? "",
+                        ...(message.value !== undefined && { value: message.value }),
+                    }
+                    : {
+                        type: "input",
+                        key,
+                        locator,
+                        ...(message.value !== undefined && { value: message.value }),
+                        ...(message.secret && { secret: true }),
+                        ...(message.secretName !== undefined && {
+                            secretName: message.secretName,
+                        }),
+                    };
         this.emit(this.normaliser.observe(observation, Date.now()));
     }
     async release() {

package/dist/runner/groups.d.ts

@@ -0,0 +1,39 @@
+import type { SamuraiGroup } from "../types/config.js";
+/** The test folder when the config names none */
+export declare const DEFAULT_SRC_DIR = "./src";
+/** The spec pattern when a group names none */
+export declare const DEFAULT_TEST_MATCH = "**/*.spec.ts";
+/** A test as groups see it: its spec file (relative to `srcDir`, or any path inside it) and full name */
+export interface GroupTest {
+    file: string;
+    name: string;
+}
+/** A group with the tests it holds */
+export interface ResolvedGroup {
+    name: string;
+    /** `picked`: the group lists its tests; `pattern`: `src` and `testMatch` select them */
+    kind: "picked" | "pattern";
+    /** What selects the tests of a pattern group, for display */
+    pattern?: string;
+    /** Ids (see `testId`) of the found tests in the group */
+    testIds: string[];
+    /** Picked tests that no longer exist */
+    missing: {
+        file: string;
+        title: string;
+    }[];
+}
+/** Separators of any platform become `/` */
+export declare const toPosix: (p: string) => string;
+/** The id of a test: its spec file relative to `srcDir` with `/` separators, then `::` and its full name */
+export declare const testId: (file: string, name: string) => string;
+/** Works out which of `tests` (files relative to `srcDir`) belong to the group */
+export declare function resolveGroup(group: SamuraiGroup, tests: GroupTest[], projectDir: string, srcDir: string): ResolvedGroup;
+/** Resolves every group of the config */
+export declare function resolveGroups(config: {
+    groups?: SamuraiGroup[];
+}, tests: GroupTest[], projectDir: string, srcDir: string): ResolvedGroup[];
+/** The group called `name`, or an error naming the groups there are */
+export declare function findGroup<T extends {
+    name: string;
+}>(groups: T[], name: string): T;

package/dist/runner/groups.js

@@ -0,0 +1,58 @@
+import { matchesGlob, relative, resolve } from "node:path";
+/** The test folder when the config names none */
+export const DEFAULT_SRC_DIR = "./src";
+/** The spec pattern when a group names none */
+export const DEFAULT_TEST_MATCH = "**/*.spec.ts";
+/** Separators of any platform become `/` */
+export const toPosix = (p) => p.replace(/\\/g, "/");
+/** The id of a test: its spec file relative to `srcDir` with `/` separators, then `::` and its full name */
+export const testId = (file, name) => `${toPosix(file)}::${name}`;
+/** Works out which of `tests` (files relative to `srcDir`) belong to the group */
+export function resolveGroup(group, tests, projectDir, srcDir) {
+    const found = tests.map((t) => ({ ...t, id: testId(t.file, t.name) }));
+    // Tests picked by hand override src and testMatch
+    if (group.tests) {
+        const known = new Set(found.map((t) => t.id));
+        const picked = group.tests.map(({ file, title }) => ({
+            file,
+            title,
+            id: testId(file, title),
+        }));
+        return {
+            name: group.name,
+            kind: "picked",
+            testIds: picked.filter((t) => known.has(t.id)).map((t) => t.id),
+            missing: picked
+                .filter((t) => !known.has(t.id))
+                .map(({ file, title }) => ({ file, title })),
+        };
+    }
+    const base = group.src ? resolve(projectDir, group.src) : srcDir;
+    const pattern = group.testMatch ?? DEFAULT_TEST_MATCH;
+    const testIds = found
+        .filter((t) => {
+        const fromBase = toPosix(relative(base, resolve(srcDir, t.file)));
+        return !fromBase.startsWith("..") && matchesGlob(fromBase, pattern);
+    })
+        .map((t) => t.id);
+    return {
+        name: group.name,
+        kind: "pattern",
+        pattern: [group.src, group.testMatch].filter(Boolean).join(" · ") || pattern,
+        testIds,
+        missing: [],
+    };
+}
+/** Resolves every group of the config */
+export function resolveGroups(config, tests, projectDir, srcDir) {
+    return (config.groups ?? []).map((group) => resolveGroup(group, tests, projectDir, srcDir));
+}
+/** The group called `name`, or an error naming the groups there are */
+export function findGroup(groups, name) {
+    const group = groups.find((g) => g.name === name);
+    if (group)
+        return group;
+    throw new Error(groups.length === 0
+        ? `Unknown group "${name}". No groups are configured.`
+        : `Unknown group "${name}". Groups: ${groups.map((g) => g.name).join(", ")}.`);
+}

package/dist/runner/run.d.ts

@@ -1,5 +1,6 @@
 import type { TestSummary } from "../types/test.js";
 import { type ProjectOptions } from "./project.js";
+import type { ResolvedGroup } from "./groups.js";
 import { type RunnerOptions } from "./test-runner.js";
 export interface RunTestsOptions extends RunnerOptions, ProjectOptions {
 }
@@ -21,7 +22,10 @@ export interface FoundTest {
 }
 /** Imports the project's specs without running anything and lists the tests the options select */
 export declare function listTests(options?: RunTestsOptions): Promise<FoundTest[]>;
+/** Imports the project's specs without running anything and lists the config's groups with the tests each holds */
+export declare function listGroups(options?: RunTestsOptions): Promise<ResolvedGroup[]>;
 export type { RunEvent } from "./reporter.js";
 export type { TestError, TestResult, TestSummary } from "../types/test.js";
+export type { ResolvedGroup } from "./groups.js";
 export type { RunnerOptions } from "./test-runner.js";
 export type { ProjectOptions } from "./project.js";

package/dist/runner/run.js

@@ -32,3 +32,15 @@ export async function listTests(options = {}) {
         expectTimeout,
     }, async (run) => (await (await TestRunner.init(run, undefined, runner)).register()).map(({ name, file }) => ({ name, file })));
 }
+/** Imports the project's specs without running anything and lists the config's groups with the tests each holds */
+export async function listGroups(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)).groups());
+}