@unotest/web 0.49.0 → 0.49.1

package/guides/dsl-reference.md

@@ -446,8 +446,16 @@ list that is still filling in passes once it is complete.
 
 ```js
 assertTexts(getByRole('listitem'), ['Apple', 'Banana', /^Cherry/])
+labels = ['Apple', 'Banana'];
+assertTexts(getByRole('listitem'), labels)
+assertText(getByRole('listitem').first(), labels[0])
 ```
 
+`expected` is any expression that holds a list: a literal, a variable,
+an index read, a helper's result. A value known to be something else (a
+string, a number) is refused by the linter; the rest is checked when the
+step runs. The same holds for the expected text of `assertText`.
+
 **Options:** `timeout?`, `exact?` (default `true`).
 
 ### `assertAttribute(loc, name, expected, options?)`
@@ -610,18 +618,22 @@ function test_live_payment() {
 }
 ```
 
-A decision on data the test reads goes after the step that reads it:
+A decision on data the test reads goes after the step that reads it, or
+inside that step:
 
 ```js
 function test_refund() {
   step("Find a paid order", () => {
     orders = apiCall('GET', '/orders?status=paid');
+    if (orders.length == 0) { skip('no paid order on this stand'); }
   });
-  skip('no paid order on this stand', orders.length == 0);
   // …
 }
 ```
 
+The rest of the test does not run; teardown blocks already registered
+still play.
+
 - 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)`.
