@itmetsam/samurai-framework 0.21.3 → 0.21.5

package/dist/runner/test-info.js

@@ -0,0 +1,169 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import path from "node:path";
+import { saveAttachment } from "./attachments.js";
+import { isSkipSignal, SkipSignal } from "./skip.js";
+import { StepLog } from "./steps.js";
+import { toTestError } from "./test-error.js";
+import { checkTimeout, TestTimeout } from "./test-timeout.js";
+/** The `TestInfo` of one attempt of a test. The runner creates it, the test only reads it. */
+export class TestInfoImpl {
+    constructor(from) {
+        this.annotations = [];
+        this.expectedStatus = "passed";
+        /** The steps the test ran with `test.step` */
+        this.stepLog = new StepLog();
+        this.errors = [];
+        this.saved = [];
+        this.used = new Set();
+        this.started = Date.now();
+        const { test } = from;
+        this.title = test.titlePath[test.titlePath.length - 1] ?? test.name;
+        this.titlePath = [...test.titlePath];
+        this.file = test.file;
+        if (test.line !== undefined)
+            this.line = test.line;
+        if (test.column !== undefined)
+            this.column = test.column;
+        this.retry = from.retry;
+        this.workerIndex = from.workerIndex;
+        this.project = { name: from.browserName };
+        this.config = { ...from.settings };
+        this.resultDir = from.resultDir;
+        this.outputDir = from.outputDir;
+        this.limit =
+            from.timeout ?? new TestTimeout(from.settings.timeout, () => { });
+    }
+    get timeout() {
+        return this.limit.ms;
+    }
+    setTimeout(ms) {
+        this.limit.set(checkTimeout("setTimeout()", ms));
+    }
+    slow(condition = true, description) {
+        if (!condition || this.annotated("slow"))
+            return;
+        this.note("slow", description);
+        this.limit.set(this.limit.ms * 3);
+    }
+    fail(condition = true, description) {
+        if (!condition)
+            return;
+        this.expectedStatus = "failed";
+        if (!this.annotated("fail"))
+            this.note("fail", description);
+    }
+    skip(condition = true, description) {
+        if (condition)
+            throw new SkipSignal("skip", description);
+    }
+    fixme(condition = true, description) {
+        if (condition)
+            throw new SkipSignal("fixme", description);
+    }
+    annotated(type) {
+        return this.annotations.some((a) => a.type === type);
+    }
+    note(type, description) {
+        this.annotations.push({
+            type,
+            ...(description !== undefined && { description }),
+        });
+    }
+    get status() {
+        return this.result;
+    }
+    get duration() {
+        return (this.ended ?? Date.now()) - this.started;
+    }
+    get attachments() {
+        return this.saved;
+    }
+    async attach(name, options) {
+        this.saved.push(await saveAttachment(this.outputDir, this.used, name, options));
+    }
+    /** The body (with its `beforeEach` hooks) ended: `error` is what it threw, if anything. Runs before the `afterEach` hooks. */
+    bodyDone(error) {
+        this.ended = Date.now();
+        if (error === undefined)
+            this.result = "passed";
+        else if (isSkipSignal(error))
+            this.result = "skipped";
+        else {
+            this.result = "failed";
+            this.errors.push(toTestError(error));
+        }
+    }
+    /** The fields a report entry adds for this attempt: nothing when there is nothing to list */
+    reportExtras() {
+        return {
+            ...(this.saved.length > 0 && {
+                attachments: this.saved.map((a) => ({
+                    name: a.name,
+                    contentType: a.contentType,
+                    path: path.relative(this.resultDir, a.path).split(path.sep).join("/"),
+                })),
+            }),
+            ...(this.annotations.length > 0 && {
+                annotations: this.annotations.map((a) => ({ ...a })),
+            }),
+            ...(this.stepLog.entries.length > 0 && {
+                steps: structuredClone(this.stepLog.entries),
+            }),
+        };
+    }
+}
+const scopes = new AsyncLocalStorage();
+/** Runs `fn` (the body and hooks of one test) so that `test.info()` and `test.skip(fn)` find the test */
+export function runInTestScope(scope, fn) {
+    return scopes.run(scope, fn);
+}
+/** `test.info()` */
+export function currentTestInfo() {
+    const scope = scopes.getStore();
+    if (!scope)
+        throw new Error("info(): no test is running");
+    return scope.info;
+}
+/** The running test's scope, if a test (or one of its hooks) is running */
+export function runningScope() {
+    return scopes.getStore();
+}
+/** The running test's info for `label` (`setTimeout()`); throws when no test is running */
+export function infoFor(label) {
+    const scope = scopes.getStore();
+    if (!scope)
+        throw new Error(`${label}: no test is running`);
+    return scope.info;
+}
+/** The running test's steps; throws when no test is running */
+export function currentStepLog() {
+    const info = infoFor("step()");
+    if (!(info instanceof TestInfoImpl))
+        throw new Error("step(): no test is running");
+    return info.stepLog;
+}
+/**
+ * Whether a condition of `test.skip`, `test.fail` or `test.slow` holds: a boolean as it is, a function called with
+ * the running test's fixtures (it must be synchronous). `label` starts the errors (`test.skip()`).
+ */
+export function conditionHolds(label, condition) {
+    if (typeof condition !== "function")
+        return Boolean(condition);
+    const scope = scopes.getStore();
+    if (!scope)
+        throw new Error(`${label}: a condition function needs a running test`);
+    const result = condition(scope.fixtures);
+    if (result instanceof Promise) {
+        result.catch(() => { });
+        throw new Error(`${label}: the condition function must be synchronous`);
+    }
+    return Boolean(result);
+}
+/**
+ * `test.skip(condition, reason)` and `test.fixme(...)` from inside a test or its hooks: throws the skip signal
+ * when `condition` is true, or when it is a function and returns something truthy.
+ */
+export function skipFromCondition(annotation, condition, reason) {
+    if (conditionHolds(`test.${annotation}()`, condition))
+        throw new SkipSignal(annotation, reason);
+}

