@unotest/web 0.49.2 → 0.51.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 +6 -7
- package/.claude/skills/write-e2e-test-ground/SKILL.md +6 -7
- package/CHANGELOG.md +349 -3
- package/README.md +25 -0
- package/dist/config/schema.d.ts +40 -18
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +13 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +388 -28
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +18 -6
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +34 -7
- package/dist/inspection/page-inject.js +69 -4
- package/dist/{interfaces-mlRtu8mL.d.ts → interfaces-BSGmF_Tv.d.ts} +99 -3
- package/dist/{linter-RrjB1n9R.d.ts → linter-CYRlmOLy.d.ts} +32 -5
- 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/guides/agent-integration.md +25 -2
- package/guides/dsl-reference.md +1139 -293
- package/llms.txt +223 -0
- package/package.json +9 -8
- package/types/unotest-dsl.d.ts +350 -106
- package/types/unotest-lib.d.ts +1289 -0
package/guides/dsl-reference.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
status: stable
|
|
3
|
-
last_updated: 2026-
|
|
3
|
+
last_updated: 2026-10-13
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# DSL Reference
|
|
@@ -46,7 +46,8 @@ step.soft("label", () => { … });
|
|
|
46
46
|
step.soft("label", {tag: <expr>}, () => { … });
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
- **`label`** is
|
|
49
|
+
- **`label`** is text written out — a string, or a template without
|
|
50
|
+
`${…}` — the intent a human reads. A changing value goes into `tag`.
|
|
50
51
|
- **`{tag: <expr>}`** names the case a data-driven step is on: any
|
|
51
52
|
expression (`q.id`, `textJoin(['q-', i])`), evaluated when the block
|
|
52
53
|
starts. It rides on every event of the block (`Question [q17]` in the
|
|
@@ -64,7 +65,8 @@ step.soft("label", {tag: <expr>}, () => { … });
|
|
|
64
65
|
✗ soft step "Question" [q42]: …
|
|
65
66
|
```
|
|
66
67
|
|
|
67
|
-
`return`
|
|
68
|
+
A `return` leaves the soft step's callback, as in any step; `break` /
|
|
69
|
+
`continue` do not cross a callback, as in JavaScript. A
|
|
68
70
|
hard failure after soft ones ends the run with *that* error; the soft
|
|
69
71
|
list is still attached. The failure bundle shows the page at the moment
|
|
70
72
|
of the **first** soft failure (`failure.json` carries `soft: true` and
|
|
@@ -95,7 +97,7 @@ function test_control_questions() {
|
|
|
95
97
|
step.soft("Question", {tag: q.id}, () => {
|
|
96
98
|
fill(getByRole('textbox', {name: 'Message'}), q.text);
|
|
97
99
|
press(getByRole('textbox', {name: 'Message'}), 'Enter');
|
|
98
|
-
answer =
|
|
100
|
+
answer = getByTestId('last-answer');
|
|
99
101
|
screenshot(q.id);
|
|
100
102
|
assertJudge(answer, q.rubric);
|
|
101
103
|
});
|
|
@@ -117,12 +119,24 @@ wires the fix; on an existing project, or a fresh checkout,
|
|
|
117
119
|
`npx @unotest/web types` does. A run never writes the editor config. What
|
|
118
120
|
it consists of:
|
|
119
121
|
|
|
120
|
-
- `unotest/jsconfig.json` — points the IDE at the
|
|
122
|
+
- `unotest/jsconfig.json` — points the IDE at the declaration files
|
|
121
123
|
below. Written by `init` (which also adds it to `.gitignore`) and by
|
|
122
124
|
`types` when missing; never rewritten silently. Type
|
|
123
125
|
CHECKING stays off (`checkJs: false`) on purpose: diagnostics come from
|
|
124
126
|
the DSL validator (`npx @unotest/web lint`), the editor only gains
|
|
125
127
|
completion, hover docs, signature help and locator-chain resolution.
|
|
128
|
+
It sets `noLib: true`: the editor's standard library is the scenario
|
|
129
|
+
library alone, so it completes `Math.round` and `s.trim()` but not
|
|
130
|
+
`Date`, `setTimeout` or `document` — what lint would refuse. A
|
|
131
|
+
jsconfig an earlier `init` wrote reads the full JavaScript library;
|
|
132
|
+
`lint` and runs say so in one line, and `npx @unotest/web types`
|
|
133
|
+
brings it up to date. One you edited by hand is left as it is, with a
|
|
134
|
+
line that says what to change.
|
|
135
|
+
- `node_modules/@unotest/web/types/unotest-lib.d.ts` — the scenario
|
|
136
|
+
library (`Math`, `JSON`, `Object`, `Map`, `Set`, the string, number and
|
|
137
|
+
array methods), cut from TypeScript's own declarations to exactly what
|
|
138
|
+
a scenario has. `keys()`, `values()` and `entries()` of a Map or a Set
|
|
139
|
+
read as arrays, as they run.
|
|
126
140
|
- `node_modules/@unotest/web/types/unotest-dsl.d.ts` — ambient
|
|
127
141
|
declarations for every DSL function, generated from the same contracts
|
|
128
142
|
the validator uses and shipped with the package, so it always matches
|
|
@@ -164,11 +178,14 @@ Two squiggle sources remain that typings cannot fix, both cosmetic:
|
|
|
164
178
|
- [Storage](#storage) — localStorage / cookies
|
|
165
179
|
- [Edge actions](#edge-actions) — drag, upload, paste
|
|
166
180
|
- [Sandbox primitives](#sandbox-primitives) — shell / db / HTTP / files
|
|
181
|
+
- [MCP client](#mcp-client) — start an MCP server, call it, wait for it
|
|
167
182
|
- [Network mocks](#network-mocks) — what the page's requests get
|
|
183
|
+
- [Terminal (macOS)](#terminal-macos) — a real Terminal.app / iTerm2 window
|
|
168
184
|
- [Typed getters](#typed-getters) — page properties
|
|
169
185
|
- [Generators](#generators) — random fixture data + time
|
|
170
186
|
- [`evaluate`](#evaluate) — escape hatch into the page
|
|
171
187
|
- [Logging](#logging)
|
|
188
|
+
- [Signatures](#signatures) — every function with the types it takes
|
|
172
189
|
|
|
173
190
|
---
|
|
174
191
|
|
|
@@ -181,28 +198,21 @@ hasNotText})`) accept either:
|
|
|
181
198
|
|
|
182
199
|
- A string literal — matched as substring by default, exactly with
|
|
183
200
|
`{exact: true}`.
|
|
184
|
-
- A regex literal `/pattern/flags` —
|
|
201
|
+
- A regex literal `/pattern/flags` — a JavaScript RegExp, any flag
|
|
202
|
+
included: see [Regex literals](#regex-literals).
|
|
185
203
|
|
|
186
204
|
```js
|
|
187
205
|
getByRole("link", {name: /^Sets/})
|
|
188
206
|
getByText(/Items \d+/i)
|
|
189
|
-
filter({hasText: /done/i})
|
|
207
|
+
getByRole('row').filter({hasText: /done/i})
|
|
190
208
|
```
|
|
191
209
|
|
|
192
|
-
**Supported regex flags:** `g`, `i`, `m`. Post-ES5 flags (`s u y d v`)
|
|
193
|
-
are rejected at parse time with a message naming the spec they came
|
|
194
|
-
from — write a separate plan if you need them
|
|
195
|
-
(`docs/dsl/regex-literal-es5.md` out-of-scope section).
|
|
196
|
-
|
|
197
|
-
**Escape rules:** standard ECMA-262 5.1 grammar — `\` introduces
|
|
198
|
-
escape sequences, `[...]` is a character class where `/` does not
|
|
199
|
-
close the literal. No literal line breaks inside a regex body.
|
|
200
|
-
|
|
201
210
|
## The `timeout` option
|
|
202
211
|
|
|
203
212
|
Actions, navigation, waits and assertions take their time limit in
|
|
204
|
-
milliseconds as `
|
|
205
|
-
|
|
213
|
+
milliseconds as `timeoutMs`. Where a signature lists `timeoutMs?`, the
|
|
214
|
+
older spelling `timeout` is accepted as an alias for it; giving both in
|
|
215
|
+
one call is refused. The examples below use `timeoutMs`.
|
|
206
216
|
|
|
207
217
|
An option an action, a navigation, a wait or an assertion does not take
|
|
208
218
|
is refused with the ones it does, so a misspelled `{timout: 5000}` fails at once
|
|
@@ -237,8 +247,8 @@ The other options narrow by ARIA state, as Playwright's `getByRole` does:
|
|
|
237
247
|
`checked`, `disabled`, `expanded`, `pressed`, `selected` (true / false),
|
|
238
248
|
`level` (a heading level from 1) and `includeHidden` (true — match
|
|
239
249
|
elements hidden from the accessibility tree too). Any other key is
|
|
240
|
-
refused, at lint time (`
|
|
241
|
-
|
|
250
|
+
refused, at lint time (`validator:options`) and at run time — it would
|
|
251
|
+
otherwise match without it.
|
|
242
252
|
|
|
243
253
|
```js
|
|
244
254
|
getByRole('button', {name: 'Save'})
|
|
@@ -307,8 +317,8 @@ Each requires a locator as the receiver / first argument.
|
|
|
307
317
|
### `filter(options)`
|
|
308
318
|
|
|
309
319
|
Narrow down a locator. `hasText`, `hasNotText`, `has`, `hasNot` — any
|
|
310
|
-
other key is refused, at lint time (`
|
|
311
|
-
|
|
320
|
+
other key is refused, at lint time (`validator:options`) and at run
|
|
321
|
+
time. A class or an attribute of the element itself goes into a CSS
|
|
312
322
|
`locator(...)` instead.
|
|
313
323
|
|
|
314
324
|
```js
|
|
@@ -364,7 +374,7 @@ click(getByRole('button', {name: 'Save'}))
|
|
|
364
374
|
click(getByText('Submit'), {force: true})
|
|
365
375
|
```
|
|
366
376
|
|
|
367
|
-
**Options:** `force?`, `
|
|
377
|
+
**Options:** `force?`, `timeoutMs?`, `position?`, `modifiers?`.
|
|
368
378
|
|
|
369
379
|
### `doubleClick(loc, options?)`
|
|
370
380
|
|
|
@@ -393,7 +403,7 @@ press(getByLabel('Body'), 'Control+A')
|
|
|
393
403
|
|
|
394
404
|
Idempotent — no click if already in the target state. Otherwise one
|
|
395
405
|
click, then a wait until the element reads checked (unchecked) within
|
|
396
|
-
the action timeout (`options.
|
|
406
|
+
the action timeout (`options.timeoutMs`, else the config default). A
|
|
397
407
|
controlled switch the app flips a beat after the click — once the server
|
|
398
408
|
confirms — passes; one that never flips fails, naming the state it
|
|
399
409
|
wanted and the last one it saw. Works on native checkboxes and radios
|
|
@@ -403,7 +413,7 @@ wrapped input). Any other element is refused — use `click` for it.
|
|
|
403
413
|
|
|
404
414
|
```js
|
|
405
415
|
check(getByRole('checkbox', {name: 'Subscribe'}))
|
|
406
|
-
uncheck(getByRole('switch', {name: 'Notifications'}), {
|
|
416
|
+
uncheck(getByRole('switch', {name: 'Notifications'}), {timeoutMs: 5000})
|
|
407
417
|
```
|
|
408
418
|
|
|
409
419
|
### `hover(loc, options?)`
|
|
@@ -415,17 +425,28 @@ hover(getByRole('button', {name: 'Help'}))
|
|
|
415
425
|
hover(getByTestId('message-42'), {position: {x: 24, y: 8}})
|
|
416
426
|
```
|
|
417
427
|
|
|
418
|
-
**Options:** `force?`, `
|
|
428
|
+
**Options:** `force?`, `timeoutMs?`, `position?` (no `modifiers` — that
|
|
419
429
|
is a `click` option).
|
|
420
430
|
|
|
421
431
|
### `selectOption(loc, value, options?)`
|
|
422
432
|
|
|
423
|
-
Native `<select>` only. `value`
|
|
424
|
-
|
|
433
|
+
Native `<select>` only. `value` picks the option:
|
|
434
|
+
|
|
435
|
+
- by its value — a string, `{value}`, or an array of strings for a
|
|
436
|
+
multi-select;
|
|
437
|
+
- by its visible text — `{label}`;
|
|
438
|
+
- by its position — `{index}`, from 0.
|
|
439
|
+
|
|
440
|
+
The call waits for the option to appear. A `{label}` or `{index}` no
|
|
441
|
+
option has fails with the labels the element holds:
|
|
442
|
+
`selectOption: … has no option labelled "Blue" — labels: "Red", "Dark
|
|
443
|
+
blue".` A misspelt key (`{lable}`) is `validator:options`.
|
|
425
444
|
|
|
426
445
|
```js
|
|
427
446
|
selectOption(getByLabel('Country'), 'US')
|
|
428
447
|
selectOption(getByLabel('Tags'), ['a', 'b'])
|
|
448
|
+
selectOption(getByLabel('Folder'), {label: 'Archive'})
|
|
449
|
+
selectOption(getByLabel('Folder'), {index: 0})
|
|
429
450
|
```
|
|
430
451
|
|
|
431
452
|
### `scrollIntoView(loc)`
|
|
@@ -439,7 +460,7 @@ scrollIntoView(getByText('Footer'))
|
|
|
439
460
|
## Assertions
|
|
440
461
|
|
|
441
462
|
Each polls until the condition holds or the timeout fires (default 5s;
|
|
442
|
-
override per-call with `{
|
|
463
|
+
override per-call with `{timeoutMs}`). Throw `AssertionError` on failure.
|
|
443
464
|
|
|
444
465
|
### `assertText(loc, expected, options?)`
|
|
445
466
|
|
|
@@ -460,7 +481,7 @@ assertText(getByRole('status'), 'Saving…', {not: true}) // waits until it ch
|
|
|
460
481
|
- Empty text: `assertText(loc, '')`. Any text at all:
|
|
461
482
|
`assertText(loc, '', {not: true})`.
|
|
462
483
|
|
|
463
|
-
**Options:** `
|
|
484
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`), `not?`.
|
|
464
485
|
|
|
465
486
|
### `assertTexts(loc, expected, options?)`
|
|
466
487
|
|
|
@@ -481,7 +502,7 @@ an index read, a helper's result. A value known to be something else (a
|
|
|
481
502
|
string, a number) is refused by the linter; the rest is checked when the
|
|
482
503
|
step runs. The same holds for the expected text of `assertText`.
|
|
483
504
|
|
|
484
|
-
**Options:** `
|
|
505
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`).
|
|
485
506
|
|
|
486
507
|
### `assertAttribute(loc, name, expected, options?)`
|
|
487
508
|
|
|
@@ -497,15 +518,15 @@ assertAttribute(getByRole('link', {name: 'Docs'}), 'href', /\/docs\//)
|
|
|
497
518
|
assertAttribute(getByRole('form'), 'aria-busy', 'true', {not: true})
|
|
498
519
|
```
|
|
499
520
|
|
|
500
|
-
**Options:** `
|
|
521
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`), `not?`.
|
|
501
522
|
|
|
502
523
|
### `assertVisible(loc, options?)` / `assertHidden(loc, options?)`
|
|
503
524
|
|
|
504
|
-
**Options:** `
|
|
525
|
+
**Options:** `timeoutMs?`.
|
|
505
526
|
|
|
506
527
|
```js
|
|
507
528
|
assertVisible(getByTestId('toast'))
|
|
508
|
-
assertHidden(getByTestId('spinner'), {
|
|
529
|
+
assertHidden(getByTestId('spinner'), {timeoutMs: 10000})
|
|
509
530
|
```
|
|
510
531
|
|
|
511
532
|
### `assertNeverAppears(loc, options)`
|
|
@@ -526,11 +547,39 @@ system under test could realistically react. Unlike `assertHidden`
|
|
|
526
547
|
(a poll that PASSES as soon as the element is gone), this one watches
|
|
527
548
|
the whole window.
|
|
528
549
|
|
|
550
|
+
### `assertNever(() => condition, options)`
|
|
551
|
+
|
|
552
|
+
The same window for a condition instead of a locator: poll the body for
|
|
553
|
+
`withinMs` (required) and **fail the moment** it is truthy; pass only
|
|
554
|
+
when the whole window elapsed clean. Use it where `pause()` and one
|
|
555
|
+
assertion afterwards would miss an event that came and went inside the
|
|
556
|
+
pause.
|
|
557
|
+
|
|
558
|
+
```js
|
|
559
|
+
assertNever(() => apiCall('GET', '/me', null, revokedAuth).status == 200,
|
|
560
|
+
{withinMs: 5000, label: 'revoked key rejected'});
|
|
561
|
+
assertNever(() => {
|
|
562
|
+
n = parseJson(textContent(getByTestId('unread')));
|
|
563
|
+
if (n > 0) { return n; }
|
|
564
|
+
return false;
|
|
565
|
+
}, {withinMs: 3000, intervalMs: 100});
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
- The body is an arrow, as in `waitUntil`: an expression, or a block
|
|
569
|
+
that gives its value with `return`.
|
|
570
|
+
- Options: `{ withinMs, intervalMs?, label? }`. `intervalMs` defaults to
|
|
571
|
+
250; the last poll falls on the end of the window.
|
|
572
|
+
- The failure names the label, the moment and the value: `assertNever
|
|
573
|
+
"revoked key rejected": truthy at 1250 ms of the 5000 ms window (6
|
|
574
|
+
tries); value: true.`
|
|
575
|
+
- An error inside the body fails the step at once. A clean window costs
|
|
576
|
+
the whole `withinMs`.
|
|
577
|
+
|
|
529
578
|
### `assertValue(loc, expected, options?)`
|
|
530
579
|
|
|
531
580
|
Compares `inputValue()` (`<input>`, `<textarea>`, native `<select>`).
|
|
532
581
|
|
|
533
|
-
**Options:** `
|
|
582
|
+
**Options:** `timeoutMs?`.
|
|
534
583
|
|
|
535
584
|
```js
|
|
536
585
|
assertValue(getByLabel('Email'), 'a@b.c')
|
|
@@ -555,11 +604,11 @@ value, and so does the failure.
|
|
|
555
604
|
|
|
556
605
|
### `assertCount(loc, expected, options?)`
|
|
557
606
|
|
|
558
|
-
**Options:** `
|
|
607
|
+
**Options:** `timeoutMs?`.
|
|
559
608
|
|
|
560
609
|
```js
|
|
561
610
|
assertCount(getByRole('listitem'), 5)
|
|
562
|
-
assertCount(getByRole('row'), 20, {
|
|
611
|
+
assertCount(getByRole('row'), 20, {timeoutMs: 15000})
|
|
563
612
|
```
|
|
564
613
|
|
|
565
614
|
### `assertUrl(pattern, options?)`
|
|
@@ -568,7 +617,7 @@ A string is a substring match against the active page's URL. A
|
|
|
568
617
|
`/regex/` is tested against the whole URL, unanchored: add `^` or `$`
|
|
569
618
|
yourself. A failure names the regex as `/source/flags`.
|
|
570
619
|
|
|
571
|
-
**Options:** `
|
|
620
|
+
**Options:** `timeoutMs?`.
|
|
572
621
|
|
|
573
622
|
```js
|
|
574
623
|
assertUrl('/dashboard')
|
|
@@ -934,7 +983,8 @@ goto('/dashboard') // relative — resolved against the
|
|
|
934
983
|
```
|
|
935
984
|
|
|
936
985
|
**Options:** `waitUntil?` (`'load'` | `'domcontentloaded'` |
|
|
937
|
-
`'networkidle'`), `
|
|
986
|
+
`'networkidle'` | `'commit'`), `timeoutMs?`. The same two keys go to
|
|
987
|
+
`reload`, `goBack`, `goForward` and `waitForUrl`.
|
|
938
988
|
|
|
939
989
|
### `reload(options?)` / `goBack(options?)` / `goForward(options?)`
|
|
940
990
|
|
|
@@ -944,7 +994,7 @@ Wait until the active page URL contains `pattern` (a string) or matches
|
|
|
944
994
|
it (a `/regex/`, unanchored). Useful after a click that triggers
|
|
945
995
|
navigation.
|
|
946
996
|
|
|
947
|
-
**Options:** `
|
|
997
|
+
**Options:** `waitUntil?` (as for `goto`), `timeoutMs?`.
|
|
948
998
|
|
|
949
999
|
```js
|
|
950
1000
|
click(getByRole('link', {name: 'Settings'}));
|
|
@@ -970,7 +1020,7 @@ waitFor(getByTestId('content-loaded'))
|
|
|
970
1020
|
|
|
971
1021
|
```js
|
|
972
1022
|
step("Wait until the widget re-enables the send button", () => {
|
|
973
|
-
waitFor(locator('.chat__send'), {state: 'enabled',
|
|
1023
|
+
waitFor(locator('.chat__send'), {state: 'enabled', timeoutMs: 30000});
|
|
974
1024
|
});
|
|
975
1025
|
```
|
|
976
1026
|
|
|
@@ -1006,15 +1056,44 @@ job = waitUntil(() => {
|
|
|
1006
1056
|
- On timeout the step fails with the label, the number of tries and the
|
|
1007
1057
|
last value: `waitUntil "job done": still falsy after 30000 ms (60
|
|
1008
1058
|
tries); last value: false.`
|
|
1059
|
+
- State the body keeps between tries — a counter, the last value seen —
|
|
1060
|
+
lives in a variable declared with `let` inside the `test_` function or
|
|
1061
|
+
the step; the body writes it:
|
|
1062
|
+
|
|
1063
|
+
```js
|
|
1064
|
+
let tries = 0;
|
|
1065
|
+
n = waitUntil(() => {
|
|
1066
|
+
tries = tries + 1;
|
|
1067
|
+
return tries >= 3 ? tries : false;
|
|
1068
|
+
});
|
|
1069
|
+
assertEqual(n, 3);
|
|
1070
|
+
```
|
|
1071
|
+
|
|
1072
|
+
A `let` at the top level of the file never runs: the validator refuses
|
|
1073
|
+
the declaration (`validator:unsupported-statement`), and the body then
|
|
1074
|
+
finds no such variable.
|
|
1075
|
+
|
|
1076
|
+
```js bad
|
|
1077
|
+
let seen = 0;
|
|
1078
|
+
|
|
1079
|
+
function test_counter() {
|
|
1080
|
+
step('poll', () => {
|
|
1081
|
+
waitUntil(() => {
|
|
1082
|
+
seen = seen + 1;
|
|
1083
|
+
return seen >= 3;
|
|
1084
|
+
});
|
|
1085
|
+
});
|
|
1086
|
+
}
|
|
1087
|
+
```
|
|
1009
1088
|
|
|
1010
1089
|
### `waitForText(text, options?)`
|
|
1011
1090
|
|
|
1012
1091
|
Wait until at least one **visible** element on the active page contains
|
|
1013
1092
|
`text` (chat feeds and repeated labels legally duplicate text — ≥1
|
|
1014
|
-
visible match is the success condition; `
|
|
1015
|
-
|
|
1093
|
+
visible match is the success condition; the `first` option of older
|
|
1094
|
+
releases is gone and is refused).
|
|
1016
1095
|
|
|
1017
|
-
Options: `{ exact?, state?,
|
|
1096
|
+
Options: `{ exact?, state?, timeoutMs? }`. Default matching is substring —
|
|
1018
1097
|
it also matches *inside* a word (`'hi'` hits `'anything'`). For precise
|
|
1019
1098
|
matching pass `{exact: true}` (full-text equality) or a regex with word
|
|
1020
1099
|
boundaries:
|
|
@@ -1022,7 +1101,7 @@ boundaries:
|
|
|
1022
1101
|
```js
|
|
1023
1102
|
waitForText('Active'); // ≥1 visible occurrence
|
|
1024
1103
|
waitForText('Active', {exact: true}); // full-text equality
|
|
1025
|
-
waitForText(/\bhi\b/, {
|
|
1104
|
+
waitForText(/\bhi\b/, {timeoutMs: 60000}); // word-boundary, long poll
|
|
1026
1105
|
```
|
|
1027
1106
|
|
|
1028
1107
|
`state: 'hidden'` waits until **no** visible occurrence remains.
|
|
@@ -1040,8 +1119,8 @@ content:
|
|
|
1040
1119
|
n = count(locator('[data-message]'));
|
|
1041
1120
|
fill(getByRole('textbox'), '@Bot Service ' + question);
|
|
1042
1121
|
press(getByRole('textbox'), 'Enter');
|
|
1043
|
-
waitForCount(locator('[data-message]'), n + 2, {
|
|
1044
|
-
waitForText(/Ital/i, {
|
|
1122
|
+
waitForCount(locator('[data-message]'), n + 2, {timeoutMs: 90000}); // echo + reply
|
|
1123
|
+
waitForText(/Ital/i, {timeoutMs: 90000}); // reply content
|
|
1045
1124
|
```
|
|
1046
1125
|
|
|
1047
1126
|
A unique marker (`randomWord(8)`) in the outgoing message plus a wait on
|
|
@@ -1054,14 +1133,14 @@ pattern "wait for reply №N": at-least semantics don't flake when the
|
|
|
1054
1133
|
feed grows past N between polls. `{exact: true}` waits for exactly
|
|
1055
1134
|
`count` matches; timeout throws with the last observed count.
|
|
1056
1135
|
|
|
1057
|
-
Options: `{ exact?,
|
|
1136
|
+
Options: `{ exact?, timeoutMs? }` (default timeout 5000 ms — raise it for
|
|
1058
1137
|
slow producers like LLM replies).
|
|
1059
1138
|
|
|
1060
1139
|
```js
|
|
1061
1140
|
// Chat feed: the bot's reply is message #3 — wait for it, then assert
|
|
1062
1141
|
// on its text with a second, content-anchored wait:
|
|
1063
|
-
waitForCount(locator('[data-id]'), 3, {
|
|
1064
|
-
waitForText(/\bshipping\b/i, {
|
|
1142
|
+
waitForCount(locator('[data-id]'), 3, {timeoutMs: 90000});
|
|
1143
|
+
waitForText(/\bshipping\b/i, {timeoutMs: 90000});
|
|
1065
1144
|
```
|
|
1066
1145
|
|
|
1067
1146
|
### `waitForAnimations(loc, options?)`
|
|
@@ -1072,7 +1151,7 @@ or screenshotting it. Infinite animations (spinners) and paused ones are
|
|
|
1072
1151
|
not waited for: neither ends by itself, so waiting could only time out.
|
|
1073
1152
|
A static element returns at once. Same rule as `hasAnimation`.
|
|
1074
1153
|
|
|
1075
|
-
Options: `{
|
|
1154
|
+
Options: `{ timeoutMs? }` (default 5000 ms). A timeout is an error naming
|
|
1076
1155
|
the element and how many animations were still running.
|
|
1077
1156
|
|
|
1078
1157
|
```js
|
|
@@ -1142,7 +1221,7 @@ there rather than half-applied.
|
|
|
1142
1221
|
|
|
1143
1222
|
`timezone` and `locale` in `unotest.config.mjs` set them for every page:
|
|
1144
1223
|
|
|
1145
|
-
```js
|
|
1224
|
+
```js config
|
|
1146
1225
|
export default {
|
|
1147
1226
|
timezone: 'Europe/Madrid', // Date#toString, Intl, getTimezoneOffset
|
|
1148
1227
|
locale: 'es-ES', // navigator.language, Intl defaults, Accept-Language
|
|
@@ -1208,6 +1287,44 @@ bringToFront(); // now tab 1 is shown too
|
|
|
1208
1287
|
bringToFront(0); // show the site again; steps stay on 1
|
|
1209
1288
|
```
|
|
1210
1289
|
|
|
1290
|
+
### `setPageHidden(hidden, index?)`
|
|
1291
|
+
|
|
1292
|
+
Emulates the tab's visibility for the page's scripts. `true` sends tab
|
|
1293
|
+
`index` to the background as its scripts see it: `document.hidden` is
|
|
1294
|
+
`true`, `document.visibilityState` is `'hidden'`, `document.hasFocus()`
|
|
1295
|
+
is `false`, and the page gets `blur` on `window`, then
|
|
1296
|
+
`visibilitychange`. `false` brings it back: `visibilitychange`, then
|
|
1297
|
+
`focus`. No index: the active tab. The steps keep acting on the hidden
|
|
1298
|
+
tab, as on any other.
|
|
1299
|
+
|
|
1300
|
+
A hidden tab stays hidden across navigations, and in its frames, until
|
|
1301
|
+
`setPageHidden(false)`. Asking for the state the tab is already in
|
|
1302
|
+
fires nothing. `setPage` and `bringToFront` do not show a hidden tab.
|
|
1303
|
+
|
|
1304
|
+
```js
|
|
1305
|
+
step("A message that arrives while the chat is in the background", () => {
|
|
1306
|
+
goto('/chat');
|
|
1307
|
+
clockFreeze('2026-01-15T10:00:00Z');
|
|
1308
|
+
setPageHidden(true);
|
|
1309
|
+
clockTick(6 * 60 * 1000); // six minutes away, on the page clock
|
|
1310
|
+
setPageHidden(false);
|
|
1311
|
+
assertVisible(getByText('New message'));
|
|
1312
|
+
});
|
|
1313
|
+
```
|
|
1314
|
+
|
|
1315
|
+
Time away is the page clock's
|
|
1316
|
+
([`clockTick`](#clockfreezeiso--clocktickms--clockrun)) or real
|
|
1317
|
+
(`pause(ms)`); hiding the tab does not move it.
|
|
1318
|
+
|
|
1319
|
+
Not emulated: what the browser itself does to a background tab.
|
|
1320
|
+
Timers are not throttled, animation frames keep running, the page is
|
|
1321
|
+
not frozen (`freeze` / `resume`), and a service worker's
|
|
1322
|
+
`clients.matchAll()` still reports the tab `visible`.
|
|
1323
|
+
|
|
1324
|
+
Engines: the same in Chromium, Firefox and WebKit. In Firefox a frame
|
|
1325
|
+
that loads while the tab is hidden sees it visible while it loads, and
|
|
1326
|
+
hidden from then on.
|
|
1327
|
+
|
|
1211
1328
|
### `newPage(url?)` → `number`
|
|
1212
1329
|
|
|
1213
1330
|
Open a new tab in the active browser context, make it active and bring
|
|
@@ -1375,6 +1492,59 @@ again after `setPage` / `waitForPage`. An app that reads the color
|
|
|
1375
1492
|
scheme once at load sees the change on its next load (`reload()`), not
|
|
1376
1493
|
before.
|
|
1377
1494
|
|
|
1495
|
+
### `addVirtualAuthenticator(options?)` → `id` / `virtualCredentials(id?)` / `removeVirtualAuthenticator(id)`
|
|
1496
|
+
|
|
1497
|
+
A passkey without a person at a device: a virtual WebAuthn
|
|
1498
|
+
authenticator answers the page's `navigator.credentials.create()` and
|
|
1499
|
+
`.get()` as a phone or laptop would. **Chromium only**; Firefox and
|
|
1500
|
+
WebKit fail the call with an error naming the engine.
|
|
1501
|
+
|
|
1502
|
+
```js
|
|
1503
|
+
const key = addVirtualAuthenticator();
|
|
1504
|
+
click(getByRole('button', {name: 'Create a passkey'}));
|
|
1505
|
+
waitForText('Passkey saved');
|
|
1506
|
+
const [passkey] = virtualCredentials(key);
|
|
1507
|
+
assertTrue(passkey.rpId == 'app.example.com', json(passkey));
|
|
1508
|
+
click(getByRole('button', {name: 'Sign in with a passkey'}));
|
|
1509
|
+
waitForText('Welcome back');
|
|
1510
|
+
```
|
|
1511
|
+
|
|
1512
|
+
- Without options it is the passkey of a phone or laptop: `protocol:
|
|
1513
|
+
'ctap2'`, `transport: 'internal'`, a resident key, a verified user,
|
|
1514
|
+
and every request answered without a touch. Each option overrides one
|
|
1515
|
+
of these: `protocol` (`'ctap2'` | `'u2f'`), `transport`
|
|
1516
|
+
(`'internal'` | `'usb'` | `'nfc'` | `'ble'` | `'cable'`),
|
|
1517
|
+
`hasResidentKey`, `hasUserVerification`, `isUserVerified`,
|
|
1518
|
+
`automaticPresenceSimulation`.
|
|
1519
|
+
- `virtualCredentials(id?)` — `[{credentialId, rpId, userHandle,
|
|
1520
|
+
signCount, resident}]` of one authenticator, or of all. Ids are
|
|
1521
|
+
base64url, as the page's `PublicKeyCredential.id` spells them;
|
|
1522
|
+
`signCount` grows with every sign-in.
|
|
1523
|
+
- The authenticator belongs to the tab that was active when it was
|
|
1524
|
+
added: a tab opened later does not see it.
|
|
1525
|
+
- The page must be https or `localhost`: WebAuthn does not exist
|
|
1526
|
+
elsewhere.
|
|
1527
|
+
|
|
1528
|
+
### `grantPermissions(permissions, options?)` / `setOffline(offline)`
|
|
1529
|
+
|
|
1530
|
+
```js
|
|
1531
|
+
grantPermissions(['notifications']);
|
|
1532
|
+
grantPermissions(['geolocation'], {origin: 'https://maps.example.com'});
|
|
1533
|
+
setOffline(true); // every request of the context fails as offline
|
|
1534
|
+
click(getByRole('button', {name: 'Sync'}));
|
|
1535
|
+
waitForText('You are offline');
|
|
1536
|
+
setOffline(false);
|
|
1537
|
+
```
|
|
1538
|
+
|
|
1539
|
+
- `grantPermissions` gives the context the named permissions, for every
|
|
1540
|
+
origin or for `{origin}`. The names are the browser's — which ones an
|
|
1541
|
+
engine knows differs: a name the engine does not know fails the call
|
|
1542
|
+
naming the engine, and what was granted before stays granted.
|
|
1543
|
+
- `setOffline(true)` cuts every page of the context off the network;
|
|
1544
|
+
`setOffline(false)` connects it again.
|
|
1545
|
+
- Both, and the authenticators, are taken back when the context closes:
|
|
1546
|
+
the next scenario starts without them.
|
|
1547
|
+
|
|
1378
1548
|
#### Viewport and scale
|
|
1379
1549
|
|
|
1380
1550
|
Where the window's size and scale come from, first match wins:
|
|
@@ -1400,7 +1570,7 @@ Where the window's size and scale come from, first match wins:
|
|
|
1400
1570
|
first scenario starts, as in the config.
|
|
1401
1571
|
3. **The config.** `unotest.config.mjs`:
|
|
1402
1572
|
|
|
1403
|
-
```js
|
|
1573
|
+
```js config
|
|
1404
1574
|
export default {
|
|
1405
1575
|
viewport: { width: 390, height: 844, deviceScaleFactor: 2 },
|
|
1406
1576
|
};
|
|
@@ -1416,7 +1586,7 @@ Where the window's size and scale come from, first match wins:
|
|
|
1416
1586
|
has no window manager — the size comes from `--window-size` in
|
|
1417
1587
|
`launch.args`:
|
|
1418
1588
|
|
|
1419
|
-
```js
|
|
1589
|
+
```js config
|
|
1420
1590
|
export default {
|
|
1421
1591
|
viewport: null,
|
|
1422
1592
|
launch: { args: ["--window-size=1440,900"] },
|
|
@@ -1477,7 +1647,8 @@ goto('chrome-extension://' + id + '/popup.html');
|
|
|
1477
1647
|
`chrome-extension://<id>/sw.js`. A running worker comes back at once;
|
|
1478
1648
|
otherwise it waits up to `timeoutMs` (default: the navigation timeout).
|
|
1479
1649
|
`url` — a substring or `/regex/` when several extensions run.
|
|
1480
|
-
- `evaluateInServiceWorker(js, ...args)` — `evaluate` in the worker.
|
|
1650
|
+
- `evaluateInServiceWorker(js, ...args)` — `evaluate` in the worker.
|
|
1651
|
+
`js` is a function or a string, under the same page-code rules. The
|
|
1481
1652
|
extras reach the body by the same rule as `evaluate`: none →
|
|
1482
1653
|
`undefined`, one → the value itself, two or more → one array. JSON
|
|
1483
1654
|
return; a returned Promise is awaited. Not discouraged by the
|
|
@@ -1547,6 +1718,29 @@ real event won't accept formatting.
|
|
|
1547
1718
|
clipboardPaste(getByLabel('Notes'), 'pasted text');
|
|
1548
1719
|
```
|
|
1549
1720
|
|
|
1721
|
+
### `clipboardRead()` → `string` / `assertClipboard(expected, options?)`
|
|
1722
|
+
|
|
1723
|
+
What a "copy" button left in the clipboard — read by the active page,
|
|
1724
|
+
instead of intercepting `navigator.clipboard.writeText` in it.
|
|
1725
|
+
|
|
1726
|
+
```js
|
|
1727
|
+
click(getByRole('button', {name: 'Copy invite link'}));
|
|
1728
|
+
assertClipboard(/\/invite\/\d+$/);
|
|
1729
|
+
const link = clipboardRead();
|
|
1730
|
+
```
|
|
1731
|
+
|
|
1732
|
+
- `assertClipboard` waits until the clipboard holds `expected` — the
|
|
1733
|
+
whole text for a string, a match for a regex — `{timeoutMs}`, default
|
|
1734
|
+
5 s. A page writes the clipboard from a promise, so the text lands a
|
|
1735
|
+
beat after the click; `clipboardRead()` reads once, without waiting.
|
|
1736
|
+
- Engines: Chromium (the context is given clipboard read and write
|
|
1737
|
+
access when it is opened, so the page's own copy works too) and
|
|
1738
|
+
Firefox, on an https or `localhost` page — the clipboard API does not
|
|
1739
|
+
exist elsewhere. WebKit does not let a page read the clipboard: the
|
|
1740
|
+
call fails with an error naming the engine, never an empty string.
|
|
1741
|
+
- The clipboard belongs to the browser, not to one test: tests running
|
|
1742
|
+
in parallel in one browser share it.
|
|
1743
|
+
|
|
1550
1744
|
---
|
|
1551
1745
|
|
|
1552
1746
|
## Sandbox primitives
|
|
@@ -1555,7 +1749,7 @@ Project-agnostic core (D-13, D-27). Consumers wire connection / base-URL
|
|
|
1555
1749
|
config in `unotest/unotest.config.{js,mjs,ts}` under `sandbox.{shellCwd, database,
|
|
1556
1750
|
apiBaseUrl}` — the scenario **cannot** override.
|
|
1557
1751
|
|
|
1558
|
-
```js
|
|
1752
|
+
```js config
|
|
1559
1753
|
// unotest/unotest.config.mjs
|
|
1560
1754
|
export default {
|
|
1561
1755
|
sandbox: {
|
|
@@ -1679,7 +1873,7 @@ yet is judged by the nearest directory above it that does.
|
|
|
1679
1873
|
A background process that writes outside the project (a listener's log
|
|
1680
1874
|
in `/tmp`) needs its directory in the config:
|
|
1681
1875
|
|
|
1682
|
-
```js
|
|
1876
|
+
```js config
|
|
1683
1877
|
// unotest/unotest.config.mjs
|
|
1684
1878
|
export default {
|
|
1685
1879
|
sandbox: { readRoots: ['/tmp/my-listener'] },
|
|
@@ -1804,11 +1998,11 @@ An environment value the test can do without. It reads what a bare
|
|
|
1804
1998
|
`unotest/.env` — but returns `fallback` for a name that is not set
|
|
1805
1999
|
instead of failing the step, and `null` when no fallback is given.
|
|
1806
2000
|
|
|
1807
|
-
The fallback is the one-line default
|
|
1808
|
-
answers `true` / `false`, not a value:
|
|
2001
|
+
The fallback is the one-line default; `??` says the same:
|
|
1809
2002
|
|
|
1810
2003
|
```js
|
|
1811
2004
|
api = env('API_URL', 'http://localhost:3000');
|
|
2005
|
+
api = env('API_URL') ?? 'http://localhost:3000';
|
|
1812
2006
|
```
|
|
1813
2007
|
|
|
1814
2008
|
Without a fallback, use the `null` to decide:
|
|
@@ -1900,6 +2094,38 @@ step("The agent answered exactly once", () => {
|
|
|
1900
2094
|
Counting is per **line** (`grep -c` semantics), not per occurrence: two
|
|
1901
2095
|
matches on one line count once.
|
|
1902
2096
|
|
|
2097
|
+
### `assertFileHas(path, needle, options?)` / `assertFileLacks(path, needle, options?)`
|
|
2098
|
+
|
|
2099
|
+
A string or a regex must — or must not — appear in a file, or anywhere
|
|
2100
|
+
in a directory. The usual subject is what a run leaves behind: a secret
|
|
2101
|
+
must not reach a log or a database dump, while its ciphertext must.
|
|
2102
|
+
|
|
2103
|
+
```js
|
|
2104
|
+
step("The token is stored encrypted, never in plain text", () => {
|
|
2105
|
+
shell('sh', '-c', 'pg_dump app > tmp/dump.sql');
|
|
2106
|
+
assertFileLacks('tmp/dump.sql', API_TOKEN);
|
|
2107
|
+
assertFileLacks('logs', /sk-live-[0-9a-f]{24}/);
|
|
2108
|
+
assertFileHas('tmp/dump.sql', /v1:[A-Za-z0-9+\/=]{20,}/);
|
|
2109
|
+
});
|
|
2110
|
+
```
|
|
2111
|
+
|
|
2112
|
+
- `path` follows the rules of `readFile`: relative to `sandbox.shellCwd`,
|
|
2113
|
+
inside the project, the downloads dir or `sandbox.readRoots`. A
|
|
2114
|
+
directory is searched recursively; symlinks inside it are not followed.
|
|
2115
|
+
- A string `needle` is searched as **bytes**, so a binary file is
|
|
2116
|
+
searched too. A regex reads each file as UTF-8 text.
|
|
2117
|
+
- `assertFileHas` polls until the needle appears — `{timeoutMs}`, default
|
|
2118
|
+
20 s — and on a miss says how many files and bytes it searched, or
|
|
2119
|
+
that the path does not exist.
|
|
2120
|
+
- `assertFileLacks` searches **once**. `{withinMs}` watches a window
|
|
2121
|
+
instead and fails the moment the needle appears. A path that does not
|
|
2122
|
+
exist fails as well: nothing searched proves nothing absent.
|
|
2123
|
+
- A hit names the file and the line, with the line around it — the
|
|
2124
|
+
matched bytes themselves replaced by `‹match, N bytes›`, so a regex
|
|
2125
|
+
that catches an unregistered secret does not copy it into the report.
|
|
2126
|
+
The needle is quoted as written; a value from `unotest/.secrets` is
|
|
2127
|
+
masked in every report and log like anywhere else.
|
|
2128
|
+
|
|
1903
2129
|
### `dbQuery(sql, ...params)` → `rows[]`
|
|
1904
2130
|
|
|
1905
2131
|
Parameterized SELECT. Driver picked by URL scheme:
|
|
@@ -1930,7 +2156,7 @@ res = apiCall('POST', '/auth/login', {email: 'a@b.c', password: 'x'});
|
|
|
1930
2156
|
assertTrue(res.status == 200, 'login failed');
|
|
1931
2157
|
```
|
|
1932
2158
|
|
|
1933
|
-
**Named API bases.** Without `
|
|
2159
|
+
**Named API bases.** Without `{base}` the path goes against
|
|
1934
2160
|
`sandbox.apiBaseUrl`. A setup that talks to more than one host names
|
|
1935
2161
|
the base per call — `{base: 'API_BASE_X'}` is the **name of a
|
|
1936
2162
|
variable** from `unotest/.env` (overlays apply as usual), never a URL:
|
|
@@ -1941,9 +2167,11 @@ res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
|
|
|
1941
2167
|
{base: 'API_BASE_CHAT'});
|
|
1942
2168
|
```
|
|
1943
2169
|
|
|
1944
|
-
The variable must hold an http(s) URL
|
|
1945
|
-
|
|
1946
|
-
|
|
2170
|
+
The variable must hold an http(s) URL. It is read from the project's
|
|
2171
|
+
environment only: a scenario variable of the same name is not a base,
|
|
2172
|
+
and a name the environment does not hold is refused with where to put
|
|
2173
|
+
it. URLs never appear in the scenario — hosts are controlled by project
|
|
2174
|
+
env files only.
|
|
1947
2175
|
|
|
1948
2176
|
**With an environment overlay active, the base must come from it.**
|
|
1949
2177
|
Running `--env dev` while `API_BASE_CHAT` is set only in the base
|
|
@@ -1953,7 +2181,7 @@ base host while everything else in the run resolves against `dev`. Set
|
|
|
1953
2181
|
the name in `unotest/.env.dev`, or, when the base value really is meant
|
|
1954
2182
|
for every environment, list the name in the config:
|
|
1955
2183
|
|
|
1956
|
-
```js
|
|
2184
|
+
```js config
|
|
1957
2185
|
// unotest/unotest.config.mjs
|
|
1958
2186
|
export default { env: { shared: ['API_BASE_CHAT'] } };
|
|
1959
2187
|
```
|
|
@@ -1964,6 +2192,21 @@ file the overlay was supposed to replace. The same rule covers
|
|
|
1964
2192
|
`APP_BASE_URL` (the base every relative `goto` resolves against) and a
|
|
1965
2193
|
variable used as the URL in `goto(NAME)`.
|
|
1966
2194
|
|
|
2195
|
+
**Per-call timeout — `{timeoutMs}`.** A call has no time limit of its
|
|
2196
|
+
own: it waits as long as the step and the test allow. An endpoint that
|
|
2197
|
+
must answer in a known time — or a slow one you would rather fail fast
|
|
2198
|
+
on — gets a budget for the whole call, the reply body included:
|
|
2199
|
+
|
|
2200
|
+
```js
|
|
2201
|
+
res = apiCall('POST', '/live/start', {stand: 'a'}, null, {timeoutMs: 150000});
|
|
2202
|
+
```
|
|
2203
|
+
|
|
2204
|
+
Past the budget the request is aborted and the step fails as a timeout
|
|
2205
|
+
naming the call (`apiCall(POST /live/start) got no full reply within
|
|
2206
|
+
150000ms`), without the base or the query. The value is a positive
|
|
2207
|
+
number of milliseconds; `{timeout}` is not an alias here and is refused.
|
|
2208
|
+
It combines with `{base}` in the same object.
|
|
2209
|
+
|
|
1967
2210
|
**Multipart file upload — `upload(path, options?)`.** Passing the
|
|
1968
2211
|
result of `upload(...)` as the body posts `multipart/form-data`:
|
|
1969
2212
|
|
|
@@ -1996,6 +2239,151 @@ assertTrue(res.status == 202, 'ingestion not accepted');
|
|
|
1996
2239
|
|
|
1997
2240
|
---
|
|
1998
2241
|
|
|
2242
|
+
## MCP client
|
|
2243
|
+
|
|
2244
|
+
A scenario can be the client of a stdio MCP server: start it, call its
|
|
2245
|
+
tools, wait for the notifications it sends. Every call, result and
|
|
2246
|
+
notification is a note in the run's journal, next to the browser steps,
|
|
2247
|
+
and a failing step quotes the server's last message — request, response
|
|
2248
|
+
or notification — in its error, so the failure bundle shows what the
|
|
2249
|
+
server said last.
|
|
2250
|
+
|
|
2251
|
+
```js
|
|
2252
|
+
function test_echo_notifies() {
|
|
2253
|
+
step('echo answers and notifies', () => {
|
|
2254
|
+
const srv = mcpStart('node', ['server.js'], {env: {API_TOKEN: API_TOKEN}});
|
|
2255
|
+
const res = mcpCall(srv, 'echo', {text: 'hi'});
|
|
2256
|
+
assertTrue(res.content[0].text == 'hi', 'echo answered something else');
|
|
2257
|
+
mcpWaitNotification(srv, 'notifications/message', {match: {'data.echoed': 'hi'}});
|
|
2258
|
+
});
|
|
2259
|
+
}
|
|
2260
|
+
```
|
|
2261
|
+
|
|
2262
|
+
A server the test leaves running is stopped when the test ends, passed
|
|
2263
|
+
or failed — a red step that never reached `mcpStop` leaves nothing
|
|
2264
|
+
behind.
|
|
2265
|
+
|
|
2266
|
+
### `mcpStart(command, args?, options?)` → server
|
|
2267
|
+
|
|
2268
|
+
Starts `command` with `args` (a list of strings) and finishes the MCP
|
|
2269
|
+
handshake. Returns the handle the other `mcp*` functions take.
|
|
2270
|
+
|
|
2271
|
+
- `env` — variables added to the environment the server inherits (the
|
|
2272
|
+
runner's own credentials are kept out of it, as for `shell()`). The
|
|
2273
|
+
journal names them, never their values.
|
|
2274
|
+
- `cwd` — relative to the project (`sandbox.shellCwd`), default the
|
|
2275
|
+
project itself.
|
|
2276
|
+
- `timeoutMs` — for the start and the handshake, default 30 s.
|
|
2277
|
+
|
|
2278
|
+
A server that does not come up — a missing command, an exit before the
|
|
2279
|
+
handshake — errors the test, with the tail of its stderr.
|
|
2280
|
+
|
|
2281
|
+
### `mcpCall(server, tool, args?, options?)` → `{content, structuredContent?, isError?}`
|
|
2282
|
+
|
|
2283
|
+
Calls `tool` with `args` (an object) and returns the result as the
|
|
2284
|
+
server sent it. These fail the step, quoting the last MCP message:
|
|
2285
|
+
|
|
2286
|
+
- a JSON-RPC error answer;
|
|
2287
|
+
- no answer within `timeoutMs` (default 30 s);
|
|
2288
|
+
- the server going away mid-call (its stderr tail is quoted);
|
|
2289
|
+
- a result marked `isError` — pass `{allowError: true}` to get it back
|
|
2290
|
+
and check it yourself.
|
|
2291
|
+
|
|
2292
|
+
### `mcpWaitNotification(server, method, options?)` → params
|
|
2293
|
+
|
|
2294
|
+
Waits for a notification of `method` and returns its `params`.
|
|
2295
|
+
Notifications are kept from the moment the server started and each one
|
|
2296
|
+
is handed out once, so the usual order — call, then wait for what the
|
|
2297
|
+
call set off — loses nothing even when the notification beats the
|
|
2298
|
+
response.
|
|
2299
|
+
|
|
2300
|
+
- `match` — scalars at dot paths of the params, as `waitForJsonLine`
|
|
2301
|
+
reads them: `{'data.status': 'done', 'level': 'info'}`.
|
|
2302
|
+
- `timeoutMs` — default 30 s. The failure names the notifications that
|
|
2303
|
+
did come and are still waiting to be taken.
|
|
2304
|
+
|
|
2305
|
+
### `mcpStop(server)`
|
|
2306
|
+
|
|
2307
|
+
Stops the server. Optional — see above.
|
|
2308
|
+
|
|
2309
|
+
---
|
|
2310
|
+
|
|
2311
|
+
## Virtual machines
|
|
2312
|
+
|
|
2313
|
+
A scenario can drive [Tart](https://tart.run) VMs: clone a ready image,
|
|
2314
|
+
boot it, reach it by its address — a clean machine to install on, per
|
|
2315
|
+
test. The image is yours, prepared once on the host; the scenario does
|
|
2316
|
+
not build it.
|
|
2317
|
+
|
|
2318
|
+
**Preparing the image, once.** A step that logs in to the VM over ssh
|
|
2319
|
+
(`openTerminal(app, {host})`) uses your key and never a password, and a
|
|
2320
|
+
clean Tart image takes only the password (`admin` / `admin`). Put your
|
|
2321
|
+
public key in the image before the first run:
|
|
2322
|
+
|
|
2323
|
+
```sh
|
|
2324
|
+
tart clone ghcr.io/cirruslabs/macos-sequoia-base:latest clean-mac
|
|
2325
|
+
tart run clean-mac & # boot it
|
|
2326
|
+
ssh-copy-id admin@"$(tart ip --wait 120 clean-mac)" # password: admin
|
|
2327
|
+
tart stop clean-mac # the image now holds the key
|
|
2328
|
+
```
|
|
2329
|
+
|
|
2330
|
+
Every VM `vmClone('clean-mac')` makes from then on holds it too. A key
|
|
2331
|
+
that is not the default one goes into your ssh agent (`ssh-add <key>`).
|
|
2332
|
+
Without it the step fails with `ssh could not reach or log in to …
|
|
2333
|
+
with a key (exit 255)` and these same three commands, `<image>` standing
|
|
2334
|
+
for your image: the VM the step reached is a clone the run deletes, so
|
|
2335
|
+
the key goes into the image. `ssh-copy-id` asks for the image's password
|
|
2336
|
+
(`admin` on Tart's images).
|
|
2337
|
+
|
|
2338
|
+
```js
|
|
2339
|
+
function test_install_on_clean_mac() {
|
|
2340
|
+
skip('no tart on this host', !vmAvailable());
|
|
2341
|
+
step('boot a clean mac', () => {
|
|
2342
|
+
const vm = vmClone('clean-mac');
|
|
2343
|
+
const ip = vmRun(vm);
|
|
2344
|
+
const res = shell('curl', '-fsS', `http://${ip}:8080/health`);
|
|
2345
|
+
assertTrue(res.stdout.includes('ok'), 'the service on the VM did not answer');
|
|
2346
|
+
});
|
|
2347
|
+
}
|
|
2348
|
+
```
|
|
2349
|
+
|
|
2350
|
+
The VMs are the test's. `vmClone` names each one `unotest-<id>-<n>`,
|
|
2351
|
+
the id random per test, so parallel runs never meet. Every VM the test
|
|
2352
|
+
cloned is stopped and deleted when it ends, passed or failed. The other
|
|
2353
|
+
`vm*` steps take only a name `vmClone` returned in this test: any other
|
|
2354
|
+
VM on the machine is refused, never stopped or deleted. Clone and boot
|
|
2355
|
+
are notes in the run's journal, with the VM's name and the run.
|
|
2356
|
+
|
|
2357
|
+
### `vmAvailable()` → `boolean`
|
|
2358
|
+
|
|
2359
|
+
Whether VMs can run here: Tart is installed and answers. `false`, not an
|
|
2360
|
+
error, where it is missing — guard a VM test with `skip`.
|
|
2361
|
+
|
|
2362
|
+
### `vmClone(image)` → name
|
|
2363
|
+
|
|
2364
|
+
A new VM from `image` — a local Tart VM or an OCI reference. Returns its
|
|
2365
|
+
name for the other `vm*` steps.
|
|
2366
|
+
|
|
2367
|
+
### `vmRun(name, options?)` → ip
|
|
2368
|
+
|
|
2369
|
+
Boots the VM without a window and waits for its address.
|
|
2370
|
+
|
|
2371
|
+
- `timeoutMs` — default 180 s, about what a macOS guest needs.
|
|
2372
|
+
|
|
2373
|
+
A boot that fails errors the step at once with Tart's output, without
|
|
2374
|
+
waiting the timeout out.
|
|
2375
|
+
|
|
2376
|
+
### `vmIp(name, options?)` → ip
|
|
2377
|
+
|
|
2378
|
+
The address of a running VM. `timeoutMs` — default 60 s.
|
|
2379
|
+
|
|
2380
|
+
### `vmStop(name)` / `vmDelete(name)`
|
|
2381
|
+
|
|
2382
|
+
Stop the VM; delete it, stopping it first if it runs. Both optional —
|
|
2383
|
+
see above.
|
|
2384
|
+
|
|
2385
|
+
---
|
|
2386
|
+
|
|
1999
2387
|
## Network mocks
|
|
2000
2388
|
|
|
2001
2389
|
What the page's requests get, for the rest of the scenario: a fixed
|
|
@@ -2030,7 +2418,10 @@ mockRoute('**/ads/**', { abort: true });
|
|
|
2030
2418
|
navigation to your site still loads. Only the document: its scripts,
|
|
2031
2419
|
styles, images and API calls are ordinary requests, and an abort mask
|
|
2032
2420
|
that matches them stops them.
|
|
2033
|
-
- A mask reaches
|
|
2421
|
+
- A mask reaches http(s) requests only. A WebSocket is no request: no
|
|
2422
|
+
mask reaches it, wait for one with
|
|
2423
|
+
[`waitForWebSocket`](#waitforwebsocketglob-options--url), and a
|
|
2424
|
+
`ws://` or `wss://` mask is named with a warning. An extension's
|
|
2034
2425
|
own pages and scripts (`chrome-extension://`) load under `**/*`, so
|
|
2035
2426
|
a network allowlist does not leave its UI dead. To mock one of them,
|
|
2036
2427
|
start the mask with its scheme: `chrome-extension://<id>/panel.js`.
|
|
@@ -2070,6 +2461,28 @@ assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
|
|
|
2070
2461
|
On any other mask only requests from the call on count — to catch one
|
|
2071
2462
|
the previous step sent, mock the mask with `{continue: true}` first.
|
|
2072
2463
|
- `{timeoutMs}` — default 20 000.
|
|
2464
|
+
- A `ws://` or `wss://` mask is refused: a WebSocket is no request.
|
|
2465
|
+
|
|
2466
|
+
### `waitForWebSocket(glob, options?)` → `{url}`
|
|
2467
|
+
|
|
2468
|
+
Waits until the active page has opened a WebSocket whose URL matches
|
|
2469
|
+
`glob` and returns its URL. The mask is a Playwright URL glob, as for
|
|
2470
|
+
`mockRoute`; one starting with `/` is a path on your site
|
|
2471
|
+
(`/live` → `ws://<host>/live`, `wss://` for an `https` site).
|
|
2472
|
+
|
|
2473
|
+
```js
|
|
2474
|
+
goto('/chat');
|
|
2475
|
+
socket = waitForWebSocket('**/ws');
|
|
2476
|
+
assertTrue(socket.url.endsWith('/ws'));
|
|
2477
|
+
```
|
|
2478
|
+
|
|
2479
|
+
- A socket opened before the call counts, from the page's last load on:
|
|
2480
|
+
a page that connects as it loads has done so by the time the step
|
|
2481
|
+
asks. A new document starts the list again; a single-page app moving
|
|
2482
|
+
between its routes does not.
|
|
2483
|
+
- Two waits on one mask find the same socket.
|
|
2484
|
+
- A timeout names the mask and the sockets the page did open.
|
|
2485
|
+
- `{timeoutMs}` — default 20 000.
|
|
2073
2486
|
|
|
2074
2487
|
### `assertNoRequest(glob, options?)`
|
|
2075
2488
|
|
|
@@ -2091,6 +2504,116 @@ assertNoRequest('**/*');
|
|
|
2091
2504
|
|
|
2092
2505
|
---
|
|
2093
2506
|
|
|
2507
|
+
## Terminal (macOS)
|
|
2508
|
+
|
|
2509
|
+
A real terminal window: Terminal.app or iTerm2, driven by real key
|
|
2510
|
+
events, read as screen text, framed as a picture. For a CLI or a TUI
|
|
2511
|
+
(an agent in a terminal, an installer, a `--watch` mode) the bugs a
|
|
2512
|
+
pseudo-terminal hides live here: a key the terminal encodes itself
|
|
2513
|
+
(Shift+Enter under the kitty keyboard protocol), the window's width, the
|
|
2514
|
+
`PATH` of the shell the user actually has.
|
|
2515
|
+
|
|
2516
|
+
The verbs are the page's ones with a `terminal` prefix:
|
|
2517
|
+
`terminalType`, `terminalPress`, `terminalWaitForText`,
|
|
2518
|
+
`terminalAssertText`, `terminalScreenshot`. The bare names act on the
|
|
2519
|
+
page, and a test can drive both.
|
|
2520
|
+
|
|
2521
|
+
```js
|
|
2522
|
+
step("The CLI answers in a real terminal", () => {
|
|
2523
|
+
openTerminal('Terminal');
|
|
2524
|
+
terminalResize(100, 30);
|
|
2525
|
+
terminalType('my-cli --version');
|
|
2526
|
+
terminalPress('Enter');
|
|
2527
|
+
terminalWaitForText(/my-cli \d+\.\d+/);
|
|
2528
|
+
});
|
|
2529
|
+
```
|
|
2530
|
+
|
|
2531
|
+
Every step lands in the run's report like a page step, without a frame
|
|
2532
|
+
of the terminal per step: frames are taken by `terminalScreenshot()`
|
|
2533
|
+
and on failure. A failed test
|
|
2534
|
+
keeps the active window in the failure bundle: `terminal.png` (its last
|
|
2535
|
+
frame), `terminal.txt` (its screen text, secrets redacted) and
|
|
2536
|
+
`terminal.json` (which app, on which host).
|
|
2537
|
+
|
|
2538
|
+
**Where it runs.** macOS, through `osascript` and `screencapture`.
|
|
2539
|
+
|
|
2540
|
+
- On this Mac, the default. macOS asks once to let the app the run starts
|
|
2541
|
+
from (Terminal, iTerm2, your editor) control the computer and record
|
|
2542
|
+
the screen. While the test types, **it has the keyboard**: keys go to
|
|
2543
|
+
the terminal window only while it is in front, and a step fails rather
|
|
2544
|
+
than type into a window that took the focus. Leave the machine alone,
|
|
2545
|
+
or run it in a VM.
|
|
2546
|
+
- On another Mac, a Tart VM: `openTerminal('Terminal', {host:
|
|
2547
|
+
'admin@192.168.64.38'})`. The run reaches it over ssh with your key
|
|
2548
|
+
(ssh agent or `~/.ssh`; a password is never passed) and drives the
|
|
2549
|
+
terminal through a small controller it starts in the logged-in session
|
|
2550
|
+
there — macOS gives an ssh session itself no control of the screen.
|
|
2551
|
+
A VM just booted by `vmRun` answers ssh before its automatic login
|
|
2552
|
+
is done: the run waits up to 90 s for that session, and an image that
|
|
2553
|
+
logs no one in fails the step saying so.
|
|
2554
|
+
A clean Tart macOS image needs no extra permission for Terminal.app,
|
|
2555
|
+
but it needs your key once: see
|
|
2556
|
+
[Preparing the image](#virtual-machines).
|
|
2557
|
+
- A Linux terminal is not driven yet.
|
|
2558
|
+
|
|
2559
|
+
### `openTerminal(app, options?)` → `number`
|
|
2560
|
+
|
|
2561
|
+
Opens a window of `'Terminal'` or `'iTerm2'` with a login shell, makes it
|
|
2562
|
+
active, returns its index. Options: `{host: 'user@address'}` — the Mac to
|
|
2563
|
+
open it on. Every window the test opened closes when it ends, green or
|
|
2564
|
+
red; its shell and what runs in it are stopped.
|
|
2565
|
+
|
|
2566
|
+
### `setTerminal(index)` / `closeTerminal()`
|
|
2567
|
+
|
|
2568
|
+
`setTerminal` moves the terminal steps to another window, as `setContext`
|
|
2569
|
+
does for browser contexts; indices stay put when a window closes.
|
|
2570
|
+
`closeTerminal` closes the active one.
|
|
2571
|
+
|
|
2572
|
+
### `terminalType(text)` / `terminalPress(key)`
|
|
2573
|
+
|
|
2574
|
+
`terminalType` puts the text in as a paste, line by line: a line goes on
|
|
2575
|
+
the clipboard, then ⌘V, and a line break presses Return. The Mac's
|
|
2576
|
+
keyboard layout does not change what arrives — Cyrillic and emoji
|
|
2577
|
+
included — and the clipboard holds what you copied again when the step
|
|
2578
|
+
ends. A program in the terminal sees a paste, not typing: a TUI that
|
|
2579
|
+
turned bracketed paste on gets the text as one paste.
|
|
2580
|
+
|
|
2581
|
+
Each line must show on the screen within 2 s, or the step fails and its
|
|
2582
|
+
message ends with the screen's last rows — what arrived instead. Input a
|
|
2583
|
+
program does not echo goes with `{echo: false}`:
|
|
2584
|
+
|
|
2585
|
+
```js
|
|
2586
|
+
terminalWaitForText('Password:');
|
|
2587
|
+
terminalType(env('ADMIN_PASSWORD'), {echo: false});
|
|
2588
|
+
terminalPress('Enter');
|
|
2589
|
+
```
|
|
2590
|
+
|
|
2591
|
+
`terminalPress` presses one key with modifiers, spelled as `press()`
|
|
2592
|
+
spells them: `'Enter'`, `'Shift+Enter'`, `'Control+]'`, `'Escape'`,
|
|
2593
|
+
`'ArrowUp'`, `'F5'`, a single character. Modifiers: `Shift`, `Control`,
|
|
2594
|
+
`Alt`, `Meta`. A character held with a modifier (`'Control+c'`) presses
|
|
2595
|
+
that key of a US keyboard, whatever the layout; a character with no key
|
|
2596
|
+
of its own there names the key it is on (`'Control+Shift+='`, not
|
|
2597
|
+
`'Control++'`). A single character alone is pasted, as `terminalType`
|
|
2598
|
+
does it, without the wait for the echo: a shell prompt (`y/n`) takes it
|
|
2599
|
+
as the key, while a TUI with bracketed paste on (vim in normal mode)
|
|
2600
|
+
sees a paste.
|
|
2601
|
+
|
|
2602
|
+
### `terminalWaitForText(text, options?)` / `terminalAssertText(text, options?)`
|
|
2603
|
+
|
|
2604
|
+
The screen is the window's visible text, rows without their padding. A
|
|
2605
|
+
string matches anywhere on it, a `/regex/` is tested against it.
|
|
2606
|
+
`{not: true}` waits for the text to go. `terminalWaitForText` waits up to
|
|
2607
|
+
30 s, `terminalAssertText` 5000 ms; `{timeoutMs}` sets either.
|
|
2608
|
+
|
|
2609
|
+
### `terminalResize(cols, rows)`
|
|
2610
|
+
|
|
2611
|
+
Resizes the active window to `cols` × `rows` character cells.
|
|
2612
|
+
|
|
2613
|
+
### `terminalScreenshot(name?)` → `string`
|
|
2614
|
+
|
|
2615
|
+
A PNG of the active window, saved with the run like `screenshot()`.
|
|
2616
|
+
|
|
2094
2617
|
## Typed getters
|
|
2095
2618
|
|
|
2096
2619
|
Read page properties directly into a local variable.
|
|
@@ -2174,6 +2697,28 @@ the rule `waitForAnimations` waits by.
|
|
|
2174
2697
|
assertTrue(hasAnimation(getByRole('dialog')) === false, 'dialog still moving');
|
|
2175
2698
|
```
|
|
2176
2699
|
|
|
2700
|
+
### `animations(loc)` → `[{name, kind, playState, currentTime?, infinite}]`
|
|
2701
|
+
|
|
2702
|
+
Every animation of the element and its descendants, as the page has
|
|
2703
|
+
them now. The typed read instead of `getAnimations()` through
|
|
2704
|
+
`evaluateOnLocator`.
|
|
2705
|
+
|
|
2706
|
+
- `name` — the `@keyframes` name, the property a transition moves, or a
|
|
2707
|
+
script animation's `id`.
|
|
2708
|
+
- `kind` — `'animation'`, `'transition'` or `'script'`.
|
|
2709
|
+
- `playState` — `'running'`, `'paused'`, `'finished'` or `'idle'`.
|
|
2710
|
+
- `currentTime` — milliseconds into it; left out when it has no time.
|
|
2711
|
+
- `infinite` — `true` for one that repeats forever (a spinner).
|
|
2712
|
+
|
|
2713
|
+
Infinite and paused animations are listed too. `hasAnimation` counts
|
|
2714
|
+
only those with `playState: 'running'` and `infinite: false`.
|
|
2715
|
+
|
|
2716
|
+
```js
|
|
2717
|
+
list = animations(getByTestId('status'));
|
|
2718
|
+
pulse = list.find((a) => a.name == 'pulse');
|
|
2719
|
+
assertTrue(pulse !== undefined && pulse.playState == 'running', json(list));
|
|
2720
|
+
```
|
|
2721
|
+
|
|
2177
2722
|
### `getTitle()` → `string`
|
|
2178
2723
|
|
|
2179
2724
|
Active page title.
|
|
@@ -2365,8 +2910,13 @@ dates.
|
|
|
2365
2910
|
context. Discouraged (`lint:evaluate-discouraged`) — prefer typed
|
|
2366
2911
|
getters or the action API.
|
|
2367
2912
|
|
|
2913
|
+
`js` is a function or a string. A function is sent to the page as it is
|
|
2914
|
+
written, the way Playwright sends `fn.toString()`: the page sees none of
|
|
2915
|
+
the scenario's variables, only the arguments after it.
|
|
2916
|
+
|
|
2368
2917
|
```js
|
|
2369
|
-
height = evaluate(
|
|
2918
|
+
height = evaluate(() => document.documentElement.scrollHeight);
|
|
2919
|
+
height = evaluate(`document.documentElement.scrollHeight`); // the string form
|
|
2370
2920
|
```
|
|
2371
2921
|
|
|
2372
2922
|
The extra arguments reach the body by one rule: none → `undefined`,
|
|
@@ -2375,15 +2925,33 @@ destructures. So one argument is `function(x)`, not `function([x])` —
|
|
|
2375
2925
|
that one fails with `2 is not iterable`.
|
|
2376
2926
|
|
|
2377
2927
|
```js
|
|
2378
|
-
doubled = evaluate(
|
|
2928
|
+
doubled = evaluate((n) => n * 2, 21); // one → the value
|
|
2379
2929
|
result = evaluate(
|
|
2380
|
-
|
|
2930
|
+
([a, b]) => window.myApp.compute(a, b),
|
|
2381
2931
|
10, 20 // two → one array
|
|
2382
2932
|
);
|
|
2383
2933
|
```
|
|
2384
2934
|
|
|
2385
|
-
|
|
2386
|
-
(
|
|
2935
|
+
Page code built from scenario values is an error
|
|
2936
|
+
(`validator:evaluate-interpolation`): a `${…}` in it, a `+` of a value,
|
|
2937
|
+
or a variable that is ever given one — a value in it would become code
|
|
2938
|
+
of the page. Text the source spells out passes: a string, a template
|
|
2939
|
+
without `${…}`, `+` of those, or a variable every assignment of which
|
|
2940
|
+
is one, declared with `let` or `const` or not at all, or the variable
|
|
2941
|
+
of a `for…of` over an array literal of such texts. A function handed
|
|
2942
|
+
to the page reads only its own parameters
|
|
2943
|
+
(`validator:page-code-closure`). Pass values as arguments instead. The
|
|
2944
|
+
run checks both rules before it starts, in the test and in every helper
|
|
2945
|
+
of `_helpers/` it loads, and stops on them.
|
|
2946
|
+
|
|
2947
|
+
The validator reads a function literal with the file: its syntax, and
|
|
2948
|
+
the scenario names it must not read. A string the source spells out (a
|
|
2949
|
+
literal, or a template without `${…}`) is parsed only as one JavaScript
|
|
2950
|
+
expression: a syntax error is reported with its line and column inside
|
|
2951
|
+
the string (`validator:page-code-syntax`), and the run refuses the step.
|
|
2952
|
+
A string that parses gets an info with the rewrite to a function
|
|
2953
|
+
(`validator:page-code-string`). Text built with `+` or held in a
|
|
2954
|
+
variable is not parsed at all.
|
|
2387
2955
|
|
|
2388
2956
|
A page whose main thread is busy — a script loop, a long task — cannot
|
|
2389
2957
|
start the script. `evaluate` then fails the step after the action timeout
|
|
@@ -2397,7 +2965,7 @@ The body gets the element first, then the extras by the same rule as
|
|
|
2397
2965
|
array.
|
|
2398
2966
|
|
|
2399
2967
|
```js
|
|
2400
|
-
ok = evaluateOnLocator(getByRole('main'),
|
|
2968
|
+
ok = evaluateOnLocator(getByRole('main'), (el, [a, b]) => el.children.length > a + b, 1, 2);
|
|
2401
2969
|
```
|
|
2402
2970
|
|
|
2403
2971
|
Reach for it only for what no typed call reads — a style is
|
|
@@ -2574,273 +3142,552 @@ step.soft("Question", {tag: q.id}, () => {
|
|
|
2574
3142
|
|
|
2575
3143
|
---
|
|
2576
3144
|
|
|
2577
|
-
##
|
|
3145
|
+
## Signatures
|
|
3146
|
+
|
|
3147
|
+
Every function with the types it takes, read from the same contract the
|
|
3148
|
+
linter and the run check a call against: a call these lines refuse is
|
|
3149
|
+
refused before the run and at the call. Each options object lists one key
|
|
3150
|
+
per option; an older spelling it still takes is named after the line.
|
|
3151
|
+
|
|
3152
|
+
<!-- generated:signatures — pnpm build:dsl-types writes this from the contracts -->
|
|
3153
|
+
**Navigation**
|
|
3154
|
+
|
|
3155
|
+
- `goto(url: string, options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3156
|
+
- `reload(options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3157
|
+
- `goBack(options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3158
|
+
- `goForward(options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3159
|
+
- `waitForUrl(pattern: string | RegExp, options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3160
|
+
- `waitForNavigation(options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3161
|
+
|
|
3162
|
+
**Locators**
|
|
3163
|
+
|
|
3164
|
+
- `locator(selector: string, options?: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator`
|
|
3165
|
+
- `getByRole(role: string, options?: { name?: string | RegExp; exact?: boolean; checked?: boolean; disabled?: boolean; expanded?: boolean; includeHidden?: boolean; level?: number; pressed?: boolean; selected?: boolean }): Locator`
|
|
3166
|
+
- `getByText(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3167
|
+
- `getByLabel(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3168
|
+
- `getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3169
|
+
- `getByAltText(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3170
|
+
- `getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3171
|
+
- `getByTestId(id: string): Locator`
|
|
3172
|
+
- `contentFrame(frame?: Locator): Locator`
|
|
3173
|
+
|
|
3174
|
+
**Refining a locator**
|
|
3175
|
+
|
|
3176
|
+
- `filter(receiver: Locator, options: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator`
|
|
3177
|
+
- `first(receiver: Locator): Locator`
|
|
3178
|
+
- `last(receiver: Locator): Locator`
|
|
3179
|
+
- `nth(receiver: Locator, index: number): Locator`
|
|
3180
|
+
- `randomNth(receiver: Locator): Locator`
|
|
3181
|
+
|
|
3182
|
+
**Actions**
|
|
3183
|
+
|
|
3184
|
+
- `click(locator: Locator, options?: { force?: boolean; position?: any; modifiers?: unknown[]; button?: any; clickCount?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3185
|
+
- `doubleClick(locator: Locator, options?: { force?: boolean; position?: any; modifiers?: unknown[]; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3186
|
+
- `check(locator: Locator, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3187
|
+
- `uncheck(locator: Locator, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3188
|
+
- `hover(locator: Locator, options?: { force?: boolean; position?: any; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3189
|
+
- `scrollIntoView(locator: Locator): void`
|
|
3190
|
+
- `fill(locator: Locator, text: string, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3191
|
+
- `press(locator: Locator, key: string, options?: { delay?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3192
|
+
- `selectOption(locator: Locator, value: string | string[] | { value?: string; label?: string; index?: number }, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3193
|
+
- `dragAndDrop(source: Locator, target: Locator, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3194
|
+
- `uploadFile(input: Locator, files: any): void`
|
|
3195
|
+
- `clipboardPaste(target: Locator, text: string): void`
|
|
3196
|
+
|
|
3197
|
+
**Waits and the page clock**
|
|
3198
|
+
|
|
3199
|
+
- `waitFor(locator: Locator, options?: { state?: string; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3200
|
+
- `waitForText(text: string | RegExp, options?: { state?: string; exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3201
|
+
- `waitForCount(locator: Locator, count: number, options?: { exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3202
|
+
- `waitForAnimations(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3203
|
+
- `pause(ms: number): void`
|
|
3204
|
+
- `waitForDownload(options?: { timeoutMs?: number; name?: string | RegExp }): any`
|
|
3205
|
+
- `clockFreeze(iso: string): void`
|
|
3206
|
+
- `clockTick(ms: number): void`
|
|
3207
|
+
- `clockRun(): void`
|
|
3208
|
+
|
|
3209
|
+
**Assertions**
|
|
3210
|
+
|
|
3211
|
+
- `assertText(locator: Locator, text: string | RegExp, options?: { exact?: boolean; not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3212
|
+
- `assertTexts(locator: Locator, expected: unknown[], options?: { exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3213
|
+
- `assertAttribute(locator: Locator, name: string, value: string | RegExp, options?: { exact?: boolean; not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3214
|
+
- `assertVisible(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3215
|
+
- `assertHidden(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3216
|
+
- `assertNeverAppears(locator: Locator, options: { withinMs?: number }): void`
|
|
3217
|
+
- `assertValue(locator: Locator, value: string, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3218
|
+
- `assertCount(locator: Locator, count: number, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3219
|
+
- `assertUrl(pattern: string | RegExp, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3220
|
+
- `assertJudge(locator: Locator, rubric: string): void`
|
|
3221
|
+
- `assertScreenshot(nameOrLocator: any, nameOrOptions?: any, options?: { maxDiffRatio?: number; threshold?: number; mask?: unknown[]; ignore?: unknown[]; fullPage?: boolean }): void`
|
|
3222
|
+
- `assertEqual(actual: any, expected: any): void`
|
|
3223
|
+
- `assertTrue(condition: boolean, message?: string): void`
|
|
3224
|
+
- `assertSchema(value: any, schema: any): void`
|
|
3225
|
+
- `assertFileHas(path: string, needle: string | RegExp, options?: { timeoutMs?: number }): void`
|
|
3226
|
+
- `assertFileLacks(path: string, needle: string | RegExp, options?: { withinMs?: number }): void`
|
|
3227
|
+
- `skip(reason: string, condition?: boolean): void`
|
|
3228
|
+
- `setTestTimeout(ms: number): void`
|
|
3229
|
+
|
|
3230
|
+
**Reading the page and values**
|
|
3231
|
+
|
|
3232
|
+
- `clipboardRead(): string`
|
|
3233
|
+
- `assertClipboard(expected: string | RegExp, options?: { timeoutMs?: number }): void`
|
|
3234
|
+
- `count(locator: Locator): number`
|
|
3235
|
+
- `textContent(locator: Locator): string`
|
|
3236
|
+
- `texts(locator: Locator): any`
|
|
3237
|
+
- `inputValue(locator: Locator): string`
|
|
3238
|
+
- `isVisible(locator: Locator): boolean`
|
|
3239
|
+
- `isChecked(locator: Locator): boolean`
|
|
3240
|
+
- `isDisabled(locator: Locator): boolean`
|
|
3241
|
+
- `isEnabled(locator: Locator): boolean`
|
|
3242
|
+
- `hasAttribute(locator: Locator, name: string): boolean`
|
|
3243
|
+
- `computedStyle(locator: Locator, property: string): string`
|
|
3244
|
+
- `getImageSize(locator: Locator): any`
|
|
3245
|
+
- `hasAnimation(locator: Locator): boolean`
|
|
3246
|
+
- `animations(locator: Locator): any`
|
|
3247
|
+
- `randomFirstName(): string`
|
|
3248
|
+
- `randomLastName(): string`
|
|
3249
|
+
- `randomEmail(): string`
|
|
3250
|
+
- `randomText(length: number): string`
|
|
3251
|
+
- `randomWord(length?: number): string`
|
|
3252
|
+
- `json(value: any): string`
|
|
3253
|
+
- `textContains(haystack: string, needle: string): boolean`
|
|
3254
|
+
- `textJoin(parts: unknown[]): string`
|
|
3255
|
+
- `nowMs(): number`
|
|
3256
|
+
- `today(): string`
|
|
3257
|
+
- `daysFromNow(days: number): string`
|
|
3258
|
+
- `textMatches(text: string, pattern: any): any`
|
|
3259
|
+
- `parseJson(text: string): any`
|
|
3260
|
+
- `urlParam(url: string, key: string): any`
|
|
3261
|
+
- `toNumber(text: any, options?: { decimal?: string }): number`
|
|
3262
|
+
- `round(n: number, digits?: number): number`
|
|
3263
|
+
- `formatNumber(n: number, options?: { locale?: string; minFractionDigits?: number; maxFractionDigits?: number }): string`
|
|
3264
|
+
- `env(name: string, fallback?: any): any`
|
|
3265
|
+
|
|
3266
|
+
**Page state**
|
|
3267
|
+
|
|
3268
|
+
- `getAttribute(locator: Locator, attribute: string): string`
|
|
3269
|
+
- `getInnerText(locator: Locator): string`
|
|
3270
|
+
- `getInputValue(locator: Locator): string`
|
|
3271
|
+
- `boundingBox(locator: Locator): any`
|
|
3272
|
+
- `getTitle(): string`
|
|
3273
|
+
- `getUrl(): string`
|
|
3274
|
+
- `log(message: any, ...args: unknown[]): void`
|
|
3275
|
+
|
|
3276
|
+
**Storage and cookies**
|
|
3277
|
+
|
|
3278
|
+
- `setLocalStorage(key: string, value: string): void`
|
|
3279
|
+
- `getLocalStorage(key: string): string`
|
|
3280
|
+
- `setCookie(name: string, value: string, options?: { domain?: string; path?: string; expires?: number; httpOnly?: boolean; secure?: boolean; sameSite?: string }): void`
|
|
3281
|
+
- `getCookie(name: string): string`
|
|
3282
|
+
|
|
3283
|
+
**Tabs, frames, contexts, extensions**
|
|
3284
|
+
|
|
3285
|
+
- `setPage(indexOrTitle: string | number, options?: { activate?: boolean }): void`
|
|
3286
|
+
- `waitForPage(options?: { timeoutMs?: number }): number`
|
|
3287
|
+
- `bringToFront(index?: number): void`
|
|
3288
|
+
- `setPageHidden(hidden: boolean, index?: number): void`
|
|
3289
|
+
- `newPage(url?: string): number`
|
|
3290
|
+
- `closePage(index?: number): void`
|
|
3291
|
+
- `setViewport(size: { width?: number; height?: number } | null): void`
|
|
3292
|
+
- `emulateMedia(media: { reducedMotion?: "reduce" | "no-preference"; colorScheme?: "light" | "dark" | "no-preference" }): void`
|
|
3293
|
+
- `newContext(): number`
|
|
3294
|
+
- `setContext(index: number): void`
|
|
3295
|
+
- `enterFrame(frame: Locator): void`
|
|
3296
|
+
- `exitFrame(): void`
|
|
3297
|
+
- `addVirtualAuthenticator(options?: { protocol?: string; transport?: string; hasResidentKey?: boolean; hasUserVerification?: boolean; isUserVerified?: boolean; automaticPresenceSimulation?: boolean }): string`
|
|
3298
|
+
- `virtualCredentials(id?: string): any`
|
|
3299
|
+
- `removeVirtualAuthenticator(id: string): void`
|
|
3300
|
+
- `grantPermissions(permissions: string[], options?: { origin?: string }): void`
|
|
3301
|
+
- `setOffline(offline: boolean): void`
|
|
3302
|
+
- `waitForServiceWorker(options?: { timeoutMs?: number; url?: string | RegExp }): string`
|
|
3303
|
+
- `extensionId(): string`
|
|
3304
|
+
- `evaluateInServiceWorker(jsBody: any, ...args: unknown[]): any`
|
|
3305
|
+
|
|
3306
|
+
**Data, files, network, processes**
|
|
3307
|
+
|
|
3308
|
+
- `shell(cmd: string, ...args: unknown[]): any`
|
|
3309
|
+
- `waitForFile(path: string, pattern?: any, options?: { timeoutMs?: number }): string`
|
|
3310
|
+
- `assertNoFile(path: string, pattern?: any, options?: { withinMs?: number }): void`
|
|
3311
|
+
- `waitForJsonLine(path: string, filter: any, options?: { timeoutMs?: number }): any`
|
|
3312
|
+
- `assertNoJsonLine(path: string, filter: any, options?: { withinMs?: number }): void`
|
|
3313
|
+
- `readJsonLine(path: string, filter: any): any`
|
|
3314
|
+
- `readJson(path: string): any`
|
|
3315
|
+
- `readFile(path: string, options?: { encoding?: string }): string`
|
|
3316
|
+
- `readFileInfo(path: string): any`
|
|
3317
|
+
- `waitForFileCount(path: string, pattern: any, count: number, options?: { timeoutMs?: number }): number`
|
|
3318
|
+
- `assertFileCount(path: string, pattern: any, count: number): void`
|
|
3319
|
+
- `dbQuery(sql: string, ...args: unknown[]): any`
|
|
3320
|
+
- `dbExec(sql: string, ...args: unknown[]): number`
|
|
3321
|
+
- `apiCall(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS", path: string, body?: any, headers?: any, options?: { base?: string; timeoutMs?: number }): any`
|
|
3322
|
+
- `upload(path: string, options?: { field?: string; fields?: any }): any`
|
|
3323
|
+
- `mockRoute(glob: string, response: any): void`
|
|
3324
|
+
- `unmockRoute(glob?: string): void`
|
|
3325
|
+
- `waitForRequest(glob: string, options?: { timeoutMs?: number }): any`
|
|
3326
|
+
- `waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any`
|
|
3327
|
+
- `assertNoRequest(glob: string, options?: { since?: number }): void`
|
|
3328
|
+
- `openTerminal(app: string, options?: { host?: any }): number`
|
|
3329
|
+
- `setTerminal(index: number): void`
|
|
3330
|
+
- `closeTerminal(): void`
|
|
3331
|
+
- `terminalType(text: string, options?: { echo?: boolean }): void`
|
|
3332
|
+
- `terminalPress(key: string): void`
|
|
3333
|
+
- `terminalWaitForText(text: string | RegExp, options?: { not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3334
|
+
- `terminalAssertText(text: string | RegExp, options?: { not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3335
|
+
- `terminalResize(cols: number, rows: number): void`
|
|
3336
|
+
- `terminalScreenshot(name?: string): string`
|
|
3337
|
+
- `mcpStart(command: string, args?: string[], options?: { env?: any; cwd?: any; timeoutMs?: number }): any`
|
|
3338
|
+
- `mcpCall(server: any, tool: string, args?: any, options?: { timeoutMs?: number; allowError?: any }): any`
|
|
3339
|
+
- `mcpWaitNotification(server: any, method: string, options?: { timeoutMs?: number; match?: any }): any`
|
|
3340
|
+
- `mcpStop(server: any): void`
|
|
3341
|
+
- `vmAvailable(): boolean`
|
|
3342
|
+
- `vmClone(image: string): string`
|
|
3343
|
+
- `vmRun(name: string, options?: { timeoutMs?: number }): string`
|
|
3344
|
+
- `vmIp(name: string, options?: { timeoutMs?: number }): string`
|
|
3345
|
+
- `vmStop(name: string): void`
|
|
3346
|
+
- `vmDelete(name: string): void`
|
|
3347
|
+
|
|
3348
|
+
**Diagnostics**
|
|
3349
|
+
|
|
3350
|
+
- `screenshot(name?: string, options?: { fullPage?: boolean }): string`
|
|
3351
|
+
- `note(label: string, value: any): void`
|
|
3352
|
+
- `consoleEntries(options?: { level?: any; since?: number }): any`
|
|
3353
|
+
- `pageErrors(options?: { since?: number }): any`
|
|
3354
|
+
- `assertNoConsoleErrors(options?: { includePageErrors?: boolean; since?: number }): void`
|
|
3355
|
+
|
|
3356
|
+
**Page code (last resort)**
|
|
3357
|
+
|
|
3358
|
+
- `evaluate(jsBody: any, ...args: unknown[]): any`
|
|
3359
|
+
- `evaluateOnLocator(locator: Locator, jsBody: any, ...args: unknown[]): any`
|
|
3360
|
+
<!-- /generated:signatures -->
|
|
3361
|
+
|
|
3362
|
+
---
|
|
3363
|
+
|
|
3364
|
+
## The language — JavaScript
|
|
2578
3365
|
|
|
2579
|
-
|
|
2580
|
-
|
|
3366
|
+
A scenario file is JavaScript (ES2020), run by unotest's own
|
|
3367
|
+
interpreter, not by Node. The parser reads all of JavaScript; what the
|
|
3368
|
+
scenario language leaves out is refused with what to write instead —
|
|
3369
|
+
by `lint`, by `e2e` before the browser starts, and by the run when it
|
|
3370
|
+
gets there. The list is the table in
|
|
3371
|
+
[Outside the language](#outside-the-language). Everything else works as
|
|
3372
|
+
in JavaScript: `let` / `const` / `var`, arrows and closures, `while`,
|
|
3373
|
+
`for…of`, `try` / `catch`, destructuring, spread, template strings,
|
|
3374
|
+
`?.` and `??`.
|
|
2581
3375
|
|
|
2582
|
-
|
|
3376
|
+
Two things set it apart:
|
|
3377
|
+
|
|
3378
|
+
- **Every call to the page or the system is awaited for you.**
|
|
3379
|
+
`click(…)`, `apiCall(…)`, `textContent(…)` return their result, not a
|
|
3380
|
+
promise. `await` is allowed inside an `async function` and changes
|
|
3381
|
+
nothing.
|
|
3382
|
+
- **The library is a white list.** `Math`, `JSON`, `Object`, string,
|
|
3383
|
+
number and array methods are the ones in
|
|
3384
|
+
[The library](#the-library); a member outside it is a lint error, not
|
|
3385
|
+
`undefined` at run time.
|
|
3386
|
+
|
|
3387
|
+
### A file: tests, helpers, constants
|
|
3388
|
+
|
|
3389
|
+
- **`function test_*() { … }`** — a test. A file may hold several; each
|
|
2583
3390
|
is its own run with its own browser context, retry and verdict, and the
|
|
2584
3391
|
viewer shows it as its own row under the file. `e2e <file>` plays them
|
|
2585
3392
|
in order; `e2e <file> --test <name>` plays one. Functions of the file
|
|
2586
3393
|
are shared between its tests, state is not.
|
|
2587
|
-
- **Top level of a file — function
|
|
2588
|
-
Nothing else there runs: `BASE = 'x'` above `test_*`
|
|
2589
|
-
`
|
|
2590
|
-
|
|
2591
|
-
`
|
|
2592
|
-
|
|
2593
|
-
|
|
2594
|
-
`function base_url() { return
|
|
2595
|
-
|
|
2596
|
-
|
|
2597
|
-
`
|
|
2598
|
-
|
|
2599
|
-
`
|
|
2600
|
-
|
|
2601
|
-
|
|
2602
|
-
|
|
3394
|
+
- **Top level of a file — function declarations and `const` literals.**
|
|
3395
|
+
Nothing else there runs: `let BASE = 'x'` or a call above `test_*`
|
|
3396
|
+
is refused (`validator:unsupported-statement`). A shared fixed value is
|
|
3397
|
+
a const holding a literal — a number, a string, `true` / `false` /
|
|
3398
|
+
`null`, or an array or object of those — visible in every function, as
|
|
3399
|
+
helper functions are (`const BASE = 'https://x.test';`). A computed
|
|
3400
|
+
value or an arrow is a function instead
|
|
3401
|
+
(`validator:top-level-const`): `function base_url() { return
|
|
3402
|
+
env('BASE'); }`.
|
|
3403
|
+
- **A `test_*` body is a list of steps.** Each statement directly in
|
|
3404
|
+
it is a `step(…)` / `step.soft(…)`, a `teardown(…)`, `skip(…)` /
|
|
3405
|
+
`setTestTimeout(…)`, or a declaration that runs nothing — `let id;`,
|
|
3406
|
+
`const LIMIT = 5;`, a literal at most. Anything else there — a call,
|
|
3407
|
+
an `if`, a `return` — is `validator:step-coverage`. Inside a step, and
|
|
3408
|
+
in a helper or a `flow_*`, everything below works.
|
|
3409
|
+
|
|
3410
|
+
### Variables and scope
|
|
3411
|
+
|
|
3412
|
+
`let` and `const` are block-scoped, `var` and parameters belong to the
|
|
3413
|
+
function, as in JavaScript. A `const` is not assigned again: `lint`
|
|
3414
|
+
refuses it (`validator:const-assign`) and a run fails at that line. The
|
|
3415
|
+
array or object it holds can still change (`ids.push(x)`).
|
|
3416
|
+
|
|
3417
|
+
**A value one step hands to the next** is declared in the `test_*`
|
|
3418
|
+
body, above the steps; a `let` inside a step stays in that step, as in
|
|
3419
|
+
JavaScript:
|
|
3420
|
+
|
|
3421
|
+
```js
|
|
3422
|
+
function test_order() {
|
|
3423
|
+
let orderId;
|
|
3424
|
+
step('Place the order', () => {
|
|
3425
|
+
orderId = textContent(getByTestId('order-id'));
|
|
3426
|
+
});
|
|
3427
|
+
step('Find it in the list', () => {
|
|
3428
|
+
assertVisible(getByRole('row', {name: orderId}));
|
|
3429
|
+
});
|
|
3430
|
+
}
|
|
3431
|
+
```
|
|
2603
3432
|
|
|
2604
|
-
|
|
2605
|
-
|
|
2606
|
-
|
|
2607
|
-
|
|
2608
|
-
|
|
2609
|
-
|
|
2610
|
-
|
|
2611
|
-
}
|
|
2612
|
-
pause(2000); // reason: ingestion job is async, poll every 2s
|
|
2613
|
-
}
|
|
2614
|
-
assertTrue(done, 'job never reached DONE');
|
|
2615
|
-
```
|
|
3433
|
+
**Assignment without a declaration** works too: it declares the name in
|
|
3434
|
+
the nearest top-level function — the `test_*`, the `flow_*` or the
|
|
3435
|
+
helper. `lint` notes such a name once, as information
|
|
3436
|
+
(`validator:implicit-declaration`), with the declaration to write. A
|
|
3437
|
+
helper's names do not leak into its caller.
|
|
3438
|
+
|
|
3439
|
+
### Functions and callbacks
|
|
2616
3440
|
|
|
2617
|
-
|
|
2618
|
-
|
|
2619
|
-
|
|
2620
|
-
|
|
2621
|
-
|
|
2622
|
-
|
|
2623
|
-
|
|
2624
|
-
|
|
2625
|
-
|
|
2626
|
-
|
|
2627
|
-
|
|
2628
|
-
|
|
2629
|
-
|
|
2630
|
-
|
|
2631
|
-
|
|
2632
|
-
|
|
2633
|
-
|
|
2634
|
-
|
|
2635
|
-
|
|
2636
|
-
|
|
2637
|
-
|
|
2638
|
-
|
|
2639
|
-
|
|
2640
|
-
|
|
2641
|
-
|
|
2642
|
-
|
|
2643
|
-
|
|
2644
|
-
|
|
2645
|
-
|
|
2646
|
-
|
|
2647
|
-
|
|
2648
|
-
|
|
2649
|
-
|
|
2650
|
-
|
|
2651
|
-
|
|
2652
|
-
|
|
2653
|
-
|
|
2654
|
-
|
|
2655
|
-
|
|
2656
|
-
|
|
2657
|
-
|
|
2658
|
-
|
|
2659
|
-
inspection.
|
|
2660
|
-
|
|
2661
|
-
The only arrows are the fixed ones of `step(...)`, `teardown(...)` and
|
|
2662
|
-
`waitUntil(...)`, and their body may be a block: `waitUntil(() => {
|
|
2663
|
-
n = count(rows); return n > 3; })`. A lambda goes only into `filter`,
|
|
2664
|
-
`map`, `find` and `some` on an array (`a.map(x => x.id)`); anywhere
|
|
2665
|
-
else, and `+=`, `for…of`, `o.a = 2` and the like, are refused by `lint`
|
|
2666
|
-
with what to write instead.
|
|
2667
|
-
|
|
2668
|
-
See `vendor/dsl/EXTENSIONS.md` for the
|
|
2669
|
-
exact grammar deltas from the upstream parser.
|
|
2670
|
-
|
|
2671
|
-
### Escape rules
|
|
2672
|
-
|
|
2673
|
-
In a quoted string (`'…'` or `"…"`):
|
|
2674
|
-
|
|
2675
|
-
| Escape | Gives |
|
|
2676
|
-
|---|---|
|
|
2677
|
-
| `\n` `\t` `\r` `\f` `\v` | the control character |
|
|
2678
|
-
| `\\` | one backslash |
|
|
2679
|
-
| `\'` in `'…'`, `\"` in `"…"` | the quote |
|
|
2680
|
-
| `\0` (no digit after it) | the NUL character |
|
|
2681
|
-
| `\xHH` | the character with that hex code: `"\xA0"` is a non-breaking space |
|
|
2682
|
-
| `\uXXXX` | the same with four hex digits: `'\u00A0'` |
|
|
3441
|
+
Functions are values: an arrow or a `function` can be kept in a
|
|
3442
|
+
variable, passed to a helper, returned, and it closes over the variables
|
|
3443
|
+
around it. Parameters take defaults and rest (`function f(a, b = 2,
|
|
3444
|
+
...more)`), nested functions are hoisted in their function.
|
|
3445
|
+
|
|
3446
|
+
```js
|
|
3447
|
+
const byStatus = (status) => (row) => row.status == status;
|
|
3448
|
+
const open = rows.filter(byStatus('open'));
|
|
3449
|
+
let total = 0;
|
|
3450
|
+
rows.forEach((r) => { total += r.amount; });
|
|
3451
|
+
```
|
|
3452
|
+
|
|
3453
|
+
A callback writes the outer variable for real, as `total` above shows.
|
|
3454
|
+
Every call inside a callback is a step of its own in the run, as
|
|
3455
|
+
everywhere.
|
|
3456
|
+
|
|
3457
|
+
### Control flow
|
|
3458
|
+
|
|
3459
|
+
`if` / `else`, `for`, `for…of`, `for…in` (own keys), `while`,
|
|
3460
|
+
`do…while`, `break`, `continue`, `switch`, `return`, `throw`, `try` /
|
|
3461
|
+
`catch` / `finally`, `cond ? a : b` — as in JavaScript. Labels are
|
|
3462
|
+
outside the language.
|
|
3463
|
+
|
|
3464
|
+
One check is stricter than JavaScript: an `if` whose condition `lint`
|
|
3465
|
+
knows to be a number, a string or a locator is `validator:if-shape` —
|
|
3466
|
+
write the comparison, `if (rows.length > 0)`, `if (name != '')`.
|
|
3467
|
+
|
|
3468
|
+
```js
|
|
3469
|
+
let job;
|
|
3470
|
+
let tries = 0;
|
|
3471
|
+
do {
|
|
3472
|
+
job = apiCall('GET', '/jobs/1');
|
|
3473
|
+
if (job.body.status != 'DONE') pause(2000); // reason: the job is async
|
|
3474
|
+
tries++;
|
|
3475
|
+
} while (job.body.status != 'DONE' && tries < 30);
|
|
3476
|
+
assertEqual(job.body.status, 'DONE');
|
|
3477
|
+
```
|
|
3478
|
+
|
|
3479
|
+
A loop that never ends does not hang the run: the run counts the
|
|
3480
|
+
statements it plays and stops at its budget (`maxSteps budget (100000)
|
|
3481
|
+
exhausted`); the test ends as errored ‼, a fault of the script, not
|
|
3482
|
+
failed.
|
|
2683
3483
|
|
|
2684
|
-
|
|
2685
|
-
|
|
2686
|
-
|
|
2687
|
-
|
|
2688
|
-
the
|
|
2689
|
-
|
|
3484
|
+
**`try` / `catch`.** `catch (e)` takes what was thrown, as thrown:
|
|
3485
|
+
`throw {code: 7}` gives `e.code`. A failed action — a click that found
|
|
3486
|
+
nothing, a failed assertion — arrives as `{name, message}`, with no
|
|
3487
|
+
stack. The parameter may be left out (`catch { … }`). An error caught by
|
|
3488
|
+
the scenario is not a failure: the run goes on, and the debugger does
|
|
3489
|
+
not stop on it. `catch` does not take control flow — a `skip()`, a
|
|
3490
|
+
`return`, `break` / `continue` — nor the step budget. To give the stand back
|
|
3491
|
+
whatever happens, use [`teardown`](#teardown--give-the-stand-back), not
|
|
3492
|
+
`finally`: a teardown also plays when the run is stopped or times out.
|
|
2690
3493
|
|
|
2691
|
-
|
|
2692
|
-
|
|
2693
|
-
|
|
3494
|
+
**`return`** leaves the function it is in. Inside a step it leaves
|
|
3495
|
+
that step's callback, and the next step runs; in a helper or a callback
|
|
3496
|
+
it returns from them. Directly in a `test_*` body it is
|
|
3497
|
+
`validator:step-coverage`: a test that does not apply here ends with
|
|
3498
|
+
`skip(reason)`.
|
|
2694
3499
|
|
|
2695
|
-
###
|
|
3500
|
+
### Values and operators
|
|
2696
3501
|
|
|
2697
|
-
|
|
3502
|
+
- **Equality and arithmetic** are JavaScript's: `==` is loose (`"1" ==
|
|
3503
|
+
1`), `===` strict, `null == undefined`. DOM reads (`textContent`,
|
|
3504
|
+
`getInputValue`, `getAttribute`) return strings — compare them with a
|
|
3505
|
+
number by `==`, or convert with `Number(s)` / `toNumber(s)`.
|
|
3506
|
+
- **`&&`, `||` and `??` give an operand**, as in JavaScript:
|
|
3507
|
+
`env('API_URL') ?? 'http://localhost:3000'`, `name || 'anonymous'`.
|
|
3508
|
+
The right side runs only when the left one does not decide.
|
|
3509
|
+
- **`?.`** reads through a missing value: `res.body?.items?.[0]?.id`,
|
|
3510
|
+
`o.callback?.()`.
|
|
3511
|
+
- **`typeof`, `in`** (own keys), `delete`, `void`, `++` / `--`, the
|
|
3512
|
+
compound assignments up to `**=`, the comma operator — as in
|
|
3513
|
+
JavaScript.
|
|
3514
|
+
- **`+` and `<` apply to numbers and strings only.** On an object or an
|
|
3515
|
+
array they fail the step (`Operator "+" does not apply to an object`)
|
|
3516
|
+
instead of giving `[object Object]`: combine or compare the fields.
|
|
3517
|
+
- **A missing property or argument is `undefined`.** A host function
|
|
3518
|
+
that finds nothing returns `null`; `x == null` is true for both.
|
|
2698
3519
|
|
|
2699
|
-
|
|
3520
|
+
### Strings and templates
|
|
2700
3521
|
|
|
2701
|
-
|
|
2702
|
-
|
|
2703
|
-
|
|
2704
|
-
|
|
2705
|
-
|
|
2706
|
-
| `s.startsWith(prefix)` | `boolean` | |
|
|
2707
|
-
| `s.split(separator)` | array of strings | as in JS: parts keep their spaces, a missing separator gives one part |
|
|
3522
|
+
Quoted strings decode escapes as in JavaScript: `'\n'` is a line break,
|
|
3523
|
+
`'\u00A0'` a non-breaking space, `'\\'` one backslash. A malformed `\x`
|
|
3524
|
+
or `\u` (`'\u12'`) is a parse error. A backslash before any other
|
|
3525
|
+
character is dropped, as JavaScript drops it: `'\d+'` is `d+`. For a
|
|
3526
|
+
regex write a `/…/` literal, or double the backslash (`'\\d+'`).
|
|
2708
3527
|
|
|
2709
|
-
|
|
2710
|
-
|
|
3528
|
+
Backticks are template strings, with `${…}` interpolation and the same
|
|
3529
|
+
escapes. `` String.raw`…` `` keeps backslashes as written — the only tag
|
|
3530
|
+
the language has.
|
|
2711
3531
|
|
|
2712
3532
|
```js
|
|
2713
|
-
|
|
2714
|
-
|
|
2715
|
-
|
|
2716
|
-
assertTrue(getUrl().startsWith('https://'), getUrl());
|
|
2717
|
-
ids = 'a, b'.split(', '); // ['a', 'b']
|
|
3533
|
+
const n = 3;
|
|
3534
|
+
note('rows', `found ${n} rows`);
|
|
3535
|
+
assertText(getByRole('cell', {name: /^Total/}), '1\u00A0250');
|
|
2718
3536
|
```
|
|
2719
3537
|
|
|
2720
|
-
|
|
2721
|
-
(`validator:unsupported-string-member`); `s.padStart(3)` does not
|
|
2722
|
-
reach the browser. A member of the list used on a value that turns out
|
|
2723
|
-
not to be a string at run time — a number, or `null` from a missing
|
|
2724
|
-
field — fails the step with the value's type in the message.
|
|
3538
|
+
Two lint rules guard templates:
|
|
2725
3539
|
|
|
2726
|
-
|
|
2727
|
-
|
|
3540
|
+
- `validator:evaluate-interpolation` (error) — code handed to the page
|
|
3541
|
+
that the scenario builds from values (`${…}`, `+` of a value, a
|
|
3542
|
+
variable ever given one): the value would become code of the page.
|
|
3543
|
+
Write fixed text or a function, and pass the value as an argument.
|
|
3544
|
+
- `validator:template-escape-changed` (warning) — a backtick string
|
|
3545
|
+
with a backslash escape JavaScript drops (`\s` reads as `s`, `\.`
|
|
3546
|
+
as `.`): a scenario written for the earlier raw backticks loses
|
|
3547
|
+
characters. Double the backslash or use `` String.raw`…` ``. Escapes
|
|
3548
|
+
JavaScript reads as meant (`\n`, `\\`, `\u…`) are not reported.
|
|
2728
3549
|
|
|
2729
|
-
|
|
2730
|
-
|
|
2731
|
-
|
|
2732
|
-
|
|
2733
|
-
|
|
3550
|
+
### Regex literals
|
|
3551
|
+
|
|
3552
|
+
A `/…/flags` literal is a JavaScript RegExp: every flag and syntax
|
|
3553
|
+
Node accepts — `i`, `g`, `m`, `s`, `u`, `y`, `d`, `v`, named groups,
|
|
3554
|
+
lookbehind. In a matcher slot (`getByText(/Items \d+/i)`) it goes to
|
|
3555
|
+
Playwright as that RegExp; in the scenario it answers `test`, `source` and
|
|
3556
|
+
`flags`, and the string methods `match`, `matchAll`, `replace`,
|
|
3557
|
+
`replaceAll`, `search` and `split` take it.
|
|
3558
|
+
|
|
3559
|
+
`match` gives an array of the match and its groups, or `null`; there is
|
|
3560
|
+
no `.groups` — read a named group by its index: `s.match(/(?<id>\d+)/)[1]`.
|
|
2734
3561
|
|
|
2735
|
-
|
|
2736
|
-
object in that slot is still an `arg-kind` error.
|
|
3562
|
+
### Objects, arrays, indexes
|
|
2737
3563
|
|
|
2738
|
-
|
|
3564
|
+
Object literals take shorthand, computed keys, methods and spread
|
|
3565
|
+
(`{...base, id}`); a property is set as in JavaScript (`o.k = v`,
|
|
3566
|
+
`o['k'] = v`, nested too). Destructuring works in declarations,
|
|
3567
|
+
parameters, `for…of` and `catch`:
|
|
2739
3568
|
|
|
2740
3569
|
```js
|
|
2741
|
-
|
|
2742
|
-
|
|
2743
|
-
first = dbQuery('SELECT id FROM users ORDER BY id')[0].id;
|
|
3570
|
+
const {status, body: {items = []}} = apiCall('GET', '/documents');
|
|
3571
|
+
for (const [key, value] of Object.entries(counts)) note(key, value);
|
|
2744
3572
|
```
|
|
2745
3573
|
|
|
2746
|
-
|
|
3574
|
+
A variable holds the array or object itself, not a copy: after
|
|
3575
|
+
`b = a; a.push(1)`, `b` has the new element too. `arr[i] = v` takes an
|
|
3576
|
+
index from `0` to `arr.length` — the length appends, an index further
|
|
3577
|
+
out fails the step instead of leaving holes. The keys `__proto__`,
|
|
3578
|
+
`constructor` and `prototype` cannot be assigned, and a value has no
|
|
3579
|
+
prototype to reach: `o.constructor` and `[].map.call` are `undefined`.
|
|
2747
3580
|
|
|
2748
|
-
|
|
3581
|
+
**Locators are not arrays.** An index on a locator is refused
|
|
3582
|
+
(`validator:locator-index-access`):
|
|
2749
3583
|
|
|
2750
|
-
|
|
2751
|
-
|
|
2752
|
-
treats as false. An array or an object is truthy, empty or not. `!`
|
|
2753
|
-
binds tighter than any other operator: `!a && b` is `(!a) && b`.
|
|
2754
|
-
|
|
2755
|
-
```js
|
|
2756
|
-
if (!isVisible(getByRole('dialog'))) { log('dialog closed'); }
|
|
2757
|
-
assertTrue(!out.stdout.includes('error'), out.stdout);
|
|
3584
|
+
```js bad
|
|
3585
|
+
const first = getByRole('row')[0];
|
|
2758
3586
|
```
|
|
2759
3587
|
|
|
2760
|
-
|
|
2761
|
-
length. Other JS array methods (`pop`, `join`, `reduce`, …) are not
|
|
2762
|
-
there; `length`, `sortBy` and the lambda methods `filter` / `map` /
|
|
2763
|
-
`find` / `some` ([let, const and lambdas](#let-const-and-lambdas)) are.
|
|
3588
|
+
Pick one with `.nth(i)`, `.first()`, `.filter({…})`:
|
|
2764
3589
|
|
|
2765
3590
|
```js
|
|
2766
|
-
|
|
2767
|
-
|
|
2768
|
-
for (i = 0; i < count(rows); i = i + 1) {
|
|
2769
|
-
ids.push(textContent(rows.nth(i)));
|
|
2770
|
-
}
|
|
2771
|
-
assertTrue(ids.length > 0, json(ids));
|
|
3591
|
+
const first = getByRole('row').first();
|
|
3592
|
+
const third = getByRole('row').nth(2);
|
|
2772
3593
|
```
|
|
2773
3594
|
|
|
2774
|
-
|
|
2775
|
-
`b = a; a.push(1)`, `b` has the new element too. So does a caller whose
|
|
2776
|
-
array a helper pushed onto. A helper that assigns a new array to its
|
|
2777
|
-
parameter (`list = []`) changes only its own name. `push` on a value
|
|
2778
|
-
that is not an array — a string, a number, a `null` field — fails the
|
|
2779
|
-
step with that type in the message; on a string the linter flags it
|
|
2780
|
-
first.
|
|
3595
|
+
### The library
|
|
2781
3596
|
|
|
2782
|
-
|
|
2783
|
-
|
|
2784
|
-
`
|
|
2785
|
-
|
|
2786
|
-
|
|
2787
|
-
|
|
2788
|
-
|
|
3597
|
+
A scenario reads these names — the whole list. A member outside it is a
|
|
3598
|
+
lint error that names it: `validator:library-member` on a namespace
|
|
3599
|
+
(`Math.tau`), `validator:unsupported-string-member` on a string,
|
|
3600
|
+
`validator:unknown-member` on an array, a number, a Map or a Set.
|
|
3601
|
+
|
|
3602
|
+
| Global | Members |
|
|
3603
|
+
|---|---|
|
|
3604
|
+
| `Math` | `E` `LN10` `LN2` `LOG10E` `LOG2E` `PI` `SQRT1_2` `SQRT2`, `abs` `acos` `acosh` `asin` `asinh` `atan` `atan2` `atanh` `cbrt` `ceil` `clz32` `cos` `cosh` `exp` `expm1` `floor` `fround` `hypot` `imul` `log` `log10` `log1p` `log2` `max` `min` `pow` `round` `sign` `sin` `sinh` `random` `sqrt` `tan` `tanh` `trunc` |
|
|
3605
|
+
| `JSON` | `parse`, `stringify` |
|
|
3606
|
+
| `Number(x)` | `EPSILON` `MAX_SAFE_INTEGER` `MAX_VALUE` `MIN_SAFE_INTEGER` `MIN_VALUE` `NaN` `NEGATIVE_INFINITY` `POSITIVE_INFINITY`, `isFinite` `isInteger` `isNaN` `isSafeInteger` `parseFloat` `parseInt` |
|
|
3607
|
+
| `String(x)` | `raw` |
|
|
3608
|
+
| `Array` | `isArray`, `from`, `of` |
|
|
3609
|
+
| `Object` | `keys`, `values`, `entries`, `fromEntries`, `assign`, `hasOwn` |
|
|
3610
|
+
| functions | `parseInt`, `parseFloat`, `isNaN`, `isFinite` |
|
|
3611
|
+
|
|
3612
|
+
<!-- generated:constructors — pnpm build:dsl-types writes this from the library -->
|
|
3613
|
+
Constructors — the only globals `new` applies to: `new Map(…)`, `new Set(…)`.
|
|
3614
|
+
<!-- /generated:constructors -->
|
|
3615
|
+
|
|
3616
|
+
| Value | Members |
|
|
3617
|
+
|---|---|
|
|
3618
|
+
| string | `length`, `at` `charAt` `includes` `startsWith` `endsWith` `indexOf` `lastIndexOf` `slice` `substring` `split` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `replace` `replaceAll` `toLowerCase` `toUpperCase` `match` `matchAll` `search` `localeCompare` `normalize` |
|
|
3619
|
+
| number | `toFixed`, `toPrecision`, `toString(radix)` |
|
|
3620
|
+
| regex | `source`, `flags`, `test` |
|
|
3621
|
+
| array | `length`, `push` `pop` `shift` `unshift` `slice` `splice` `concat` `join` `reverse` `indexOf` `lastIndexOf` `includes` `at` `flat` `fill` `toReversed` `toSpliced` `with`; with a callback: `forEach` `map` `filter` `flatMap` `some` `every` `find` `findIndex` `findLast` `findLastIndex` `reduce` `reduceRight` `sort` `toSorted`; and `sortBy` |
|
|
3622
|
+
| Map | `size`, `get` `set` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
|
|
3623
|
+
| Set | `size`, `add` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
|
|
3624
|
+
|
|
3625
|
+
The methods behave as in JavaScript; `matchAll` gives an array, and so
|
|
3626
|
+
do `keys()`, `values()` and `entries()` of a Map or a Set
|
|
3627
|
+
(`m.keys().map(…)` works directly). `for…of`, a spread and `Array.from`
|
|
3628
|
+
iterate a Map or a Set as in JavaScript; `note`, `log` and the viewer
|
|
3629
|
+
show one as `Map(1) {"a" => 1}`. A Map keeps its entries apart from its
|
|
3630
|
+
members: `m.length` is a lint error, the count is `m.size`.
|
|
3631
|
+
`Math.random()` draws a new number on every call, so a run that uses it
|
|
3632
|
+
differs from the last one; for fresh test data `randomWord(n)` and
|
|
3633
|
+
`randomEmail()` read better. `undefined`, `NaN` and `Infinity` are
|
|
3634
|
+
values too.
|
|
2789
3635
|
|
|
2790
3636
|
**`arr.sortBy(key?, {desc?})`** sorts the array in place and returns it.
|
|
2791
3637
|
With a key every element is an object and its field is compared;
|
|
2792
3638
|
without one (`sortBy()`, or `sortBy(null, {desc: true})`) the elements
|
|
2793
3639
|
themselves. The compared values are all numbers or all strings —
|
|
2794
|
-
anything else fails the step. The sort is stable
|
|
2795
|
-
order.
|
|
3640
|
+
anything else fails the step. The sort is stable.
|
|
2796
3641
|
|
|
2797
3642
|
```js
|
|
2798
|
-
controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
|
|
3643
|
+
const controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
|
|
2799
3644
|
controls.sortBy('order'); // a, b
|
|
2800
3645
|
controls.sortBy('order', {desc: true});
|
|
2801
|
-
controls[0] = {id: 'z', order: 0};
|
|
2802
3646
|
```
|
|
2803
3647
|
|
|
2804
|
-
|
|
3648
|
+
With a function argument `filter` is the array method; with an options
|
|
3649
|
+
object it is still the locator step:
|
|
3650
|
+
`getByRole('row').filter({hasText: 'x'})`.
|
|
2805
3651
|
|
|
2806
|
-
|
|
2807
|
-
bare assignment `x = …;` with a name for intent: the scope is the
|
|
2808
|
-
function's, as for any variable here — a block does not make one.
|
|
2809
|
-
`for (let i = 0; i < n; i = i + 1)` declares the loop variable. A const
|
|
2810
|
-
needs a value and is not assigned again: `lint` refuses it
|
|
2811
|
-
(`validator:const-assign`) and a run fails at that line, as JavaScript
|
|
2812
|
-
does. The array or object it holds can still change (`ids.push(x)`). `var`
|
|
2813
|
-
is refused.
|
|
3652
|
+
### Outside the language
|
|
2814
3653
|
|
|
2815
|
-
|
|
2816
|
-
|
|
3654
|
+
What JavaScript has and a scenario does not — refused by `lint`
|
|
3655
|
+
(`validator:out-of-language`, error) and by the run, with the
|
|
3656
|
+
replacement:
|
|
2817
3657
|
|
|
2818
|
-
|
|
|
3658
|
+
| Not in the language | Write instead |
|
|
2819
3659
|
|---|---|
|
|
2820
|
-
| `
|
|
2821
|
-
| `
|
|
2822
|
-
| `
|
|
2823
|
-
| `
|
|
2824
|
-
|
|
2825
|
-
|
|
2826
|
-
|
|
2827
|
-
|
|
2828
|
-
|
|
2829
|
-
|
|
2830
|
-
|
|
2831
|
-
|
|
2832
|
-
|
|
2833
|
-
|
|
2834
|
-
|
|
2835
|
-
|
|
2836
|
-
|
|
2837
|
-
|
|
2838
|
-
|
|
2839
|
-
|
|
2840
|
-
|
|
2841
|
-
|
|
2842
|
-
|
|
2843
|
-
|
|
3660
|
+
| `import`, `export`, `require(…)` | functions in `_helpers/` are visible by name in every scenario |
|
|
3661
|
+
| `class`, `this`, `super`, `new X(…)` other than the constructors of the library | an object literal and functions; a regex is a `/…/` literal |
|
|
3662
|
+
| `throw new Error('x')` | `throw 'x'` or `throw {message: 'x'}` |
|
|
3663
|
+
| `get` / `set` in an object literal | a plain property or a function |
|
|
3664
|
+
| `function*`, `yield` | an array and a loop |
|
|
3665
|
+
| `for await` | `for…of` — host calls are awaited already |
|
|
3666
|
+
| `Date`, `new Date()` | `clockFreeze` / `clockTick` / `clockRun`; the page's time via `evaluate`; `nowMs()`, `today()` |
|
|
3667
|
+
| `setTimeout`, `setInterval` and the other timers | `pause(ms)` or `waitUntil(() => …)` |
|
|
3668
|
+
| `Promise`, `.then` | nothing: host calls are awaited already |
|
|
3669
|
+
| `eval`, `Function(…)` | page code goes to `evaluate(fn, arg)` |
|
|
3670
|
+
| `process`, `window`, `document`, `globalThis`, `fetch`, `console`, `localStorage`, `navigator`, `location` | an `UPPER_SNAKE` external variable or `env(…)`; the page via `evaluate(…)`; HTTP via `apiCall(…)`; output via `note(…)` / `log(…)` |
|
|
3671
|
+
| `WeakMap`, `WeakSet`, `WeakRef` | a `Map` or a `Set` |
|
|
3672
|
+
| `Symbol`, `Proxy`, `Reflect` | plain objects |
|
|
3673
|
+
| `instanceof` | `Array.isArray(x)` or `typeof x` |
|
|
3674
|
+
| `with` | name the object: `obj.prop` |
|
|
3675
|
+
| labels | a helper function and `return` |
|
|
3676
|
+
| `debugger` | a breakpoint in the viewer, or `pause()` |
|
|
3677
|
+
| BigInt (`1n`) | a number |
|
|
3678
|
+
| `&&=`, `\|\|=`, `??=` | the full form: `x = x ?? value` |
|
|
3679
|
+
| tagged templates | `` String.raw`…` `` is the only tag |
|
|
3680
|
+
| `new.target`, `import.meta` | pass the value as a parameter |
|
|
3681
|
+
|
|
3682
|
+
A name in the table is refused only when the scenario does not declare
|
|
3683
|
+
it: `const window = 1;` is an ordinary variable. `new` is the other way
|
|
3684
|
+
round: it applies to the library's `Map` and `Set` only, never to a
|
|
3685
|
+
name the scenario declares.
|
|
3686
|
+
|
|
3687
|
+
A method call on a name nothing declares — `clock.freeze(…)`,
|
|
3688
|
+
`page.waitForTimeout(…)` as another framework spells it — is an
|
|
3689
|
+
unknown function (`validator:unknown-function`), with the name to use
|
|
3690
|
+
here when there is one: `use clockFreeze("2026-01-15T10:00:00Z")`.
|
|
2844
3691
|
|
|
2845
3692
|
### `teardown` — give the stand back
|
|
2846
3693
|
|
|
@@ -2854,7 +3701,7 @@ function test_ticket_closed_in_second_client() {
|
|
|
2854
3701
|
});
|
|
2855
3702
|
apiCall('POST', '/stand/flags', {closeTickets: true});
|
|
2856
3703
|
});
|
|
2857
|
-
step("…", () => { … });
|
|
3704
|
+
step("…", () => { /* … */ });
|
|
2858
3705
|
}
|
|
2859
3706
|
```
|
|
2860
3707
|
|
|
@@ -2931,7 +3778,7 @@ function test_theme_rebuild() {
|
|
|
2931
3778
|
```
|
|
2932
3779
|
|
|
2933
3780
|
Running out is a failure, not a stop: the test is red — counted as
|
|
2934
|
-
|
|
3781
|
+
failed (`✗`), like any run budget — with
|
|
2935
3782
|
`setTestTimeout(90000) budget exhausted` (or `testTimeoutMs budget
|
|
2936
3783
|
(30000ms) exhausted`), the action it cut is abandoned, and the teardown
|
|
2937
3784
|
blocks play. Stop in the viewer aborts the run instead — same teardown,
|
|
@@ -2939,7 +3786,7 @@ but the run reads as stopped, not failed. Call it in the `test_*` body:
|
|
|
2939
3786
|
in a helper or a `flow_*` it is reported by
|
|
2940
3787
|
`lint:set-test-timeout-outside-test`.
|
|
2941
3788
|
|
|
2942
|
-
Rules (lint, `teardown-shape`): the label is
|
|
3789
|
+
Rules (lint, `teardown-shape`): the label is text written out; no
|
|
2943
3790
|
`return` inside, no `break` out of it (a `break` in a loop inside is
|
|
2944
3791
|
fine); no `teardown` inside a `teardown`. Allowed in tests, flows and
|
|
2945
3792
|
helpers. A function, parameter or variable of your own named
|
|
@@ -2963,7 +3810,7 @@ helpers. A function, parameter or variable of your own named
|
|
|
2963
3810
|
|
|
2964
3811
|
// The badge must stay hidden.
|
|
2965
3812
|
// @expect-fail <- test_badge_hidden only
|
|
2966
|
-
function test_badge_hidden() { … }
|
|
3813
|
+
function test_badge_hidden() { /* … */ }
|
|
2967
3814
|
```
|
|
2968
3815
|
|
|
2969
3816
|
The `//` lines directly above a `function test_*` — no blank line
|
|
@@ -3001,8 +3848,7 @@ helpers. A function, parameter or variable of your own named
|
|
|
3001
3848
|
}
|
|
3002
3849
|
```
|
|
3003
3850
|
|
|
3004
|
-
`return` is legal in either kind
|
|
3005
|
-
would mean the scenario silently ended halfway. A `flow_*` that returns a
|
|
3851
|
+
`return` is legal in either kind. A `flow_*` that returns a
|
|
3006
3852
|
value gets `lint:flow-returns-value` (warning): fine when the flow acts
|
|
3007
3853
|
and yields its result (`email = flow_signup()`), a rename hint when it
|
|
3008
3854
|
only reads.
|