@@ -630,9 +642,8 @@ function test_refund() {
   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`.
+- Call it in the `test_*` body — at its top or inside a step or a block.
+  In a helper or a `flow_*` it is reported by `lint:skip-outside-test`.
 
 ### `assertJudge(loc, rubric)`
 
@@ -816,6 +827,19 @@ Read state without asserting. No polling.
 
 ### `count(loc)` → `number`
 
+How many elements match now. To count by a condition, narrow the
+locator: by text or by a child — `.filter({...})`; by the element's own
+class or attribute — CSS. `assertCount` / `waitForCount` take the same
+locator and wait for the number.
+
+```js
+done = count(getByRole('row').filter({hasText: 'Done'}));
+admins = count(getByRole('row').filter({has: getByTestId('admin-badge')}));
+selected = count(locator('li.selected'));
+external = count(locator('a[target="_blank"]'));
+assertCount(getByRole('listitem').filter({hasNotText: 'Archived'}), 3)
+```
+
 ### `textContent(loc)` → `string`
 
 Empty string when the element has no text node (does not throw).
@@ -1719,8 +1743,8 @@ step("Send button uses the app's own label", () => {
 - 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").
+  generate the JSON from them instead — see
+  [App constants in scenarios](https://docs.unotest.com/concepts/scenarios/#app-constants-in-scenarios).
 
 ### `env(name)` → `string | null`
 
@@ -2057,6 +2081,29 @@ assertTrue(computedStyle(getByRole('dialog'), 'opacity') == 1, 'dialog is faded'
 accent = computedStyle(locator('body'), '--accent');
 ```
 
+### `getImageSize(loc)` → `{width, height}` | `null`
+
+The natural size of an `<img>` — the pixels of the file, not its size on
+the page (that is `boundingBox`). `null` when the image has no pixels:
+the file is broken, or there is no `src`. The one query that waits: an
+image still loading is waited for up to the action timeout, so a good
+image is never read too early as broken.
+
+- Not an `<img>` fails with a `LocatorError` naming the tag. An inline
+  `<svg>` has no natural size — `boundingBox` gives its rendered one.
+- Still loading when the timeout runs out fails with a `TimeoutError`.
+  A `loading="lazy"` image below the fold never starts —
+  `scrollIntoView(loc)` it first.
+- An SVG file without its own `width` / `height` reports the browser's
+  default (300 × 150 in Chromium): check it is not `null`, not the
+  numbers.
+
+```js
+size = getImageSize(getByRole('img', {name: 'Avatar'}));
+assertTrue(size !== null, 'avatar is broken');
+assertTrue(size.width >= 256, json(size));
+```
+
 ### `hasAnimation(loc)` → `boolean`
 
 Whether the element or a descendant has an animation still running
@@ -2466,7 +2513,17 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
   viewer shows it as its own row under the file. `e2e <file>` plays them
   in order; `e2e <file> --test <name>` plays one. Functions of the file
   are shared between its tests, state is not.
-- **Assignments** — `name = expression;` (no `let`/`const`/`var`).
+- **Top level of a file — function definitions and `const` literals.**
+  Nothing else there runs: `BASE = 'x'` above `test_*` would leave
+  `BASE` undefined in the test, so `lint` refuses it
+  (`validator:unsupported-statement`). A shared fixed value is a const:
+  `const BASE = 'https://x.test';` — a literal only (number, string,
+  `true` / `false` / `null`, or an array or object of those), visible in
+  every function, as helper functions are. A computed one is a function:
+  `function base_url() { return env('BASE'); }`.
+- **Assignments** — `name = expression;`, or `let name = …;` /
+  `const name = …;`: see [let, const and lambdas](#let-const-and-lambdas).
+  `var` is refused.
 - **`if` / `else`** and **`for` in the canonical shape**
   `for (i = 0; i < N; i = i + 1) { … }` (increment must be an
   assignment — `i++` is rejected everywhere). A loop over cases, each a
@@ -2490,8 +2547,8 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
 - **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 —
-  `arr.push(v)` appends: see [Logical not and arrays](#logical-not-and-arrays).
+  (`.filter(...)`). `arr[i] = v` replaces an element, `arr.push(v)`
+  appends, `arr.sortBy(key)` sorts: see [Logical not and arrays](#logical-not-and-arrays).
 - **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
@@ -2504,6 +2561,9 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
   numeric strings coerce), `===` / `!==` (strict: type AND value must
   match, `1 === "1"` is false), `<` `<=` `>` `>=`, logical `&&` / `||`
   and `!` (see [Logical not and arrays](#logical-not-and-arrays)).
+  `&&` and `||` short-circuit as in JS and give a boolean: the right side
+  is skipped once the left one decides, so `x != null && x.a == 1` is a
+  safe null guard (also inside `waitUntil`).
   Caveat: DOM reads (`textContent`, `getInputValue`, `getAttribute`)
   return **strings** — for comparing against a number use `==`
   (`getAttribute(loc, "data-count") === 5` is always false; write
@@ -2511,13 +2571,20 @@ 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
+functions as values (a lambda goes only into `filter` / `map` / `find` /
+`some`), async/await (everything is sequenced by the AST
 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.
 
+The only arrows are the fixed ones of `step(...)`, `teardown(...)` and
+`waitUntil(...)`, and their body may be a block: `waitUntil(() => {
+n = count(rows); return n > 3; })`. A callback (`a.map(x => …)`), a
+ternary, `+=`, `for…of`, `o.a = 2` and the like are refused by `lint`
+with what to write instead.
+
 See `vendor/dsl/EXTENSIONS.md` for the
 exact grammar deltas from the upstream parser.
 
@@ -2549,7 +2616,7 @@ assertText(getByRole('cell', {name: /^Total/}), '1\u00A0250');   // NBSP between
 
 Since 0.44.0.
 
-**Strings** answer four members — the whole list:
+**Strings** answer these members — the whole list:
 
 | Member | Returns | |
 |---|---|---|
@@ -2557,6 +2624,7 @@ Since 0.44.0.
 | `s.trim()` | `string` | whitespace off both ends |
 | `s.includes(search)` | `boolean` | substring probe, same as `textContains(s, search)` |
 | `s.startsWith(prefix)` | `boolean` | |
+| `s.split(separator)` | array of strings | as in JS: parts keep their spaces, a missing separator gives one part |
 
 They work wherever an expression does — in `assertTrue`, in `if`, on a
 literal, on a call result:
@@ -2566,9 +2634,10 @@ title = getTitle();
 assertTrue(title.trim().length > 0, 'empty title');
 if (out.stdout.includes('ready')) { log('up'); }
 assertTrue(getUrl().startsWith('https://'), getUrl());
+ids = 'a, b'.split(', ');        // ['a', 'b']
 ```
 
-Any other member is a lint error that names it and lists the four
+Any other member is a lint error that names it and lists them
 (`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
@@ -2609,8 +2678,9 @@ assertTrue(!out.stdout.includes('error'), out.stdout);
 ```
 
 **`arr.push(x, …)`** appends to the array in place and returns its new
-length. Other array methods (`pop`, `map`, `join`, …) are not there;
-`length` is.
+length. Other JS array methods (`pop`, `join`, `reduce`, …) are not
+there; `length`, `sortBy` and the lambda methods `filter` / `map` /
+`find` / `some` ([let, const and lambdas](#let-const-and-lambdas)) are.
 
 ```js
 rows = getByRole('row');
@@ -2629,6 +2699,69 @@ that is not an array — a string, a number, a `null` field — fails the
 step with that type in the message; on a string the linter flags it
 first.
 
+**`arr[i] = v`** replaces element `i`, nested too (`grid[r][c] = v`); on
+an object it sets the key (`o["k"] = v`). The index is an integer from
+`0` to `arr.length`: the length itself appends, anything further out
+fails the step instead of leaving holes. The keys `__proto__`,
+`constructor` and `prototype` cannot be assigned, and an index read on
+an object sees its own keys only. Property assignment (`o.k = v`) stays
+unsupported.
+
+**`arr.sortBy(key?, {desc?})`** sorts the array in place and returns it.
+With a key every element is an object and its field is compared;
+without one (`sortBy()`, or `sortBy(null, {desc: true})`) the elements
+themselves. The compared values are all numbers or all strings —
+anything else fails the step. The sort is stable: equal keys keep their
+order.
+
+```js
+controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
+controls.sortBy('order');            // a, b
+controls.sortBy('order', {desc: true});
+controls[0] = {id: 'z', order: 0};
+```
+
+### let, const and lambdas
+
+**`let x = …;`** and **`const x = …;`** declare a variable. They are the
+bare assignment `x = …;` with a name for intent: the scope is the
+function's, as for any variable here — a block does not make one.
+`for (let i = 0; i < n; i = i + 1)` declares the loop variable. A const
+needs a value and is not assigned again: `lint` refuses it
+(`validator:const-assign`) and a run fails at that line, as JavaScript
+does. The array or object it holds can still change (`ids.push(x)`). `var`
+is refused.
+
+A **lambda** — `x => expr`, `(x, i) => expr`, or a block with `return` —
+goes into exactly four array methods, as their argument:
+
+| Call | Returns |
+|---|---|
+| `a.filter(x => cond)` | a new array of the elements for which `cond` is truthy |
+| `a.map((x, i) => value)` | a new array of the values |
+| `a.find(x => cond)` | the first element for which `cond` is truthy, or `null` |
+| `a.some(x => cond)` | `true` if `cond` is truthy for any element |
+
+```js
+const rows = fetchData('orders');
+let open = rows.filter(r => r.status == 'open');
+ids = open.map((r, i) => i + ': ' + r.id);
+first = rows.find(r => {
+  if (r.total > 100) { return true; }
+  return false;
+});
+assertTrue(rows.some(r => r.id == '42'), json(ids));
+```
+
+The parameters live in a scope of their own, like a helper's: the body
+reads the variables around it, and what it assigns stays inside. The
+body runs element by element, so a call in it — `textContent(…)`,
+`count(…)` — is a step of its own. A lambda is not a value: it cannot be
+assigned, returned or passed anywhere else (`validator:lambda-position`),
+and on a value that is not an array the step fails. With a lambda,
+`filter` is the array method; with an options object it is still the
+locator step `getByRole('row').filter({hasText: 'x'})`.
+
 ### `teardown` — give the stand back
 
 Since 0.44.0.
@@ -2758,8 +2891,21 @@ helpers. A function, parameter or variable of your own named
   file's leading comments, set apart from the first function by a blank
   line, mark every test in it. A marker trailing code (`foo(); //
   @expect-fail`) or inside a body is a comment, not a marker.
+
+  A marked test that fails is reported as failed on purpose:
+  `✗ test: test_x (…ms) — failed on purpose (@expect-fail)` in `e2e`,
+  `N of M failed on purpose` and `expected=N` in a collection, and the
+  viewer shows it as expected rather than failing. A collection whose
+  only failures are on purpose exits 0; `e2e` of such a test still exits
+  1 — the test did fail. A marked test that passes is a failure: the bug
+  it guarded is gone, so either remove the marker or fix the test.
 - **Helpers stay in `unotest/e2e/_helpers/`** — these are project-owned,
   not part of the core surface. Use sandbox primitives there.
+- **A helper for one scenario can live in its file.** A function defined
+  at the top level of a scenario is a helper like one in `_helpers/`,
+  seen only by that file: the run calls it and `lint` knows its name. A
+  misspelt call is reported wherever it stands, inside an object
+  argument too (`apiCall('POST', '/pages', {html: page_html()})`).
 - **Two kinds of helper.** A `flow_*` helper is a composite journey —
   sign-in, checkout — and is *executable on its own*: the runner accepts it
   as an entry and the agent can replay it while recording. A plain
@@ -2781,4 +2927,6 @@ helpers. A function, parameter or variable of your own named
   and yields its result (`email = flow_signup()`), a rename hint when it
   only reads.
 - **Lint before you ship** — `npx @unotest/web lint` runs the AST
-  linter across `unotest/e2e/**/*.js`.
+  linter across `unotest/e2e/**/*.js`. `lint <name>` checks one scenario,
+  named as `e2e` takes it (`lint values/string-escapes`); a file or a
+  folder works too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/web",
-  "version": "0.49.0",
+  "version": "0.49.1",
   "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.49.0",
-    "@unotest/protocol": "^0.49.0",
-    "@unotest/dsl": "^0.49.0",
-    "@unotest/grounder-client": "^0.49.0",
-    "@unotest/viewer": "^0.49.0"
+    "@unotest/core": "^0.49.1",
+    "@unotest/dsl": "^0.49.1",
+    "@unotest/protocol": "^0.49.1",
+    "@unotest/grounder-client": "^0.49.1",
+    "@unotest/viewer": "^0.49.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "javascript-obfuscator": "^4.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.2",
-    "@unotest/grounder": "^0.49.0",
-    "@unotest/judge": "^0.49.0"
+    "@unotest/judge": "^0.49.1",
+    "@unotest/grounder": "^0.49.1"
   }
 }

package/types/unotest-dsl.d.ts

@@ -187,7 +187,7 @@ declare function assertText(locator: Locator, text: string | RegExp, options?: a
  *
  * 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;
+declare function assertTexts(locator: Locator, expected: unknown[], options?: any): void;
 
 /**
  * assertAttribute(locator, name, expected, { exact?, not?, timeout? })
@@ -546,6 +546,13 @@ declare function hasAttribute(locator: Locator, name: string): boolean;
  */
 declare function computedStyle(locator: Locator, property: string): string;
 
+/**
+ * getImageSize(locator) → {width, height} | null
+ *
+ * Natural size of an <img>, once it has loaded or failed (waits up to the action timeout); null when it has no pixels — broken, or no src. Not an <img> fails.
+ */
+declare function getImageSize(locator: Locator): any;
+
 /**
  * hasAnimation(locator) → bool
  *