@unotest/web 0.47.0 → 0.49.0

package/guides/dsl-reference.md

@@ -79,6 +79,11 @@ step.soft("label", {tag: <expr>}, () => { … });
   with the next statement and records nothing — same as resuming past
   any failure on web.
 
+Porting a `@playwright/test` spec with several `test(...)` calls — one
+`step.soft` per former test — and running one test over a table or a
+JSONL file of cases are worked through in
+[Port a @playwright/test spec](https://docs.unotest.com/guides/port-a-spec/).
+
 The data-driven gate, in full (`readJsonLine` reads the cases; the outer
 `step` satisfies step coverage):
 
@@ -285,11 +290,15 @@ Each requires a locator as the receiver / first argument.
 
 ### `filter(options)`
 
-Narrow down a locator. `hasText`, `hasNotText`, `has`, `hasNot`.
+Narrow down a locator. `hasText`, `hasNotText`, `has`, `hasNot` — any
+other key is refused, at lint time (`lint:filter-unknown-option`) and at
+run time. A class or an attribute of the element itself goes into a CSS
+`locator(...)` instead.
 
 ```js
 getByRole('row').filter({hasText: 'Alice'})
 getByRole('row').filter({has: getByTestId('admin-badge')})
+locator('tr.done')                                  // own class: CSS, not filter
 ```
 
 ### `first()`, `last()`, `nth(index)`
@@ -459,9 +468,11 @@ assertAttribute(getByRole('form'), 'aria-busy', 'true', {not: true})
 
 ### `assertVisible(loc, options?)` / `assertHidden(loc, options?)`
 
+**Options:** `timeout?`.
+
 ```js
 assertVisible(getByTestId('toast'))
-assertHidden(getByTestId('spinner'))
+assertHidden(getByTestId('spinner'), {timeout: 10000})
 ```
 
 ### `assertNeverAppears(loc, options)`
@@ -486,6 +497,8 @@ the whole window.
 
 Compares `inputValue()` (`<input>`, `<textarea>`, native `<select>`).
 
+**Options:** `timeout?`.
+
 ```js
 assertValue(getByLabel('Email'), 'a@b.c')
 ```
@@ -509,8 +522,11 @@ value, and so does the failure.
 
 ### `assertCount(loc, expected, options?)`
 
+**Options:** `timeout?`.
+
 ```js
 assertCount(getByRole('listitem'), 5)
+assertCount(getByRole('row'), 20, {timeout: 15000})
 ```
 
 ### `assertUrl(pattern, options?)`
@@ -541,7 +557,7 @@ assertTrue(probe.code == 0, 'app.log should contain "ready"');
 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:
+the two sides, every line of them — nothing is folded away:
 
 ```js
 body = parseJson(getAttribute(locator('#state'), 'data-json'));
@@ -1254,9 +1270,14 @@ Both fields are required. Anything else is refused on that line,
 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.
+`setViewport(null)` runs the test on the real window — but only before
+the test does anything in its browser: the first navigation, `mockRoute`,
+a cookie or storage value, the page clock, `emulateMedia`, a second page
+or context. It opens the browser context again with the same options;
+after any of those it is refused, since the new context would lose them.
+On a browser profile (`launch.userDataDir`, `launch.profile`) it is
+refused always. For a whole suite, set `viewport: null` in the config;
+for the runs of one collection, in its YAML (below).
 
 ### `emulateMedia({reducedMotion?, colorScheme?})`
 
@@ -1288,7 +1309,21 @@ Where the window's size and scale come from, first match wins:
    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`:
+2. **The collection.** `viewport:` in `unotest/e2e/_collections/<name>.yaml`
+   applies to every scenario that collection runs; the same scenario run
+   on its own keeps the config's window. `null` is the real window,
+   `{width, height}` a size (whole pixels, both required):
+
+   ```yaml
+   viewport: null
+   scenarios:
+     - shots/gallery
+   ```
+
+   It works with a browser profile, where `setViewport(null)` cannot. A
+   `viewport: null` here over a config `device` is refused before the
+   first scenario starts, as in the config.
+3. **The config.** `unotest.config.mjs`:
 
    ```js
    export default {
@@ -1315,12 +1350,12 @@ Where the window's size and scale come from, first match wins:
 
    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
+4. **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.
+5. **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
@@ -1367,9 +1402,10 @@ goto('chrome-extension://' + id + '/popup.html');
   `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
+- `evaluateInServiceWorker(js, ...args)` — `evaluate` in the worker. The
+  extras reach the body by the same rule as `evaluate`: none →
+  `undefined`, one → the value itself, two or more → one array. 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,
@@ -2226,12 +2262,16 @@ getters or the action API.
 height = evaluate(`document.documentElement.scrollHeight`);
 ```
 
-Multi-arg form (args destructured in the page-side function):
+The extra arguments reach the body by one rule: none → `undefined`,
+exactly one → the value itself, two or more → ONE array the body
+destructures. So one argument is `function(x)`, not `function([x])` —
+that one fails with `2 is not iterable`.
 
 ```js
+doubled = evaluate(`function(n) { return n * 2; }`, 21);   // one → the value
 result = evaluate(
   `function([a, b]) { return window.myApp.compute(a, b); }`,
-  10, 20
+  10, 20                                                    // two → one array
 );
 ```
 
@@ -2239,8 +2279,9 @@ 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.
+The body gets the element first, then the extras by the same rule as
+`evaluate`: none → `undefined`, one → the value itself, two or more → one
+array.
 
 ```js
 ok = evaluateOnLocator(getByRole('main'), `(el, [a, b]) => el.children.length > a + b`, 1, 2);
@@ -2408,6 +2449,10 @@ step.soft("Question", {tag: q.id}, () => {
   that called the helper.
 - Without a run journal (exploration, an ad-hoc runtime) `note` goes to
   the logger instead; nothing fails.
+- When a statement fails, the notes of its `step(...)` block (the
+  innermost one, in call order) come with the failure: under the error
+  in the `e2e` output as `note label: value`, and as `notes` in the
+  failure `run_test` returns. A green step prints nothing extra.
 
 ---
 
@@ -2416,17 +2461,16 @@ step.soft("Question", {tag: q.id}, () => {
 The DSL is JavaScript-shaped but parsed by a small AST engine
 (`vendor/dsl/`), not V8. What's supported in scenario files:
 
-- **`function test_*(): { … }`** — the scenario entry, **exactly one per
-  file**: a collection runs files, and the viewer projects a run onto
-  the first `test_*` it finds. A second `test_*` is reported by
-  `lint:one-test-per-file` (a warning in 0.31, an error in a later
-  release) — fold the cases into one test with tagged steps
-  (`step("…", {tag: id}, …)`), or move shared journeys to
-  `unotest/e2e/_helpers/`.
+- **`function test_*(): { … }`** — a test. A file may hold several; each
+  is its own run with its own browser context, retry and verdict, and the
+  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`).
 - **`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).
+  assignment — `i++` is rejected everywhere). A loop over cases, each a
+  tagged soft step: [Port a @playwright/test spec](https://docs.unotest.com/guides/port-a-spec/).
 - **`break`** — inside a loop body only. Typical polling loop:
 
   ```js
@@ -2446,7 +2490,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.
+  (`.filter(...)`), and `arr[i] = v` assignment stays unsupported —
+  `arr.push(v)` appends: 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
@@ -2457,7 +2502,8 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
   [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 `&&` / `||`.
+  match, `1 === "1"` is false), `<` `<=` `>` `>=`, logical `&&` / `||`
+  and `!` (see [Logical not and arrays](#logical-not-and-arrays)).
   Caveat: DOM reads (`textContent`, `getInputValue`, `getAttribute`)
   return **strings** — for comparing against a number use `==`
   (`getAttribute(loc, "data-count") === 5` is always false; write
@@ -2548,6 +2594,41 @@ assertTrue(res.body.items[0].status == 'ready', json(res.body));
 first = dbQuery('SELECT id FROM users ORDER BY id')[0].id;
 ```
 
+### Logical not and arrays
+
+Since 0.48.0.
+
+**`!x`** negates, as in JS: the result is always `true` or `false`, and
+`0`, `""`, `null` and `false` are the falsy values — the same ones `if`
+treats as false. An array or an object is truthy, empty or not. `!`
+binds tighter than any other operator: `!a && b` is `(!a) && b`.
+
+```js
+if (!isVisible(getByRole('dialog'))) { log('dialog closed'); }
+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.
+
+```js
+rows = getByRole('row');
+ids = [];
+for (i = 0; i < count(rows); i = i + 1) {
+  ids.push(textContent(rows.nth(i)));
+}
+assertTrue(ids.length > 0, json(ids));
+```
+
+A variable holds the array itself, not a copy, as in JS: after
+`b = a; a.push(1)`, `b` has the new element too. So does a caller whose
+array a helper pushed onto. A helper that assigns a new array to its
+parameter (`list = []`) changes only its own name. `push` on a value
+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.
+
 ### `teardown` — give the stand back
 
 Since 0.44.0.
@@ -2656,10 +2737,27 @@ helpers. A function, parameter or variable of your own named
 ## Conventions
 
 - **Snake-case test names** — `function test_login_happy_path()`.
-- **One scenario file = one test.** The file is the unit a collection
-  runs and the viewer shows; several cases of one feature are one
-  `test_*` with a loop and `step("…", {tag: id}, …)` per case, not
-  several `test_*`.
+- **Tests of one feature share a file.** Several `test_*` in a file are
+  several runs — a collection counts and reports each. Many cases of ONE
+  behaviour can still be one test with a loop and
+  `step("…", {tag: id}, …)` per case.
+- **Expected failures — `// @expect-fail`.** A test that is supposed to
+  fail carries the marker in a `//` comment. Where it sits says which
+  tests it is about:
+
+  ```js
+  // @expect-fail                     <- every test in this file
+
+  // The badge must stay hidden.
+  // @expect-fail                     <- test_badge_hidden only
+  function test_badge_hidden() { … }
+  ```
+
+  The `//` lines directly above a `function test_*` — no blank line
+  between — belong to that test, the first one in the file included. The
+  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.
 - **Helpers stay in `unotest/e2e/_helpers/`** — these are project-owned,
   not part of the core surface. Use sandbox primitives there.
 - **Two kinds of helper.** A `flow_*` helper is a composite journey —

package/package.json

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

package/src/mcp/prompts/agent-test-author.md

@@ -49,13 +49,16 @@ The linter rejects a test in the e2e root (`lint:scenario-in-root`), and
 from the area of the app under test. Shared helpers live in
 `unotest/e2e/_helpers/`; `_template.js` is a starting point to copy.
 
-One `test_*` per file. The file is what a collection runs and what the viewer
-shows (its Steps tree projects the run onto the first `test_*`; any other
-runs unseen). Several cases of one feature are ONE test with a loop and
-`step("…", {tag: id}, () => { … })` per case — `step.soft` when a failed case
-must not stop the run; shared journeys are `flow_*` helpers in
-`unotest/e2e/_helpers/`. A second `test_*` is flagged by
-`lint:one-test-per-file` (a warning today, an error in a later release).
+A file may hold several `test_*` — the tests of one feature. Each test is
+its own run: its own browser context, retry, verdict and row in the viewer,
+under the file. Functions of the file are shared between them; state is
+not — every test starts from a fresh context. `run_test` plays one test:
+in a file of several, name it (`run_test {name, test: "test_…"}`); without
+it the reply is `test_required` with the file's tests. Many cases of one
+behaviour can still be ONE test with a loop and
+`step("…", {tag: id}, () => { … })` per case — `step.soft` when a failed
+case must not stop the run; shared journeys are `flow_*` helpers in
+`unotest/e2e/_helpers/`.
 
 ## Locator hierarchy (D-22, hard rule)
 

package/types/unotest-dsl.d.ts

@@ -201,14 +201,14 @@ declare function assertAttribute(locator: Locator, name: string, value: string |
  *
  * Element is visible.
  */
-declare function assertVisible(locator: Locator): void;
+declare function assertVisible(locator: Locator, options?: any): void;
 
 /**
  * assertHidden(locator, { timeout? })
  *
  * Element is hidden or detached.
  */
-declare function assertHidden(locator: Locator): void;
+declare function assertHidden(locator: Locator, options?: any): void;
 
 /**
  * assertNeverAppears(locator, { withinMs })
@@ -222,14 +222,14 @@ declare function assertNeverAppears(locator: Locator, options: any): void;
  *
  * Input's value equals `expected`. On a checkbox/radio/switch: its checked state — pass 'true' or 'false'.
  */
-declare function assertValue(locator: Locator, value: string): void;
+declare function assertValue(locator: Locator, value: string, options?: any): void;
 
 /**
  * assertCount(locator, expected, { timeout? })
  *
  * Number of matches equals `expected`.
  */
-declare function assertCount(locator: Locator, count: number): void;
+declare function assertCount(locator: Locator, count: number, options?: any): void;
 
 /**
  * assertUrl(pattern, { timeout? })