@unotest/web 0.30.0 → 0.32.0

package/guides/dsl-reference.md

@@ -37,6 +37,68 @@ function test_my_scenario() {
 > one block per logical chunk; anything is allowed inside a block (nested
 > blocks, control flow, comments).
 
+### `step(...)` forms — tags and soft steps
+
+```
+step("label", () => { … });
+step("label", {tag: <expr>}, () => { … });
+step.soft("label", () => { … });
+step.soft("label", {tag: <expr>}, () => { … });
+```
+
+- **`label`** is a string literal — the intent a human reads.
+- **`{tag: <expr>}`** names the case a data-driven step is on: any
+  expression (`q.id`, `textJoin(['q-', i])`), evaluated when the block
+  starts. It rides on every event of the block (`Question [q17]` in the
+  CLI line, a chip on the step in the viewer). `tag` is the only option.
+- **`step.soft(...)`** — a failure inside the body is *recorded* instead
+  of stopping the run: the rest of that body is skipped (as after
+  `expect.soft` inside a Playwright `test.step`), execution continues
+  with the statement after the block, and the test still ends **failed**
+  with every soft failure listed:
+
+  ```
+  ✗ test: test_control_questions (12.4s)
+    3 soft step(s) failed: Question [q17]: …; Question [q42]: …; Question [q58]: …
+    ✗ soft step "Question" [q17]: judge said no: …
+    ✗ soft step "Question" [q42]: …
+  ```
+
+  `return` / `break` / `continue` pass through a soft step untouched. A
+  hard failure after soft ones ends the run with *that* error; the soft
+  list is still attached. The failure bundle shows the page at the moment
+  of the **first** soft failure (`failure.json` carries `soft: true` and
+  `stepTag`); later ones are in the journal (`step-block:finished`) and in
+  `run_test`'s reply (`next.softFailures`).
+- `step.soft` is allowed **inside `test_*` only** (validator
+  `step-shape`): a helper has no test to report a soft failure on.
+  Nesting is free — the usual shape is a plain outer step, a loop, and
+  tagged soft steps inside it. A soft failure does **not** change the
+  outer step's own outcome: the group is not an assertion.
+- In the debugger, resuming past a failure inside a soft step continues
+  with the next statement and records nothing — same as resuming past
+  any failure on web.
+
+The data-driven gate, in full (`readJsonLine` reads the cases; the outer
+`step` satisfies step coverage):
+
+```js
+function test_control_questions() {
+  step("Control questions", () => {
+    for (i = 1; i < 11; i = i + 1) {
+      q = readJsonLine('questions.jsonl', {slot: i});
+      step.soft("Question", {tag: q.id}, () => {
+        fill(getByRole('textbox', {name: 'Message'}), q.text);
+        press(getByRole('textbox', {name: 'Message'}), 'Enter');
+        answer = textContent(getByTestId('last-answer'));
+        screenshot(q.id);
+        assertJudge(answer, q.rubric);
+      });
+    }
+  });
+}
+```
+
 > **Locator quality matters (D-22).** Prefer `getByTestId` →
 > `getByRole(name)` → `getByLabel` → `getByText` → `locator(css)`. The AST
 > linter (`unotest-web lint`) flags brittle selectors — see
@@ -303,8 +365,14 @@ check(getByRole('checkbox', {name: 'Subscribe'}))
 
 ```js
 hover(getByRole('button', {name: 'Help'}))
+// A tall chat bubble whose menu appears only near its top edge: hover
+// the centre and nothing shows — hover an offset inside the element.
+hover(getByTestId('message-42'), {position: {x: 24, y: 8}})
 ```
 
+**Options:** `force?`, `timeout?`, `position?` (no `modifiers` — that
+is a `click` option).
+
 ### `selectOption(loc, value, options?)`
 
 Native `<select>` only. `value` can be a string, an array of strings, or
@@ -453,6 +521,11 @@ Semantics:
   a separate `preamble` field: the model saw the two concatenated, and
   the split says which half came from the scenario and which from the
   environment.
+- **In the viewer** the verdict sits under the step (`judge ✓/✗ ·
+  rubric · text`, open by default when it said no), and the error card
+  of a failed judge step carries the whole verdict — rubric, judged
+  text, reasoning, model. See `note()` below for attaching the question
+  and the answer next to it.
 - A judge is not deterministic: the judge itself re-asks on `fail`
   (`UNOTEST_JUDGE_RETRIES`, first `pass` wins); temperature is pinned to 0
   where the backend accepts it (vertex/gemini). The runner's retry layer is
@@ -881,6 +954,30 @@ step("A personal chat must not leak into the project feed", () => {
 });
 ```
 
+### `readJsonLine(path, filter)` → `object`
+
+The no-wait form of `waitForJsonLine` for a file that **already exists**:
+read it once and return the first line matching `filter`. Use it for
+fixtures and finished exports — a data-driven test reads its cases from
+a JSONL file this way. Same filter rules as `waitForJsonLine` (strict
+equality per key, dot paths for nesting, unparsable lines skipped).
+
+```js
+step("Ask control question 3", () => {
+  q = readJsonLine('questions.jsonl', {slot: 3});
+  fill(getByRole('textbox', {name: 'Message'}), q.text);
+  screenshot(q.id);
+});
+```
+
+- No options and no poll: a missing file fails at once with
+  `file not found: <path>`, a missing line with
+  `no line matches {…} in <path>` plus the same parse stats and
+  closest-line hint `waitForJsonLine` reports on timeout.
+- Pick `waitForJsonLine` when the file is still being written to (a
+  background listener's output); its timeout is what makes that safe,
+  and what would only hide a wrong path here.
+
 ### `waitForFileCount(path, pattern, count, options?)` → `number`
 
 Wait until **at least** `count` lines match, then return how many there
@@ -1152,8 +1249,18 @@ screenshot('bot-reply');                 // 002-bot-reply.png
 screenshot('landing', {fullPage: true}); // full scroll height
 ```
 
-- `name` is slugified to `[a-z0-9._-]` (`'Bot Reply!'` → `bot-reply`);
-  omitted → `shot`. Files are numbered in capture order.
+- `name` is any string value, not only a literal — a data-driven test
+  names its evidence after the case it is on:
+
+  ```js
+  q = waitForJsonLine('questions.jsonl', {slot: 3});
+  screenshot(q.id);                        // 003-q-17.png
+  screenshot(textJoin(['q-', q.id, '-answer']));
+  ```
+
+- `name` is slugified to `[a-z0-9._-]` (`'Bot Reply!'` → `bot-reply`,
+  `'Q 17/a'` → `q-17-a`); omitted → `shot`. Files are numbered in
+  capture order.
 - **Options:** `fullPage?` (default `false` — viewport only).
 - Before capturing, the call waits for the network to go quiet and for a
   painted frame (up to 2s). Without it a `screenshot()` right after
@@ -1174,17 +1281,50 @@ screenshot('landing', {fullPage: true}); // full scroll height
 
 ---
 
-## Logging
+## Logging and notes
 
 ### `log(...args)`
 
-Routes through the runtime's `Logger.info`. Non-string args are
-`JSON.stringify`'d.
+Writes one line to the runner's output (the terminal, the live System
+pane in the viewer) **and** to the run journal (`steps.jsonl`, as a
+`log` event under the current step), so a finished run still shows it
+under the step that wrote it and in the System pane. Non-string args
+are `JSON.stringify`'d.
 
 ```js
 log('user id:', userId);
 ```
 
