@itmetsam/samurai-framework 0.21.4 → 0.22.0

package/dist/runner/run-hooks.js

@@ -0,0 +1,52 @@
+import { resolveConfig } from "../config/resolved-config.js";
+import { webServersOf } from "../config/web-server-options.js";
+import logger from "../logger/index.js";
+import { globalHooks } from "./global-hooks.js";
+import { startWebServers } from "./web-server.js";
+/**
+ * Runs `work` between the config's run-level steps: web servers start, then `globalSetup`, then `work`, then
+ * `globalTeardown`, then the servers stop. The teardown runs when the work or the setup throws (not when a server
+ * failed to start, since nothing was set up), and the servers are stopped whatever happens. When the config has no
+ * `baseURL` for the run, the first server's address becomes `settings.baseURL`.
+ * Errors: a failed start is `webServer(): ...`, a failed setup `globalSetup(): ...`; the work's own error wins over
+ * a teardown error, which is logged then.
+ */
+export async function withRunHooks(run, work) {
+    const { config, settings, projectDir, signal } = run;
+    const servers = webServersOf(config);
+    if (servers.length === 0 &&
+        config.globalSetup === undefined &&
+        config.globalTeardown === undefined)
+        return work();
+    const running = await startWebServers(servers, { projectDir, signal });
+    let outcome;
+    try {
+        if (settings.baseURL === undefined && running.baseURL !== undefined)
+            settings.baseURL = running.baseURL;
+        const hooks = globalHooks(config, {
+            ...resolveConfig(config, { projectDir, env: process.env }),
+            environment: settings.environment,
+            ...(settings.baseURL !== undefined && { baseURL: settings.baseURL }),
+        }, projectDir);
+        try {
+            await hooks.setup();
+            outcome = { value: await work() };
+        }
+        catch (error) {
+            outcome = { error };
+        }
+        const teardownError = await hooks.teardown();
+        if (teardownError) {
+            if ("error" in outcome)
+                logger.error("%s", teardownError.message);
+            else
+                outcome = { error: teardownError };
+        }
+    }
+    finally {
+        await running.stop();
+    }
+    if (outcome && "error" in outcome)
+        throw outcome.error;
+    return outcome.value;
+}

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

@@ -1,5 +1,5 @@
 import type { SupportedBrowser } from "../types/browser.js";
-import type { AllHookFixtures, RegisteredTestCase } from "../types/test.js";
+import type { RegisteredTestCase } from "../types/test.js";
 import type { RunnerOptions } from "./options.js";
 import type { AllHooks } from "./all-hooks.js";
 import type { PreparedRun } from "./prepare-run.js";
@@ -17,7 +17,5 @@ export interface WorkerResources {
     /** The `beforeAll` / `afterAll` hooks of this worker: kept across tests, closed when the worker is done */
     allHooks?: AllHooks;
 }
-/** What `beforeAll` and `afterAll` hooks get: no page, only what a run knows */
-export declare function allHookFixtures(run: PreparedRun, browserName: SupportedBrowser, workerIndex?: number): AllHookFixtures;
 /** Runs one test in one browser and reports it: launch, run the body, judge the page's logs, close the browser */
 export declare function runOneTest(test: RegisteredTestCase, browserName: SupportedBrowser, run: PreparedRun, options: RunnerOptions, srcDir: string, reporter: TestSink, resources?: WorkerResources): Promise<void>;

package/dist/runner/run-test.js

@@ -1,9 +1,8 @@
+import path from "node:path";
 import { takePendingAssertions } from "../assert/expect.js";
 import { Browser } from "../browser/browser.js";
-import { Evidence } from "../browser/evidence.js";
+import { cleanName, Evidence } from "../browser/evidence.js";
 import { projectDir, readConfig } from "../config/config.js";
-import { createSecretsFixture } from "../config/secrets.js";
-import { createEnvFixture } from "../config/variables.js";
 import logger from "../logger/index.js";
 import { ConnectionClosedError } from "../transport/bidi-connection.js";
 import { judgePageLogs } from "./page-logs-report.js";
@@ -13,7 +12,14 @@ import { isSkipSignal, staticSkip } from "./skip.js";
 import { runOutput } from "./output.js";
 import { testDirOf } from "./test-dir.js";
 import { toTestError } from "./test-error.js";
