@unotest/web 0.49.0 → 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?)`
@@ -446,8 +471,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 +643,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 +667,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,14 +852,53 @@ 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).
 
+### `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)
@@ -1719,15 +1794,24 @@ 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`
+### `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) {
@@ -1738,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`
 
@@ -2057,6 +2141,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
@@ -2278,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
@@ -2452,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.
 
 ---
 
@@ -2466,7 +2584,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 +2618,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,20 +2632,39 @@ 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
   `== 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), `++`/`--`,
-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 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
 exact grammar deltas from the upstream parser.
 
@@ -2549,7 +2696,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 +2704,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 +2714,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 +2758,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 +2779,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 +2971,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 +3007,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.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.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.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/grounder": "^0.49.0",
-    "@unotest/judge": "^0.49.0"
+    "@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;
 
@@ -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? })
@@ -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
  *
@@ -546,6 +560,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
  *
@@ -673,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 }
@@ -785,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;