@unotest/web 0.45.0 → 0.47.0

package/guides/dsl-reference.md

@@ -198,6 +198,10 @@ 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
@@ -405,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
@@ -472,11 +515,16 @@ assertCount(getByRole('listitem'), 5)
 
 ### `assertUrl(pattern, options?)`
 
-Substring match against the active page's URL.
+A string is a substring match against the active page's URL. A
+`/regex/` is tested against the whole URL, unanchored: add `^` or `$`
+yourself. A failure names the regex as `/source/flags`.
+
+**Options:** `timeout?`.
 
 ```js
 assertUrl('/dashboard')
 assertUrl('https://example.com/checkout')
+assertUrl(/\/cars\/\d+$/)
 ```
 
 ### `assertTrue(value, message)`
@@ -501,6 +549,75 @@ 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
@@ -732,12 +849,16 @@ goto('/dashboard')                          // relative — resolved against the
 
 ### `waitForUrl(pattern, options?)`
 
-Wait until the active page URL contains `pattern`. Useful after a click
-that triggers navigation.
+Wait until the active page URL contains `pattern` (a string) or matches
+it (a `/regex/`, unanchored). Useful after a click that triggers
+navigation.
+
+**Options:** `timeout?`.
 
 ```js
 click(getByRole('link', {name: 'Settings'}));
 waitForUrl('/settings');
+waitForUrl(/\/orders\/\d+/);
 ```
 
 ### `waitForNavigation(options?)`
