@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.
- package/.claude/skills/write-e2e-test/SKILL.md +44 -7
- package/.claude/skills/write-e2e-test-ground/SKILL.md +20 -5
- package/CHANGELOG.md +250 -3
- package/README.md +7 -6
- package/bin/unotest-web.js +13 -0
- package/dist/config/schema.d.ts +29 -23
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +16 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +74 -94
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/v8/scenario-worker.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +30 -3
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +63 -7
- package/dist/inspection/page-inject.js +199 -19
- package/dist/{interfaces-CNvyInrY.d.ts → interfaces-DDp6Chwx.d.ts} +167 -10
- package/dist/{linter-BpaIstU3.d.ts → linter-q4UNIeGI.d.ts} +20 -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-CGexnWK4.d.ts +106 -0
- package/examples/idioms/README.md +16 -0
- package/examples/idioms/animations-list.js +24 -0
- package/examples/idioms/api-call-timeout.js +14 -0
- package/examples/idioms/background-tab.js +24 -0
- package/examples/idioms/clipboard-paste.js +25 -0
- package/examples/idioms/computed-style.js +21 -0
- package/examples/idioms/image-size.js +20 -0
- package/examples/idioms/never-appears.js +20 -0
- package/examples/idioms/never-condition.js +24 -0
- package/examples/idioms/page-code-function.js +18 -0
- package/examples/idioms/select-by-label.js +22 -0
- package/examples/idioms/wait-enabled.js +24 -0
- package/examples/idioms/wait-for-animations.js +16 -0
- package/examples/idioms/wait-until-value.js +32 -0
- package/guides/agent-integration.md +28 -4
- package/guides/dsl-reference.md +896 -45
- package/llms.txt +38 -9
- package/package.json +9 -8
- package/types/unotest-dsl.d.ts +107 -30
- package/types/unotest-lib.d.ts +5 -3
package/guides/dsl-reference.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
status: stable
|
|
3
|
-
last_updated: 2026-10-
|
|
3
|
+
last_updated: 2026-10-25
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# DSL Reference
|
|
@@ -125,18 +125,17 @@ it consists of:
|
|
|
125
125
|
CHECKING stays off (`checkJs: false`) on purpose: diagnostics come from
|
|
126
126
|
the DSL validator (`npx @unotest/web lint`), the editor only gains
|
|
127
127
|
completion, hover docs, signature help and locator-chain resolution.
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
`Date`,
|
|
131
|
-
|
|
132
|
-
`
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
read as iterators, as they run: spread one for array methods.
|
|
128
|
+
Its standard library is JavaScript's own (`"lib": ["es2023", "dom"]`),
|
|
129
|
+
the one lint's type layer checks against: a scenario runs as plain
|
|
130
|
+
JavaScript, so `Date`, classes and `Map.prototype.keys` complete, and
|
|
131
|
+
the DOM is there for the page code handed to `evaluate`. A jsconfig an
|
|
132
|
+
earlier `init` wrote (`noLib` with the cut-down `unotest-lib.d.ts`)
|
|
133
|
+
is outdated; `lint` and runs say so in one line, and
|
|
134
|
+
`npx @unotest/web types` brings it up to date. One you edited by hand
|
|
135
|
+
is left as it is, with a line that says what to change.
|
|
136
|
+
- `node_modules/@unotest/web/types/unotest-lib.d.ts` — deprecated, no
|
|
137
|
+
longer updated: kept for one release so an old jsconfig that names it
|
|
138
|
+
keeps its globals until `types` rewrites it.
|
|
140
139
|
- `node_modules/@unotest/web/types/unotest-dsl.d.ts` — ambient
|
|
141
140
|
declarations for every DSL function, generated from the same contracts
|
|
142
141
|
the validator uses and shipped with the package, so it always matches
|
|
@@ -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.
|
|
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
|
|
875
|
-
|
|
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
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
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.
|
|
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.
|
|
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?)`
|
|
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,
|
|
2017
|
+
### `dragAndDrop(from, to, { force?, sourcePosition?, targetPosition?, timeoutMs? })`
|
|
1777
2018
|
|
|
1778
|
-
|
|
1779
|
-
draggables; native HTML5 drag-and-drop (real `DragEvent`) is
|
|
1780
|
-
|
|
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 —
|
|
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?:
|
|
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(
|
|
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?:
|
|
3824
|
-
- `assertNoFile(path: string, pattern?:
|
|
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})`.
|