@unotest/web 0.49.1 → 0.49.2

package/guides/dsl-reference.md

@@ -113,12 +113,13 @@ function test_control_questions() {
 
 Scenarios are plain `.js` with an implicit global vocabulary, so an
 untouched editor shows them as broken JavaScript. `npx @unotest/web init`
-wires the fix; on an existing project the first `lint` / `e2e` run after a
-package upgrade wires it automatically (announced with one line). What it
-consists of:
+wires the fix; on an existing project, or a fresh checkout,
+`npx @unotest/web types` does. A run never writes the editor config. What
+it consists of:
 
 - `unotest/jsconfig.json` — points the IDE at the two declaration files
-  below. Created once when missing; never rewritten silently. Type
+  below. Written by `init` (which also adds it to `.gitignore`) and by
+  `types` when missing; never rewritten silently. Type
   CHECKING stays off (`checkJs: false`) on purpose: diagnostics come from
   the DSL validator (`npx @unotest/web lint`), the editor only gains
   completion, hover docs, signature help and locator-chain resolution.
@@ -211,14 +212,19 @@ instead of waiting the default.
 
 ## Builders
 
-### `locator(selector)`
+### `locator(selector, options?)`
 
 CSS selector, last-resort escape hatch. Use only when nothing else works
 — the linter discourages this with `lint:deep-css` for `>`-bearing
 selectors.
 
+`options` narrows the matches exactly as [`filter`](#filteroptions)
+does: the same keys (`hasText`, `hasNotText`, `has`, `hasNot`), the same
+refusal of any other key, at lint time and at run time.
+
 ```js
 locator('.error-banner')
+locator('option', {hasText: 'Beta'})               // = locator('option').filter({hasText: 'Beta'})
 ```
 
 ### `getByRole(role, options?)`
@@ -227,10 +233,20 @@ ARIA role. `options.name` is the accessible name — string or regex
 (see [Matcher arguments](#matcher-arguments--string--regexp)).
 Substring by default, exact with `{exact: true}`.
 
+The other options narrow by ARIA state, as Playwright's `getByRole` does:
+`checked`, `disabled`, `expanded`, `pressed`, `selected` (true / false),
+`level` (a heading level from 1) and `includeHidden` (true — match
+elements hidden from the accessibility tree too). Any other key is
+refused, at lint time (`lint:role-unknown-option`) and at run time — it
+would otherwise match without it.
+
 ```js
 getByRole('button', {name: 'Save'})
 getByRole('heading', {name: 'Welcome', exact: true})
 getByRole('link', {name: /^Sets/})        // regex matcher
+getByRole('button', {name: 'Save', disabled: false})   // the enabled one
+getByRole('checkbox', {checked: true})
+getByRole('heading', {level: 2})
 ```
 
 ### `getByText(text, options?)`
@@ -375,10 +391,19 @@ press(getByLabel('Body'), 'Control+A')
 
 ### `check(loc, options?)` / `uncheck(loc, options?)`
 
-Idempotent — no-op if already in the target state.
+Idempotent — no click if already in the target state. Otherwise one
+click, then a wait until the element reads checked (unchecked) within
+the action timeout (`options.timeout`, else the config default). A
+controlled switch the app flips a beat after the click — once the server
+confirms — passes; one that never flips fails, naming the state it
+wanted and the last one it saw. Works on native checkboxes and radios
+and on ARIA `checkbox` / `radio` / `switch` widgets. A `<label>` — or
+anything inside one — stands for the control it names (`for=` or a
+wrapped input). Any other element is refused — use `click` for it.
 
 ```js
 check(getByRole('checkbox', {name: 'Subscribe'}))
+uncheck(getByRole('switch', {name: 'Notifications'}), {timeout: 5000})
 ```
 
 ### `hover(loc, options?)`
@@ -844,10 +869,36 @@ assertCount(getByRole('listitem').filter({hasNotText: 'Archived'}), 3)
 
 Empty string when the element has no text node (does not throw).
 
+### `texts(loc)` → `string[]`
+
+`textContent` of every element the locator matches, in page order; `[]`
+when nothing matches. One read, no wait — the list to branch on.
+`assertTexts` is the waiting check of the same list.
+
+```js
+names = texts(locator('#agents li'));      // ["Claude Code", "Codex"]
+if (names.length > 0) {
+  log('first agent:', names[0]);
+}
+```
+
 ### `inputValue(loc)` → `string`
 
 ### `isVisible(loc)` → `boolean`
 
+### `isChecked(loc)` → `boolean`
+
+Checked state of a checkbox, radio or switch — native or ARIA role
+(`aria-checked`); a `<label>` reads as the control it names. Any other
+element fails the step instead of answering
+`false`: "unchecked" and "has no checked state" are different answers.
+
+```js
+if (isChecked(getByRole('switch', {name: 'Notifications'}))) {
+  uncheck(getByRole('switch', {name: 'Notifications'}));
+}
+```
+
 ### `isDisabled(loc)` → `boolean` / `isEnabled(loc)` → `boolean`
 
 Disabled = native `:disabled` (covers `<fieldset disabled>` inheritance)
@@ -1746,12 +1797,21 @@ step("Send button uses the app's own label", () => {
   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`
+### `env(name, fallback?)` → `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:
+`unotest/.env` — but returns `fallback` for a name that is not set
+instead of failing the step, and `null` when no fallback is given.
+
+The fallback is the one-line default — the DSL has no `??`, and `||`
+answers `true` / `false`, not a value:
+
+```js
+api = env('API_URL', 'http://localhost:3000');
+```
+
+Without a fallback, use the `null` to decide:
 
 ```js
 if (env('LIVE_API') == null) {
@@ -1762,8 +1822,8 @@ if (env('LIVE_API') == null) {
 ```
 
 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.
+refused, with a fallback or without: `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`
 
@@ -2325,6 +2385,12 @@ result = evaluate(
 Backticks are **raw** — `${…}` interpolation is rejected at parse time
 (see `vendor/dsl/EXTENSIONS.md`).
 
+A page whose main thread is busy — a script loop, a long task — cannot
+start the script. `evaluate` then fails the step after the action timeout
+(the config's `defaultTimeoutMs`) with `the page gave no answer` instead
+of waiting forever. Once the script has started, it runs as long as it
+needs: an `async` body that awaits a slow promise is not cut off.
+
 `evaluateOnLocator(loc, js, ...args)` — the same hatch on one element.
 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
@@ -2499,7 +2565,12 @@ step.soft("Question", {tag: q.id}, () => {
 - 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.
+  failure `run_test` returns. Without `--notes` a green step prints
+  nothing extra.
+- `e2e --notes` / `collection --notes` print every note of every test
+  under its line, a passing test's too, as
+  `note label: value — step "<step>"`. A failed test then lists them in
+  place of the failing step's own, so each note prints once.
 
 ---
 
@@ -2568,6 +2639,14 @@ The DSL is JavaScript-shaped but parsed by a small AST engine
   return **strings** — for comparing against a number use `==`
   (`getAttribute(loc, "data-count") === 5` is always false; write
   `== 5` or compare with a string).
+- **Ternary** — `cond ? a : b`, as in JS: the lowest precedence,
+  nested to the right (`n == 0 ? 'none' : n == 1 ? 'one' : 'many'`),
+  and allowed wherever a value goes (an argument, an object field, a
+  `return`). Only the branch the condition picks runs, so
+  `x == null ? '' : x.name` is a safe null guard. The condition is read
+  as `if` reads it: `0`, `""`, `null` and `false` pick `b`. Where a slot
+  expects a kind (a locator, a number), both branches must give it.
+  `?.` and `??` are not in the DSL — use the ternary or `if` / `else`.
 
 Not supported (and intentionally so): `while` / `do…while` /
 `continue` (bound loops keep every scenario terminating), `++`/`--`,
@@ -2581,8 +2660,9 @@ 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`
+n = count(rows); return n > 3; })`. A lambda goes only into `filter`,
+`map`, `find` and `some` on an array (`a.map(x => x.id)`); anywhere
+else, and `+=`, `for…of`, `o.a = 2` and the like, are refused by `lint`
 with what to write instead.
 
 See `vendor/dsl/EXTENSIONS.md` for the

package/package.json

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

package/types/unotest-dsl.d.ts

@@ -36,15 +36,15 @@ interface Locator {
    */
   randomNth(): Locator;
   /**
-   * locator(css)
+   * locator(css, { hasText?, hasNotText?, has?, hasNot? }?)
    *
-   * Match by raw CSS selector. Last resort — the linter warns on deep/brittle CSS.
+   * Match by raw CSS selector. Last resort — the linter warns on deep/brittle CSS. Options narrow the matches exactly as filter() does.
    */
-  locator(selector: string): Locator;
+  locator(selector: string, options?: any): Locator;
   /**
-   * getByRole(role, { name?, exact? })
+   * getByRole(role, { name?, exact?, checked?, disabled?, expanded?, includeHidden?, level?, pressed?, selected? })
    *
-   * Match by ARIA role + accessible name. `name` accepts a string or `/regex/`.
+   * Match by ARIA role + accessible name. `name` accepts a string or `/regex/`; the state options narrow by ARIA state (`{disabled: false}` skips a disabled button). Any other key is refused.
    */
   getByRole(role: string, options?: any): Locator;
   /**
@@ -108,14 +108,14 @@ declare function doubleClick(locator: Locator, options?: any): void;
 /**
  * check(locator, { force?, timeout? })
  *
- * Check a checkbox/radio.
+ * Check a checkbox/radio/switch: click, then wait until it reads checked (a controlled widget may flip a beat later). Already checked → no click.
  */
 declare function check(locator: Locator, options?: any): void;
 
 /**
  * uncheck(locator, { force?, timeout? })
  *
- * Uncheck a checkbox.
+ * Uncheck a checkbox/switch: click, then wait until it reads unchecked. Already unchecked → no click.
  */
 declare function uncheck(locator: Locator, options?: any): void;
 
@@ -504,6 +504,13 @@ declare function count(locator: Locator): number;
  */
 declare function textContent(locator: Locator): string;
 
+/**
+ * texts(locator) → string[]
+ *
+ * textContent of every match, in DOM order; [] when nothing matches. No wait — the list to branch on; assertTexts is the waiting check.
+ */
+declare function texts(locator: Locator): any;
+
 /**
  * inputValue(locator) → string
  *
@@ -518,6 +525,13 @@ declare function inputValue(locator: Locator): string;
  */
 declare function isVisible(locator: Locator): boolean;
 
+/**
+ * isChecked(locator) → boolean
+ *
+ * Checked state of a checkbox/radio/switch (native or ARIA role). Fails on any other element instead of answering false.
+ */
+declare function isChecked(locator: Locator): boolean;
+
 /**
  * isDisabled(locator) → boolean
  *
@@ -680,11 +694,11 @@ declare function round(n: number, digits?: number): number;
 declare function formatNumber(n: number, options?: any): string;
 
 /**
- * env(name) → string | null
+ * env(name, fallback?) → string | fallback | 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.
+ * An environment value the test can do without: the ambient environment, unotest/.env or .secrets, as a bare UPPER_SNAKE name reads it — but the fallback (null without one) when unset instead of failing. A default in one line: env('API_URL', 'http://localhost:3000'). For deciding on it: if (env('LIVE_API') == null) { … }. A secret is refused, fallback or not; write its bare name where the value is typed.
  */
-declare function env(name: string): any;
+declare function env(name: string, fallback?: any): any;
 
 /**
  * shell(cmd, ...args, options?) → { stdout, stderr, code }
@@ -792,16 +806,16 @@ declare function apiCall(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "
 declare function upload(path: string, options?: any): any;
 
 /**
- * locator(css)
+ * locator(css, { hasText?, hasNotText?, has?, hasNot? }?)
  *
- * Match by raw CSS selector. Last resort — the linter warns on deep/brittle CSS.
+ * Match by raw CSS selector. Last resort — the linter warns on deep/brittle CSS. Options narrow the matches exactly as filter() does.
  */
-declare function locator(selector: string): Locator;
+declare function locator(selector: string, options?: any): Locator;
 
 /**
- * getByRole(role, { name?, exact? })
+ * getByRole(role, { name?, exact?, checked?, disabled?, expanded?, includeHidden?, level?, pressed?, selected? })
  *
- * Match by ARIA role + accessible name. `name` accepts a string or `/regex/`.
+ * Match by ARIA role + accessible name. `name` accepts a string or `/regex/`; the state options narrow by ARIA state (`{disabled: false}` skips a disabled button). Any other key is refused.
  */
 declare function getByRole(role: string, options?: any): Locator;