package/dist/runner/test-runner.js

@@ -11,7 +11,8 @@ import { DEFAULT_SRC_DIR, DEFAULT_TEST_MATCH } from "../config/defaults.js";
 import { DEFAULT_PORT } from "./ports.js";
 import TestReporter from "./reporter.js";
 import { concurrency, planItems, poolMode, runPooled, serialKeyOf, } from "./pooled-run.js";
-import { allHookFixtures, runOneTest } from "./run-test.js";
+import { allHookFixtures } from "./fixtures.js";
+import { runOneTest } from "./run-test.js";
 import { staticSkip } from "./skip.js";
 import { browsersOfRun, loadSpecs, selectTests } from "./select.js";
 import { resolveRetries } from "./retries-option.js";

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

@@ -0,0 +1,22 @@
+/**
+ * The time limit of one test. It starts once, and can be changed while the test runs: the new limit counts from
+ * the start of the test, so the time already spent counts against it (a limit already passed ends the test now).
+ */
+export declare class TestTimeout {
+    private limit;
+    private readonly onExpire;
+    private timer;
+    private startedAt;
+    private expired;
+    constructor(limit: number, onExpire: () => void);
+    /** The limit in milliseconds; 0 means none */
+    get ms(): number;
+    /** Starts the clock; nothing can expire before this */
+    start(): void;
+    /** Changes the limit, re-arming the timer from the start of the test */
+    set(ms: number): void;
+    stop(): void;
+    private arm;
+}
+/** Checks a timeout in milliseconds; `label` starts the error (`setTimeout()`) */
+export declare function checkTimeout(label: string, ms: unknown): number;

package/dist/runner/test-timeout.js

