@unotest/web 0.55.0 → 0.57.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/.claude/skills/write-e2e-test/SKILL.md +44 -7
  2. package/.claude/skills/write-e2e-test-ground/SKILL.md +20 -5
  3. package/CHANGELOG.md +250 -3
  4. package/README.md +7 -6
  5. package/bin/unotest-web.js +13 -0
  6. package/dist/config/schema.d.ts +29 -23
  7. package/dist/config/schema.js +1 -1
  8. package/dist/driver/index.d.ts +16 -2
  9. package/dist/driver/index.js +1 -1
  10. package/dist/dsl/index.d.ts +74 -94
  11. package/dist/dsl/index.js +1 -1
  12. package/dist/dsl/v8/scenario-worker.js +1 -1
  13. package/dist/dsl/web-dsl-language-service.d.ts +30 -3
  14. package/dist/dsl/web-dsl-language-service.js +1 -1
  15. package/dist/inspection/page-inject.d.ts +63 -7
  16. package/dist/inspection/page-inject.js +199 -19
  17. package/dist/{interfaces-CNvyInrY.d.ts → interfaces-DDp6Chwx.d.ts} +167 -10
  18. package/dist/{linter-BpaIstU3.d.ts → linter-q4UNIeGI.d.ts} +20 -0
  19. package/dist/mcp/server.js +1 -1
  20. package/dist/runner/cli.d.ts +1 -1
  21. package/dist/runner/cli.js +1 -1
  22. package/dist/runner/init/chrome-probe.js +1 -1
  23. package/dist/runner/init.js +1 -1
  24. package/dist/runner/install-chromium.js +1 -1
  25. package/dist/runner/prepare-fix.js +1 -1
  26. package/dist/runner/scaffold-workspace.js +1 -1
  27. package/dist/runner/serve-fixture.js +1 -1
  28. package/dist/runner/web-runner-adapter.js +1 -1
  29. package/dist/scenario-variables-CGexnWK4.d.ts +106 -0
  30. package/examples/idioms/README.md +16 -0
  31. package/examples/idioms/animations-list.js +24 -0
  32. package/examples/idioms/api-call-timeout.js +14 -0
  33. package/examples/idioms/background-tab.js +24 -0
  34. package/examples/idioms/clipboard-paste.js +25 -0
  35. package/examples/idioms/computed-style.js +21 -0
  36. package/examples/idioms/image-size.js +20 -0
  37. package/examples/idioms/never-appears.js +20 -0
  38. package/examples/idioms/never-condition.js +24 -0
  39. package/examples/idioms/page-code-function.js +18 -0
  40. package/examples/idioms/select-by-label.js +22 -0
  41. package/examples/idioms/wait-enabled.js +24 -0
  42. package/examples/idioms/wait-for-animations.js +16 -0
  43. package/examples/idioms/wait-until-value.js +32 -0
  44. package/guides/agent-integration.md +28 -4
  45. package/guides/dsl-reference.md +896 -45
  46. package/llms.txt +38 -9
  47. package/package.json +9 -8
  48. package/types/unotest-dsl.d.ts +107 -30
  49. package/types/unotest-lib.d.ts +5 -3
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  status: stable
3
- last_updated: 2026-10-13
3
+ last_updated: 2026-10-25
4
4
  ---
5
5
 
6
6
  # DSL Reference
@@ -125,18 +125,17 @@ it consists of:
125
125
  CHECKING stays off (`checkJs: false`) on purpose: diagnostics come from
126
126
  the DSL validator (`npx @unotest/web lint`), the editor only gains
127
127
  completion, hover docs, signature help and locator-chain resolution.
128
- It sets `noLib: true`: the editor's standard library is the scenario
129
- library alone, so it completes `Math.round` and `s.trim()` but not
130
- `Date`, `setTimeout` or `document` — what lint would refuse. A
131
- jsconfig an earlier `init` wrote reads the full JavaScript library;
132
- `lint` and runs say so in one line, and `npx @unotest/web types`
133
- brings it up to date. One you edited by hand is left as it is, with a
134
- line that says what to change.
135
- - `node_modules/@unotest/web/types/unotest-lib.d.ts` — the scenario
136
- library (`Math`, `JSON`, `Object`, `Map`, `Set`, the string, number and
137
- array methods), cut from TypeScript's own declarations to exactly what
138
- a scenario has. `keys()`, `values()` and `entries()` of a Map or a Set
139
- read as iterators, as they run: spread one for array methods.
128
+ Its standard library is JavaScript's own (`"lib": ["es2023", "dom"]`),
129
+ the one lint's type layer checks against: a scenario runs as plain
130
+ JavaScript, so `Date`, classes and `Map.prototype.keys` complete, and
131
+ the DOM is there for the page code handed to `evaluate`. A jsconfig an
132
+ earlier `init` wrote (`noLib` with the cut-down `unotest-lib.d.ts`)
133
+ is outdated; `lint` and runs say so in one line, and
134
+ `npx @unotest/web types` brings it up to date. One you edited by hand
135
+ is left as it is, with a line that says what to change.
136
+ - `node_modules/@unotest/web/types/unotest-lib.d.ts` — deprecated, no
137
+ longer updated: kept for one release so an old jsconfig that names it
138
+ keeps its globals until `types` rewrites it.
140
139
  - `node_modules/@unotest/web/types/unotest-dsl.d.ts` — ambient
141
140
  declarations for every DSL function, generated from the same contracts
142
141
  the validator uses and shipped with the package, so it always matches
@@ -455,6 +454,34 @@ selectOption(getByLabel('Folder'), {index: 0})
455
454
  scrollIntoView(getByText('Footer'))
456
455
  ```
457
456
 
457
+ ### `tap(loc, options?)` / `longPress(loc, options?)` / `swipe(loc, dx, dy, options?)`
458
+
459
+ One finger on a touch screen, after the same wait for the element as
460
+ any action. For what a phone does differently from a mouse — a tap
461
+ opens a chat, a long press on the same row opens its menu, a swipe
462
+ moves a row aside.
463
+
464
+ - `tap` — down and up at `position` (default the centre).
465
+ - `longPress` — held `durationMs` (default 800) before it lifts.
466
+ - `swipe` — down at `sourcePosition` (default the centre), moved `dx`,
467
+ `dy` CSS pixels over `durationMs` (default 300), lifted. The offset
468
+ reads as in `dragBy`.
469
+
470
+ ```js
471
+ tap(getByText('Alice')); // opens the chat
472
+ longPress(getByText('Alice')); // opens the row menu
473
+ swipe(getByText('Alice'), -200, 0, {durationMs: 400});
474
+ ```
475
+
476
+ They need a context with a touch screen — `profile: 'ios'` or a touch
477
+ `device` (a phone preset). Without one the step fails before touching
478
+ anything: `tap: this browser context has no touch screen, so nothing
479
+ was touched. Give it one with profile: 'ios' or a touch device …`.
480
+
481
+ **Options:** `tap` — `position?`, `timeoutMs?`; `longPress` —
482
+ `durationMs?`, `position?`, `timeoutMs?`; `swipe` — `durationMs?`,
483
+ `sourcePosition?`, `timeoutMs?`.
484
+
458
485
  ---
459
486
 
460
487
  ## Assertions
@@ -529,6 +556,63 @@ assertVisible(getByTestId('toast'))
529
556
  assertHidden(getByTestId('spinner'), {timeoutMs: 10000})
530
557
  ```
531
558
 