+### `note(label, value)`
+
+Attach a labelled value to the **current step**: the question a
+data-driven case asked, the answer it got, an id worth seeing next to
+the verdict. Lives in the journal, not in stdout — the viewer shows it
+under the step (an `ⓘ N` chip on the row; the list opens by default
+when the step failed or a judge said no) during and after the run.
+
+```js
+step.soft("Question", {tag: q.id}, () => {
+  note('question', q.text);
+  fill(getByRole('textbox', {name: 'Message'}), q.text);
+  press(getByRole('textbox', {name: 'Message'}), 'Enter');
+  answer = textContent(getByTestId('last-answer'));
+  note('answer', answer);
+  assertJudge(getByTestId('last-answer'), q.rubric);
+});
+```
+
+- `label` is a string; `value` is anything — a string as it is, a
+  number, an object or array serialized as JSON.
+- Long values are cut at 4 KB (marked `truncated`); secrets are masked
+  like everywhere in the run directory.
+- Each `note` / `log` event records where it was called (`file`, `line`,
+  `col`) and the nearest statement of the entry file (`entryLine`,
+  `entryCol`) — a note from inside a helper lands under the entry step
+  that called the helper.
+- Without a run journal (exploration, an ad-hoc runtime) `note` goes to
+  the logger instead; nothing fails.
+
 ---
 
 ## Variables, control flow, types