@@ -852,6 +973,23 @@ waitForCount(locator('[data-id]'), 3, {timeout: 90000});
 waitForText(/\bshipping\b/i, {timeout: 90000});
 ```
 
+### `waitForAnimations(loc, options?)`
+
+Wait until the element and its descendants have no animation still
+running — a dialog done fading in, a card done sliding — before reading
+or screenshotting it. Infinite animations (spinners) and paused ones are
+not waited for: neither ends by itself, so waiting could only time out.
+A static element returns at once. Same rule as `hasAnimation`.
+
+Options: `{ timeout? }` (default 5000 ms). A timeout is an error naming
+the element and how many animations were still running.
+
+```js
+click(getByRole('button', {name: 'Edit'}));
+waitForAnimations(getByRole('dialog'));
+assertScreenshot(getByRole('dialog'), 'edit-dialog');
+```
+
 ### `pause(ms)`
 
 Hard sleep. **Avoid** — the linter flags it (`lint:pause-explicit`). Use
@@ -1086,7 +1224,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` /
@@ -1119,6 +1258,27 @@ would be lost. See [Viewport and scale](#viewport-and-scale).
 Playwright keeps it, and nothing hands the page back to the window. For
 the real window, set `viewport: null` in the config.
 
+### `emulateMedia({reducedMotion?, colorScheme?})`
+
+Change the media features the current tab reports, mid-scenario — what
+`matchMedia` and CSS `@media` see from that moment, without a reload.
+`reducedMotion`: `'reduce'` | `'no-preference'`; `colorScheme`:
+`'light'` | `'dark'` | `'no-preference'`. A feature left out keeps its
+current value. An unknown key, another value or an empty object is
+refused on that line.
+
+```js
+emulateMedia({reducedMotion: 'reduce'});   // the app's no-animation path
+click(getByRole('button', {name: 'Edit'}));
+assertScreenshot(getByRole('dialog'), 'edit-dialog-still');
+```
+
+It applies to **this tab only**: a tab or popup opened afterwards — even
+by the same browser context — starts without it; call `emulateMedia`
+again after `setPage` / `waitForPage`. An app that reads the color
+scheme once at load sees the change on its next load (`reload()`), not
+before.
+
 #### Viewport and scale
 
 Where the window's size and scale come from, first match wins:
@@ -1189,8 +1349,10 @@ Pop one iframe scope. Idempotent at depth 0.
 
 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.
+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`).
 
@@ -1364,8 +1526,8 @@ scenario has not taken yet, waiting up to `{timeoutMs}` (default
 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`.
+  `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.
@@ -1392,6 +1554,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});
@@ -1503,6 +1686,25 @@ step("Send button uses the app's own label", () => {
   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
@@ -1520,10 +1722,11 @@ step("Export is a PNG", () => {
 - `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.
+  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`
@@ -1707,6 +1910,10 @@ mockRoute('**/ads/**', { abort: true });
   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 mask reaches web requests only: http(s) and ws(s). An extension's
+  own pages and scripts (`chrome-extension://`) load under `**/*`, so
+  a network allowlist does not leave its UI dead. To mock one of them,
+  start the mask with its scheme: `chrome-extension://<id>/panel.js`.
 
 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
@@ -1801,6 +2008,29 @@ box = boundingBox(getByRole('dialog'));
 assertTrue(box.width <= 480, json(box));
 ```
 
+### `computedStyle(loc, property)` → `string`
+
+The element's computed CSS value, as the browser resolved it — what
+`getComputedStyle(el).getPropertyValue(property)` gives, trimmed.
+Custom properties read too, inherited ones included; a property that is
+not set reads `""`. A missing or ambiguous element fails as
+`getAttribute` does.
+
+```js
+assertTrue(computedStyle(getByRole('dialog'), 'opacity') == 1, 'dialog is faded');
+accent = computedStyle(locator('body'), '--accent');
+```
+
+### `hasAnimation(loc)` → `boolean`
+
+Whether the element or a descendant has an animation still running
+towards an end. Infinite (spinners) and paused animations do not count —
+the rule `waitForAnimations` waits by.
+
+```js
+assertTrue(hasAnimation(getByRole('dialog')) === false, 'dialog still moving');
+```
+
 ### `getTitle()` → `string`
 
 Active page title.
@@ -1891,6 +2121,60 @@ src = getAttribute(locator('iframe#chat'), 'src');
 assertEqual(urlParam(src, 'roomId'), 'r-7');
 ```
 
+### `toNumber(text, options?)` → `number`
+
+A number as a page writes it, for arithmetic and comparison. What
+`parseInt`, `parseFloat` and `Number` would be in JS.
+
+- Spaces group digits, NBSP and the narrow NBSP too: `'1 234 567'`.
+- A leading sign: `-`, `+` or the typographic minus `−`.
+- With both `,` and `.`, the last one is the decimal mark:
+  `'1,234.56'` and `'1.234,56'` are both 1234.56. One mark used twice
+  groups: `'1,234,567'`. One mark used once is the decimal mark:
+  `'12,5'`, `'0.125'`.
+- `'1,234'` and `'1.234'` read both ways (1234 or 1.234), so they fail
+  the step unless `{decimal: ','}` or `{decimal: '.'}` says which. With
+  `{decimal}` the other mark may only group digits left of it.
+- Anything else fails the step and quotes the input: units and
+  currency (`'440px'`, `'€12'`), exponents, an empty string. Cut the
+  number out first with `textMatches`.
+- A number passes through unchanged.
+
+```js
+total = toNumber(getInnerText(getByTestId('total')));   // "1 234,50"
+assertTrue(total > 1000, 'total: ' + total);
+width = toNumber(textMatches(computedStyle(phone, '--phone-w'), /(\d+)px/)[1]);
+```
+
+### `round(n, digits?)` → `number`
+
+Round to `digits` decimals, 0 to 10, default 0. Half goes away from
+zero, on the decimal as written: `round(2.5)` is 3, `round(-2.5)` is
+-3, `round(1.005, 2)` is 1.01. A string fails: read it with
+`toNumber` first.
+
+```js
+payout = round(stake * odds, 2);
+```
+
+### `formatNumber(n, options?)` → `string`
+
+A number as text, with digit grouping, through `Intl.NumberFormat`.
+
+**Options:** `locale?` (default `'en-US'`), `minFractionDigits?`,
+`maxFractionDigits?` (0 to 20; without them, up to 3 decimals).
+
+- Without a locale the answer is the same on every machine, whatever
+  its system language: `formatNumber(1234.5)` is `'1,234.5'`.
+- With another locale the text comes from the ICU data of the Node
+  that runs the scenario, spaces included (`fr-FR` puts a narrow NBSP
+  between thousands). Compare it with what the page shows rather than
+  with a string typed in the scenario.
+
+```js
+assertText(getByTestId('payout'), formatNumber(payout, {minFractionDigits: 2, maxFractionDigits: 2}));
+```
+
 ### `json(value)` → `string`
 
 Serialize any value to a JSON string. The debug tool for API and data
@@ -1959,10 +2243,20 @@ 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);
 ```
 
+Reach for it only for what no typed call reads — a style is
+`computedStyle`, a box is `boundingBox`. Overflow is one such case: is
+the text cut off? There is no getter for `scrollWidth`, so the line says
+why it uses the hatch, and the linter takes the reason:
+
+```js
+// Truncated with an ellipsis: the content is wider than the cell.
+overflows = evaluateOnLocator(getByRole('cell', {name: /^R-00001/}), `(el) => el.scrollWidth > el.clientWidth`); // lint-ok: no typed getter reads scrollWidth
+assertTrue(overflows === false, 'the id is cut off');
+```
+
 ---
 
 ## Diagnostics
@@ -2013,6 +2307,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
@@ -2103,7 +2453,8 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
   parse).
 - **Method chains** — `getByRole('row').filter({hasText:'X'}).click()`.
 - **Backticks** — multi-line raw strings, no `${}` interpolation.
-- **Booleans, numbers, strings, `null`**.
+- **Booleans, numbers, strings, `null`** — escapes in strings: see
+  [Escape rules](#escape-rules).
 - **Comparison operators** — `==` / `!=` (loose: `"1" == 1` is true,
   numeric strings coerce), `===` / `!==` (strict: type AND value must
   match, `1 === "1"` is false), `<` `<=` `>` `>=`, logical `&&` / `||`.
@@ -2124,6 +2475,30 @@ inspection.
 See `vendor/dsl/EXTENSIONS.md` for the
 exact grammar deltas from the upstream parser.
 
+### Escape rules
+
+In a quoted string (`'…'` or `"…"`):
+
+| Escape | Gives |
+|---|---|
+| `\n` `\t` `\r` `\f` `\v` | the control character |
+| `\\` | one backslash |
+| `\'` in `'…'`, `\"` in `"…"` | the quote |
+| `\0` (no digit after it) | the NUL character |
+| `\xHH` | the character with that hex code: `"\xA0"` is a non-breaking space |
+| `\uXXXX` | the same with four hex digits: `'\u00A0'` |
+
+A malformed `\x` / `\u` (`'\u12'`, `'\xG1'`) is a parse error at the
+backslash. Any other backslash pair stays **as written** — `'\d+'` is
+three characters, which is what a regex built from a string needs. The
+same goes for `\b`: a word boundary there, never a backspace. `\01` and
+the other quote (`"\'"`) are kept as written too. Backtick strings are raw: no
+escape decodes inside `` `…` ``.
+
+```js
+assertText(getByRole('cell', {name: /^Total/}), '1\u00A0250');   // NBSP between digit groups
+```
+
 ### Strings, objects, indexes
 
 Since 0.44.0.
@@ -2238,14 +2613,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/web",
-  "version": "0.45.0",
+  "version": "0.47.0",
   "description": "AI-native E2E testing for web applications. MCP server (run_test / step / resume / inspect_runtime / agent_fix) + CLI runner + JavaScript DSL scenarios on a sandboxed AST engine + semantic DOM snapshots.",
   "license": "MIT",
   "publishConfig": {
@@ -77,6 +77,7 @@
   "dependencies": {
     "@faker-js/faker": "^10.5.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "ajv": "^8.20.0",
     "chokidar": "^4.0.3",
     "dotenv": "^16.4.5",
     "playwright": "1.62.1",
@@ -84,18 +85,18 @@
     "tsx": "^4.19.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8",
-    "@unotest/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"
+    "@unotest/grounder-client": "^0.47.0",
+    "@unotest/dsl": "^0.47.0",
+    "@unotest/core": "^0.47.0",
+    "@unotest/protocol": "^0.47.0",
+    "@unotest/viewer": "^0.47.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "javascript-obfuscator": "^4.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.2",
-    "@unotest/grounder": "^0.45.0",
-    "@unotest/judge": "^0.45.0"
+    "@unotest/grounder": "^0.47.0",
+    "@unotest/judge": "^0.47.0"
   }
 }