559
+ ### `assertInViewport(loc, options?)`
560
+
561
+ The element intersects the viewport — the visible part of the page,
562
+ cut down by every scroll container around it. It catches what
563
+ `assertVisible` lets through: an element that is rendered but scrolled
564
+ away, as when the arrow keys do not scroll a long block. Waits like the
565
+ other asserts and scrolls nothing itself. `{ratio}` (0..1) asks for at
566
+ least that share of the element in view; without it any part counts.
567
+
568
+ ```js
569
+ press(getByRole('main'), 'ArrowDown');
570
+ assertInViewport(getByRole('heading', {name: 'Pricing'}));
571
+ assertInViewport(getByTestId('chart'), {ratio: 0.5});
572
+ ```
573
+
574
+ A failure names the share it saw: `assertInViewport: expected in the
575
+ viewport — 0 of it is in view …`. No match at all says so; a `ratio`
576
+ outside 0..1 is refused before the wait.
577
+
578
+ **Options:** `ratio?`, `timeoutMs?`.
579
+
580
+ ### `assertNoFocusZoom(scope?, options?)`
581
+
582
+ iOS Safari zooms the page into a text field whose text is under 16px
583
+ when the field takes focus, and the page stays zoomed after. No engine
584
+ Playwright drives does that zoom, so the check reads its cause: every
585
+ visible, enabled, writable `input`, `textarea`, `select` and
586
+ `contenteditable` in `scope` (the whole page when absent), its computed
587
+ font size times the page scale, against `minFontPx`. A
588
+ `<meta name="viewport">` with `maximum-scale` at 1 or below forbids the
589
+ zoom, and the check passes. Run it on an iPhone device preset, so the
590
+ page scale is the phone's.
591
+
592
+ **The page scale.** A field is small when its CSS font size times the
593
+ page scale is under `minFontPx`. When the scale is not 1 the failure
594
+ names both, and what the reader sees: `input#search 16px × page scale
595
+ 0.40 = 6.4px`. A page without `<meta name="viewport"
596
+ content="width=device-width">` is laid out at a desktop width and shown
597
+ zoomed out on a phone, so even 16px text looks small and iOS zooms in on
598
+ any field; the failure says so. Add the meta, and the scale is 1.
599
+
600
+ **Options:** `minFontPx?` (default `16`), `timeoutMs?`. The options may
601
+ take the place of the scope.
602
+
603
+ ```js
604
+ assertNoFocusZoom(); // the whole page
605
+ assertNoFocusZoom(getByRole('form', {name: 'Chat'}));
606
+ assertNoFocusZoom({minFontPx: 14});
607
+ ```
608
+
609
+ **Not covered: the on-screen keyboard.** On iOS the keyboard shrinks the
610
+ visual viewport only, and an element fixed to the bottom of the layout
611
+ ends up under it. No engine Playwright drives shows the keyboard or
612
+ shrinks the visual viewport, and `setViewport` shrinks the layout too: a
613
+ check with `setViewport` and `assertInViewport` catches a layout that
614
+ the keyboard resizes (Android's), not iOS's composer under the keyboard.
615
+
532
616
  ### `assertNeverAppears(loc, options)`
533
617
 
534
618
  Negative window assertion: watch for `withinMs` (required) and **fail
@@ -674,6 +758,12 @@ assertSchema(req.postDataJson, schema);
674
758
  - The schema must be an object: pass what `readJson` returned, not the
675
759
  file name.
676
760
 
761
+ zod's own `schema.parse(value)` would import the schema at run time — a
762
+ scenario has no imports. The JSON Schema above checks the value at run
763
+ time; the schema's type, `z.infer`, named in JSDoc, lets `lint` catch a
764
+ renamed field before the run (see the type check in
765
+ `dsl/validator.md`).
766
+
677
767
  ### `skip(reason, condition?)`
678
768
 
679
769
  End the test as **skipped**: it does not apply here — a live-only check
@@ -853,7 +943,14 @@ so in one warning line, once.
853
943
  **The baseline** lives next to the scenario:
854
944
  `unotest/e2e/<scenario path without .js>.screenshots/<name>.png` (the
855
945
  name is lower-cased and dashed, as for `screenshot()`), and travels with
856
- the scenario into a box bundle. Two names that become the same file in one
946
+ the scenario into a box bundle. A suite with several `browsers` keeps a
947
+ baseline per engine: the first engine listed under `<name>.png` — so a
948
+ suite that adds an engine keeps its baselines as they are — and any
949
+ other under `<name>.<engine>.png` (`home.webkit.png`); an engine
950
+ `UNOTEST_BROWSER` names outside the list too. Reordering `browsers`
951
+ changes which engine `<name>.png` belongs to: rename the files with it.
952
+ A failure message names the engine and the baseline file it compared
953
+ with. Two names that become the same file in one
857
954
  scenario (`"Checkout Page"` and `"checkout/page"`) are refused at the
858
955
  second one; the same name twice in one run of `--update-screenshots` is
859
956
  written twice, and the runner says that the last one wins. A symlink on
@@ -871,8 +968,9 @@ shared directory of the suite); one that leads outside is refused.
871
968
  check nothing.
872
969
  - **Accept the current page** — `npx @unotest/web e2e <name>
873
970
  --update-screenshots` (MCP: `run_test {updateScreenshots: true}`)
874
- writes every snapshot of the run as its baseline; the asserts pass and
875
- the journal marks them `updated`. Refused on a box.
971
+ writes every snapshot of the run as its baseline — in every engine of
972
+ `browsers`, each its own file; the asserts pass and the journal marks
973
+ them `updated`. Refused on a box.
876
974
  - **It failed** — the run keeps three pictures: `expected`, `actual` and
877
975
  `diff` (differing pixels red over a greyed-out snapshot, masked areas
878
976
  grey). The viewer shows them side by side on the failed step; the
@@ -1171,12 +1269,35 @@ waitForAnimations(getByRole('dialog'));
1171
1269
  assertScreenshot(getByRole('dialog'), 'edit-dialog');
1172
1270
  ```
1173
1271
 
1174
- ### `pause(ms)`
1272
+ ### `pause(ms, reason?)`
1273
+
1274
+ A fixed delay. To wait for the page, use `waitFor` / `waitForText` /
1275
+ assertion polling instead: a bare `pause(ms)` is reported by
1276
+ `lint:pause-explicit`.
1277
+
1278
+ #### Waiting a fixed time
1279
+
1280
+ When the wait IS the test — a quiz that opens 20 minutes after the start,
1281
+ a rate limit that lifts after a minute — say why in the call:
1282
+
1283
+ ```js
1284
+ setTestTimeout(30 * 60 * 1000); // the budget has room for the wait
1285
+ step("Wait until the hunt opens", () => {
1286
+ pause(21 * 60 * 1000, 'the hunt opens 21 minutes after the start');
1287
+ });
1288
+ ```
1289
+
1290
+ - The reason is printed on the step (`pause 1260000 ms: the hunt opens …`)
1291
+ and `lint:pause-explicit` leaves the call be. It must be text that is
1292
+ not empty.
1293
+ - A wait longer than the test's budget ends on the budget: raise it with
1294
+ [`setTestTimeout(ms)`](#settesttimeoutms) in that test.
1295
+ - Not `shell('sleep 1260')`: that waits the same, says nothing on the
1296
+ step, and is a process the run has to keep.
1175
1297
 
1176
- Hard sleep. **Avoid** — the linter flags it (`lint:pause-explicit`). Use
1177
- `waitFor` / `waitForText` / assertion polling instead. A justified
1178
- occurrence is silenced per-line with `// lint-ok: <reason>` (the reason
1179
- is required — a bare `// lint-ok` suppresses nothing):
1298
+ A short pause you cannot replace (a widget with no signal to wait for)
1299
+ can also be silenced on its line with `// lint-ok: <reason>` — the reason
1300
+ is required, a bare `// lint-ok` suppresses nothing:
1180
1301
 
1181
1302
  ```js
1182
1303
  pause(500); // lint-ok: third-party widget has no completion signal to hook into
@@ -1344,14 +1465,14 @@ path resolves against the base URL, as in `goto`. Without one the tab
1344
1465
  stays blank. A tab `newPage` opened is the scenario's own: `waitForPage`
1345
1466
  never returns it.
1346
1467
 
1347
- ### `closePage(index?)`
1468
+ ### `closePage(index?, { beforeUnload? })` → `{asked, closed}`
1348
1469
 
1349
1470
  Close tab `index`; no index: the active tab. Closing the active tab
1350
1471
  makes the tab that was active before it active again (and brings it to
1351
1472
  front); if that one is closed too, the tab at the index below. Closing
1352
1473
  another tab leaves the steps where they are — later tabs move down one
1353
- index. The only open tab cannot be closed: the step fails with
1354
- `cannot close the only open tab`.
1474
+ index. Without options the only open tab cannot be closed: the step
1475
+ fails with `cannot close the only open tab`.
1355
1476
 
1356
1477
  ```js
1357
1478
  newPage('/settings'); // tab 1, active
@@ -1359,6 +1480,30 @@ assertUrl('/settings');
1359
1480
  closePage(); // back on tab 0
1360
1481
  ```
1361
1482
 
1483
+ Without options the tab closes without running its `beforeunload`, so
1484
+ the app never asks "Leave site?". `{beforeUnload: 'leave' | 'stay'}`
1485
+ closes it the way a person does: the page runs `beforeunload` and its
1486
+ prompt gets your answer. `'leave'` closes the tab; `'stay'` keeps it
1487
+ open and the steps stay on it. The run's `dialogPolicy` does not answer
1488
+ this prompt. With an index the options go second:
1489
+ `closePage(1, {beforeUnload: 'stay'})`.
1490
+
1491
+ Returns `{asked, closed}`: `asked` — the page showed the prompt,
1492
+ `closed` — the tab is gone. A browser asks only after real user input on
1493
+ the page, such as a click; a `fill` alone does not count in Firefox.
1494
+ A page that does not ask, and a call without options, return
1495
+ `{asked: false, closed: true}`.
1496
+
1497
+ With `beforeUnload` the only open tab closes too. A blank tab is left in
1498
+ its place, at index 0, and the scenario goes on there: `goto` works next.
1499
+
1500
+ ```js
1501
+ click(getByLabel('Name')); // real input: the page may now ask
1502
+ fill(getByLabel('Name'), 'Draft');
1503
+ const r = closePage({ beforeUnload: 'stay' });
1504
+ assertEqual(r, { asked: true, closed: false }); // still on the tab
1505
+ ```
1506
+
1362
1507
  ### `waitForPage(options?)` → `number`
1363
1508
 
1364
1509
  Wait for a tab the scenario has not received yet, make it active and
@@ -1382,7 +1527,7 @@ assertUrl('/report');
1382
1527
  setPage(0);
1383
1528
  ```
1384
1529
 
1385
- ### `newContext({profile?, cdpEndpoint?})` → `number` / `setContext(index)`
1530
+ ### `newContext({profile?, cdpEndpoint?, headers?, viewport?})` → `number` / `setContext(index)`
1386
1531
 
1387
1532
  A second browser context: another client of the same app, with its own
1388
1533
  cookies, localStorage, sessionStorage and tabs. For anything that takes
@@ -1454,6 +1599,59 @@ own.
1454
1599
  — your function wins a call by that name, so the DSL's is out of reach
1455
1600
  until you rename it.
1456
1601
 
