@unotest/web 0.43.2 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/web",
-  "version": "0.43.2",
+  "version": "0.45.0",
   "description": "AI-native E2E testing for web applications. MCP server (run_test / step / resume / inspect_runtime / agent_fix) + CLI runner + JavaScript DSL scenarios on a sandboxed AST engine + semantic DOM snapshots.",
   "license": "MIT",
   "publishConfig": {
@@ -80,21 +80,22 @@
     "chokidar": "^4.0.3",
     "dotenv": "^16.4.5",
     "playwright": "1.62.1",
+    "pngjs": "7.0.0",
     "tsx": "^4.19.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8",
-    "@unotest/core": "^0.43.2",
-    "@unotest/dsl": "^0.43.2",
-    "@unotest/grounder-client": "^0.43.2",
-    "@unotest/protocol": "^0.43.2",
-    "@unotest/viewer": "^0.43.2"
+    "@unotest/core": "^0.45.0",
+    "@unotest/dsl": "^0.45.0",
+    "@unotest/protocol": "^0.45.0",
+    "@unotest/viewer": "^0.45.0",
+    "@unotest/grounder-client": "^0.45.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "javascript-obfuscator": "^4.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.2",
-    "@unotest/judge": "^0.43.2",
-    "@unotest/grounder": "^0.43.2"
+    "@unotest/grounder": "^0.45.0",
+    "@unotest/judge": "^0.45.0"
   }
 }

package/types/unotest-dsl.d.ts

@@ -231,6 +231,20 @@ declare function assertUrl(pattern: string): void;
  */
 declare function assertJudge(locator: Locator, rubric: string): void;
 
+/**
+ * assertScreenshot(name | locator, name?, { maxDiffRatio?, threshold?, mask?, ignore?, fullPage? })
+ *
+ * The page (or an element) against the PNG baseline unotest/e2e/<scenario>.screenshots/<name>.png. A pixel differs when any channel differs by more than threshold (default 32); fails when the share of differing pixels is MORE than maxDiffRatio (default 0). mask: locators, ignore: rectangles in baseline pixels — both left out of the comparison. No baseline: fails and saves the snapshot as a candidate; accept with e2e --update-screenshots. On failure the run keeps expected / actual / diff.
+ */
+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?)
  *
@@ -295,11 +309,67 @@ 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})
+ *
+ * Resize every tab of the browser, and the ones it opens later, without reloading. The scale (deviceScaleFactor) is set in the config, not here.
+ */
+declare function setViewport(size: any): void;
+
+/**
+ * newContext() → number
+ *
+ * Open another browser context — a separate client with its own cookies, storage and tabs — and make it active. Returns its number (the run's own is 0).
+ */
+declare function newContext(): number;
+
+/**
+ * setContext(index)
+ *
+ * Make browser context `index` active. Each keeps its own tab and frame, so switching back lands where it was.
+ */
+declare function setContext(index: number): void;
 
 /**
  * enterFrame(locator)
@@ -483,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 }
  *
@@ -525,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
  *
@@ -651,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
  *
@@ -728,6 +847,83 @@ 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)
+ *
+ * Stop time on the page at an ISO instant: `Date` reads it and no timer fires until clockTick / clockRun. Any instant, past or future.
+ */
+declare function clockFreeze(iso: string): void;
+
+/**
+ * clockTick(ms)
+ *
+ * Move frozen time forward by ms, firing every timer due in it.
+ */
+declare function clockTick(ms: number): void;
+
+/**
+ * clockRun()
+ *
+ * Let time on the page run again from where it stands.
+ */
+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