@itmetsam/samurai-framework 0.22.0 → 0.22.2

package/dist/runner/fixture-use.js

@@ -0,0 +1,64 @@
+import { FIXTURES_KEY, mergeFixtureUse, pickFixtureUse, } from "../config/fixture-use.js";
+import { peekRunSettings } from "../config/run-settings.js";
+import { useLayers } from "./use-options.js";
+/**
+ * The fixtures a test gets from `use`: config, then the run's environment, then the group, then `test.use()`, a
+ * later layer winning key by key. The environment's `false` is the exception: it wins over a `true` anywhere, so a
+ * fixture an environment turns off cannot be switched back on for it.
+ */
+export async function effectiveFixtureUse(test) {
+    const layers = await useLayers(test);
+    const merged = mergeFixtureUse([
+        layers.config,
+        layers.environment,
+        layers.group,
+        ...layers.tests,
+    ]);
+    const environment = peekRunSettings()?.environment ?? "";
+    const disabled = new Map();
+    for (const [name, on] of Object.entries(mergeFixtureUse([layers.environment]).fixtures))
+        if (!on)
+            disabled.set(name, `Fixture ${name} is turned off in ${environment}`);
+    return {
+        attach: Object.entries(merged.fixtures)
+            .filter(([, on]) => on)
+            .map(([name]) => name),
+        options: merged.options,
+        disabled,
+    };
+}
+const list = (names, none) => names.length > 0 ? names.join(", ") : none;
+/** Throws when a `use` names a fixture or an option fixture that `catalog` does not have */
+function checkPlace(place, use, catalog) {
+    const fixtures = catalog.map((entry) => entry.name);
+    const options = catalog.flatMap((entry) => entry.options?.name ?? []);
+    for (const [key, value] of Object.entries(pickFixtureUse(use))) {
+        if (key === FIXTURES_KEY) {
+            for (const name of Object.keys(value))
+                if (!fixtures.includes(name))
+                    throw new Error(`${place}.fixtures: unknown fixture "${name}". ${fixtures.length > 0 ? `Known fixtures: ${list(fixtures, "")}` : "No fixtures are listed in config.fixtures"}`);
+        }
+        else if (!options.includes(key))
+            throw new Error(`${place}.${key}: unknown option fixture "${key}". ${options.length > 0 ? `Known option fixtures: ${list(options, "")}` : "No option fixtures are listed in config.fixtures"}`);
+    }
+}
+/** Refuses a config whose `use` (config, environments, groups) names a fixture that is not in `config.fixtures` */
+export function checkFixtureUseNames(config, catalog) {
+    checkPlace("config.use", config.use, catalog);
+    for (const [name, environment] of Object.entries(config.environments ?? {}))
+        checkPlace(`config.environments.${name}.use`, environment.use, catalog);
+    config.groups?.forEach((group, index) => checkPlace(`config.groups[${index}].use`, group.use, catalog));
+}
+/** Refuses a `test.use()` that names a fixture the test's own `test.extend()` does not define */
+export function checkTestFixtureUse(use, layers) {
+    for (const [key, value] of Object.entries(pickFixtureUse(use))) {
+        const known = [...(layers?.keys() ?? [])];
+        if (key === FIXTURES_KEY) {
+            for (const name of Object.keys(value))
+                if (!layers?.has(name))
+                    throw new TypeError(`use(): unknown fixture "${name}". ${known.length > 0 ? `This test has: ${known.join(", ")}` : "This test has no fixtures; write it with test.extend()"}`);
+        }
+        else if (!layers?.get(key)?.slice(-1)[0]?.option)
+            throw new TypeError(`use(): unknown option fixture "${key}"`);
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { FixtureDef } from "./fixture-defs.js";
+import { type Started } from "./fixture-start.js";
+/** A worker fixture that is set up: its value, how to finish it, and the outputs the report lists */
+export interface WorkerInstance {
+    value: unknown;
+    started: Started;
+    outputs?: Record<string, string | number | boolean> | undefined;
+}
+/**
+ * The worker-scoped fixtures of one worker. An instance is shared by the tests that need the same definition with
+ * the same key (the environment, the resolved options and the instances it uses), is set up on first use and is
+ * torn down when the worker is done, last set up first.
+ */
+export declare class WorkerFixtures {
+    private readonly limitMs;
+    private readonly byDef;
+    private readonly live;
+    /** `limitMs`: how long a teardown may take when the fixture has no `timeout` of its own */
+    constructor(limitMs: number);
+    /** The instance of `def` under `key`: the one already set up, else the result of `make`. A failed setup is not kept */
+    acquire(def: FixtureDef, key: string, make: () => Promise<WorkerInstance>): Promise<WorkerInstance & {
+        reused: boolean;
+    }>;
+    /** Tears every instance down, last set up first, and returns the errors; a second call has nothing to do */
+    closeAll(): Promise<Error[]>;
+}

package/dist/runner/fixture-worker.js

@@ -0,0 +1,46 @@
+import { finishWithin } from "./fixture-start.js";
+/**
+ * The worker-scoped fixtures of one worker. An instance is shared by the tests that need the same definition with
+ * the same key (the environment, the resolved options and the instances it uses), is set up on first use and is
+ * torn down when the worker is done, last set up first.
+ */
+export class WorkerFixtures {
+    /** `limitMs`: how long a teardown may take when the fixture has no `timeout` of its own */
+    constructor(limitMs) {
+        this.limitMs = limitMs;
+        this.byDef = new Map();
+        this.live = [];
+    }
+    /** The instance of `def` under `key`: the one already set up, else the result of `make`. A failed setup is not kept */
+    async acquire(def, key, make) {
+        let keys = this.byDef.get(def);
+        if (!keys)
+            this.byDef.set(def, (keys = new Map()));
+        const existing = keys.get(key);
+        if (existing)
+            return { ...(await existing), reused: true };
+        const created = make().then((instance) => {
+            this.live.push(instance);
+            return instance;
+        });
+        keys.set(key, created);
+        try {
+            return { ...(await created), reused: false };
+        }
+        catch (err) {
+            keys.delete(key);
+            throw err;
+        }
+    }
+    /** Tears every instance down, last set up first, and returns the errors; a second call has nothing to do */
+    async closeAll() {
+        const errors = [];
+        this.byDef.clear();
+        for (let one = this.live.pop(); one; one = this.live.pop()) {
+            const error = await finishWithin(one.started, this.limitMs);
+            if (error)
+                errors.push(error);
+        }
+        return errors;
+    }
+}

package/dist/runner/prepare-run.js

@@ -2,11 +2,16 @@ import { isShortSecret, registerSecret } from "../config/mask.js";
 import { resolveRunSettings, setRunSettings, } from "../config/run-settings.js";
 import { loadSecrets } from "../config/secrets.js";
 import logger from "../logger/index.js";
+import { fixtureCatalog } from "./fixture-registry.js";
+import { checkFixtureUseNames } from "./fixture-use.js";
 /**
  * Starts a run: picks the environment, loads its secrets and registers every value for masking
  * (all of them, not only the ones a test reads), then makes the settings active.
  */
 export function prepareRun(config, overrides, options = {}) {
+    // A fixture name defined twice refuses the run before any test starts
+    const catalog = fixtureCatalog(config.fixtures ?? []);
+    checkFixtureUseNames(config, catalog);
     const settings = resolveRunSettings(config, overrides);
     const secrets = loadSecrets(settings.environment, options);
     for (const [name, value] of secrets) {

package/dist/runner/registry.js

@@ -1,6 +1,8 @@
 import { fileURLToPath } from "node:url";
 import logger from "../logger/index.js";
 import { extendLayers } from "./fixture-defs.js";
+import { rememberLayers } from "./fixture-registry.js";
+import { checkTestFixtureUse } from "./fixture-use.js";
 import { validateUseOptions } from "../config/use-options.js";
 import { currentStepLog, currentTestInfo, infoFor, skipFromCondition, } from "./test-info.js";
 import { runStep } from "./steps.js";
@@ -150,16 +152,21 @@ export function beforeAll(hook) {
 export function afterAll(hook) {
     addHook(currentSuite(callerFile()), "afterAll", hook);
 }
-/** `test.use(options)`: checked now, applied when each test of the scope runs */
-function use(options) {
-    addUse(currentSuite(callerFile()), validateUseOptions(options));
+/** `test.use(options)` of a test with the fixtures `extension`: checked now, applied when each test of the scope runs */
+function usingFor(extension) {
+    return (options) => {
+        const checked = validateUseOptions(options);
+        // `fixtures` and option fixtures may only name what this test's `test.extend()` defines
+        checkTestFixtureUse(checked, extension);
+        addUse(currentSuite(callerFile()), checked);
+    };
 }
 /**
  * A `test` that registers its tests with the custom fixtures `extension`. The aliases are the same functions as
  * the named exports: they find the spec file from the stack, so they must not be wrapped.
  */
 function makeTest(extension) {
-    return Object.assign(registering("test", undefined, extension), {
+    const made = Object.assign(registering("test", undefined, extension), {
         skip: skipping("skip", extension),
         fixme: skipping("fixme", extension),
         fail: failing(extension),
@@ -168,7 +175,7 @@ function makeTest(extension) {
         step: (title, body, options) => runStep(currentStepLog(), title, body, options),
         only: registering("test.only", "only", extension),
         info: currentTestInfo,
-        use,
+        use: usingFor(extension),
         describe,
         beforeEach,
         afterEach,
@@ -176,6 +183,9 @@ function makeTest(extension) {
         afterAll,
         extend: (fixtures) => makeTest(extendLayers(extension, fixtures)),
     });
+    if (extension)
+        rememberLayers(made, extension);
+    return made;
 }
 export const test = makeTest();
 export function registeredTests() {

package/dist/runner/reporter.d.ts

@@ -1,4 +1,4 @@
-import type { TestAnnotation, TestStepEntry, TestAttachmentEntry, RegisteredTestCase, TestError, TestLogEntry, TestResult, TestRetries, TestSummary } from "../types/test.js";
+import type { TestAnnotation, TestFixtureEntry, 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 */
@@ -75,6 +75,8 @@ export interface TestEndExtras extends TestRetries {
     annotations?: TestAnnotation[];
     /** The steps the test ran with `test.step` */
     steps?: TestStepEntry[];
+    /** The fixtures the test set up, when it set any up */
+    fixtures?: TestFixtureEntry[];
 }
 export default class TestReporter implements TestSink {
     private testResults;

package/dist/runner/reporter.js

@@ -160,6 +160,7 @@ export default class TestReporter {
             ...(extras?.attachments && { attachments: extras.attachments }),
             ...(extras?.annotations && { annotations: extras.annotations }),
             ...(extras?.steps && { steps: extras.steps }),
+            ...(extras?.fixtures?.length && { fixtures: extras.fixtures }),
             ...(extras?.retry && { retry: extras.retry }),
             ...(extras?.flaky && { flaky: true }),
             ...(extras?.previousAttempts?.length && {

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

@@ -4,6 +4,7 @@ import type { RunnerOptions } from "./options.js";
 import type { AllHooks } from "./all-hooks.js";
 import type { PreparedRun } from "./prepare-run.js";
 import type { TestSink } from "./reporter.js";
+import type { WorkerFixtures } from "./fixture-worker.js";
 /** What a worker gives its tests that the main process does not: its own port and profile, and its number */
 export interface WorkerResources {
     /** The browser's debugging port. @default `options.port`, else DEFAULT_PORT */
@@ -16,6 +17,8 @@ export interface WorkerResources {
     attempt?: number;
     /** The `beforeAll` / `afterAll` hooks of this worker: kept across tests, closed when the worker is done */
     allHooks?: AllHooks;
+    /** The worker-scoped fixtures of this worker: kept across tests, closed when the worker is done */
+    workerFixtures?: WorkerFixtures;
 }
 /** Runs one test in one browser and reports it: launch, run the body, judge the page's logs, close the browser */
 export declare function runOneTest(test: RegisteredTestCase, browserName: SupportedBrowser, run: PreparedRun, options: RunnerOptions, srcDir: string, reporter: TestSink, resources?: WorkerResources): Promise<void>;

package/dist/runner/run-test.js

@@ -20,6 +20,7 @@ import { buildTestFixtures } from "./fixtures.js";
 import { FixtureScope } from "./fixture-scope.js";
 import { RequestFixture } from "./request-fixture.js";
 import { effectiveUse } from "./use-options.js";
+import { effectiveFixtureUse } from "./fixture-use.js";
 import { beginOutputs, endOutputs } from "../wait/output-sink.js";
 /**
  * The state of one test run. A test ends once, whichever of finishing, failing, timing out, an abort or a
@@ -38,6 +39,8 @@ class TestOutcome {
         this.browserClosed = false;
         /** The test's inputs and outputs, as its report entry lists them when it ends */
         this.io = () => ({});
+        /** The fixtures the test set up, as they stand when it ends */
+        this.fixtures = () => [];
     }
     get isEnded() {
         return this.ended;
@@ -65,6 +68,7 @@ class TestOutcome {
             screenshots: this.evidence?.screenshots,
             ...this.info?.reportExtras(),
             ...this.io(),
+            fixtures: this.fixtures(),
         });
     }
 }
@@ -119,6 +123,9 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
             // The `beforeAll` hooks come first, before a browser exists
             await resources.allHooks?.ensure(test, browserName);
             const use = await effectiveUse(test);
+            const fixtureUse = test.extension
+                ? await effectiveFixtureUse(test)
+                : undefined;
             const launched = await Browser.launch(browserName, {
                 port: resources.port ?? options.port ?? DEFAULT_PORT,
                 ...(resources.profileDir && { profileDir: resources.profileDir }),
@@ -177,9 +184,17 @@ export async function runOneTest(test, browserName, run, options, srcDir, report
             });
             // A test written with `test.extend()` gets its custom fixtures set up on demand, and torn down below
             const custom = test.extension
-                ? new FixtureScope(test.extension, built)
+                ? new FixtureScope(test.extension, built, {
+                    ...fixtureUse,
+                    environment: settings.environment,
+                    ...(resources.workerFixtures && {
+                        workers: resources.workerFixtures,
+                    }),
+                })
                 : undefined;
             customFixtures = custom;
+            if (custom)
+                outcome.fixtures = () => custom.report();
             const fixtures = custom?.fixtures ?? built;
             let failure;
             let failed = false;

package/dist/runner/run.d.ts

@@ -1,6 +1,7 @@
 import type { Modifier, TestSummary } from "../types/test.js";
 import { type ProjectOptions } from "./project.js";
 import { type ResolvedGroup } from "./groups.js";
+import { type FixtureCatalogEntry } from "./fixture-registry.js";
 import type { RunnerOptions } from "./options.js";
 export interface RunTestsOptions extends RunnerOptions, ProjectOptions {
 }
@@ -45,6 +46,12 @@ export interface FoundTest {
 export declare function listTests(options?: RunTestsOptions): Promise<FoundTest[]>;
 /** Imports the project's specs without running anything and lists the config's groups with the tests each holds */
 export declare function listGroups(options?: RunTestsOptions): Promise<ResolvedGroup[]>;
+/**
+ * Lists the fixtures of the extended tests in the config's `fixtures`, with their label, icon, scope, option form
+ * and declared outputs, without running a test. Throws for a name defined twice or one that is not allowed.
+ */
+export declare function listFixtures(options?: ProjectOptions): Promise<FixtureCatalogEntry[]>;
+export type { FixtureCatalogEntry } from "./fixture-registry.js";
 export { BROWSER_NAMES, checkBrowserList } from "../config/browsers.js";
 export { parseWorkers } from "../config/workers.js";
 export { parseRetries } from "../config/retries.js";

package/dist/runner/run.js

@@ -1,6 +1,8 @@
 import path from "path";
 import { withProject } from "./project.js";
 import { testId, toPosix } from "./groups.js";
+import { projectConfig } from "../config/config.js";
+import { fixtureCatalog, } from "./fixture-registry.js";
 import TestRunner from "./test-runner.js";
 /**
  * Sets the project up (config, environment, secrets), builds a runner from the rest of the options and hands both to
@@ -67,6 +69,13 @@ export async function listTests(options = {}) {
 export async function listGroups(options = {}) {
     return inProject(options, (runner) => runner.groups());
 }
+/**
+ * Lists the fixtures of the extended tests in the config's `fixtures`, with their label, icon, scope, option form
+ * and declared outputs, without running a test. Throws for a name defined twice or one that is not allowed.
+ */
+export async function listFixtures(options = {}) {
+    return fixtureCatalog((await projectConfig(options)).fixtures ?? []);
+}
 export { BROWSER_NAMES, checkBrowserList } from "../config/browsers.js";
 export { parseWorkers } from "../config/workers.js";
 export { parseRetries } from "../config/retries.js";

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

@@ -1,5 +1,5 @@
 import type { AllHook, SuiteMode, TestCaseBase, TestDetails, TestInfo, TestOptions } from "../types/test.js";
-import type { UseOptions } from "../types/use.js";
+import type { FixtureUse, UseOptions } from "../types/use.js";
 import type { FixtureDefinitions, FixturesOf, MergeFixtures } from "../types/extend.js";
 /** What the registry keeps of a test body; the fixtures it gets are those of the test it was written for */
 export type Body = TestCaseBase["function"];
@@ -46,7 +46,7 @@ export interface TestFunction<X = NoFixtures> {
      * the whole file at the top level, whether before or after the tests. An inner block wins over an outer one, and
      * both win over config `use`.
      */
-    use: (options: UseOptions) => void;
+    use: (options: UseOptions & FixtureUse) => void;
     /** `describe`, under the name other frameworks use */
     describe: DescribeFunction;
     /** `beforeEach`, as `test.beforeEach` */

package/dist/runner/test-runner.js

@@ -6,6 +6,7 @@ import { loadRawConfig, projectDir, readConfig } from "../config/config.js";
 import { forbidsOnly } from "../config/forbid-only.js";
 import logger from "../logger/index.js";
 import { AllHooks } from "./all-hooks.js";
+import { WorkerFixtures } from "./fixture-worker.js";
 import { assertNoOnly, narrowToOnly } from "./focus.js";
 import { DEFAULT_SRC_DIR, DEFAULT_TEST_MATCH } from "../config/defaults.js";
 import { DEFAULT_PORT } from "./ports.js";
@@ -149,11 +150,13 @@ export default class TestRunner {
             timeout: this.run.settings.timeout,
             fixtures: (browser) => allHookFixtures(this.run, browser),
         });
+        // The worker-scoped fixtures of the run: torn down when the last test is done
+        const workerFixtures = new WorkerFixtures(this.run.settings.timeout);
         try {
             for (const browser of browsers) {
                 const forBrowser = selected.filter((test) => runsIn(test, browser));
                 for (const chunk of chunkBySerialBlock(forBrowser)) {
-                    const runTest = (test, sink, attempt) => runOneTest(test, browser, this.run, this.options, loaded.srcDir, sink, { allHooks, attempt });
+                    const runTest = (test, sink, attempt) => runOneTest(test, browser, this.run, this.options, loaded.srcDir, sink, { allHooks, workerFixtures, attempt });
                     if (chunk.block) {
                         const { suite } = chunk.block;
                         await serialBlockRun({
@@ -192,6 +195,8 @@ export default class TestRunner {
         finally {
             for (const error of await allHooks.closeAll())
                 logger.error("%s", error.message);
+            for (const error of await workerFixtures.closeAll())
+                logger.error("%s", error.message);
         }
         return reporter.onEnd();
     }

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

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

package/dist/runner/use-options.js

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

package/dist/runner/worker-session.js

@@ -3,6 +3,7 @@ import logger from "../logger/index.js";
 import { withProject } from "./project.js";
 import TestReporter from "./reporter.js";
 import { AllHooks } from "./all-hooks.js";
+import { WorkerFixtures } from "./fixture-worker.js";
 import { allHookFixtures } from "./fixtures.js";
 import { runOneTest } from "./run-test.js";
 import { runWithRetries } from "./retry.js";
@@ -37,6 +38,8 @@ export function openSession(init) {
                 timeout: run.settings.timeout,
                 fixtures: (browser) => allHookFixtures(run, browser, workerIndex),
             });
+            // The worker-scoped fixtures this worker set up: torn down when it closes
+            const workerFixtures = new WorkerFixtures(run.settings.timeout);
             resolve({
                 tests: loaded.all,
                 async runTest(test, browser, signal, onEvent, perTest = {}) {
@@ -63,12 +66,15 @@ export function openSession(init) {
                         profileDir: workerProfileDir(browser, workerIndex),
                         workerIndex,
                         allHooks,
+                        workerFixtures,
                         attempt,
                     }), reporter);
                 },
                 async close() {
                     for (const error of await allHooks.closeAll())
                         logger.error("%s", error.message);
+                    for (const error of await workerFixtures.closeAll())
+                        logger.error("%s", error.message);
                     release();
                     await finished;
                 },

package/dist/steps/build.js

@@ -1,32 +1,56 @@
+/** The RegExp or string a matcher stands for */
+function textFromMatcher(matcher) {
+    return typeof matcher === "string"
+        ? matcher
+        : new RegExp(matcher.regex.source, matcher.regex.flags);
+}
+/** `options` without the keys that are undefined, or undefined when nothing is left */
+function defined(options) {
+    const entries = Object.entries(options).filter(([, v]) => v !== undefined);
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
+function apply(target, call) {
+    switch (call.method) {
+        case "locator":
+            return target.locator(call.xpath);
+        case "getByCss":
+            return target.getByCss(call.css);
+        case "getByText":
+        case "getByLabel": {
+            const { exact, match, ignoreCase } = call;
+            return target[call.method](textFromMatcher(call.text), defined({ exact, match, ignoreCase }));
+        }
+        case "getByPlaceholder":
+        case "getByAltText":
+        case "getByTitle":
+            return target[call.method](textFromMatcher(call.text), defined({ exact: call.exact }));
+        case "getByRole": {
+            const { method, role, name, ...options } = call;
+            return target.getByRole(role, defined({
+                ...options,
+                ...(name !== undefined && { name: textFromMatcher(name) }),
+            }));
+        }
+        case "getByTestId":
+            return target.getByTestId(call.testId);
+        case "nth":
+        case "first":
+        case "last":
+        case "filter": {
+            if (!("nth" in target))
+                throw new Error(`${call.method} needs a locator to narrow`);
+            return call.method === "nth"
+                ? target.nth(call.index)
+                : call.method === "filter"
+                    ? target.filter({ hasText: textFromMatcher(call.hasText) })
+                    : target[call.method]();
+        }
+    }
+}
 function fromCalls(page, calls) {
     const [first, ...rest] = calls;
     if (!first)
         throw new Error("A locator needs at least one call");
-    const apply = (target, call) => {
-        const text = {
-            ...(call.method !== "locator" &&
-                call.method !== "getByCss" &&
-                call.method !== "getByTestId" &&
-                call.method !== "getByRole" && {
-                ...(call.match !== undefined && { match: call.match }),
-                ...(call.ignoreCase !== undefined && { ignoreCase: call.ignoreCase }),
-            }),
-        };
-        switch (call.method) {
-            case "locator":
-                return target.locator(call.xpath);
-            case "getByCss":
-                return target.getByCss(call.css);
-            case "getByText":
-                return target.getByText(call.text, text);
-            case "getByLabel":
-                return target.getByLabel(call.text, text);
-            case "getByRole":
-                return target.getByRole(call.role, call.name === undefined ? undefined : { name: call.name });
-            case "getByTestId":
-                return target.getByTestId(call.testId);
-        }
-    };
     return rest.reduce((locator, call) => apply(locator, call), apply(page, first));
 }
 /** The locator a step's `LocatorSpec` stands for, with its fallbacks */