@unotest/web 0.43.2 → 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
@@ -545,6 +565,116 @@ Semantics:
   parsing rubric lines `must contain: <substring>` /
   `must not contain: <substring>`.
 
+### `assertScreenshot(name, options?)` / `assertScreenshot(loc, name, options?)`
+
+Since 0.44.0.
+
+The page — or one element — against a PNG baseline in the repo: a mockup
+exported from Figma, or a snapshot you accepted earlier.
+
+```js
+function test_chat_matches_figma() {
+  step("Chat screen matches the mockup", () => {
+    goto('/demo/chat');
+    waitForText('Hi!');
+    assertScreenshot('chat-empty', {
+      maxDiffRatio: 0.05,                                  // share of pixels, 0..1
+      threshold: 32,                                       // per channel, 0..255
+      mask: [getByTestId('clock'), getByTestId('avatar')], // elements on the page
+      ignore: [{x: 0, y: 0, width: 780, height: 94}],      // areas of the baseline
+    });
+  });
+}
+```
+
+**The metric** is the one you would count by hand. A pixel *differs* when
+any of its R, G, B, A channels differs by more than `threshold` (default
+32). The assert fails when the share of differing pixels among the
+compared ones is **more than** `maxDiffRatio` (default 0 — every pixel
+within the threshold). Exactly the limit passes: 5.0% differing at
+`maxDiffRatio: 0.05` is green, 5.1% is red. No perceptual colour model —
+the number in the report is the number you get.
+
+**Masks.** `mask: [locator…]` — the boxes of those elements at the moment
+of the snapshot; a locator that matches nothing is an error, not a
+skipped mask. `ignore: [{x, y, width, height}…]` — rectangles in the
+baseline's pixels, for what the page does not have (a phone's status bar
+in a mockup). Everything masked is left out on both sides and out of the
+share.
+
+**Password fields** — `type="password"`, or `autocomplete` of
+`current-password`, `new-password` or `one-time-code` — are painted over
+in magenta (`#FF00FF`) on the snapshot, as on every screenshot the tool
+takes, so a baseline accepted from a snapshot has them painted over too. A
+mockup that shows such a field needs it covered with `ignore`.
+
+**Size.** Snapshot and baseline are compared pixel for pixel, never
+resampled. A different size fails at once with both sizes: match the
+viewport and `deviceScaleFactor` to the baseline — a 780×1688 Figma
+export at 2x is `viewport: {width: 390, height: 844, deviceScaleFactor: 2}`.
+
+**The snapshot** is taken the way `screenshot()` takes one — after the
+page settles — with animations finished and the caret hidden, and the
+page's time frozen if you froze it. By default it is the viewport;
+`fullPage: true` takes the whole page (not for an element). An image may
+have at most 25 megapixels — a larger baseline or snapshot is refused
+before it is read.
+
+**The baseline** lives next to the scenario:
+`unotest/e2e/<scenario path without .js>.screenshots/<name>.png` (the
+name is lower-cased and dashed, as for `screenshot()`), and travels with
+the scenario into a box bundle. Two names that become the same file in one
+scenario (`"Checkout Page"` and `"checkout/page"`) are refused at the
+second one; the same name twice in one run of `--update-screenshots` is
+written twice, and the runner says that the last one wins. A symlink on
+the way to a baseline is followed while it stays inside the project (a
+shared directory of the suite); one that leads outside is refused.
+
+- **Unreadable baseline** — a file that is not a PNG, or one over the
+  ceiling, fails the assert (not the run); the snapshot is saved as a
+  candidate to replace it.
+
+- **No baseline yet** — the assert fails; the snapshot is saved in the
+  run's artifacts as a candidate under the baseline's own file name, and
+  the message says where it goes. Nothing is written into the repo on its
+  own: a first run that turned green by writing its own baseline would
+  check nothing.
+- **Accept the current page** — `npx @unotest/web e2e <name>
+  --update-screenshots` (MCP: `run_test {updateScreenshots: true}`)
+  writes every snapshot of the run as its baseline; the asserts pass and
+  the journal marks them `updated`. Refused on a box.
+- **It failed** — the run keeps three pictures: `expected`, `actual` and
+  `diff` (differing pixels red over a greyed-out snapshot, masked areas
+  grey). The viewer shows them side by side on the failed step; the
+  failure bundle and `run_test` (`next.visual`) point at them. A retried
+  attempt keeps its own pictures.
+
+**Baselines for a box.** Fonts render differently on macOS and on the
+box (Linux), so a baseline recorded on your laptop will not match there.
+Take recorded baselines where the suite runs:
+
+1. Push the scenario with `assertScreenshot` and no baseline.
+2. The run on the box is red: `no baseline at …`, the candidate is in
+   the run's artifacts.
+3. Download it — the viewer's **Download as baseline** on the failed
+   step, or `npx @unotest/web box run <runId> --env <project>/<env>
+   --download` (MCP: `box_run_download`), which unpacks the candidates
+   next to the zip. The file is already named as the assert expects.
+4. Put it in `unotest/e2e/<scenario>.screenshots/`, commit, push — the
+   next run on the box is green.
+
+A Figma export is the same on every platform: commit it as is.
+
+Baselines count towards the bundle. Boxes accept 128 MB by default; a
+larger suite is warned about before the upload, with its biggest files
+and baselines — compare an element instead of a full page to keep them
+small.
+
+**Secrets and personal data.** A baseline is a file in your repo. Mask
+every area that shows a secret, a token or someone's personal data
+before the first snapshot is written — once committed, it is in the
+history.
+
 ---
 
 ## Queries
