@itmetsam/samurai-framework 0.21.5 → 0.22.1

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[];

package/dist/runner/shard.js

@@ -0,0 +1,73 @@
+import { serialBlockOf } from "./serial.js";
+import { suiteChain } from "./suite.js";
+/**
+ * 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 function parseShard(value, where) {
+    const shard = shardOf(value);
+    if (shard &&
+        Number.isInteger(shard.current) &&
+        Number.isInteger(shard.total) &&
+        shard.current >= 1 &&
+        shard.current <= shard.total)
+        return { current: shard.current, total: shard.total };
+    const shown = typeof value === "string" ? value : JSON.stringify(value);
+    throw new Error(`${where}: expected current/total with 1 <= current <= total, got ${typeof value === "string" ? `"${shown}"` : String(shown)}`);
+}
+function shardOf(value) {
+    if (typeof value === "string") {
+        const match = /^\s*(\d+)\s*\/\s*(\d+)\s*$/.exec(value);
+        return match
+            ? { current: Number(match[1]), total: Number(match[2]) }
+            : undefined;
+    }
+    if (typeof value === "object" && value !== null) {
+        const { current, total } = value;
+        if (typeof current === "number" && typeof total === "number")
+            return { current, total };
+    }
+    return undefined;
+}
+/**
+ * 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 function shardGroupOf(test, fullyParallel) {
+    const block = serialBlockOf(test);
+    if (block)
+        return block.key;
+    const alone = fullyParallel === true ||
+        suiteChain(test.suite).some((s) => s.mode === "parallel");
+    return alone ? `test:${test.file}::${test.name}` : `file:${test.file}`;
+}
+/**
+ * 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 function shardTests(tests, { current, total }, groupOf) {
+    const groups = new Map();
+    for (const test of tests) {
+        const key = groupOf(test);
+        const members = groups.get(key);
+        if (members)
+            members.push(test);
+        else
+            groups.set(key, [test]);
+    }
+    const size = Math.floor(tests.length / total);
+    const extra = tests.length - size * total;
+    const index = current - 1;
+    const from = size * index + Math.min(extra, index);
+    const to = from + size + (index < extra ? 1 : 0);
+    const kept = new Set();
+    let first = 0;
+    for (const members of groups.values()) {
+        if (first >= from && first < to)
+            for (const test of members)
+                kept.add(test);
+        first += members.length;
+    }
+    return tests.filter((test) => kept.has(test));
+}

package/dist/runner/suite.d.ts

@@ -1,12 +1,12 @@
-import type { EachHook, Modifier, Suite } from "../types/test.js";
+import type { EachHook, Modifier, Suite, SuiteMode } from "../types/test.js";
 import type { UseOptions } from "../types/use.js";
 /** The four hook lists a suite can hold */
 export type HookKind = "beforeEach" | "afterEach" | "beforeAll" | "afterAll";
-export declare function newSuite(title?: string, parent?: Suite, modifier?: Modifier, reason?: string): Suite;
+export declare function newSuite(title?: string, parent?: Suite, modifier?: Modifier, reason?: string, mode?: SuiteMode): Suite;
 /** The suite a test or hook written now belongs to: the innermost open `describe`, else the file's own */
 export declare function currentSuite(file: string): Suite;
 /** Opens a `describe` block under the current suite; `leaveSuite` closes it */
-export declare function enterSuite(file: string, title: string, modifier?: Modifier, reason?: string): Suite;
+export declare function enterSuite(file: string, title: string, modifier?: Modifier, reason?: string, mode?: SuiteMode): Suite;
 export declare function leaveSuite(): void;
 /** Forgets every suite: a run registers its specs afresh */
 export declare function resetSuites(): void;

package/dist/runner/suite.js

@@ -2,12 +2,13 @@
 const roots = new Map();
 /** The `describe` blocks being registered, outermost first */
 const open = [];
