@unotest/web 0.56.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 (35) hide show
  1. package/.claude/skills/write-e2e-test/SKILL.md +14 -0
  2. package/.claude/skills/write-e2e-test-ground/SKILL.md +14 -0
  3. package/CHANGELOG.md +147 -3
  4. package/README.md +3 -3
  5. package/bin/unotest-web.js +13 -0
  6. package/dist/config/schema.d.ts +15 -15
  7. package/dist/config/schema.js +1 -1
  8. package/dist/driver/index.d.ts +10 -2
  9. package/dist/driver/index.js +1 -1
  10. package/dist/dsl/index.d.ts +66 -16
  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 +2 -2
  14. package/dist/dsl/web-dsl-language-service.js +1 -1
  15. package/dist/inspection/page-inject.d.ts +34 -2
  16. package/dist/inspection/page-inject.js +119 -0
  17. package/dist/{interfaces-BiGd3BdD.d.ts → interfaces-DDp6Chwx.d.ts} +148 -6
  18. package/dist/{linter-DIAb0JOB.d.ts → linter-q4UNIeGI.d.ts} +12 -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-B-ULUTHt.d.ts → scenario-variables-CGexnWK4.d.ts} +18 -0
  30. package/examples/idioms/wait-enabled.js +6 -3
  31. package/guides/agent-integration.md +2 -2
  32. package/guides/dsl-reference.md +388 -17
  33. package/llms.txt +14 -4
  34. package/package.json +8 -8
  35. package/types/unotest-dsl.d.ts +80 -10
@@ -454,6 +454,34 @@ selectOption(getByLabel('Folder'), {index: 0})
454
454
  scrollIntoView(getByText('Footer'))
455
455
  ```
456
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
+
457
485
  ---
458
486
 
459
487
  ## Assertions
@@ -528,6 +556,63 @@ assertVisible(getByTestId('toast'))
528
556
  assertHidden(getByTestId('spinner'), {timeoutMs: 10000})
529
557
  ```
530
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
+
531
616
  ### `assertNeverAppears(loc, options)`
532
617
 
533
618
  Negative window assertion: watch for `withinMs` (required) and **fail
@@ -673,6 +758,12 @@ assertSchema(req.postDataJson, schema);
673
758
  - The schema must be an object: pass what `readJson` returned, not the
674
759
  file name.
675
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
+
676
767
  ### `skip(reason, condition?)`
677
768
 
678
769
  End the test as **skipped**: it does not apply here — a live-only check
@@ -852,7 +943,14 @@ so in one warning line, once.
852
943
  **The baseline** lives next to the scenario:
853
944
  `unotest/e2e/<scenario path without .js>.screenshots/<name>.png` (the
854
945
  name is lower-cased and dashed, as for `screenshot()`), and travels with
855
- 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
856
954
  scenario (`"Checkout Page"` and `"checkout/page"`) are refused at the
857
955
  second one; the same name twice in one run of `--update-screenshots` is
858
956
  written twice, and the runner says that the last one wins. A symlink on
@@ -870,8 +968,9 @@ shared directory of the suite); one that leads outside is refused.
870
968
  check nothing.
871
969
  - **Accept the current page** — `npx @unotest/web e2e <name>
872
970
  --update-screenshots` (MCP: `run_test {updateScreenshots: true}`)
873
- writes every snapshot of the run as its baseline; the asserts pass and
874
- 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.
875
974
  - **It failed** — the run keeps three pictures: `expected`, `actual` and
876
975
  `diff` (differing pixels red over a greyed-out snapshot, masked areas
877
976
  grey). The viewer shows them side by side on the failed step; the
@@ -1366,14 +1465,14 @@ path resolves against the base URL, as in `goto`. Without one the tab
1366
1465
  stays blank. A tab `newPage` opened is the scenario's own: `waitForPage`
1367
1466
  never returns it.
1368
1467
 
