@itmetsam/samurai-framework 0.21.5 → 0.22.1

package/dist/runner/prepare-run.js

@@ -2,11 +2,16 @@ 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";
+import { fixtureCatalog } from "./fixture-registry.js";
+import { checkFixtureUseNames } from "./fixture-use.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 = {}) {
+    // A fixture name defined twice refuses the run before any test starts
+    const catalog = fixtureCatalog(config.fixtures ?? []);
+    checkFixtureUseNames(config, catalog);
     const settings = resolveRunSettings(config, overrides);
     const secrets = loadSecrets(settings.environment, options);
     for (const [name, value] of secrets) {

package/dist/runner/registry.js

@@ -1,16 +1,19 @@
 import { fileURLToPath } from "node:url";
 import logger from "../logger/index.js";
 import { extendLayers } from "./fixture-defs.js";
+import { rememberLayers } from "./fixture-registry.js";
+import { checkTestFixtureUse } from "./fixture-use.js";
 import { validateUseOptions } from "../config/use-options.js";
 import { currentStepLog, currentTestInfo, infoFor, skipFromCondition, } from "./test-info.js";
 import { runStep } from "./steps.js";
 import { markTests } from "./test-annotations.js";
 import { validateTestIO } from "./test-io.js";
 import { addHook, addUse, currentSuite, enterSuite, leaveSuite, modifierOf, resetSuites, } from "./suite.js";
+import { configureSuite } from "./serial.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, reason) {
-    enterSuite(file, title, modifier, reason);
+function openDescribe(file, title, fn, modifier, reason, mode) {
+    enterSuite(file, title, modifier, reason, mode);
     try {
         const result = fn();
         if (result instanceof Promise) {
@@ -129,6 +132,9 @@ export const describe = Object.assign((title, fn) => openDescribe(callerFile(),
     skip: describeSkipping("skip"),
     fixme: describeSkipping("fixme"),
     only: (title, fn) => openDescribe(callerFile(), title, fn, "only"),
+    configure: (options) => configureSuite(currentSuite(callerFile()), options),
+    serial: (title, fn) => openDescribe(callerFile(), title, fn, undefined, undefined, "serial"),
+    parallel: (title, fn) => openDescribe(callerFile(), title, fn, undefined, undefined, "parallel"),
 });
 /** Runs before each test of the `describe` block it is written in (of the file, at the top level) */
 export function beforeEach(hook) {
@@ -146,16 +152,21 @@ export function beforeAll(hook) {
 export function afterAll(hook) {
     addHook(currentSuite(callerFile()), "afterAll", hook);
 }
-/** `test.use(options)`: checked now, applied when each test of the scope runs */
-function use(options) {
-    addUse(currentSuite(callerFile()), validateUseOptions(options));
+/** `test.use(options)` of a test with the fixtures `extension`: checked now, applied when each test of the scope runs */
+function usingFor(extension) {
+    return (options) => {
+        const checked = validateUseOptions(options);
+        // `fixtures` and option fixtures may only name what this test's `test.extend()` defines
+        checkTestFixtureUse(checked, extension);
+        addUse(currentSuite(callerFile()), checked);
+    };
 }
 /**
  * A `test` that registers its tests with the custom fixtures `extension`. The aliases are the same functions as
  * the named exports: they find the spec file from the stack, so they must not be wrapped.
  */
 function makeTest(extension) {
-    return Object.assign(registering("test", undefined, extension), {
+    const made = Object.assign(registering("test", undefined, extension), {
         skip: skipping("skip", extension),
         fixme: skipping("fixme", extension),
         fail: failing(extension),
@@ -164,7 +175,7 @@ function makeTest(extension) {
         step: (title, body, options) => runStep(currentStepLog(), title, body, options),
         only: registering("test.only", "only", extension),
         info: currentTestInfo,
-        use,
+        use: usingFor(extension),
         describe,
         beforeEach,
         afterEach,
@@ -172,6 +183,9 @@ function makeTest(extension) {
         afterAll,
         extend: (fixtures) => makeTest(extendLayers(extension, fixtures)),
     });
+    if (extension)
+        rememberLayers(made, extension);
+    return made;
 }
 export const test = makeTest();
 export function registeredTests() {

package/dist/runner/reporter.d.ts

@@ -1,5 +1,6 @@
-import type { TestAnnotation, TestStepEntry, TestAttachmentEntry, RegisteredTestCase, TestError, TestLogEntry, TestResult, TestRetries, TestSummary } from "../types/test.js";
+import type { TestAnnotation, TestFixtureEntry, TestStepEntry, TestAttachmentEntry, RegisteredTestCase, TestError, TestLogEntry, TestResult, TestRetries, TestSummary } from "../types/test.js";
 import type { SupportedBrowser } from "../types/browser.js";
+import type { Shard } from "./shard.js";
 /** What a run reports while it happens */
 export type RunEvent = {
     type: "run-start";
@@ -9,11 +10,15 @@ export type RunEvent = {
     browsers: SupportedBrowser[];
     /** How many tests run at the same time; absent when they run one after the other */
     workers?: number;
+    /** The slice of the selected tests this run holds, when it is a shard */
+    shard?: Shard;
 } | {
     type: "test-start";
     name: string;
     file: string;
     browser: SupportedBrowser;
+    /** The group the test runs for, when the run selected groups; absent otherwise */
+    group?: string;
     /** The attempt, counting from 1, when the test is run again after a failure; absent for the first */
     retry?: number;
 } | {
@@ -21,6 +26,8 @@ export type RunEvent = {
     name: string;
     file: string;
     browser: SupportedBrowser;
+    /** The group the test ran for, when the run selected groups; absent otherwise */
+    group?: string;
     result: TestResult;
 } | {
     type: "run-end";
@@ -33,6 +40,8 @@ export interface ReporterOptions {
     browsers: SupportedBrowser[];
     /** Where the report is written. @default <cwd>/result/report.json */
     output?: string | false;
+    /** The slice of the selected tests this run holds; recorded in the report */
+    shard?: Shard;
     /** Called with every event, in order. A throwing listener is ignored */
     onEvent?: (event: RunEvent) => void;
 }
@@ -66,6 +75,8 @@ export interface TestEndExtras extends TestRetries {
     annotations?: TestAnnotation[];
     /** The steps the test ran with `test.step` */
     steps?: TestStepEntry[];
+    /** The fixtures the test set up, when it set any up */
+    fixtures?: TestFixtureEntry[];
 }
 export default class TestReporter implements TestSink {
     private testResults;
@@ -74,6 +85,7 @@ export default class TestReporter implements TestSink {
     private browsers;
     private output;
     private listener;
+    private shard;
     /** Keys of the run's tests in the order the report lists them; unset: the order they started in */
     private order;
     constructor(options: ReporterOptions);

package/dist/runner/reporter.js

@@ -2,10 +2,12 @@ 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, full title and browser, so equal titles in different files or describe blocks, and the same test in two browsers, stay apart */
+/** Results are keyed by file, full title, browser and group, so equal titles in different files or describe blocks, and the same test in two browsers or for two groups, stay apart */
 function keyOf(test, browser) {
-    return `${test.file}::${test.name}::${browser}`;
+    return `${test.file}::${test.name}::${browser}${test.group === undefined ? "" : `::${test.group}`}`;
 }
+/** The `group` of a test's report entry and events: nothing when no group was selected */
+const groupOf = (test) => test.group === undefined ? {} : { group: test.group };
 export default class TestReporter {
     constructor(options) {
         this.testResults = new Map();
@@ -14,6 +16,7 @@ export default class TestReporter {
         this.output =
             options.output ?? path.join(projectDir(), "result/report.json");
         this.listener = options.onEvent;
+        this.shard = options.shard;
     }
     emit(event) {
         try {
@@ -43,6 +46,7 @@ export default class TestReporter {
             total,
             browsers: this.browsers,
             ...(workers > 1 && { workers }),
+            ...(this.shard && { shard: this.shard }),
         });
     }
     async onEnd() {
@@ -61,6 +65,7 @@ export default class TestReporter {
             duration,
             environment: this.environment,
             browsers: this.browsers,
+            ...(this.shard && { shard: this.shard }),
             tests,
             status: tests.every((r) => r.status === "success" || r.status === "skipped")
                 ? "success"
@@ -82,6 +87,7 @@ export default class TestReporter {
             name: test.name,
             file: test.file,
             browser,
+            ...groupOf(test),
             status: "started",
             startTime: t.startTime,
         });
@@ -90,6 +96,7 @@ export default class TestReporter {
             name: test.name,
             file: test.file,
             browser,
+            ...groupOf(test),
             ...(retry ? { retry } : {}),
         });
     }
@@ -111,6 +118,7 @@ export default class TestReporter {
             name: test.name,
             file: test.file,
             browser,
+            ...groupOf(test),
             result,
         });
     }
@@ -131,6 +139,7 @@ export default class TestReporter {
             name: test.name,
             file: test.file,
             browser,
+            ...groupOf(test),
             result: ended,
         });
     }
@@ -151,6 +160,7 @@ export default class TestReporter {
             ...(extras?.attachments && { attachments: extras.attachments }),
             ...(extras?.annotations && { annotations: extras.annotations }),
             ...(extras?.steps && { steps: extras.steps }),
+            ...(extras?.fixtures?.length && { fixtures: extras.fixtures }),
             ...(extras?.retry && { retry: extras.retry }),
             ...(extras?.flaky && { flaky: true }),
             ...(extras?.previousAttempts?.length && {
@@ -163,6 +173,7 @@ export default class TestReporter {
             name: test.name,
             file: test.file,
             browser,
+            ...groupOf(test),
             result,
         });
     }

package/dist/runner/request-fixture.d.ts

@@ -0,0 +1,14 @@
+import type { APIRequestContext } from "../request/api-request-context.js";
+import type { UseOptions } from "../types/use.js";
+/**
+ * The `request` fixture of one test: an `APIRequestContext` of its own (its own cookies), made when the test first
+ * reads it, from the run's `baseURL` and the `use` options, and disposed when the test is over
+ */
+export declare class RequestFixture {
+    private readonly baseURL;
+    private readonly use;
+    private context;
+    constructor(baseURL: string | undefined, use: UseOptions);
+    get(): APIRequestContext;
+    dispose(): Promise<void>;
+}

package/dist/runner/request-fixture.js

@@ -0,0 +1,25 @@
+import { createRequestContext } from "../request/request.js";
+/**
+ * The `request` fixture of one test: an `APIRequestContext` of its own (its own cookies), made when the test first
+ * reads it, from the run's `baseURL` and the `use` options, and disposed when the test is over
+ */
+export class RequestFixture {
+    constructor(baseURL, use) {
+        this.baseURL = baseURL;
+        this.use = use;
+    }
+    get() {
+        const { use } = this;
+        return (this.context ??= createRequestContext({
+            baseURL: this.baseURL,
+            extraHTTPHeaders: use.extraHTTPHeaders,
+            ignoreHTTPSErrors: use.acceptInsecureCerts,
+            ...(use.storageState !== undefined && {
+                storageState: use.storageState,
+            }),
+        }));
+    }
+    async dispose() {
+        await this.context?.dispose();
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { RunSettings } from "../config/run-settings.js";
+import type { SamuraiTestConfig } from "../types/config.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 declare function withRunHooks<T>(run: {
+    config: SamuraiTestConfig;
+    settings: RunSettings;
+    projectDir: string;
+    signal?: AbortSignal | undefined;
+}, work: () => Promise<T>): Promise<T>;

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

@@ -4,6 +4,7 @@ import type { RunnerOptions } from "./options.js";
 import type { AllHooks } from "./all-hooks.js";
 import type { PreparedRun } from "./prepare-run.js";
 import type { TestSink } from "./reporter.js";
+import type { WorkerFixtures } from "./fixture-worker.js";
 /** What a worker gives its tests that the main process does not: its own port and profile, and its number */
 export interface WorkerResources {
     /** The browser's debugging port. @default `options.port`, else DEFAULT_PORT */
@@ -16,6 +17,8 @@ export interface WorkerResources {
     attempt?: number;
     /** The `beforeAll` / `afterAll` hooks of this worker: kept across tests, closed when the worker is done */
     allHooks?: AllHooks;
+    /** The worker-scoped fixtures of this worker: kept across tests, closed when the worker is done */
+    workerFixtures?: WorkerFixtures;
 }
 /** 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,7 +1,7 @@
 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 logger from "../logger/index.js";
 import { ConnectionClosedError } from "../transport/bidi-connection.js";
@@ -18,7 +18,9 @@ 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 { effectiveFixtureUse } from "./fixture-use.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
@@ -37,6 +39,8 @@ class TestOutcome {
         this.browserClosed = false;
         /** The test's inputs and outputs, as its report entry lists them when it ends */
         this.io = () => ({});
+        /** The fixtures the test set up, as they stand when it ends */
+        this.fixtures = () => [];
     }
     get isEnded() {
         return this.ended;
@@ -64,6 +68,7 @@ class TestOutcome {
             screenshots: this.evidence?.screenshots,
             ...this.info?.reportExtras(),
             ...this.io(),
+            fixtures: this.fixtures(),
         });
     }
 }
@@ -84,6 +89,7 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
     let browser;
     let page;
     let customFixtures;
+    let requestFixture;
     let onRunAborted;
     const timeoutController = new AbortController();
     let browserGone = () => { };
@@ -117,6 +123,9 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
             // The `beforeAll` hooks come first, before a browser exists
             await resources.allHooks?.ensure(test, browserName);
             const use = await effectiveUse(test);
+            const fixtureUse = test.extension
+                ? await effectiveFixtureUse(test)
+                : undefined;
             const launched = await Browser.launch(browserName, {
                 port: resources.port ?? options.port ?? DEFAULT_PORT,
                 ...(resources.profileDir && { profileDir: resources.profileDir }),
@@ -142,7 +151,7 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
             const applied = Object.keys(use).length > 0
                 ? await launched.browser.setUse(use, projectDir())
                 : undefined;
-            const testFolder = `${browserName}/${testDirOf(test, srcDir)}${resources.attempt ? `/retry-${resources.attempt}` : ""}`;
+            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 info = new TestInfoImpl({
@@ -157,7 +166,9 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
             });
             outcome.info = info;
             applyDeclaredMarks(info, test);
+            requestFixture = new RequestFixture(settings.baseURL, use);
             const built = buildTestFixtures({
+                request: requestFixture,
                 info,
                 launched,
                 browserName,
@@ -173,9 +184,17 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
             });
             // 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)
+                ? new FixtureScope(test.extension, built, {
+                    ...fixtureUse,
+                    environment: settings.environment,
+                    ...(resources.workerFixtures && {
+                        workers: resources.workerFixtures,
+                    }),
+                })
                 : undefined;
             customFixtures = custom;
+            if (custom)
+                outcome.fixtures = () => custom.report();
             const fixtures = custom?.fixtures ?? built;
             let failure;
             let failed = false;
@@ -246,6 +265,7 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
         const late = await customFixtures?.teardown(timeout);
         if (late)
             logger.debug("A fixture failed after the test ended", { late });
+        await requestFixture?.dispose();
         endOutputs();
     }
     testTimeout?.stop();

package/dist/runner/run.d.ts

@@ -1,6 +1,7 @@
 import type { Modifier, TestSummary } from "../types/test.js";
 import { type ProjectOptions } from "./project.js";
 import { type ResolvedGroup } from "./groups.js";
+import { type FixtureCatalogEntry } from "./fixture-registry.js";
 import type { RunnerOptions } from "./options.js";
 export interface RunTestsOptions extends RunnerOptions, ProjectOptions {
 }
@@ -45,9 +46,16 @@ export interface FoundTest {
 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[]>;
+/**
+ * Lists the fixtures of the extended tests in the config's `fixtures`, with their label, icon, scope, option form
+ * and declared outputs, without running a test. Throws for a name defined twice or one that is not allowed.
+ */
+export declare function listFixtures(options?: ProjectOptions): Promise<FixtureCatalogEntry[]>;
+export type { FixtureCatalogEntry } from "./fixture-registry.js";
 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

@@ -1,6 +1,8 @@
 import path from "path";
 import { withProject } from "./project.js";
 import { testId, toPosix } from "./groups.js";
+import { projectConfig } from "../config/config.js";
+import { fixtureCatalog, } from "./fixture-registry.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
@@ -67,7 +69,15 @@ export async function listTests(options = {}) {
 export async function listGroups(options = {}) {
     return inProject(options, (runner) => runner.groups());
 }
+/**
+ * Lists the fixtures of the extended tests in the config's `fixtures`, with their label, icon, scope, option form
+ * and declared outputs, without running a test. Throws for a name defined twice or one that is not allowed.
+ */
+export async function listFixtures(options = {}) {
+    return fixtureCatalog((await projectConfig(options)).fixtures ?? []);
+}
 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>;