-export function newSuite(title, parent, modifier, reason) {
+export function newSuite(title, parent, modifier, reason, mode) {
     return {
         ...(title !== undefined && { title }),
         ...(parent && { parent }),
         ...(modifier && { modifier }),
         ...(reason !== undefined && { reason }),
+        ...(mode && { mode }),
     };
 }
 /** The suite a test or hook written now belongs to: the innermost open `describe`, else the file's own */
@@ -23,8 +24,8 @@ export function currentSuite(file) {
     return root;
 }
 /** Opens a `describe` block under the current suite; `leaveSuite` closes it */
-export function enterSuite(file, title, modifier, reason) {
-    const suite = newSuite(title, currentSuite(file), modifier, reason);
+export function enterSuite(file, title, modifier, reason, mode) {
+    const suite = newSuite(title, currentSuite(file), modifier, reason, mode);
     open.push(suite);
     return suite;
 }

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

@@ -1,5 +1,5 @@
-import type { AllHook, TestCaseBase, TestDetails, TestInfo, TestOptions } from "../types/test.js";
-import type { UseOptions } from "../types/use.js";
+import type { AllHook, SuiteMode, TestCaseBase, TestDetails, TestInfo, TestOptions } from "../types/test.js";
+import type { FixtureUse, UseOptions } from "../types/use.js";
 import type { FixtureDefinitions, FixturesOf, MergeFixtures } from "../types/extend.js";
 /** What the registry keeps of a test body; the fixtures it gets are those of the test it was written for */
 export type Body = TestCaseBase["function"];
@@ -46,7 +46,7 @@ export interface TestFunction<X = NoFixtures> {
      * the whole file at the top level, whether before or after the tests. An inner block wins over an outer one, and
      * both win over config `use`.
      */
-    use: (options: UseOptions) => void;
+    use: (options: UseOptions & FixtureUse) => void;
     /** `describe`, under the name other frameworks use */
     describe: DescribeFunction;
     /** `beforeEach`, as `test.beforeEach` */
@@ -86,6 +86,18 @@ export interface DescribeFunction {
     skip: DescribeSkipFunction;
     fixme: DescribeSkipFunction;
     only(title: string, fn: () => void): void;
+    /**
+     * Sets how the tests of the `describe` block it is written in (of the file, at the top level) run:
+     * `"serial"` runs them in order on one worker and skips the rest after a failure, `"parallel"` lets them run on
+     * different workers even when the config does not, `"default"` follows the config's `fullyParallel`
+     */
+    configure(options: {
+        mode: SuiteMode;
+    }): void;
+    /** A `describe` block in `"serial"` mode */
+    serial(title: string, fn: () => void): void;
+    /** A `describe` block in `"parallel"` mode */
+    parallel(title: string, fn: () => void): void;
 }
 /** `test.fail()` and `test.slow()`: with a condition (a function gets the test's fixtures), or none for "always" */
 export interface ConditionFunction<X> {

package/dist/runner/test-info.js

@@ -26,7 +26,8 @@ export class TestInfoImpl {
             this.column = test.column;
         this.retry = from.retry;
         this.workerIndex = from.workerIndex;
-        this.project = { name: from.browserName };
+        // A run for a group is named after it (as a Playwright project is), else after the browser
+        this.project = { name: test.group ?? from.browserName };
         this.config = { ...from.settings };
         this.resultDir = from.resultDir;
         this.outputDir = from.outputDir;

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

@@ -39,6 +39,7 @@ export default class TestRunner {
      * was also written to the report. With more than one worker the tests run at the same time in worker processes.
      */
     start(): Promise<import("../types/test.js").TestSummary>;
+    private execute;
     /** Whether anything but the default says how many workers to use */
     private workersAsked;
     /** The pool of a run: up to `workers` worker processes that read the same project and settings as this run */

package/dist/runner/test-runner.js

@@ -6,6 +6,7 @@ import { loadRawConfig, projectDir, readConfig } from "../config/config.js";
 import { forbidsOnly } from "../config/forbid-only.js";
 import logger from "../logger/index.js";
 import { AllHooks } from "./all-hooks.js";
+import { WorkerFixtures } from "./fixture-worker.js";
 import { assertNoOnly, narrowToOnly } from "./focus.js";
 import { DEFAULT_SRC_DIR, DEFAULT_TEST_MATCH } from "../config/defaults.js";
 import { DEFAULT_PORT } from "./ports.js";
@@ -14,11 +15,15 @@ import { concurrency, planItems, poolMode, runPooled, serialKeyOf, } from "./poo
 import { allHookFixtures } from "./fixtures.js";
 import { runOneTest } from "./run-test.js";
 import { staticSkip } from "./skip.js";
-import { browsersOfRun, loadSpecs, selectTests } from "./select.js";
+import { browserPlan, expandByGroup, loadSpecs, selectTests, } from "./select.js";
 import { resolveRetries } from "./retries-option.js";
 import { runWithRetries } from "./retry.js";
+import { chunkBySerialBlock, unitOf } from "./serial.js";
+import { parseShard, shardGroupOf, shardTests } from "./shard.js";
+import { serialBlockRun } from "./serial-run.js";
 import { resolveWorkers } from "../config/workers-option.js";
 import { runOutput } from "./output.js";
+import { withRunHooks } from "./run-hooks.js";
 import { WorkerPool } from "./worker-pool.js";
 import { processWorkerFactory } from "./worker-process.js";
 /** Finds the spec files, picks the tests and browsers of a run and runs each test in each browser */
@@ -63,18 +68,37 @@ export default class TestRunner {
      * was also written to the report. With more than one worker the tests run at the same time in worker processes.
      */
     async start() {
+        const config = await loadRawConfig();
+        // Web servers and `globalSetup` come first and `globalTeardown` last, around everything below
+        return withRunHooks({
+            config,
+            settings: this.run.settings,
+            projectDir: projectDir(),
+            signal: this.options.signal,
+        }, () => this.execute(config));
+    }
+    async execute(config) {
         const { onEvent, signal } = this.options;
         // The specs are imported once: their top-level code runs once per run
         const loaded = await loadSpecs(this.testFiles);
-        const config = await loadRawConfig();
         // A focused test the config refuses stops the run before anything starts; else only the focused ones run
         assertNoOnly(loaded.all, forbidsOnly(config), loaded.srcDir);
-        const selected = narrowToOnly(selectTests(loaded, this.options));
-        const browsers = await browsersOfRun(loaded.groups, this.options);
+        const shard = this.options.shard
+            ? parseShard(this.options.shard, "shard")
+            : undefined;
+        const focused = narrowToOnly(selectTests(loaded, this.options));
+        const sharded = shard
+            ? shardTests(focused, shard, (test) => shardGroupOf(test, config.fullyParallel))
+            : focused;
+        // A test of two selected groups is two runs, each with its group's `use` and `browsers`
+        const selected = expandByGroup(sharded, loaded, this.options);
+        const { browsers, browsersOf } = await browserPlan(loaded.groups, this.options);
+        const runsIn = (test, browser) => browsersOf(test).includes(browser);
         const reporter = new TestReporter({
             environment: this.run.settings.environment,
             browsers,
             output: runOutput(this.options, projectDir()).report,
+            ...(shard && { shard }),
             ...(onEvent && { onEvent }),
         });
         // How the run goes is settled first: a bad `workers` is an error before any browser starts
@@ -89,7 +113,7 @@ export default class TestRunner {
             env: process.env.SAMURAI_RETRIES,
             config: config.retries,
         });
-        const plan = planItems(selected, browsers, serialKeyOf(loaded.groups, config.groups, loaded.srcDir), this.options.inputs);
+        const plan = planItems(selected, browsers, serialKeyOf(loaded.groups, config.groups, loaded.srcDir), this.options.inputs, (test) => unitOf(test, config.fullyParallel), runsIn);
         // A pool larger than what can overlap would only hold idle workers: a group that runs one at a time needs one
         const lanes = concurrency(plan.items);
         const mode = poolMode({
@@ -120,35 +144,59 @@ export default class TestRunner {
             }
             return reporter.onEnd();
         }
-        reporter.onStart(selected.length * browsers.length);
+        reporter.onStart(plan.planned.length);
         // The `afterAll` hooks run when the last test is done, before the run ends
         const allHooks = new AllHooks({
             timeout: this.run.settings.timeout,
             fixtures: (browser) => allHookFixtures(this.run, browser),
         });
+        // The worker-scoped fixtures of the run: torn down when the last test is done
+        const workerFixtures = new WorkerFixtures(this.run.settings.timeout);
         try {
             for (const browser of browsers) {
-                for (const test of selected) {
-                    const skip = staticSkip(test);
-                    if (skip) {
-                        reporter.onTestSkipped(test, browser, skip);
-                        continue;
-                    }
-                    if (signal?.aborted) {
-                        reporter.onTestStart(test, browser);
-                        reporter.onTestEnd(test, browser, {
-                            message: "Run aborted",
-                            type: "error",
+                const forBrowser = selected.filter((test) => runsIn(test, browser));
+                for (const chunk of chunkBySerialBlock(forBrowser)) {
+                    const runTest = (test, sink, attempt) => runOneTest(test, browser, this.run, this.options, loaded.srcDir, sink, { allHooks, workerFixtures, attempt });
+                    if (chunk.block) {
+                        const { suite } = chunk.block;
+                        await serialBlockRun({
+                            tests: chunk.tests,
+                            browser,
+                            retries,
+                            signal,
+                            sink: reporter,
+                            runTest,
+                            restart: async () => {
+                                for (const error of await allHooks.closeWithin(suite))
+                                    logger.error("%s", error.message);
+                            },
                         });
                         continue;
                     }
-                    await runWithRetries(test, browser, retries, signal, (sink, attempt) => runOneTest(test, browser, this.run, this.options, loaded.srcDir, sink, { allHooks, attempt }), reporter);
+                    for (const test of chunk.tests) {
+                        const skip = staticSkip(test);
+                        if (skip) {
+                            reporter.onTestSkipped(test, browser, skip);
+                            continue;
+                        }
+                        if (signal?.aborted) {
+                            reporter.onTestStart(test, browser);
+                            reporter.onTestEnd(test, browser, {
+                                message: "Run aborted",
+                                type: "error",
+                            });
+                            continue;
+                        }
+                        await runWithRetries(test, browser, retries, signal, (sink, attempt) => runTest(test, sink, attempt), reporter);
+                    }
                 }
             }
         }
         finally {
             for (const error of await allHooks.closeAll())
                 logger.error("%s", error.message);
+            for (const error of await workerFixtures.closeAll())
+                logger.error("%s", error.message);
         }
         return reporter.onEnd();
     }
@@ -171,6 +219,7 @@ export default class TestRunner {
                     dataDir: this.project.dataDir,
                 }),
                 environment: settings.environment,
+                ...(settings.baseURL !== undefined && { baseURL: settings.baseURL }),
                 timeout: settings.timeout,
                 expectTimeout: settings.expectTimeout,
                 ...(headless !== undefined && { headless }),

package/dist/runner/use-options.d.ts

@@ -1,7 +1,21 @@
+import type { GroupUse } from "../types/config.js";
 import type { RegisteredTestCase } from "../types/test.js";
-import type { UseOptions } from "../types/use.js";
+/** The `use` objects that apply to one test, as written, lowest layer first */
+export interface UseLayers {
+    /** Config `use` */
+    config: object;
+    /** `environments.<name>.use` of the run's environment */
+    environment: object;
+    /** `use` of the group the test runs for */
+    group: object;
+    /** The `test.use()` calls around the test, outermost first */
+    tests: object[];
+}
+/** The `use` layers of a test: config, then the run's environment, then the group it runs for, then `test.use()` */
+export declare function useLayers(test: RegisteredTestCase): Promise<UseLayers>;
 /**
- * The `use` options one test runs with: config `use`, then the `test.use()` calls around the test, outermost
- * first, a later one winning key by key
+ * The `use` options one test runs with: config `use`, then the `use` of the run's environment, then the `use` of
+ * the group the test runs for (if any), then the `test.use()` calls around the test, outermost first, a later one
+ * winning key by key. The fixture keys (`fixtures`, `orderOptions`) are for the fixtures: see `effectiveFixtureUse`.
  */
-export declare function effectiveUse(test: RegisteredTestCase): Promise<UseOptions>;
+export declare function effectiveUse(test: RegisteredTestCase): Promise<GroupUse>;

package/dist/runner/use-options.js

@@ -1,18 +1,45 @@
 import { readConfig } from "../config/config.js";
+import { omitFixtureUse } from "../config/fixture-use.js";
+import { groupUseOf } from "../config/group-use.js";
+import { peekRunSettings } from "../config/run-settings.js";
 import { mergeUse, useOptionsOf } from "../config/use-options.js";
 import logger from "../logger/index.js";
 import { useOf } from "./suite.js";
-/**
- * The `use` options one test runs with: config `use`, then the `test.use()` calls around the test, outermost
- * first, a later one winning key by key
- */
-export async function effectiveUse(test) {
+/** The `use` layers of a test: config, then the run's environment, then the group it runs for, then `test.use()` */
+export async function useLayers(test) {
     let config;
+    let groups;
+    let environments;
     try {
         config = await readConfig("use");
+        groups = await readConfig("groups");
+        environments = await readConfig("environments");
     }
     catch (err) {
         logger.debug("Could not read use config, using defaults", { err });
     }
-    return mergeUse([useOptionsOf(config), ...useOf(test.suite)]);
+    const environment = peekRunSettings()?.environment;
+    return {
+        config: config ?? {},
+        environment: (environment !== undefined &&
+            Object.prototype.hasOwnProperty.call(environments ?? {}, environment) &&
+            environments?.[environment]?.use) ||
+            {},
+        group: test.group === undefined ? {} : groupUseOf(groups, test.group),
+        tests: useOf(test.suite),
+    };
+}
+/**
+ * The `use` options one test runs with: config `use`, then the `use` of the run's environment, then the `use` of
+ * the group the test runs for (if any), then the `test.use()` calls around the test, outermost first, a later one
+ * winning key by key. The fixture keys (`fixtures`, `orderOptions`) are for the fixtures: see `effectiveFixtureUse`.
+ */
+export async function effectiveUse(test) {
+    const layers = await useLayers(test);
+    return mergeUse([
+        useOptionsOf(layers.config),
+        omitFixtureUse(layers.environment),
+        omitFixtureUse(layers.group),
+        ...layers.tests.map((layer) => omitFixtureUse(layer)),
+    ]);
 }

package/dist/runner/wait-for-url.d.ts

@@ -0,0 +1,20 @@
+/** What to probe: an `http`/`https` URL, or a local port */
+export type ReadyTarget = {
+    url: string;
+    ignoreHTTPSErrors?: boolean;
+} | {
+    port: number;
+};
+/** One probe of `target` */
+export declare function answers(target: ReadyTarget): Promise<boolean>;
+/** The target as text for messages: the URL, or `localhost:<port>` */
+export declare function describeTarget(target: ReadyTarget): string;
+/**
+ * Probes `target` until it answers. Resolves "ready", or "timeout" after `timeout` ms, or "aborted" when `signal`
+ * fires or `stopped()` turns true (the caller saw the server die)
+ */
+export declare function waitUntilReady(target: ReadyTarget, options: {
+    timeout: number;
+    signal?: AbortSignal;
+    stopped?: () => boolean;
+}): Promise<"ready" | "timeout" | "aborted">;