1369
- ### `closePage(index?)`
1468
+ ### `closePage(index?, { beforeUnload? })` → `{asked, closed}`
1370
1469
 
1371
1470
  Close tab `index`; no index: the active tab. Closing the active tab
1372
1471
  makes the tab that was active before it active again (and brings it to
1373
1472
  front); if that one is closed too, the tab at the index below. Closing
1374
1473
  another tab leaves the steps where they are — later tabs move down one
1375
- index. The only open tab cannot be closed: the step fails with
1376
- `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`.
1377
1476
 
1378
1477
  ```js
1379
1478
  newPage('/settings'); // tab 1, active
@@ -1381,6 +1480,30 @@ assertUrl('/settings');
1381
1480
  closePage(); // back on tab 0
1382
1481
  ```
1383
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
+
1384
1507
  ### `waitForPage(options?)` → `number`
1385
1508
 
1386
1509
  Wait for a tab the scenario has not received yet, make it active and
@@ -1404,7 +1527,7 @@ assertUrl('/report');
1404
1527
  setPage(0);
1405
1528
  ```
1406
1529
 
1407
- ### `newContext({profile?, cdpEndpoint?})` → `number` / `setContext(index)`
1530
+ ### `newContext({profile?, cdpEndpoint?, headers?, viewport?})` → `number` / `setContext(index)`
1408
1531
 
1409
1532
  A second browser context: another client of the same app, with its own
1410
1533
  cookies, localStorage, sessionStorage and tabs. For anything that takes
@@ -1476,6 +1599,59 @@ own.
1476
1599
  — your function wins a call by that name, so the DSL's is out of reach
1477
1600
  until you rename it.
1478
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
+
1479
1655
  #### Two devices: `newContext({profile: '<dir>'})`
1480
1656
 
1481
1657
  `{profile: '<dir>'}` opens the context on a persistent browser profile of
@@ -1567,7 +1743,9 @@ setViewport({width: 1280, height: 720});
1567
1743
  Both fields are required. Anything else is refused on that line,
1568
1744
  `deviceScaleFactor` included: the scale is fixed when the browser opens,
1569
1745
  and changing it would need a new browser context — the page under test
1570
- 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).
1571
1749
 
1572
1750
  `setViewport(null)` runs the test on the real window — but only before
1573
1751
  the test does anything in its browser: the first navigation, `mockRoute`,
@@ -1661,6 +1839,9 @@ Where the window's size and scale come from, first match wins:
1661
1839
  replace the config's window for that context. `explore_start` with a
1662
1840
  window while a context is already open is refused — call
1663
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.
1664
1845
  2. **The collection.** `viewport:` in `unotest/e2e/_collections/<name>.yaml`
1665
1846
  applies to every scenario that collection runs; the same scenario run
1666
1847
  on its own keeps the config's window. `null` is the real window,
@@ -1833,16 +2014,43 @@ assertEqual(getCookie('theme', {page: true}), 'dark');
1833
2014
 
1834
2015
  ## Edge actions
1835
2016
 
1836
- ### `dragAndDrop(from, to, options?)`
2017
+ ### `dragAndDrop(from, to, { force?, sourcePosition?, targetPosition?, timeoutMs? })`
1837
2018
 
1838
- Uses Playwright `loc.dragTo()` — mouse-event drag. Works for most
1839
- draggables; native HTML5 drag-and-drop (real `DragEvent`) is a known
1840
- 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.
1841
2028
 
1842
2029
  ```js
