@itmetsam/samurai-framework 0.15.1 → 0.16.0

package/dist/network/router.js

@@ -1,11 +1,10 @@
+import { DEFAULT_ROUTE_TIMEOUT } from "../config/defaults.js";
 import logger from "../logger/index.js";
 import { toRequest } from "./bidi-wire.js";
 import { Intercept } from "./intercept.js";
 import { PendingRoute, } from "./route.js";
 import { matchUrl, samePattern } from "./url-match.js";
 export { Route } from "./route.js";
-/** Time (ms) a handler may take to answer a request before the router lets it continue */
-const DEFAULT_ROUTE_TIMEOUT = 30000;
 /** How many handler errors the router keeps */
 const MAX_ERRORS = 100;
 /**

package/dist/project/files-store.js

@@ -2,6 +2,7 @@ import { constants, createReadStream } from "node:fs";
 import { copyFile, mkdir, readFile, stat } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import path from "node:path";
+import { DEFAULT_FILES_DIR } from "../config/defaults.js";
 /** Files bigger than this aren't stored while recording */
 export const RECORD_LIMIT = 50 * 1024 * 1024;
 const NAME_LIMIT = 120;
@@ -20,7 +21,7 @@ export function cleanFileName(name) {
     return cleaned === "" ? "file" : cleaned;
 }
 /** The files folder: absolute, and relative to the project with forward slashes */
