@itmetsam/samurai-framework 0.22.0 → 0.22.1

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/types/config.d.ts

@@ -1,6 +1,6 @@
 import type { StepDefinition } from "../flows/steps/define.js";
 import type { SupportedBrowser } from "./browser.js";
-import type { UseOptions } from "./use.js";
+import type { FixtureUse, UseOptions } from "./use.js";
 import type { ResolvedConfig } from "../config/resolved-config.js";
 
 interface SamuraiTest {
@@ -39,7 +39,7 @@ export interface SamuraiGroup {
    * as config `use` that make sense per group (`locale`, `isMobile`, `viewport`, ...). They apply when the group is
    * selected (`--group`); a run without `--group` ignores them. The way to port a Playwright project.
    */
-  use?: GroupUse;
+  use?: GroupUse & FixtureUse;
 }
 
 /** The options of a group's `use`: those of `test.use()`, and the page's `viewport` */
@@ -105,6 +105,12 @@ export interface SamuraiEnvironment {
   headless?: boolean;
   /** Test data, used in steps as ${name}. Never put secrets here. */
   variables?: Record<string, string | number | boolean>;
+  /**
+   * `use` options for every test run in this environment, over config `use` and under a group's `use` and
+   * `test.use()`. `fixtures: { order: false }` turns a fixture off here for good: a test that needs it is skipped,
+   * whatever a group or test says.
+   */
+  use?: GroupUse & FixtureUse;
 }
 
 export interface SamuraiTestConfig {
@@ -199,26 +205,27 @@ export interface SamuraiTestConfig {
    */
   filesDir?: string;
   /** How pages are opened, and what the browser pretends: the options of `test.use()` apply to every test */
-  use?: UseOptions & {
-    /**
-     * Size of the page's viewport, so screenshots and layout are the same on every machine.
-     * `null` keeps the browser's own size
-     * @default { width: 1280, height: 720 }
-     */
-    viewport?: { width: number; height: number } | null;
-    /**
-     * Run the browser without a window. Needed on machines without a display, such as CI runners.
-     * Left out, a run is headless when the `CI` environment variable is set and shows a window otherwise
-     */
-    headless?: boolean;
-    /**
-     * Make an action or read on a locator that matches several elements throw
-     * `name(): strict mode violation, N elements match ...` instead of using the first one. Narrow the locator
-     * (`first()`, `nth()`, `filter()`) or turn it off for one locator with `locator.strict(false)`
-     * @default false
-     */
-    strictSelectors?: boolean;
-  };
+  use?: UseOptions &
+    FixtureUse & {
+      /**
+       * Size of the page's viewport, so screenshots and layout are the same on every machine.
+       * `null` keeps the browser's own size
+       * @default { width: 1280, height: 720 }
+       */
+      viewport?: { width: number; height: number } | null;
+      /**
+       * Run the browser without a window. Needed on machines without a display, such as CI runners.
+       * Left out, a run is headless when the `CI` environment variable is set and shows a window otherwise
+       */
+      headless?: boolean;
+      /**
+       * Make an action or read on a locator that matches several elements throw
+       * `name(): strict mode violation, N elements match ...` instead of using the first one. Narrow the locator
+       * (`first()`, `nth()`, `filter()`) or turn it off for one locator with `locator.strict(false)`
+       * @default false
+       */
+      strictSelectors?: boolean;
+    };
   /** What to do with the browser's console output and uncaught page exceptions */
   logs?: {
     /**
@@ -293,6 +300,12 @@ export interface SamuraiTestConfig {
   globalSetup?: string | GlobalSetupFunction;
   /** Module (path relative to the project folder) whose default export runs once after the tests; or the function itself */
   globalTeardown?: string | GlobalTeardownFunction;
+  /**
+   * The tests made with `test.extend()` whose fixtures the app, the groups and `use.fixtures` can name. The
+   * fixtures are read from the list without running a test; a name defined twice, or not matching
+   * `/^[a-z][A-Za-z0-9]*$/`, refuses the run.
+   */
+  fixtures?: { extend: (...args: never[]) => unknown }[];
   /** Keyed by name: 'dev', 'staging', 'production' */
   environments?: Record<string, SamuraiEnvironment>;
   /** Used when no environment is chosen with --env or SAMURAI_ENV */

package/dist/types/extend.d.ts

@@ -1,3 +1,4 @@
+import type { Field } from "../flows/core/index.js";
 import type { TestFixtures } from "./test.js";
 
 /** What a test sees when it is built with `test.extend()`: the built-in fixtures, a custom one of the same name replacing it */
@@ -6,12 +7,63 @@ export type FixturesOf<X> = Omit<TestFixtures, keyof X> & X;
 /** `B` on top of `A`: a key in both takes the type from `B` */
 export type MergeFixtures<A, B> = Omit<A, keyof B> & B;
 
+/** One key of the value a fixture sets up, listed for the app and the report */
+export interface FixtureOutput {
+  name: string;
+  label?: string;
+  /** The test gets the key, but the report and the app never do */
+  secret?: boolean;
+}
+
+/**
+ * One setting of an option fixture, as data for a form: the flows field types, with paths relative to the option
+ * object. `secret` stores the name of a secret and `variable` the name of a variable; the fixture receives the
+ * resolved value.
+ */
+export type FixtureField =
+  | Extract<
+      Field,
+      {
+        type:
+          | "text"
+          | "code"
+          | "expression"
+          | "number"
+          | "select"
+          | "segmented"
+          | "switch";
+      }
+    >
+  | {
+      path: string;
+      label?: string;
+      type: "secret" | "variable";
+      default?: string;
+    };
+
 /** The options of a fixture written as `[fixture, options]` */
 export interface FixtureOptions {
   /** Set the fixture up for every test, whether or not the test asks for it */
   auto?: boolean;
-  /** Fixtures live as long as one test; worker-scoped fixtures are not supported */
-  scope?: "test";
+  /**
+   * `"test"`: set up for each test (the default). `"worker"`: set up once per worker for the tests that use it with
+   * the same options and environment, and torn down when the worker is done. A worker fixture gets no `page`.
+   */
+  scope?: "test" | "worker";
+  /** The name in the app's catalog */
+  label?: string;
+  /** A design-system icon name */
+  icon?: string;
+  /** One sentence for the catalog */
+  description?: string;
+  /** The keys of the value the fixture sets up, when it is a flat record of strings, numbers and booleans */
+  outputs?: FixtureOutput[];
+  /** Milliseconds a setup or a teardown may take. @default the test timeout */
+  timeout?: number;
+  /** The fixture is the options of the fixture `<name without "Options">`: a value that `use` overrides key by key */
+  option?: boolean;
+  /** The form of an option fixture */
+  fields?: FixtureField[];
 }
 
 /** A value, or a function that sets the value up, calls `use(value)` and cleans up once `use` returns */

package/dist/types/test.d.ts

@@ -74,6 +74,26 @@ export interface TestStepEntry {
   steps?: TestStepEntry[];
 }
 
+/** How a fixture's setup or teardown went in one test */
+export interface TestFixturePhase {
+  /** `"skipped"`: a worker fixture another test of this worker already set up */
+  status: "passed" | "failed" | "skipped";
+  /** Milliseconds */
+  durationMs: number;
+  error?: TestError;
+}
+
+/** A fixture that set up for a test (hand-written `test.extend` ones too), as the report lists it */
+export interface TestFixtureEntry {
+  name: string;
+  scope: "test" | "worker";
+  setup: TestFixturePhase;
+  /** Absent for a worker fixture: it is torn down when the worker is done, after the test's result is written */
+  teardown?: Omit<TestFixturePhase, "status"> & { status: "passed" | "failed" };
+  /** The declared outputs that are not secret */
+  outputs?: Record<string, string | number | boolean>;
+}
+
 /** What `testInfo` and `test.info()` tell about the running test (hooks included) */
 export interface TestInfo {
   /** The test's own title */
@@ -245,6 +265,8 @@ interface TestResultSuccess extends TestResultIdentity, TestRetries {
   annotations?: TestAnnotation[];
   /** The steps the test ran with `test.step`; absent when it ran none */
   steps?: TestStepEntry[];
+  /** The fixtures the test set up and how each went; absent when it used none */
+  fixtures?: TestFixtureEntry[];
 }
 
 /** The error sits flat on the entry, as in the report: `message`, `type`, `stack`, and for assertions `expected` and `actual` */
@@ -265,6 +287,8 @@ interface TestResultFailed extends TestResultIdentity, TestError, TestRetries {
   annotations?: TestAnnotation[];
   /** The steps the test ran with `test.step`; absent when it ran none */
   steps?: TestStepEntry[];
+  /** The fixtures the test set up and how each went; absent when it used none */
+  fixtures?: TestFixtureEntry[];
 }
 
 /** What a result says about the retries of its test; absent when it passed or failed on the first attempt */

package/dist/types/use.d.ts

@@ -38,6 +38,20 @@ export interface UseOptions {
   colorScheme?: ColorScheme;
 }
 
+/**
+ * What a `use` that is layered over config, environment, group and `test.use()` can also say about fixtures. Not
+ * part of `UseOptions`: `page.use()` and the browser know nothing of fixtures.
+ */
+export interface FixtureUse {
+  /**
+   * Fixtures to attach by name (`true`: set up before `beforeEach`, like an `auto` fixture) or to remove (`false`).
+   * An environment's `false` wins over a group's or test's `true`.
+   */
+  fixtures?: Record<string, boolean>;
+  /** The values of an option fixture (`orderOptions: { items: 2 }`), merged key by key with the other layers */
+  [option: `${string}Options`]: Record<string, unknown> | undefined;
+}
+
 /** The options `page.use()` and `context.use()` take: those that can change while the browser runs */
 export type RuntimeUseOptions = Pick<
   UseOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {