@itmetsam/samurai-framework 0.22.0 → 0.22.2

package/dist/config/fixture-use.js

@@ -0,0 +1,44 @@
+/** The key of `use` that attaches fixtures by name (`true`) or removes them (`false`) */
+export const FIXTURES_KEY = "fixtures";
+const OPTION_FIXTURE_KEY = /^[a-z][A-Za-z0-9]*Options$/;
+/** Whether `key` of a `use` object is about fixtures: `fixtures`, or an option fixture (`orderOptions`) */
+export function isFixtureUseKey(key) {
+    return key === FIXTURES_KEY || OPTION_FIXTURE_KEY.test(key);
+}
+/** The fixture keys of one `use` layer */
+export function pickFixtureUse(layer) {
+    return Object.fromEntries(Object.entries(layer ?? {}).filter(([key]) => isFixtureUseKey(key)));
+}
+/** The layer without its fixture keys: what is left is for the browser */
+export function omitFixtureUse(layer) {
+    return Object.fromEntries(Object.entries(layer ?? {}).filter(([key]) => !isFixtureUseKey(key)));
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Checks the fixture keys of one `use` layer; throws `use(): what is wrong` */
+export function checkFixtureUse(options) {
+    const attached = options[FIXTURES_KEY];
+    if (attached !== undefined) {
+        if (!isObject(attached))
+            throw new TypeError("use(): fixtures must be an object of fixture names and true or false");
+        for (const [name, on] of Object.entries(attached))
+            if (typeof on !== "boolean")
+                throw new TypeError(`use(): fixtures.${name} must be true or false, got ${JSON.stringify(on)}`);
+    }
+    for (const [key, value] of Object.entries(options))
+        if (key !== FIXTURES_KEY && isFixtureUseKey(key) && !isObject(value))
+            throw new TypeError(`use(): ${key} must be an object`);
+}
+/** Merges the fixture keys of the `use` layers in order (config, environment, group, `test.use()`) */
+export function mergeFixtureUse(layers) {
+    const merged = { fixtures: {}, options: {} };
+    for (const layer of layers)
+        for (const [key, value] of Object.entries(pickFixtureUse(layer)))
+            if (key === FIXTURES_KEY)
+                Object.assign(merged.fixtures, value);
+            else
+                merged.options[key] = {
+                    ...merged.options[key],
+                    ...value,
+                };
+    return merged;
+}

package/dist/config/group-use.d.ts

@@ -1,8 +1,10 @@
 import type { GroupUse, SamuraiGroup, SamuraiTestConfig } from "../types/config.js";
 /**
- * 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 declare function validateGroupUse(config: SamuraiTestConfig): void;
+/** Checks the `use` of every environment the same way: `config.environments.production.use.locale: what is wrong` */
+export declare function validateEnvironmentUse(config: SamuraiTestConfig): void;
 /** The `use` of the group called `name`; nothing when there is no such group or it has none */
 export declare function groupUseOf(groups: readonly SamuraiGroup[] | undefined, name: string): GroupUse;

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/recorder/capture.d.ts

@@ -7,6 +7,9 @@
  *
  * - `{ type: "click", target, candidates, unique, textEntry }`: a click, retargeted to the nearest interactive
  *   element (a label click reports its control; the click the browser forwards to the control is dropped).
+ *   On a checkbox or radio it also carries `checked`, the state the click leaves.
+ * - `{ type: "select", target, candidates, option }`: a trusted `change` of a single-choice `<select>`; `option` is
+ *   `{ value }`, else `{ label }`, else `{ index }` of the chosen option.
  * - `{ type: "input", target, candidates, value, secret, secretName }`: text typed into a field. Password
  *   values never leave the page: `secret` is set and `value` is left out.
  * - `{ type: "press", target, candidates, unique, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a

package/dist/recorder/capture.js

@@ -14,6 +14,9 @@ const RUN_KEY = "samurai.recorder.run";
  *
  * - `{ type: "click", target, candidates, unique, textEntry }`: a click, retargeted to the nearest interactive
  *   element (a label click reports its control; the click the browser forwards to the control is dropped).
+ *   On a checkbox or radio it also carries `checked`, the state the click leaves.
+ * - `{ type: "select", target, candidates, option }`: a trusted `change` of a single-choice `<select>`; `option` is
+ *   `{ value }`, else `{ label }`, else `{ index }` of the chosen option.
  * - `{ type: "input", target, candidates, value, secret, secretName }`: text typed into a field. Password
  *   values never leave the page: `secret` is set and `value` is left out.
  * - `{ type: "press", target, candidates, unique, pressed }`: Enter, Tab or Escape (Enter in a button, link or textarea is a
@@ -76,7 +79,21 @@ export const CAPTURE_SOURCE = String.raw `(send) => {
     if (event.detail === 0 && el.form && el.form === lastEnter.form && now - lastEnter.at < 150) return;
     lastClick = { el, at: now };
     const candidates = candidatesOf(el);
-    report({ type: "click", target: el, candidates, unique: uniqueOf(el, candidates), textEntry: isTextEntry(el) });
+    // A checkbox or radio click is a check or an uncheck, by the state it leaves: the browser has already flipped a
+    // control that is the click's own target, while a label's click flips its control only after this listener
+    const checkable = el.tagName === "INPUT" && (el.type === "checkbox" || el.type === "radio");
+    const checked = checkable ? (el.type === "radio" ? true : event.target === el ? el.checked : !el.checked) : undefined;
+    report({ type: "click", target: el, candidates, unique: uniqueOf(el, candidates), textEntry: isTextEntry(el), ...(checked !== undefined && { checked }) });
+  }, true);
+
+  // A choice in a <select> (one that takes a single option; several are a list, which stays custom code)
+  document.addEventListener("change", (event) => {
+    if (inToolbar(event)) return;
+    const el = event.target;
+    if (off() || !event.isTrusted || !(el instanceof HTMLSelectElement) || el.multiple || !el.selectedOptions.length) return;
+    const chosen = el.selectedOptions[0];
+    const option = chosen.value !== "" ? { value: chosen.value } : chosen.label !== "" ? { label: chosen.label } : { index: chosen.index };
+    report({ type: "select", target: el, candidates: candidatesOf(el), option });
   }, true);
 
   document.addEventListener("input", (event) => {

package/dist/recorder/normalise.d.ts

@@ -1,4 +1,4 @@
-import type { Expectation, FileEntry, LocatorSpec, PageExpectation, Step, TestInput } from "../steps/model.js";
+import type { Expectation, FileEntry, LocatorSpec, PageExpectation, SelectChoice, Step, TestInput } from "../steps/model.js";
 /** What the recorder does to the step list: a new step at `index`, a step rewritten in place, or one taken out */
 export type RecorderEvent = 
 /** `declare`: an input the step reads, declared with its default before the step goes in */
@@ -21,6 +21,15 @@ export type Observation = {
     key: string;
     locator: LocatorSpec;
     textEntry: boolean;
+    /** Of a checkbox or radio: whether the click leaves it checked. Recorded as `check` or `uncheck` */
+    checked?: boolean;
+}
+/** A `<select>` changed to this option */
+ | {
+    type: "select";
+    key: string;
+    locator: LocatorSpec;
+    option: SelectChoice;
 } | {
     type: "input";
     key: string;
@@ -143,6 +152,8 @@ export declare class Normaliser {
     private pickerCancelled;
     private filesSet;
     private clicked;
+    /** A choice in a `<select>`; the click that opened it, just before, is the same step */
+    private selected;
     private pressed;
     /** An Alt+click */
     private asserted;

package/dist/recorder/normalise.js

@@ -105,6 +105,8 @@ export class Normaliser {
                 return this.filesSet(observation, at);
             case "click":
                 return this.clicked(observation, at);
+            case "select":
+                return this.selected(observation, at);
             case "press":
                 return this.pressed(observation, at);
             case "assert":
@@ -163,12 +165,38 @@ export class Normaliser {
             return []; // focusing a field: the fill that follows needs no click
         this.lastFill = undefined;
         this.lastAction = at;
+        if (observation.checked !== undefined)
+            return [
+                this.insert({
+                    kind: observation.checked ? "check" : "uncheck",
+                    locator: observation.locator,
+                }),
+            ];
         const events = [
             this.insert({ kind: "click", locator: observation.locator }),
         ];
-        this.lastClick = { index: this.next - 1, at };
+        this.lastClick = { index: this.next - 1, at, key: observation.key };
         return events;
     }
+    /** A choice in a `<select>`; the click that opened it, just before, is the same step */
+    selected(observation, at) {
+        this.lastFill = undefined;
+        this.lastAction = at;
+        const step = {
+            kind: "selectOption",
+            locator: observation.locator,
+            option: observation.option,
+        };
+        const click = this.lastClick;
+        if (click &&
+            click.key === observation.key &&
+            click.index === this.next - 1) {
+            this.lastClick = undefined;
+            this.lastStep = step;
+            return [{ op: "replace", index: click.index, step }];
+        }
+        return [this.insert(step)];
+    }
     pressed(observation, at) {
         // The page may react by clearing the field: what is typed next is a new fill, not a rewrite of this one
         this.lastFill = undefined;

package/dist/recorder/page-messages.d.ts

@@ -1,5 +1,5 @@
 import type { ElementHandle } from "../script/element-handle.js";
-import type { LocatorCall, LocatorSpec } from "../steps/model.js";
+import type { LocatorCall, LocatorSpec, SelectChoice } from "../steps/model.js";
 import type { Observation } from "./normalise.js";
 /** What the files capture script sends */
 export type FilesMessage = {
@@ -20,12 +20,16 @@ export type FilesMessage = {
 };
 /** What the capture script sends */
 export interface PageMessage {
-    type: "click" | "input" | "press" | "assert";
+    type: "click" | "input" | "press" | "assert" | "select";
     target: ElementHandle;
     candidates: LocatorCall[];
     /** Of a click or press: the candidates that matched only the target when it happened, checked in the page */
     unique?: LocatorCall[];
     textEntry?: boolean;
+    /** Of a click on a checkbox or radio: whether it leaves the control checked */
+    checked?: boolean;
+    /** Of a `select` message: the option the tester chose */
+    option?: SelectChoice;
     /** The key of a `press` message */
     pressed?: string;
     value?: string;

package/dist/recorder/page-messages.js

@@ -2,25 +2,33 @@
 export function observationFor(message, locator) {
     const key = message.target.sharedId;
     return message.type === "click"
-        ? { type: "click", key, locator, textEntry: message.textEntry === true }
-        : message.type === "press"
-            ? { type: "press", key, locator, pressed: message.pressed ?? "" }
-            : message.type === "assert"
-                ? {
-                    type: "assert",
-                    key,
-                    locator,
-                    text: message.text ?? "",
-                    ...(message.value !== undefined && { value: message.value }),
-                }
-                : {
-                    type: "input",
-                    key,
-                    locator,
-                    ...(message.value !== undefined && { value: message.value }),
-                    ...(message.secret && { secret: true }),
-                    ...(message.secretName !== undefined && {
-                        secretName: message.secretName,
-                    }),
-                };
+        ? {
+            type: "click",
+            key,
+            locator,
+            textEntry: message.textEntry === true,
+            ...(message.checked !== undefined && { checked: message.checked }),
+        }
+        : message.type === "select"
+            ? { type: "select", key, locator, option: message.option ?? "" }
+            : message.type === "press"
+                ? { type: "press", key, locator, pressed: message.pressed ?? "" }
+                : message.type === "assert"
+                    ? {
+                        type: "assert",
+                        key,
+                        locator,
+                        text: message.text ?? "",
+                        ...(message.value !== undefined && { value: message.value }),
+                    }
+                    : {
+                        type: "input",
+                        key,
+                        locator,
+                        ...(message.value !== undefined && { value: message.value }),
+                        ...(message.secret && { secret: true }),
+                        ...(message.secretName !== undefined && {
+                            secretName: message.secretName,
+                        }),
+                    };
 }

package/dist/recorder/toolbar/inspect.js

@@ -1,5 +1,6 @@
 import { callFunction } from "../../script/call-function.js";
 import { locatorFromSpec } from "../../steps/build.js";
+import { callToSource } from "../../steps/emit.js";
 import { CANDIDATES_JS } from "../candidates.js";
 import { expectationFor } from "../expectation.js";
 import { TOOLBAR_SANDBOX } from "./protocol.js";
@@ -45,19 +46,25 @@ function describeCall(call) {
         case "getByRole":
             return call.name === undefined
                 ? call.role
-                : `${call.role} "${call.name}"`;
+                : `${call.role} ${quoted(call.name)}`;
         case "getByLabel":
-            return `label "${call.text}"`;
+            return `label ${quoted(call.text)}`;
         case "getByText":
-            return `text "${call.text}"`;
+            return `text ${quoted(call.text)}`;
         case "getByTestId":
             return `test id "${call.testId}"`;
         case "getByCss":
             return call.css;
         case "locator":
             return call.xpath;
+        default:
+            return callToSource(call);
     }
 }
+/** A text as the panel shows it: in quotes, a RegExp as written */
+const quoted = (text) => typeof text === "string"
+    ? `"${text}"`
+    : `/${text.regex.source}/${text.regex.flags}`;
 const sameCall = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 /**
  * What the Assert panel needs for a picked element: its short label, text, value, attributes, the first

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