@itmetsam/samurai-framework 0.21.4 → 0.22.0

package/dist/types/test.d.ts

@@ -1,7 +1,10 @@
 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";
 
 /** What a test function receives */
 export interface TestFixtures {
@@ -19,6 +22,106 @@ export interface TestFixtures {
   inputs: Readonly<Record<string, string>>;
   /** Saves the text values the test declared as outputs */
   outputs: TestOutputs;
+  /** The browser context (cookies, storage) of `page`; same as `page.context()` */
+  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 */
+  isMobile: boolean;
+  /** Whether the page has touch input (`use.hasTouch`); always false on Firefox, which cannot do it */
+  hasTouch: boolean;
+}
+
+/** A file or text a test attached to its result */
+export interface TestAttachment {
+  name: string;
+  contentType: string;
+  /** Absolute path of the saved file */
+  path: string;
+}
+
+/** An attachment as the report lists it */
+export interface TestAttachmentEntry {
+  name: string;
+  contentType: string;
+  /** Relative to the result folder */
+  path: string;
+}
+
+/** A note on a test (`{ type: "issue", description: "PROJ-1" }`) that the report lists */
+export interface TestAnnotation {
+  type: string;
+  description?: string;
+}
+
+/** A step the test ran with `test.step`, as the report lists it */
+export interface TestStepEntry {
+  title: string;
+  /** `"skipped"`: the step ended the test with `test.skip(...)` */
+  status: "passed" | "failed" | "skipped";
+  /** Milliseconds */
+  duration: number;
+  /** The message of what the step threw, or that the test ended before it finished */
+  error?: string;
+  /** The steps started inside this one; absent when there are none */
+  steps?: TestStepEntry[];
+}
+
+/** What `testInfo` and `test.info()` tell about the running test (hooks included) */
+export interface TestInfo {
+  /** The test's own title */
+  readonly title: string;
+  /** The `describe` titles, then the title */
+  readonly titlePath: string[];
+  /** Absolute path of the spec file */
+  readonly file: string;
+  /** Where the test is written; absent when unknown */
+  readonly line?: number;
+  readonly column?: number;
+  /** The attempt, counting from 0: 1 is the first run again */
+  readonly retry: number;
+  readonly workerIndex: number;
+  /** The browser this run is in. There is no `projects` matrix yet, so `name` is the browser name */
+  readonly project: { name: string };
+  /** The run settings that apply to the test */
+  readonly config: { baseURL: string | undefined; timeout: number };
+  /** Push notes here; they are listed in the report entry */
+  annotations: TestAnnotation[];
+  /** Undefined while the test body runs; set before the `afterEach` hooks */
+  readonly status: "passed" | "failed" | "skipped" | undefined;
+  /** What the test is expected to end as: `"failed"` after `test.fail()`, else `"passed"` */
+  readonly expectedStatus: "passed" | "failed";
+  /** The time limit of the test in milliseconds (0: none); see `setTimeout` */
+  readonly timeout: number;
+  /** Sets the limit of this test, counted from its start; `0` removes it */
+  setTimeout(ms: number): void;
+  /** Triples the timeout, once, and adds a `slow` annotation; nothing happens when `condition` is false */
+  slow(condition?: boolean, description?: string): void;
+  /** Expects the test to fail (`expectedStatus` is `"failed"`) and adds a `fail` annotation */
+  fail(condition?: boolean, description?: string): void;
+  /** Ends the test as skipped when `condition` is not false */
+  skip(condition?: boolean, description?: string): void;
+  /** Ends the test as skipped (known to be broken) when `condition` is not false */
+  fixme(condition?: boolean, description?: string): void;
+  /** Milliseconds since the attempt started; fixed once the body is done */
+  readonly duration: number;
+  /** The errors of the test body or of its `beforeEach` hooks; filled before the `afterEach` hooks */
+  readonly errors: TestError[];
+  /** Folder for the files this attempt attaches (created when the first one is saved) */
+  readonly outputDir: string;
+  readonly attachments: readonly TestAttachment[];
+  /** Saves a file in `outputDir` and lists it in the report entry; give `body` or `path`, not both */
+  attach(
+    name: string,
+    options: { body?: string | Buffer; path?: string; contentType?: string },
+  ): Promise<void>;
 }
 
 /** The `outputs` fixture */
@@ -73,13 +176,25 @@ export interface Suite {
   afterEach?: EachHook[];
   beforeAll?: AllHook[];
   afterAll?: AllHook[];
+  /** `test.fail(true)` and `test.slow(true)` written in this scope: they apply to every test below */
+  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;
   /** describe titles, then the test title */
   titlePath: string[];
+  /** Where the test is written, when known */
+  line?: number;
+  column?: number;
   /** The `describe` block (or the file) the test is written in */
   suite: Suite;
   /** What applies to the test: its own modifier, or the one of a suite around it */
@@ -90,6 +205,12 @@ export interface RegisteredTestCase extends TestCaseBase {
   inputs?: Record<string, string>;
   /** The names of the outputs the test declared */
   outputs?: string[];
+  /** Registered with `test.fail("title", fn)`: expected to fail; `description` is the `{ reason }` given */
+  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 {
@@ -118,6 +239,12 @@ interface TestResultSuccess extends TestResultIdentity, TestRetries {
   inputs?: Record<string, string>;
   /** The outputs the test saved; absent when it declares none */
   outputs?: Record<string, string>;
+  /** Files the test attached, relative to the result folder; absent when it attached none */
+  attachments?: TestAttachmentEntry[];
+  /** The notes the test pushed to `testInfo.annotations`; absent when there are none */
+  annotations?: TestAnnotation[];
+  /** The steps the test ran with `test.step`; absent when it ran none */
+  steps?: TestStepEntry[];
 }
 
 /** The error sits flat on the entry, as in the report: `message`, `type`, `stack`, and for assertions `expected` and `actual` */
@@ -132,6 +259,12 @@ interface TestResultFailed extends TestResultIdentity, TestError, TestRetries {
   inputs?: Record<string, string>;
   /** The outputs the test saved; absent when it declares none */
   outputs?: Record<string, string>;
+  /** Files the test attached, relative to the result folder; absent when it attached none */
+  attachments?: TestAttachmentEntry[];
+  /** The notes the test pushed to `testInfo.annotations`; absent when there are none */
+  annotations?: TestAnnotation[];
+  /** The steps the test ran with `test.step`; absent when it ran none */
+  steps?: TestStepEntry[];
 }
 
 /** What a result says about the retries of its test; absent when it passed or failed on the first attempt */
@@ -168,6 +301,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;
@@ -177,6 +312,7 @@ interface TestResultBase {
   name: string;
   file: string;
   browser: SupportedBrowser;
+  group?: string;
   worker?: number;
   startTime: number;
   status: "started";
@@ -211,4 +347,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

@@ -0,0 +1,85 @@
+/**
+ * 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 | null;
+  /** An IANA timezone, e.g. "Europe/Amsterdam" */
+  timezone?: string | null;
+  /** The `User-Agent` header and `navigator.userAgent` */
+  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 | 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;
+  /** 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 */
+  storageState?: string | StorageState;
+  /** Headers added to every request of the page */
+  extraHTTPHeaders?: Record<string, string>;
+  /** What `prefers-color-scheme` reports */
+  colorScheme?: ColorScheme;
+}
+
+/** 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 */
+export interface StorageState {
+  cookies?: StorageStateCookie[];
+  origins?: {
+    origin: string;
+    localStorage: { name: string; value: string }[];
+  }[];
+}
+
+export interface StorageStateCookie {
+  name: string;
+  value: string;
+  domain: string;
+  /** @default "/" */
+  path?: string;
+  /** Seconds since the epoch; -1 or left out is a session cookie */
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}

package/package.json

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

package/dist/browser/emulation.js

@@ -1,180 +0,0 @@
-import { isUnsupported, UnsupportedOperationError, } from "../transport/unsupported.js";
-const ORIENTATIONS = [
-    "portrait-primary",
-    "portrait-secondary",
-    "landscape-primary",
-    "landscape-secondary",
-];
-/** A part of the options could not be applied; what was applied before it stays applied */
-export class EmulationError extends Error {
-    constructor(failed, applied, cause) {
-        const detail = cause instanceof Error ? cause.message : String(cause);
-        super(`emulate(): ${failed} failed${applied.length ? ` after applying ${applied.join(", ")}` : ""}: ${detail}`);
-        this.name = "EmulationError";
-        this.failed = failed;
-        this.applied = applied;
-        this.cause = cause;
-    }
-}
-/** The browser does not implement an emulation command */
-export class EmulationUnsupportedError extends UnsupportedOperationError {
-    constructor(option, applied) {
-        super(`emulate(): ${option} is not supported by the browser`);
-        this.name = "EmulationUnsupportedError";
-        this.option = option;
-        this.applied = applied;
-    }
-}
-const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
-const isPositiveInteger = (value) => Number.isInteger(value) && value > 0;
-/** Turns the options into commands, in a fixed order; throws RangeError for an invalid value, before anything is sent */
-function plan(options) {
-    const steps = [];
-    if (options.locale !== undefined) {
-        if (options.locale !== null) {
-            try {
-                if (options.locale === "" ||
-                    Intl.getCanonicalLocales(options.locale).length !== 1)
-                    throw new RangeError();
-            }
-            catch {
-                throw new RangeError(`emulate(): invalid locale "${options.locale}"`);
-            }
-        }
-        steps.push({
-            option: "locale",
-            method: "emulation.setLocaleOverride",
-            params: { locale: options.locale },
-        });
-    }
-    if (options.timezone !== undefined) {
-        if (options.timezone !== null) {
-            try {
-                new Intl.DateTimeFormat(undefined, { timeZone: options.timezone });
-            }
-            catch {
-                throw new RangeError(`emulate(): unknown timezone "${options.timezone}"`);
-            }
-        }
-        steps.push({
-            option: "timezone",
-            method: "emulation.setTimezoneOverride",
-            params: { timezone: options.timezone },
-        });
-    }
-    if (options.userAgent !== undefined) {
-        if (options.userAgent === "")
-            throw new RangeError("emulate(): userAgent must not be empty");
-        steps.push({
-            option: "userAgent",
-            method: "emulation.setUserAgentOverride",
-            params: { userAgent: options.userAgent },
-        });
-    }
-    if (options.geolocation !== undefined) {
-        const place = options.geolocation;
-        if (place !== null) {
-            if (!isNumber(place.latitude) ||
-                place.latitude < -90 ||
-                place.latitude > 90) {
-                throw new RangeError("emulate(): latitude must be between -90 and 90");
-            }
-            if (!isNumber(place.longitude) ||
-                place.longitude < -180 ||
-                place.longitude > 180) {
-                throw new RangeError("emulate(): longitude must be between -180 and 180");
-            }
-            if (place.accuracy !== undefined &&
-                (!isNumber(place.accuracy) || place.accuracy < 0)) {
-                throw new RangeError("emulate(): accuracy must be 0 or more");
-            }
-        }
-        steps.push({
-            option: "geolocation",
-            method: "emulation.setGeolocationOverride",
-            params: { coordinates: place },
-        });
-    }
-    if (options.offline !== undefined) {
-        steps.push({
-            option: "offline",
-            method: "emulation.setNetworkConditions",
-            params: {
-                networkConditions: options.offline ? { type: "offline" } : null,
-            },
-        });
-    }
-    if (options.orientation !== undefined) {
-        let screenOrientation = null;
-        if (options.orientation !== null) {
-            const type = (options.orientation === "portrait" ||
-                options.orientation === "landscape"
-                ? `${options.orientation}-primary`
-                : options.orientation);
-            if (!ORIENTATIONS.includes(type))
-                throw new RangeError(`emulate(): unknown orientation "${options.orientation}"`);
-            screenOrientation = {
-                natural: type.startsWith("portrait") ? "portrait" : "landscape",
-                type,
-            };
-        }
-        steps.push({
-            option: "orientation",
-            method: "emulation.setScreenOrientationOverride",
-            params: { screenOrientation },
-        });
-    }
-    if (options.screen !== undefined) {
-        const area = options.screen;
-        if (area !== null &&
-            !(isPositiveInteger(area.width) && isPositiveInteger(area.height))) {
-            throw new RangeError("emulate(): screen width and height must be positive integers");
-        }
-        steps.push({
-            option: "screen",
-            method: "emulation.setScreenSettingsOverride",
-            params: { screenArea: area },
-        });
-    }
-    if (options.touch !== undefined) {
-        if (options.touch !== null && !isPositiveInteger(options.touch)) {
-            throw new RangeError("emulate(): touch must be a positive integer");
-        }
-        steps.push({
-            option: "touch",
-            method: "emulation.setTouchOverride",
-            params: { maxTouchPoints: options.touch },
-        });
-    }
-    if (options.javaScriptEnabled !== undefined) {
-        steps.push({
-            option: "javaScriptEnabled",
-            method: "emulation.setScriptingEnabled",
-            params: { enabled: options.javaScriptEnabled === false ? false : null },
-        });
-    }
-    return steps;
-}
-/** Throws RangeError when a value is invalid, without sending anything */
-export function validateEmulation(options) {
-    plan(options);
-}
-/**
- * Applies the options to `target`, one command after the other. Nothing is rolled back when one fails:
- * the error says what was applied.
- */
-export async function applyEmulation(connector, target, options) {
-    const applied = [];
-    for (const step of plan(options)) {
-        try {
-            await connector.send(step.method, { ...step.params, ...target });
-        }
-        catch (err) {
-            if (isUnsupported(err)) {
-                throw new EmulationUnsupportedError(step.option, applied);
-            }
-            throw new EmulationError(step.option, applied, err);
-        }
-        applied.push(step.option);
-    }
-}