@unotest/web 0.54.0 → 0.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/.claude/skills/write-e2e-test/SKILL.md +30 -7
  2. package/.claude/skills/write-e2e-test-ground/SKILL.md +6 -5
  3. package/CHANGELOG.md +160 -3
  4. package/README.md +24 -6
  5. package/dist/config/schema.d.ts +25 -19
  6. package/dist/config/schema.js +1 -1
  7. package/dist/driver/index.d.ts +8 -2
  8. package/dist/driver/index.js +1 -1
  9. package/dist/dsl/index.d.ts +29 -82
  10. package/dist/dsl/index.js +1 -1
  11. package/dist/dsl/v8/scenario-worker.js +1 -1
  12. package/dist/dsl/web-dsl-language-service.d.ts +30 -3
  13. package/dist/dsl/web-dsl-language-service.js +1 -1
  14. package/dist/inspection/page-inject.d.ts +31 -7
  15. package/dist/inspection/page-inject.js +80 -19
  16. package/dist/{interfaces-BU-PQbt4.d.ts → interfaces-BiGd3BdD.d.ts} +29 -4
  17. package/dist/{linter-BpaIstU3.d.ts → linter-DIAb0JOB.d.ts} +8 -0
  18. package/dist/mcp/server.js +1 -1
  19. package/dist/runner/cli.d.ts +1 -1
  20. package/dist/runner/cli.js +1 -1
  21. package/dist/runner/init/chrome-probe.js +1 -1
  22. package/dist/runner/init.js +1 -1
  23. package/dist/runner/install-chromium.js +1 -1
  24. package/dist/runner/prepare-fix.js +1 -1
  25. package/dist/runner/scaffold-workspace.js +1 -1
  26. package/dist/runner/serve-fixture.js +1 -1
  27. package/dist/runner/web-runner-adapter.js +1 -1
  28. package/dist/scenario-variables-B-ULUTHt.d.ts +88 -0
  29. package/examples/idioms/README.md +16 -0
  30. package/examples/idioms/animations-list.js +24 -0
  31. package/examples/idioms/api-call-timeout.js +14 -0
  32. package/examples/idioms/background-tab.js +24 -0
  33. package/examples/idioms/clipboard-paste.js +25 -0
  34. package/examples/idioms/computed-style.js +21 -0
  35. package/examples/idioms/image-size.js +20 -0
  36. package/examples/idioms/never-appears.js +20 -0
  37. package/examples/idioms/never-condition.js +24 -0
  38. package/examples/idioms/page-code-function.js +18 -0
  39. package/examples/idioms/select-by-label.js +22 -0
  40. package/examples/idioms/wait-enabled.js +21 -0
  41. package/examples/idioms/wait-for-animations.js +16 -0
  42. package/examples/idioms/wait-until-value.js +32 -0
  43. package/guides/agent-integration.md +43 -5
  44. package/guides/dsl-reference.md +589 -34
  45. package/llms.txt +26 -6
  46. package/package.json +9 -8
  47. package/types/unotest-dsl.d.ts +36 -22
  48. package/types/unotest-lib.d.ts +5 -3
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  status: stable
3
- last_updated: 2026-10-13
3
+ last_updated: 2026-10-25
4
4
  ---
5
5
 
6
6
  # DSL Reference
@@ -125,18 +125,17 @@ it consists of:
125
125
  CHECKING stays off (`checkJs: false`) on purpose: diagnostics come from
126
126
  the DSL validator (`npx @unotest/web lint`), the editor only gains
127
127
  completion, hover docs, signature help and locator-chain resolution.
128
- It sets `noLib: true`: the editor's standard library is the scenario
129
- library alone, so it completes `Math.round` and `s.trim()` but not
130
- `Date`, `setTimeout` or `document` — what lint would refuse. A
131
- jsconfig an earlier `init` wrote reads the full JavaScript library;
132
- `lint` and runs say so in one line, and `npx @unotest/web types`
133
- brings it up to date. One you edited by hand is left as it is, with a
134
- line that says what to change.
135
- - `node_modules/@unotest/web/types/unotest-lib.d.ts` — the scenario
136
- library (`Math`, `JSON`, `Object`, `Map`, `Set`, the string, number and
137
- array methods), cut from TypeScript's own declarations to exactly what
138
- a scenario has. `keys()`, `values()` and `entries()` of a Map or a Set
139
- read as iterators, as they run: spread one for array methods.
128
+ Its standard library is JavaScript's own (`"lib": ["es2023", "dom"]`),
129
+ the one lint's type layer checks against: a scenario runs as plain
130
+ JavaScript, so `Date`, classes and `Map.prototype.keys` complete, and
131
+ the DOM is there for the page code handed to `evaluate`. A jsconfig an
132
+ earlier `init` wrote (`noLib` with the cut-down `unotest-lib.d.ts`)
133
+ is outdated; `lint` and runs say so in one line, and
134
+ `npx @unotest/web types` brings it up to date. One you edited by hand
135
+ is left as it is, with a line that says what to change.
136
+ - `node_modules/@unotest/web/types/unotest-lib.d.ts` — deprecated, no
137
+ longer updated: kept for one release so an old jsconfig that names it
138
+ keeps its globals until `types` rewrites it.
140
139
  - `node_modules/@unotest/web/types/unotest-dsl.d.ts` — ambient
141
140
  declarations for every DSL function, generated from the same contracts
142
141
  the validator uses and shipped with the package, so it always matches
@@ -639,7 +638,10 @@ assertTrue(probe.code == 0, 'app.log should contain "ready"');
639
638
  Deep equality, the way JSON sees the two values: key order does not
640
639
  count, and a missing key differs from a key set to `null`. The failure
641
640
  names the first path that differs and both values, then a line diff of
642
- the two sides, every line of them — nothing is folded away:
641
+ the two sides, every line of them — nothing is folded away. A value
642
+ nested deeper than 1000 levels is refused by name (the test is
643
+ errored: `assertEqual: value nested deeper than 1000 levels`), as by
644
+ every DSL function:
643
645
 
644
646
  ```js
645
647
  const body = parseJson(getAttribute(locator('#state'), 'data-json'));
@@ -751,7 +753,9 @@ Semantics:
751
753
  CLI session), `vertex` uses ADC via
752
754
  `GOOGLE_CLOUD_PROJECT`/`GOOGLE_CLOUD_LOCATION`, the rest take the
753
755
  vendor-standard key vars (`GEMINI_API_KEY`, `OPENAI_API_KEY`,
754
- `ANTHROPIC_API_KEY`) — see the `@unotest/judge` README. Unconfigured
756
+ `ANTHROPIC_API_KEY`) — see the `@unotest/judge` README. In `local`
757
+ mode the key goes in `unotest/.secrets` (or `.secrets.<env>`); an
758
+ exported variable wins over the file. Unconfigured
755
759
  (`off`) → the step fails with the setup message; a judge assert is
756
760
  never silently skipped.
757
761
  - The judged text is the element's **rendered** text (`innerText`): line
@@ -1166,12 +1170,35 @@ waitForAnimations(getByRole('dialog'));
1166
1170
  assertScreenshot(getByRole('dialog'), 'edit-dialog');
1167
1171
  ```
