@unotest/web 0.44.0 → 0.45.0

package/types/unotest-dsl.d.ts

@@ -238,6 +238,13 @@ declare function assertJudge(locator: Locator, rubric: string): void;
  */
 declare function assertScreenshot(nameOrLocator: any, nameOrOptions?: any, options?: any): void;
 
+/**
+ * assertEqual(actual, expected)
+ *
+ * Deep equality as JSON sees it: key order does not count, a missing key differs from a null one. FAILS naming the first differing path (`chat.labels[0].send`) with both values, plus a line diff of the two sides. The DSL form of toEqual.
+ */
+declare function assertEqual(actual: any, expected: any): void;
+
 /**
  * assertTrue(condition, message?)
  *
@@ -302,11 +309,46 @@ declare function note(label: string, value: any): void;
 declare function evaluate(jsBody: string, ...args: unknown[]): any;
 
 /**
- * setPage(index)
+ * evaluateOnLocator(locator, js, ...args) → any
+ *
+ * Like evaluate, on the matched element: the body is called with the element, then the extra arguments by the same rule (`(el, x) => …`, two or more → `(el, [a, b]) => …`). Last resort — prefer typed getters.
+ */
+declare function evaluateOnLocator(locator: Locator, jsBody: string, ...args: unknown[]): any;
+
+/**
+ * setPage(index, options?)
+ *
+ * Switch the active tab/page by index (0-based) and bring it to front. {activate: false} switches only the tab the steps act on and leaves the visible tab as is.
+ */
+declare function setPage(indexOrTitle: string | number, options?: any): void;
+
+/**
+ * waitForPage(options?) → number
+ *
+ * Wait for a tab the scenario has not been handed yet (window.open, target=_blank, an extension), switch to it and return its index. Counts a tab that opened before the call. {timeoutMs} defaults to the navigation timeout.
+ */
+declare function waitForPage(options?: any): number;
+
+/**
+ * bringToFront(index?)
+ *
+ * Bring a tab to front — the visible one — without changing the tab the steps act on. No index: the active tab.
+ */
+declare function bringToFront(index?: number): void;
+
+/**
+ * newPage(url?) → number
+ *
+ * Open a new tab in the active browser context, make it active and return its index. With a url the tab opens it (relative to the base URL, as goto).
+ */
+declare function newPage(url?: string): number;
+
+/**
+ * closePage(index?)
  *
- * Switch the active tab/page by index (0-based).
+ * Close a tab; no index: the active one. Closing the active tab makes the tab that was active before it active again. The only open tab cannot be closed.
  */
-declare function setPage(indexOrTitle: string | number): void;
+declare function closePage(index?: number): void;
 
 /**
  * setViewport({width, height})
@@ -511,6 +553,27 @@ declare function today(): string;
  */
 declare function daysFromNow(days: number): string;
 
+/**
+ * textMatches(text, /re/) → false | string[]
+ *
+ * First match of a regex literal: false on a miss, else `[whole, group1, …]` (a group that took no part is null). The array is truthy, so it also reads as a test: `m = textMatches(url, /room=(\d+)/); id = m[1];`. For a plain substring use textContains.
+ */
+declare function textMatches(text: string, pattern: any): any;
+
+/**
+ * parseJson(text) → any
+ *
+ * Parse a JSON string (an api body, a data attribute, a request's postData) into a value you walk with `.` and `[]`. FAILS on invalid JSON, quoting the input; an empty string is not JSON.
+ */
+declare function parseJson(text: string): any;
+
+/**
+ * urlParam(url, key) → string | null
+ *
+ * A query parameter of a URL, decoded; null when the key is absent, '' when it is empty. A path without a host (`/room?id=7`) works too. The DSL form of `new URL(u).searchParams.get(key)`.
+ */
+declare function urlParam(url: string, key: string): any;
+
 /**
  * shell(cmd, ...args, options?) → { stdout, stderr, code }
  *
@@ -553,6 +616,27 @@ declare function assertNoJsonLine(path: string, filter: any, options?: any): voi
  */
 declare function readJsonLine(path: string, filter: any): any;
 
