@unotest/web 0.55.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 +106 -3
  4. package/README.md +4 -3
  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 +12 -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-CNvyInrY.d.ts → interfaces-BiGd3BdD.d.ts} +19 -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 +26 -2
  44. package/guides/dsl-reference.md +508 -28
  45. package/llms.txt +24 -5
  46. package/package.json +9 -8
  47. package/types/unotest-dsl.d.ts +27 -20
  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
@@ -1171,12 +1170,35 @@ waitForAnimations(getByRole('dialog'));
1171
1170
  assertScreenshot(getByRole('dialog'), 'edit-dialog');
1172
1171
  ```
1173
1172
 
1174
- ### `pause(ms)`
1173
+ ### `pause(ms, reason?)`
1175
1174
 
1176
- Hard sleep. **Avoid** — the linter flags it (`lint:pause-explicit`). Use
1177
- `waitFor` / `waitForText` / assertion polling instead. A justified
1178
- occurrence is silenced per-line with `// lint-ok: <reason>` (the reason
1179
- 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:
1180
1202
 
1181
1203
  ```js
1182
1204
  pause(500); // lint-ok: third-party widget has no completion signal to hook into
@@ -1760,7 +1782,7 @@ setLocalStorage('feature-flag', 'enabled');
1760
1782
  const v = getLocalStorage('feature-flag');
1761
1783
  ```
1762
1784
 
1763
- ### `setCookie(name, value, options?)` / `getCookie(name)` → `string`
1785
+ ### `setCookie(name, value, options?)`
1764
1786
 
1765
1787
  **Options:** `domain?`, `path?`, `expires?`, `httpOnly?`, `secure?`,
1766
1788
  `sameSite?`.
@@ -1769,6 +1791,44 @@ const v = getLocalStorage('feature-flag');
1769
1791
  setCookie('session', 'abc123', {path: '/', sameSite: 'Lax'});
1770
1792
  ```
1771
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
+
1772
1832
  ---
1773
1833
 
1774
1834
  ## Edge actions
@@ -1871,6 +1931,11 @@ Semantics:
1871
1931
  - **Timeout**: each call has a wall-clock budget —
1872
1932
  `sandbox.shellTimeoutMs` (default 120 000 ms) or per-call
1873
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.
1874
1939
  - Output capture is limited to 10 MiB per stream; exceeding it fails the
1875
1940
  step (write bulk output to a file instead).
1876
1941
  - **Env**: the child inherits the runner's `process.env` (which includes
@@ -2115,6 +2180,36 @@ A secret — a name from `unotest/.secrets`, or one a box injects — is
2115
2180
  refused, with a fallback or without: `env()` returns a plain string, and
2116
2181
  a credential must stay masked. Write the secret's bare name where its value is typed instead.
2117
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
+
2118
2213
  ### `readFile(path, options?)` → `string`
2119
2214
 
2120
2215
  Read a whole file once and return its content: the text by default, or
@@ -2572,6 +2667,17 @@ assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
2572
2667
  the mock keeps what it answered, and each request is returned once.
2573
2668
  On any other mask only requests from the call on count — to catch one
2574
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.
2575
2681
  - `{timeoutMs}` — default 20 000.
2576
2682
  - A `ws://` or `wss://` mask is refused: a WebSocket is no request.
2577
2683
 
@@ -2666,6 +2772,9 @@ assertNoRequest('**/*');
2666
2772
  A mask without a recording abort is an error, not a pass: nothing
2667
2773
  watched it.
2668
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).
2669
2778
 
2670
2779
  ---
2671
2780
 
@@ -3472,7 +3581,18 @@ screenshot('landing', {fullPage: true}); // full scroll height
3472
3581
  - `name` is slugified to `[a-z0-9._-]` (`'Bot Reply!'` → `bot-reply`,
3473
3582
  `'Q 17/a'` → `q-17-a`); omitted → `shot`. Files are numbered in
3474
3583
  capture order.
3475
- - **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.
3476
3596
  - Before capturing, the call waits for the network to go quiet and for a
3477
3597
  painted frame (up to 2s). Without it a `screenshot()` right after
3478
3598
  `goto()` would freeze the blank pre-render frame — `goto` resolves on