-export function filesFolder(projectDir, filesDir = "files") {
+export function filesFolder(projectDir, filesDir = DEFAULT_FILES_DIR) {
     const absolute = path.resolve(projectDir, filesDir);
     return {
         absolute,

package/dist/project/index.d.ts

@@ -2,3 +2,4 @@ export { ConfigEditError, editConfig, hasConfigPath, propertyText, type ConfigVa
 export { addVariable, ExistsError, VARIABLE_NAME } from "./variables.js";
 export { isGitIgnored, SECRET_NAME, setSecret } from "./secrets-file.js";
 export { cleanFileName, filesFolder, isFolderIgnored, RECORD_LIMIT, storeFile, } from "./files-store.js";
+export { loadConfig, type ResolvedConfig, type ResolvedEnvironment, type ResolvedIgnoreError, } from "../config/resolved-config.js";

package/dist/project/index.js

@@ -2,3 +2,4 @@ export { ConfigEditError, editConfig, hasConfigPath, propertyText, } from "./con
 export { addVariable, ExistsError, VARIABLE_NAME } from "./variables.js";
 export { isGitIgnored, SECRET_NAME, setSecret } from "./secrets-file.js";
 export { cleanFileName, filesFolder, isFolderIgnored, RECORD_LIMIT, storeFile, } from "./files-store.js";
+export { loadConfig, } from "../config/resolved-config.js";

package/dist/recorder/session-browser.js

@@ -1,7 +1,7 @@
 import { Browser } from "../browser/browser.js";
 import { ensureWarm } from "../browser/warm-up.js";
 import { readConfig } from "../config/config.js";
-import { browsersFor } from "../runner/browsers.js";
+import { browsersFor } from "../config/browsers-for.js";
 import { DEFAULT_PORT } from "../runner/ports.js";
 /**
  * The browser a recording uses: the one asked for, else the first of the project's (recording in two browsers at

package/dist/recorder/session.d.ts

@@ -31,8 +31,10 @@ export interface RecordSpecOptions extends ProjectOptions {
     /** Called after each step is written to the file, with the file's new content */
     onEvent?: (event: RecorderEvent, source: string) => void;
     /**
-     * Called when the recording is paused or resumed, or the toolbar fails (or comes back) on a page.
-     * There is no initial call: until the first one the recording is `{ state: "recording", toolbar: true }`
+     * Called once with the recording's first status right after `onStarted` resolves (`{ state: "recording" }`,
+     * and `toolbar: false` if the toolbar had already failed to load), then whenever the recording is paused
+     * or resumed, or the toolbar fails (or comes back) on a page. Statuses that arrive while `onStarted` runs are held
+     * and sent once it resolves, after the first status.
      */
     onStatus?: (status: {
         state: "recording" | "paused";
@@ -46,6 +48,7 @@ export interface RecordSpecOptions extends ProjectOptions {
         browser: Browser;
     }) => void | Promise<void>;
 }
+/** What a recording returns; every field is always present, empty when there is nothing to report. */
 export interface RecordResult {
     file: string;
     /** Full name of the test the steps went into */

package/dist/recorder/session.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { loadConfig, projectDir } from "../config/config.js";
+import { loadRawConfig, projectDir } from "../config/config.js";
 import { loadSecrets } from "../config/secrets.js";
 import { filesFolder, isFolderIgnored } from "../project/index.js";
 import { withProject } from "../runner/project.js";
@@ -30,11 +30,21 @@ export async function recordSpec(options) {
             ...options,
             headless: options.headless ?? settings.headless,
         });
-        const loaded = await loadConfig();
+        const loaded = await loadRawConfig();
         const folder = filesFolder(projectDir(), loaded.filesDir);
         const hadFolder = existsSync(folder.absolute);
         let recorder;
         const addedSecrets = new Set();
+        // Statuses that come while `onStarted` runs wait behind the first one, which is always the first
+        let waiting = [];
+        let toolbarLoaded = true;
+        const onStatus = (status) => {
+            toolbarLoaded = status.toolbar;
+            if (waiting)
+                waiting.push(status);
+            else
+                options.onStatus?.(status);
+        };
         let stopRequested;
         const stopped = new Promise((resolve) => (stopRequested = resolve));
         try {
@@ -50,7 +60,7 @@ export async function recordSpec(options) {
                 toolbar: {
                     ...(await toolbarOptions(run, spec.source, projectDir(), loaded, testIndex)),
                     projectDir: projectDir(),
-                    ...(options.onStatus && { onStatus: options.onStatus }),
+                    ...(options.onStatus && { onStatus }),
                     onSecretAdded: (name) => addedSecrets.add(name),
                     onStop: () => stopRequested(),
                 },
@@ -65,6 +75,11 @@ export async function recordSpec(options) {
                 },
             });
             await options.onStarted?.({ page, browser });
+            const queued = waiting ?? [];
+            waiting = undefined;
+            options.onStatus?.({ state: "recording", toolbar: toolbarLoaded });
+            for (const status of queued)
+                options.onStatus?.(status);
             let windowClosed = false;
             void browser.exited.then(() => (windowClosed = true));
             await new Promise((resolve) => {

package/dist/runner/groups.d.ts

@@ -1,9 +1,5 @@
 import type { SupportedBrowser } from "../types/browser.js";
 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;
@@ -16,7 +12,10 @@ export interface ResolvedGroup {
     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 */
+    /**
+     * Ids of the found tests in the group: the spec file relative to `srcDir` with `/` separators, `::`, then the
+     * full name (`FoundTest.id` is the same)
+     */
     testIds: string[];
     /** Picked tests that no longer exist */
     missing: {

package/dist/runner/groups.js

@@ -1,10 +1,7 @@
 import { realpathSync } from "node:fs";
 import { matchesGlob, relative, resolve } from "node:path";
-import { browsersFor } from "./browsers.js";
-/** 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";
+import { DEFAULT_TEST_MATCH } from "../config/defaults.js";
+import { browsersFor } from "../config/browsers-for.js";
 /**
  * The real path of `p` (symlinks resolved), or `p` itself when it does not exist. Registered test files come
  * from stack traces, which resolve symlinks, so paths compared with them must be real too

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

@@ -1,3 +1,4 @@
+import { DEFAULT_LOGS_CAPTURE } from "../config/defaults.js";
 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 {
@@ -16,15 +17,17 @@ export class RouteErrorsError extends Error {
     }
 }
 function isIgnored(error, ignore) {
-    return ignore.some((pattern) => typeof pattern === "string" ? error.message.includes(pattern) : pattern.test(error.message));
+    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";
+    const { config, entries, errors, dropped, testFailed, allowPageErrors, routeErrors = [], } = input;
+    const capture = config?.capture ?? DEFAULT_LOGS_CAPTURE;
     let error;
     if (routeErrors.length > 0 && !testFailed) {
         error = toTestError(new RouteErrorsError(routeErrors));

package/dist/runner/pooled-run.js

@@ -70,9 +70,9 @@ export function poolMode(input) {
 export async function runPooled(pool, planned, items, reporter, signal) {
     reporter.setOrder(planned);
     for (const { test, browser } of planned) {
-        const annotation = staticSkip(test);
-        if (annotation)
-            reporter.onTestSkipped(test, browser, { annotation });
+        const skip = staticSkip(test);
+        if (skip)
+            reporter.onTestSkipped(test, browser, skip);
     }
     const started = new Set();
     const ended = new Set();

package/dist/runner/project.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { removeGeneratedFiles } from "../browser/generated-files.js";
-import { loadConfig, projectDir, setActiveProject } from "../config/config.js";
+import { loadRawConfig, projectDir, setActiveProject, } from "../config/config.js";
 import { resetSecrets } from "../config/mask.js";
 import { setRunSettings } from "../config/run-settings.js";
 import { keepLogFiles } from "../logger/index.js";
@@ -20,7 +20,7 @@ export async function withProject(options, work) {
     const releaseLogs = keepLogFiles(path.resolve(dir ?? previousDir));
     try {
         setActiveProject({ dir: dir ?? previousDir, config, dataDir });
-        const loaded = config ?? (await loadConfig());
+        const loaded = config ?? (await loadRawConfig());
         setActiveProject({ dir: dir ?? previousDir, config: loaded, dataDir });
         resetSecrets();
         const run = prepareRun(loaded, {

package/dist/runner/registry.d.ts

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

package/dist/runner/registry.js

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

package/dist/runner/retries-option.js

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

package/dist/runner/run-test.js

@@ -67,7 +67,7 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
     // A test marked skip or fixme never runs, whoever asked for it (a flow's test node, a worker)
     const marked = staticSkip(test);
     if (marked) {
-        reporter.onTestSkipped(test, browserName, { annotation: marked });
+        reporter.onTestSkipped(test, browserName, marked);
         return;
     }
     logger.verbose("Starting test: %s in %s", test.name, browserName);

package/dist/runner/run.d.ts

@@ -1,6 +1,6 @@
 import type { Modifier, TestSummary } from "../types/test.js";
 import { type ProjectOptions } from "./project.js";
-import type { ResolvedGroup } from "./groups.js";
+import { type ResolvedGroup } from "./groups.js";
 import type { RunnerOptions } from "./options.js";
 export interface RunTestsOptions extends RunnerOptions, ProjectOptions {
 }
@@ -16,13 +16,25 @@ export interface RunTestsOptions extends RunnerOptions, ProjectOptions {
 export declare function runTests(options?: RunTestsOptions): Promise<TestSummary>;
 /** A test found in a spec file */
 export interface FoundTest {
+    /**
+     * The id the groups use for this test (`ResolvedGroup.testIds`): its spec file relative to `srcDir` with `/`
+     * separators, then `::` and its full name, e.g. `checkout/cart.spec.ts::Cart > adds`
+     */
+    id: string;
     /** Full name: `describe` titles and the test title joined with " > " */
     name: string;
     file: string;
+    /** The spec file relative to `srcDir`, with `/` separators */
+    relativeFile: string;
     /** `skip` or `fixme` (not run), or `only` (focused); absent for a plain test. A modifier on a `describe` counts. */
     modifier?: Modifier;
+    /** The `{ reason }` given with the `skip` or `fixme` that applies */
+    reason?: string;
 }
-/** Imports the project's specs without running anything and lists the tests the options select */
+/**
+ * Imports the project's specs without running anything and lists the tests the options select, each with the id
+ * its group uses and its spec file relative to `srcDir`
+ */
 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[]>;

package/dist/runner/run.js

@@ -1,4 +1,6 @@
+import path from "path";
 import { withProject } from "./project.js";
+import { testId, toPosix } from "./groups.js";
 import TestRunner from "./test-runner.js";
 /**
  * Sets the project up (config, environment, secrets), builds a runner from the rest of the options and hands both to
@@ -33,13 +35,26 @@ function inProject(options, work) {
 export async function runTests(options = {}) {
     return inProject(options, (runner) => runner.start());
 }
-/** Imports the project's specs without running anything and lists the tests the options select */
+/**
+ * Imports the project's specs without running anything and lists the tests the options select, each with the id
+ * its group uses and its spec file relative to `srcDir`
+ */
 export async function listTests(options = {}) {
-    return inProject(options, async (runner) => (await runner.register()).map(({ name, file, modifier }) => ({
-        name,
-        file,
-        ...(modifier && { modifier }),
-    })));
+    return inProject(options, async (runner) => {
+        const { tests, srcDir } = await runner.list();
+        return tests.map((test) => {
+            const { name, file, modifier, reason } = test;
+            const relativeFile = toPosix(path.relative(srcDir, file));
+            return {
+                id: testId(relativeFile, name),
+                name,
+                file,
+                relativeFile,
+                ...(modifier && { modifier }),
+                ...(reason !== undefined && { reason }),
+            };
+        });
+    });
 }
 /** Imports the project's specs without running anything and lists the config's groups with the tests each holds */
 export async function listGroups(options = {}) {

package/dist/runner/select.js

@@ -1,8 +1,8 @@
 import path from "path";
 import { pathToFileURL } from "url";
-import { loadConfig } from "../config/config.js";
+import { loadRawConfig } from "../config/config.js";
 import logger from "../logger/index.js";
-import { browsersFor } from "./browsers.js";
+import { browsersFor } from "../config/browsers-for.js";
 import { findGroup, resolveGroups, testId, toPosix, } from "./groups.js";
 import { assertModuleProject } from "./module-type.js";
 import { clearRegistry, registeredTests } from "./registry.js";
@@ -40,7 +40,7 @@ export function idOf(test, srcDir) {
 }
 /** The config's groups, resolved against the tests the specs register */
 async function resolveAll(tests) {
-    const config = await loadConfig();
+    const config = await loadRawConfig();
     const { dir, srcDir } = realDirs(config.srcDir);
     const groups = resolveGroups(config, tests.map(({ file, name }) => ({
         file: toPosix(path.relative(srcDir, file)),
@@ -69,7 +69,7 @@ export function selectTests({ all, groups, srcDir }, options) {
  */
 export async function browsersOfRun(groups, options) {
     const { browsers: flag, group } = options;
-    const config = await loadConfig();
+    const config = await loadRawConfig();
     const ofGroup = group !== undefined && !(flag && flag.length > 0)
         ? findGroup(groups, group).browsers
         : undefined;

package/dist/runner/skip.d.ts

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

package/dist/runner/skip.js

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

package/dist/runner/suite.d.ts

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

package/dist/runner/suite.js

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

package/dist/runner/test-dir.js

@@ -1,7 +1,8 @@
 import path from "path";
 import { projectDir } from "../config/config.js";
 import { cleanName } from "../browser/evidence.js";
-import { DEFAULT_SRC_DIR, realPath, toPosix } from "./groups.js";
+import { DEFAULT_SRC_DIR } from "../config/defaults.js";
+import { realPath, toPosix } from "./groups.js";
 /** The project and source folders as real paths: registered test files come from stack traces, which resolve symlinks */
 export function realDirs(configuredSrcDir) {
     const dir = realPath(projectDir());

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

@@ -26,8 +26,14 @@ export default class TestRunner {
     static init(run: PreparedRun, options?: RunnerOptions, project?: ProjectInfo): Promise<TestRunner>;
     /** The groups of the config with the tests each holds; see `listGroups` */
     groups(): Promise<ResolvedGroup[]>;
-    /** Imports the spec files and returns the tests the options select: by `group`, `testNames` and `grep` */
-    register(): Promise<RegisteredTestCase[]>;
+    /**
+     * Imports the spec files and returns the tests the options select (by `group`, `testNames` and `grep`)
+     * with the real `srcDir` their ids are relative to
+     */
+    list(): Promise<{
+        tests: RegisteredTestCase[];
+        srcDir: string;
+    }>;
     /**
      * Runs the selected tests in every browser of the run, one browser after the other, and returns the summary that
      * was also written to the report. With more than one worker the tests run at the same time in worker processes.