@unotest/web 0.46.0 → 0.47.0

package/guides/dsl-reference.md

@@ -515,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)`
@@ -844,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?)`
@@ -964,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
@@ -1232,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:
@@ -1863,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
@@ -1957,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.
@@ -2047,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
@@ -2115,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
@@ -2315,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 `&&` / `||`.
@@ -2336,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/web",
-  "version": "0.46.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": {
@@ -85,18 +85,18 @@
     "tsx": "^4.19.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8",
-    "@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"
+    "@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/judge": "^0.46.0",
-    "@unotest/grounder": "^0.46.0"
+    "@unotest/grounder": "^0.47.0",
+    "@unotest/judge": "^0.47.0"
   }
 }

package/types/unotest-dsl.d.ts

@@ -234,9 +234,9 @@ declare function assertCount(locator: Locator, count: number): void;
 /**
  * assertUrl(pattern, { timeout? })
  *
- * Current URL contains `pattern`.
+ * Current URL contains `pattern` (a string) or matches it (a /regex/, unanchored). A failure names the pattern as /source/flags.
  */
-declare function assertUrl(pattern: string): void;
+declare function assertUrl(pattern: string | RegExp, options?: any): void;
 
 /**
  * assertJudge(locator, rubric)
@@ -413,6 +413,13 @@ declare function closePage(index?: number): void;
  */
 declare function setViewport(size: any): void;
 
+/**
+ * emulateMedia({ reducedMotion?, colorScheme? })
+ *
+ * Change the media features the current tab reports from now on — what matchMedia and CSS @media see: reducedMotion 'reduce' | 'no-preference', colorScheme 'light' | 'dark' | 'no-preference'. This tab only: a tab or popup opened later starts without it.
+ */
+declare function emulateMedia(media: any): void;
+
 /**
  * newContext() → number
  *
@@ -472,9 +479,9 @@ declare function goForward(): void;
 /**
  * waitForUrl(pattern, { timeout? })
  *
- * Wait until the URL contains `pattern` (substring match).
+ * Wait until the URL contains `pattern` (a string, substring match) or matches it (a /regex/, unanchored).
  */
-declare function waitForUrl(pattern: string): void;
+declare function waitForUrl(pattern: string | RegExp, options?: any): void;
 
 /**
  * waitForNavigation({ timeout? })
@@ -532,6 +539,20 @@ declare function isEnabled(locator: Locator): boolean;
  */
 declare function hasAttribute(locator: Locator, name: string): boolean;
 
+/**
+ * computedStyle(locator, property) → string
+ *
+ * The element's computed CSS value, as the browser resolved it: computedStyle(card, "opacity") → "0.5", custom properties too ("--accent"). "" when the property is not set.
+ */
+declare function computedStyle(locator: Locator, property: string): string;
+
+/**
+ * hasAnimation(locator) → bool
+ *
+ * Whether the element or a descendant has an animation still running towards an end. Infinite (spinners) and paused ones do not count — the same rule waitForAnimations waits by.
+ */
+declare function hasAnimation(locator: Locator): boolean;
+
 /**
  * randomFirstName() → string
  *
@@ -630,6 +651,27 @@ declare function parseJson(text: string): any;
  */
 declare function urlParam(url: string, key: string): any;
 
+/**
+ * toNumber(text, { decimal? }) → number
+ *
+ * A number as a page writes it: '1 234,5', '1,234.56', '−12'. Spaces (NBSP too) group digits; with both ',' and '.' the last one is the decimal mark; one mark used twice groups. '1,234' and '1.234' read both ways and FAIL unless {decimal: ',' | '.'} says which. Units and currency ('440px', '€12') FAIL, quoting the input — cut the number out with textMatches first. A number passes through.
+ */
+declare function toNumber(text: any, options?: any): number;
+
+/**
+ * round(n, digits?) → number
+ *
+ * Round to `digits` decimals (0..10, default 0), half away from zero on the decimal as written: round(2.5) → 3, round(-2.5) → -3, round(1.005, 2) → 1.01.
+ */
+declare function round(n: number, digits?: number): number;
+
+/**
+ * formatNumber(n, { locale?, minFractionDigits?, maxFractionDigits? }) → string
+ *
+ * A number as text, via Intl.NumberFormat with digit grouping. Without a locale it is en-US on every machine: formatNumber(1234.5) → '1,234.5'. Another locale's output (its spaces and marks) comes from the ICU of the Node that runs it.
+ */
+declare function formatNumber(n: number, options?: any): string;
+
 /**
  * env(name) → string | null
  *
@@ -903,6 +945,13 @@ declare function waitForText(text: string | RegExp, options?: any): void;
  */
 declare function waitForCount(locator: Locator, count: number, options?: any): void;
 
+/**
+ * waitForAnimations(locator, { timeout? })
+ *
+ * Wait until the element and its descendants have no animation still running — a dialog done fading in, a card done sliding. Infinite ones (spinners) and paused ones are not waited for. Default timeout 5000 ms; a timeout names the element and how many were left.
+ */
+declare function waitForAnimations(locator: Locator, options?: any): void;
+
 /**
  * pause(ms)
  *
@@ -941,7 +990,7 @@ declare function clockRun(): void;
 /**
  * mockRoute(glob, response)
  *
- * From now on, requests matching `glob` (a Playwright URL glob: `**\/api/items*`) get a fixed answer: `{status?, body?, headers?, contentType?}` (an object body goes as JSON), `{abort: true, record?}` or `{continue: true}` (to the network). Where several masks match, the one mocked last answers; mocking a mask again replaces its answer. A response to `**\/*` is refused; the site's own page is never aborted. Mocks last until the scenario ends.
+ * From now on, requests matching `glob` (a Playwright URL glob: `**\/api/items*`) get a fixed answer: `{status?, body?, headers?, contentType?}` (an object body goes as JSON), `{abort: true, record?}` or `{continue: true}` (to the network). Where several masks match, the one mocked last answers; mocking a mask again replaces its answer. A response to `**\/*` is refused; the site's own page is never aborted. A mask reaches http(s) and ws(s) only, so an extension's own pages and scripts load under `**\/*`; to mock them, start the mask with their scheme (`chrome-extension://<id>/x.js`). Mocks last until the scenario ends.
  */
 declare function mockRoute(glob: string, response: any): void;