@@ -638,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
@@ -710,17 +867,79 @@ pause(500); // lint-ok: third-party widget has no completion signal to hook into
 helpers with known warnings stop drowning out new ones). Error-severity
 diagnostics are never suppressible.
 
+### `clockFreeze(iso)` / `clockTick(ms)` / `clockRun()`
+
+The page clock. Stops time on the page, moves it by hand, lets it go.
+For anything that animates on timers — a "typing…" indicator, a
+countdown, a relative "5 minutes ago" — so a screenshot of it is the
+same pixels on every run.
+
+```js
+goto('/chat');
+clockFreeze('2026-01-15T10:00:00Z');   // Date reads this; no timer fires
+screenshot('chat-typing');              // same pixels every run
+clockTick(1500);                        // 1.5 s pass: due timers fire
+clockRun();                             // time runs by itself again
+```
+
+- `clockFreeze(iso)` — `Date.now()` and `new Date()` on the page read
+  `iso`; `setTimeout`, `setInterval` and `requestAnimationFrame` stand
+  still. Any instant, past or future: no timer fires on the way to it.
+- `clockTick(ms)` — frozen time moves forward by `ms`, and every timer
+  due in that span fires, in order.
+- `clockRun()` — time runs by itself again, from where it stands.
+
+**When the clock is installed.** A fake clock only controls timers set
+after it is in place, so a run puts it on the browser before the first
+page loads — and only for a scenario that can reach a clock call
+(directly, or through a helper it calls). Every other scenario keeps the
+page's real time, as before. So `clockFreeze` works at any point of the
+scenario, after `goto` included. Over MCP the browser has to be opened
+with the clock: `new_context {clock: true}` (or `explore_start {clock:
+true}`), then `explore_step` actions `clock_freeze {time}`,
+`clock_tick {ms}`, `clock_run`.
+
+**Coming from Playwright.** The names are flat: `clock.freeze(...)`,
+`clock.tick(...)`, `clock.run()` (and `pauseAt`, `setFixedTime`,
+`runFor`, `resume`) are refused with the name to use instead. Where
+Playwright's `pauseAt` only moves forward, `clockFreeze` also takes a
+date in the past.
+
+Not with `launch.userDataDir`, once its shared context is open: the
+pages already loaded in it keep real timers, so the clock is refused
+there rather than half-applied.
+
+### Time zone and locale
+
+`timezone` and `locale` in `unotest.config.mjs` set them for every page:
+
+```js
+export default {
+  timezone: 'Europe/Madrid',   // Date#toString, Intl, getTimezoneOffset
+  locale: 'es-ES',             // navigator.language, Intl defaults, Accept-Language
+};
+```
+
+Unset, the page gets the machine's zone and the browser's locale.
+`UNOTEST_TIMEZONE` / `UNOTEST_LOCALE` override the config for one run.
+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
@@ -742,6 +961,216 @@ 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
+cookies, localStorage, sessionStorage and tabs. For anything that takes
+two users — one closes a ticket, the other still has it open.
+
+`newContext()` opens one with the same options as the first (base URL,
+viewport and scale, `device`, time zone, locale, page clock), makes it
+active, and returns its number: the test's own context is `0`, the next
+is `1`. Nothing of the first is inherited — no cookie, no storage, no
+`storageState`. `setContext(i)` makes context `i` active; every locator,
+assertion, `setPage`, frame and storage call then acts in it. Each
+context keeps its own active tab and frame stack, so switching away and
+back lands where the scenario left off.
+
+```js
+function test_second_client_writes_to_closed_thread() {
+  step("Client A opens the thread", () => {
+    flow_login(LOGIN, PASSWORD);
+    goto('/support/thread/42');
+  });
+  step("Client B opens the same thread", () => {
+    clientB = newContext();             // returns 1, becomes active
+    flow_login(LOGIN, PASSWORD);
+    goto('/support/thread/42');
+  });
+  step("Client A closes the ticket", () => {
+    setContext(0);                      // client A
+    click(getByRole('button', {name: 'Close ticket'}));
+  });
+  step("Client B cannot write", () => {
+    setContext(clientB);
+    fill(getByRole('textbox', {name: 'Message'}), 'hello');
+    press(getByRole('textbox', {name: 'Message'}), 'Enter');
+    assertVisible(getByText('This ticket is closed'));
+  });
+}
+```
+
+`flow_login` is your project's own sign-in helper (`unotest/e2e/_helpers/`);
+the rest is the DSL. A variable set inside one `step(...)` is visible
+in the next — `clientB` above — because a step block has no scope of its
+own.
+
+- **Ceiling:** 4 contexts per test, `maxContexts` in the config. The next
+  `newContext()` is refused, naming the key — a loop opening one per
+  iteration stops there.
+- **End of the test:** every context is closed, in any outcome. One that
+  fails to close is a warning in the run log.
+- **Journal:** once a second context exists, each step event carries
+  `contextIndex` — the context the step **started** in (so
+  `setContext(0)` issued from context 1 is marked `1`), and the viewer's
+  Trace shows it as a `ctx N` chip. A one-context test writes exactly
+  what it did before.
+- **Failure bundle:** the page, console and network of the context
+  active at the failure, and `contextIndex` in `failure.json`. The other
+  contexts are not in it: to keep a frame of client A, `screenshot()` it
+  before switching.
+- **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.
+- **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` /
+  `setContext` (or any DSL name) is reported by `lint:shadows-dsl-function`
+  — your function wins a call by that name, so the DSL's is out of reach
+  until you rename it.
+
+Over MCP, record it with `explore_step {action: "newContext"}` and
+`{action: "setContext", index}`; they become the same two calls in the
+saved test. The `new_context` tool is different: it resets the browser.
+
+### `setViewport({width, height})`
+
+Resize the browser window mid-scenario. Every open tab is resized in
+place — no reload, the page keeps its state — and a tab opened afterwards
+starts at the same size. The size belongs to the browser, not to one tab.
+
+```js
+setViewport({width: 420, height: 900});   // a phone-width layout
+screenshot('card-narrow');
+setViewport({width: 1280, height: 720});
+```
+
+Both fields are required. Anything else is refused on that line,
+`deviceScaleFactor` included: the scale is fixed when the browser opens,
+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:
+
+1. **The MCP call.** `new_context` and `explore_start` take
+   `viewport: {width, height, deviceScaleFactor}` and `device`. They
+   replace the config's window for that context. `explore_start` with a
+   window while a context is already open is refused — call
+   `new_context` with it instead.
+2. **The config.** `unotest.config.mjs`:
+
+   ```js
+   export default {
+     viewport: { width: 390, height: 844, deviceScaleFactor: 2 },
+   };
+   ```
+
+   `deviceScaleFactor: 2` doubles every screenshot: a 390×844 page
+   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
+   nearest ones. `viewport` next to `device` overrides the preset field
+   by field.
+4. **The default:** 1280×720 at scale 1.
+
+A preset's viewport is the page area, smaller than the device's screen:
+`"iPhone 14"` is 390×664 (the browser chrome takes the rest of 844). To
+match a 390×844 mockup, set `viewport` explicitly:
+`{width: 390, height: 844, deviceScaleFactor: 2}`.
+
+A mobile preset lays out a page with no `<meta name="viewport">` tag at
+980 px wide, as a real phone does. Firefox has no mobile mode: a mobile
+preset on Firefox is refused — give it a plain `viewport` instead.
+
 ### `enterFrame(loc)`
 
 Enter an iframe scope. Subsequent calls run inside the frame's document.
@@ -756,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
@@ -891,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
@@ -986,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
@@ -1115,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.
@@ -1142,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.
@@ -1194,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
@@ -1257,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
@@ -1295,7 +2001,8 @@ screenshot('landing', {fullPage: true}); // full scroll height
   `load`, which on a client-rendered app fires before any content is on
   screen. A page that never goes quiet (polling, live feeds) costs the
   2s cap and is then captured as-is.
-- Not a visual assertion: the test does not compare images. In runtimes
+- Not a visual assertion: `screenshot()` does not compare images — that is
+  [`assertScreenshot`](#assertscreenshotname-options--assertscreenshotloc-name-options). In runtimes
   with no artifact dir (exploration) the call logs a warning, returns
   `null` and does NOT fail the run.
 - **Every step, without calling it:** `UNOTEST_STEP_SCREENSHOTS=1` makes
@@ -1386,13 +2093,12 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
   ```
 
 - **Array literals** — `[1, 2, 3]`.