1843
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 } })
1844
2033
  ```
1845
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
+
1846
2054
  ### `uploadFile(loc, paths)`
1847
2055
 
1848
2056
  `paths` can be a single string or an array.
@@ -2383,6 +2591,11 @@ file the overlay was supposed to replace. The same rule covers
2383
2591
  `APP_BASE_URL` (the base every relative `goto` resolves against) and a
2384
2592
  variable used as the URL in `goto(NAME)`.
2385
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
+
2386
2599
  **Per-call timeout — `{timeoutMs}`.** A call has no time limit of its
2387
2600
  own: it waits as long as the step and the test allow. An endpoint that
2388
2601
  must answer in a known time — or a slow one you would rather fail fast
@@ -2480,6 +2693,29 @@ server sent it. These fail the step, quoting the last MCP message:
2480
2693
  - a result marked `isError` — pass `{allowError: true}` to get it back
2481
2694
  and check it yourself.
2482
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
+
2483
2719
  ### `mcpWaitNotification(server, method, options?)` → params
2484
2720
 
2485
2721
  Waits for a notification of `method` and returns its `params`.
@@ -2755,6 +2991,36 @@ assertTrue(socket.url.endsWith('/ws'));
2755
2991
  - A timeout names the mask and the sockets the page did open.
2756
2992
  - `{timeoutMs}` — default 20 000.
2757
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
+
2758
3024
  ### `assertNoRequest(glob, options?)`
2759
3025
 
2760
3026
  Fails if the recording abort at `glob` stopped any request, naming
@@ -2940,6 +3206,12 @@ the same way.
2940
3206
  does for browser contexts; indices stay put when a window closes.
2941
3207
  `closeTerminal` closes the active one.
2942
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
+
2943
3215
  ### `terminalType(text)` / `terminalPress(key)`
2944
3216
 
2945
3217
  `terminalType` puts the text in as a paste, line by line, and a line
@@ -3195,7 +3467,10 @@ Read page properties directly into a local variable.
3195
3467
  const href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
3196
3468
  ```
3197
3469
 
3198
- 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
3199
3474
  boolean attributes**: `<button disabled>` and a button without the
3200
3475
  attribute both read `""`. For those use `isDisabled(loc)` /
3201
3476
  `hasAttribute(loc, name)`.
