@unotest/web 0.44.0 → 0.46.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,16 @@ 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.
+
+An option an action, a navigation, a wait or an assertion does not take
+is refused with the ones it does, so a misspelled `{timout: 5000}` fails at once
+instead of waiting the default.
+
 ---
 
 ## Builders
@@ -398,15 +409,54 @@ override per-call with `{timeout}`). Throw `AssertionError` on failure.
 
 ### `assertText(loc, expected, options?)`
 
-Default is exact match. Use `{exact: false}` for substring.
+`expected` is a string or a `/regex/`. A string must equal the element's
+text; with `{exact: false}` it only has to occur in it. A regex is tested
+against the text as is: `exact` does not anchor it, write `^…$` for that.
 
 ```js
 assertText(getByTestId('success-banner'), 'Saved successfully')
 assertText(getByRole('heading'), 'Welcome', {exact: false})
+assertText(getByTestId('order-id'), /^#\d{4}$/)
+assertText(getByRole('status'), 'Saving…', {not: true})   // waits until it changes
+```
+
+- `{not: true}` inverts the check and waits for it: the step passes as
+  soon as the text no longer matches, and fails at the timeout with the
+  text that still does.
+- Empty text: `assertText(loc, '')`. Any text at all:
+  `assertText(loc, '', {not: true})`.
+
+**Options:** `timeout?`, `exact?` (default `true`), `not?`.
+
+### `assertTexts(loc, expected, options?)`
+
+One entry per element, in order: the locator must match exactly
+`expected.length` elements, and element `i` must match `expected[i]`
+(string or regex, the rules of `assertText`). Polled as a whole, so a
+list that is still filling in passes once it is complete.
+
+```js
+assertTexts(getByRole('listitem'), ['Apple', 'Banana', /^Cherry/])
 ```
 
 **Options:** `timeout?`, `exact?` (default `true`).
 
+### `assertAttribute(loc, name, expected, options?)`
+
+Polls the attribute `name` until it matches `expected`: a string equals
+it (`{exact: false}` — contains), a regex is tested against it. An
+absent attribute matches nothing; with `{not: true}` the step passes
+once the value stops matching or the attribute is gone.
+
+```js
+click(getByRole('button', {name: 'Menu'}));
+assertAttribute(getByRole('button', {name: 'Menu'}), 'aria-expanded', 'true')
+assertAttribute(getByRole('link', {name: 'Docs'}), 'href', /\/docs\//)
+assertAttribute(getByRole('form'), 'aria-busy', 'true', {not: true})
+```
+
+**Options:** `timeout?`, `exact?` (default `true`), `not?`.
+
 ### `assertVisible(loc, options?)` / `assertHidden(loc, options?)`
 
 ```js
@@ -481,6 +531,88 @@ 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"
+```
+
+### `assertSchema(value, schema)`
+
+Check a value against a JSON Schema (draft 2020-12) — typically one your
+app generates from its own zod schemas (`z.toJSONSchema`) and the scenario
+reads with `readJson`. The failure names every field that breaks the
+schema, by path, with what is wrong there:
+
+```js
+schema = readJson('unotest/fixtures/message.schema.json');
+req = waitForRequest('**/api/messages');
+assertSchema(req.postDataJson, schema);
+// assertSchema: the value breaks the schema in 2 places:
+//   /room: must be >= 1
+//   /tags/1: must be string
+```
+
+- A `$ref` inside the schema (`#/$defs/tag`) is followed; a `$ref` to
+  another file is refused. Put shared parts under `$defs`.
+- A schema that declares another draft in `$schema`, or is itself
+  invalid, is refused before any value is checked.
+- `format` (`email`, `uuid`, `date-time`) is not checked.
+- The schema must be an object: pass what `readJson` returned, not the
+  file name.
+
+### `skip(reason, condition?)`
+
+End the test as **skipped**: it does not apply here — a live-only check
+with no live target configured, data this stand does not have. With the
+condition true, or without one, the run reports skipped with the reason,
+neither passed nor failed; nothing after the call runs, and `teardown(...)`
+blocks registered before it still play. With the condition false the test
+goes on.
+
+`skip` is a test guard: it stands in the `test_*` body next to its steps,
+like `step(...)` and `teardown(...)`, not inside one.
+
+```js
+function test_live_payment() {
+  skip('LIVE_API is not set: no live target', env('LIVE_API') == null);
+  step("Pay on the live API", () => {
+    // …
+  });
+}
+```
+
+A decision on data the test reads goes after the step that reads it:
+
+```js
+function test_refund() {
+  step("Find a paid order", () => {
+    orders = apiCall('GET', '/orders?status=paid');
+  });
+  skip('no paid order on this stand', orders.length == 0);
+  // …
+}
+```
+
+- The CLI prints `○ test: … skipped: <reason>` and counts it apart:
+  `0 passed, 0 failed, 0 errored, 1 skipped`. The exit code is 0.
+- A collection counts it as `skipped=N(test=N)`.
+- `run_test` answers `outcome: "skipped"` with `skipReason`.
+- A skip after a failed `step.soft(...)` is a failed test, and so is a
+  skipped test whose teardown fails.
+- The condition is `true` or `false`; anything else fails the test with
+  the value named — compare it: `env('LIVE_API') == null`.
+- Call it at the level of the `test_*` body: inside a step or an `if`
+  block, in a helper or a `flow_*`, it is reported by
+  `lint:skip-outside-test`.
+
 ### `assertJudge(loc, rubric)`
 
 LLM-judge assert for **free-form text** — chat replies, generated