-- **Index access on data** — `docs[0]`, `docs[0].objectsCount`. The
-  index goes on a **bare variable** (grammar restriction), so pull
-  nested arrays into one first: `docs = res.body; n = docs[0].count;`.
+- **Index access on data** — `docs[0]`, `docs[0].objectsCount`,
+  `res.body.items[0].id`: see [Strings, objects, indexes](#strings-objects-indexes).
   Indexing a **Locator** is rejected — disambiguate with chain methods
   (`.filter(...)`), and `arr[i] = v` assignment stays unsupported.
-- **Object literals — as call arguments only** (`click(loc, {force:
-  true})`); a standalone `x = {name: 'x'}` is rejected.
+- **Object literals** — as call arguments (`click(loc, {force: true})`)
+  and as values in a variable: see [Strings, objects, indexes](#strings-objects-indexes).
 - **Member access** — `row.email` (dot form; `obj['key']` doesn't
   parse).
 - **Method chains** — `getByRole('row').filter({hasText:'X'}).click()`.
@@ -1409,13 +2115,143 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
 Not supported (and intentionally so): `while` / `do…while` /
 `continue` (bound loops keep every scenario terminating), `++`/`--`,
 arrow functions, async/await (everything is sequenced by the AST
-executor), classes, modules, promises, `try/catch`. Errors thrown from
-a primitive abort the scenario; if the runtime is paused (debugger /
-MCP step mode), the failure is captured for inspection.
+executor), classes, modules, promises, `try/catch` — for cleanup that
+must run whatever happens, see [`teardown`](#teardown--give-the-stand-back).
+Errors thrown from a primitive abort the scenario; if the runtime is
+paused (debugger / MCP step mode), the failure is captured for
+inspection.
 
 See `vendor/dsl/EXTENSIONS.md` for the
 exact grammar deltas from the upstream parser.
 
+### Strings, objects, indexes
+
+Since 0.44.0.
+
+**Strings** answer four members — the whole list:
+
+| Member | Returns | |
+|---|---|---|
+| `s.length` | `number` | a property: no parentheses |
+| `s.trim()` | `string` | whitespace off both ends |
+| `s.includes(search)` | `boolean` | substring probe, same as `textContains(s, search)` |
+| `s.startsWith(prefix)` | `boolean` | |
+
+They work wherever an expression does — in `assertTrue`, in `if`, on a
+literal, on a call result:
+
+```js
+title = getTitle();
+assertTrue(title.trim().length > 0, 'empty title');
+if (out.stdout.includes('ready')) { log('up'); }
+assertTrue(getUrl().startsWith('https://'), getUrl());
+```
+
+Any other member is a lint error that names it and lists the four
+(`validator:unsupported-string-member`); `s.padStart(3)` does not
+reach the browser. A member of the list used on a value that turns out
+not to be a string at run time — a number, or `null` from a missing
+field — fails the step with the value's type in the message.
+
+**Object literals** are values: keep one in a variable, read it back by
+field, hand it to a helper.
+
+```js
+user = {name: 'Alice', tags: ['admin'], address: {city: 'Riga'}};
+flow_sign_up(user);
+assertTrue(user.address.city == 'Riga');
+```
+
+Where a function wants a specific kind (a string, a locator), an
+object in that slot is still an `arg-kind` error.
+
+**Indexes** go anywhere in a chain — no temporary variable:
+
+```js
+res = apiCall('GET', '/documents');
+assertTrue(res.body.items[0].status == 'ready', json(res.body));
+first = dbQuery('SELECT id FROM users ORDER BY id')[0].id;
+```
+
+### `teardown` — give the stand back
+
+Since 0.44.0.
+
+```js
+function test_ticket_closed_in_second_client() {
+  step("Enable the stand flag", () => {
+    teardown("Disable the stand flag", () => {
+      apiCall('POST', '/stand/flags', {closeTickets: false});
+    });
+    apiCall('POST', '/stand/flags', {closeTickets: true});
+  });
+  step("…", () => { … });
+}
+```
+
+`teardown("label", () => { … })` **registers** a rollback — nothing in
+it runs where it stands. After the test body every registered block
+runs, **newest first**:
+
+- whatever the outcome — passed, failed, over its time budget, or
+  stopped (Stop in the viewer, `abort_runtime`, Ctrl-C), including a run
+  stopped while paused at its failure in the debugger or in `run_test`;
+- each block even if an earlier one failed.
+
+Put it **before** the call that changes the stand: then a failure in
+that very call is rolled back too. A flow or helper can carry its own
+rollback (`flow_enable_flag` registers the teardown that disables the
+flag); it still runs at the end of the test, not when the helper
+returns, with the helper's variables as they were when it registered.
+A block in the test itself sees the test's variables as they are when
+it runs.
+
+What you see:
+
+- the CLI prints `↺ teardown "Disable the stand flag"` for each block;
+  the journal and the viewer show it as a frame marked **teardown**
+  after the test's last step;
+- the failure bundle is taken **before** the rollback — its screenshot is
+  the page the test broke on;
+- a green test whose teardown failed is **failed** (the stand was not
+  given back); a failed test keeps its own error, and the teardown
+  failures are listed next to it (CLI `↺ teardown "…" failed: …`,
+  `run_test` → `next.teardownFailures`).
+
+Stopping a run: the first Stop gives the stand back and then ends the
+run — the viewer shows **returning the stand…**, `abort_runtime` answers
+`status: "returning the stand…"`. A second Stop (or a second
+`abort_runtime`) skips what is left; the journal records
+`teardown skipped: second stop` with the blocks that did not run.
+
+How long the first Stop can take: the rollback is cut at
+`teardownTimeoutMs` (60 s by default), and the run ends at the latest
+15 s after that, saying so (`stop: the rollback did not finish within
+…`) — a Stop never hangs silently. A viewer that started the run
+force-kills it only if it is still alive 5 minutes after the first
+Stop — a safety net for a stuck process, not a wait for the rollback.
+
+**When the stand is NOT given back.** A process that is killed
+(SIGKILL, a crashed machine) runs no teardown at all. Blocks still
+running when `teardownTimeoutMs` (config, default 60 s for all blocks
+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
+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.
+
+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
+helpers. A function, parameter or variable of your own named
+`teardown` is reported as `teardown-name-conflict` — rename it.
+
 ---
 
 ## Conventions