+/**
+ * readJson(path) → any
+ *
+ * A whole JSON file, read once and parsed: app constants a build script exported, fixture objects. Path is relative to config `shellCwd` and must stay inside it. FAILS at once when the path leaves the project, the file is missing or it is not valid JSON. Walk the result with `.` and `[]`.
+ */
+declare function readJson(path: string): any;
+
+/**
+ * readFile(path, options?) → string
+ *
+ * A whole file, read once: its text, or its bytes as base64 with {encoding: 'base64'}. Path is relative to config `shellCwd`, or absolute inside the project or to a file waitForDownload saved (its .path). FAILS at once when the path or a symlink leads out, the file is missing or the encoding is unknown.
+ */
+declare function readFile(path: string, options?: any): string;
+
+/**
+ * readFileInfo(path) → object
+ *
+ * What to assert about a file without reading it: {size} in bytes, plus png: {width, height} for a PNG (from its header). Same path rules and failures as readFile.
+ */
+declare function readFileInfo(path: string): any;
+
 /**
  * waitForFileCount(path, pattern, count, options?) → number
  *
@@ -679,6 +763,13 @@ declare function getInnerText(locator: Locator): string;
  */
 declare function getInputValue(locator: Locator): string;
 
+/**
+ * boundingBox(locator) → {x, y, width, height} | null
+ *
+ * Where the element lies in the viewport, CSS pixels; null when it is not rendered (display:none, detached). Does not scroll.
+ */
+declare function boundingBox(locator: Locator): any;
+
 /**
  * getTitle() → string
  *
@@ -756,6 +847,13 @@ declare function waitForCount(locator: Locator, count: number, options?: any): v
  */
 declare function pause(ms: number): void;
 
+/**
+ * waitForDownload(options?) → { path, name }
+ *
+ * The first file the page downloaded that the scenario has not taken yet, saved with the run: `path` is absolute (read it with waitForFile), `name` is the name the site suggested. Downloads are recorded from the start, so click first, then call this. options: {timeoutMs} (default: the navigation timeout), {name} (substring or regex of the file name).
+ */
+declare function waitForDownload(options?: any): any;
+
 /**
  * clockFreeze(iso)
  *
@@ -777,6 +875,55 @@ declare function clockTick(ms: number): void;
  */
 declare function clockRun(): void;
 
+/**
+ * mockRoute(glob, response)
+ *
+ * From now on, requests matching `glob` (a Playwright URL glob: `**\/api/items*`) get a fixed answer: `{status?, body?, headers?, contentType?}` (an object body goes as JSON), `{abort: true, record?}` or `{continue: true}` (to the network). Where several masks match, the one mocked last answers; mocking a mask again replaces its answer. A response to `**\/*` is refused; the site's own page is never aborted. Mocks last until the scenario ends.
+ */
+declare function mockRoute(glob: string, response: any): void;
+
+/**
+ * unmockRoute(glob?)
+ *
+ * Take off the mock at `glob`, or every mock when called without one.
+ */
+declare function unmockRoute(glob?: string): void;
+
+/**
+ * waitForRequest(glob, { timeoutMs? }) → { url, method, headers, postData, postDataJson }
+ *
+ * Wait for a request matching `glob` and return it; `postDataJson` is the body read as JSON (null when it is not). On a mocked mask it also finds a request sent before the call, each one returned once; on any other mask only requests from the call on. Default timeout 20 s.
+ */
+declare function waitForRequest(glob: string, options?: any): any;
+
+/**
+ * assertNoRequest(glob, { since? })
+ *
+ * FAIL if the recording abort at `glob` — mockRoute(glob, {abort: true, record: true}) — stopped any request; with `since` (epoch ms, from nowMs()) only from then on. A mask without a recording abort is an error, not a pass.
+ */
+declare function assertNoRequest(glob: string, options?: any): void;
+
+/**
+ * waitForServiceWorker({ timeoutMs?, url? }) → string
+ *
+ * Wait for a browser extension's service worker and return its URL (`chrome-extension://<id>/sw.js`); a running one comes back at once. `url` — substring or /regex/ when several extensions run. Extensions load only with `launch.userDataDir`: without it the call fails at once.
+ */
+declare function waitForServiceWorker(options?: any): string;
+
+/**
+ * extensionId() → string
+ *
+ * The id of the extension whose service worker runs — for `goto('chrome-extension://' + extensionId() + '/popup.html')`.
+ */
+declare function extensionId(): string;
+
+/**
+ * evaluateInServiceWorker(js, ...args) → any
+ *
+ * Like evaluate, in the extension's service worker — the way to `chrome.storage`, `chrome.tabs`, `chrome.runtime`. Same argument and JSON-return rules; waits for the worker if none runs. Each call finds the worker anew: MV3 stops an idle one.
+ */
+declare function evaluateInServiceWorker(jsBody: string, ...args: unknown[]): any;
+
 /** step(label, [options,] body)
  *
  *  Groups statements under a labelled block. Every direct child of a