@itmetsam/samurai-framework 0.22.0 → 0.22.1

package/dist/config/group-use.js

@@ -1,3 +1,4 @@
+import { isFixtureUseKey } from "./fixture-use.js";
 import { USE_OPTION_NAMES, validateUseOptions } from "./use-options.js";
 const isSize = (value) => typeof value === "number" && Number.isInteger(value) && value > 0;
 /** Rewrites `use(): locale must ...` as `config.groups[1].use.locale: locale must ...` */
@@ -7,34 +8,43 @@ function atGroup(place, err) {
     const problem = err.message.replace(/^use\(\): /, "");
     const name = /^(?:invalid |unknown )?(\w+)/.exec(problem)?.[1];
     const known = name !== undefined &&
-        (name === "viewport" || USE_OPTION_NAMES.includes(name));
+        (name === "viewport" ||
+            USE_OPTION_NAMES.includes(name) ||
+            isFixtureUseKey(name));
     throw new TypeError(`${place}${known ? `.${name}` : ""}: ${problem}`);
 }
+/** Checks one `use` of a group or an environment; throws `<place>.locale: what is wrong` */
+function validateUseAt(place, use) {
+    try {
+        const isObject = typeof use === "object" && use !== null && !Array.isArray(use);
+        const { viewport, ...options } = (isObject ? use : {});
+        // Anything but an object is refused here, with the message `test.use()` gives
+        validateUseOptions(isObject ? options : use);
+        if (viewport !== undefined &&
+            viewport !== null &&
+            !(isSize(viewport.width) && isSize(viewport.height)))
+            throw new TypeError(`viewport must be { width, height } with whole numbers above 0, or null, got ${JSON.stringify(viewport)}`);
+    }
+    catch (err) {
+        atGroup(place, err);
+    }
+}
 /**
- * Checks the `use` of every group of the config: the options of config `use` (`test.use()` ones, and `viewport`).
- * Throws `config.groups[1].use.locale: what is wrong`.
+ * Checks the `use` of every group of the config: the options of config `use` (`test.use()` ones, and `viewport`),
+ * and the fixture keys. Throws `config.groups[1].use.locale: what is wrong`.
  */
 export function validateGroupUse(config) {
     config.groups?.forEach((group, index) => {
-        if (group.use === undefined)
-            return;
-        const place = `config.groups[${index}].use`;
-        try {
-            const raw = group.use;
-            const isObject = typeof raw === "object" && raw !== null && !Array.isArray(raw);
-            const { viewport, ...options } = (isObject ? raw : {});
-            // Anything but an object is refused here, with the message `test.use()` gives
-            validateUseOptions(isObject ? options : raw);
-            if (viewport !== undefined &&
-                viewport !== null &&
-                !(isSize(viewport.width) && isSize(viewport.height)))
-                throw new TypeError(`viewport must be { width, height } with whole numbers above 0, or null, got ${JSON.stringify(viewport)}`);
-        }
-        catch (err) {
-            atGroup(place, err);
-        }
+        if (group.use !== undefined)
+            validateUseAt(`config.groups[${index}].use`, group.use);
     });
 }
