@unotest/web 0.44.0 → 0.46.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-DEmGI704.js';
+import { E as ElementHint } from '../interfaces-CYoL4Taq.js';
 import '../config/schema.js';
 import 'zod';
 

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

@@ -88,6 +88,10 @@ interface LaunchOptions {
      *  persistent context, which every `newContext()` then returns
      *  (`config.launch.userDataDir`). */
     userDataDir?: string;
+    /** A new browser on a new profile directory for every context
+     *  (`config.launch.profile`); each `newContext()` then needs
+     *  `ContextOptions.profileDir`. */
+    profile?: "per-test";
     /** Extra browser command-line arguments (`config.launch.args`). */
     args?: string[];
 }
@@ -107,7 +111,8 @@ interface ContextOptions {
      *  name it does not know. Applied before `viewport`, which overrides the
      *  preset's size and scale field by field. */
     device?: string;
-    viewport?: Viewport;
+    /** `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. */
@@ -138,6 +143,10 @@ interface ContextOptions {
      * `UNOTEST_DEFAULT_NAVIGATION_TIMEOUT_MS` env overrides.
      */
     defaultNavigationTimeoutMs?: number;
+    /** The directory a `profile: "per-test"` browser starts on. The caller
+     *  makes it and decides whether it stays; given to any other launch it
+     *  is refused. */
+    profileDir?: string;
 }
 interface ActionTimeout {
     /** Override default action timeout (D-7 actionability wait). Milliseconds. */
@@ -323,6 +332,11 @@ interface WebDriver {
     wsEndpoint(): string | undefined;
     connectShared(wsEndpoint: string, browser: LaunchOptions["browser"]): Promise<void>;
     attachExisting(opts?: AttachOptions): Promise<DriverContext>;
+    /** True while the browser `connectShared` joined is still there. A run
+     *  on `launch.profile: "per-test"` closes it with each test and starts
+     *  the next one at the same endpoint, so a joined client asks this
+     *  before it follows the run. False when nothing is joined. */
+    sharedBrowserConnected(): boolean;
 }
 /** One captured network request/response, recorded only under
  *  `UNOTEST_NETWORK`. `status`/`ok` come from the response; `failureText`
@@ -340,6 +354,23 @@ 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`. */
@@ -356,6 +387,68 @@ interface DriverClock {
      *  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. */
     pages(): ReadonlyArray<DriverPage>;
@@ -363,8 +456,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
@@ -379,6 +490,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
@@ -407,6 +529,16 @@ interface DriverContext {
      *  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>;
@@ -426,10 +558,16 @@ interface DriverContext {
      * runner can pull the tail when a test fails.
      */
     consoleEntries(): ReadonlyArray<{
-        level: "log" | "info" | "warn" | "error" | "debug";
+        level: ConsoleLevel;
         text: string;
         timestamp: string;
     }>;
+    /** The console lines and uncaught errors of the ACTIVE page, oldest
+     *  first. Recorded always, from the moment the page opened — unlike
+     *  `consoleEntries()`, which only `UNOTEST_CONSOLE` fills — so a
+     *  scenario that clicks and then asks finds what the click logged.
+     *  Extension pages (`chrome-extension://`) are pages like any other. */
+    pageConsole(): PageConsole;
     /**
      * Snapshot of network request/response entries captured since context
      * creation, oldest first. Populated only when `UNOTEST_NETWORK` is on (else
@@ -437,6 +575,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>;
 }
@@ -477,6 +627,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
@@ -510,7 +663,9 @@ 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
@@ -538,6 +693,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). */
@@ -644,5 +806,26 @@ interface AncestorHint {
     /** A single stable, semantic class token (not a hash / utility class). */
     className?: string;
 }
+type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
+/** One console line of a page: `url` is the page's at the time, `at`
+ *  epoch ms — the scale `nowMs()` gives a scenario. */
+interface PageConsoleEntry {
+    level: ConsoleLevel;
+    text: string;
+    url: string;
+    at: number;
+}
+/** An error the page threw and nothing caught (`pageerror`). `stack` is
+ *  empty when the browser gave none. */
+interface PageErrorEntry {
+    message: string;
+    stack: string;
+    url: string;
+    at: number;
+}
+interface PageConsole {
+    entries: readonly PageConsoleEntry[];
+    errors: readonly PageErrorEntry[];
+}
 
-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 };
+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 PageConsole 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 PressOptions as j, type SelectOptions as k, type ViewportSize as l, type WaitOptions as m, type WaitState as n, type DriverDownload as o, type LocatorStep as p, appendStep as q, describeLocator as r, isLocatorValue as s, rootedAt as t };