1602
+ #### Request headers: `newContext({headers: {...}})`
1603
+
1604
+ `headers` is an object of strings. Every page of the new context sends
1605
+ them with every request: documents, `fetch` and XHR, every tab. The run's
1606
+ own context does not. Use it for a host that lets the app in by a token
1607
+ in a header.
1608
+
1609
+ ```js
1610
+ function test_host_behind_a_token() {
1611
+ step("A client with the token opens the host", () => {
1612
+ newContext({headers: {Authorization: API_TOKEN}});
1613
+ goto('/dashboard');
1614
+ assertVisible(getByRole('heading', {name: 'Dashboard'}));
1615
+ });
1616
+ }
1617
+ ```
1618
+
1619
+ `API_TOKEN` lives in `unotest/.secrets` with its scheme: `API_TOKEN=Bearer
1620
+ eyJ…`. The value is masked in the journal and the run log. Over MCP,
1621
+ `new_context` and `explore_start` take the same `headers`; a value written
1622
+ as `{{API_TOKEN}}` is the variable. `{{NAME}}` is read only as the whole
1623
+ value: `"Bearer {{API_TOKEN}}"` is sent as those letters, so the prefix
1624
+ goes into the secret. A value that is not a string is refused.
1625
+
1626
+ #### Its own window: `newContext({viewport: {...}})`
1627
+
1628
+ `viewport` is `{width, height, deviceScaleFactor}`, all optional — the
1629
+ fields of `viewport` in `unotest.config`, and of `viewport` on MCP
1630
+ `new_context`. The new context opens on that window instead of the
1631
+ config's. The scale is fixed when a context opens, so this is the way to
1632
+ a second scale in a scenario: `setViewport` changes width and height
1633
+ only.
1634
+
1635
+ ```js
1636
+ function test_narrow_screen_at_2x() {
1637
+ step("A client on a narrow screen at twice the density", () => {
1638
+ newContext({viewport: {width: 854, height: 534, deviceScaleFactor: 2}});
1639
+ goto('/dashboard');
1640
+ assertVisible(getByRole('navigation', {name: 'Menu'}));
1641
+ });
1642
+ }
1643
+ ```
1644
+
1645
+ - **Whole, not merged:** the window asked for replaces the config's. A
1646
+ `deviceScaleFactor` not given is `1`, not the config's; the config's
1647
+ `device` is not applied under it.
1648
+ - **Refused:** a stray field, a width or height that is not a positive
1649
+ integer, a scale that is not a positive number — one line naming the
1650
+ fields, before the run and at the call.
1651
+ - **With the others:** `viewport` goes next to `headers`, `profile` and
1652
+ `cdpEndpoint`; on a profile or a joined browser the context opens on
1653
+ that window too.
1654
+
1457
1655
  #### Two devices: `newContext({profile: '<dir>'})`
1458
1656
 
1459
1657
  `{profile: '<dir>'}` opens the context on a persistent browser profile of
@@ -1545,7 +1743,9 @@ setViewport({width: 1280, height: 720});
1545
1743
  Both fields are required. Anything else is refused on that line,
1546
1744
  `deviceScaleFactor` included: the scale is fixed when the browser opens,
1547
1745
  and changing it would need a new browser context — the page under test
