@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.
- package/.claude/skills/write-e2e-test/SKILL.md +30 -7
- package/.claude/skills/write-e2e-test-ground/SKILL.md +6 -5
- package/CHANGELOG.md +106 -3
- package/README.md +4 -3
- package/dist/config/schema.d.ts +25 -19
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +8 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +12 -82
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/v8/scenario-worker.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +30 -3
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +31 -7
- package/dist/inspection/page-inject.js +80 -19
- package/dist/{interfaces-CNvyInrY.d.ts → interfaces-BiGd3BdD.d.ts} +19 -4
- package/dist/{linter-BpaIstU3.d.ts → linter-DIAb0JOB.d.ts} +8 -0
- package/dist/mcp/server.js +1 -1
- package/dist/runner/cli.d.ts +1 -1
- package/dist/runner/cli.js +1 -1
- package/dist/runner/init/chrome-probe.js +1 -1
- package/dist/runner/init.js +1 -1
- package/dist/runner/install-chromium.js +1 -1
- package/dist/runner/prepare-fix.js +1 -1
- package/dist/runner/scaffold-workspace.js +1 -1
- package/dist/runner/serve-fixture.js +1 -1
- package/dist/runner/web-runner-adapter.js +1 -1
- package/dist/scenario-variables-B-ULUTHt.d.ts +88 -0
- package/examples/idioms/README.md +16 -0
- package/examples/idioms/animations-list.js +24 -0
- package/examples/idioms/api-call-timeout.js +14 -0
- package/examples/idioms/background-tab.js +24 -0
- package/examples/idioms/clipboard-paste.js +25 -0
- package/examples/idioms/computed-style.js +21 -0
- package/examples/idioms/image-size.js +20 -0
- package/examples/idioms/never-appears.js +20 -0
- package/examples/idioms/never-condition.js +24 -0
- package/examples/idioms/page-code-function.js +18 -0
- package/examples/idioms/select-by-label.js +22 -0
- package/examples/idioms/wait-enabled.js +21 -0
- package/examples/idioms/wait-for-animations.js +16 -0
- package/examples/idioms/wait-until-value.js +32 -0
- package/guides/agent-integration.md +26 -2
- package/guides/dsl-reference.md +508 -28
- package/llms.txt +24 -5
- package/package.json +9 -8
- package/types/unotest-dsl.d.ts +27 -20
- package/types/unotest-lib.d.ts +5 -3
package/guides/dsl-reference.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
status: stable
|
|
3
|
-
last_updated: 2026-10-
|
|
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
|
-
|
|
129
|
-
|
|
130
|
-
`Date`,
|
|
131
|
-
|
|
132
|
-
`
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
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?)`
|
|
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?:
|
|
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?:
|
|
3824
|
-
- `assertNoFile(path: string, pattern?:
|
|
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})`.
|