@@ -0,0 +1,45 @@
+/**
+ * The time limit of one test. It starts once, and can be changed while the test runs: the new limit counts from
+ * the start of the test, so the time already spent counts against it (a limit already passed ends the test now).
+ */
+export class TestTimeout {
+    constructor(limit, onExpire) {
+        this.limit = limit;
+        this.onExpire = onExpire;
+        this.expired = false;
+    }
+    /** The limit in milliseconds; 0 means none */
+    get ms() {
+        return this.limit;
+    }
+    /** Starts the clock; nothing can expire before this */
+    start() {
+        this.startedAt = Date.now();
+        this.arm();
+    }
+    /** Changes the limit, re-arming the timer from the start of the test */
+    set(ms) {
+        this.limit = ms;
+        if (this.startedAt !== undefined && !this.expired)
+            this.arm();
+    }
+    stop() {
+        clearTimeout(this.timer);
+    }
+    arm() {
+        clearTimeout(this.timer);
+        if (this.limit === 0 || this.startedAt === undefined)
+            return;
+        const left = Math.max(0, this.limit - (Date.now() - this.startedAt));
+        this.timer = setTimeout(() => {
+            this.expired = true;
+            this.onExpire();
+        }, left);
+    }
+}
+/** Checks a timeout in milliseconds; `label` starts the error (`setTimeout()`) */
+export function checkTimeout(label, ms) {
+    if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0)
+        throw new Error(`${label}: the timeout must be a number of milliseconds, 0 or more`);
+    return ms;
+}

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

@@ -0,0 +1,7 @@
+import type { RegisteredTestCase } from "../types/test.js";
+import type { UseOptions } from "../types/use.js";
+/**
+ * The `use` options one test runs with: config `use`, then the `test.use()` calls around the test, outermost
+ * first, a later one winning key by key
+ */
+export declare function effectiveUse(test: RegisteredTestCase): Promise<UseOptions>;

package/dist/runner/use-options.js

@@ -0,0 +1,18 @@
+import { readConfig } from "../config/config.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 `test.use()` calls around the test, outermost
+ * first, a later one winning key by key
+ */
+export async function effectiveUse(test) {
+    let config;
+    try {
+        config = await readConfig("use");
+    }
+    catch (err) {
+        logger.debug("Could not read use config, using defaults", { err });
+    }
+    return mergeUse([useOptionsOf(config), ...useOf(test.suite)]);
+}

package/dist/runner/worker-session.js

@@ -3,7 +3,8 @@ import logger from "../logger/index.js";
 import { withProject } from "./project.js";
 import TestReporter from "./reporter.js";
 import { AllHooks } from "./all-hooks.js";
-import { allHookFixtures, runOneTest } from "./run-test.js";
+import { allHookFixtures } from "./fixtures.js";
+import { runOneTest } from "./run-test.js";
 import { runWithRetries } from "./retry.js";
 import { loadSpecs } from "./select.js";
 /**

package/dist/script/call-function.d.ts

@@ -20,7 +20,14 @@ export declare class ScriptError extends Error {
 export declare class ScriptSerializationError extends Error {
     constructor(message: string);
 }
+/** A function to run in the page, or its source (a string is used as written) */
+export type PageFunction<A extends unknown[], R> = string | ((...args: A) => R | Promise<R>);
 /** The source to send for `fn`; a function object must not depend on transpiler helpers */
 export declare function toFunctionDeclaration(fn: string | ((...args: any[]) => unknown)): string;
 /** Calls `fn` in the page with serialized arguments and returns its deserialized result */
 export declare function callFunction<T = unknown>(connector: BiDiConnector, context: string, fn: string | ((...args: any[]) => unknown), args?: Arg[], options?: CallOptions): Promise<T>;
+/**
+ * Evaluates `expression` in the page and returns its deserialized result; a promise is awaited.
+ * Throws `ScriptError` with the page's message when it throws.
+ */
+export declare function evaluateExpression<T = unknown>(connector: BiDiConnector, context: string, expression: string): Promise<T>;