1168
1172
 
1169
- ### `pause(ms)`
1173
+ ### `pause(ms, reason?)`
1170
1174
 
1171
- Hard sleep. **Avoid** — the linter flags it (`lint:pause-explicit`). Use
1172
- `waitFor` / `waitForText` / assertion polling instead. A justified
1173
- occurrence is silenced per-line with `// lint-ok: <reason>` (the reason
1174
- is required — a bare `// lint-ok` suppresses nothing):
1175
+ A fixed delay. To wait for the page, use `waitFor` / `waitForText` /
1176
+ assertion polling instead: a bare `pause(ms)` is reported by
1177
+ `lint:pause-explicit`.
1178
+
1179
+ #### Waiting a fixed time
1180
+
1181
+ When the wait IS the test — a quiz that opens 20 minutes after the start,
1182
+ a rate limit that lifts after a minute — say why in the call:
1183
+
1184
+ ```js
1185
+ setTestTimeout(30 * 60 * 1000); // the budget has room for the wait
1186
+ step("Wait until the hunt opens", () => {
1187
+ pause(21 * 60 * 1000, 'the hunt opens 21 minutes after the start');
1188
+ });
1189
+ ```
1190
+
1191
+ - The reason is printed on the step (`pause 1260000 ms: the hunt opens …`)
1192
+ and `lint:pause-explicit` leaves the call be. It must be text that is
1193
+ not empty.
1194
+ - A wait longer than the test's budget ends on the budget: raise it with
1195
+ [`setTestTimeout(ms)`](#settesttimeoutms) in that test.
1196
+ - Not `shell('sleep 1260')`: that waits the same, says nothing on the
1197
+ step, and is a process the run has to keep.
1198
+
1199
+ A short pause you cannot replace (a widget with no signal to wait for)
1200
+ can also be silenced on its line with `// lint-ok: <reason>` — the reason
1201
+ is required, a bare `// lint-ok` suppresses nothing:
1175
1202
 
1176
1203
  ```js
1177
1204
  pause(500); // lint-ok: third-party widget has no completion signal to hook into
@@ -1755,7 +1782,7 @@ setLocalStorage('feature-flag', 'enabled');
1755
1782
  const v = getLocalStorage('feature-flag');
1756
1783
  ```
1757
1784
 
1758
- ### `setCookie(name, value, options?)` / `getCookie(name)` → `string`
1785
+ ### `setCookie(name, value, options?)`
1759
1786
 
1760
1787
  **Options:** `domain?`, `path?`, `expires?`, `httpOnly?`, `secure?`,
1761
1788
  `sameSite?`.
@@ -1764,6 +1791,44 @@ const v = getLocalStorage('feature-flag');
1764
1791
  setCookie('session', 'abc123', {path: '/', sameSite: 'Lax'});
1765
1792
  ```
1766
1793
 
1794
+ `domain` defaults to the current page's host, `path` to `/`. The cookie
1795
+ is read back after the write: one the browser does not keep fails the
1796
+ step, without naming the value — `sameSite: 'None'` needs `secure: true`:
1797
+
1798
+ ```
1799
+ setCookie('cross'): the browser dropped the cookie — sameSite: 'None' requires secure: true
1800
+ ```
1801
+
1802
+ A cookie set with `expires` in the past is a deletion: the browser drops
1803
+ it, and the step passes.
1804
+
1805
+ ```js
1806
+ setCookie('session', '', {expires: 1}); // delete it
1807
+ ```
1808
+
1809
+ ### `getCookie(name, options?)` → `string` / `hasCookie(name, options?)` → `boolean`
1810
+
1811
+ `getCookie` reads a cookie's value, `''` when there is none.
1812
+ `hasCookie` says whether it is there at all — the probe that tells a
1813
+ missing cookie from an empty value, as `hasAttribute` does for
1814
+ `getAttribute`.
1815
+
1816
+ Two views of the cookies:
1817
+
1818
+ - **default — the jar** of the browser context: every domain and path,
1819
+ `httpOnly` too. What the server is sent.
1820
+ - **`{page: true}`** — what the page's script is given: `document.cookie`
1821
+ of the page, or of the frame entered with `enterFrame`. No `httpOnly`
1822
+ cookie, none for another path or domain; the browser decides, as it
1823
+ does for the app.
1824
+
1825
+ ```js
1826
+ setCookie('session', 'abc', {httpOnly: true});
1827
+ assertTrue(hasCookie('session')); // the jar has it
1828
+ assertTrue(!hasCookie('session', {page: true})); // the page's script does not
1829
+ assertEqual(getCookie('theme', {page: true}), 'dark');
1830
+ ```
1831
+
1767
1832
  ---
1768
1833
 
1769
1834
  ## Edge actions
@@ -1866,12 +1931,28 @@ Semantics:
1866
1931
  - **Timeout**: each call has a wall-clock budget —
1867
1932
  `sandbox.shellTimeoutMs` (default 120 000 ms) or per-call
1868
1933
  `{timeoutMs}`. On expiry the child is killed and the step fails.
1934
+ A per-call `{timeoutMs}` longer than what is left of the test's budget
1935
+ is said before the command starts — a warning on the step with both
1936
+ numbers and the `setTestTimeout(…)` that fits it. The command still
1937
+ runs; the budget ends the test first if it takes that long. A literal
1938
+ that long is reported by `lint:wait-exceeds-test-budget` before the run.
1869
1939
  - Output capture is limited to 10 MiB per stream; exceeding it fails the
1870
1940
  step (write bulk output to a file instead).
1871
1941
  - **Env**: the child inherits the runner's `process.env` (which includes
1872
1942
  `unotest/.env` layers). Secrets from `.secrets*` are **not** inherited;
1873
1943
  export them explicitly via the `sandbox.exportSecrets` allowlist
1874
- (values stay masked in logs).
1944
+ (values stay masked in logs). The runner's own credentials
1945
+ (`UNOTEST_CLOUD_TOKEN`, the judge's and the grounder's keys) are
1946
+ dropped from the child's env as well.
1947
+ - **Rights**: the child runs with the rights of the account that runs
1948
+ the suite. Exported keys and key files are visible to it. Dropping
1949
+ names from its env keeps them out of an accidental `printenv` and out
1950
+ of logs; it is not a wall — the same command can read your files
1951
+ (`unotest/.secrets`, the cloud sign-in in `~/.config/unotest/`) and the
1952
+ environment your shell exported (for example through the parent
1953
+ process). Do not run a suite you do not trust from a shell that
1954
+ exports a key; on a box a run's container holds none of the box's
1955
+ tokens.
1875
1956
 
1876
1957
  ```js
1877
1958
  const out = shell('pnpm', 'db:create-user', 'alice'); // non-zero exit → step fails
@@ -2099,6 +2180,36 @@ A secret — a name from `unotest/.secrets`, or one a box injects — is
2099
2180
  refused, with a fallback or without: `env()` returns a plain string, and
2100
2181
  a credential must stay masked. Write the secret's bare name where its value is typed instead.
2101
2182
 
2183
+ **An empty value is not set.** `ADMIN_BASE_URL=` in the layer files the
2184
+ run reads means the name has no value on this environment. `env()`
2185
+ returns the fallback, or `null`. A bare `ADMIN_BASE_URL` fails the test
2186
+ with the name and the environment:
2187
+
2188
+ ```
2189
+ `ADMIN_BASE_URL` is empty on this environment (environment "dev" …) — an empty value means "not set here". …
2190
+ ```
2191
+
2192
+ It never reads `""`: a `goto` to an empty URL would land on
2193
+ `APP_BASE_URL` and pass. To keep such a test, skip it where the name is
2194
+ missing — this works on every run, with `--env` or without:
2195
+
2196
+ ```js
2197
+ function test_admin_panel() {
2198
+ skip('ADMIN_BASE_URL is not set here', env('ADMIN_BASE_URL', null) == null);
2199
+ step('Open the admin panel', () => {
2200
+ goto(ADMIN_BASE_URL);
2201
+ });
2202
+ }
2203
+ ```
2204
+
2205
+ `// @env local, staging` above the test (see
2206
+ environments) is enough only if you always run with
2207
+ `--env`: a run without `--env` ignores the marker, reads the base
2208
+ `unotest/.env` and fails the same way. A secret fails the same way too,
2209
+ and the message never carries its value; `env()` refuses a secret, so
2210
+ the `skip` line does not apply to it — give the secret a value, or keep
2211
+ the test to `--env` runs with `// @env`.
2212
+
2102
2213
  ### `readFile(path, options?)` → `string`
2103
2214
 
2104
2215
  Read a whole file once and return its content: the text by default, or
@@ -2556,9 +2667,73 @@ assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
2556
2667
  the mock keeps what it answered, and each request is returned once.
2557
2668
  On any other mask only requests from the call on count — to catch one
2558
2669
  the previous step sent, mock the mask with `{continue: true}` first.
2670
+ - `{method}` — `'GET'`, `'POST'`, … in any case: only a request of that
2671
+ method is taken. One of another method is not taken and stays for the
2672
+ next wait, so a GET and a POST to one path need no order of masks:
2673
+
2674
+ ```js
2675
+ const saved = waitForRequest('**/api/item', { method: 'POST' });
2676
+ const read = waitForRequest('**/api/item', { method: 'GET' });
2677
+ ```
2678
+
2679
+ On a mask that is not mocked a request of another method that comes
2680
+ while the call waits is not kept: mock the mask to keep it.
2559
2681
  - `{timeoutMs}` — default 20 000.
2560
2682
  - A `ws://` or `wss://` mask is refused: a WebSocket is no request.
2561
2683
 
2684
+ ### `waitForResponse(glob, options?)` → `{url, method, status, ok, headers, json, text}`
2685
+
2686
+ Waits for the answer to a request matching `glob` and returns it. Use it
2687
+ when what the test checks comes only with the answer — an element drawn
2688
+ from it, or one that must not be.
2689
+
2690
+ ```js
2691
+ click(getByRole('button', { name: 'Load' }));
2692
+ const res = waitForResponse('**/api/items', { status: 200 });
2693
+ assertEqual(res.json.items.length, 0);
2694
+ assertHidden(getByTestId('item'));
2695
+ ```
2696
+
2697
+ - **Which request.** Those sent from the start of the last call that
2698
+ acted on the page: `click`, `fill`, `press`, `check`, `hover`,
2699
+ `selectOption`, `goto`, `reload`, `evaluate`, `clockTick` and the
2700
+ like. A `log`, a `note`, an assertion or another wait in between moves
2701
+ nothing. The same GET the page made as it loaded is not taken after a
2702
+ later click.
2703
+ - **An answer that came before the call is found**: the page's requests
2704
+ are recorded all along, there is no race with a fast server.
2705
+ - Of those, the one sent first that no earlier `waitForResponse`
2706
+ returned: two waits on one mask take two answers.
2707
+ - `{status}` — only that status; others are passed over and named in
2708
+ the timeout. `{method}` — only that method, any case.
2709
+ - A request that failed (refused, aborted by `mockRoute`) is no answer.
2710
+ A `mockRoute` answer is one, with `mocked: true`; `{continue: true}`
2711
+ gives the network's.
2712
+ - `{since}` — epoch ms from `nowMs()`: requests sent from then on, in
2713
+ place of the last page action. Needed when another action came
2714
+ between the one that sent the request and the wait:
2715
+
2716
+ ```js
2717
+ const before = nowMs();
2718
+ click(getByRole('button', { name: 'Load' }));
2719
+ hover(getByRole('menu'));
2720
+ waitForResponse('**/api/items', { since: before });
2721
+ ```
2722
+
2723
+ Without `{since}` that wait looks from the `hover` on and times out;
2724
+ the timeout says so.
2725
+ - `headers` — the response's, names in lower case. `json` — the body
2726
+ read as JSON, `null` when it is not JSON, was not read or was cut.
2727
+ `text` — the body of a text or JSON content type, `null` otherwise.
2728
+ Bodies are read for `fetch` and `xhr`, at most 64 KB; a longer one has
2729
+ `truncated: true`. Documents and images have status and headers only.
2730
+ - `{timeoutMs}` — default 20 000. A timeout fails the test and quotes the
2731
+ answers on the mask it passed over and why.
2732
+ - The answer is in, not yet drawn: the page renders after it. To show an
2733
+ element never appears, follow with
2734
+ `assertNeverAppears(locator, { withinMs })`.
2735
+ - A `ws://` or `wss://` mask is refused: use `waitForWebSocket`.
2736
+
2562
2737
  ### `waitForWebSocket(glob, options?)` → `{url}`
2563
2738
 
2564
2739
  Waits until the active page has opened a WebSocket whose URL matches
@@ -2597,6 +2772,9 @@ assertNoRequest('**/*');
2597
2772
  A mask without a recording abort is an error, not a pass: nothing
2598
2773
  watched it.
2599
2774
  - `{since}` — epoch ms, as `nowMs()` gives: only requests from then on.
2775
+ - `{method}` — `'POST'` and the like, in any case: only stopped requests
2776
+ of that method count (`assertNoRequest('**/api/**', { method: 'POST' })`
2777
+ lets the page read but not write).
2600
2778
 
2601
2779
  ---
2602
2780
 
@@ -3403,7 +3581,18 @@ screenshot('landing', {fullPage: true}); // full scroll height
3403
3581
  - `name` is slugified to `[a-z0-9._-]` (`'Bot Reply!'` → `bot-reply`,
3404
3582
  `'Q 17/a'` → `q-17-a`); omitted → `shot`. Files are numbered in
3405
3583
  capture order.
3406
- - **Options:** `fullPage?` (default `false` — viewport only).
3584
+ - **Options:** `fullPage?` (default `false` — viewport only);
3585
+ `timeoutMs?` — how long the capture may take, default the context's
3586
+ `defaultTimeoutMs`. A busy page (a chat widget still loading fonts)
3587
+ may need more: `screenshot('bot-reply', {timeoutMs: 15000})`.
3588
+ - **A capture that runs out of time does not fail the test.**
3589
+ `screenshot()` is evidence: the call returns `null`, the step gets a
3590
+ warning line (`screenshot "bot-reply" not taken (…)`), and the reason is
3591
+ filed in the same sequence as the pictures,
3592
+ `screenshot/<NNN>-bot-reply-screenshot-error.txt`. Any other failure
3593
+ of the capture (the page has gone) fails the step as before.
3594
+ [`assertScreenshot`](#assertscreenshotname-options--assertscreenshotloc-name-options)
3595
+ is a check and still fails on a timeout.
3407
3596
  - Before capturing, the call waits for the network to go quiet and for a
3408
3597
  painted frame (up to 2s). Without it a `screenshot()` right after
3409
3598
  `goto()` would freeze the blank pre-render frame — `goto` resolves on
@@ -3454,12 +3643,12 @@ assertTrue(consoleEntries({ level: ['warn', 'error'], since: before }).length ==
3454
3643
  `console.json` holds the lines of every browser context, each with its
3455
3644
  `contextIndex`, the last 500 by time.
3456
3645
 
3457
- ### `networkEntries(options?)` → `[{ url, method, status, ok, requestJson, responseJson, responseText, at }]`
3646
+ ### `networkEntries(options?)` → `[{ url, method, status, ok, headers, requestJson, responseJson, responseText, at }]`
3458
3647
 
3459
3648
  What the active page requested and was answered, oldest first. Like the
3460
3649
  console, it is recorded from the moment the page opened, so the usual
3461
3650
  order works: act, then ask. A response is entered when it finishes, so
3462
- wait for it.
3651
+ wait for it — `waitForResponse` waits for one.
3463
3652
 
3464
3653
  ```js
3465
3654
  click(getByRole('button', { name: 'Verify' }));
@@ -3472,6 +3661,8 @@ assertEqual(answer.responseJson.kind, 'mobile');
3472
3661
  - `status` / `ok` — the response; a request that failed before any
3473
3662
  response (refused, aborted) has `status` 0, `ok` false and
3474
3663
  `failureText`.
3664
+ - `headers` — the response's, names in lower case; empty for a request
3665
+ that failed.
3475
3666
  - `mocked` — `true` when a `mockRoute` answered or aborted it.
3476
3667
  - Bodies are read for `fetch` and `xhr` requests with a text or JSON
3477
3668
  content type, at most 64 KB each; a longer one is cut, `truncated` is
@@ -3531,7 +3722,10 @@ Writes one line to the runner's output (the terminal, the live System
3531
3722
  pane in the viewer) **and** to the run journal (`steps.jsonl`, as a
3532
3723
  `log` event under the current step), so a finished run still shows it
3533
3724
  under the step that wrote it and in the System pane. Non-string args
3534
- are `JSON.stringify`'d.
3725
+ are `JSON.stringify`'d. An arg nested deeper than 1000 levels is
3726
+ refused by name, as by every DSL function: `log: value nested deeper
3727
+ than 1000 levels`, and the test is errored. The Vars view shows such a
3728
+ value cut at that depth, marked `…`.
3535
3729
 
3536
3730
  ```js
3537
3731
  log('user id:', userId);
@@ -3640,7 +3834,7 @@ per option; an older spelling it still takes is named after the line.
3640
3834
  - `waitForText(text: string | RegExp, options?: { state?: string; exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3641
3835
  - `waitForCount(locator: Locator, count: number, options?: { exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3642
3836
  - `waitForAnimations(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3643
- - `pause(ms: number): void`
3837
+ - `pause(ms: number, reason?: string): void`
3644
3838
  - `waitForDownload(options?: { timeoutMs?: number; name?: string | RegExp }): any`
3645
3839
  - `clockFreeze(iso: string): void`
3646
3840
  - `clockTick(ms: number): void`
@@ -3658,7 +3852,7 @@ per option; an older spelling it still takes is named after the line.
3658
3852
  - `assertCount(locator: Locator, count: number, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3659
3853
  - `assertUrl(pattern: string | RegExp, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3660
3854
  - `assertJudge(locator: Locator, rubric: string): void`
3661
- - `assertScreenshot(nameOrLocator: any, nameOrOptions?: any, options?: { maxDiffRatio?: number; threshold?: number; mask?: unknown[]; ignore?: unknown[]; fullPage?: boolean }): void`
3855
+ - `assertScreenshot(nameOrLocator: any, nameOrOptions?: string | { maxDiffRatio?: number; threshold?: number; mask?: unknown[]; ignore?: unknown[]; fullPage?: boolean }, options?: { maxDiffRatio?: number; threshold?: number; mask?: unknown[]; ignore?: unknown[]; fullPage?: boolean }): void`
3662
3856
  - `assertEqual(actual: any, expected: any): void`
3663
3857
  - `assertTrue(condition: boolean, message?: string): void`
3664
3858
  - `assertSchema(value: any, schema: any): void`
@@ -3718,7 +3912,8 @@ per option; an older spelling it still takes is named after the line.
3718
3912
  - `setLocalStorage(key: string, value: string): void`
3719
3913
  - `getLocalStorage(key: string): string`
3720
3914
  - `setCookie(name: string, value: string, options?: { domain?: string; path?: string; expires?: number; httpOnly?: boolean; secure?: boolean; sameSite?: string }): void`
3721
- - `getCookie(name: string): string`
3915
+ - `getCookie(name: string, options?: { page?: any }): string`
3916
+ - `hasCookie(name: string, options?: { page?: any }): boolean`
3722
3917
 
3723
3918
  **Tabs, frames, contexts, extensions**
3724
3919
 
@@ -3746,8 +3941,8 @@ per option; an older spelling it still takes is named after the line.
3746
3941
  **Data, files, network, processes**
3747
3942
 
3748
3943
  - `shell(cmd: string, ...args: unknown[]): any`
3749
- - `waitForFile(path: string, pattern?: any, options?: { timeoutMs?: number }): string`
3750
- - `assertNoFile(path: string, pattern?: any, options?: { withinMs?: number }): void`
3944
+ - `waitForFile(path: string, pattern?: string | RegExp | { timeoutMs?: number }, options?: { timeoutMs?: number }): string`
3945
+ - `assertNoFile(path: string, pattern?: string | RegExp | { withinMs?: number }, options?: { withinMs?: number }): void`
3751
3946
  - `waitForJsonLine(path: string, filter: any, options?: { timeoutMs?: number }): any`
3752
3947
  - `assertNoJsonLine(path: string, filter: any, options?: { withinMs?: number }): void`
3753
3948
  - `readJsonLine(path: string, filter: any): any`
@@ -3762,10 +3957,11 @@ per option; an older spelling it still takes is named after the line.
3762
3957
  - `upload(path: string, options?: { field?: string; fields?: any }): any`
3763
3958
  - `mockRoute(glob: string, response: any): void`
3764
3959
  - `unmockRoute(glob?: string): void`
3765
- - `waitForRequest(glob: string, options?: { timeoutMs?: number }): any`
3960
+ - `waitForRequest(glob: string, options?: { timeoutMs?: number; method?: string }): any`
3961
+ - `waitForResponse(glob: string, options?: { status?: number; method?: string; since?: number; timeoutMs?: number }): any`
3766
3962
  - `waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any`
3767
3963
  - `networkEntries(options?: { since?: number; glob?: any }): any`
3768
- - `assertNoRequest(glob: string, options?: { since?: number }): void`
3964
+ - `assertNoRequest(glob: string, options?: { since?: number; method?: string }): void`
3769
3965
  - `openTerminal(app?: string, options?: { host?: any; leaveOpen?: boolean; env?: any; cwd?: string; shell?: string; cols?: number; rows?: number; term?: string; locale?: string; cleanProfile?: boolean }): number`
3770
3966
  - `setTerminal(index: number): void`
3771
3967
  - `closeTerminal(): void`
@@ -3792,7 +3988,7 @@ per option; an older spelling it still takes is named after the line.
3792
3988
 
3793
3989
  **Diagnostics**
3794
3990
 
3795
- - `screenshot(name?: string, options?: { fullPage?: boolean }): string`
3991
+ - `screenshot(name?: string, options?: { fullPage?: boolean; timeoutMs?: number }): string`
3796
3992
  - `note(label: string, value: any): void`
3797
3993
  - `consoleEntries(options?: { level?: any; since?: number }): any`
3798
3994
  - `pageErrors(options?: { since?: number }): any`
@@ -3804,6 +4000,29 @@ per option; an older spelling it still takes is named after the line.
3804
4000
  - `evaluateOnLocator(locator: Locator, jsBody: any, ...args: unknown[]): any`
3805
4001
  <!-- /generated:signatures -->
3806
4002
 
4003
+ ## Versions
4004
+
4005
+ The release of `@unotest/web` that added each function and keyword. A
4006
+ suite runs the DSL of the release it installs: a function newer than that
4007
+ is unknown to its `lint` and its run — install a newer `@unotest/web` in
4008
+ the suite, or write the scenario without it.
4009
+
4010
+ <!-- generated:versions — pnpm build:dsl-types writes this from the contracts -->
4011
+ - **0.56.0** — `hasCookie`
4012
+ - **0.55.0** — `waitForResponse`
4013
+ - **0.53.0** — `networkEntries`, `terminalClipboardRead`, `terminalClipboardWrite`, `terminalText`, `terminalWaitForExit`
4014
+ - **0.51.0** — `addVirtualAuthenticator`, `animations`, `assertClipboard`, `assertFileHas`, `assertFileLacks`, `assertNever`, `clipboardRead`, `closeTerminal`, `grantPermissions`, `mcpCall`, `mcpStart`, `mcpStop`, `mcpWaitNotification`, `openTerminal`, `removeVirtualAuthenticator`, `setOffline`, `setPageHidden`, `setTerminal`, `terminalAssertText`, `terminalPress`, `terminalResize`, `terminalScreenshot`, `terminalType`, `terminalWaitForText`, `virtualCredentials`, `vmAvailable`, `vmClone`, `vmDelete`, `vmIp`, `vmRun`, `vmStop`, `waitForWebSocket`
4015
+ - **0.49.2** — `isChecked`, `texts`
4016
+ - **0.49.1** — `getImageSize`
4017
+ - **0.47.0** — `computedStyle`, `emulateMedia`, `formatNumber`, `hasAnimation`, `round`, `toNumber`, `waitForAnimations`
4018
+ - **0.46.0** — `assertAttribute`, `assertNoConsoleErrors`, `assertSchema`, `assertTexts`, `consoleEntries`, `env`, `pageErrors`, `setTestTimeout`, `skip`
4019
+ - **0.45.0** — `assertEqual`, `assertNoRequest`, `boundingBox`, `bringToFront`, `closePage`, `evaluateInServiceWorker`, `evaluateOnLocator`, `extensionId`, `mockRoute`, `newPage`, `parseJson`, `readFile`, `readFileInfo`, `readJson`, `textMatches`, `unmockRoute`, `urlParam`, `waitForDownload`, `waitForPage`, `waitForRequest`, `waitForServiceWorker`
4020
+ - **0.44.0** — `assertScreenshot`, `clockFreeze`, `clockRun`, `clockTick`, `newContext`, `setContext`, `setViewport`
4021
+ - **0.31.0** — `note`, `readJsonLine`
4022
+ - **0.22.0** — `assertJudge`
4023
+ - **before 0.22.0** — `apiCall`, `assertCount`, `assertFileCount`, `assertHidden`, `assertNeverAppears`, `assertNoFile`, `assertNoJsonLine`, `assertText`, `assertTrue`, `assertUrl`, `assertValue`, `assertVisible`, `check`, `click`, `clipboardPaste`, `contentFrame`, `count`, `daysFromNow`, `dbExec`, `dbQuery`, `doubleClick`, `dragAndDrop`, `enterFrame`, `evaluate`, `exitFrame`, `fill`, `filter`, `first`, `getAttribute`, `getByAltText`, `getByLabel`, `getByPlaceholder`, `getByRole`, `getByTestId`, `getByText`, `getByTitle`, `getCookie`, `getInnerText`, `getInputValue`, `getLocalStorage`, `getTitle`, `getUrl`, `goBack`, `goForward`, `goto`, `hasAttribute`, `hover`, `inputValue`, `isDisabled`, `isEnabled`, `isVisible`, `json`, `last`, `locator`, `log`, `nowMs`, `nth`, `pause`, `press`, `randomEmail`, `randomFirstName`, `randomLastName`, `randomNth`, `randomText`, `randomWord`, `reload`, `screenshot`, `scrollIntoView`, `selectOption`, `setCookie`, `setLocalStorage`, `setPage`, `shell`, `textContains`, `textContent`, `textJoin`, `today`, `uncheck`, `upload`, `uploadFile`, `waitFor`, `waitForCount`, `waitForFile`, `waitForFileCount`, `waitForJsonLine`, `waitForNavigation`, `waitForText`, `waitForUrl`
4024
+ <!-- /generated:versions -->
4025
+
3807
4026
  ---
3808
4027
 
3809
4028
  ## The language — JavaScript
@@ -4262,3 +4481,339 @@ helpers. A function, parameter or variable of your own named
4262
4481
  linter across `unotest/e2e/**/*.js`. `lint <name>` checks one scenario,
4263
4482
  named as `e2e` takes it (`lint values/string-escapes`); a file or a
4264
4483
  folder works too.
4484
+
4485
+ ---
4486
+
4487
+ ## Linter rules
4488
+
4489
+ `npx @unotest/web lint` reports these, and so does a run before it starts
4490
+ (see Lint before a run).
4491
+ Each rule's severity is set in `unotest.config.*` under `linter.rules`;
4492
+ `// lint-ok: <reason>` on the line silences a warning or an info.
4493
+
4494
+ ### `lint:deep-css`
4495
+
4496
+ CSS selector with `>` or descendant combinators. Brittle to DOM
4497
+ restructure. Prefer role/name/testid.
4498
+
4499
+ ```js
4500
+ locator('div > div.row > .cell:nth-child(3)') // ⚠
4501
+ ```
4502
+
4503
+ ### `lint:xpath`
4504
+
4505
+ XPath selectors. Reasoning is the same as deep-css; XPath is
4506
+ particularly fragile.
4507
+
4508
+ ```js
4509
+ locator('xpath=//div[contains(@class, "row")]/td[3]') // ⚠
4510
+ ```
4511
+
4512
+ ### `lint:obfuscated-class`
4513
+
4514
+ CSS classes that look hashed (`.abc_123`, `.css-1a2b3c`, Tailwind-JIT
4515
+ `.text-[#f00]`). These rename between builds.
4516
+
4517
+ ### `lint:pause-explicit`
4518
+
4519
+ Bare `pause(N)`. A wait the test means takes its reason as the second
4520
+ argument, `pause(N, 'why')`: the reason is printed on the step and the
4521
+ rule leaves it be (see [Waiting a fixed time](#waiting-a-fixed-time)).
4522
+ Silence another justified occurrence with a trailing
4523
+ `// lint-ok: <reason>` on the same line — the reason is required, and the
4524
+ mechanism works for any warning/info rule (legacy helper warnings stop
4525
+ drowning out new ones):
4526
+
4527
+ ```js
4528
+ pause(500); // lint-ok: third-party widget settles its own state with no public signal
4529
+ ```
4530
+
4531
+ ### `lint:function-newer-than-suite`
4532
+
4533
+ **Warning.** A call of a DSL function that this `@unotest/web` knows and
4534
+ the suite's own does not: it was added in a later release than the one
4535
+ installed in `unotest/` (see [Versions](#versions)). The suite's `lint`
4536
+ reports it as an unknown function and its run refuses the call. Upgrade
4537
+ `@unotest/web` in `unotest/` to that release or newer, or write the step
4538
+ without it. Named once per function; off when the installed release
4539
+ cannot be read.
4540
+
4541
+ ### `lint:typed-step-available`
4542
+
4543
+ Info: the scenario does by hand what the language has a typed step for.
4544
+ The message names the function and its section of
4545
+ `node_modules/@unotest/web/guides/dsl-reference.md`:
4546
+
4547
+ | What the scenario does | Typed step |
4548
+ |---|---|
4549
+ | `getComputedStyle(…)` in page code | `computedStyle(locator, property)` |
4550
+ | `naturalWidth` / `naturalHeight` / `complete` in page code | `getImageSize(locator)` |
4551
+ | `pause(N)` followed by `assertHidden(…)` or `assertCount(…, 0)` | `assertNeverAppears(locator, {withinMs})` |
4552
+ | `pause(N)` whose step label or comment speaks of a fade, an animation, a transition or settling | `waitForAnimations(locator)` |
4553
+ | `pause(N)` whose step label or comment speaks of a control being enabled | `waitFor(locator, {state: 'enabled'})` |
4554
+
4555
+ Page code is read when it is a function literal
4556
+ (`evaluateOnLocator(loc, (el) => …)`). The reason of a `pause` is the
4557
+ label of the steps around it and a comment on its line or the line
4558
+ above it. The check after a `pause` may be the first call of the next
4559
+ step.
4560
+
4561
+ `npx @unotest/web upgrade-hints` counts these sites across the whole
4562
+ suite, with page code written as a string (`validator:page-code-string`)
4563
+ as one more row: the count per pattern, the step to write instead, every
4564
+ file and line. The first `e2e` run on a new version prints the counts
4565
+ once.
4566
+
4567
+ ### `lint:disambig-by-index`
4568
+
4569
+ `first()`, `last()`, `nth(N)` on a multi-match without a prior `filter`
4570
+ narrowing. The locator becomes order-dependent.
4571
+
4572
+ ### `lint:evaluate-discouraged`
4573
+
4574
+ `evaluate(js, …)` / `evaluateOnLocator(loc, js, …)` calls. One warning
4575
+ per file, at the first call, with the number of calls. A call under
4576
+ `// lint-ok: <reason>` is left out of the count. Prefer typed getters /
4577
+ actions; reach for `evaluate` only when nothing else fits.
4578
+
4579
+ ### `lint:legacy-layout`
4580
+
4581
+ `unotest.config.*` still sits at the project root (the pre-0.28 layout)
4582
+ where nothing reads it. `lint` does not refuse the way `e2e` /
4583
+ `collection` / `bundle push` do — it only needs the config for rule
4584
+ severities and the helpers dir, so it lints on the defaults and reports
4585
+ the layout once, as a warning that does not fail the run:
4586
+
4587
+ ```
4588
+ unotest.config.mjs:1:1: ⚠ warn [lint:legacy-layout] unotest.config.mjs is at the project root, …
4589
+ ```
4590
+
4591
+ Your `unotest/.env`, `.secrets` and `_helpers/` are read as usual — they
4592
+ never moved. The message carries the migration on one line; the full
4593
+ steps are what `e2e` prints on the same project.
4594
+
4595
+ ### `lint:external-variable-undeclared`
4596
+
4597
+ A bare `UPPER_SNAKE` identifier (`fill(loc, LOGN)`) that no layer file
4598
+ declares. Such a name resolves at run time through `unotest/.env` /
4599
+ `unotest/.secrets` (plus the `.env.<name>` / `.secrets.<name>` overlay of
4600
+ the active environment), and a name that is not there fails only at that
4601
+ statement — after the browser is up and every earlier step has run. The
4602
+ rule reports it before anything starts, with the files it searched:
4603
+
4604
+ ```
4605
+ billing/token.js:4:30: ✗ error [lint:external-variable-undeclared] `BILLING_TOKEN` is not declared (searched: base environment (no UNOTEST_ENV): unotest/.env, unotest/.secrets (no such file); declared names only: unotest/.env.example, unotest/.secrets.example (no such file); other environments (no --env, so they count): none) — fix the name, or declare it in unotest/.secrets.example (`BILLING_TOKEN=`, committed, names only) and set its value in unotest/.secrets.
4606
+ ```
4607
+
4608
+ - **Without `--env`, every env file declares.** `lint` with no
4609
+ environment chosen stands for no particular run, so a name that any
4610
+ `unotest/.env*` or `unotest/.secrets*` file declares counts —
4611
+ `.env.local`, `.env.staging`, `.secrets.ci` included. The error is left
4612
+ for a name no file declares at all.
4613
+ - **With `--env <name>` (or `UNOTEST_ENV`), `lint` reads what that run
4614
+ reads**: the base files, that environment's overlay and the templates. A
4615
+ name declared only in `.env.prod` is an error for `lint --env dev` and
4616
+ fine for `lint --env prod`.
4617
+ - **The shell is not a declaration.** `lint` reads files only, so a
4618
+ value that CI exports (`export CI_TOKEN=…`) still needs the name in
4619
+ `unotest/.env` — `CI_TOKEN=` with no value declares it and the shell's
4620
+ value wins at run time, as it always did.
4621
+ - **`unotest/.env.example` and `.secrets.example` declare as well.** The
4622
+ real files are gitignored, so in a fresh checkout — a CI runner, a
4623
+ colleague who has just cloned — the twins are the only place the project
4624
+ still says which externals it expects, and a name written there counts as
4625
+ declared. Values are never taken from them: a scenario that READS such a
4626
+ variable still fails at that step, with "no value" instead of "no such
4627
+ name". Credentials belong in `.secrets.example`, the rest in
4628
+ `.env.example`, both without values:
4629
+
4630
+ ```
4631
+ # unotest/.secrets.example
4632
+ LOGIN=
4633
+ PASSWORD=
4634
+ ```
4635
+
4636
+ It is the same list a pushed bundle carries, so a box and the linter
4637
+ agree on what the suite declares.
4638
+ - **A template has to be committed to declare anything.** If git ignores
4639
+ `unotest/.env.example` or `.secrets.example`, `lint` warns: the file
4640
+ exists only in your checkout, and a fresh one does not know its names.
4641
+ `init` writes the lines that keep both templates committable
4642
+ (`!unotest/.env.example`, `!unotest/.secrets.example`, each right after
4643
+ the line that ignores its family); a `.gitignore` from an older `init`
4644
+ gets the missing line on the next `init`.
4645
+ - An **error**, so `// lint-ok:` does not silence it (errors are never
4646
+ baselined). If you must, downgrade it in `unotest.config.*`:
4647
+ `linter: { rules: { 'lint:external-variable-undeclared': 'warn' } }`
4648
+ — then `// lint-ok: <reason>` works per line.
4649
+ - `run_test` (MCP) and `e2e` run the same check before starting the
4650
+ browser, but against what the run will actually resolve — files **and**
4651
+ the ambient shell — so a suite that lives on a shell variable keeps
4652
+ running; only a name that would fail in the scenario anyway is refused
4653
+ up front (`run_test` answers `lint_failed`; `e2e` prints it and goes on,
4654
+ as with every `lint:*` error at its default severity — see
4655
+ Lint before a run).
4656
+ - A name **bound in the file** — assigned, a function parameter, a loop
4657
+ counter — is never flagged, whatever its case.
4658
+
4659
+ ### `lint:external-variable-no-value`
4660
+
4661
+ A bare `UPPER_SNAKE` identifier that only a template declares
4662
+ (`unotest/.env.example`, `.secrets.example`) while nothing gives it a
4663
+ value: no layer file, not the active overlay, not the shell. The name is
4664
+ not misspelt — the value is missing on this machine:
4665
+
4666
+ ```
4667
+ qa/lock.js:3:9: ✗ error [lint:external-variable-no-value] `QA_WHO` is declared in unotest/.env.example but has no value here: set it in unotest/.env, the active overlay, or the shell.
4668
+ ```
4669
+
4670
+ - Only a run reports it — `run_test` (MCP) and the pre-run check of
4671
+ `e2e`, which see the shell. The `lint` command reads files alone, so a
4672
+ value a CI runner exports is invisible to it; there a template's name
4673
+ counts as declared, and `lint` stays quiet.
4674
+ - A template never gives a value, even a non-empty placeholder
4675
+ (`QA_WHO=lock-1`): the run header names the templates apart from the
4676
+ value files, as `declared names only`.
4677
+
4678
+ ### `lint:one-test-per-file`
4679
+
4680
+ **Deprecated — reports nothing.** A scenario file may hold several
4681
+ `test_*`, each its own run (see the DSL reference). The id is still
4682
+ accepted in `linter.rules`, so a config that names it keeps loading; it
4683
+ goes away in the next major release — drop it from your config then.
4684
+
4685
+ ### `lint:scenario-in-root`
4686
+
4687
+ **Error.** A scenario file directly in `unotest/e2e/`. Scenarios live in
4688
+ feature folders (`unotest/e2e/checkout/pay.js`). Files whose name starts
4689
+ with `_` (`_template.js`, `_helpers/`) are exempt.
4690
+
4691
+ ### `lint:mustache-in-dsl`
4692
+
4693
+ **Error.** A string literal with `{{NAME}}` in scenario code. In DSL a
4694
+ variable is a bare identifier, `fill(loc, LOGIN)`, which the runtime
4695
+ resolves from `unotest/.env` / `.secrets`. The `{{NAME}}` form is for
4696
+ `explore_step` matcher fields only.
4697
+
4698
+ ### `lint:goto-concat`
4699
+
4700
+ **Warning.** `goto(APP_BASE_URL + '/path')`. `APP_BASE_URL` already
4701
+ reaches the browser as its `baseURL`, so pass the relative path,
4702
+ `goto('/path')`, and the test follows `--env` without edits. Another
4703
+ host's variable is not flagged: `goto(ITR_BASE_URL + '/path')` is how a
4704
+ test reaches a second host.
4705
+
4706
+ ### `lint:regex-invalid`
4707
+
4708
+ **Deprecated — reports nothing.** A regex literal that does not
4709
+ compile is refused by the parser, with the reason, before lint runs. The id is still accepted in
4710
+ `linter.rules`, so a config that names it keeps loading; it goes away in
4711
+ the next major release — drop it from your config then.
4712
+
4713
+ ### `lint:echo-assert`
4714
+
4715
+ **Warning.** A `waitForText` (or similar) whose text is part of a value
4716
+ the scenario itself filled. It can go green on your own input echoed in the
4717
+ UI before the real reply arrives. Assert a marker unique to the reply,
4718
+ or count messages and `waitForCount(loc, N + 1)`.
4719
+
4720
+ ### `lint:api-call-file-body`
4721
+
4722
+ **Warning.** An `apiCall` JSON body with a `file` field. It goes out as a
4723
+ string; nothing is attached. For a multipart upload pass `upload(...)`
4724
+ as the body: `apiCall('POST', path, upload('fixtures/doc.pdf', {field:
4725
+ 'file'}))`. If the endpoint really wants a JSON field named `file`, keep
4726
+ it with `// lint-ok: <reason>`.
4727
+
4728
+ ### `lint:lint-ok-missing-reason`
4729
+
4730
+ **Warning.** A bare `// lint-ok` with no reason. It suppresses nothing:
4731
+ write `// lint-ok: <why this is fine>`.
4732
+
4733
+ ### `lint:flow-returns-value`
4734
+
4735
+ **Warning.** A `flow_*` helper that returns a value. `flow_*` is an
4736
+ executable journey the agent may replay; a helper that only reads state
4737
+ belongs under a plain snake_case name.
4738
+
4739
+ ### `lint:env-host-from-base`
4740
+
4741
+ **Error.** An environment overlay is active (`UNOTEST_ENV` / `--env`),
4742
+ but a variable that becomes a HOST still takes its value from the base
4743
+ `unotest/.env`. The run would go to the base environment's host while
4744
+ everything else resolves against the overlay, so it refuses too. A
4745
+ variable is a host in three places:
4746
+
4747
+ - `APP_BASE_URL` — the base URL every relative `goto` resolves against;
4748
+ - the name passed as `apiCall(..., {base: "NAME"})`;
4749
+ - a variable passed as the URL in `goto(NAME)`.
4750
+
4751
+ Ways out:
4752
+
4753
+ - set the name in the overlay's file (`unotest/.env.<name>`);
4754
+ - or list it under `env: { shared: [...] }` in the config when the base
4755
+ value is meant for every environment.
4756
+
4757
+ Not reported:
4758
+
4759
+ - a value the process environment provides — a shell variable, the
4760
+ values a box injects;
4761
+ - a name the base file sets **empty** (`ADMIN_BASE_URL=`) and the overlay
4762
+ does not set. An empty value says the host does not exist in that
4763
+ environment; no overlay value is missing, so there is nothing to share.
4764
+ A test that reads the name bare then fails in the run, on that
4765
+ environment only — see [an empty value is not set](#envname-fallback--string--null).
4766
+
4767
+ The rule has been in place since 0.43.0.
4768
+
4769
+ ### `lint:shadows-dsl-function`
4770
+
4771
+ **Warning.** A function or variable of yours with the name of a DSL
4772
+ function. A function of yours is always reported: calls by that name run
4773
+ yours, and the DSL function is out of reach. A variable or a parameter is
4774
+ reported only when the code that sees it calls the DSL function bare by
4775
+ that name — `check(row)` next to a `check` parameter calls the variable.
4776
+ A helper's `check` or `count` parameter that nothing calls draws nothing,
4777
+ and neither does a method call (`list.count()`). Rename it (`my_upload`).
4778
+
4779
+ ### `lint:skip-outside-test`
4780
+
4781
+ **Error.** `skip()` outside a `test_*` body — in a helper, a `flow_*` or
4782
+ at the top level. There it would skip every test that calls it, a
4783
+ decision nobody reading the test can see. Call it in the test it skips:
4784
+ at the top of its body, or inside a step or an `if` block where data an
4785
+ earlier step read decides —
4786
+ `skip('needs LIVE_API', env('LIVE_API') == null)`.
4787
+
4788
+ ### `lint:set-test-timeout-outside-test`
4789
+
4790
+ **Error.** `setTestTimeout()` in a helper, a `flow_*` or at the top level.
4791
+ There it would change the budget of every test that calls it, a number
4792
+ nobody reading the test can see. Call it in the `test_*` body whose budget
4793
+ it sets, at the top: `setTestTimeout(90000)`.
4794
+
4795
+ ### `lint:wait-exceeds-test-budget`
4796
+
4797
+ **Warning.** A literal `timeoutMs` (or `timeout`) in a `test_*` body that is
4798
+ as long as the test's whole budget, or longer: `terminalWaitForText('x',
4799
+ {timeoutMs: 300000})` in a test that has 300000 ms. The budget is the one
4800
+ `setTestTimeout(N)` sets in that test, else the project's (`testTimeoutMs`).
4801
+ A wait like that can only end on the budget of the test, not on its own
4802
+ failure. Make the wait shorter, or raise the budget with `setTestTimeout()`.
4803
+ Only waits spelled as numbers in a `test_*` body are checked; helpers are
4804
+ skipped, since their budget is their caller's.
4805
+
4806
+ ### `lint:filter-unknown-option`, `lint:role-unknown-option`
4807
+
4808
+ **Deprecated — reports nothing.** A key that `filter`, `locator` or
4809
+ `getByRole` does not read is reported by `validator:options`, with the
4810
+ same message the run refuses it with — before the run starts, as every
4811
+ `validator:*` error is: `run_test` answers `lint_failed`, `e2e` stops with
4812
+ `run stopped: N error(s)` (the run would refuse the key too). The id is still accepted in
4813
+ `linter.rules`, so a config that names it keeps loading; it goes away in
4814
+ the next major release — drop it from your config then.
4815
+
4816
+ For `filter({visible: true})` or `filter({hasClass: 'done'})`: a class or
4817
+ an attribute of the element itself is CSS — `count(locator('tr.done'))`.
4818
+ For the enabled button: `getByRole('button', {name: 'Save', disabled:
4819
+ false})`.