@unotest/web 0.43.2 → 0.45.0

package/dist/inspection/page-inject.d.ts

@@ -1,6 +1,6 @@
 import { InjectedDomHelpers } from '@unotest/grounder-client/dom-walker';
 import { PickerMode } from '@unotest/protocol';
-import { E as ElementHint } from '../interfaces-ClW2IRgY.js';
+import { E as ElementHint } from '../interfaces-OvnJKELk.js';
 import '../config/schema.js';
 import 'zod';
 

package/dist/{interfaces-ClW2IRgY.d.ts → interfaces-OvnJKELk.d.ts}

@@ -91,13 +91,28 @@ interface LaunchOptions {
     /** Extra browser command-line arguments (`config.launch.args`). */
     args?: string[];
 }
-interface Viewport {
+interface ViewportSize {
     width: number;
     height: number;
 }
+/** What a context is asked to look like. Each field left out comes from
+ *  the device preset, or from DEFAULT_VIEWPORT when there is none. */
+interface Viewport extends Partial<ViewportSize> {
+    /** Device pixels per CSS pixel. Fixed for the life of a context. */
+    deviceScaleFactor?: number;
+}
 interface ContextOptions {
     baseUrl?: string;
-    viewport?: Viewport;
+    /** A device preset by name — the driver owns the list and refuses a
+     *  name it does not know. Applied before `viewport`, which overrides the
+     *  preset's size and scale field by field. */
+    device?: string;
+    /** `null` — the real browser window, no size emulation. */
+    viewport?: Viewport | null;
+    /** Put a fake clock on the context before its first page loads, so that
+     *  every timer the pages set is under `DriverContext.clock()`. Off by
+     *  default: time on the page is the real one. */
+    clock?: boolean;
     /** Path to storageState JSON (D-23 caching, optional). */
     storageState?: string;
     /** Per-context override for dialog policy. Defaults to config.dialogPolicy. */
@@ -231,11 +246,34 @@ interface ScreenshotOptions {
      *  as `png`. `webp` needs Playwright 1.62+, which is why the package
      *  pins that floor. */
     type?: "png" | "jpeg" | "webp";
+    /** `"disabled"` — CSS animations and transitions are finished first, so
+     *  two captures of the same page are the same picture (the visual
+     *  assert). Default: as Playwright, animations run. */
+    animations?: "disabled" | "allow";
+    /** `"hide"` — the text caret is not drawn (it blinks). Default `"initial"`. */
+    caret?: "hide" | "initial";
 }
 /** Encoding options for an element capture — `ScreenshotOptions` minus
  *  the page-geometry fields (`fullPage`, `clip`) that have no meaning for a
  *  single element. */
-type ElementScreenshotOptions = Pick<ScreenshotOptions, "type" | "quality">;
+type ElementScreenshotOptions = Pick<ScreenshotOptions, "type" | "quality" | "animations" | "caret">;
+/** A rectangle in the PIXELS of a capture (device pixels, the capture's own
+ *  origin) — where an element lies in a screenshot. */
+interface CaptureRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Which capture a `CaptureRect` is measured in. */
+type CaptureFrame = {
+    kind: "viewport";
+} | {
+    kind: "fullPage";
+} | {
+    kind: "element";
+    loc: LocatorValue;
+};
 interface CookieOptions {
     domain?: string;
     path?: string;
@@ -250,7 +288,12 @@ interface CookieOptions {
  *  dismisses every dialog on behalf of the client that has none — and a
  *  second client watching the run's page would answer `confirm()` with
  *  "no" before the run's own accept lands. */
-type AttachOptions = Pick<ContextOptions, "dialogPolicy">;
+interface AttachOptions extends Pick<ContextOptions, "dialogPolicy"> {
+    /** The browser's id of the context to attach to (CDP `browserContextId`,
+     *  as the run publishes it). Unset, or not found → the first context
+     *  with an open page, as before. */
+    contextId?: string;
+}
 
 interface WebDriver {
     /**
@@ -280,7 +323,7 @@ interface WebDriver {
      */
     wsEndpoint(): string | undefined;
     connectShared(wsEndpoint: string, browser: LaunchOptions["browser"]): Promise<void>;
-    attachExisting(opts?: AttachOptions): DriverContext;
+    attachExisting(opts?: AttachOptions): Promise<DriverContext>;
 }
 /** One captured network request/response, recorded only under
  *  `UNOTEST_NETWORK`. `status`/`ok` come from the response; `failureText`
@@ -298,6 +341,100 @@ interface NetworkEntry {
     /** Total request→response-end time (ms), from Playwright request timing. */
     durationMs?: number;
     timestamp: string;
+    /** The request never reached the network: a `mockRoute` answered or
+     *  aborted it. Absent for requests a mock let through. */
+    mocked?: true;
+}
+/** A file a page of the context downloaded. The bytes stay with the
+ *  browser until `saveAs` copies them out. */
+interface DriverDownload {
+    /** The name the site suggested (`Content-Disposition`, `download`). */
+    readonly name: string;
+    /** Copy the file to `path` (absolute); resolves once it is written. */
+    saveAs(path: string): Promise<void>;
+}
+/** Which downloads `waitForDownload` accepts, by suggested name. `describe`
+ *  is an infinitive for the timeout message ("contain \"report\""). */
+interface DownloadNameFilter {
+    matches(name: string): boolean;
+    describe(): string;
+}
+/** A fake clock shared by every page of a context. Time runs by itself
+ *  until `freeze`, and again after `run`. */
+interface DriverClock {
+    /** Stop time at `at`: `Date` reads it, and no timer fires until `tick`
+     *  or `run`. Any instant, past or future — no timer fires on the way. */
+    freeze(at: Date): Promise<void>;
+    /** Advance frozen time by `ms`, firing every timer due in it. */
+    tick(ms: number): Promise<void>;
+    /** Let time run again from where it stands. */
+    run(): Promise<void>;
+    /** Whether time stands still now (after `freeze`, before `run`). While
+     *  it does, `requestAnimationFrame` does not fire either — a wait for a
+     *  painted frame would wait for nothing. */
+    frozen(): boolean;
+}
+/** What a mocked route does with a request it catches. */
+type RouteResponse = {
+    kind: "fulfill";
+    status: number;
+    body: string;
+    contentType?: string;
+    headers: Readonly<Record<string, string>>;
+}
+/** `record` keeps every aborted request, for `blocked` to report. */
+ | {
+    kind: "abort";
+    record: boolean;
+} | {
+    kind: "continue";
+};
+/** A request as the page sent it. */
+interface CapturedRequest {
+    url: string;
+    method: string;
+    headers: Readonly<Record<string, string>>;
+    /** The body as sent, or null when there is none. */
+    postData: string | null;
+    /** The body parsed as JSON, or null when it is absent or not JSON. */
+    postDataJson: unknown;
+}
+/** A service worker of the context — an MV3 extension's background. MV3
+ *  puts an idle worker to sleep, so a handle is good for the call at hand:
+ *  ask the context for the worker again next time. */
+interface DriverWorker {
+    url(): string;
+    /** Like `DriverPage.evaluate`, in the worker: a function source is
+     *  CALLED with `arg`. */
+    evaluate<T = unknown>(js: string, arg?: unknown): Promise<T>;
+}
+/** A request a recording abort stopped, with when it was stopped. */
+interface BlockedRequest {
+    url: string;
+    method: string;
+    /** Epoch milliseconds. */
+    at: number;
+}
+/** The context's route mocks. Masks use Playwright's URL glob syntax;
+ *  where several match one request, the one mocked last answers it, and
+ *  mocking a mask again replaces its answer and makes it the latest.
+ *  Mocks last as long as the context. */
+interface DriverNetwork {
+    mock(glob: string, response: RouteResponse): Promise<void>;
+    /** Take off the mock at `glob`, or every mock when it is omitted.
+     *  What a recording abort kept stays readable through `blocked`. */
+    unmock(glob?: string): Promise<void>;
+    /** The next request matching `glob` not yet returned by an earlier
+     *  wait. A mocked mask keeps its requests from the moment it was
+     *  mocked, so one sent before the wait is still found; any other mask
+     *  sees requests from the call on. Throws TimeoutError after `timeoutMs`. */
+    waitForRequest(glob: string, opts: {
+        timeoutMs: number;
+    }): Promise<CapturedRequest>;
+    /** The requests stopped by the recording abort at `glob`. Throws when
+     *  `glob` was never mocked with a recording abort: an empty answer
+     *  would then mean "nothing was watched", not "nothing left". */
+    blocked(glob: string): ReadonlyArray<BlockedRequest>;
 }
 interface DriverContext {
     /** Currently-open tabs/windows in this context. Index 0 = first opened. */
@@ -306,8 +443,26 @@ interface DriverContext {
     activePage(): DriverPage;
     /** Switch the active page index (D-4 setPage). 0 = first opened, etc.
      *  Implementations MUST also reset the frame stack — a frame scope
-     *  established on tab A is not valid on tab B. */
-    setActivePage(index: number): Promise<void>;
+     *  established on tab A is not valid on tab B. `activate: false` moves
+     *  only the runner's target and leaves the browser's front tab as is
+     *  (default `true`: the tab is brought to front too). */
+    setActivePage(index: number, opts?: {
+        activate?: boolean;
+    }): Promise<void>;
+    /** Bring a tab to front — the browser's visible tab, not the runner's
+     *  target. Absent index → the active page. Throws `DriverError` on an
+     *  index no open tab has. */
+    bringToFront(index?: number): Promise<void>;
+    /** Open a blank tab in this context and make it the active page (brought
+     *  to front, frame stack reset). It counts as handed: `waitForNewPage`
+     *  never returns it. Resolves with its index. */
+    newPage(): Promise<number>;
+    /** Close a tab. Absent index → the active page. Closing the active page
+     *  makes the page that was active before it active again (the one at the
+     *  index below when that one is gone); closing another tab keeps the
+     *  active page. Throws `DriverError` on an index no open tab has, and on
+     *  the only open tab — nothing would be left to drive. */
+    closePage(index?: number): Promise<void>;
     /**
      * Subscribe to new-page events. Listener fires when a tab/window opens
      * in this context (`target="_blank"`, `window.open`, etc.). Returns an
@@ -322,6 +477,17 @@ interface DriverContext {
         index: number;
         url: string;
     }) => void): () => void;
+    /**
+     * Resolve with the index of the first open tab the scenario has not been
+     * handed yet, waiting up to `timeoutMs` (default: the navigation budget)
+     * for one to open. "Handed" = open when the context started, switched to
+     * by `setActivePage`, or returned here before — so a tab opened by a click
+     * a step earlier still counts, and no tab is returned twice. Throws
+     * `TimeoutError` naming how many tabs are open. Does not switch to it.
+     */
+    waitForNewPage(opts?: {
+        timeoutMs?: number;
+    }): Promise<number>;
     /**
      * Enter a frame scope (D-4 stateful pair). All subsequent locators
      * resolve inside this frame until `exitFrame()` is called. Stacks (calling
@@ -334,6 +500,32 @@ interface DriverContext {
      *  before auto-switching to a popup (frame scope does not survive tab
      *  changes). */
     frameDepth(): number;
+    /**
+     * Resize every open page of this context, and every page it opens after
+     * this call. Width and height only: the device scale factor is fixed when
+     * the context is created — changing it would mean a new context and the
+     * loss of the page, which a resize must never cost.
+     */
+    setViewport(size: ViewportSize): Promise<void>;
+    /** The browser's own id of this context (CDP `browserContextId`), the
+     *  same in every process connected to the browser — or null where the
+     *  engine has no such id to give (Firefox, WebKit) or no page is open. */
+    browserContextId(): Promise<string | null>;
+    /** The page clock. Works only on a context opened with `clock: true`
+     *  (the fake clock must be in place before the first page loads, or the
+     *  page's own timers stay real) — otherwise every call throws
+     *  ClockNotInstalledError. */
+    clock(): DriverClock;
+    /** Route mocks of this context: every page, tab and frame of it. */
+    network(): DriverNetwork;
+    /** A running service worker whose URL matches `url` (substring or
+     *  regex; any when omitted), or the first to start within `timeoutMs`
+     *  (default: the context's navigation timeout). Throws at once on a
+     *  context without a browser profile — extensions never load there. */
+    waitForServiceWorker(opts?: {
+        timeoutMs?: number;
+        url?: Matcher;
+    }): Promise<DriverWorker>;
     /** Typed storage shortcuts (D-6). */
     setLocalStorage(key: string, value: string): Promise<void>;
     getLocalStorage(key: string): Promise<string | null>;
@@ -364,6 +556,18 @@ interface DriverContext {
      * `network.json` for the viewer's Network tab.
      */
     networkEntries(): ReadonlyArray<NetworkEntry>;
+    /**
+     * The first download of this context the scenario has not taken yet,
+     * waiting up to `timeoutMs` (default: the navigation budget) for one.
+     * Downloads are recorded from the moment the context opens, on every
+     * page, so one a click started before this call is not lost. `name`
+     * narrows to downloads whose suggested file name it accepts. Each
+     * download is handed out once. Throws `TimeoutError` when none comes.
+     */
+    waitForDownload(opts?: {
+        timeoutMs?: number;
+        name?: DownloadNameFilter;
+    }): Promise<DriverDownload>;
     /** Close all pages in this context. Idempotent. */
     close(): Promise<void>;
 }
@@ -404,6 +608,9 @@ interface DriverPage {
      *  `value` is the submitted payload ("on" by default), never its state. */
     checkedState(loc: LocatorValue): Promise<boolean | null>;
     isVisible(loc: LocatorValue): Promise<boolean>;
+    /** Where the matched element lies in the viewport, CSS pixels; `null`
+     *  when it is not rendered (display:none, detached). No scrolling. */
+    boundingBox(loc: LocatorValue): Promise<BoundingBox | null>;
     /** Disabled state of the matched element: native `:disabled` (covers
      *  fieldset inheritance) OR `aria-disabled="true"`. Boolean attributes
      *  are invisible through `getAttribute` (`""` present vs `null` absent
@@ -437,12 +644,21 @@ interface DriverPage {
      *  CALLED with `arg` — that is the documented multi-arg escape hatch
      *  (`evaluate('function([a, b]) { … }', 1, 2)`). */
     evaluate<T = unknown>(js: string, arg?: unknown): Promise<T>;
-    evaluateOnLocator<T = unknown>(loc: LocatorValue, js: string): Promise<T>;
+    /** `evaluate` on the matched element: a function body is called with
+     *  the element and `arg`. */
+    evaluateOnLocator<T = unknown>(loc: LocatorValue, js: string, arg?: unknown): Promise<T>;
     screenshot(opts?: ScreenshotOptions): Promise<Buffer>;
     /** Capture ONE element (first match, scrolled into view) instead of the
      *  viewport — the evidence shot of a card / row / dialog. Same encoding
      *  options as `screenshot`; `fullPage` / `clip` don't apply. */
     screenshotElement(loc: LocatorValue, opts?: ElementScreenshotOptions): Promise<Buffer>;
+    /** Where each element lies in a capture of `frame`, in that capture's
+     *  pixels (device pixel ratio, page scroll and the element's own box
+     *  applied) — the masks of the visual assert. Each locator must match
+     *  exactly one element (a locator that matches none is an error, not a
+     *  skipped mask); an element that is not rendered has no box and is
+     *  left out. */
+    boxesInCapture(locs: readonly LocatorValue[], frame: CaptureFrame): Promise<CaptureRect[]>;
     inspectElement(loc: LocatorValue, opts?: InspectElementOptions): Promise<ElementHint | null>;
     /** HTML of the element the locator matches (first match), redacted like
      *  page.html — secret and hidden field values and script content become
@@ -458,6 +674,13 @@ interface DriverPage {
  * optional — an element might have only a role+name, or only a testId,
  * or nothing stable at all (in which case the resolver throws).
  */
+/** An element's box in the viewport, CSS pixels — Playwright's shape. */
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 /** How `inspectElement` reads the element's `readable` text. By default
  *  whitespace folded and clipped to 200 — a hint. `whole` keeps the text as
  *  it is, up to `limit` characters, for a refusal that quotes it (#256). */
@@ -565,4 +788,4 @@ interface AncestorHint {
     className?: string;
 }
 
-export { type AttachOptions as A, type ContextOptions as C, type DriverContext as D, type ElementHint as E, type FillOptions as F, type GotoOptions as G, type HoverOptions as H, type LaunchOptions as L, type NetworkEntry as N, type PressOptions as P, type ReloadOptions as R, type ScreenshotOptions as S, type Viewport as V, type WebDriver as W, type ActionTimeout as a, type CheckOptions as b, type ClickOptions as c, type CookieOptions as d, type DriverPage as e, type NavigationOptions as f, type SelectOptions as g, type WaitOptions as h, type WaitState as i, type LocatorValue as j, type LocatorStep as k, appendStep as l, describeLocator as m, isLocatorValue as n, rootedAt as r };
+export { type AttachOptions as A, type BoundingBox as B, type CaptureFrame as C, type DriverContext as D, type ElementHint as E, type FillOptions as F, type GotoOptions as G, type HoverOptions as H, type LocatorValue as L, type NetworkEntry as N, type PressOptions as P, type ReloadOptions as R, type ScreenshotOptions as S, type Viewport as V, type WebDriver as W, type CaptureRect as a, type LaunchOptions as b, type ContextOptions as c, type ActionTimeout as d, type CheckOptions as e, type ClickOptions as f, type CookieOptions as g, type DriverPage as h, type NavigationOptions as i, type SelectOptions as j, type ViewportSize as k, type WaitOptions as l, type WaitState as m, type DriverDownload as n, type LocatorStep as o, appendStep as p, describeLocator as q, isLocatorValue as r, rootedAt as s };