@@ -3714,7 +3834,7 @@ per option; an older spelling it still takes is named after the line.
3714
3834
  - `waitForText(text: string | RegExp, options?: { state?: string; exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3715
3835
  - `waitForCount(locator: Locator, count: number, options?: { exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3716
3836
  - `waitForAnimations(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3717
- - `pause(ms: number): void`
3837
+ - `pause(ms: number, reason?: string): void`
3718
3838
  - `waitForDownload(options?: { timeoutMs?: number; name?: string | RegExp }): any`
3719
3839
  - `clockFreeze(iso: string): void`
3720
3840
  - `clockTick(ms: number): void`
@@ -3732,7 +3852,7 @@ per option; an older spelling it still takes is named after the line.
3732
3852
  - `assertCount(locator: Locator, count: number, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3733
3853
  - `assertUrl(pattern: string | RegExp, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3734
3854
  - `assertJudge(locator: Locator, rubric: string): void`
3735
- - `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`
3736
3856
  - `assertEqual(actual: any, expected: any): void`
3737
3857
  - `assertTrue(condition: boolean, message?: string): void`
3738
3858
  - `assertSchema(value: any, schema: any): void`
@@ -3792,7 +3912,8 @@ per option; an older spelling it still takes is named after the line.
3792
3912
  - `setLocalStorage(key: string, value: string): void`
3793
3913
  - `getLocalStorage(key: string): string`
3794
3914
  - `setCookie(name: string, value: string, options?: { domain?: string; path?: string; expires?: number; httpOnly?: boolean; secure?: boolean; sameSite?: string }): void`
3795
- - `getCookie(name: string): string`
3915
+ - `getCookie(name: string, options?: { page?: any }): string`
3916
+ - `hasCookie(name: string, options?: { page?: any }): boolean`
3796
3917
 
3797
3918
  **Tabs, frames, contexts, extensions**
3798
3919
 
@@ -3820,8 +3941,8 @@ per option; an older spelling it still takes is named after the line.
3820
3941
  **Data, files, network, processes**
3821
3942
 
3822
3943
  - `shell(cmd: string, ...args: unknown[]): any`
3823
- - `waitForFile(path: string, pattern?: any, options?: { timeoutMs?: number }): string`
3824
- - `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`
3825
3946
  - `waitForJsonLine(path: string, filter: any, options?: { timeoutMs?: number }): any`
3826
3947
  - `assertNoJsonLine(path: string, filter: any, options?: { withinMs?: number }): void`
3827
3948
  - `readJsonLine(path: string, filter: any): any`
@@ -3836,11 +3957,11 @@ per option; an older spelling it still takes is named after the line.
3836
3957
  - `upload(path: string, options?: { field?: string; fields?: any }): any`
3837
3958
  - `mockRoute(glob: string, response: any): void`
3838
3959
  - `unmockRoute(glob?: string): void`
3839
- - `waitForRequest(glob: string, options?: { timeoutMs?: number }): any`
3960
+ - `waitForRequest(glob: string, options?: { timeoutMs?: number; method?: string }): any`
3840
3961
  - `waitForResponse(glob: string, options?: { status?: number; method?: string; since?: number; timeoutMs?: number }): any`
3841
3962
  - `waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any`
3842
3963
  - `networkEntries(options?: { since?: number; glob?: any }): any`
3843
- - `assertNoRequest(glob: string, options?: { since?: number }): void`
3964
+ - `assertNoRequest(glob: string, options?: { since?: number; method?: string }): void`
3844
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`
3845
3966
  - `setTerminal(index: number): void`
3846
3967
  - `closeTerminal(): void`
@@ -3867,7 +3988,7 @@ per option; an older spelling it still takes is named after the line.
3867
3988
 
3868
3989
  **Diagnostics**
3869
3990
 
3870
- - `screenshot(name?: string, options?: { fullPage?: boolean }): string`
3991
+ - `screenshot(name?: string, options?: { fullPage?: boolean; timeoutMs?: number }): string`
3871
3992
  - `note(label: string, value: any): void`
3872
3993
  - `consoleEntries(options?: { level?: any; since?: number }): any`
3873
3994
  - `pageErrors(options?: { since?: number }): any`
@@ -3879,6 +4000,29 @@ per option; an older spelling it still takes is named after the line.
3879
4000
  - `evaluateOnLocator(locator: Locator, jsBody: any, ...args: unknown[]): any`
3880
4001
  <!-- /generated:signatures -->
3881
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
+
3882
4026
  ---
3883
4027
 
3884
4028
  ## The language — JavaScript
@@ -4337,3 +4481,339 @@ helpers. A function, parameter or variable of your own named
4337
4481
  linter across `unotest/e2e/**/*.js`. `lint <name>` checks one scenario,
4338
4482
  named as `e2e` takes it (`lint values/string-escapes`); a file or a
4339
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})`.