+/** Checks the `use` of every environment the same way: `config.environments.production.use.locale: what is wrong` */
+export function validateEnvironmentUse(config) {
+    for (const [name, environment] of Object.entries(config.environments ?? {}))
+        if (environment?.use !== undefined)
+            validateUseAt(`config.environments.${name}.use`, environment.use);
+}
 /** The `use` of the group called `name`; nothing when there is no such group or it has none */
 export function groupUseOf(groups, name) {
     return groups?.find((group) => group.name === name)?.use ?? {};

package/dist/config/use-options.js

@@ -1,3 +1,4 @@
+import { checkFixtureUse, isFixtureUseKey } from "./fixture-use.js";
 /** The options of `use`: config, group, `test.use()` and (those that can change at run time) `page.use()` */
 export const USE_OPTION_NAMES = [
     "locale",
@@ -47,9 +48,12 @@ export function validateUseOptions(options, allowOthers = false) {
         const renamed = RENAMED[key];
         if (renamed !== undefined)
             fail(`unknown option "${key}"; use "${renamed}"`);
-        if (!allowOthers && !USE_OPTION_NAMES.includes(key))
+        if (!allowOthers &&
+            !USE_OPTION_NAMES.includes(key) &&
+            !isFixtureUseKey(key))
             fail(`unknown option "${key}"`);
     }
+    checkFixtureUse(options);
     const use = options;
     for (const name of BOOLEANS)
         if (use[name] !== undefined && typeof use[name] !== "boolean")

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

@@ -1,7 +1,8 @@
+import { type FixtureMeta } from "./fixture-meta.js";
 /** The function of a fixture: sets the value up, calls `use(value)`, cleans up after `use` returns */
 type FixtureSetup = (args: Record<string, unknown>, use: (value: unknown) => Promise<void>) => Promise<void>;
 /** One definition of a fixture: the value or the setup function, what it depends on, whether every test gets it */
-export interface FixtureDef {
+export interface FixtureDef extends FixtureMeta {
     name: string;
     auto: boolean;
     deps: string[];

package/dist/runner/fixture-defs.js

@@ -1,4 +1,5 @@
 import { requestedBy } from "./fixture-args.js";
+import { checkedOptions, OPTIONS_SUFFIX, } from "./fixture-meta.js";
 /** The fixtures the runner builds for every test: a custom fixture of the same name overrides it */
 export const BUILT_IN_FIXTURES = new Set([
     "page",
@@ -16,42 +17,50 @@ export const BUILT_IN_FIXTURES = new Set([
     "isMobile",
     "hasTouch",
 ]);
-const OPTION_KEYS = new Set(["auto", "scope"]);
 function isPlainObject(value) {
     if (typeof value !== "object" || value === null)
         return false;
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
-/** `[fixture, options]` is always a pair with options; an array value goes in a function */
-function checkedOptions(name, options) {
-    for (const key of Object.keys(options))
-        if (!OPTION_KEYS.has(key))
-            throw new Error(`extend(): fixture "${name}" has an unknown option "${key}"`);
-    if (options.auto !== undefined && typeof options.auto !== "boolean")
-        throw new Error(`extend(): fixture "${name}": auto must be true or false`);
-    if (options.scope === "worker")
-        throw new Error(`extend(): fixture "${name}" has scope "worker", which is not supported; fixtures live as long as one test ({ scope: "test" })`);
-    if (options.scope !== undefined && options.scope !== "test")
-        throw new Error(`extend(): fixture "${name}": scope must be "test"`);
-    return { auto: options.auto === true };
-}
 function definitionOf(name, raw) {
     const [fixture, options] = Array.isArray(raw) && raw.length === 2 && isPlainObject(raw[1])
         ? [raw[0], checkedOptions(name, raw[1])]
-        : [raw, { auto: false }];
+        : [raw, checkedOptions(name, {})];
+    const { auto, meta } = options;
+    checkOptionFixture(name, fixture, meta);
     if (typeof fixture !== "function")
-        return { name, auto: options.auto, deps: [], value: fixture };
+        return { name, auto, deps: [], value: fixture, ...meta };
     const requested = requestedBy(fixture);
     if (requested.kind === "opaque" || requested.rest)
         throw new Error(`extend(): fixture "${name}" must destructure the fixtures it uses in its first argument, as ({ page }, use) or ({}, use)`);
     return {
         name,
-        auto: options.auto,
+        auto,
         deps: requested.names,
         setup: fixture,
+        ...meta,
     };
 }
+/** `option: true` and `fields` go together with a name ending in `Options` and a plain object as the value */
+function checkOptionFixture(name, fixture, meta) {
+    const suffixed = name.endsWith(OPTIONS_SUFFIX) && name !== OPTIONS_SUFFIX;
+    if (!meta.option) {
+        if (meta.fields)
+            throw new Error(suffixed
+                ? `extend(): fixture "${name}" has fields but option is not true`
+                : `extend(): fixture "${name}" has fields but is not an option fixture; put them on "${name}${OPTIONS_SUFFIX}" (option: true)`);
+        return;
+    }
+    if (!suffixed)
+        throw new Error(`extend(): fixture "${name}" is an option fixture, so its name must end in "${OPTIONS_SUFFIX}"`);
+    if (typeof fixture === "function")
+        throw new Error(`extend(): option fixture "${name}" must be a plain object, not a function`);
+    if (!isPlainObject(fixture))
+        throw new Error(`extend(): option fixture "${name}" must be a plain object`);
+}
+/** The name of the fixture an option fixture belongs to */
+const fixtureOf = (optionName) => optionName.slice(0, -OPTIONS_SUFFIX.length);
 /** Where a dependency of `name` (at definition `level`) comes from: another definition, or the built-in fixture */
 export function dependencyOf(layers, name, level, dep) {
     if (dep === name)
@@ -65,6 +74,25 @@ export function dependencyOf(layers, name, level, dep) {
         return { name: dep, level: defs.length - 1 };
     return BUILT_IN_FIXTURES.has(dep) ? "built-in" : undefined;
 }
+/** The built-in fixtures a worker fixture may use: those that do not belong to one test or one page */
+const WORKER_BUILT_INS = new Set([
+    "browserName",
+    "workerIndex",
+    "env",
+    "secrets",
+    "baseURL",
+]);
+/** A worker fixture outlives every test: it may use the run's values, other worker fixtures and plain values */
+function checkWorkerDependency(layers, def, dep, target) {
+    if (target === "built-in") {
+        if (!WORKER_BUILT_INS.has(dep))
+            throw new Error(`extend(): worker fixture "${def.name}" cannot use "${dep}"; it lives longer than one test (it may use ${[...WORKER_BUILT_INS].join(", ")}, other worker fixtures and values)`);
+        return;
+    }
+    const used = target && layers.get(target.name)?.[target.level];
+    if (used && used.scope !== "worker" && used.setup)
+        throw new Error(`extend(): worker fixture "${def.name}" cannot use the test-scoped fixture "${dep}"`);
+}
 /** Throws for a dependency nobody defines and for a cycle (`a` needs `b` needs `a`) */
 function validate(layers) {
     const done = new Set();
@@ -83,14 +111,19 @@ function validate(layers) {
             const target = dependencyOf(layers, name, level, dep);
             if (target === undefined)
                 throw new Error(`extend(): fixture "${name}" depends on unknown fixture "${dep}"`);
+            if (def.scope === "worker")
+                checkWorkerDependency(layers, def, dep, target);
             if (target !== "built-in")
                 walk(target.name, target.level, [...path, key]);
         }
         done.add(key);
     };
-    for (const [name, defs] of layers)
+    for (const [name, defs] of layers) {
+        if (defs[defs.length - 1]?.option && !layers.has(fixtureOf(name)))
+            throw new Error(`extend(): option fixture "${name}" has no fixture "${fixtureOf(name)}"`);
         for (let level = 0; level < defs.length; level++)
             walk(name, level, []);
+    }
 }
 /** The fixtures after `test.extend(definitions)` on a test that has `base`; throws `extend(): ...` for a definition that cannot work */
 export function extendLayers(base, definitions) {

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

@@ -0,0 +1,20 @@
+import type { FixtureField, FixtureOutput } from "../types/extend.js";
+/** What a fixture's options say besides `auto`: its scope, and the metadata the app's catalog and the report use */
+export interface FixtureMeta {
+    scope: "test" | "worker";
+    label?: string;
+    icon?: string;
+    description?: string;
+    outputs?: FixtureOutput[];
+    timeout?: number;
+    /** The fixture is the options of the fixture named without the `Options` suffix */
+    option: boolean;
+    fields?: FixtureField[];
+}
+/** The suffix that pairs an option fixture with its fixture: `order` reads `orderOptions` */
+export declare const OPTIONS_SUFFIX = "Options";
+/** Checks the options of `[fixture, options]` and returns what the definition keeps; throws `extend(): ...` */
+export declare function checkedOptions(name: string, options: Record<string, unknown>): {
+    auto: boolean;
+    meta: FixtureMeta;
+};

package/dist/runner/fixture-meta.js

@@ -0,0 +1,109 @@
+/** The suffix that pairs an option fixture with its fixture: `order` reads `orderOptions` */
+export const OPTIONS_SUFFIX = "Options";
+const OPTION_KEYS = new Set([
+    "auto",
+    "scope",
+    "label",
+    "icon",
+    "description",
+    "outputs",
+    "timeout",
+    "option",
+    "fields",
+]);
+const FIELD_TYPES = [
+    "text",
+    "code",
+    "expression",
+    "number",
+    "select",
+    "segmented",
+    "switch",
+    "secret",
+    "variable",
+];
+const fail = (name, problem) => {
+    throw new Error(`extend(): fixture "${name}": ${problem}`);
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function checkOutputs(name, outputs) {
+    if (!Array.isArray(outputs))
+        return fail(name, "outputs must be an array");
+    const seen = new Set();
+    for (const output of outputs) {
+        if (!isObject(output) ||
+            typeof output.name !== "string" ||
+            output.name === "")
+            fail(name, "every output needs a name");
+        const { name: key, label, secret } = output;
+        if (seen.has(key))
+            fail(name, `output "${key}" is listed twice`);
+        seen.add(key);
+        if (label !== undefined && typeof label !== "string")
+            fail(name, `output "${key}": label must be a string`);
+        if (secret !== undefined && typeof secret !== "boolean")
+            fail(name, `output "${key}": secret must be true or false`);
+    }
+    return outputs;
+}
+function checkFields(name, fields) {
+    if (!Array.isArray(fields))
+        return fail(name, "fields must be an array");
+    const seen = new Set();
+    for (const field of fields) {
+        if (!isObject(field) || typeof field.path !== "string" || field.path === "")
+            fail(name, "every field needs a path");
+        const { path, type, options } = field;
+        if (!FIELD_TYPES.includes(type))
+            fail(name, `field "${path}" has an unknown type ${JSON.stringify(type)}`);
+        if (seen.has(path))
+            fail(name, `field "${path}" is listed twice`);
+        seen.add(path);
+        if ((type === "select" || type === "segmented") && !Array.isArray(options))
+            fail(name, `field "${path}" needs options`);
+    }
+    return fields;
+}
+/** Checks the options of `[fixture, options]` and returns what the definition keeps; throws `extend(): ...` */
+export function checkedOptions(name, options) {
+    for (const key of Object.keys(options))
+        if (!OPTION_KEYS.has(key))
+            throw new Error(`extend(): fixture "${name}" has an unknown option "${key}"`);
+    if (options.auto !== undefined && typeof options.auto !== "boolean")
+        fail(name, "auto must be true or false");
+    if (options.scope !== undefined &&
+        !["test", "worker"].includes(options.scope))
+        fail(name, 'scope must be "test" or "worker"');
+    if (options.label !== undefined && typeof options.label !== "string")
+        fail(name, "label must be a string");
+    if (options.icon !== undefined &&
+        (typeof options.icon !== "string" || options.icon === ""))
+        fail(name, "icon must be a non-empty string");
+    if (options.description !== undefined &&
+        typeof options.description !== "string")
+        fail(name, "description must be a string");
+    if (options.timeout !== undefined &&
+        !(typeof options.timeout === "number" && options.timeout > 0))
+        fail(name, "timeout must be a number of milliseconds above 0");
+    if (options.option !== undefined && typeof options.option !== "boolean")
+        fail(name, "option must be true or false");
+    const meta = {
+        scope: options.scope === "worker" ? "worker" : "test",
+        option: options.option === true,
+        ...(options.label !== undefined && { label: options.label }),
+        ...(options.icon !== undefined && { icon: options.icon }),
+        ...(options.description !== undefined && {
+            description: options.description,
+        }),
+        ...(options.timeout !== undefined && {
+            timeout: options.timeout,
+        }),
+        ...(options.outputs !== undefined && {
+            outputs: checkOutputs(name, options.outputs),
+        }),
+        ...(options.fields !== undefined && {
+            fields: checkFields(name, options.fields),
+        }),
+    };
+    return { auto: options.auto === true, meta };
+}

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

@@ -0,0 +1,8 @@
+import type { TestFixtures } from "../types/test.js";
+import type { FixtureDef } from "./fixture-defs.js";
+/**
+ * The value an option fixture gives: its default with the values from `use` over it, key by key. A field of type
+ * `secret` holds the name of a secret and one of type `variable` the name of a variable; they are replaced by the
+ * secret's or the variable's value here, so the fixture never sees the name.
+ */
+export declare function resolveOptions(def: FixtureDef, fromUse: Readonly<Record<string, unknown>> | undefined, base: Pick<TestFixtures, "env" | "secrets">): Record<string, unknown>;

package/dist/runner/fixture-options.js

@@ -0,0 +1,35 @@
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** The object at `path` (dots go into objects) and the last key, or nothing when the path leads nowhere */
+function parentOf(value, path) {
+    const keys = path.split(".");
+    let parent = value;
+    for (const key of keys.slice(0, -1)) {
+        const next = parent[key];
+        if (!isObject(next))
+            return undefined;
+        parent = next;
+    }
+    return { parent, key: keys[keys.length - 1] };
+}
+/**
+ * The value an option fixture gives: its default with the values from `use` over it, key by key. A field of type
+ * `secret` holds the name of a secret and one of type `variable` the name of a variable; they are replaced by the
+ * secret's or the variable's value here, so the fixture never sees the name.
+ */
+export function resolveOptions(def, fromUse, base) {
+    const merged = structuredClone({
+        ...def.value,
+        ...fromUse,
+    });
+    for (const field of def.fields ?? []) {
+        if (field.type !== "secret" && field.type !== "variable")
+            continue;
+        const place = parentOf(merged, field.path);
+        const name = place?.parent[place.key];
+        if (!place || typeof name !== "string" || name === "")
+            continue;
+        place.parent[place.key] =
+            field.type === "secret" ? base.secrets[name] : base.env[name];
+    }
+    return merged;
+}

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

@@ -0,0 +1,11 @@
+import type { FixtureDef } from "./fixture-defs.js";
+/** A value as the report lists it */
+type OutputValue = string | number | boolean;
+/**
+ * The declared outputs of a fixture that the report and the app may show: the non-secret keys of its value.
+ * Throws when a declared output is not a string, a number or a boolean (the value must be a flat record).
+ */
+export declare function outputsOf(def: FixtureDef, value: unknown): Record<string, OutputValue> | undefined;
+/** JSON with the keys of every object in order, so equal options give equal text */
+export declare function stableJson(value: unknown): string;
+export {};

package/dist/runner/fixture-outputs.js

@@ -0,0 +1,28 @@
+/**
+ * The declared outputs of a fixture that the report and the app may show: the non-secret keys of its value.
+ * Throws when a declared output is not a string, a number or a boolean (the value must be a flat record).
+ */
+export function outputsOf(def, value) {
+    const shown = (def.outputs ?? []).filter((output) => !output.secret);
+    if (shown.length === 0)
+        return undefined;
+    const record = typeof value === "object" && value !== null
+        ? value
+        : {};
+    const outputs = {};
+    for (const { name } of shown) {
+        const output = record[name];
+        if (typeof output !== "string" &&
+            typeof output !== "number" &&
+            typeof output !== "boolean")
+            throw new Error(`output "${name}" must be a string, number or boolean`);
+        outputs[name] = output;
+    }
+    return outputs;
+}
+/** JSON with the keys of every object in order, so equal options give equal text */
+export function stableJson(value) {
+    return JSON.stringify(value, (_key, item) => typeof item === "object" && item !== null && !Array.isArray(item)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)))
+        : item);
+}

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

@@ -0,0 +1,35 @@
+import type { FixtureField, FixtureOutput } from "../types/extend.js";
+import { type FixtureLayers } from "./fixture-defs.js";
+/** Remembers the fixtures of an extended `test`, so `config.fixtures` can be read without running a test */
+export declare function rememberLayers(test: object, layers: FixtureLayers): void;
+/** The fixtures of an extended `test`; nothing for the plain one */
+export declare const layersOf: (test: object) => FixtureLayers | undefined;
+/** What the app and the CLI show of one fixture of a project, read without running a test */
+export interface FixtureCatalogEntry {
+    name: string;
+    /** The `label` option, else the name */
+    label: string;
+    icon?: string;
+    description?: string;
+    scope: "test" | "worker";
+    /** Set up for every test */
+    auto: boolean;
+    /** The name is a built-in fixture's: this one replaces it */
+    overridesBuiltIn: boolean;
+    /** The fixtures it destructures, built-in ones included */
+    dependencies: string[];
+    /** The `<name>Options` fixture: its form, and its values when `use` sets none */
+    options?: {
+        name: string;
+        fields: FixtureField[];
+        defaults: Record<string, unknown>;
+    };
+    /** The declared keys of its value, without the secret ones */
+    outputs?: FixtureOutput[];
+}
+/**
+ * The catalog of the fixtures in `config.fixtures`, read from the extended tests without running anything. Throws
+ * `config.fixtures: ...` for a list entry that is not an extended test, a name that does not match
+ * `/^[a-z][A-Za-z0-9]*$/` and a name defined in two places.
+ */
+export declare function fixtureCatalog(tests: readonly unknown[]): FixtureCatalogEntry[];

package/dist/runner/fixture-registry.js

@@ -0,0 +1,73 @@
+import { BUILT_IN_FIXTURES, } from "./fixture-defs.js";
+/** The fixtures each `test.extend()` result carries; the test function itself holds nothing a config could read */
+const layersByTest = new WeakMap();
+/** Remembers the fixtures of an extended `test`, so `config.fixtures` can be read without running a test */
+export function rememberLayers(test, layers) {
+    layersByTest.set(test, layers);
+}
+/** The fixtures of an extended `test`; nothing for the plain one */
+export const layersOf = (test) => layersByTest.get(test);
+const NAME = /^[a-z][A-Za-z0-9]*$/;
+const fail = (problem) => {
+    throw new Error(`config.fixtures: ${problem}`);
+};
+/** The last definition of every name in the listed tests, with the place of the first test that has it */
+function collect(tests) {
+    const found = new Map();
+    tests.forEach((test, index) => {
+        const layers = (typeof test === "function" ||
+            (typeof test === "object" && test !== null)) &&
+            layersByTest.has(test)
+            ? layersByTest.get(test)
+            : undefined;
+        if (layers === undefined &&
+            !(typeof test === "function" && "extend" in test))
+            throw new Error(`config.fixtures[${index}] is not a test (use the result of test.extend())`);
+        for (const [name, defs] of layers ?? []) {
+            const def = defs[defs.length - 1];
+            const earlier = found.get(name);
+            if (earlier && earlier.def !== def)
+                fail(`fixture "${name}" is defined twice (config.fixtures[${earlier.index}] and config.fixtures[${index}])`);
+            if (!earlier)
+                found.set(name, { def, index });
+        }
+    });
+    return new Map([...found].map(([name, { def }]) => [name, def]));
+}
+/**
+ * The catalog of the fixtures in `config.fixtures`, read from the extended tests without running anything. Throws
+ * `config.fixtures: ...` for a list entry that is not an extended test, a name that does not match
+ * `/^[a-z][A-Za-z0-9]*$/` and a name defined in two places.
+ */
+export function fixtureCatalog(tests) {
+    if (!Array.isArray(tests))
+        throw new Error("config.fixtures must be an array");
+    const defs = collect(tests);
+    for (const name of defs.keys())
+        if (!NAME.test(name))
+            fail(`fixture name "${name}" must match ${NAME} (letters and digits, starting with a lower-case letter)`);
+    return [...defs.values()]
+        .filter((def) => !def.option)
+        .map((def) => {
+        const option = defs.get(`${def.name}Options`);
+        const outputs = def.outputs?.filter((output) => !output.secret);
+        return {
+            name: def.name,
+            label: def.label ?? def.name,
+            ...(def.icon !== undefined && { icon: def.icon }),
+            ...(def.description !== undefined && { description: def.description }),
+            scope: def.scope,
+            auto: def.auto,
+            overridesBuiltIn: BUILT_IN_FIXTURES.has(def.name),
+            dependencies: def.deps,
+            ...(option?.option && {
+                options: {
+                    name: option.name,
+                    fields: option.fields ?? [],
+                    defaults: { ...option.value },
+                },
+            }),
+            ...(outputs && outputs.length > 0 && { outputs }),
+        };
+    });
+}

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

@@ -1,33 +1,63 @@
-import type { TestFixtures } from "../types/test.js";
+import type { TestFixtureEntry, TestFixtures } from "../types/test.js";
 import { type FixtureLayers } from "./fixture-defs.js";
-/** A custom fixture whose setup threw or never called `use` */
-export declare class FixtureSetupError extends Error {
-    constructor(name: string, cause: unknown);
+import { WorkerFixtures } from "./fixture-worker.js";
+/** What `use` and the run's environment say about the fixtures of one test */
+export interface ScopeRun {
+    /** Fixtures to set up with the `auto` ones */
+    attach?: readonly string[];
+    /** The values of the option fixtures from `use`, by option fixture name */
+    options?: Readonly<Record<string, Record<string, unknown>>>;
+    /** Fixtures the environment turns off, with the reason a test that needs one is skipped for */
+    disabled?: ReadonlyMap<string, string>;
+    /** The worker's fixtures, where worker-scoped ones live. Without it they live as long as this scope */
+    workers?: WorkerFixtures;
+    /** The run's environment: a worker fixture is shared only within one environment */
+    environment?: string;
 }
 /**
  * The custom fixtures of one test run. Fixtures are set up when a test or hook asks for them (by destructuring
  * them), their dependencies first, and torn down in the opposite order. The hooks and the body of a test share
- * one scope, so they see the same instances.
+ * one scope, so they see the same instances. Worker-scoped fixtures come from the worker's `WorkerFixtures`.
  */
 export declare class FixtureScope {
     private readonly layers;
     private readonly base;
+    private readonly run;
     /** The built-in fixtures, with each custom fixture added (replacing a built-in of that name) once it is set up */
     readonly fixtures: TestFixtures;
     private readonly values;
     private readonly pending;
+    /** What was set up for this test, last in the order it is torn down */
     private readonly started;
+    /** The key of each worker fixture set up here, which the fixtures that use it build theirs from */
+    private readonly keys;
+    private readonly entries;
+    private readonly entryOf;
+    private readonly workers;
+    private readonly ownsWorkers;
     private closed;
-    constructor(layers: FixtureLayers, base: TestFixtures);
-    /** Sets up the fixtures marked `auto` */
+    constructor(layers: FixtureLayers, base: TestFixtures, run?: ScopeRun);
+    /** Sets up the fixtures marked `auto`, then those `use` attaches */
     prepareAuto(): Promise<void>;
     /** Sets up the custom fixtures `fn` destructures from its first parameter */
     prepare(fn: (...args: never[]) => unknown): Promise<void>;
+    /** The fixtures this test set up, in the order they were set up, with how each went so far */
+    report(): TestFixtureEntry[];
     /**
-     * Finishes the fixtures that were set up, last first, each within `limitMs`. Returns the first error (a
-     * fixture's cleanup threw or ran out of time); the others still run.
+     * Finishes the fixtures that were set up, last first, each within its own `timeout` else `limitMs`. Returns the
+     * first error (a fixture's cleanup threw or ran out of time); the others still run. The worker fixtures of a
+     * scope that has no worker are finished too.
      */
     teardown(limitMs: number): Promise<Error | undefined>;
     private ensure;
     private setUp;
+    /** Runs the setup function of `def` (for this test, or through the worker) and records how it went */
+    private instantiate;
+    /** Starts the setup of `def` until it calls `use`, and checks the declared outputs of the value */
+    private make;
+    /**
+     * What makes one instance of a worker fixture different from another: the environment, the values of the
+     * option fixtures it reads, the instances of the worker fixtures it uses and the built-ins that differ
+     */
+    private workerKey;
 }