@unotest/web 0.45.0 → 0.46.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
@@ -501,6 +544,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
@@ -1086,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` /
@@ -1189,8 +1302,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 +1479,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 +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});
@@ -1503,6 +1639,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 +1675,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`
@@ -2013,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
@@ -2238,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

package/package.json

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

package/types/unotest-dsl.d.ts

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