@unotest/web 0.44.0 → 0.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/web",
-  "version": "0.44.0",
+  "version": "0.46.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": {
@@ -77,6 +77,7 @@
   "dependencies": {
     "@faker-js/faker": "^10.5.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "ajv": "^8.20.0",
     "chokidar": "^4.0.3",
     "dotenv": "^16.4.5",
     "playwright": "1.62.1",
@@ -84,18 +85,18 @@
     "tsx": "^4.19.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8",
-    "@unotest/dsl": "^0.44.0",
-    "@unotest/core": "^0.44.0",
-    "@unotest/viewer": "^0.44.0",
-    "@unotest/grounder-client": "^0.44.0",
-    "@unotest/protocol": "^0.44.0"
+    "@unotest/core": "^0.46.0",
+    "@unotest/dsl": "^0.46.0",
+    "@unotest/protocol": "^0.46.0",
+    "@unotest/viewer": "^0.46.0",
+    "@unotest/grounder-client": "^0.46.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "javascript-obfuscator": "^4.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.2",
-    "@unotest/judge": "^0.44.0",
-    "@unotest/grounder": "^0.44.0"
+    "@unotest/judge": "^0.46.0",
+    "@unotest/grounder": "^0.46.0"
   }
 }

package/types/unotest-dsl.d.ts

@@ -92,7 +92,7 @@ interface Locator {
 }
 
 /**
- * click(locator, { force?, timeout?, noWaitAfter? })
+ * click(locator, { force?, timeout?, position?, modifiers?, button?, clickCount? })
  *
  * Click an element.
  */
@@ -134,7 +134,7 @@ declare function hover(locator: Locator, options?: any): void;
 declare function scrollIntoView(locator: Locator, options?: any): void;
 
 /**
- * fill(locator, value, { timeout?, noWaitAfter? })
+ * fill(locator, value, { force?, timeout? })
  *
  * Clear and type a value into an input.
  */
@@ -176,11 +176,25 @@ declare function uploadFile(input: Locator, files: any): void;
 declare function clipboardPaste(target: Locator, text: string): void;
 
 /**
- * assertText(locator, expected, { exact?, timeout? })
+ * assertText(locator, expected, { exact?, not?, timeout? })
  *
- * Element's text equals/contains `expected`.
+ * Element's text equals `expected` (a string; exact: false — contains it) or matches it (a /regex/). {not: true} waits until it no longer does. Empty: assertText(loc, ''); not empty: assertText(loc, '', {not: true}).
  */
-declare function assertText(locator: Locator, text: string, options?: any): void;
+declare function assertText(locator: Locator, text: string | RegExp, options?: any): void;
+
+/**
+ * assertTexts(locator, expected, { exact?, timeout? })
+ *
+ * The locator matches exactly expected.length elements, and element i's text matches expected[i] (string or /regex/, same rules as assertText), in order.
+ */
+declare function assertTexts(locator: Locator, texts: unknown[], options?: any): void;
+
+/**
+ * assertAttribute(locator, name, expected, { exact?, not?, timeout? })
+ *
+ * Polls the attribute `name` until it equals `expected` (exact: false — contains) or matches a /regex/. An absent attribute matches nothing. {not: true} waits until it no longer matches or is gone.
+ */
+declare function assertAttribute(locator: Locator, name: string, value: string | RegExp, options?: any): void;
 
 /**
  * assertVisible(locator, { timeout? })
@@ -238,6 +252,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?)
  *
@@ -245,6 +266,27 @@ declare function assertScreenshot(nameOrLocator: any, nameOrOptions?: any, optio
  */
 declare function assertTrue(condition: boolean, message?: string): void;
 
+/**
+ * assertSchema(value, schema)
+ *
+ * Check a value against a JSON Schema (draft 2020-12), e.g. one your app generates from its zod schemas: assertSchema(res.body, readJson('unotest/fixtures/message.schema.json')). FAILS naming every broken field by path (`/items/0/id`) with what is wrong. External $ref is refused; `format` is not checked.
+ */
+declare function assertSchema(value: any, schema: any): void;
+
+/**
+ * skip(reason, condition?)
+ *
+ * End the test as skipped when the condition is true (always, without one) — it does not apply here: skip('no live API configured', env('LIVE_API') == null). The run reports skipped with the reason, not passed and not failed; teardown blocks already registered still play. A test guard: at the level of the test_* body, next to its steps, not inside one.
+ */
+declare function skip(reason: string, condition?: boolean): void;
+
+/**
+ * setTestTimeout(ms)
+ *
+ * This test's own time budget, counted from its start (Playwright's test.setTimeout). Replaces config testTimeoutMs and UNOTEST_MAX_DURATION_MS for this test. A deadline: an action still running when it runs out is cut, the test fails naming the budget, teardown blocks still play. Only in a test_* body.
+ */
+declare function setTestTimeout(ms: number): void;
+
 /**
  * filter(locator, { hasText?, hasNotText?, has?, hasNot? })
  *
@@ -294,6 +336,27 @@ declare function screenshot(name?: string, options?: any): string;
  */
 declare function note(label: string, value: any): void;
 
+/**
+ * consoleEntries({ level?, since? }) → [{ level, text, url }]
+ *
+ * What the active page wrote to its console, oldest first: `level` is log, info, warn, error or debug. Recorded from the moment the page opened, so act first, then ask. Extension pages (chrome-extension://) too. options: {level} (one level or a list), {since} (epoch ms, from nowMs()).
+ */
+declare function consoleEntries(options?: any): any;
+
+/**
+ * pageErrors({ since? }) → [{ message, stack }]
+ *
+ * Errors the active page threw and nothing caught (an uncaught exception, a rejected promise), oldest first; `stack` is empty when the browser gave none. options: {since} (epoch ms, from nowMs()).
+ */
+declare function pageErrors(options?: any): any;
+
+/**
+ * assertNoConsoleErrors({ includePageErrors?, since? })
+ *
+ * FAIL when the active page logged console errors, or threw uncaught ones (unless {includePageErrors: false}), quoting the first three. With `since` (epoch ms, from nowMs()) only from then on.
+ */
+declare function assertNoConsoleErrors(options?: any): void;
+
 /**
  * evaluate(js, arg?) → any
  *
@@ -302,11 +365,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
  *
- * Switch the active tab/page by index (0-based).
+ * 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 setPage(indexOrTitle: string | number): void;
+declare function newPage(url?: string): number;
+
+/**
+ * closePage(index?)
+ *
+ * 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 closePage(index?: number): void;
 
 /**
  * setViewport({width, height})
@@ -511,6 +609,34 @@ 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;
+
+/**
+ * env(name) → string | null
+ *
+ * An environment value the test can do without: the ambient environment, unotest/.env or .secrets, as a bare UPPER_SNAKE name reads it — but null when unset instead of failing. For deciding on it: if (env('LIVE_API') == null) { … }. A secret is refused; write its bare name where the value is typed.
+ */
+declare function env(name: string): any;
+
 /**
  * shell(cmd, ...args, options?) → { stdout, stderr, code }
  *
@@ -553,6 +679,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 +826,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 +910,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 +938,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