@@ -748,6 +880,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 +1040,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 +1073,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
@@ -970,7 +1198,8 @@ own.
 - **Traces and video:** not recorded for any context — unotest does not
   capture Playwright traces or video today.
 - **Browser profile:** with `launch.userDataDir` every page shares one
-  context, so `newContext()` is refused there.
+  context, and with `launch.profile: 'per-test'` the test is one browser,
+  so `newContext()` is refused in both.
 - **Debugging:** an agent that joins a paused run (`take_wheel`,
   `attach_debug_session`) lands in the context the run is on (Chromium).
 - **Names:** a function or variable of your own called `newContext` /
@@ -999,6 +1228,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 +1253,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 +1298,41 @@ 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` or `launch.profile: 'per-test'`, plus the
+`--load-extension` args in `unotest.config`; without one every call below
+fails at once, naming it. With `per-test` every test starts the worker
+from scratch, on empty storage.
+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 +1468,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`,
+  `readFile` or `readFileInfo`: the downloads are one of the directories
+  a scenario reads from.
+- `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
@@ -1193,6 +1507,27 @@ returns the file content. Relative `path` resolves against
 `sandbox.shellCwd`. `options`: `{timeoutMs}` (default 20 000 ms). On
 expiry the step fails with the file path and the last observed state.
 
+**Where the file oracles read.** `waitForFile`, `assertNoFile`,
+`waitForJsonLine`, `readJsonLine`, `assertNoJsonLine`, `waitForFileCount`
+and `assertFileCount` read by the same rule as `readFile`: a path relative
+to `sandbox.shellCwd`, or an absolute one inside the project, the run's
+downloads or a directory listed in `sandbox.readRoots`. Anything else —
+`../` out of them, an absolute path elsewhere, a symlink that leads out —
+fails the step with a scenario error naming the path and the directories
+it left. The rule holds on every read of a wait: a file that appears as a
+symlink out is refused when it appears, and a file that does not exist
+yet is judged by the nearest directory above it that does.
+
+A background process that writes outside the project (a listener's log
+in `/tmp`) needs its directory in the config:
+
+```js
+// unotest/unotest.config.mjs
+export default {
+  sandbox: { readRoots: ['/tmp/my-listener'] },
+};
+```
+
 ```js
 step("Wait for the bot reply in the JSONL feed", () => {
   line = waitForFile('events.jsonl', /"type":"reply"/, {timeoutMs: 30000});
@@ -1280,6 +1615,91 @@ 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").
+
+### `env(name)` → `string | null`
+
+An environment value the test can do without. It reads what a bare
+`UPPER_SNAKE` name reads — the environment the run started in, then
+`unotest/.env` — but returns `null` for a name that is not set instead
+of failing the step. Use it to decide:
+
+```js
+if (env('LIVE_API') == null) {
+  note('live API', 'not configured, checks run against fixtures');
+} else {
+  apiCall('GET', env('LIVE_API') + '/health');
+}
+```
+
+A secret — a name from `unotest/.secrets`, or one a box injects — is
+refused: `env()` returns a plain string, and a credential must stay
+masked. Write the secret's bare name where its value is typed instead.
+
+### `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, is a file
+  `waitForDownload()` saved (`readFile(file.path)`) or lies in a directory
+  listed in `sandbox.readRoots`. `../` out of them, an absolute path
+  elsewhere, or a symlink that leads out is refused — also for a file that
+  does not exist yet, under a directory that leads out.
+- 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 +1829,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 +1947,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 +2009,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 +2110,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
@@ -1601,6 +2169,62 @@ screenshot('landing', {fullPage: true}); // full scroll height
   Keep explicit `screenshot()` calls for the moments a green run has to
   prove; the flag is for seeing the whole run afterwards.
 
+### `consoleEntries(options?)` → `[{ level, text, url }]`
+
+What the active page wrote to its console, oldest first. The page is
+recorded from the moment it opened, so the usual order works: act, then
+ask. An extension's own page (`chrome-extension://…/popup.html`) is a
+page like any other.
+
+```js
+click(getByRole('button', { name: 'Save' }));
+errors = consoleEntries({ level: 'error' });
+assertTrue(errors.length == 0, json(errors));
+
+before = nowMs();
+click(getByRole('button', { name: 'Retry' }));
+assertTrue(consoleEntries({ level: ['warn', 'error'], since: before }).length == 1, 'one complaint');
+```
+
+- `level` of each entry: `log`, `info`, `warn`, `error` or `debug`
+  (`console.table`, `console.dir` and the like read as `log`).
+- `url` — the page's address when the line was written.
+- `{level}` — one level or a list of them; an unknown level is refused.
+- `{since}` — epoch ms, as `nowMs()` gives: only lines from then on.
+- The last 500 lines of the context are kept, the oldest go first.
+- A service worker's console is not a page's: it is not here.
+- Independent of `UNOTEST_CONSOLE`, which decides only whether a run
+  also writes `console.json` into its artifacts and failure bundles.
+
+### `pageErrors(options?)` → `[{ message, stack }]`
+
+Errors the active page threw and nothing caught — an exception out of an
+event handler, a rejected promise nobody awaited. Oldest first; `stack`
+is empty when the browser gave none. The last 100 are kept.
+
+```js
+click(getByRole('button', { name: 'Load' }));
+thrown = pageErrors();
+assertTrue(thrown.length == 0, json(thrown));
+```
+
+- `{since}` — epoch ms, as `nowMs()` gives.
+
+### `assertNoConsoleErrors(options?)`
+
+Fails when the active page logged console errors, or threw errors
+nothing caught, quoting the first three and counting the rest.
+
+```js
+goto('/checkout');
+assertNoConsoleErrors();
+assertNoConsoleErrors({ includePageErrors: false, since: before });
+```
+
+- `{includePageErrors}` — default `true`: an uncaught error is worse than
+  a logged one. `false` looks at console errors only.
+- `{since}` — epoch ms, as `nowMs()` gives: only from then on.
+
 ---
 
 ## Logging and notes
@@ -1826,14 +2450,38 @@ together) runs out are cut, and so is whatever a second Stop skips.
 Each such block is reported in the run result as a teardown failure —
 the stand may be left as the test set it.
 
-**The run's own budget is a deadline.** `UNOTEST_MAX_DURATION_MS`
-(default 5 min) ends the test the moment it runs out: an action still
+**The run's own budget is a deadline.** `testTimeoutMs` in config
+(default 5 min), `UNOTEST_MAX_DURATION_MS` for one run, or
+`setTestTimeout(ms)` inside the test ends the test the moment it runs out: an action still
 running is abandoned there, and one that finished past it fails the
 test on that line — the last action included. The abandoned browser
 call lives on until its own timeout or until the context closes; the
 teardown pass runs anyway, on `teardownTimeoutMs`, not on what the test
 left of its budget.
 
+### `setTestTimeout(ms)`
+
+This test's own time budget, counted from its start — Playwright's
+`test.setTimeout`. It replaces `testTimeoutMs` and
+`UNOTEST_MAX_DURATION_MS` for the test it runs in, longer or shorter:
+
+```js
+// unotest.config.mjs: testTimeoutMs: 30000 — every test gets 30 s
+function test_theme_rebuild() {
+  setTestTimeout(90000); // this one rebuilds the theme, give it 90 s
+  // …
+}
+```
+
+Running out is a failure, not a stop: the test is red — counted as
+errored (`‼`), like any run budget — with
+`setTestTimeout(90000) budget exhausted` (or `testTimeoutMs budget
+(30000ms) exhausted`), the action it cut is abandoned, and the teardown
+blocks play. Stop in the viewer aborts the run instead — same teardown,
+but the run reads as stopped, not failed. Call it in the `test_*` body:
+in a helper or a `flow_*` it is reported by
+`lint:set-test-timeout-outside-test`.
+
 Rules (lint, `teardown-shape`): the label is a string literal; no
 `return` inside, no `break` out of it (a `break` in a loop inside is
 fine); no `teardown` inside a `teardown`. Allowed in tests, flows and