package/dist/script/call-function.js

@@ -26,10 +26,12 @@ export function toFunctionDeclaration(fn) {
     if (typeof fn === "string")
         return fn;
     const source = fn.toString();
-    // tsx/esbuild wrap named functions in a __name() helper that does not exist in the page
+    // tsx/esbuild (keepNames) wrap named functions in a __name() helper that does not exist in the page
     if (source.includes("__name(")) {
-        throw new ScriptSerializationError("The function's source uses the transpiler's __name helper, which does not exist in the page. " +
-            "Use an arrow function without inner named functions, or pass the function as a string.");
+        throw new ScriptSerializationError("The function's source uses __name(), a helper that tsx and esbuild add around named functions " +
+            "(also an arrow function assigned to a variable) and that does not exist in the page. " +
+            "Write the function without inner named functions (pass callbacks inline as anonymous arrow functions), " +
+            "or pass it as a string.");
     }
     return source;
 }
@@ -52,3 +54,19 @@ export async function callFunction(connector, context, fn, args = [], options =
     }
     return fromRemoteValue(result.result);
 }
+/**
+ * Evaluates `expression` in the page and returns its deserialized result; a promise is awaited.
+ * Throws `ScriptError` with the page's message when it throws.
+ */
+export async function evaluateExpression(connector, context, expression) {
+    const result = await connector.send("script.evaluate", {
+        expression,
+        awaitPromise: true,
+        target: { context },
+        resultOwnership: "none",
+    });
+    if (result.type === "exception") {
+        throw new ScriptError(result.exceptionDetails.text, expression, result.exceptionDetails.stackTrace);
+    }
+    return fromRemoteValue(result.result);
+}

package/dist/script/element-handle.d.ts

