@unotest/web 0.44.0 → 0.45.0

package/guides/dsl-reference.md

@@ -158,6 +158,7 @@ Two squiggle sources remain that typings cannot fix, both cosmetic:
 - [Storage](#storage) — localStorage / cookies
 - [Edge actions](#edge-actions) — drag, upload, paste
 - [Sandbox primitives](#sandbox-primitives) — shell / db / HTTP / files
+- [Network mocks](#network-mocks) — what the page's requests get
 - [Typed getters](#typed-getters) — page properties
 - [Generators](#generators) — random fixture data + time
 - [`evaluate`](#evaluate) — escape hatch into the page
@@ -191,6 +192,12 @@ from — write a separate plan if you need them
 escape sequences, `[...]` is a character class where `/` does not
 close the literal. No literal line breaks inside a regex body.
 
+## The `timeout` option
+
+Actions, navigation, waits and assertions take their time limit in
+milliseconds as `timeout` (`timeoutMs` is accepted too, the name the
+newer functions use); giving both in one call is refused.
+
 ---
 
 ## Builders
@@ -481,6 +488,19 @@ probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
 assertTrue(probe.code == 0, 'app.log should contain "ready"');
 ```
 
+### `assertEqual(actual, expected)`
+
+Deep equality, the way JSON sees the two values: key order does not
+count, and a missing key differs from a key set to `null`. The failure
+names the first path that differs and both values, then a line diff of
+the two sides:
+
+```js
+body = parseJson(getAttribute(locator('#state'), 'data-json'));
+assertEqual(body.controls, {theme: 'dark', devices: ['pixel']});
+// assertEqual: values differ at devices[0]: expected "pixel", got "iphone"
+```
+
 ### `assertJudge(loc, rubric)`
 
 LLM-judge assert for **free-form text** — chat replies, generated
@@ -748,6 +768,33 @@ not just native `:disabled`. This is the wait to reach for instead of a
 `for` loop around `pause()`: most legacy `pause` calls in a helper layer
 are surrogates for exactly this.
 
+### `waitUntil(() => condition, options?)` → the truthy value
+
+Poll a condition no single wait covers — a number crossing a threshold,
+an API answering the way the test needs. The body runs again and again
+until it is truthy; the call gives that value back.
+
+```js
+waitUntil(() => parseJson(textContent(getByTestId('count'))) >= 5);
+job = waitUntil(() => {
+  r = apiCall('GET', '/jobs/' + id);
+  if (r.body.state != 'done') { return false; }
+  return r.body;
+}, {timeoutMs: 30000, intervalMs: 500, label: 'job done'});
+```
+
+- The body is an arrow: an expression, or a block that gives its value
+  with `return`. A `return` there ends the wait, not the function
+  around it.
+- Options: `{ timeoutMs?, intervalMs?, label? }`. `timeoutMs` defaults
+  to the wait timeout of the run (`defaultTimeoutMs`), `intervalMs` to
+  250.
+- Only a falsy value is retried; an error inside the body fails the
+  step at once.
+- On timeout the step fails with the label, the number of tries and the
+  last value: `waitUntil "job done": still falsy after 30000 ms (60
+  tries); last value: false.`
+
 ### `waitForText(text, options?)`
 
 Wait until at least one **visible** element on the active page contains
@@ -881,13 +928,18 @@ An unknown zone or a malformed locale is refused when the config loads.
 
 ## Multi-context
 
-### `setPage(index)`
+### `setPage(index, options?)`
 
 Make tab `index` active. After this, every locator and assertion
 targets that tab. Resets the frame stack — a `setPage` always lands on
 the new tab's root document, never inside a frame inherited from the
 previous tab.
 
+By default the tab also comes to front, as a user would see it.
+`{activate: false}` switches only the tab the steps act on and leaves
+the visible tab as is — drive an extension panel in the background
+while the site stays in front. `bringToFront` shows a tab explicitly.
+
 Tabs open asynchronously: a click that triggers `window.open` (often
 after a `fetch`) registers the new tab a beat later. `setPage` waits for
 the tab at `index` to appear, then for its document to load, before
@@ -909,6 +961,70 @@ having to track tab indexes. See
 `docs/auto-page-switch/README.md`
 and `UNOTEST_POPUP_GRACE_MS` in `unotest/.env`.
 
+```js
+setPage(1, {activate: false});   // steps act on the panel tab
+click(getByRole('button', {name: 'Run'}));
+// tab 0 (the site) is still the one the browser shows
+```
+
+### `bringToFront(index?)`
+
+Bring tab `index` to front — the tab the browser shows — without
+changing the tab the steps act on. No index: the active tab. An index
+no open tab has fails with `page index out of range`.
+
+```js
+setPage(1, {activate: false});   // steps on tab 1, tab 0 in front
+bringToFront();                  // now tab 1 is shown too
+bringToFront(0);                 // show the site again; steps stay on 1
+```
+
+### `newPage(url?)` → `number`
+
+Open a new tab in the active browser context, make it active and bring
+it to front; returns its index. With `url` the tab opens it — a relative
+path resolves against the base URL, as in `goto`. Without one the tab
+stays blank. A tab `newPage` opened is the scenario's own: `waitForPage`
+never returns it.
+
+### `closePage(index?)`
+
+Close tab `index`; no index: the active tab. Closing the active tab
+makes the tab that was active before it active again (and brings it to
+front); if that one is closed too, the tab at the index below. Closing
+another tab leaves the steps where they are — later tabs move down one
+index. The only open tab cannot be closed: the step fails with
+`cannot close the only open tab`.
+
+```js
+newPage('/settings');           // tab 1, active
+assertUrl('/settings');
+closePage();                    // back on tab 0
+```
+
+### `waitForPage(options?)` → `number`
+
+Wait for a tab the scenario has not received yet, make it active and
+return its index. For tabs whose index you do not know up front: one a
+browser extension opens (`chrome.tabs.create`), one a click opens next
+to tabs already there. `waitForPage` returns the first tab the scenario
+has not received yet and waits if there is none. A tab counts as
+received when it was open as the test started, when `setPage` switched
+to it, or when an earlier `waitForPage` returned it. So a tab that
+opened before the call — a click a step earlier — still counts, and no
+tab is returned twice.
+
+`{timeoutMs}` defaults to `UNOTEST_DEFAULT_NAVIGATION_TIMEOUT_MS`. With
+no new tab within it, the step fails with
+`no new tab within 30000 ms, 1 tab open`.
+
+```js
+click(getByRole('button', {name: 'Open report'}));
+tab = waitForPage();                    // e.g. 1, now active
+assertUrl('/report');
+setPage(0);
+```
+
 ### `newContext()` → `number` / `setContext(index)`
 
 A second browser context: another client of the same app, with its own
@@ -999,6 +1115,10 @@ Both fields are required. Anything else is refused on that line,
 and changing it would need a new browser context — the page under test
 would be lost. See [Viewport and scale](#viewport-and-scale).
 
+`setViewport(null)` is refused too: once a size is set on an open page,
+Playwright keeps it, and nothing hands the page back to the window. For
+the real window, set `viewport: null` in the config.
+
 #### Viewport and scale
 
 Where the window's size and scale come from, first match wins:
@@ -1020,6 +1140,21 @@ Where the window's size and scale come from, first match wins:
    becomes a 780×1688 PNG, the scale design mockups are usually drawn
    at. Every field is optional; a missing one comes from the preset or
    the default.
+
+   `viewport: null` turns emulation off: the page is as wide as the real
+   browser window, and a resize of the window reaches the page. Headless
+   has no window manager — the size comes from `--window-size` in
+   `launch.args`:
+
+   ```js
+   export default {
+     viewport: null,
+     launch: { args: ["--window-size=1440,900"] },
+   };
+   ```
+
+   A `device` next to `viewport: null` is refused: a preset is a size and
+   a scale of its own.
 3. **A device preset.** `device: "iPhone 14"` applies Playwright's
    preset whole: size, scale, touch, mobile mode, user agent. The name
    is Playwright's, exactly; an unknown name is refused with the
@@ -1050,6 +1185,39 @@ exitFrame();
 
 Pop one iframe scope. Idempotent at depth 0.
 
+### Extensions — `waitForServiceWorker` / `evaluateInServiceWorker` / `extensionId`
+
+The background of a Chrome MV3 extension is a service worker, and
+`chrome.*` lives there. Extensions load only into a browser started on a
+profile — `launch.userDataDir` plus the `--load-extension` args in
+`unotest.config`; without one every call below fails at once, naming it.
+Headless needs `channel: "chromium"` (the headless shell ignores
+`--load-extension`).
+
+```js
+id = extensionId();
+evaluateInServiceWorker('(theme) => chrome.storage.local.set({theme: theme})', 'dark');
+stored = evaluateInServiceWorker('() => chrome.storage.local.get("theme")');
+goto('chrome-extension://' + id + '/popup.html');
+```
+
+- `waitForServiceWorker({timeoutMs?, url?})` → the worker's URL,
+  `chrome-extension://<id>/sw.js`. A running worker comes back at once;
+  otherwise it waits up to `timeoutMs` (default: the navigation timeout).
+  `url` — a substring or `/regex/` when several extensions run.
+- `evaluateInServiceWorker(js, ...args)` — `evaluate` in the worker, same
+  argument rules (one extra → the value, two or more → ONE array) and
+  JSON return; a returned Promise is awaited. Not discouraged by the
+  linter: `chrome.*` has no other way in.
+- `extensionId()` — the id out of the worker's URL.
+- MV3 stops an idle worker after ~30 s. Each call finds the worker anew,
+  so nothing goes stale between steps.
+- `mockRoute` answers the worker's own `fetch` too, but only on a
+  profile the browser opens for the first time. On a profile it opened
+  before, Playwright does not route the worker's requests, and the
+  worker reaches the network. A scenario that mocks them needs a fresh
+  `launch.userDataDir`.
+
 ---
 
 ## Storage
@@ -1185,6 +1353,37 @@ step("Start the listener", () => {
 });
 ```
 
+### `waitForDownload(options?)` → `{ path, name }`
+
+A file the page downloads — a link with `download`, a
+`Content-Disposition: attachment` response, a script-made blob. The
+browser records every download from the moment it opens, so the natural
+order works: click first, then ask. Returns the first download the
+scenario has not taken yet, waiting up to `{timeoutMs}` (default
+`UNOTEST_DEFAULT_NAVIGATION_TIMEOUT_MS`) when there is none. Each
+download is returned once.
+
+- `path` — absolute path of the saved copy. Read it with `waitForFile`,
+  which takes absolute paths as they are, or with `readFile` /
+  `readFileInfo`.
+- `name` — the file name the site suggested.
+- `{name}` — substring or regex of the file name. A download that does
+  not match stays for a later call.
+
+In a run the file is saved with the run, under `download/`, and the
+viewer lists it under the step as a link. Outside a run (explore) it is
+saved under `~/.cache/unotest/web/downloads/`. With no download in time
+the step fails: `no download within 30000 ms`, plus the names of
+downloads that are there but did not match.
+
+```js
+step("Export the report", () => {
+  click(getByRole('button', {name: 'Export CSV'}));
+  report = waitForDownload({name: /\.csv$/});
+  waitForFile(report.path, 'id,total');
+});
+```
+
 ### `waitForFile(path, pattern?, options?)` → `string`
 
 The file-side analogue of `waitForText` — polls a file until it exists
@@ -1280,6 +1479,71 @@ step("Ask control question 3", () => {
   background listener's output); its timeout is what makes that safe,
   and what would only hide a wrong path here.
 
+### `readJson(path)` → `any`
+
+Read a whole JSON file once and return the parsed value. Use it for data
+the scenario must not repeat by hand: constants your app keeps in source
+(labels, device lists, limits) that a build script exports to JSON, or a
+fixture object. Walk the result with `.` and `[]`.
+
+```js
+step("Send button uses the app's own label", () => {
+  shared = readJson('unotest/fixtures/shared.json');
+  assertVisible(getByRole('button', {name: shared.chat.labels[0].send}));
+});
+```
+
+- The path is relative to `sandbox.shellCwd` (the project root by
+  default), the same base `readJsonLine` uses. An absolute path, one
+  that climbs out with `../`, or a symlink that leads out of the project
+  is refused.
+- No poll: a missing file fails at once with `file not found: <path>`,
+  a file that does not parse with `<path> is not valid JSON: …`.
+- Scenarios cannot import your app's modules, and that is on purpose:
+  generate the JSON from them instead (see Scenarios, "App constants in
+  scenarios").
+
+### `readFile(path, options?)` → `string`
+
+Read a whole file once and return its content: the text by default, or
+the bytes as base64 with `{encoding: 'base64'}`. Use it where a test
+compares what a file holds: an exported CSV, the first bytes of a
+download.
+
+```js
+step("Export is a PNG", () => {
+  bytes = readFile('unotest/fixtures/files/image-3x2.png', {encoding: 'base64'});
+  assertTrue(textContains(bytes, 'iVBORw0KGgo'), 'not a PNG signature');
+});
+```
+
+- `options.encoding`: `'utf8'` (default) or `'base64'`. Any other value
+  or option key fails the step.
+- The path is relative to `sandbox.shellCwd` (the project root by
+  default), or absolute when it lies inside the project or is a file
+  `waitForDownload()` saved (`readFile(file.path)`). `../` out of the
+  project, an absolute path elsewhere, or a symlink that leads out is
+  refused.
+- No poll: a missing file fails at once with `file not found: <path>`.
+
+### `readFileInfo(path)` → `object`
+
+What a test asserts about a file without reading it whole, for example
+a downloaded image (`readFileInfo(waitForDownload().path)`):
+`{size}` in bytes, plus `png: {width, height}` when the file is a PNG.
+The dimensions come from the PNG header, so a large image is not read.
+
+```js
+step("Fixture image is 3x2", () => {
+  info = readFileInfo('unotest/fixtures/files/image-3x2.png');
+  assertTrue(info.png.width == 3 && info.png.height == 2, 'size: ' + info.size);
+});
+```
+
+- A file that is not a PNG has no `png` field.
+- Same path rules as `readFile`. A missing file fails with
+  `file not found: <path>`; a directory cannot be read and says so.
+
 ### `waitForFileCount(path, pattern, count, options?)` → `number`
 
 Wait until **at least** `count` lines match, then return how many there
@@ -1409,6 +1673,97 @@ assertTrue(res.status == 202, 'ingestion not accepted');
 
 ---
 
+## Network mocks
+
+What the page's requests get, for the rest of the scenario: a fixed
+response, an abort, or a pass to the network. Masks are Playwright URL
+globs (`**/api/items*`), matched against every request of the browser
+context — every tab and frame. A scenario holds no callbacks between
+steps, so a mock is a fixed answer, not a handler.
+
+- Where several masks match one request, the one mocked **last**
+  answers. Mocking a mask again replaces its answer and makes it the
+  latest.
+- Mocks end with the scenario; `unmockRoute` takes them off earlier.
+
+### `mockRoute(glob, response)`
+
+```js
+mockRoute('**/room/last-message/load', { body: { text: 'Hi from the mock' } });
+mockRoute('**/api/items', { status: 503, body: 'down', headers: { 'retry-after': '5' } });
+mockRoute('**/ads/**', { abort: true });
+```
+
+- `{status?, body?, headers?, contentType?}` — the response. `status`
+  defaults to 200. An object or array `body` goes out as JSON with
+  `contentType: 'application/json'`; a string body as it is.
+- `{abort: true}` — the request fails, as with no network.
+  `{abort: true, record: true}` also keeps every request it stopped,
+  for `assertNoRequest`.
+- `{continue: true}` — the request goes to the network.
+- A fixed response to `**/*` is refused: it would answer the page itself.
+  `abort` and `continue` there are fine.
+- The page document of the `baseUrl` origin is never aborted, so a
+  navigation to your site still loads. Only the document: its scripts,
+  styles, images and API calls are ordinary requests, and an abort mask
+  that matches them stops them.
+
+A network allowlist is two masks — the later one wins where both match.
+The second one lets through everything your app loads from its own
+origin, not just the page:
+
+```js
+mockRoute('**/*', { abort: true, record: true });   // nothing leaves…
+mockRoute('**/localhost:*/**', { continue: true }); // …except the app's origin
+```
+
+For a site on a domain, the mask is its origin:
+`mockRoute('https://app.example.com/**', {continue: true})`.
+
+### `unmockRoute(glob?)`
+
+Takes off the mock at `glob`, or every mock without an argument. What a
+recording abort kept stays for `assertNoRequest`.
+
+### `waitForRequest(glob, options?)` → `{url, method, headers, postData, postDataJson}`
+
+Waits for a request matching `glob` and returns it. `postData` is the
+body as sent (null without one); `postDataJson` is that body read as
+JSON (null when it is not JSON).
+
+```js
+mockRoute('**/api/messages', { body: { ok: true } });
+click(getByRole('button', { name: 'Send' }));
+req = waitForRequest('**/api/messages');
+assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
+```
+
+- On a **mocked** mask it also finds a request sent before the call:
+  the mock keeps what it answered, and each request is returned once.
+  On any other mask only requests from the call on count — to catch one
+  the previous step sent, mock the mask with `{continue: true}` first.
+- `{timeoutMs}` — default 20 000.
+
+### `assertNoRequest(glob, options?)`
+
+Fails if the recording abort at `glob` stopped any request, naming
+them — a test that got its data from the internet it should not reach
+fails instead of passing by luck.
+
+```js
+mockRoute('**/*', { abort: true, record: true });
+mockRoute('**/localhost:*/**', { continue: true });
+// … the test …
+assertNoRequest('**/*');
+```
+
+- `glob` is the mask of a `mockRoute(glob, {abort: true, record: true})`.
+  A mask without a recording abort is an error, not a pass: nothing
+  watched it.
+- `{since}` — epoch ms, as `nowMs()` gives: only requests from then on.
+
+---
+
 ## Typed getters
 
 Read page properties directly into a local variable.
@@ -1436,6 +1791,16 @@ source-order concatenation, hidden nodes included.
 Identical to `inputValue`; kept under typed-getters for symmetry with
 agent prompts that prefer the `get*` prefix.
 
+### `boundingBox(loc)` → `{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 it into view.
+
+```js
+box = boundingBox(getByRole('dialog'));
+assertTrue(box.width <= 480, json(box));
+```
+
 ### `getTitle()` → `string`
 
 Active page title.
@@ -1488,6 +1853,44 @@ out = shell('./status.sh');
 assertTrue(textContains(out.stdout, 'ready'), out.stderr);
 ```
 
+### `textMatches(text, /re/)` → `false` | `string[]`
+
+The first match of a regex literal: `false` on a miss, otherwise
+`[whole, group1, …]`, the array JavaScript's `match` gives. A group that
+took no part in the match is `null`. The array is truthy, so the call
+also works as a test.
+
+```js
+m = textMatches(getUrl(), /room=(\d+)/);
+assertTrue(m, getUrl());
+roomId = m[1];
+```
+
+A string pattern is refused: for a plain substring use `textContains`.
+A `g` flag does not change the answer, it is always the first match.
+
+### `parseJson(text)` → `any`
+
+Parse a JSON string into a value you walk with `.` and `[]`: an
+apiCall body that came back as text, a `data-*` attribute, a stored
+setting. Invalid JSON fails the step and quotes the input; an empty
+string is not JSON.
+
+```js
+saved = parseJson(getLocalStorage('messages'));
+assertEqual(saved[0].type, 'hello');
+```
+
+### `urlParam(url, key)` → `string` | `null`
+
+A query parameter, decoded. `null` when the key is absent, `''` when it
+is present but empty. A path without a host (`/room?id=7`) works too.
+
+```js
+src = getAttribute(locator('iframe#chat'), 'src');
+assertEqual(urlParam(src, 'roomId'), 'r-7');
+```
+
 ### `json(value)` → `string`
 
 Serialize any value to a JSON string. The debug tool for API and data
@@ -1551,6 +1954,15 @@ result = evaluate(
 Backticks are **raw** — `${…}` interpolation is rejected at parse time
 (see `vendor/dsl/EXTENSIONS.md`).
 
+`evaluateOnLocator(loc, js, ...args)` — the same hatch on one element.
+The body gets the element first, then the extras by the same rule: one
+→ the value itself, two or more → one array.
+
+```js
+color = evaluateOnLocator(getByRole('alert'), `(el) => getComputedStyle(el).color`);
+ok = evaluateOnLocator(getByRole('main'), `(el, [a, b]) => el.children.length > a + b`, 1, 2);
+```
+
 ---
 
 ## Diagnostics

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/web",
-  "version": "0.44.0",
+  "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": {
@@ -84,18 +84,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.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.44.0",
-    "@unotest/grounder": "^0.44.0"
+    "@unotest/grounder": "^0.45.0",
+    "@unotest/judge": "^0.45.0"
   }
 }