@itmetsam/samurai-framework 0.21.5 → 0.22.1

package/dist/types/config.d.ts

@@ -1,6 +1,7 @@
 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 {
   /** Path relative to srcDir, e.g. 'checkout/coupons.spec.ts' */
@@ -33,8 +34,67 @@ export interface SamuraiGroup {
    * nothing but such a group uses one worker.
    */
   workers?: number;
+  /**
+   * Options for this group's tests, over the config's `use` and under the `test.use()` of a spec: the same options
+   * 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 & FixtureUse;
+}
+
+/** The options of a group's `use`: those of `test.use()`, and the page's `viewport` */
+export interface GroupUse extends UseOptions {
+  /** Size of the page's viewport, instead of config `use.viewport`. `null` keeps the browser's own size */
+  viewport?: { width: number; height: number } | null;
 }
 
+/** One server the run starts before the first test (see `SamuraiTestConfig.webServer`). Give either `url` or `port`. */
+export interface WebServerConfig {
+  /** Shell command that starts the server. It leads its own process group, so the whole tree is stopped at the end */
+  command: string;
+  /** Where the server answers: ready once it responds with a status from 200 to 403 */
+  url?: string;
+  /** Where the server listens: ready once `localhost` accepts TCP connections on it */
+  port?: number;
+  /** Working directory of the command, relative to the project folder. @default the project folder */
+  cwd?: string;
+  /** Extra environment variables for the command, on top of this process's. Never printed in errors */
+  env?: Record<string, string>;
+  /** Time (ms) the server may take to be ready. @default 60000 */
+  timeout?: number;
+  /** When `url`/`port` already answers, use that server and start nothing (it is not stopped either). @default false */
+  reuseExistingServer?: boolean;
+  /** Send the command's stdout to this process's stdout, or drop it. @default "ignore" */
+  stdout?: "pipe" | "ignore";
+  /** Send the command's stderr to this process's stderr, or drop it. @default "pipe" */
+  stderr?: "pipe" | "ignore";
+  /** Do not fail on a certificate error while waiting for an `https` `url`. @default false */
+  ignoreHTTPSErrors?: boolean;
+  /**
+   * How the server is stopped: `signal` goes to the whole process group, and after `timeout` ms what is left is
+   * killed. @default { signal: "SIGTERM", timeout: 5000 }
+   */
+  gracefulShutdown?: { signal?: "SIGTERM" | "SIGINT"; timeout?: number };
+}
+
+/** What `globalSetup` and `globalTeardown` receive: the project's resolved config, with the run's environment and base URL */
+export type GlobalHookConfig = ResolvedConfig & {
+  /** The environment the run uses */
+  environment: string;
+};
+
+/** A run-level hook; `globalSetup` may return a function that runs as teardown too */
+export type GlobalSetupFunction = (
+  config: GlobalHookConfig,
+) =>
+  | void
+  | (() => void | Promise<void>)
+  | Promise<void | (() => void | Promise<void>)>;
+
+export type GlobalTeardownFunction = (
+  config: GlobalHookConfig,
+) => void | Promise<void>;
+
 export interface SamuraiEnvironment {
   /** Where page.goto('/…') resolves to in this environment, and where recordings start */
   baseURL?: string;
@@ -45,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 {
@@ -65,6 +131,14 @@ export interface SamuraiTestConfig {
    * @default half the CPUs
    */
   workers?: number | string;
+  /**
+   * Whether the tests of one file may run on different workers. Not set: they do, one test at a time goes to the
+   * next free worker (the same as `true`). `false` keeps the tests of a file together, in order, on one worker;
+   * `describe.configure({ mode: 'parallel' })` frees a part of it again. A serial block (`describe.serial`) is
+   * never split, whatever this says.
+   * @default not set
+   */
+  fullyParallel?: boolean;
   /**
    * How many times a failing test is run again, each time with a fresh browser. A test that passes on a retry is
    * reported as flaky and does not fail the run; a run that is aborted is never retried. `--retries` and
@@ -131,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?: {
     /**
@@ -210,6 +285,27 @@ export interface SamuraiTestConfig {
      */
     maxBodySize?: number;
   };
+  /**
+   * Servers the run starts before the first test and stops after the last. Each waits until its `url` answers or
+   * its `port` accepts connections. When no `baseURL` is configured (project or environment), the first server's
+   * `url` origin (or `http://localhost:<port>`) becomes the base URL. Only a run (`samurai run`, `runTests`)
+   * starts them, not `list` or the recorder.
+   */
+  webServer?: WebServerConfig | WebServerConfig[];
+  /**
+   * Module (path relative to the project folder) whose default export `async (config) => void | teardown` runs once
+   * before the tests, after the web servers are up; or the function itself. Variables it sets in `process.env`
+   * reach the tests, workers included. A function it returns runs as teardown.
+   */
+  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

@@ -2,6 +2,7 @@ import type { Browser } from "../browser/browser.js";
 import type Page from "../browser/page.js";
 import type { BrowserContext } from "../browser/browser-context.js";
 import type Locator from "../locator/locator.js";
+import type { APIRequestContext } from "../request/api-request-context.js";
 import type { SupportedBrowser } from "./browser.js";
 import type { UseOptions } from "./use.js";
 
@@ -25,6 +26,11 @@ export interface TestFixtures {
   context: BrowserContext;
   /** The run's `baseURL` (the environment's, else the project's); `undefined` when none is set */
   baseURL: string | undefined;
+  /**
+   * Makes HTTP requests without a browser: its own cookies, the run's `baseURL`, `use.extraHTTPHeaders` and
+   * `use.acceptInsecureCerts`. For requests that share the page's cookies use `page.request`.
+   */
+  request: APIRequestContext;
   /** About the running test: its title, retry, attachments; same as `test.info()` */
   testInfo: TestInfo;
   /** Whether the page runs as a phone (`use.isMobile`); always false on Firefox, which cannot do it */
@@ -68,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 */
@@ -174,8 +200,13 @@ export interface Suite {
   marks?: { type: "fail" | "slow"; description?: string }[];
   /** The `test.use()` calls written in this scope, in order; they apply to every test below */
   use?: UseOptions[];
+  /** Set by `describe.configure({ mode })`, `describe.serial` or `describe.parallel`; absent: `"default"` */
+  mode?: SuiteMode;
 }
 
+/** How the tests of a suite run: `"serial"` in order on one worker, the rest stops at the first failure */
+export type SuiteMode = "default" | "parallel" | "serial";
+
 export interface RegisteredTestCase extends TestCaseBase {
   /** Path of the spec file that registered the test */
   file: string;
@@ -198,6 +229,8 @@ export interface RegisteredTestCase extends TestCaseBase {
   expectedFail?: { description?: string };
   /** The custom fixtures of the `test` it was written with (`test.extend()`); absent for the plain `test` */
   extension?: ReadonlyMap<string, readonly unknown[]>;
+  /** The group this run of the test is for, when groups were selected; the same test runs once per selected group */
+  group?: string;
 }
 
 export interface TestCaseBase {
@@ -232,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` */
@@ -252,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 */
@@ -288,6 +325,8 @@ interface TestResultIdentity {
   file: string;
   /** The browser the test ran in */
   browser: SupportedBrowser;
+  /** The group the test ran for, when the run selected groups (`--group`); absent otherwise */
+  group?: string;
   /** The worker process that ran the test; absent when the test ran in the main process */
   worker?: number;
   startTime: number;
@@ -297,6 +336,7 @@ interface TestResultBase {
   name: string;
   file: string;
   browser: SupportedBrowser;
+  group?: string;
   worker?: number;
   startTime: number;
   status: "started";
@@ -331,4 +371,6 @@ interface TestSummaryBase {
   environment: string;
   /** The browsers the run used, in the order they ran */
   browsers: SupportedBrowser[];
+  /** The slice of the selected tests the run held (`--shard`); absent for a whole run */
+  shard?: { current: number; total: number };
 }

package/dist/types/use.d.ts

@@ -1,17 +1,33 @@
-/** How the page looks to the site, and what the browser starts with. Set in config `use` or with `test.use()`. */
+/**
+ * How the page looks to the site, and what the browser starts with. One vocabulary for every level: config `use`,
+ * a group's `use`, `test.use()` (fixed before the test starts) and `page.use()` / `context.use()` (applied now).
+ * At run time `null` puts the real value back; in config a later layer's `null` cancels an earlier value.
+ */
 export interface UseOptions {
   /** A BCP 47 tag, e.g. "nl-NL": `navigator.language`, `Intl` formatting and the `Accept-Language` header */
-  locale?: string;
+  locale?: string | null;
   /** An IANA timezone, e.g. "Europe/Amsterdam" */
-  timezoneId?: string;
+  timezone?: string | null;
   /** The `User-Agent` header and `navigator.userAgent` */
-  userAgent?: string;
+  userAgent?: string | null;
+  /** Needs the geolocation permission: see `page.grantPermission("geolocation")` */
+  geolocation?: {
+    latitude: number;
+    longitude: number;
+    accuracy?: number;
+  } | null;
+  /** `true`: no network (`navigator.onLine` is false and requests fail); `false`: back online */
+  offline?: boolean | null;
+  /** "portrait" and "landscape" mean the primary orientation of that kind */
+  orientation?: Orientation | null;
+  /** The size `screen.width` and `screen.height` report */
+  screen?: { width: number; height: number } | null;
   /** `false` runs pages without JavaScript */
-  javaScriptEnabled?: boolean;
+  javaScriptEnabled?: boolean | null;
+  /** Touch input: `navigator.maxTouchPoints` is 1. Chrome only. */
+  hasTouch?: boolean | null;
   /** Accept certificates that are self-signed, expired or for another host. Fixed when the browser starts. */
   acceptInsecureCerts?: boolean;
-  /** Touch input: `navigator.maxTouchPoints` is 1. Chrome only. */
-  hasTouch?: boolean;
   /** A phone-like browser (the layout viewport follows the page's `<meta name="viewport">`). Chrome only. */
   isMobile?: boolean;
   /** Cookies and local storage to start with: a JSON file (relative to the project folder) or the object itself */
@@ -22,6 +38,42 @@ 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,
+  | "locale"
+  | "timezone"
+  | "userAgent"
+  | "geolocation"
+  | "offline"
+  | "orientation"
+  | "screen"
+  | "javaScriptEnabled"
+  | "hasTouch"
+>;
+
+export type Orientation =
+  | "portrait"
+  | "landscape"
+  | "portrait-primary"
+  | "portrait-secondary"
+  | "landscape-primary"
+  | "landscape-secondary";
+
 export type ColorScheme = "light" | "dark" | "no-preference";
 
 /** Cookies and local storage, in the format Playwright's `storageState` files use */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itmetsam/samurai-framework",
-  "version": "0.21.5",
+  "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": {

package/dist/browser/emulation.d.ts

@@ -1,61 +0,0 @@
-import { UnsupportedOperationError } from "../transport/unsupported.js";
-import type { BiDiConnector } from "../transport/bidi-connection.js";
-declare const ORIENTATIONS: readonly ["portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary"];
-type OrientationType = (typeof ORIENTATIONS)[number];
-/**
- * What to pretend about the browser. `undefined` leaves an option as it is, `null` puts the real value back.
- * Which options a browser supports differs: an unsupported one throws UnsupportedOperationError.
- */
-export interface EmulationOptions {
-    /** A BCP 47 tag, e.g. "nl-NL": `navigator.language`, `Intl` formatting */
-    locale?: string | null;
-    /** An IANA timezone, e.g. "Europe/Amsterdam" */
-    timezone?: string | null;
-    userAgent?: string | null;
-    /** Needs the geolocation permission: see `page.grantPermission("geolocation")` */
-    geolocation?: {
-        latitude: number;
-        longitude: number;
-        accuracy?: number;
-    } | null;
-    /** `true`: no network (`navigator.onLine` is false and requests fail); `false` or `null`: back online */
-    offline?: boolean | null;
-    /** "portrait" and "landscape" mean the primary orientation of that kind */
-    orientation?: "portrait" | "landscape" | OrientationType | null;
-    /** The size `screen.width` and `screen.height` report */
-    screen?: {
-        width: number;
-        height: number;
-    } | null;
-    /** How many touch points `navigator.maxTouchPoints` reports */
-    touch?: number | null;
-    /** `false` turns JavaScript off; `true` or `null` on again */
-    javaScriptEnabled?: boolean | null;
-}
-export type EmulationTarget = {
-    contexts: string[];
-} | {
-    userContexts: string[];
-};
-/** A part of the options could not be applied; what was applied before it stays applied */
-export declare class EmulationError extends Error {
-    /** The options that were applied before the failure, in the order they were applied */
-    readonly applied: string[];
-    readonly failed: string;
-    readonly cause: unknown;
-    constructor(failed: string, applied: string[], cause: unknown);
-}
-/** The browser does not implement an emulation command */
-export declare class EmulationUnsupportedError extends UnsupportedOperationError {
-    readonly option: string;
-    readonly applied: string[];
-    constructor(option: string, applied: string[]);
-}
-/** Throws RangeError when a value is invalid, without sending anything */
-export declare function validateEmulation(options: EmulationOptions): void;
-/**
- * Applies the options to `target`, one command after the other. Nothing is rolled back when one fails:
- * the error says what was applied.
- */
-export declare function applyEmulation(connector: BiDiConnector, target: EmulationTarget, options: EmulationOptions): Promise<void>;
-export {};