@itmetsam/samurai-framework 0.21.3 → 0.21.5

package/dist/locator/element-reads.d.ts

@@ -3,6 +3,23 @@ import { type ActionabilityContext } from "./actionability.js";
 import { type ElementAccess } from "./element-access.js";
 /** Trimmed text content, or null when the element is missing */
 export declare function readTextContent(access: ElementAccess): Promise<string | null>;
+/** Rendered text (what a person would copy: line breaks, no hidden text), untrimmed, or null when the element is missing */
+export declare function readInnerText(access: ElementAccess): Promise<string | null>;
+/** The markup inside the element, or null when the element is missing */
+export declare function readInnerHTML(access: ElementAccess): Promise<string | null>;
+/** `textContent` of every match, as the page has it (untrimmed); an empty array when none match */
+export declare function readAllTextContents(access: ElementAccess): Promise<string[]>;
+/** `innerText` of every match; an empty array when none match */
+export declare function readAllInnerTexts(access: ElementAccess): Promise<string[]>;
+/** The element's box in CSS pixels from the viewport's top left */
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The element's box, or null when it is missing or not rendered (`display: none`, detached): it has no boxes then */
+export declare function readBoundingBox(access: ElementAccess): Promise<BoundingBox | null>;
 /** The accessible name (see `ACCESSIBLE_NAME_JS`), "" when it has none, or null when the element is missing */
 export declare function readAccessibleName(access: ElementAccess): Promise<string | null>;
 /** The accessible description, "" when it has none, or null when the element is missing */

package/dist/locator/element-reads.js

@@ -2,6 +2,7 @@ import { probeState } from "./actionability.js";
 import { callOnElement, callOnExistingElement, } from "./element-access.js";
 import { describeType } from "./element-state.js";
 import { ACCESSIBLE_NAME_JS } from "./accessible-name.js";