@@ -1192,8 +1332,13 @@ log('user id:', userId);
 The DSL is JavaScript-shaped but parsed by a small AST engine
 (`vendor/dsl/`), not V8. What's supported in scenario files:
 
-- **`function test_*(): { … }`** — scenario entry; each top-level
-  `function test_*` is a separately runnable test.
+- **`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/`.
 - **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
@@ -1249,8 +1394,10 @@ exact grammar deltas from the upstream parser.
 ## Conventions
 
 - **Snake-case test names** — `function test_login_happy_path()`.
-- **One scenario file = one feature.** Multiple `test_*` entries are
-  fine when they share a feature surface.
+- **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_*`.
 - **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.30.0",
+  "version": "0.32.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": {
@@ -83,18 +83,18 @@
     "tsx": "^4.19.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8",
-    "@unotest/core": "^0.30.0",
-    "@unotest/viewer": "^0.30.0",
-    "@unotest/grounder-client": "^0.30.0",
-    "@unotest/dsl": "^0.30.0",
-    "@unotest/protocol": "^0.30.0"
+    "@unotest/core": "^0.32.0",
+    "@unotest/protocol": "^0.32.0",
+    "@unotest/grounder-client": "^0.32.0",
+    "@unotest/dsl": "^0.32.0",
+    "@unotest/viewer": "^0.32.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
     "javascript-obfuscator": "^4.1.1",
     "tsup": "^8.5.1",
     "typescript": "^5.7.2",
-    "@unotest/judge": "^0.30.0",
-    "@unotest/grounder": "^0.30.0"
+    "@unotest/grounder": "^0.32.0",
+    "@unotest/judge": "^0.32.0"
   }
 }

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

@@ -49,6 +49,14 @@ 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).
+
 ## Locator hierarchy (D-22, hard rule)
 
 When choosing a selector, prefer in this exact order:
@@ -310,7 +318,9 @@ A login (or any setup block) that many tests share should be a reusable
 - **Flow already exists** (it's in `availableFlows`): call
   `explore_run_flow({ explorationId, name })`. It replays the flow LIVE (you end
   up logged in) and records a single `flow_<name>()` call — don't re-record the
-  steps.
+  steps. A flow with parameters (`params` in `availableFlows`) takes them as
+  `args`, positional — `args: ["{{LOGIN}}", "{{PASSWORD}}"]` replays on the
+  values and records `flow_login(LOGIN, PASSWORD)`; the count must match.
 - **First time** (no flow yet): record the block normally but put
   `flow:"signin"` on every step of it (`explore_step({…, flow:"signin"})`).
   On `save_exploration_as_test`, those steps are extracted into

package/types/unotest-dsl.d.ts

@@ -120,9 +120,9 @@ declare function check(locator: Locator, options?: any): void;
 declare function uncheck(locator: Locator, options?: any): void;
 
 /**
- * hover(locator, { force?, timeout? })
+ * hover(locator, { force?, position?, timeout? })
  *
- * Hover over an element.
+ * Hover over an element. `position` is an {x, y} offset inside it — for a menu that only appears at one edge of a tall element.
  */
 declare function hover(locator: Locator, options?: any): void;
 
@@ -280,6 +280,13 @@ declare function randomNth(receiver: Locator): Locator;
  */
 declare function screenshot(name?: string, options?: any): string;
 
+/**
+ * note(label, value)
+ *
+ * Attach a labelled value to the current step: shown in the viewer under the step (also after the run) and kept in the run journal. Any value — a string, a number, an object (recorded as JSON). Secrets are masked; long values are cut at 4 KB. Use it for the question a data-driven case asked and the answer it got.
+ */
+declare function note(label: string, value: any): void;
+
 /**
  * evaluate(js, arg?) → any
  *
@@ -511,6 +518,13 @@ declare function waitForJsonLine(path: string, filter: any, options?: any): any;
  */
 declare function assertNoJsonLine(path: string, filter: any, options?: any): void;
 
+/**
+ * readJsonLine(path, filter) → object
+ *
+ * First matching line of a JSONL file that already exists, no wait: one read, same key filter as waitForJsonLine. FAILS at once when the file is missing or no line matches — use it for fixtures and finished exports, waitForJsonLine for a file still being written.
+ */
+declare function readJsonLine(path: string, filter: any): any;
+
 /**
  * waitForFileCount(path, pattern, count, options?) → number
  *
@@ -654,7 +668,7 @@ declare function getUrl(): string;
 /**
  * log(...args)
  *
- * Write to the run trace.
+ * Write a line to the runner's output AND to the run journal, under the current step — visible in the viewer's System pane after the run too.
  */
 declare function log(message: any, ...args: unknown[]): void;
 
@@ -714,8 +728,18 @@ declare function waitForCount(locator: Locator, count: number, options?: any): v
  */
 declare function pause(ms: number): void;
 
-/** step(label, body)
+/** step(label, [options,] body)
  *
  *  Groups statements under a labelled block. Every direct child of a
- *  test_* function must sit inside a step(...). */
+ *  test_* function must sit inside a step(...). `{tag}` names the case a
+ *  data-driven step is on. */
 declare function step(label: string, body: () => void): void;
+declare function step(label: string, options: { tag: unknown }, body: () => void): void;
+declare namespace step {
+  /** step.soft(label, [options,] body)
+   *
+   *  A failure inside is recorded and the run continues after the block;
+   *  the test still ends failed. Allowed inside test_* only. */
+  function soft(label: string, body: () => void): void;
+  function soft(label: string, options: { tag: unknown }, body: () => void): void;
+}

package/dist/linter-CM2CpIyW.d.ts

@@ -1,21 +0,0 @@
-import { BlockStatement } from '@unotest/dsl';
-
-type LintSeverity = 'error' | 'warning' | 'info';
-interface LintDiagnostic {
-    rule: string;
-    severity: LintSeverity;
-    message: string;
-    line: number;
-    col: number;
-}
-interface LintOptions {
-    /** Per-rule severity override. Default severities live with each rule. */
-    ruleSeverity?: Partial<Record<string, LintSeverity>>;
-    /** Pass through if the agent provided documented justification — e.g. a
-     *  `// reason:` comment immediately above the line. The lexer doesn't
-     *  preserve comments today; for v1 we accept a flag from the caller. */
-    allowDisambigByIndex?: boolean;
-}
-declare function lintAst(ast: BlockStatement, opts?: LintOptions): LintDiagnostic[];
-
-export { type LintDiagnostic as L, type LintSeverity as a, type LintOptions as b, lintAst as l };