@unotest/web 0.43.2 → 0.44.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-DEmGI704.js';
 import '../config/schema.js';
 import 'zod';
 

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

@@ -91,13 +91,27 @@ 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;
+    /** 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;
     viewport?: Viewport;
+    /** 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 +245,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 +287,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 +322,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`
@@ -299,6 +341,21 @@ interface NetworkEntry {
     durationMs?: number;
     timestamp: 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;
+}
 interface DriverContext {
     /** Currently-open tabs/windows in this context. Index 0 = first opened. */
     pages(): ReadonlyArray<DriverPage>;
@@ -334,6 +391,22 @@ 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;
     /** Typed storage shortcuts (D-6). */
     setLocalStorage(key: string, value: string): Promise<void>;
     getLocalStorage(key: string): Promise<string | null>;
@@ -443,6 +516,13 @@ interface DriverPage {
      *  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
@@ -565,4 +645,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 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 LocatorStep as n, appendStep as o, describeLocator as p, isLocatorValue as q, rootedAt as r };