+import { evaluateOnAll } from "./evaluate.js";
 /** Body run in the page as `(el) => { ... }`: a checked checkbox or radio input, or `aria-checked="true"` */
 const IS_CHECKED_BODY = `
   const type = (el.getAttribute("type") || "").toLowerCase();
@@ -31,6 +32,36 @@ function stringOrNull(value) {
 export async function readTextContent(access) {
     return stringOrNull(await callOnElement(access, null, `return el.textContent.trim();`, [], [], "textContent"));
 }
+/** Rendered text (what a person would copy: line breaks, no hidden text), untrimmed, or null when the element is missing */
+export async function readInnerText(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.innerText;`, [], [], "innerText"));
+}
+/** The markup inside the element, or null when the element is missing */
+export async function readInnerHTML(access) {
+    return stringOrNull(await callOnElement(access, null, `return el.innerHTML;`, [], [], "innerHTML"));
+}
+/** `textContent` of every match, as the page has it (untrimmed); an empty array when none match */
+export function readAllTextContents(access) {
+    return evaluateOnAll(access, `(els) => els.map((el) => el.textContent ?? "")`, undefined);
+}
+/** `innerText` of every match; an empty array when none match */
+export function readAllInnerTexts(access) {
+    return evaluateOnAll(access, `(els) => els.map((el) => el.innerText ?? "")`, undefined);
+}
+/** The element's box, or null when it is missing or not rendered (`display: none`, detached): it has no boxes then */
+export async function readBoundingBox(access) {
+    const box = await callOnElement(access, null, `
+      if (el.getClientRects().length === 0) return null;
+      const { x, y, width, height } = el.getBoundingClientRect();
+      return { x, y, width, height };
+    `, [], [], "boundingBox");
+    if (box === null)
+        return null;
+    if (typeof box !== "object") {
+        throw new Error(`Expected to receive an object but instead received "${describeType(box)}"`);
+    }
+    return box;
+}
 /** The accessible name (see `ACCESSIBLE_NAME_JS`), "" when it has none, or null when the element is missing */
 export async function readAccessibleName(access) {
     return stringOrNull(await callOnElement(access, null, `${ACCESSIBLE_NAME_JS} return accessibleName(el);`, [], [], "accessibleName"));

package/dist/locator/evaluate.d.ts

@@ -0,0 +1,12 @@
+import { type PageFunction } from "../script/call-function.js";
+import type { ElementAccess } from "./element-access.js";
+/**
+ * Waits until the element is attached (hidden is fine), then calls `fn(element, arg)` in the page.
+ * A missing element ends in the usual timeout error; a strict locator throws when several match.
+ * What the page function throws reaches the caller unchanged (a `ScriptError`).
+ */
+export declare function evaluateOnElement<R, A>(access: ElementAccess, fn: PageFunction<[any, A], R>, arg: A | undefined, options?: {
+    timeout?: number;
+}): Promise<R>;
+/** Calls `fn(elements, arg)` in the page with every element the locator matches now (an empty array when none); does not wait */
+export declare function evaluateOnAll<R, A>(access: ElementAccess, fn: PageFunction<[any[], A], R>, arg: A | undefined): Promise<R>;

package/dist/locator/evaluate.js

@@ -0,0 +1,36 @@
+import { BiDiError } from "../transport/bidi-error.js";
+import { callFunction } from "../script/call-function.js";
+import { ATTACHED_ONLY } from "./page-scripts.js";
+/**
+ * Waits until the element is attached (hidden is fine), then calls `fn(element, arg)` in the page.
+ * A missing element ends in the usual timeout error; a strict locator throws when several match.
+ * What the page function throws reaches the caller unchanged (a `ScriptError`).
+ */
+export async function evaluateOnElement(access, fn, arg, options) {
+    await access.waitForActionable("evaluate", ATTACHED_ONLY, { scroll: false, hitTest: false }, options?.timeout === undefined ? undefined : { timeout: options.timeout });
+    const el = await access.requireElement();
+    try {
+        return await callFunction(access.connector, access.contextId, fn, arg === undefined ? [el] : [el, arg]);
+    }
+    catch (err) {
+        // The element went away between the search and the call
+        if (err instanceof BiDiError && err.code === "no such node")
+            throw access.noElementError();
+        throw err;
+    }
+}
+/** Calls `fn(elements, arg)` in the page with every element the locator matches now (an empty array when none); does not wait */
+export async function evaluateOnAll(access, fn, arg) {
+    // One more search when an element was removed between the search and the call
+    for (let attempt = 1;; attempt++) {
+        const elements = await access.resolveAll();
+        try {
+            return await callFunction(access.connector, access.contextId, fn, arg === undefined ? [elements] : [elements, arg]);
+        }
+        catch (err) {
+            if (attempt === 2 ||
+                !(err instanceof BiDiError && err.code === "no such node"))
+                throw err;
+        }
+    }
+}

package/dist/locator/locator.d.ts

@@ -1,10 +1,12 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 import type { BrowsingContext, ElementRectangle } from "../types/bidi-modules/browsing-context.js";
 import { ElementHandle } from "../script/element-handle.js";
+import type { PageFunction } from "../script/call-function.js";
 import type { ElementScreenshotOptions } from "../browser/screenshot.js";
 import type { FileInput } from "../browser/generated-files.js";
 import { type ActionOptions } from "./actionability.js";
 import { type CheckOptions } from "./check-actions.js";
+import { type BoundingBox } from "./element-reads.js";
 import type { WaitForState } from "./element-state.js";
 import type { HelperInstaller } from "./helper-realm.js";
 import { type StrictSource } from "./strict-mode.js";
@@ -197,6 +199,27 @@ export default class Locator {
     isHidden(): Promise<boolean>;
     /** Trimmed text content, or null when the element is missing */
     textContent(): Promise<string | null>;
+    /** Rendered text of the element (as a person would copy it, hidden text left out), untrimmed, or null when the element is missing */
+    innerText(): Promise<string | null>;
+    /** The markup inside the element, or null when the element is missing */
+    innerHTML(): Promise<string | null>;
+    /** `textContent` of every match, as the page has it (untrimmed, unlike `textContent()`); `[]` when none match. Does not wait */
+    allTextContents(): Promise<string[]>;
+    /** `innerText` of every match; `[]` when none match. Does not wait */
+    allInnerTexts(): Promise<string[]>;
+    /** The element's box in CSS pixels from the viewport's top left, or null when it is missing or not rendered (`display: none`). Does not wait or scroll */
+    boundingBox(): Promise<BoundingBox | null>;
+    /**
+     * Waits until the element is attached (hidden is fine), then calls `fn(element, arg)` in the page and returns the result
+     * (see `page.evaluate` for what comes back). `fn` is a function or the source of one; a strict locator throws when several match.
+     * @example
+     *  const id = await page.getByTestId("row").evaluate((el) => el.dataset.id);
+     */
+    evaluate<R = unknown, A = unknown>(fn: PageFunction<[any, A], R>, arg?: A, options?: {
+        timeout?: number;
+    }): Promise<R>;
+    /** Calls `fn(elements, arg)` in the page with an array of every match (empty when none; does not wait) and returns the result */
+    evaluateAll<R = unknown, A = unknown>(fn: PageFunction<[any[], A], R>, arg?: A): Promise<R>;
     /** Value of an input/textarea/select, or null when missing */
     inputValue(): Promise<string | null>;
     /** Attribute value, or null when the element or attribute is missing */

package/dist/locator/locator.js

@@ -4,7 +4,8 @@ import { setChecked } from "./check-actions.js";
 import { ChainResolver } from "./chain-resolver.js";
 import { callInPage, noElementError, requireElement, } from "./element-access.js";
 import { clickElement, fillElement, focusElement, pressOnElement, screenshotElement, } from "./element-actions.js";
-import { readAccessibleDescription, readAccessibleName, readAttribute, readBoundingClientRect, readClassAttribute, readCssValue, readEnabledState, readInputValue, readIsChecked, readIsEditable, readIsEnabled, readIsVisible, readTextContent, } from "./element-reads.js";
+import { readAccessibleDescription, readAccessibleName, readAllInnerTexts, readAllTextContents, readAttribute, readBoundingBox, readBoundingClientRect, readClassAttribute, readCssValue, readEnabledState, readInnerHTML, readInnerText, readInputValue, readIsChecked, readIsEditable, readIsEnabled, readIsVisible, readTextContent, } from "./element-reads.js";
+import { evaluateOnAll, evaluateOnElement } from "./evaluate.js";
 import { dropFiles, setInputFiles } from "./file-actions.js";
 import { DEFAULT_PAUSE_MS, pause } from "./input-actions.js";
 import { NOT_STRICT, strictViolation, } from "./strict-mode.js";
@@ -44,6 +45,7 @@ export default class Locator {
                 return locator.selector;
             },
             resolveOne: (method) => this.resolveOne(method),
+            resolveAll: () => this.resolve(),
             call: (fn, args, sandbox) => callInPage(this.access, fn, args, sandbox),
             waitForActionable: (action, checks, probe, options) => this.waitForActionable(action, checks, probe, options),
             requireElement: () => requireElement(this.access),
@@ -338,6 +340,39 @@ export default class Locator {
     async textContent() {
         return readTextContent(this.access);
     }
+    /** Rendered text of the element (as a person would copy it, hidden text left out), untrimmed, or null when the element is missing */
+    async innerText() {
+        return readInnerText(this.access);
+    }
+    /** The markup inside the element, or null when the element is missing */
+    async innerHTML() {
+        return readInnerHTML(this.access);
+    }
+    /** `textContent` of every match, as the page has it (untrimmed, unlike `textContent()`); `[]` when none match. Does not wait */
+    async allTextContents() {
+        return readAllTextContents(this.access);
+    }
+    /** `innerText` of every match; `[]` when none match. Does not wait */
+    async allInnerTexts() {
+        return readAllInnerTexts(this.access);
+    }
+    /** The element's box in CSS pixels from the viewport's top left, or null when it is missing or not rendered (`display: none`). Does not wait or scroll */
+    async boundingBox() {
+        return readBoundingBox(this.access);
+    }
+    /**
+     * Waits until the element is attached (hidden is fine), then calls `fn(element, arg)` in the page and returns the result
+     * (see `page.evaluate` for what comes back). `fn` is a function or the source of one; a strict locator throws when several match.
+     * @example
+     *  const id = await page.getByTestId("row").evaluate((el) => el.dataset.id);
+     */
+    async evaluate(fn, arg, options) {
+        return evaluateOnElement(this.access, fn, arg, options);
+    }
+    /** Calls `fn(elements, arg)` in the page with an array of every match (empty when none; does not wait) and returns the result */
+    async evaluateAll(fn, arg) {
+        return evaluateOnAll(this.access, fn, arg);
+    }
     /** Value of an input/textarea/select, or null when missing */
     async inputValue() {
         return readInputValue(this.access);

package/dist/logger/warn-once.d.ts

@@ -0,0 +1,4 @@
+/** Logs a warning the first time `key` is seen in this process; later calls with the same key do nothing */
+export declare function warnOnce(key: string, message: string): void;
+/** Forgets what was warned about (tests) */
+export declare function resetWarnOnce(): void;

package/dist/logger/warn-once.js

@@ -0,0 +1,13 @@
+import logger from "./index.js";
+const warned = new Set();
+/** Logs a warning the first time `key` is seen in this process; later calls with the same key do nothing */
+export function warnOnce(key, message) {
+    if (warned.has(key))
+        return;
+    warned.add(key);
+    logger.warn(message);
+}
+/** Forgets what was warned about (tests) */
+export function resetWarnOnce() {
+    warned.clear();
+}

package/dist/runner/attachments.d.ts

@@ -0,0 +1,16 @@
+/** What `testInfo.attach` takes besides the name */
+export interface AttachInput {
+    body?: string | Buffer;
+    path?: string;
+    contentType?: string;
+}
+/**
+ * Writes one attachment into `dir` and returns what to list: a body is saved under the cleaned name, a path is
+ * copied under it keeping its extension. `used` holds the file names taken so far; a repeat gets -2, -3, ...
+ * String bodies are masked like the rest of a report.
+ */
+export declare function saveAttachment(dir: string, used: Set<string>, name: string, input: AttachInput): Promise<{
+    name: string;
+    contentType: string;
+    path: string;
+}>;

package/dist/runner/attachments.js

@@ -0,0 +1,60 @@
+import { copyFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { cleanName } from "../browser/evidence.js";
+import { maskText } from "../config/mask.js";
+/** The file types an attachment is known by; the rest is `application/octet-stream` */
+const TYPES = {
+    ".txt": "text/plain",
+    ".log": "text/plain",
+    ".html": "text/html",
+    ".json": "application/json",
+    ".csv": "text/csv",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webm": "video/webm",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+};
+const OCTET = "application/octet-stream";
+/** The extension (with its dot) that stands for `contentType`, else `fallback` */
+function extensionOf(contentType, fallback) {
+    const found = Object.entries(TYPES).find(([, type]) => type === contentType);
+    return found ? found[0] : fallback;
+}
+/**
+ * Writes one attachment into `dir` and returns what to list: a body is saved under the cleaned name, a path is
+ * copied under it keeping its extension. `used` holds the file names taken so far; a repeat gets -2, -3, ...
+ * String bodies are masked like the rest of a report.
+ */
+export async function saveAttachment(dir, used, name, input) {
+    if (name === "")
+        throw new Error("attach(): name must not be empty");
+    const { body, path: from } = input;
+    if (body === undefined && from === undefined)
+        throw new Error("attach(): give either body or path");
+    if (body !== undefined && from !== undefined)
+        throw new Error("attach(): give either body or path, not both");
+    const fileExt = from !== undefined ? path.extname(from).toLowerCase() : "";
+    const contentType = input.contentType ??
+        (from !== undefined
+            ? (TYPES[fileExt] ?? OCTET)
+            : typeof body === "string"
+                ? "text/plain"
+                : OCTET);
+    const ext = fileExt !== ""
+        ? fileExt
+        : extensionOf(contentType, typeof body === "string" ? ".txt" : ".bin");
+    const base = cleanName(name);
+    let unique = base;
+    for (let n = 2; used.has(unique); n++)
+        unique = `${base}-${n}`;
+    used.add(unique);
+    const file = path.join(dir, `${unique}${ext}`);
+    await mkdir(dir, { recursive: true });
+    if (from !== undefined)
+        await copyFile(from, file);
+    else
+        await writeFile(file, typeof body === "string" ? maskText(body) : body);
+    return { name, contentType, path: file };
+}

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

@@ -0,0 +1,15 @@
+/** What a function asks for in the destructuring of its first parameter */
+export type Requested = {
+    kind: "names";
+    names: string[];
+    rest: boolean;
+}
+/** No destructuring pattern: the function takes the fixtures object whole, or none */
+ | {
+    kind: "opaque";
+};
+/**
+ * The fixture names a function destructures from its first parameter (`async ({ page, user }) => ...`), read
+ * from its source. A `...rest` entry asks for everything.
+ */
+export declare function requestedBy(fn: (...args: never[]) => unknown): Requested;

package/dist/runner/fixture-args.js

@@ -0,0 +1,95 @@
+const OPAQUE = { kind: "opaque" };
+/** Where the `}` or `)` that closes the bracket at `from` is, skipping strings; -1 when there is none */
+function closing(text, from) {
+    let depth = 0;
+    for (let i = from; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"' || c === "'" || c === "`") {
+            i = endOfString(text, i);
+            if (i < 0)
+                return -1;
+        }
+        else if (c === "{" || c === "(" || c === "[")
+            depth++;
+        else if (c === "}" || c === ")" || c === "]") {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function endOfString(text, from) {
+    const quote = text[from];
+    for (let i = from + 1; i < text.length; i++) {
+        if (text[i] === "\\")
+            i++;
+        else if (text[i] === quote)
+            return i;
+    }
+    return -1;
+}
+/** Splits at the commas that sit outside brackets and strings */
+function topLevelParts(text) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (c === '"' || c === "'" || c === "`") {
+            const end = endOfString(text, i);
+            if (end < 0)
+                break;
+            i = end;
+        }
+        else if (c === "{" || c === "(" || c === "[")
+            depth++;
+        else if (c === "}" || c === ")" || c === "]")
+            depth--;
+        else if (c === "," && depth === 0) {
+            parts.push(text.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(text.slice(start));
+    return parts.map((part) => part.trim()).filter((part) => part !== "");
+}
+/** The property a destructuring entry reads: `a`, `a: b`, `a = 1`, `"a-b": c`; undefined for a computed key */
+function keyOf(entry) {
+    const quoted = /^(["'])(.*?)\1/.exec(entry);
+    if (quoted)
+        return quoted[2];
+    return /^[\w$]+/.exec(entry)?.[0];
+}
+/**
+ * The fixture names a function destructures from its first parameter (`async ({ page, user }) => ...`), read
+ * from its source. A `...rest` entry asks for everything.
+ */
+export function requestedBy(fn) {
+    const text = Function.prototype.toString.call(fn);
+    if (/^(async\s+)?[\w$]+\s*=>/.test(text))
+        return OPAQUE;
+    const open = text.indexOf("(");
+    if (open < 0)
+        return OPAQUE;
+    let at = open + 1;
+    while (/\s/.test(text[at] ?? ""))
+        at++;
+    if (text[at] === ")")
+        return { kind: "names", names: [], rest: false };
+    if (text[at] !== "{")
+        return OPAQUE;
+    const end = closing(text, at);
+    if (end < 0)
+        return OPAQUE;
+    const names = [];
+    let rest = false;
+    for (const entry of topLevelParts(text.slice(at + 1, end))) {
+        const key = entry.startsWith("...") ? undefined : keyOf(entry);
+        if (key === undefined)
+            rest = true;
+        else
+            names.push(key);
+    }
+    return { kind: "names", names, rest };
+}

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

@@ -0,0 +1,22 @@
+/** 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 {
+    name: string;
+    auto: boolean;
+    deps: string[];
+    setup?: FixtureSetup;
+    value?: unknown;
+}
+/** Every custom fixture by name; the last definition of a name wins, the ones before it are what it may depend on by its own name */
+export type FixtureLayers = ReadonlyMap<string, readonly FixtureDef[]>;
+/** The fixtures the runner builds for every test: a custom fixture of the same name overrides it */
+export declare const BUILT_IN_FIXTURES: ReadonlySet<string>;
+/** Where a dependency of `name` (at definition `level`) comes from: another definition, or the built-in fixture */
+export declare function dependencyOf(layers: FixtureLayers, name: string, level: number, dep: string): {
+    name: string;
+    level: number;
+} | "built-in" | undefined;
+/** The fixtures after `test.extend(definitions)` on a test that has `base`; throws `extend(): ...` for a definition that cannot work */
+export declare function extendLayers(base: FixtureLayers | undefined, definitions: unknown): FixtureLayers;
+export {};

package/dist/runner/fixture-defs.js

@@ -0,0 +1,103 @@
+import { requestedBy } from "./fixture-args.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",
+    "browser",
+    "browserName",
+    "workerIndex",
+    "env",
+    "secrets",
+    "inputs",
+    "outputs",
+    "context",
+    "baseURL",
+    "testInfo",
+    "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 }];
+    if (typeof fixture !== "function")
+        return { name, auto: options.auto, deps: [], value: fixture };
+    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,
+        deps: requested.names,
+        setup: fixture,
+    };
+}
+/** 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)
+        return level > 0
+            ? { name, level: level - 1 }
+            : BUILT_IN_FIXTURES.has(dep)
+                ? "built-in"
+                : undefined;
+    const defs = layers.get(dep);
+    if (defs)
+        return { name: dep, level: defs.length - 1 };
+    return BUILT_IN_FIXTURES.has(dep) ? "built-in" : undefined;
+}
+/** Throws for a dependency nobody defines and for a cycle (`a` needs `b` needs `a`) */
+function validate(layers) {
+    const done = new Set();
+    const walk = (name, level, path) => {
+        const key = `${name}#${level}`;
+        if (done.has(key))
+            return;
+        if (path.includes(key)) {
+            const loop = [...path.slice(path.indexOf(key)), key];
+            throw new Error(`extend(): fixtures depend on each other in a circle: ${loop.map((k) => k.split("#")[0]).join(" -> ")}`);
+        }
+        const def = layers.get(name)?.[level];
+        if (!def)
+            return;
+        for (const dep of def.deps) {
+            const target = dependencyOf(layers, name, level, dep);
+            if (target === undefined)
+                throw new Error(`extend(): fixture "${name}" depends on unknown fixture "${dep}"`);
+            if (target !== "built-in")
+                walk(target.name, target.level, [...path, key]);
+        }
+        done.add(key);
+    };
+    for (const [name, defs] of layers)
+        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) {
+    if (!isPlainObject(definitions))
+        throw new Error("extend(): needs an object of fixtures");
+    const layers = new Map(base);
+    for (const [name, raw] of Object.entries(definitions))
+        layers.set(name, [...(layers.get(name) ?? []), definitionOf(name, raw)]);
+    validate(layers);
+    return layers;
+}

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

@@ -0,0 +1,33 @@
+import type { 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);
+}
+/**
+ * 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.
+ */
+export declare class FixtureScope {
+    private readonly layers;
+    private readonly base;
+    /** 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;
+    private readonly started;
+    private closed;
+    constructor(layers: FixtureLayers, base: TestFixtures);
+    /** Sets up the fixtures marked `auto` */
+    prepareAuto(): Promise<void>;
+    /** Sets up the custom fixtures `fn` destructures from its first parameter */
+    prepare(fn: (...args: never[]) => unknown): Promise<void>;
+    /**
+     * 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.
+     */
+    teardown(limitMs: number): Promise<Error | undefined>;
+    private ensure;
+    private setUp;
+}