@itmetsam/samurai-framework 0.21.5 → 0.22.1

package/dist/runner/fixture-use.js

@@ -0,0 +1,64 @@
+import { FIXTURES_KEY, mergeFixtureUse, pickFixtureUse, } from "../config/fixture-use.js";
+import { peekRunSettings } from "../config/run-settings.js";
+import { useLayers } from "./use-options.js";
+/**
+ * The fixtures a test gets from `use`: config, then the run's environment, then the group, then `test.use()`, a
+ * later layer winning key by key. The environment's `false` is the exception: it wins over a `true` anywhere, so a
+ * fixture an environment turns off cannot be switched back on for it.
+ */
+export async function effectiveFixtureUse(test) {
+    const layers = await useLayers(test);
+    const merged = mergeFixtureUse([
+        layers.config,
+        layers.environment,
+        layers.group,
+        ...layers.tests,
+    ]);
+    const environment = peekRunSettings()?.environment ?? "";
+    const disabled = new Map();
+    for (const [name, on] of Object.entries(mergeFixtureUse([layers.environment]).fixtures))
+        if (!on)
+            disabled.set(name, `Fixture ${name} is turned off in ${environment}`);
+    return {
+        attach: Object.entries(merged.fixtures)
+            .filter(([, on]) => on)
+            .map(([name]) => name),
+        options: merged.options,
+        disabled,
+    };
+}
+const list = (names, none) => names.length > 0 ? names.join(", ") : none;
+/** Throws when a `use` names a fixture or an option fixture that `catalog` does not have */
+function checkPlace(place, use, catalog) {
+    const fixtures = catalog.map((entry) => entry.name);
+    const options = catalog.flatMap((entry) => entry.options?.name ?? []);
+    for (const [key, value] of Object.entries(pickFixtureUse(use))) {
+        if (key === FIXTURES_KEY) {
+            for (const name of Object.keys(value))
+                if (!fixtures.includes(name))
+                    throw new Error(`${place}.fixtures: unknown fixture "${name}". ${fixtures.length > 0 ? `Known fixtures: ${list(fixtures, "")}` : "No fixtures are listed in config.fixtures"}`);
+        }
+        else if (!options.includes(key))
+            throw new Error(`${place}.${key}: unknown option fixture "${key}". ${options.length > 0 ? `Known option fixtures: ${list(options, "")}` : "No option fixtures are listed in config.fixtures"}`);
+    }
+}
+/** Refuses a config whose `use` (config, environments, groups) names a fixture that is not in `config.fixtures` */
+export function checkFixtureUseNames(config, catalog) {
+    checkPlace("config.use", config.use, catalog);
+    for (const [name, environment] of Object.entries(config.environments ?? {}))
+        checkPlace(`config.environments.${name}.use`, environment.use, catalog);
+    config.groups?.forEach((group, index) => checkPlace(`config.groups[${index}].use`, group.use, catalog));
+}
+/** Refuses a `test.use()` that names a fixture the test's own `test.extend()` does not define */
+export function checkTestFixtureUse(use, layers) {
+    for (const [key, value] of Object.entries(pickFixtureUse(use))) {
+        const known = [...(layers?.keys() ?? [])];
+        if (key === FIXTURES_KEY) {
+            for (const name of Object.keys(value))
+                if (!layers?.has(name))
+                    throw new TypeError(`use(): unknown fixture "${name}". ${known.length > 0 ? `This test has: ${known.join(", ")}` : "This test has no fixtures; write it with test.extend()"}`);
+        }
+        else if (!layers?.get(key)?.slice(-1)[0]?.option)
+            throw new TypeError(`use(): unknown option fixture "${key}"`);
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { FixtureDef } from "./fixture-defs.js";
+import { type Started } from "./fixture-start.js";
+/** A worker fixture that is set up: its value, how to finish it, and the outputs the report lists */
+export interface WorkerInstance {
+    value: unknown;
+    started: Started;
+    outputs?: Record<string, string | number | boolean> | undefined;
+}
+/**
+ * The worker-scoped fixtures of one worker. An instance is shared by the tests that need the same definition with
+ * the same key (the environment, the resolved options and the instances it uses), is set up on first use and is
+ * torn down when the worker is done, last set up first.
+ */
+export declare class WorkerFixtures {
+    private readonly limitMs;
+    private readonly byDef;
+    private readonly live;
+    /** `limitMs`: how long a teardown may take when the fixture has no `timeout` of its own */
+    constructor(limitMs: number);
+    /** The instance of `def` under `key`: the one already set up, else the result of `make`. A failed setup is not kept */
+    acquire(def: FixtureDef, key: string, make: () => Promise<WorkerInstance>): Promise<WorkerInstance & {
+        reused: boolean;
+    }>;
+    /** Tears every instance down, last set up first, and returns the errors; a second call has nothing to do */
+    closeAll(): Promise<Error[]>;
+}

package/dist/runner/fixture-worker.js

@@ -0,0 +1,46 @@
+import { finishWithin } from "./fixture-start.js";
+/**
+ * The worker-scoped fixtures of one worker. An instance is shared by the tests that need the same definition with
+ * the same key (the environment, the resolved options and the instances it uses), is set up on first use and is
+ * torn down when the worker is done, last set up first.
+ */
+export class WorkerFixtures {
+    /** `limitMs`: how long a teardown may take when the fixture has no `timeout` of its own */
+    constructor(limitMs) {
+        this.limitMs = limitMs;
+        this.byDef = new Map();
+        this.live = [];
+    }
+    /** The instance of `def` under `key`: the one already set up, else the result of `make`. A failed setup is not kept */
+    async acquire(def, key, make) {
+        let keys = this.byDef.get(def);
+        if (!keys)
+            this.byDef.set(def, (keys = new Map()));
+        const existing = keys.get(key);
+        if (existing)
+            return { ...(await existing), reused: true };
+        const created = make().then((instance) => {
+            this.live.push(instance);
+            return instance;
+        });
+        keys.set(key, created);
+        try {
+            return { ...(await created), reused: false };
+        }
+        catch (err) {
+            keys.delete(key);
+            throw err;
+        }
+    }
+    /** Tears every instance down, last set up first, and returns the errors; a second call has nothing to do */
+    async closeAll() {
+        const errors = [];
+        this.byDef.clear();
+        for (let one = this.live.pop(); one; one = this.live.pop()) {
+            const error = await finishWithin(one.started, this.limitMs);
+            if (error)
+                errors.push(error);
+        }
+        return errors;
+    }
+}

package/dist/runner/fixtures.d.ts

@@ -2,6 +2,7 @@ import type { Browser } from "../browser/browser.js";
 import type Page from "../browser/page.js";
 import type { SupportedBrowser } from "../types/browser.js";
 import type { AllHookFixtures, RegisteredTestCase, TestFixtures, TestInfo } from "../types/test.js";
+import type { RequestFixture } from "./request-fixture.js";
 import type { RunnerOptions } from "./options.js";
 import type { PreparedRun } from "./prepare-run.js";
 import type { OutputSink } from "../wait/output-sink.js";
@@ -20,6 +21,8 @@ export interface FixtureSources {
     options: RunnerOptions;
     sink: OutputSink;
     info: TestInfo;
+    /** The test's `request` fixture, made on first use */
+    request: RequestFixture;
     /** What the `use` options came to in this browser */
     device: {
         isMobile: boolean;
@@ -27,7 +30,7 @@ export interface FixtureSources {
     };
 }
 /**
- * The fixtures a test body and its each-hooks receive. `context`, `baseURL` and `testInfo` are getters: nothing
+ * The fixtures a test body and its each-hooks receive. `context`, `baseURL`, `request` and `testInfo` are getters: nothing
  * is looked up until a test reads one (and `page.context()` throws for a page without one, which only a test
  * that asks for it should see).
  */

package/dist/runner/fixtures.js

@@ -12,12 +12,12 @@ export function allHookFixtures(run, browserName, workerIndex = 0) {
     };
 }
 /**
- * The fixtures a test body and its each-hooks receive. `context`, `baseURL` and `testInfo` are getters: nothing
+ * The fixtures a test body and its each-hooks receive. `context`, `baseURL`, `request` and `testInfo` are getters: nothing
  * is looked up until a test reads one (and `page.context()` throws for a page without one, which only a test
  * that asks for it should see).
  */
 export function buildTestFixtures(from) {
-    const { launched, browserName, workerIndex, run, test, options, sink, info, device, } = from;
+    const { launched, browserName, workerIndex, run, test, options, sink, info, device, request, } = from;
     const { settings, secrets } = run;
     const fixtures = {
         page: launched.page,
@@ -34,6 +34,7 @@ export function buildTestFixtures(from) {
     return Object.defineProperties(fixtures, {
         context: { enumerable: true, get: () => launched.page.context() },
         baseURL: { enumerable: true, get: () => settings.baseURL },
+        request: { enumerable: true, get: () => request.get() },
         testInfo: { enumerable: true, get: () => info },
     });
 }

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

@@ -0,0 +1,13 @@
+import type { GlobalHookConfig, SamuraiTestConfig } from "../types/config.js";
+/** The run-level hooks of a config: `setup` before the tests, `teardown` after them */
+export interface GlobalHooks {
+    /** Runs `globalSetup`. A throw is `globalSetup(): message` */
+    setup(): Promise<void>;
+    /**
+     * Runs what the setup returned, then `globalTeardown`; both even when the setup failed half way. Resolves with the
+     * first error as `globalTeardown(): message`, else undefined
+     */
+    teardown(): Promise<Error | undefined>;
+}
+/** Binds the config's `globalSetup` / `globalTeardown` to the config they receive and the project folder they load from */
+export declare function globalHooks(config: SamuraiTestConfig, hookConfig: GlobalHookConfig, projectDir: string): GlobalHooks;

package/dist/runner/global-hooks.js

@@ -0,0 +1,66 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+/** The function a hook names: given directly, or the default export of the module at `projectDir`/`hook` */
+async function loadHook(name, hook, projectDir) {
+    if (typeof hook === "function")
+        return hook;
+    const file = path.resolve(projectDir, hook);
+    let module;
+    try {
+        module = (await import(pathToFileURL(file).href));
+    }
+    catch (error) {
+        throw new Error(`${name}(): cannot load ${hook}: ${messageOf(error)}`);
+    }
+    if (typeof module.default !== "function")
+        throw new Error(`${name}(): ${hook} must export a function as default`);
+    return module.default;
+}
+/** Binds the config's `globalSetup` / `globalTeardown` to the config they receive and the project folder they load from */
+export function globalHooks(config, hookConfig, projectDir) {
+    const returned = [];
+    return {
+        async setup() {
+            if (config.globalSetup === undefined)
+                return;
+            try {
+                const setup = (await loadHook("globalSetup", config.globalSetup, projectDir));
+                const teardown = await setup(hookConfig);
+                if (typeof teardown === "function")
+                    returned.push(teardown);
+            }
+            catch (error) {
+                const message = messageOf(error);
+                throw new Error(message.startsWith("globalSetup(): ")
+                    ? message
+                    : `globalSetup(): ${message}`);
+            }
+        },
+        async teardown() {
+            let first;
+            const record = (error) => {
+                const message = messageOf(error);
+                first ??= new Error(message.startsWith("globalTeardown(): ")
+                    ? message
+                    : `globalTeardown(): ${message}`);
+            };
+            for (const teardown of returned.splice(0).reverse())
+                try {
+                    await teardown();
+                }
+                catch (error) {
+                    record(error);
+                }
+            if (config.globalTeardown !== undefined)
+                try {
+                    const teardown = (await loadHook("globalTeardown", config.globalTeardown, projectDir));
+                    await teardown(hookConfig);
+                }
+                catch (error) {
+                    record(error);
+                }
+            return first;
+        },
+    };
+}

package/dist/runner/options.d.ts

@@ -1,5 +1,6 @@
 import type { SupportedBrowser } from "../types/browser.js";
 import type { RunEvent } from "./reporter.js";
+import type { Shard } from "./shard.js";
 /** What decides which tests of the found files run, and how the browser starts */
 export interface RunnerOptions {
     /** Spec files to run, absolute or relative to the project folder. Default: every `*.spec.ts` under `srcDir` */
@@ -8,8 +9,12 @@ export interface RunnerOptions {
     grep?: string | RegExp;
     /** Only tests with exactly one of these full names (`describe` titles joined with " > ") */
     testNames?: string[];
-    /** Only the tests of this group of the config's `groups` (unknown name: an error). Combines with the other filters */
-    group?: string;
+    /**
+     * Only the tests of this group of the config's `groups`, or of any of these (unknown name: an error). Combines with
+     * the other filters. The run applies the group's `use` and `browsers`; a test in two selected groups runs once per
+     * group, and its results name the group.
+     */
+    group?: string | string[];
     /** The browsers to run in, instead of the group's or the project's `browsers` (the command line's `--browser`) */
     browsers?: SupportedBrowser[];
     /**
@@ -24,6 +29,12 @@ export interface RunnerOptions {
      * @default the config's `retries`, else 0
      */
     retries?: number | string;
+    /**
+     * Runs only one slice of the selected tests, to split a run over several machines (the command line's
+     * `--shard=current/total`). Whole files, and serial blocks, go to one shard; the shards are disjoint and together
+     * hold every test. The report names the shard. A shard without tests succeeds.
+     */
+    shard?: Shard;
     /**
      * Values for the inputs the tests declare, by name: every test of the run reads the names it declares from
      * here, and its own default for a name missing here

package/dist/runner/output-tail.d.ts

@@ -0,0 +1,14 @@
+/** The last few lines a child process printed, kept for the error message when it fails */
+export declare class OutputTail {
+    private readonly max;
+    /** Values to hide besides the registered secrets (the child's own `env` values) */
+    private readonly hidden;
+    private lines;
+    private partial;
+    constructor(max?: number, 
+    /** Values to hide besides the registered secrets (the child's own `env` values) */
+    hidden?: readonly string[]);
+    add(chunk: Buffer | string): void;
+    /** The kept lines, masked, one per line; empty when the child printed nothing */
+    text(): string;
+}

package/dist/runner/output-tail.js

@@ -0,0 +1,30 @@
+import { MASK, maskText } from "../config/mask.js";
+/** The last few lines a child process printed, kept for the error message when it fails */
+export class OutputTail {
+    constructor(max = 20, 
+    /** Values to hide besides the registered secrets (the child's own `env` values) */
+    hidden = []) {
+        this.max = max;
+        this.hidden = hidden;
+        this.lines = [];
+        this.partial = "";
+    }
+    add(chunk) {
+        const text = this.partial + chunk.toString();
+        const parts = text.split(/\r?\n/);
+        this.partial = parts.pop() ?? "";
+        this.lines.push(...parts);
+        if (this.lines.length > this.max)
+            this.lines.splice(0, this.lines.length - this.max);
+    }
+    /** The kept lines, masked, one per line; empty when the child printed nothing */
+    text() {
+        let text = [...this.lines, this.partial]
+            .filter((line) => line !== "")
+            .join("\n");
+        for (const value of this.hidden)
+            if (value.length >= 4)
+                text = text.split(value).join(MASK);
+        return maskText(text);
+    }
+}

package/dist/runner/pool-schedule.d.ts

@@ -0,0 +1,22 @@
+import type { WorkItem } from "./worker-protocol.js";
+/** What scheduling needs to know of a queued item and of a worker */
+interface Queued {
+    item: WorkItem;
+}
+export interface Worker {
+    /** The unit this worker is running; it keeps the unit's items to itself until none is left */
+    unit?: string | undefined;
+    /** The serial key of the unit, held while the worker keeps the unit */
+    unitKey?: string | undefined;
+    busy?: {
+        entry: Queued;
+    } | undefined;
+}
+/**
+ * The queue position of the next item for `worker`: one of the unit it is running, else the first whose serial
+ * key is not running and whose unit is not held by a worker. -1 when there is none.
+ */
+export declare function nextEligible(queue: Queued[], workers: Worker[], worker: Worker): number;
+/** How many queued items could run at the same time right now: the items of a unit count one */
+export declare function eligibleCount(queue: Queued[], workers: Worker[]): number;
+export {};

package/dist/runner/pool-schedule.js

@@ -0,0 +1,55 @@
+/** The serial keys that are running, or kept by a worker between the items of its unit */
+function busyKeys(workers) {
+    const keys = new Set();
+    for (const { busy, unitKey } of workers) {
+        const key = busy?.entry.item.serialKey ?? unitKey;
+        if (key)
+            keys.add(key);
+    }
+    return keys;
+}
+/** The units workers are running: no other worker may take their items */
+function heldUnits(workers) {
+    const units = new Set();
+    for (const { unit } of workers)
+        if (unit)
+            units.add(unit);
+    return units;
+}
+/**
+ * The queue position of the next item for `worker`: one of the unit it is running, else the first whose serial
+ * key is not running and whose unit is not held by a worker. -1 when there is none.
+ */
+export function nextEligible(queue, workers, worker) {
+    if (worker.unit) {
+        const unit = worker.unit;
+        const at = queue.findIndex(({ item }) => item.unit === unit);
+        if (at >= 0)
+            return at;
+        worker.unit = worker.unitKey = undefined;
+    }
+    const busy = busyKeys(workers);
+    const units = heldUnits(workers);
+    return queue.findIndex(({ item }) => (!item.serialKey || !busy.has(item.serialKey)) &&
+        (!item.unit || !units.has(item.unit)));
+}
+/** How many queued items could run at the same time right now: the items of a unit count one */
+export function eligibleCount(queue, workers) {
+    const taken = busyKeys(workers);
+    const units = heldUnits(workers);
+    let count = 0;
+    for (const { item } of queue) {
+        if (item.unit) {
+            if (units.has(item.unit))
+                continue;
+            units.add(item.unit);
+        }
+        if (item.serialKey) {
+            if (taken.has(item.serialKey))
+                continue;
+            taken.add(item.serialKey);
+        }
+        count++;
+    }
+    return count;
+}

package/dist/runner/pool-units.d.ts

@@ -0,0 +1,34 @@
+import type { TestError, TestResult } from "../types/test.js";
+import type { WorkItem } from "./worker-protocol.js";
+/** The error a failed result carries, as the next result lists it in `previousAttempts` */
+export declare function errorOf(result: TestResult): TestError;
+/** The result of a test of a serial block that did not run, because an earlier test of the block failed */
+export declare function serialSkipped(item: WorkItem): TestResult;
+/** What the pool keeps of a queued item: the item, and whatever else it needs to find its place again */
+interface Held<E> {
+    entry: E;
+    result: TestResult;
+}
+/**
+ * A serial block as the pool runs it. With retries the results are held until the block's last attempt is known,
+ * so a test ends once, saying which attempt that was; without, the pool reports them as they come and uses this
+ * only to count the attempts.
+ */
+export declare class UnitState<E extends {
+    item: WorkItem;
+}> {
+    readonly call: unknown;
+    /** Which attempt at the block this is, counting from 0 */
+    attempt: number;
+    private held;
+    private readonly previous;
+    constructor(call: unknown);
+    hold(entry: E, result: TestResult): void;
+    /** The block failed and runs again: forgets this attempt's results, remembers the error and returns the entries to queue again, in order */
+    restart(failed: E, result: TestResult): E[];
+    /** The held results of the last attempt, each saying which attempt it was and what failed before; they are not held any more */
+    release(): Held<E>[];
+}
+/** The result of an item that ended without one: the worker died, or the run was aborted */
+export declare function failedResult(item: WorkItem, message: string, startTime?: number): TestResult;
+export {};

package/dist/runner/pool-units.js

@@ -0,0 +1,85 @@
+import { SERIAL_SKIP_REASON } from "./serial.js";
+/** The error a failed result carries, as the next result lists it in `previousAttempts` */
+export function errorOf(result) {
+    const { message, type, stack, expected, actual } = result;
+    return {
+        message: message ?? "The test failed",
+        type: type ?? "error",
+        ...(stack !== undefined && { stack }),
+        ...(expected !== undefined && { expected }),
+        ...(actual !== undefined && { actual }),
+    };
+}
+/** The result of a test of a serial block that did not run, because an earlier test of the block failed */
+export function serialSkipped(item) {
+    return {
+        name: item.testName,
+        file: item.file,
+        browser: item.browser,
+        status: "skipped",
+        startTime: Date.now(),
+        duration: 0,
+        annotation: "skip",
+        reason: SERIAL_SKIP_REASON,
+    };
+}
+/**
+ * A serial block as the pool runs it. With retries the results are held until the block's last attempt is known,
+ * so a test ends once, saying which attempt that was; without, the pool reports them as they come and uses this
+ * only to count the attempts.
+ */
+export class UnitState {
+    constructor(call) {
+        this.call = call;
+        /** Which attempt at the block this is, counting from 0 */
+        this.attempt = 0;
+        this.held = [];
+        this.previous = new Map();
+    }
+    hold(entry, result) {
+        this.held.push({ entry, result });
+    }
+    /** The block failed and runs again: forgets this attempt's results, remembers the error and returns the entries to queue again, in order */
+    restart(failed, result) {
+        const entries = this.held.map(({ entry }) => entry);
+        this.held = [];
+        const errors = this.previous.get(failed) ?? [];
+        errors.push(errorOf(result));
+        this.previous.set(failed, errors);
+        this.attempt++;
+        return entries;
+    }
+    /** The held results of the last attempt, each saying which attempt it was and what failed before; they are not held any more */
+    release() {
+        const released = this.held.map(({ entry, result }) => {
+            const before = this.previous.get(entry) ?? [];
+            return {
+                entry,
+                result: {
+                    ...result,
+                    ...(this.attempt > 0 && {
+                        retry: this.attempt,
+                        previousAttempts: [...before],
+                        ...(result.status === "success" &&
+                            before.length > 0 && { flaky: true }),
+                    }),
+                },
+            };
+        });
+        this.held = [];
+        return released;
+    }
+}
+/** The result of an item that ended without one: the worker died, or the run was aborted */
+export function failedResult(item, message, startTime = Date.now()) {
+    return {
+        name: item.testName,
+        file: item.file,
+        browser: item.browser,
+        status: "failed",
+        type: "error",
+        message,
+        startTime,
+        duration: Date.now() - startTime,
+    };
+}

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

@@ -3,6 +3,7 @@ import type { SamuraiGroup } from "../types/config.js";
 import type { RegisteredTestCase, TestResult } from "../types/test.js";
 import type { ResolvedGroup } from "./groups.js";
 import type TestReporter from "./reporter.js";
+import type { RunUnit } from "./serial.js";
 import type { RunHooks } from "./worker-pool.js";
 import type { WorkItem } from "./worker-protocol.js";
 /** What a run needs from a worker pool: `WorkerPool` itself, or a fake in tests */
@@ -16,10 +17,11 @@ export interface PlannedTest {
 }
 /**
  * Lists the run: every selected test in the first browser, then every selected test in the next one. The
- * position in the list is the item's `index`. `serialKey` says which group makes a test run alone. `inputs`, the
- * run's input values, go with every item.
+ * position in the list is the item's `index`. `serialKey` says which group makes a test run alone, `unitOf` which
+ * tests must run one after the other on one worker (a serial block, a file). `inputs`, the run's input values, go
+ * with every item. `runsIn` says which browsers a test runs in (all of them unless a group names its own).
  */
-export declare function planItems(selected: RegisteredTestCase[], browsers: SupportedBrowser[], serialKey: (test: RegisteredTestCase) => string | undefined, inputs?: Record<string, string>): {
+export declare function planItems(selected: RegisteredTestCase[], browsers: SupportedBrowser[], serialKey: (test: RegisteredTestCase) => string | undefined, inputs?: Record<string, string>, unitOf?: (test: RegisteredTestCase) => RunUnit | undefined, runsIn?: (test: RegisteredTestCase, browser: SupportedBrowser) => boolean): {
     items: WorkItem[];
     planned: PlannedTest[];
 };
@@ -29,8 +31,8 @@ export declare function planItems(selected: RegisteredTestCase[], browsers: Supp
  */
 export declare function serialKeyOf(groups: ResolvedGroup[], configGroups: SamuraiGroup[] | undefined, srcDir: string): (test: RegisteredTestCase) => string | undefined;
 /**
- * How many items can run at the same time: each item alone counts one, and the items of one serial key together
- * count one. More workers than this would only sit idle.
+ * How many items can run at the same time: each item alone counts one, and the items of one unit, or of one serial
+ * key, together count one. More workers than this would only sit idle.
  */
 export declare function concurrency(items: WorkItem[]): number;
 /**

package/dist/runner/pooled-run.js

@@ -2,23 +2,31 @@ import { idOf } from "./select.js";
 import { staticSkip } from "./skip.js";
 /**
  * Lists the run: every selected test in the first browser, then every selected test in the next one. The
- * position in the list is the item's `index`. `serialKey` says which group makes a test run alone. `inputs`, the
- * run's input values, go with every item.
+ * position in the list is the item's `index`. `serialKey` says which group makes a test run alone, `unitOf` which
+ * tests must run one after the other on one worker (a serial block, a file). `inputs`, the run's input values, go
+ * with every item. `runsIn` says which browsers a test runs in (all of them unless a group names its own).
  */
-export function planItems(selected, browsers, serialKey, inputs) {
-    const planned = browsers.flatMap((browser) => selected.map((test) => ({ test, browser })));
+export function planItems(selected, browsers, serialKey, inputs, unitOf = () => undefined, runsIn = () => true) {
+    const planned = browsers.flatMap((browser) => selected
+        .filter((test) => runsIn(test, browser))
+        .map((test) => ({ test, browser })));
     // A test that does not run (skip, fixme) is in the plan but not in the queue; `index` is its place in the plan
     const items = planned.flatMap(({ test, browser }, index) => {
         if (staticSkip(test))
             return [];
         const key = serialKey(test);
+        const unit = unitOf(test);
         return [
             {
                 index,
                 file: test.file,
                 testName: test.name,
                 browser,
+                ...(test.group !== undefined && { group: test.group }),
                 ...(key !== undefined && { serialKey: key }),
+                // One unit per browser: the same block in two browsers is two runs
+                ...(unit && { unit: `${unit.key}@${browser}` }),
+                ...(unit?.serial && { serial: true }),
                 ...(inputs !== undefined && { inputs }),
             },
         ];
@@ -41,17 +49,19 @@ export function serialKeyOf(groups, configGroups, srcDir) {
     return (test) => keys.get(idOf(test, srcDir));
 }
 /**
- * How many items can run at the same time: each item alone counts one, and the items of one serial key together
- * count one. More workers than this would only sit idle.
+ * How many items can run at the same time: each item alone counts one, and the items of one unit, or of one serial
+ * key, together count one. More workers than this would only sit idle.
  */
 export function concurrency(items) {
     const keys = new Set();
     let free = 0;
     for (const item of items) {
-        if (item.serialKey === undefined)
-            free++;
+        if (item.unit !== undefined)
+            keys.add(`unit:${item.unit}`);
+        else if (item.serialKey !== undefined)
+            keys.add(`key:${item.serialKey}`);
         else
-            keys.add(item.serialKey);
+            free++;
     }
     return free + keys.size;
 }