@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.
- package/.claude/skills/write-e2e-test/SKILL.md +14 -0
- package/.claude/skills/write-e2e-test-ground/SKILL.md +14 -0
- package/CHANGELOG.md +147 -3
- package/README.md +3 -3
- package/bin/unotest-web.js +13 -0
- package/dist/config/schema.d.ts +15 -15
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +10 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +66 -16
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/v8/scenario-worker.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +2 -2
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +34 -2
- package/dist/inspection/page-inject.js +119 -0
- package/dist/{interfaces-BiGd3BdD.d.ts → interfaces-DDp6Chwx.d.ts} +148 -6
- package/dist/{linter-DIAb0JOB.d.ts → linter-q4UNIeGI.d.ts} +12 -0
- package/dist/mcp/server.js +1 -1
- package/dist/runner/cli.d.ts +1 -1
- package/dist/runner/cli.js +1 -1
- package/dist/runner/init/chrome-probe.js +1 -1
- package/dist/runner/init.js +1 -1
- package/dist/runner/install-chromium.js +1 -1
- package/dist/runner/prepare-fix.js +1 -1
- package/dist/runner/scaffold-workspace.js +1 -1
- package/dist/runner/serve-fixture.js +1 -1
- package/dist/runner/web-runner-adapter.js +1 -1
- package/dist/{scenario-variables-B-ULUTHt.d.ts → scenario-variables-CGexnWK4.d.ts} +18 -0
- package/examples/idioms/wait-enabled.js +6 -3
- package/guides/agent-integration.md +2 -2
- package/guides/dsl-reference.md +388 -17
- package/llms.txt +14 -4
- package/package.json +8 -8
- package/types/unotest-dsl.d.ts +80 -10
package/guides/dsl-reference.md
CHANGED
|
@@ -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.
|
|
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
|
|
874
|
-
|
|
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.
|
|
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.
|
|
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,
|
|
2017
|
+
### `dragAndDrop(from, to, { force?, sourcePosition?, targetPosition?, timeoutMs? })`
|
|
1837
2018
|
|
|
1838
|
-
|
|
1839
|
-
draggables; native HTML5 drag-and-drop (real `DragEvent`) is
|
|
1840
|
-
|
|
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 —
|
|
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(
|
|
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
|