@itmetsam/samurai-framework 0.21.5 → 0.22.0

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;
 }

package/dist/runner/registry.js

@@ -7,10 +7,11 @@ 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 +130,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) {

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 { 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;
 }
@@ -74,6 +83,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,
         });
     }
@@ -163,6 +172,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;
+}