@@ -1,7 +1,7 @@
 /**
  * A reference to a DOM node in the browser. The `sharedId` stays valid across scripts in the
  * same document; after navigation or removal the browser answers `no such node`.
- * Internal: user code keeps using `Locator`.
+ * What `evaluate` returns for a DOM node; user code keeps using `Locator` to act on elements.
  */
 export declare class ElementHandle {
     readonly sharedId: string;

package/dist/script/element-handle.js

@@ -1,7 +1,7 @@
 /**
  * A reference to a DOM node in the browser. The `sharedId` stays valid across scripts in the
  * same document; after navigation or removal the browser answers `no such node`.
- * Internal: user code keeps using `Locator`.
+ * What `evaluate` returns for a DOM node; user code keeps using `Locator` to act on elements.
  */
 export class ElementHandle {
     constructor(sharedId) {

package/dist/types/config.d.ts

@@ -1,5 +1,6 @@
 import type { StepDefinition } from "../flows/steps/define.js";
 import type { SupportedBrowser } from "./browser.js";
+import type { UseOptions } from "./use.js";
 
 interface SamuraiTest {
   /** Path relative to srcDir, e.g. 'checkout/coupons.spec.ts' */
@@ -129,8 +130,8 @@ export interface SamuraiTestConfig {
    * @default "files"
    */
   filesDir?: string;
-  /** How pages are opened */
-  use?: {
+  /** 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

package/dist/types/extend.d.ts

@@ -0,0 +1,30 @@
+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 */
+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;
+
+/** 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";
+}
+
+/** A value, or a function that sets the value up, calls `use(value)` and cleans up once `use` returns */
+export type FixtureValue<R, Args> =
+  | Exclude<R, (...args: never[]) => unknown>
+  | ((args: Args, use: (value: R) => Promise<void>) => Promise<void>);
+
+/** What `test.extend()` takes: each fixture alone, or as `[fixture, options]` */
+export type FixtureDefinitions<T, Existing> = {
+  [K in keyof T]:
+    | FixtureValue<T[K], FixturesOf<MergeFixtures<Existing, T>>>
+    | [
+        FixtureValue<T[K], FixturesOf<MergeFixtures<Existing, T>>>,
+        FixtureOptions,
+      ];
+};

package/dist/types/test.d.ts

@@ -1,7 +1,9 @@
 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 { SupportedBrowser } from "./browser.js";
+import type { UseOptions } from "./use.js";
 
 /** What a test function receives */
 export interface TestFixtures {
@@ -19,6 +21,101 @@ 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;
+  /** 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,6 +170,10 @@ 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[];
 }
 
 export interface RegisteredTestCase extends TestCaseBase {
@@ -80,6 +181,9 @@ export interface RegisteredTestCase extends TestCaseBase {
   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 +194,10 @@ 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[]>;
 }
 
 export interface TestCaseBase {
@@ -118,6 +226,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 +246,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 */

package/dist/types/use.d.ts

@@ -0,0 +1,47 @@
+/** How the page looks to the site, and what the browser starts with. Set in config `use` or with `test.use()`. */
+export interface UseOptions {
+  /** A BCP 47 tag, e.g. "nl-NL": `navigator.language`, `Intl` formatting and the `Accept-Language` header */
+  locale?: string;
+  /** An IANA timezone, e.g. "Europe/Amsterdam" */
+  timezoneId?: string;
+  /** The `User-Agent` header and `navigator.userAgent` */
+  userAgent?: string;
+  /** `false` runs pages without JavaScript */
+  javaScriptEnabled?: boolean;
+  /** 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 */
+  storageState?: string | StorageState;
+  /** Headers added to every request of the page */
+  extraHTTPHeaders?: Record<string, string>;
+  /** What `prefers-color-scheme` reports */
+  colorScheme?: ColorScheme;
+}
+
+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/dist/wait/wait-until.d.ts

@@ -1,6 +1,8 @@
 export interface WaitOptions {
     /** Total time (ms) to keep probing; 0 probes exactly once */
     timeout: number;
+    /** Pauses (ms) after the first, second, ... probe; the last one repeats. Default: 100 every time */
+    intervals?: readonly number[];
 }
 export declare class WaitTimeoutError<T> extends Error {
     readonly timeout: number;
@@ -13,4 +15,4 @@ export declare class WaitTimeoutError<T> extends Error {
  * Always probes at least once; with `timeout > 0` every probe races the time left.
  * Probe errors are rethrown immediately. Throws WaitTimeoutError at the deadline.
  */
-export declare function waitUntil<T>(probe: () => Promise<T>, isDone: (current: T, previous: T | undefined) => boolean, { timeout }: WaitOptions): Promise<T>;
+export declare function waitUntil<T>(probe: () => Promise<T>, isDone: (current: T, previous: T | undefined) => boolean, { timeout, intervals }: WaitOptions): Promise<T>;

package/dist/wait/wait-until.js

@@ -29,9 +29,10 @@ function probeBefore(probe, remaining) {
  * Always probes at least once; with `timeout > 0` every probe races the time left.
  * Probe errors are rethrown immediately. Throws WaitTimeoutError at the deadline.
  */
-export async function waitUntil(probe, isDone, { timeout }) {
+export async function waitUntil(probe, isDone, { timeout, intervals }) {
     const deadline = Date.now() + timeout;
     let previous;
+    let probes = 0;
     for (let first = true;; first = false) {
         const remaining = deadline - Date.now();
         // Only start a probe while time remains; a later one could only lose the race
@@ -49,6 +50,10 @@ export async function waitUntil(probe, isDone, { timeout }) {
         const left = deadline - Date.now();
         if (left <= 0)
             throw new WaitTimeoutError(timeout, previous);
-        await sleep(Math.min(POLL_INTERVAL, left));
+        const pause = intervals?.length
+            ? intervals[Math.min(probes, intervals.length - 1)]
+            : POLL_INTERVAL;
+        probes++;
+        await sleep(Math.min(pause, left));
     }
 }