@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.
- package/.claude/skills/write-e2e-test/SKILL.md +30 -7
- package/.claude/skills/write-e2e-test-ground/SKILL.md +6 -5
- package/CHANGELOG.md +160 -3
- package/README.md +24 -6
- 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 +29 -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-BU-PQbt4.d.ts → interfaces-BiGd3BdD.d.ts} +29 -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 +43 -5
- package/guides/dsl-reference.md +589 -34
- package/llms.txt +26 -6
- package/package.json +9 -8
- package/types/unotest-dsl.d.ts +36 -22
- 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
|
|
@@ -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.
|
|
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
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
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?)`
|
|
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?:
|
|
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?:
|
|
3750
|
-
- `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`
|
|
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})`.
|