1548
- would be lost. See [Viewport and scale](#viewport-and-scale).
1746
+ would be lost. A second context on its own scale is
1747
+ `newContext({viewport: {width, height, deviceScaleFactor}})`. See
1748
+ [Viewport and scale](#viewport-and-scale).
1549
1749
 
1550
1750
  `setViewport(null)` runs the test on the real window — but only before
1551
1751
  the test does anything in its browser: the first navigation, `mockRoute`,
@@ -1639,6 +1839,9 @@ Where the window's size and scale come from, first match wins:
1639
1839
  replace the config's window for that context. `explore_start` with a
1640
1840
  window while a context is already open is refused — call
1641
1841
  `new_context` with it instead.
1842
+ In a scenario, `newContext({viewport})` does the same for the context
1843
+ it opens (see `newContext` above); the run's own context keeps the
1844
+ window below.
1642
1845
  2. **The collection.** `viewport:` in `unotest/e2e/_collections/<name>.yaml`
1643
1846
  applies to every scenario that collection runs; the same scenario run
1644
1847
  on its own keeps the config's window. `null` is the real window,
@@ -1760,7 +1963,7 @@ setLocalStorage('feature-flag', 'enabled');
1760
1963
  const v = getLocalStorage('feature-flag');
1761
1964
  ```
1762
1965
 
1763
- ### `setCookie(name, value, options?)` / `getCookie(name)` → `string`
1966
+ ### `setCookie(name, value, options?)`
1764
1967
 
1765
1968
  **Options:** `domain?`, `path?`, `expires?`, `httpOnly?`, `secure?`,
1766
1969
  `sameSite?`.
@@ -1769,20 +1972,85 @@ const v = getLocalStorage('feature-flag');
1769
1972
  setCookie('session', 'abc123', {path: '/', sameSite: 'Lax'});
1770
1973
  ```
1771
1974
 
1975
+ `domain` defaults to the current page's host, `path` to `/`. The cookie
1976
+ is read back after the write: one the browser does not keep fails the
1977
+ step, without naming the value — `sameSite: 'None'` needs `secure: true`:
1978
+
1979
+ ```
1980
+ setCookie('cross'): the browser dropped the cookie — sameSite: 'None' requires secure: true
1981
+ ```
1982
+
1983
+ A cookie set with `expires` in the past is a deletion: the browser drops
1984
+ it, and the step passes.
1985
+
1986
+ ```js
1987
+ setCookie('session', '', {expires: 1}); // delete it
1988
+ ```
1989
+
1990
+ ### `getCookie(name, options?)` → `string` / `hasCookie(name, options?)` → `boolean`
1991
+
1992
+ `getCookie` reads a cookie's value, `''` when there is none.
1993
+ `hasCookie` says whether it is there at all — the probe that tells a
1994
+ missing cookie from an empty value, as `hasAttribute` does for
1995
+ `getAttribute`.
1996
+
1997
+ Two views of the cookies:
1998
+
1999
+ - **default — the jar** of the browser context: every domain and path,
2000
+ `httpOnly` too. What the server is sent.
2001
+ - **`{page: true}`** — what the page's script is given: `document.cookie`
2002
+ of the page, or of the frame entered with `enterFrame`. No `httpOnly`
2003
+ cookie, none for another path or domain; the browser decides, as it
2004
+ does for the app.
2005
+
2006
+ ```js
2007
+ setCookie('session', 'abc', {httpOnly: true});
2008
+ assertTrue(hasCookie('session')); // the jar has it
2009
+ assertTrue(!hasCookie('session', {page: true})); // the page's script does not
2010
+ assertEqual(getCookie('theme', {page: true}), 'dark');
2011
+ ```
2012
+
1772
2013
  ---
1773
2014
 
1774
2015
  ## Edge actions
1775
2016
 
1776
- ### `dragAndDrop(from, to, options?)`
2017
+ ### `dragAndDrop(from, to, { force?, sourcePosition?, targetPosition?, timeoutMs? })`
1777
2018
 
1778
- Uses Playwright `loc.dragTo()` — mouse-event drag. Works for most
1779
- draggables; native HTML5 drag-and-drop (real `DragEvent`) is a known
1780
- limitation — see `KNOWN_ISSUES.md`.
2019
+ Drag one element onto another with mouse events. Works for most
2020
+ draggables; native HTML5 drag-and-drop (a real `DragEvent`) is not
2021
+ produced, so a page that listens only for `dragstart` / `drop` sees
2022
+ nothing.
2023
+
2024
+ `sourcePosition` and `targetPosition` are `{x, y}` points inside each
2025
+ element: CSS pixels from its top-left corner, by default its centre.
2026
+ `from` and `to` may be the same element: that sweeps a selection inside
2027
+ one frame, from one point to the other.
1781
2028
 
1782
2029
  ```js
1783
2030
  dragAndDrop(getByTestId('todo-1'), getByTestId('list-done'))
2031
+ const chart = getByTestId('chart');
2032
+ dragAndDrop(chart, chart, { sourcePosition: { x: 10, y: 50 }, targetPosition: { x: 200, y: 50 } })
1784
2033
  ```
1785
2034
 
2035
+ ### `dragBy(loc, dx, dy, options?)`
2036
+
2037
+ Take hold of the element — its centre, or the `{x, y}` point
2038
+ `sourcePosition` inside it — move the pointer `dx`, `dy` CSS pixels and
2039
+ let go. For a drag with no element to drop on: a resize handle, a
2040
+ slider, a selection box on a canvas. Synthetic mouse events in several
2041
+ steps, after the same wait for the element as any action.
2042
+
2043
+ ```js
2044
+ dragBy(getByRole('separator', {name: 'Resize sidebar'}), 120, 0);
2045
+ dragBy(getByTestId('canvas'), 200, 80, {sourcePosition: {x: 10, y: 10}});
2046
+ ```
2047
+
2048
+ `dx` / `dy` that are not finite numbers and a `sourcePosition` without
2049
+ both coordinates are refused before the drag: `dragBy: dx must be a
2050
+ finite number of pixels, got …`.
2051
+
2052
+ **Options:** `sourcePosition?`, `force?`, `timeoutMs?`.
2053
+
1786
2054
  ### `uploadFile(loc, paths)`
1787
2055
 
1788
2056
  `paths` can be a single string or an array.
@@ -1871,6 +2139,11 @@ Semantics:
1871
2139
  - **Timeout**: each call has a wall-clock budget —
1872
2140
  `sandbox.shellTimeoutMs` (default 120 000 ms) or per-call
1873
2141
  `{timeoutMs}`. On expiry the child is killed and the step fails.
2142
+ A per-call `{timeoutMs}` longer than what is left of the test's budget
2143
+ is said before the command starts — a warning on the step with both
2144
+ numbers and the `setTestTimeout(…)` that fits it. The command still
2145
+ runs; the budget ends the test first if it takes that long. A literal
2146
+ that long is reported by `lint:wait-exceeds-test-budget` before the run.
1874
2147
  - Output capture is limited to 10 MiB per stream; exceeding it fails the
1875
2148
  step (write bulk output to a file instead).
1876
2149
  - **Env**: the child inherits the runner's `process.env` (which includes
@@ -2115,6 +2388,36 @@ A secret — a name from `unotest/.secrets`, or one a box injects — is
2115
2388
  refused, with a fallback or without: `env()` returns a plain string, and
2116
2389
  a credential must stay masked. Write the secret's bare name where its value is typed instead.
2117
2390
 
2391
+ **An empty value is not set.** `ADMIN_BASE_URL=` in the layer files the
2392
+ run reads means the name has no value on this environment. `env()`
2393
+ returns the fallback, or `null`. A bare `ADMIN_BASE_URL` fails the test
2394
+ with the name and the environment:
2395
+
2396
+ ```
2397
+ `ADMIN_BASE_URL` is empty on this environment (environment "dev" …) — an empty value means "not set here". …
2398
+ ```
2399
+
2400
+ It never reads `""`: a `goto` to an empty URL would land on
2401
+ `APP_BASE_URL` and pass. To keep such a test, skip it where the name is
2402
+ missing — this works on every run, with `--env` or without:
2403
+
2404
+ ```js
2405
+ function test_admin_panel() {
2406
+ skip('ADMIN_BASE_URL is not set here', env('ADMIN_BASE_URL', null) == null);
2407
+ step('Open the admin panel', () => {
2408
+ goto(ADMIN_BASE_URL);
2409
+ });
2410
+ }
2411
+ ```
2412
+
2413
+ `// @env local, staging` above the test (see
2414
+ environments) is enough only if you always run with
2415
+ `--env`: a run without `--env` ignores the marker, reads the base
2416
+ `unotest/.env` and fails the same way. A secret fails the same way too,
2417
+ and the message never carries its value; `env()` refuses a secret, so
2418
+ the `skip` line does not apply to it — give the secret a value, or keep
2419
+ the test to `--env` runs with `// @env`.
2420
+
2118
2421
  ### `readFile(path, options?)` → `string`
2119
2422
 
2120
2423
  Read a whole file once and return its content: the text by default, or
@@ -2288,6 +2591,11 @@ file the overlay was supposed to replace. The same rule covers
2288
2591
  `APP_BASE_URL` (the base every relative `goto` resolves against) and a
2289
2592
  variable used as the URL in `goto(NAME)`.
2290
2593
 
2594
+ `env.shared` takes any name, not only hosts: since 0.57.0 every other
2595
+ bare read of a name the base file still provides under `--env` is a
2596
+ warning ([`lint:env-from-base`](#lintenv-from-base)), and the list
2597
+ silences it the same way.
2598
+
2291
2599
  **Per-call timeout — `{timeoutMs}`.** A call has no time limit of its
2292
2600
  own: it waits as long as the step and the test allow. An endpoint that
2293
2601
  must answer in a known time — or a slow one you would rather fail fast
@@ -2385,6 +2693,29 @@ server sent it. These fail the step, quoting the last MCP message:
2385
2693
  - a result marked `isError` — pass `{allowError: true}` to get it back
2386
2694
  and check it yourself.
2387
2695
 
2696
+ ### `mcpCallStart(server, tool, args?)` → call / `mcpCallResult(call, options?)` → `{content, structuredContent?, isError?}`
2697
+
2698
+ A call that waits for the test itself: `ask_human` shows a card and
2699
+ answers only after Done. `mcpCall` would hold the scenario until then,
2700
+ so nothing could click Done. `mcpCallStart` sends the request and
2701
+ returns at once; `mcpCallResult` waits for the answer and returns it as
2702
+ `mcpCall` would, with the same failures and `allowError`.
2703
+
2704
+ ```js
2705
+ const srv = mcpStart('node', ['server.js']);
2706
+ const call = mcpCallStart(srv, 'ask_human', {question: 'Ship?'});
2707
+ click(getByRole('button', {name: 'Done'}));
2708
+ const res = mcpCallResult(call, {timeoutMs: 30000});
2709
+ ```
2710
+
2711
+ - `timeoutMs` (default 30 s) counts from `mcpCallResult`. Running out
2712
+ cancels the call and its answer is gone — no polling with short
2713
+ waits.
2714
+ - Each result is taken once: a second `mcpCallResult` of the same call
2715
+ fails with `… was already taken`.
2716
+ - A call never taken is a warning in the journal when the server stops
2717
+ (`mcpStop` or the end of the test), not a failure.
2718
+
2388
2719
  ### `mcpWaitNotification(server, method, options?)` → params
2389
2720
 
2390
2721
  Waits for a notification of `method` and returns its `params`.
@@ -2572,6 +2903,17 @@ assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
2572
2903
  the mock keeps what it answered, and each request is returned once.
2573
2904
  On any other mask only requests from the call on count — to catch one
2574
2905
  the previous step sent, mock the mask with `{continue: true}` first.
2906
+ - `{method}` — `'GET'`, `'POST'`, … in any case: only a request of that
2907
+ method is taken. One of another method is not taken and stays for the
2908
+ next wait, so a GET and a POST to one path need no order of masks:
2909
+
2910
+ ```js
2911
+ const saved = waitForRequest('**/api/item', { method: 'POST' });
2912
+ const read = waitForRequest('**/api/item', { method: 'GET' });
2913
+ ```
2914
+
2915
+ On a mask that is not mocked a request of another method that comes
2916
+ while the call waits is not kept: mock the mask to keep it.
2575
2917
  - `{timeoutMs}` — default 20 000.
2576
2918
  - A `ws://` or `wss://` mask is refused: a WebSocket is no request.
2577
2919
 
@@ -2649,6 +2991,36 @@ assertTrue(socket.url.endsWith('/ws'));
2649
2991
  - A timeout names the mask and the sockets the page did open.
2650
2992
  - `{timeoutMs}` — default 20 000.
2651
2993
 
2994
+ ### `waitForWebSocketFrame(glob, options?)` → frame / `webSocketFrames(glob, options?)` → `frame[]`
2995
+
2996
+ What a socket said, not only that it opened. A frame is `{url,
2997
+ direction, text, json, at}`: `direction` is `'sent'` (by the page) or
2998
+ `'received'`, `json` is `text` parsed (`null` when it is not JSON), `at`
2999
+ is epoch ms; a binary frame has `size` (bytes) instead of `text`.
3000
+
3001
+ `waitForWebSocketFrame` waits for a frame on a socket matching `glob`
3002
+ and takes it — the next call gives the next frame. Frames are kept from
3003
+ the page's last load, so a `ping` the page sent on open, before the
3004
+ step, counts. `match` filters on `json` — scalar values at dot paths,
3005
+ as `waitForJsonLine` reads them. `webSocketFrames` returns every frame
3006
+ kept, oldest first, and takes none.
3007
+
3008
+ ```js
3009
+ goto('/chat');
3010
+ waitForWebSocketFrame('**/ws', {direction: 'sent'}); // the ping
3011
+ const hello = waitForWebSocketFrame('**/ws', {direction: 'received', match: {type: 'hello'}});
3012
+ assertEqual(webSocketFrames('**/ws', {direction: 'sent'}).length, 1);
3013
+ ```
3014
+
3015
+ A timeout names the sockets the page opened and its last frames: `no
3016
+ WebSocket frame received matching … on "**/ws" within 20000 ms; the
3017
+ page opened …; its last frames: …`. A `direction` other than `'sent'` /
3018
+ `'received'` is refused. A new document starts the frames again; past
3019
+ 1000 a tab the oldest go first.
3020
+
3021
+ **Options:** `waitForWebSocketFrame` — `direction?`, `match?`,
3022
+ `timeoutMs?` (default 20 000); `webSocketFrames` — `direction?`.
3023
+
2652
3024
  ### `assertNoRequest(glob, options?)`
2653
3025
 
2654
3026
  Fails if the recording abort at `glob` stopped any request, naming
@@ -2666,6 +3038,9 @@ assertNoRequest('**/*');
2666
3038
  A mask without a recording abort is an error, not a pass: nothing
2667
3039
  watched it.
2668
3040
  - `{since}` — epoch ms, as `nowMs()` gives: only requests from then on.
3041
+ - `{method}` — `'POST'` and the like, in any case: only stopped requests
3042
+ of that method count (`assertNoRequest('**/api/**', { method: 'POST' })`
3043
+ lets the page read but not write).
2669
3044
 
2670
3045
  ---
2671
3046
 
@@ -2831,6 +3206,12 @@ the same way.
2831
3206
  does for browser contexts; indices stay put when a window closes.
2832
3207
  `closeTerminal` closes the active one.
2833
3208
 
3209
+ The page steps are not moved: `click`, `fill` and the other steps on an
3210
+ element keep acting on the active page while a terminal is active. When
3211
+ such a step times out with a terminal open, its message names the page
3212
+ it waited on (index and url) and the terminal, with the way to each:
3213
+ `setPage(n)` for another page, `setTerminal(n)` for another terminal.
3214
+
2834
3215
  ### `terminalType(text)` / `terminalPress(key)`
2835
3216
 
2836
3217
  `terminalType` puts the text in as a paste, line by line, and a line
@@ -3086,7 +3467,10 @@ Read page properties directly into a local variable.
3086
3467
  const href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
3087
3468
  ```
3088
3469
 
3089
- Returns `""` when the attribute is missing — which makes it **blind to
3470
+ Returns `""` when the attribute is missing — never `null`, so
3471
+ `getAttribute(loc, name) == null` is never true (see
3472
+ [`lint:get-attribute-null`](#lintget-attribute-null)). Check presence
3473
+ with `hasAttribute(loc, name)`. The same `""` makes it **blind to
3090
3474
  boolean attributes**: `<button disabled>` and a button without the
3091
3475
  attribute both read `""`. For those use `isDisabled(loc)` /
3092
3476
  `hasAttribute(loc, name)`.
@@ -3472,7 +3856,18 @@ screenshot('landing', {fullPage: true}); // full scroll height
3472
3856
  - `name` is slugified to `[a-z0-9._-]` (`'Bot Reply!'` → `bot-reply`,
3473
3857
  `'Q 17/a'` → `q-17-a`); omitted → `shot`. Files are numbered in
3474
3858
  capture order.
3475
- - **Options:** `fullPage?` (default `false` — viewport only).
3859
+ - **Options:** `fullPage?` (default `false` — viewport only);
3860
+ `timeoutMs?` — how long the capture may take, default the context's
3861
+ `defaultTimeoutMs`. A busy page (a chat widget still loading fonts)
3862
+ may need more: `screenshot('bot-reply', {timeoutMs: 15000})`.
3863
+ - **A capture that runs out of time does not fail the test.**
3864
+ `screenshot()` is evidence: the call returns `null`, the step gets a
3865
+ warning line (`screenshot "bot-reply" not taken (…)`), and the reason is
3866
+ filed in the same sequence as the pictures,
3867
+ `screenshot/<NNN>-bot-reply-screenshot-error.txt`. Any other failure
3868
+ of the capture (the page has gone) fails the step as before.
3869
+ [`assertScreenshot`](#assertscreenshotname-options--assertscreenshotloc-name-options)
3870
+ is a check and still fails on a timeout.
3476
3871
  - Before capturing, the call waits for the network to go quiet and for a
3477
3872
  painted frame (up to 2s). Without it a `screenshot()` right after
3478
3873
  `goto()` would freeze the blank pre-render frame — `goto` resolves on
@@ -3523,6 +3918,16 @@ assertTrue(consoleEntries({ level: ['warn', 'error'], since: before }).length ==
3523
3918
  `console.json` holds the lines of every browser context, each with its
3524
3919
  `contextIndex`, the last 500 by time.
3525
3920
 
3921
+ Over MCP an agent driving the page by hand reads the same record with
3922
+ `explore_step {action: "console_entries"}` (alone or inside
3923
+ `explore_steps`, never recorded): `entries` (`level`, `text`, `url`, `at`),
3924
+ `errors` — what the page threw uncaught (`message`, `stack`, `url`, `at`) —
3925
+ and a `cursor`. Pass the cursor back as `since` to read only what came
3926
+ after it; a cursor of another tab or context reads the active page from
3927
+ the start and answers `cursorReset: true`. `options.level` is one level or
3928
+ a list; `options.limit` (up to 200, default 50) keeps the newest lines and
3929
+ counts the rest in `dropped`.
3930
+
3526
3931
  ### `networkEntries(options?)` → `[{ url, method, status, ok, headers, requestJson, responseJson, responseText, at }]`
3527
3932
 
3528
3933
  What the active page requested and was answered, oldest first. Like the
@@ -3704,7 +4109,11 @@ per option; an older spelling it still takes is named after the line.
3704
4109
  - `fill(locator: Locator, text: string, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3705
4110
  - `press(locator: Locator, key: string, options?: { delay?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3706
4111
  - `selectOption(locator: Locator, value: string | string[] | { value?: string; label?: string; index?: number }, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3707
- - `dragAndDrop(source: Locator, target: Locator, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
4112
+ - `dragAndDrop(source: Locator, target: Locator, options?: { force?: boolean; sourcePosition?: { x?: number; y?: number }; targetPosition?: { x?: number; y?: number }; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
4113
+ - `dragBy(source: Locator, dx: number, dy: number, options?: { force?: boolean; sourcePosition?: { x?: number; y?: number }; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
4114
+ - `tap(locator: Locator, options?: { position?: any; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
4115
+ - `longPress(locator: Locator, options?: { position?: any; durationMs?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
4116
+ - `swipe(locator: Locator, dx: number, dy: number, options?: { sourcePosition?: { x?: number; y?: number }; durationMs?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3708
4117
  - `uploadFile(input: Locator, files: any): void`
3709
4118
  - `clipboardPaste(target: Locator, text: string): void`
3710
4119
 
@@ -3714,7 +4123,7 @@ per option; an older spelling it still takes is named after the line.
3714
4123
  - `waitForText(text: string | RegExp, options?: { state?: string; exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3715
4124
  - `waitForCount(locator: Locator, count: number, options?: { exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3716
4125
  - `waitForAnimations(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3717
- - `pause(ms: number): void`
4126
+ - `pause(ms: number, reason?: string): void`
3718
4127
  - `waitForDownload(options?: { timeoutMs?: number; name?: string | RegExp }): any`
3719
4128
  - `clockFreeze(iso: string): void`
3720
4129
  - `clockTick(ms: number): void`
@@ -3727,12 +4136,14 @@ per option; an older spelling it still takes is named after the line.
3727
4136
  - `assertAttribute(locator: Locator, name: string, value: string | RegExp, options?: { exact?: boolean; not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3728
4137
  - `assertVisible(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3729
4138
  - `assertHidden(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
4139
+ - `assertInViewport(locator: Locator, options?: { ratio?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
4140
+ - `assertNoFocusZoom(scopeOrOptions?: Locator | { minFontPx?: number; timeoutMs?: number }, options?: { minFontPx?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3730
4141
  - `assertNeverAppears(locator: Locator, options: { withinMs?: number }): void`
3731
4142
  - `assertValue(locator: Locator, value: string, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3732
4143
  - `assertCount(locator: Locator, count: number, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3733
4144
  - `assertUrl(pattern: string | RegExp, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3734
4145
  - `assertJudge(locator: Locator, rubric: string): void`
3735
- - `assertScreenshot(nameOrLocator: any, nameOrOptions?: any, options?: { maxDiffRatio?: number; threshold?: number; mask?: unknown[]; ignore?: unknown[]; fullPage?: boolean }): void`
4146
+ - `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
4147
  - `assertEqual(actual: any, expected: any): void`
3737
4148
  - `assertTrue(condition: boolean, message?: string): void`
3738
4149
  - `assertSchema(value: any, schema: any): void`
@@ -3792,7 +4203,8 @@ per option; an older spelling it still takes is named after the line.
3792
4203
  - `setLocalStorage(key: string, value: string): void`
3793
4204
  - `getLocalStorage(key: string): string`
3794
4205
  - `setCookie(name: string, value: string, options?: { domain?: string; path?: string; expires?: number; httpOnly?: boolean; secure?: boolean; sameSite?: string }): void`
3795
- - `getCookie(name: string): string`
4206
+ - `getCookie(name: string, options?: { page?: any }): string`
4207
+ - `hasCookie(name: string, options?: { page?: any }): boolean`
3796
4208
 
3797
4209
  **Tabs, frames, contexts, extensions**
3798
4210
 
@@ -3801,10 +4213,10 @@ per option; an older spelling it still takes is named after the line.
3801
4213
  - `bringToFront(index?: number): void`
3802
4214
  - `setPageHidden(hidden: boolean, index?: number): void`
3803
4215
  - `newPage(url?: string): number`
3804
- - `closePage(index?: number): void`
4216
+ - `closePage(indexOrOptions?: number | { beforeUnload?: "leave" | "stay" }, options?: { beforeUnload?: "leave" | "stay" }): any`
3805
4217
  - `setViewport(size: { width?: number; height?: number } | null): void`
3806
4218
  - `emulateMedia(media: { reducedMotion?: "reduce" | "no-preference"; colorScheme?: "light" | "dark" | "no-preference" }): void`
3807
- - `newContext(options?: { profile?: string; cdpEndpoint?: string }): number`
4219
+ - `newContext(options?: { profile?: string; cdpEndpoint?: string; headers?: any; viewport?: { width?: number; height?: number; deviceScaleFactor?: number } }): number`
3808
4220
  - `setContext(index: number): void`
3809
4221
  - `enterFrame(frame: Locator): void`
3810
4222
  - `exitFrame(): void`
@@ -3820,8 +4232,8 @@ per option; an older spelling it still takes is named after the line.
3820
4232
  **Data, files, network, processes**
3821
4233
 
3822
4234
  - `shell(cmd: string, ...args: unknown[]): any`
3823
- - `waitForFile(path: string, pattern?: any, options?: { timeoutMs?: number }): string`
3824
- - `assertNoFile(path: string, pattern?: any, options?: { withinMs?: number }): void`
4235
+ - `waitForFile(path: string, pattern?: string | RegExp | { timeoutMs?: number }, options?: { timeoutMs?: number }): string`
4236
+ - `assertNoFile(path: string, pattern?: string | RegExp | { withinMs?: number }, options?: { withinMs?: number }): void`
3825
4237
  - `waitForJsonLine(path: string, filter: any, options?: { timeoutMs?: number }): any`
3826
4238
  - `assertNoJsonLine(path: string, filter: any, options?: { withinMs?: number }): void`
3827
4239
  - `readJsonLine(path: string, filter: any): any`
@@ -3836,11 +4248,13 @@ per option; an older spelling it still takes is named after the line.
3836
4248
  - `upload(path: string, options?: { field?: string; fields?: any }): any`
3837
4249
  - `mockRoute(glob: string, response: any): void`
3838
4250
  - `unmockRoute(glob?: string): void`
3839
- - `waitForRequest(glob: string, options?: { timeoutMs?: number }): any`
4251
+ - `waitForRequest(glob: string, options?: { timeoutMs?: number; method?: string }): any`
3840
4252
  - `waitForResponse(glob: string, options?: { status?: number; method?: string; since?: number; timeoutMs?: number }): any`
3841
4253
  - `waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any`
4254
+ - `waitForWebSocketFrame(glob: string, options?: { direction?: any; match?: any; timeoutMs?: number }): any`
4255
+ - `webSocketFrames(glob: string, options?: { direction?: any }): any`
3842
4256
  - `networkEntries(options?: { since?: number; glob?: any }): any`
3843
- - `assertNoRequest(glob: string, options?: { since?: number }): void`
4257
+ - `assertNoRequest(glob: string, options?: { since?: number; method?: string }): void`
3844
4258
  - `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
4259
  - `setTerminal(index: number): void`
3846
4260
  - `closeTerminal(): void`
@@ -3856,6 +4270,8 @@ per option; an older spelling it still takes is named after the line.
3856
4270
  - `terminalScreenshot(name?: string): string`
3857
4271
  - `mcpStart(command: string, args?: string[], options?: { env?: any; cwd?: any; timeoutMs?: number }): any`
3858
4272
  - `mcpCall(server: any, tool: string, args?: any, options?: { timeoutMs?: number; allowError?: any }): any`
4273
+ - `mcpCallStart(server: any, tool: string, args?: any): any`
4274
+ - `mcpCallResult(call: any, options?: { timeoutMs?: number; allowError?: any }): any`
3859
4275
  - `mcpWaitNotification(server: any, method: string, options?: { timeoutMs?: number; match?: any }): any`
3860
4276
  - `mcpStop(server: any): void`
3861
4277
  - `vmAvailable(): boolean`
@@ -3867,7 +4283,7 @@ per option; an older spelling it still takes is named after the line.
3867
4283
 
3868
4284
  **Diagnostics**
3869
4285
 
3870
- - `screenshot(name?: string, options?: { fullPage?: boolean }): string`
4286
+ - `screenshot(name?: string, options?: { fullPage?: boolean; timeoutMs?: number }): string`
3871
4287
  - `note(label: string, value: any): void`
3872
4288
  - `consoleEntries(options?: { level?: any; since?: number }): any`
3873
4289
  - `pageErrors(options?: { since?: number }): any`
@@ -3879,6 +4295,30 @@ per option; an older spelling it still takes is named after the line.
3879
4295
  - `evaluateOnLocator(locator: Locator, jsBody: any, ...args: unknown[]): any`
3880
4296
  <!-- /generated:signatures -->
3881
4297
 
4298
+ ## Versions
4299
+
4300
+ The release of `@unotest/web` that added each function and keyword. A
4301
+ suite runs the DSL of the release it installs: a function newer than that
4302
+ is unknown to its `lint` and its run — install a newer `@unotest/web` in
4303
+ the suite, or write the scenario without it.
4304
+
4305
+ <!-- generated:versions — pnpm build:dsl-types writes this from the contracts -->
4306
+ - **0.57.0** — `assertInViewport`, `assertNoFocusZoom`, `dragBy`, `longPress`, `mcpCallResult`, `mcpCallStart`, `swipe`, `tap`, `waitForWebSocketFrame`, `webSocketFrames`
4307
+ - **0.56.0** — `hasCookie`
4308
+ - **0.55.0** — `waitForResponse`
4309
+ - **0.53.0** — `networkEntries`, `terminalClipboardRead`, `terminalClipboardWrite`, `terminalText`, `terminalWaitForExit`
4310
+ - **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`
4311
+ - **0.49.2** — `isChecked`, `texts`
4312
+ - **0.49.1** — `getImageSize`
4313
+ - **0.47.0** — `computedStyle`, `emulateMedia`, `formatNumber`, `hasAnimation`, `round`, `toNumber`, `waitForAnimations`
4314
+ - **0.46.0** — `assertAttribute`, `assertNoConsoleErrors`, `assertSchema`, `assertTexts`, `consoleEntries`, `env`, `pageErrors`, `setTestTimeout`, `skip`
4315
+ - **0.45.0** — `assertEqual`, `assertNoRequest`, `boundingBox`, `bringToFront`, `closePage`, `evaluateInServiceWorker`, `evaluateOnLocator`, `extensionId`, `mockRoute`, `newPage`, `parseJson`, `readFile`, `readFileInfo`, `readJson`, `textMatches`, `unmockRoute`, `urlParam`, `waitForDownload`, `waitForPage`, `waitForRequest`, `waitForServiceWorker`
4316
+ - **0.44.0** — `assertScreenshot`, `clockFreeze`, `clockRun`, `clockTick`, `newContext`, `setContext`, `setViewport`
4317
+ - **0.31.0** — `note`, `readJsonLine`
4318
+ - **0.22.0** — `assertJudge`
4319
+ - **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`
4320
+ <!-- /generated:versions -->
4321
+
3882
4322
  ---
3883
4323
 
3884
4324
  ## The language — JavaScript
@@ -3890,7 +4330,9 @@ All of it runs — classes, getters, generators, labels, `instanceof`,
3890
4330
  the vocabulary (`click`, `getByRole`, `apiCall`, …). The file is parsed
3891
4331
  first, so a syntax error is reported before anything runs, and `lint`
3892
4332
  reads the same tree; its type check (`ts:*`) reports a name nothing
3893
- declares.
4333
+ declares, and — for a value a JSDoc annotation gives a type of the
4334
+ project (`@import` / `@type`) — a field that type does not have, as an
4335
+ error (types of the project).
3894
4336
 
3895
4337
  Two things set it apart:
3896
4338
 
@@ -4337,3 +4779,412 @@ helpers. A function, parameter or variable of your own named
4337
4779
  linter across `unotest/e2e/**/*.js`. `lint <name>` checks one scenario,
4338
4780
  named as `e2e` takes it (`lint values/string-escapes`); a file or a
4339
4781
  folder works too.
4782
+
4783
+ ---
4784
+
4785
+ ## Linter rules
4786
+
4787
+ `npx @unotest/web lint` reports these, and so does a run before it starts
4788
+ (see Lint before a run).
4789
+ Each rule's severity is set in `unotest.config.*` under `linter.rules`;
4790
+ `// lint-ok: <reason>` on the line silences a warning or an info.
4791
+
4792
+ ### `lint:deep-css`
4793
+
4794
+ CSS selector with `>` or descendant combinators. Brittle to DOM
4795
+ restructure. Prefer role/name/testid.
4796
+
4797
+ ```js
4798
+ locator('div > div.row > .cell:nth-child(3)') // ⚠
4799
+ ```
4800
+
4801
+ ### `lint:xpath`
4802
+
4803
+ XPath selectors. Reasoning is the same as deep-css; XPath is
4804
+ particularly fragile.
4805
+
4806
+ ```js
4807
+ locator('xpath=//div[contains(@class, "row")]/td[3]') // ⚠
4808
+ ```
4809
+
4810
+ ### `lint:obfuscated-class`
4811
+
4812
+ CSS classes that look hashed (`.abc_123`, `.css-1a2b3c`, Tailwind-JIT
4813
+ `.text-[#f00]`). These rename between builds.
4814
+
4815
+ ### `lint:pause-explicit`
4816
+
4817
+ Bare `pause(N)`. A wait the test means takes its reason as the second
4818
+ argument, `pause(N, 'why')`: the reason is printed on the step and the
4819
+ rule leaves it be (see [Waiting a fixed time](#waiting-a-fixed-time)).
4820
+ Silence another justified occurrence with a trailing
4821
+ `// lint-ok: <reason>` on the same line — the reason is required, and the
4822
+ mechanism works for any warning/info rule (legacy helper warnings stop
4823
+ drowning out new ones):
4824
+
4825
+ ```js
4826
+ pause(500); // lint-ok: third-party widget settles its own state with no public signal
4827
+ ```
4828
+
4829
+ ### `lint:function-newer-than-suite`
4830
+
4831
+ **Warning.** A call of a DSL function that this `@unotest/web` knows and
4832
+ the suite's own does not: it was added in a later release than the one
4833
+ installed in `unotest/` (see [Versions](#versions)). The suite's `lint`
4834
+ reports it as an unknown function and its run refuses the call. Upgrade
4835
+ `@unotest/web` in `unotest/` to that release or newer, or write the step
4836
+ without it. Named once per function; off when the installed release
4837
+ cannot be read.
4838
+
4839
+ ### `lint:typed-step-available`
4840
+
4841
+ Info: the scenario does by hand what the language has a typed step for.
4842
+ The message names the function and its section of
4843
+ `node_modules/@unotest/web/guides/dsl-reference.md`:
4844
+
4845
+ | What the scenario does | Typed step |
4846
+ |---|---|
4847
+ | `getComputedStyle(…)` in page code | `computedStyle(locator, property)` |
4848
+ | `naturalWidth` / `naturalHeight` / `complete` in page code | `getImageSize(locator)` |
4849
+ | `pause(N)` followed by `assertHidden(…)` or `assertCount(…, 0)` | `assertNeverAppears(locator, {withinMs})` |
4850
+ | `pause(N)` whose step label or comment speaks of a fade, an animation, a transition or settling | `waitForAnimations(locator)` |
4851
+ | `pause(N)` whose step label or comment speaks of a control being enabled | `waitFor(locator, {state: 'enabled'})` |
4852
+
4853
+ Page code is read when it is a function literal
4854
+ (`evaluateOnLocator(loc, (el) => …)`). The reason of a `pause` is the
4855
+ label of the steps around it and a comment on its line or the line
4856
+ above it. The check after a `pause` may be the first call of the next
4857
+ step.
4858
+
4859
+ `npx @unotest/web upgrade-hints` counts these sites across the whole
4860
+ suite, with page code written as a string (`validator:page-code-string`)
4861
+ as one more row: the count per pattern, the step to write instead, every
4862
+ file and line. The first `e2e` run on a new version prints the counts
4863
+ once.
4864
+
4865
+ ### `lint:disambig-by-index`
4866
+
4867
+ `first()`, `last()`, `nth(N)` on a multi-match without a prior `filter`
4868
+ narrowing. The locator becomes order-dependent.
4869
+
4870
+ ### `lint:evaluate-discouraged`
4871
+
4872
+ `evaluate(js, …)` / `evaluateOnLocator(loc, js, …)` calls. One warning
4873
+ per file, at the first call, with the number of calls. A call under
4874
+ `// lint-ok: <reason>` is left out of the count. Prefer typed getters /
4875
+ actions; reach for `evaluate` only when nothing else fits.
4876
+
4877
+ ### `lint:legacy-layout`
4878
+
4879
+ `unotest.config.*` still sits at the project root (the pre-0.28 layout)
4880
+ where nothing reads it. `lint` does not refuse the way `e2e` /
4881
+ `collection` / `bundle push` do — it only needs the config for rule
4882
+ severities and the helpers dir, so it lints on the defaults and reports
4883
+ the layout once, as a warning that does not fail the run:
4884
+
4885
+ ```
4886
+ unotest.config.mjs:1:1: ⚠ warn [lint:legacy-layout] unotest.config.mjs is at the project root, …
4887
+ ```
4888
+
4889
+ Your `unotest/.env`, `.secrets` and `_helpers/` are read as usual — they
4890
+ never moved. The message carries the migration on one line; the full
4891
+ steps are what `e2e` prints on the same project.
4892
+
4893
+ ### `lint:external-variable-undeclared`
4894
+
4895
+ A bare `UPPER_SNAKE` identifier (`fill(loc, LOGN)`) that no layer file
4896
+ declares. Such a name resolves at run time through `unotest/.env` /
4897
+ `unotest/.secrets` (plus the `.env.<name>` / `.secrets.<name>` overlay of
4898
+ the active environment), and a name that is not there fails only at that
4899
+ statement — after the browser is up and every earlier step has run. The
4900
+ rule reports it before anything starts, with the files it searched:
4901
+
4902
+ ```
4903
+ 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.
4904
+ ```
4905
+
4906
+ - **Without `--env`, every env file declares.** `lint` with no
4907
+ environment chosen stands for no particular run, so a name that any
4908
+ `unotest/.env*` or `unotest/.secrets*` file declares counts —
4909
+ `.env.local`, `.env.staging`, `.secrets.ci` included. The error is left
4910
+ for a name no file declares at all.
4911
+ - **With `--env <name>` (or `UNOTEST_ENV`), `lint` reads what that run
4912
+ reads**: the base files, that environment's overlay and the templates. A
4913
+ name declared only in `.env.prod` is an error for `lint --env dev` and
4914
+ fine for `lint --env prod`.
4915
+ - **The shell is not a declaration.** `lint` reads files only, so a
4916
+ value that CI exports (`export CI_TOKEN=…`) still needs the name in
4917
+ `unotest/.env` — `CI_TOKEN=` with no value declares it and the shell's
4918
+ value wins at run time, as it always did.
4919
+ - **`unotest/.env.example` and `.secrets.example` declare as well.** The
4920
+ real files are gitignored, so in a fresh checkout — a CI runner, a
4921
+ colleague who has just cloned — the twins are the only place the project
4922
+ still says which externals it expects, and a name written there counts as
4923
+ declared. Values are never taken from them: a scenario that READS such a
4924
+ variable still fails at that step, with "no value" instead of "no such
4925
+ name". Credentials belong in `.secrets.example`, the rest in
4926
+ `.env.example`, both without values:
4927
+
4928
+ ```
4929
+ # unotest/.secrets.example
4930
+ LOGIN=
4931
+ PASSWORD=
4932
+ ```
4933
+
4934
+ It is the same list a pushed bundle carries, so a box and the linter
4935
+ agree on what the suite declares.
4936
+ - **A template has to be committed to declare anything.** If git ignores
4937
+ `unotest/.env.example` or `.secrets.example`, `lint` warns: the file
4938
+ exists only in your checkout, and a fresh one does not know its names.
4939
+ `init` writes the lines that keep both templates committable
4940
+ (`!unotest/.env.example`, `!unotest/.secrets.example`, each right after
4941
+ the line that ignores its family); a `.gitignore` from an older `init`
4942
+ gets the missing line on the next `init`.
4943
+ - An **error**, so `// lint-ok:` does not silence it (errors are never
4944
+ baselined). If you must, downgrade it in `unotest.config.*`:
4945
+ `linter: { rules: { 'lint:external-variable-undeclared': 'warn' } }`
4946
+ — then `// lint-ok: <reason>` works per line.
4947
+ - `run_test` (MCP) and `e2e` run the same check before starting the
4948
+ browser, but against what the run will actually resolve — files **and**
4949
+ the ambient shell — so a suite that lives on a shell variable keeps
4950
+ running; only a name that would fail in the scenario anyway is refused
4951
+ up front (`run_test` answers `lint_failed`; `e2e` prints it and goes on,
4952
+ as with every `lint:*` error at its default severity — see
4953
+ Lint before a run).
4954
+ - A name **bound in the file** — assigned, a function parameter, a loop
4955
+ counter — is never flagged, whatever its case.
4956
+
4957
+ ### `lint:external-variable-no-value`
4958
+
4959
+ A bare `UPPER_SNAKE` identifier that only a template declares
4960
+ (`unotest/.env.example`, `.secrets.example`) while nothing gives it a
4961
+ value: no layer file, not the active overlay, not the shell. The name is
4962
+ not misspelt — the value is missing on this machine:
4963
+
4964
+ ```
4965
+ 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.
4966
+ ```
4967
+
4968
+ - Only a run reports it — `run_test` (MCP) and the pre-run check of
4969
+ `e2e`, which see the shell. The `lint` command reads files alone, so a
4970
+ value a CI runner exports is invisible to it; there a template's name
4971
+ counts as declared, and `lint` stays quiet.
4972
+ - A template never gives a value, even a non-empty placeholder
4973
+ (`QA_WHO=lock-1`): the run header names the templates apart from the
4974
+ value files, as `declared names only`.
4975
+
4976
+ ### `lint:external-variable-empty`
4977
+
4978
+ **Warning.** A bare read of a declared `UPPER_SNAKE` name whose value is
4979
+ empty where the run takes it from. An empty value means "not set on this
4980
+ environment", and the run stops at that read — after the browser has
4981
+ started and every earlier step has run. The warning names the file that
4982
+ leaves it empty (or the shell, on a run):
4983
+
4984
+ ```
4985
+ e2e/chat/send.js:12:9: ⚠ warn [lint:external-variable-empty] `QA_LOGIN` is empty in unotest/.env — the run stops here. Give it a value, or read `env("QA_LOGIN", "")` where empty is fine.
4986
+ ```
4987
+
4988
+ - The file that decides is the one the run resolves the name from: the
4989
+ topmost layer that names it, `.secrets*` over `.env*`. `.example`
4990
+ templates hold no values and never count.
4991
+ - With `--env <name>`, `lint` reads that environment's layers. Without
4992
+ it, a name empty in the base files is reported only when no other
4993
+ `unotest/.env*` / `.secrets*` file gives it a value.
4994
+ - The `lint` command reads files only. The check before a run (`run_test`,
4995
+ `e2e`) also sees the shell, so a value exported there keeps it quiet.
4996
+ - `env("QA_LOGIN", "")` is the read for a name that may be empty: it is
4997
+ not reported. A name empty in a `.secrets*` file is told to get its
4998
+ value there — `env()` does not hand out secrets.
4999
+
5000
+ ### `lint:one-test-per-file`
5001
+
5002
+ **Deprecated — reports nothing.** A scenario file may hold several
5003
+ `test_*`, each its own run (see the DSL reference). The id is still
5004
+ accepted in `linter.rules`, so a config that names it keeps loading; it
5005
+ goes away in the next major release — drop it from your config then.
5006
+
5007
+ ### `lint:scenario-in-root`
5008
+
5009
+ **Error.** A scenario file directly in `unotest/e2e/`. Scenarios live in
5010
+ feature folders (`unotest/e2e/checkout/pay.js`). Files whose name starts
5011
+ with `_` (`_template.js`, `_helpers/`) are exempt.
5012
+
5013
+ ### `lint:mustache-in-dsl`
5014
+
5015
+ **Error.** A string literal with `{{NAME}}` in scenario code. In DSL a
5016
+ variable is a bare identifier, `fill(loc, LOGIN)`, which the runtime
5017
+ resolves from `unotest/.env` / `.secrets`. The `{{NAME}}` form is for
5018
+ `explore_step` matcher fields only.
5019
+
5020
+ ### `lint:goto-concat`
5021
+
5022
+ **Warning.** `goto(APP_BASE_URL + '/path')`. `APP_BASE_URL` already
5023
+ reaches the browser as its `baseURL`, so pass the relative path,
5024
+ `goto('/path')`, and the test follows `--env` without edits. Another
5025
+ host's variable is not flagged: `goto(ITR_BASE_URL + '/path')` is how a
5026
+ test reaches a second host.
5027
+
5028
+ ### `lint:get-attribute-null`
5029
+
5030
+ **Warning.** A `getAttribute(…)` read compared with `null` or
5031
+ `undefined` — by `==`, `!=`, `===`, `!==` either way round, or by
5032
+ `assertEqual` — in place or through a variable of the same function.
5033
+ `getAttribute` reads `""` when the attribute is missing, never `null`,
5034
+ so the check cannot see the attribute missing. Check presence with
5035
+ `hasAttribute(loc, name)`:
5036
+
5037
+ ```js
5038
+ assertEqual(getAttribute(locator('body'), 'data-played'), null) // ⚠ fails: got ""
5039
+ assertTrue(!hasAttribute(locator('body'), 'data-played')) // ✓
5040
+ ```
5041
+
5042
+ ### `lint:regex-invalid`
5043
+
5044
+ **Deprecated — reports nothing.** A regex literal that does not
5045
+ compile is refused by the parser, with the reason, before lint runs. The id is still accepted in
5046
+ `linter.rules`, so a config that names it keeps loading; it goes away in
5047
+ the next major release — drop it from your config then.
5048
+
5049
+ ### `lint:echo-assert`
5050
+
5051
+ **Warning.** A `waitForText` (or similar) whose text is part of a value
5052
+ the scenario itself filled. It can go green on your own input echoed in the
5053
+ UI before the real reply arrives. Assert a marker unique to the reply,
5054
+ or count messages and `waitForCount(loc, N + 1)`.
5055
+
5056
+ ### `lint:api-call-file-body`
5057
+
5058
+ **Warning.** An `apiCall` JSON body with a `file` field. It goes out as a
5059
+ string; nothing is attached. For a multipart upload pass `upload(...)`
5060
+ as the body: `apiCall('POST', path, upload('fixtures/doc.pdf', {field:
5061
+ 'file'}))`. If the endpoint really wants a JSON field named `file`, keep
5062
+ it with `// lint-ok: <reason>`.
5063
+
5064
+ ### `lint:lint-ok-missing-reason`
5065
+
5066
+ **Warning.** A bare `// lint-ok` with no reason. It suppresses nothing:
5067
+ write `// lint-ok: <why this is fine>`.
5068
+
5069
+ ### `lint:flow-returns-value`
5070
+
5071
+ **Warning.** A `flow_*` helper that returns a value. `flow_*` is an
5072
+ executable journey the agent may replay; a helper that only reads state
5073
+ belongs under a plain snake_case name.
5074
+
5075
+ ### `lint:env-host-from-base`
5076
+
5077
+ **Error.** An environment overlay is active (`UNOTEST_ENV` / `--env`),
5078
+ but a variable that becomes a HOST still takes its value from the base
5079
+ `unotest/.env`. The run would go to the base environment's host while
5080
+ everything else resolves against the overlay, so it refuses too. A
5081
+ variable is a host in three places:
5082
+
5083
+ - `APP_BASE_URL` — the base URL every relative `goto` resolves against;
5084
+ - the name passed as `apiCall(..., {base: "NAME"})`;
5085
+ - a variable passed as the URL in `goto(NAME)`.
5086
+
5087
+ Ways out:
5088
+
5089
+ - set the name in the overlay's file (`unotest/.env.<name>`);
5090
+ - or list it under `env: { shared: [...] }` in the config when the base
5091
+ value is meant for every environment.
5092
+
5093
+ Not reported:
5094
+
5095
+ - a value the process environment provides — a shell variable, the
5096
+ values a box injects;
5097
+ - a name the base file sets **empty** (`ADMIN_BASE_URL=`) and the overlay
5098
+ does not set. An empty value says the host does not exist in that
5099
+ environment; no overlay value is missing, so there is nothing to share.
5100
+ A test that reads the name bare then fails in the run, on that
5101
+ environment only — see [an empty value is not set](#envname-fallback--string--null).
5102
+
5103
+ The rule has been in place since 0.43.0.
5104
+
5105
+ ### `lint:env-from-base`
5106
+
5107
+ **Warning.** An environment overlay is active (`UNOTEST_ENV` / `--env`),
5108
+ and a bare read of a declared name still takes its value from the shared
5109
+ base `unotest/.env` — the overlay does not set it. Every environment
5110
+ then gets the same value, and nothing in the run would say so:
5111
+
5112
+ ```
5113
+ e2e/chat/send.js:12:9: ⚠ warn [lint:env-from-base] QA_LOGIN comes from unotest/.env, shared by every environment: with environment "dev" active, unotest/.env.dev does not set it. Set it in unotest/.env.dev, or, if every environment is meant to share it, list it in unotest.config.* as env: { shared: ["QA_LOGIN"] }.
5114
+ ```
5115
+
5116
+ Ways out:
5117
+
5118
+ - set the name in the overlay's file (`unotest/.env.<name>`);
5119
+ - or list it under `env: { shared: [...] }` in the config when the value
5120
+ is meant for every environment. The list takes any name.
5121
+
5122
+ Not reported:
5123
+
5124
+ - a value the process environment provides — a shell variable, the
5125
+ values a box injects;
5126
+ - a value from a `.secrets*` file: it shadows the `.env` one;
5127
+ - an empty base value — [`lint:external-variable-empty`](#lintexternal-variable-empty)
5128
+ says that;
5129
+ - a name the same file already uses as a refused host —
5130
+ [`lint:env-host-from-base`](#lintenv-host-from-base) is the error there.
5131
+
5132
+ Without `--env` the rule sleeps. Which file each variable came from is
5133
+ also in the run itself: `run:started` in the journal lists every name
5134
+ with its source (shared `.env`, the environment's file, secrets, shell)
5135
+ — never a value — and the viewer shows it as the run's **Environment**
5136
+ table.
5137
+
5138
+ Since 0.57.0.
5139
+
5140
+ ### `lint:shadows-dsl-function`
5141
+
5142
+ **Warning.** A function or variable of yours with the name of a DSL
5143
+ function. A function of yours is always reported: calls by that name run
5144
+ yours, and the DSL function is out of reach. A variable or a parameter is
5145
+ reported only when the code that sees it calls the DSL function bare by
5146
+ that name — `check(row)` next to a `check` parameter calls the variable.
5147
+ A helper's `check` or `count` parameter that nothing calls draws nothing,
5148
+ and neither does a method call (`list.count()`). Rename it (`my_upload`).
5149
+
5150
+ ### `lint:skip-outside-test`
5151
+
5152
+ **Error.** `skip()` outside a `test_*` body — in a helper, a `flow_*` or
5153
+ at the top level. There it would skip every test that calls it, a
5154
+ decision nobody reading the test can see. Call it in the test it skips:
5155
+ at the top of its body, or inside a step or an `if` block where data an
5156
+ earlier step read decides —
5157
+ `skip('needs LIVE_API', env('LIVE_API') == null)`.
5158
+
5159
+ ### `lint:set-test-timeout-outside-test`
5160
+
5161
+ **Error.** `setTestTimeout()` in a helper, a `flow_*` or at the top level.
5162
+ There it would change the budget of every test that calls it, a number
5163
+ nobody reading the test can see. Call it in the `test_*` body whose budget
5164
+ it sets, at the top: `setTestTimeout(90000)`.
5165
+
5166
+ ### `lint:wait-exceeds-test-budget`
5167
+
5168
+ **Warning.** A literal `timeoutMs` (or `timeout`) in a `test_*` body that is
5169
+ as long as the test's whole budget, or longer: `terminalWaitForText('x',
5170
+ {timeoutMs: 300000})` in a test that has 300000 ms. The budget is the one
5171
+ `setTestTimeout(N)` sets in that test, else the project's (`testTimeoutMs`).
5172
+ A wait like that can only end on the budget of the test, not on its own
5173
+ failure. Make the wait shorter, or raise the budget with `setTestTimeout()`.
5174
+ Only waits spelled as numbers in a `test_*` body are checked; helpers are
5175
+ skipped, since their budget is their caller's.
5176
+
5177
+ ### `lint:filter-unknown-option`, `lint:role-unknown-option`
5178
+
5179
+ **Deprecated — reports nothing.** A key that `filter`, `locator` or
5180
+ `getByRole` does not read is reported by `validator:options`, with the
5181
+ same message the run refuses it with — before the run starts, as every
5182
+ `validator:*` error is: `run_test` answers `lint_failed`, `e2e` stops with
5183
+ `run stopped: N error(s)` (the run would refuse the key too). The id is still accepted in
5184
+ `linter.rules`, so a config that names it keeps loading; it goes away in
5185
+ the next major release — drop it from your config then.
5186
+
5187
+ For `filter({visible: true})` or `filter({hasClass: 'done'})`: a class or
5188
+ an attribute of the element itself is CSS — `count(locator('tr.done'))`.
5189
+ For the enabled button: `getByRole('button', {name: 'Save', disabled:
5190
+ false})`.