@@ -3643,6 +3918,16 @@ assertTrue(consoleEntries({ level: ['warn', 'error'], since: before }).length ==
3643
3918
  `console.json` holds the lines of every browser context, each with its
3644
3919
  `contextIndex`, the last 500 by time.
3645
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
+
3646
3931
  ### `networkEntries(options?)` → `[{ url, method, status, ok, headers, requestJson, responseJson, responseText, at }]`
3647
3932
 
3648
3933
  What the active page requested and was answered, oldest first. Like the
@@ -3824,7 +4109,11 @@ per option; an older spelling it still takes is named after the line.
3824
4109
  - `fill(locator: Locator, text: string, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3825
4110
  - `press(locator: Locator, key: string, options?: { delay?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3826
4111
  - `selectOption(locator: Locator, value: string | string[] | { value?: string; label?: string; index?: number }, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3827
- - `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)
3828
4117
  - `uploadFile(input: Locator, files: any): void`
3829
4118
  - `clipboardPaste(target: Locator, text: string): void`
3830
4119
 
@@ -3847,6 +4136,8 @@ per option; an older spelling it still takes is named after the line.
3847
4136
  - `assertAttribute(locator: Locator, name: string, value: string | RegExp, options?: { exact?: boolean; not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3848
4137
  - `assertVisible(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3849
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)
3850
4141
  - `assertNeverAppears(locator: Locator, options: { withinMs?: number }): void`
3851
4142
  - `assertValue(locator: Locator, value: string, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
3852
4143
  - `assertCount(locator: Locator, count: number, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
@@ -3922,10 +4213,10 @@ per option; an older spelling it still takes is named after the line.
3922
4213
  - `bringToFront(index?: number): void`
3923
4214
  - `setPageHidden(hidden: boolean, index?: number): void`
3924
4215
  - `newPage(url?: string): number`
3925
- - `closePage(index?: number): void`
4216
+ - `closePage(indexOrOptions?: number | { beforeUnload?: "leave" | "stay" }, options?: { beforeUnload?: "leave" | "stay" }): any`
3926
4217
  - `setViewport(size: { width?: number; height?: number } | null): void`
3927
4218
  - `emulateMedia(media: { reducedMotion?: "reduce" | "no-preference"; colorScheme?: "light" | "dark" | "no-preference" }): void`
3928
- - `newContext(options?: { profile?: string; cdpEndpoint?: string }): number`
4219
+ - `newContext(options?: { profile?: string; cdpEndpoint?: string; headers?: any; viewport?: { width?: number; height?: number; deviceScaleFactor?: number } }): number`
3929
4220
  - `setContext(index: number): void`
3930
4221
  - `enterFrame(frame: Locator): void`
3931
4222
  - `exitFrame(): void`
@@ -3960,6 +4251,8 @@ per option; an older spelling it still takes is named after the line.
3960
4251
  - `waitForRequest(glob: string, options?: { timeoutMs?: number; method?: string }): any`
3961
4252
  - `waitForResponse(glob: string, options?: { status?: number; method?: string; since?: number; timeoutMs?: number }): any`
3962
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`
3963
4256
  - `networkEntries(options?: { since?: number; glob?: any }): any`
3964
4257
  - `assertNoRequest(glob: string, options?: { since?: number; method?: string }): void`
3965
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`
@@ -3977,6 +4270,8 @@ per option; an older spelling it still takes is named after the line.
3977
4270
  - `terminalScreenshot(name?: string): string`
3978
4271
  - `mcpStart(command: string, args?: string[], options?: { env?: any; cwd?: any; timeoutMs?: number }): any`
3979
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`
3980
4275
  - `mcpWaitNotification(server: any, method: string, options?: { timeoutMs?: number; match?: any }): any`
3981
4276
  - `mcpStop(server: any): void`
3982
4277
  - `vmAvailable(): boolean`
@@ -4008,6 +4303,7 @@ is unknown to its `lint` and its run — install a newer `@unotest/web` in
4008
4303
  the suite, or write the scenario without it.
4009
4304
 
4010
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`
4011
4307
  - **0.56.0** — `hasCookie`
4012
4308
  - **0.55.0** — `waitForResponse`
4013
4309
  - **0.53.0** — `networkEntries`, `terminalClipboardRead`, `terminalClipboardWrite`, `terminalText`, `terminalWaitForExit`
@@ -4034,7 +4330,9 @@ All of it runs — classes, getters, generators, labels, `instanceof`,
4034
4330
  the vocabulary (`click`, `getByRole`, `apiCall`, …). The file is parsed
4035
4331
  first, so a syntax error is reported before anything runs, and `lint`
4036
4332
  reads the same tree; its type check (`ts:*`) reports a name nothing
4037
- 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).
4038
4336
 
4039
4337
  Two things set it apart:
4040
4338
 
@@ -4675,6 +4973,30 @@ qa/lock.js:3:9: ✗ error [lint:external-variable-no-value] `QA_WHO` is declared
4675
4973
  (`QA_WHO=lock-1`): the run header names the templates apart from the
4676
4974
  value files, as `declared names only`.
4677
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
+
4678
5000
  ### `lint:one-test-per-file`
4679
5001
 
4680
5002
  **Deprecated — reports nothing.** A scenario file may hold several
@@ -4703,6 +5025,20 @@ reaches the browser as its `baseURL`, so pass the relative path,
4703
5025
  host's variable is not flagged: `goto(ITR_BASE_URL + '/path')` is how a
4704
5026
  test reaches a second host.
4705
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
+
4706
5042
  ### `lint:regex-invalid`
4707
5043
 
4708
5044
  **Deprecated — reports nothing.** A regex literal that does not
@@ -4766,6 +5102,41 @@ Not reported:
4766
5102
 
4767
5103
  The rule has been in place since 0.43.0.
4768
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
+
4769
5140
  ### `lint:shadows-dsl-function`
4770
5141
 
4771
5142
  **Warning.** A function or variable of yours with the name of a DSL