@itmetsam/samurai-framework 0.22.0 → 0.22.2

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.2",
   "description": "Browser test framework over WebDriver BiDi: auto-waiting locators, environments and secrets, a recorder, and a command line.",
   "main": "dist/api.js",
   "exports": {