-import { createInputsFixture, createOutputsFixture, ioOfAttempt, missingOutputs, } from "./test-io.js";
+import { runInTestScope, TestInfoImpl } from "./test-info.js";
+import { applyDeclaredMarks, judgeExpectation } from "./test-annotations.js";
+import { TestTimeout } from "./test-timeout.js";
+import { ioOfAttempt, missingOutputs } from "./test-io.js";
+import { buildTestFixtures } from "./fixtures.js";
+import { FixtureScope } from "./fixture-scope.js";
+import { RequestFixture } from "./request-fixture.js";
+import { effectiveUse } from "./use-options.js";
 import { beginOutputs, endOutputs } from "../wait/output-sink.js";
 /**
  * The state of one test run. A test ends once, whichever of finishing, failing, timing out, an abort or a
@@ -46,6 +52,10 @@ class TestOutcome {
             reason: signal.reason,
         });
     }
+    /** The test body ended by itself: a test expected to fail is passed by a failure and failed by a pass */
+    conclude(error, logs) {
+        this.finish(judgeExpectation(this.info, error), logs);
+    }
     finish(error, logs) {
         if (this.ended)
             return;
@@ -53,20 +63,11 @@ class TestOutcome {
         this.reporter.onTestEnd(this.test, this.browser, error, {
             ...logs,
             screenshots: this.evidence?.screenshots,
+            ...this.info?.reportExtras(),
             ...this.io(),
         });
     }
 }
-/** What `beforeAll` and `afterAll` hooks get: no page, only what a run knows */
-export function allHookFixtures(run, browserName, workerIndex = 0) {
-    const { settings, secrets } = run;
-    return {
-        browserName,
-        workerIndex,
-        env: createEnvFixture(settings.environment, settings.variables),
-        secrets: createSecretsFixture(settings.environment, secrets),
-    };
-}
 /** Runs one test in one browser and reports it: launch, run the body, judge the page's logs, close the browser */
 export async function runOneTest(test, browserName, run, options, srcDir, reporter, resources = {}) {
     // A test marked skip or fixme never runs, whoever asked for it (a flow's test node, a worker)
@@ -78,25 +79,29 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
     logger.verbose("Starting test: %s in %s", test.name, browserName);
     reporter.onTestStart(test, browserName);
     const outcome = new TestOutcome(reporter, test, browserName);
-    const { settings, secrets } = run;
+    const { settings } = run;
     const timeout = settings.timeout;
     const { resultDir } = runOutput(options, projectDir());
     let browser;
     let page;
-    let timeoutTimer;
+    let customFixtures;
+    let requestFixture;
     let onRunAborted;
     const timeoutController = new AbortController();
     let browserGone = () => { };
+    let testTimeout;
     /** Resolves when the time is up or the run is aborted; the test is reported failed then */
     const limit = new Promise((resolve) => {
-        timeoutTimer = setTimeout(() => {
+        // The test can change its own limit (`test.setTimeout`, `test.slow`): the message names the one in force
+        testTimeout = new TestTimeout(timeout, () => {
             outcome.finish({
-                message: `Test timed out after ${timeout / 1000} seconds`,
+                message: `Test timed out after ${(testTimeout?.ms ?? timeout) / 1000} seconds`,
                 type: "timeout",
             });
             timeoutController.abort(new Error("Test timed out"));
             resolve();
-        }, timeout);
+        });
+        testTimeout.start();
         onRunAborted = () => {
             if (timeoutController.signal.aborted)
                 return;
@@ -113,10 +118,12 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
         try {
             // The `beforeAll` hooks come first, before a browser exists
             await resources.allHooks?.ensure(test, browserName);
+            const use = await effectiveUse(test);
             const launched = await Browser.launch(browserName, {
                 port: resources.port ?? options.port ?? DEFAULT_PORT,
                 ...(resources.profileDir && { profileDir: resources.profileDir }),
                 headless: options.headless ?? settings.headless,
+                use,
             }, timeoutController.signal);
             browser = launched.browser;
             // A person closing the window, or the browser crashing: end the test now instead of waiting for a
@@ -133,25 +140,70 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
                 browserGone();
             });
             page = launched.page;
-            outcome.evidence = new Evidence(resultDir, `${browserName}/${testDirOf(test, srcDir)}${resources.attempt ? `/retry-${resources.attempt}` : ""}`);
+            // An empty `use` leaves the browser exactly as it was: no applier, nothing sent
+            const applied = Object.keys(use).length > 0
+                ? await launched.browser.setUse(use, projectDir())
+                : undefined;
+            const testFolder = `${browserName}${test.group === undefined ? "" : `/${cleanName(test.group)}`}/${testDirOf(test, srcDir)}${resources.attempt ? `/retry-${resources.attempt}` : ""}`;
+            outcome.evidence = new Evidence(resultDir, testFolder);
             launched.page.setEvidence(outcome.evidence);
-            const fixtures = {
-                page: launched.page,
-                browser: launched.browser,
+            const info = new TestInfoImpl({
+                test,
                 browserName,
                 workerIndex: resources.workerIndex ?? 0,
-                env: createEnvFixture(settings.environment, settings.variables),
-                secrets: createSecretsFixture(settings.environment, secrets),
-                inputs: createInputsFixture(test.inputs, options.inputs),
-                outputs: createOutputsFixture(sink),
-            };
-            await runWithEachHooks(test.suite, fixtures, timeoutController.signal, () => test.function(fixtures));
+                retry: resources.attempt ?? 0,
+                settings: { baseURL: settings.baseURL, timeout },
+                ...(testTimeout && { timeout: testTimeout }),
+                resultDir,
+                outputDir: path.join(resultDir, "attachments", ...testFolder.split("/")),
+            });
+            outcome.info = info;
+            applyDeclaredMarks(info, test);
+            requestFixture = new RequestFixture(settings.baseURL, use);
+            const built = buildTestFixtures({
+                request: requestFixture,
+                info,
+                launched,
+                browserName,
+                workerIndex: resources.workerIndex ?? 0,
+                run,
+                test,
+                options,
+                sink,
+                device: {
+                    isMobile: applied?.isMobile ?? false,
+                    hasTouch: applied?.hasTouch ?? false,
+                },
+            });
+            // A test written with `test.extend()` gets its custom fixtures set up on demand, and torn down below
+            const custom = test.extension
+                ? new FixtureScope(test.extension, built)
+                : undefined;
+            customFixtures = custom;
+            const fixtures = custom?.fixtures ?? built;
+            let failure;
+            let failed = false;
+            try {
+                await runInTestScope({ info, fixtures }, () => runWithEachHooks(test.suite, fixtures, timeoutController.signal, async () => {
+                    await custom?.prepare(test.function);
+                    return test.function(fixtures);
+                }, (error) => info.bodyDone(error), custom));
+            }
+            catch (err) {
+                failure = err;
+                failed = true;
+            }
+            const cleanup = await custom?.teardown(timeout);
+            if (cleanup && (!failed || isSkipSignal(failure)))
+                throw cleanup;
+            if (failed)
+                throw failure;
             // Already reported as timed out
             if (timeoutController.signal.aborted)
                 return;
             const unawaited = takePendingAssertions();
             if (unawaited.length > 0) {
-                outcome.finish({
+                outcome.conclude({
                     message: unawaited
                         .map((label) => `${label} was not awaited`)
                         .join("\n"),
@@ -162,23 +214,29 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
             // Checked only after a pass: a test that failed first reports its own failure
             const missing = missingOutputs(test.outputs, sink);
             if (missing) {
-                outcome.finish(missing, await judgeLogs(page, true));
+                outcome.conclude(missing, await judgeLogs(page, true));
                 return;
             }
             const verdict = await judgeLogs(page, false);
-            outcome.finish(verdict.error, verdict);
+            outcome.conclude(verdict.error, verdict);
         }
         catch (err) {
             if (timeoutController.signal.aborted)
                 return;
             if (isSkipSignal(err))
                 return outcome.skip(err);
-            outcome.finish(outcome.browserClosed || err instanceof ConnectionClosedError
+            const closed = outcome.browserClosed || err instanceof ConnectionClosedError;
+            const error = closed
                 ? {
                     message: "The browser was closed while the test was running",
                     type: "error",
                 }
-                : toTestError(err), await judgeLogs(page, true));
+                : toTestError(err);
+            const logs = await judgeLogs(page, true);
+            if (closed)
+                outcome.finish(error, logs);
+            else
+                outcome.conclude(error, logs);
         }
     };
     // Open for this attempt only: whatever a capture still saves after the attempt ended is ignored
@@ -188,9 +246,14 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
         await Promise.race([limit, gone, runBody()]);
     }
     finally {
+        // A test cut short (timeout, abort) did not get to its own cleanup: its fixtures are torn down before the browser
+        const late = await customFixtures?.teardown(timeout);
+        if (late)
+            logger.debug("A fixture failed after the test ended", { late });
+        await requestFixture?.dispose();
         endOutputs();
     }
-    clearTimeout(timeoutTimer);
+    testTimeout?.stop();
     if (onRunAborted)
         options.signal?.removeEventListener("abort", onRunAborted);
     takePendingAssertions();

package/dist/runner/run.d.ts

@@ -48,6 +48,7 @@ export declare function listGroups(options?: RunTestsOptions): Promise<ResolvedG
 export { BROWSER_NAMES, checkBrowserList } from "../config/browsers.js";
 export { parseWorkers } from "../config/workers.js";
 export { parseRetries } from "../config/retries.js";
+export { parseShard, type Shard } from "./shard.js";
 export type { RunEvent } from "./reporter.js";
 export type { Modifier, TestError, TestResult, TestSummary, } from "../types/test.js";
 export type { ResolvedGroup } from "./groups.js";

package/dist/runner/run.js

@@ -70,4 +70,5 @@ export async function listGroups(options = {}) {
 export { BROWSER_NAMES, checkBrowserList } from "../config/browsers.js";
 export { parseWorkers } from "../config/workers.js";
 export { parseRetries } from "../config/retries.js";
+export { parseShard } from "./shard.js";
 export { DEFAULT_PORT } from "./ports.js";

package/dist/runner/select.d.ts

@@ -15,10 +15,21 @@ export declare function isSelected(name: string, { grep, testNames }: Pick<Runne
 export declare function idOf(test: RegisteredTestCase, srcDir: string): string;
 /** Imports the spec files once and resolves the config's groups against what they registered */
 export declare function loadSpecs(testFiles: string[]): Promise<LoadedSpecs>;
-/** The tests the options select: by `group`, `testNames` and `grep` */
+/** The group names the options select, once each and in the order given; none when no group is selected */
+export declare function groupNamesOf(group: RunnerOptions["group"]): string[];
+/** The tests the options select: by `group` (in any of them), `testNames` and `grep`; each test once */
 export declare function selectTests({ all, groups, srcDir }: LoadedSpecs, options: RunnerOptions): RegisteredTestCase[];
 /**
- * The browsers the run uses: the options' (`--browser`), else the selected group's, else the project's, else
- * Firefox
+ * The runs of the selected tests: without a selected group, the tests as they are; else one copy per selected group
+ * that holds the test (its `group` set), the first group's tests first
  */
-export declare function browsersOfRun(groups: ResolvedGroup[], options: RunnerOptions): Promise<SupportedBrowser[]>;
+export declare function expandByGroup(selected: RegisteredTestCase[], { groups, srcDir }: LoadedSpecs, options: RunnerOptions): RegisteredTestCase[];
+/**
+ * The browsers a run of a test uses: the options' (`--browser`), else its group's, else the project's, else Firefox
+ */
+export declare function browserPlan(groups: ResolvedGroup[], options: RunnerOptions): Promise<{
+    /** Every browser of the run, in the order they run */
+    browsers: SupportedBrowser[];
+    /** The browsers one run of a test uses */
+    browsersOf(test: RegisteredTestCase): SupportedBrowser[];
+}>;

package/dist/runner/select.js

@@ -53,25 +53,51 @@ export async function loadSpecs(testFiles) {
     const all = await registerAll(testFiles);
     return { all, ...(await resolveAll(all)) };
 }
-/** The tests the options select: by `group`, `testNames` and `grep` */
+/** The group names the options select, once each and in the order given; none when no group is selected */
+export function groupNamesOf(group) {
+    return [...new Set(group === undefined ? [] : [group].flat())];
+}
+/** The tests the options select: by `group` (in any of them), `testNames` and `grep`; each test once */
 export function selectTests({ all, groups, srcDir }, options) {
-    const { group } = options;
+    const names = groupNamesOf(options.group);
     let inGroup = () => true;
-    if (group !== undefined) {
-        const members = new Set(findGroup(groups, group).testIds);
+    if (names.length > 0) {
+        const members = new Set(names.flatMap((name) => findGroup(groups, name).testIds));
         inGroup = (test) => members.has(idOf(test, srcDir));
     }
     return all.filter((test) => inGroup(test) && isSelected(test.name, options));
 }
 /**
- * The browsers the run uses: the options' (`--browser`), else the selected group's, else the project's, else
- * Firefox
+ * The runs of the selected tests: without a selected group, the tests as they are; else one copy per selected group
+ * that holds the test (its `group` set), the first group's tests first
+ */
+export function expandByGroup(selected, { groups, srcDir }, options) {
+    const names = groupNamesOf(options.group);
+    if (names.length === 0)
+        return selected;
+    return names.flatMap((name) => {
+        const members = new Set(findGroup(groups, name).testIds);
+        return selected
+            .filter((test) => members.has(idOf(test, srcDir)))
+            .map((test) => ({ ...test, group: name }));
+    });
+}
+/**
+ * The browsers a run of a test uses: the options' (`--browser`), else its group's, else the project's, else Firefox
  */
-export async function browsersOfRun(groups, options) {
-    const { browsers: flag, group } = options;
+export async function browserPlan(groups, options) {
+    const { browsers: flag } = options;
     const config = await loadRawConfig();
-    const ofGroup = group !== undefined && !(flag && flag.length > 0)
-        ? findGroup(groups, group).browsers
-        : undefined;
-    return browsersFor({ flag, group: ofGroup, project: config.browsers });
+    const names = groupNamesOf(options.group);
+    const flagged = flag && flag.length > 0;
+    const ofGroup = new Map(names.map((name) => [name, findGroup(groups, name).browsers]));
+    const project = browsersFor({ flag, project: config.browsers });
+    const forGroup = (name) => flagged ? project : (ofGroup.get(name) ?? project);
+    const browsers = [
+        ...new Set(names.length > 0 ? names.flatMap(forGroup) : project),
+    ];
+    return {
+        browsers,
+        browsersOf: (test) => test.group === undefined ? project : forGroup(test.group),
+    };
 }

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

@@ -0,0 +1,23 @@
+import type { SupportedBrowser } from "../types/browser.js";
+import type { RegisteredTestCase } from "../types/test.js";
+import type { TestSink } from "./reporter.js";
+/** One attempt at one test of the block, reporting to `sink` */
+export type BlockTest = (test: RegisteredTestCase, sink: TestSink, attempt: number) => Promise<void>;
+export interface SerialBlockRun {
+    tests: RegisteredTestCase[];
+    browser: SupportedBrowser;
+    retries: number;
+    signal: AbortSignal | undefined;
+    runTest: BlockTest;
+    /** Called before the block starts again after a failure: closes what the block's tests share (`afterAll`) */
+    restart(): Promise<void>;
+    sink: TestSink;
+}
+/**
+ * Runs the tests of a serial block in order. After a failure the rest of the block is reported as skipped; with
+ * `retries`, the whole block then runs again from its first test (after `restart`), up to `retries` times.
+ * Without retries every test is reported as it ends. With them the ends are held until the block's last attempt is
+ * known, as `runWithRetries` does for one test: each test ends once, with `retry` saying which attempt that was.
+ * An aborted run is never run again.
+ */
+export declare function serialBlockRun(run: SerialBlockRun): Promise<void>;

package/dist/runner/serial-run.js

@@ -0,0 +1,88 @@
+import { SERIAL_SKIP_REASON } from "./serial.js";
+import { staticSkip } from "./skip.js";
+/**
+ * Runs the tests of a serial block in order. After a failure the rest of the block is reported as skipped; with
+ * `retries`, the whole block then runs again from its first test (after `restart`), up to `retries` times.
+ * Without retries every test is reported as it ends. With them the ends are held until the block's last attempt is
+ * known, as `runWithRetries` does for one test: each test ends once, with `retry` saying which attempt that was.
+ * An aborted run is never run again.
+ */
+export async function serialBlockRun(run) {
+    const { tests, browser, retries, signal, sink } = run;
+    const live = retries === 0;
+    const previous = tests.map(() => []);
+    for (let attempt = 0;; attempt++) {
+        const ended = [];
+        let failedAt = -1;
+        for (const [at, test] of tests.entries()) {
+            const skip = staticSkip(test);
+            if (skip) {
+                sink.onTestSkipped(test, browser, skip);
+                continue;
+            }
+            if (signal?.aborted) {
+                for (const rest of tests.slice(at)) {
+                    if (staticSkip(rest))
+                        continue;
+                    sink.onTestStart(rest, browser);
+                    sink.onTestEnd(rest, browser, {
+                        message: "Run aborted",
+                        type: "error",
+                    });
+                }
+                return;
+            }
+            const attemptSink = {
+                onTestStart: (t, b) => sink.onTestStart(t, b, attempt > 0 ? attempt : undefined),
+                onTestEnd: (t, b, error, extras) => {
+                    ended[at] = { error, extras };
+                    if (live)
+                        sink.onTestEnd(t, b, error, extras);
+                },
+                onTestSkipped: (t, b, why) => sink.onTestSkipped(t, b, why),
+            };
+            await run.runTest(test, attemptSink, attempt);
+            if (ended[at]?.error) {
+                failedAt = at;
+                break;
+            }
+        }
+        const error = ended[failedAt]?.error;
+        if (error &&
+            attempt < retries &&
+            !signal?.aborted &&
+            error.message !== "Run aborted") {
+            previous[failedAt].push(error);
+            await run.restart();
+            continue;
+        }
+        if (!live)
+            flush(run, ended, previous, attempt);
+        if (failedAt >= 0)
+            for (const rest of tests.slice(failedAt + 1)) {
+                const skip = staticSkip(rest) ?? {
+                    annotation: "skip",
+                    reason: SERIAL_SKIP_REASON,
+                };
+                sink.onTestSkipped(rest, browser, skip);
+            }
+        return;
+    }
+}
+/** Reports the held ends of the last attempt, each saying which attempt it was and what failed before */
+function flush({ tests, browser, sink }, ended, previous, attempt) {
+    for (const [at, test] of tests.entries()) {
+        const end = ended[at];
+        if (!end)
+            continue;
+        const before = previous[at];
+        sink.onTestEnd(test, browser, end.error, {
+            ...end.extras,
+            ...(attempt > 0 && {
+                retry: attempt,
+                previousAttempts: [...before],
+                ...(!end.error && before.length > 0 && { flaky: true }),
+            }),
+        });
+    }
+}

package/dist/runner/serial.d.ts

@@ -0,0 +1,34 @@
+import type { RegisteredTestCase, Suite } from "../types/test.js";
+/** Why a test of a serial block did not run: an earlier test of the block failed */
+export declare const SERIAL_SKIP_REASON = "serial: an earlier test failed";
+/** `describe.configure(options)`: sets the mode of the suite the call is written in */
+export declare function configureSuite(suite: Suite, options: unknown): void;
+/** A group of tests that run in order on one worker; if one fails, the rest of the block is skipped */
+export interface SerialBlock {
+    /** The file and the `describe` titles of the block's outermost serial suite; the same in every process */
+    key: string;
+    /** The outermost suite in serial mode */
+    suite: Suite;
+}
+/** The serial block a test belongs to: the outermost suite around it in `"serial"` mode, else none */
+export declare function serialBlockOf(test: RegisteredTestCase): SerialBlock | undefined;
+/** The tests that must run one after the other on one worker, in the order they are listed */
+export interface RunUnit {
+    /** The same for every test of the unit, in every process */
+    key: string;
+    /** A serial block: a failure skips the rest and a retry runs the whole block again */
+    serial: boolean;
+}
+/**
+ * The unit a test runs in. A serial block is one. With `fullyParallel: false` every other test is in the unit of
+ * its file, unless a suite around it is in `"parallel"` mode. Otherwise (`true`, or not set: the tests of a file
+ * go to workers one by one) there is no unit.
+ */
+export declare function unitOf(test: RegisteredTestCase, fullyParallel: boolean | undefined): RunUnit | undefined;
+/** Tests that follow each other and belong to one serial block (`block`), or one test outside any block */
+export interface Chunk {
+    block?: SerialBlock;
+    tests: RegisteredTestCase[];
+}
+/** Splits a list of tests into serial blocks and the free tests between them, keeping the order */
+export declare function chunkBySerialBlock(tests: RegisteredTestCase[]): Chunk[];

package/dist/runner/serial.js

@@ -0,0 +1,63 @@
+import { suiteChain } from "./suite.js";
+/** Why a test of a serial block did not run: an earlier test of the block failed */
+export const SERIAL_SKIP_REASON = "serial: an earlier test failed";
+const MODES = ["default", "parallel", "serial"];
+/** `describe.configure(options)`: sets the mode of the suite the call is written in */
+export function configureSuite(suite, options) {
+    if (typeof options !== "object" || options === null)
+        throw new TypeError("describe.configure(): expected an options object like { mode: 'serial' }");
+    const { mode, ...rest } = options;
+    const unknown = Object.keys(rest);
+    if (unknown.length > 0)
+        throw new TypeError(`describe.configure(): unknown option "${unknown[0]}" (only mode is supported)`);
+    if (!MODES.includes(mode))
+        throw new TypeError(`describe.configure(): mode must be "default", "parallel" or "serial", got ${JSON.stringify(mode)}`);
+    if (mode === "default")
+        delete suite.mode;
+    else
+        suite.mode = mode;
+}
+const groupSuffix = (test) => test.group === undefined ? "" : `@${test.group}`;
+/** The serial block a test belongs to: the outermost suite around it in `"serial"` mode, else none */
+export function serialBlockOf(test) {
+    const suite = suiteChain(test.suite).find((s) => s.mode === "serial");
+    if (!suite)
+        return undefined;
+    const titles = suiteChain(suite).flatMap((s) => s.title === undefined ? [] : [s.title]);
+    // The same block run for two groups is two blocks
+    return {
+        key: `serial:${test.file}::${titles.join(" > ")}${groupSuffix(test)}`,
+        suite,
+    };
+}
+/**
+ * The unit a test runs in. A serial block is one. With `fullyParallel: false` every other test is in the unit of
+ * its file, unless a suite around it is in `"parallel"` mode. Otherwise (`true`, or not set: the tests of a file
+ * go to workers one by one) there is no unit.
+ */
+export function unitOf(test, fullyParallel) {
+    const block = serialBlockOf(test);
+    if (block)
+        return { key: block.key, serial: true };
+    if (fullyParallel !== false)
+        return undefined;
+    const nearest = suiteChain(test.suite)
+        .reverse()
+        .find((s) => s.mode === "parallel");
+    return nearest
+        ? undefined
+        : { key: `file:${test.file}${groupSuffix(test)}`, serial: false };
+}
+/** Splits a list of tests into serial blocks and the free tests between them, keeping the order */
+export function chunkBySerialBlock(tests) {
+    const chunks = [];
+    for (const test of tests) {
+        const block = serialBlockOf(test);
+        const last = chunks[chunks.length - 1];
+        if (block && last?.block?.key === block.key)
+            last.tests.push(test);
+        else
+            chunks.push({ ...(block && { block }), tests: [test] });
+    }
+    return chunks;
+}

package/dist/runner/shard.d.ts

@@ -0,0 +1,22 @@
+import type { RegisteredTestCase } from "../types/test.js";
+/** One slice of a run split over several machines: slice `current` of `total`, counting from 1 */
+export interface Shard {
+    current: number;
+    total: number;
+}
+/**
+ * Reads a shard: `"2/4"` (the command line's `--shard`) or `{ current: 2, total: 4 }` (the `shard` run option).
+ * `where` names the source in the error.
+ */
+export declare function parseShard(value: unknown, where: string): Shard;
+/**
+ * What a shard keeps together: a serial block is never split, and so is a file, unless `fullyParallel` is on or a
+ * `describe` around the test is in `"parallel"` mode: then the test goes by itself.
+ */
+export declare function shardGroupOf(test: RegisteredTestCase, fullyParallel: boolean | undefined): string;
+/**
+ * The tests of one shard. The groups (in the order their first test comes) are dealt out in order, so the shards are
+ * as equal in tests as whole groups allow: a group goes to the shard that holds its first test when all tests are
+ * cut into `total` equal ranges. The shards are disjoint and together hold every test; the order stays.
+ */
+export declare function shardTests(tests: RegisteredTestCase[], { current, total }: Shard, groupOf: (test: RegisteredTestCase) => string): RegisteredTestCase[];