@unotest/web 0.50.0 → 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/CHANGELOG.md +110 -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 +11 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +350 -3
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +1 -1
- 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--zgFOUB6.d.ts → interfaces-BSGmF_Tv.d.ts} +92 -3
- package/dist/{linter-Ci17V2Sr.d.ts → linter-CYRlmOLy.d.ts} +19 -0
- package/dist/mcp/server.js +1 -1
- package/dist/runner/cli.d.ts +1 -1
- package/dist/runner/cli.js +1 -1
- package/dist/runner/init/chrome-probe.js +1 -1
- package/dist/runner/init.js +1 -1
- package/dist/runner/install-chromium.js +1 -1
- package/dist/runner/prepare-fix.js +1 -1
- package/dist/runner/scaffold-workspace.js +1 -1
- package/dist/runner/serve-fixture.js +1 -1
- package/dist/runner/web-runner-adapter.js +1 -1
- package/guides/agent-integration.md +25 -2
- package/guides/dsl-reference.md +807 -38
- package/llms.txt +223 -0
- package/package.json +9 -8
- package/types/unotest-dsl.d.ts +328 -101
package/guides/dsl-reference.md
CHANGED
|
@@ -178,11 +178,14 @@ Two squiggle sources remain that typings cannot fix, both cosmetic:
|
|
|
178
178
|
- [Storage](#storage) — localStorage / cookies
|
|
179
179
|
- [Edge actions](#edge-actions) — drag, upload, paste
|
|
180
180
|
- [Sandbox primitives](#sandbox-primitives) — shell / db / HTTP / files
|
|
181
|
+
- [MCP client](#mcp-client) — start an MCP server, call it, wait for it
|
|
181
182
|
- [Network mocks](#network-mocks) — what the page's requests get
|
|
183
|
+
- [Terminal (macOS)](#terminal-macos) — a real Terminal.app / iTerm2 window
|
|
182
184
|
- [Typed getters](#typed-getters) — page properties
|
|
183
185
|
- [Generators](#generators) — random fixture data + time
|
|
184
186
|
- [`evaluate`](#evaluate) — escape hatch into the page
|
|
185
187
|
- [Logging](#logging)
|
|
188
|
+
- [Signatures](#signatures) — every function with the types it takes
|
|
186
189
|
|
|
187
190
|
---
|
|
188
191
|
|
|
@@ -207,8 +210,9 @@ getByRole('row').filter({hasText: /done/i})
|
|
|
207
210
|
## The `timeout` option
|
|
208
211
|
|
|
209
212
|
Actions, navigation, waits and assertions take their time limit in
|
|
210
|
-
milliseconds as `
|
|
211
|
-
|
|
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`.
|
|
212
216
|
|
|
213
217
|
An option an action, a navigation, a wait or an assertion does not take
|
|
214
218
|
is refused with the ones it does, so a misspelled `{timout: 5000}` fails at once
|
|
@@ -370,7 +374,7 @@ click(getByRole('button', {name: 'Save'}))
|
|
|
370
374
|
click(getByText('Submit'), {force: true})
|
|
371
375
|
```
|
|
372
376
|
|
|
373
|
-
**Options:** `force?`, `
|
|
377
|
+
**Options:** `force?`, `timeoutMs?`, `position?`, `modifiers?`.
|
|
374
378
|
|
|
375
379
|
### `doubleClick(loc, options?)`
|
|
376
380
|
|
|
@@ -399,7 +403,7 @@ press(getByLabel('Body'), 'Control+A')
|
|
|
399
403
|
|
|
400
404
|
Idempotent — no click if already in the target state. Otherwise one
|
|
401
405
|
click, then a wait until the element reads checked (unchecked) within
|
|
402
|
-
the action timeout (`options.
|
|
406
|
+
the action timeout (`options.timeoutMs`, else the config default). A
|
|
403
407
|
controlled switch the app flips a beat after the click — once the server
|
|
404
408
|
confirms — passes; one that never flips fails, naming the state it
|
|
405
409
|
wanted and the last one it saw. Works on native checkboxes and radios
|
|
@@ -409,7 +413,7 @@ wrapped input). Any other element is refused — use `click` for it.
|
|
|
409
413
|
|
|
410
414
|
```js
|
|
411
415
|
check(getByRole('checkbox', {name: 'Subscribe'}))
|
|
412
|
-
uncheck(getByRole('switch', {name: 'Notifications'}), {
|
|
416
|
+
uncheck(getByRole('switch', {name: 'Notifications'}), {timeoutMs: 5000})
|
|
413
417
|
```
|
|
414
418
|
|
|
415
419
|
### `hover(loc, options?)`
|
|
@@ -421,17 +425,28 @@ hover(getByRole('button', {name: 'Help'}))
|
|
|
421
425
|
hover(getByTestId('message-42'), {position: {x: 24, y: 8}})
|
|
422
426
|
```
|
|
423
427
|
|
|
424
|
-
**Options:** `force?`, `
|
|
428
|
+
**Options:** `force?`, `timeoutMs?`, `position?` (no `modifiers` — that
|
|
425
429
|
is a `click` option).
|
|
426
430
|
|
|
427
431
|
### `selectOption(loc, value, options?)`
|
|
428
432
|
|
|
429
|
-
Native `<select>` only. `value`
|
|
430
|
-
|
|
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`.
|
|
431
444
|
|
|
432
445
|
```js
|
|
433
446
|
selectOption(getByLabel('Country'), 'US')
|
|
434
447
|
selectOption(getByLabel('Tags'), ['a', 'b'])
|
|
448
|
+
selectOption(getByLabel('Folder'), {label: 'Archive'})
|
|
449
|
+
selectOption(getByLabel('Folder'), {index: 0})
|
|
435
450
|
```
|
|
436
451
|
|
|
437
452
|
### `scrollIntoView(loc)`
|
|
@@ -445,7 +460,7 @@ scrollIntoView(getByText('Footer'))
|
|
|
445
460
|
## Assertions
|
|
446
461
|
|
|
447
462
|
Each polls until the condition holds or the timeout fires (default 5s;
|
|
448
|
-
override per-call with `{
|
|
463
|
+
override per-call with `{timeoutMs}`). Throw `AssertionError` on failure.
|
|
449
464
|
|
|
450
465
|
### `assertText(loc, expected, options?)`
|
|
451
466
|
|
|
@@ -466,7 +481,7 @@ assertText(getByRole('status'), 'Saving…', {not: true}) // waits until it ch
|
|
|
466
481
|
- Empty text: `assertText(loc, '')`. Any text at all:
|
|
467
482
|
`assertText(loc, '', {not: true})`.
|
|
468
483
|
|
|
469
|
-
**Options:** `
|
|
484
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`), `not?`.
|
|
470
485
|
|
|
471
486
|
### `assertTexts(loc, expected, options?)`
|
|
472
487
|
|
|
@@ -487,7 +502,7 @@ an index read, a helper's result. A value known to be something else (a
|
|
|
487
502
|
string, a number) is refused by the linter; the rest is checked when the
|
|
488
503
|
step runs. The same holds for the expected text of `assertText`.
|
|
489
504
|
|
|
490
|
-
**Options:** `
|
|
505
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`).
|
|
491
506
|
|
|
492
507
|
### `assertAttribute(loc, name, expected, options?)`
|
|
493
508
|
|
|
@@ -503,15 +518,15 @@ assertAttribute(getByRole('link', {name: 'Docs'}), 'href', /\/docs\//)
|
|
|
503
518
|
assertAttribute(getByRole('form'), 'aria-busy', 'true', {not: true})
|
|
504
519
|
```
|
|
505
520
|
|
|
506
|
-
**Options:** `
|
|
521
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`), `not?`.
|
|
507
522
|
|
|
508
523
|
### `assertVisible(loc, options?)` / `assertHidden(loc, options?)`
|
|
509
524
|
|
|
510
|
-
**Options:** `
|
|
525
|
+
**Options:** `timeoutMs?`.
|
|
511
526
|
|
|
512
527
|
```js
|
|
513
528
|
assertVisible(getByTestId('toast'))
|
|
514
|
-
assertHidden(getByTestId('spinner'), {
|
|
529
|
+
assertHidden(getByTestId('spinner'), {timeoutMs: 10000})
|
|
515
530
|
```
|
|
516
531
|
|
|
517
532
|
### `assertNeverAppears(loc, options)`
|
|
@@ -532,11 +547,39 @@ system under test could realistically react. Unlike `assertHidden`
|
|
|
532
547
|
(a poll that PASSES as soon as the element is gone), this one watches
|
|
533
548
|
the whole window.
|
|
534
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
|
+
|
|
535
578
|
### `assertValue(loc, expected, options?)`
|
|
536
579
|
|
|
537
580
|
Compares `inputValue()` (`<input>`, `<textarea>`, native `<select>`).
|
|
538
581
|
|
|
539
|
-
**Options:** `
|
|
582
|
+
**Options:** `timeoutMs?`.
|
|
540
583
|
|
|
541
584
|
```js
|
|
542
585
|
assertValue(getByLabel('Email'), 'a@b.c')
|
|
@@ -561,11 +604,11 @@ value, and so does the failure.
|
|
|
561
604
|
|
|
562
605
|
### `assertCount(loc, expected, options?)`
|
|
563
606
|
|
|
564
|
-
**Options:** `
|
|
607
|
+
**Options:** `timeoutMs?`.
|
|
565
608
|
|
|
566
609
|
```js
|
|
567
610
|
assertCount(getByRole('listitem'), 5)
|
|
568
|
-
assertCount(getByRole('row'), 20, {
|
|
611
|
+
assertCount(getByRole('row'), 20, {timeoutMs: 15000})
|
|
569
612
|
```
|
|
570
613
|
|
|
571
614
|
### `assertUrl(pattern, options?)`
|
|
@@ -574,7 +617,7 @@ A string is a substring match against the active page's URL. A
|
|
|
574
617
|
`/regex/` is tested against the whole URL, unanchored: add `^` or `$`
|
|
575
618
|
yourself. A failure names the regex as `/source/flags`.
|
|
576
619
|
|
|
577
|
-
**Options:** `
|
|
620
|
+
**Options:** `timeoutMs?`.
|
|
578
621
|
|
|
579
622
|
```js
|
|
580
623
|
assertUrl('/dashboard')
|
|
@@ -940,7 +983,8 @@ goto('/dashboard') // relative — resolved against the
|
|
|
940
983
|
```
|
|
941
984
|
|
|
942
985
|
**Options:** `waitUntil?` (`'load'` | `'domcontentloaded'` |
|
|
943
|
-
`'networkidle'`), `
|
|
986
|
+
`'networkidle'` | `'commit'`), `timeoutMs?`. The same two keys go to
|
|
987
|
+
`reload`, `goBack`, `goForward` and `waitForUrl`.
|
|
944
988
|
|
|
945
989
|
### `reload(options?)` / `goBack(options?)` / `goForward(options?)`
|
|
946
990
|
|
|
@@ -950,7 +994,7 @@ Wait until the active page URL contains `pattern` (a string) or matches
|
|
|
950
994
|
it (a `/regex/`, unanchored). Useful after a click that triggers
|
|
951
995
|
navigation.
|
|
952
996
|
|
|
953
|
-
**Options:** `
|
|
997
|
+
**Options:** `waitUntil?` (as for `goto`), `timeoutMs?`.
|
|
954
998
|
|
|
955
999
|
```js
|
|
956
1000
|
click(getByRole('link', {name: 'Settings'}));
|
|
@@ -976,7 +1020,7 @@ waitFor(getByTestId('content-loaded'))
|
|
|
976
1020
|
|
|
977
1021
|
```js
|
|
978
1022
|
step("Wait until the widget re-enables the send button", () => {
|
|
979
|
-
waitFor(locator('.chat__send'), {state: 'enabled',
|
|
1023
|
+
waitFor(locator('.chat__send'), {state: 'enabled', timeoutMs: 30000});
|
|
980
1024
|
});
|
|
981
1025
|
```
|
|
982
1026
|
|
|
@@ -1012,15 +1056,44 @@ job = waitUntil(() => {
|
|
|
1012
1056
|
- On timeout the step fails with the label, the number of tries and the
|
|
1013
1057
|
last value: `waitUntil "job done": still falsy after 30000 ms (60
|
|
1014
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
|
+
```
|
|
1015
1088
|
|
|
1016
1089
|
### `waitForText(text, options?)`
|
|
1017
1090
|
|
|
1018
1091
|
Wait until at least one **visible** element on the active page contains
|
|
1019
1092
|
`text` (chat feeds and repeated labels legally duplicate text — ≥1
|
|
1020
|
-
visible match is the success condition; `
|
|
1021
|
-
|
|
1093
|
+
visible match is the success condition; the `first` option of older
|
|
1094
|
+
releases is gone and is refused).
|
|
1022
1095
|
|
|
1023
|
-
Options: `{ exact?, state?,
|
|
1096
|
+
Options: `{ exact?, state?, timeoutMs? }`. Default matching is substring —
|
|
1024
1097
|
it also matches *inside* a word (`'hi'` hits `'anything'`). For precise
|
|
1025
1098
|
matching pass `{exact: true}` (full-text equality) or a regex with word
|
|
1026
1099
|
boundaries:
|
|
@@ -1028,7 +1101,7 @@ boundaries:
|
|
|
1028
1101
|
```js
|
|
1029
1102
|
waitForText('Active'); // ≥1 visible occurrence
|
|
1030
1103
|
waitForText('Active', {exact: true}); // full-text equality
|
|
1031
|
-
waitForText(/\bhi\b/, {
|
|
1104
|
+
waitForText(/\bhi\b/, {timeoutMs: 60000}); // word-boundary, long poll
|
|
1032
1105
|
```
|
|
1033
1106
|
|
|
1034
1107
|
`state: 'hidden'` waits until **no** visible occurrence remains.
|
|
@@ -1046,8 +1119,8 @@ content:
|
|
|
1046
1119
|
n = count(locator('[data-message]'));
|
|
1047
1120
|
fill(getByRole('textbox'), '@Bot Service ' + question);
|
|
1048
1121
|
press(getByRole('textbox'), 'Enter');
|
|
1049
|
-
waitForCount(locator('[data-message]'), n + 2, {
|
|
1050
|
-
waitForText(/Ital/i, {
|
|
1122
|
+
waitForCount(locator('[data-message]'), n + 2, {timeoutMs: 90000}); // echo + reply
|
|
1123
|
+
waitForText(/Ital/i, {timeoutMs: 90000}); // reply content
|
|
1051
1124
|
```
|
|
1052
1125
|
|
|
1053
1126
|
A unique marker (`randomWord(8)`) in the outgoing message plus a wait on
|
|
@@ -1060,14 +1133,14 @@ pattern "wait for reply №N": at-least semantics don't flake when the
|
|
|
1060
1133
|
feed grows past N between polls. `{exact: true}` waits for exactly
|
|
1061
1134
|
`count` matches; timeout throws with the last observed count.
|
|
1062
1135
|
|
|
1063
|
-
Options: `{ exact?,
|
|
1136
|
+
Options: `{ exact?, timeoutMs? }` (default timeout 5000 ms — raise it for
|
|
1064
1137
|
slow producers like LLM replies).
|
|
1065
1138
|
|
|
1066
1139
|
```js
|
|
1067
1140
|
// Chat feed: the bot's reply is message #3 — wait for it, then assert
|
|
1068
1141
|
// on its text with a second, content-anchored wait:
|
|
1069
|
-
waitForCount(locator('[data-id]'), 3, {
|
|
1070
|
-
waitForText(/\bshipping\b/i, {
|
|
1142
|
+
waitForCount(locator('[data-id]'), 3, {timeoutMs: 90000});
|
|
1143
|
+
waitForText(/\bshipping\b/i, {timeoutMs: 90000});
|
|
1071
1144
|
```
|
|
1072
1145
|
|
|
1073
1146
|
### `waitForAnimations(loc, options?)`
|
|
@@ -1078,7 +1151,7 @@ or screenshotting it. Infinite animations (spinners) and paused ones are
|
|
|
1078
1151
|
not waited for: neither ends by itself, so waiting could only time out.
|
|
1079
1152
|
A static element returns at once. Same rule as `hasAnimation`.
|
|
1080
1153
|
|
|
1081
|
-
Options: `{
|
|
1154
|
+
Options: `{ timeoutMs? }` (default 5000 ms). A timeout is an error naming
|
|
1082
1155
|
the element and how many animations were still running.
|
|
1083
1156
|
|
|
1084
1157
|
```js
|
|
@@ -1214,6 +1287,44 @@ bringToFront(); // now tab 1 is shown too
|
|
|
1214
1287
|
bringToFront(0); // show the site again; steps stay on 1
|
|
1215
1288
|
```
|
|
1216
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
|
+
|
|
1217
1328
|
### `newPage(url?)` → `number`
|
|
1218
1329
|
|
|
1219
1330
|
Open a new tab in the active browser context, make it active and bring
|
|
@@ -1381,6 +1492,59 @@ again after `setPage` / `waitForPage`. An app that reads the color
|
|
|
1381
1492
|
scheme once at load sees the change on its next load (`reload()`), not
|
|
1382
1493
|
before.
|
|
1383
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
|
+
|
|
1384
1548
|
#### Viewport and scale
|
|
1385
1549
|
|
|
1386
1550
|
Where the window's size and scale come from, first match wins:
|
|
@@ -1554,6 +1718,29 @@ real event won't accept formatting.
|
|
|
1554
1718
|
clipboardPaste(getByLabel('Notes'), 'pasted text');
|
|
1555
1719
|
```
|
|
1556
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
|
+
|
|
1557
1744
|
---
|
|
1558
1745
|
|
|
1559
1746
|
## Sandbox primitives
|
|
@@ -1907,6 +2094,38 @@ step("The agent answered exactly once", () => {
|
|
|
1907
2094
|
Counting is per **line** (`grep -c` semantics), not per occurrence: two
|
|
1908
2095
|
matches on one line count once.
|
|
1909
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
|
+
|
|
1910
2129
|
### `dbQuery(sql, ...params)` → `rows[]`
|
|
1911
2130
|
|
|
1912
2131
|
Parameterized SELECT. Driver picked by URL scheme:
|
|
@@ -1937,7 +2156,7 @@ res = apiCall('POST', '/auth/login', {email: 'a@b.c', password: 'x'});
|
|
|
1937
2156
|
assertTrue(res.status == 200, 'login failed');
|
|
1938
2157
|
```
|
|
1939
2158
|
|
|
1940
|
-
**Named API bases.** Without `
|
|
2159
|
+
**Named API bases.** Without `{base}` the path goes against
|
|
1941
2160
|
`sandbox.apiBaseUrl`. A setup that talks to more than one host names
|
|
1942
2161
|
the base per call — `{base: 'API_BASE_X'}` is the **name of a
|
|
1943
2162
|
variable** from `unotest/.env` (overlays apply as usual), never a URL:
|
|
@@ -1973,6 +2192,21 @@ file the overlay was supposed to replace. The same rule covers
|
|
|
1973
2192
|
`APP_BASE_URL` (the base every relative `goto` resolves against) and a
|
|
1974
2193
|
variable used as the URL in `goto(NAME)`.
|
|
1975
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
|
+
|
|
1976
2210
|
**Multipart file upload — `upload(path, options?)`.** Passing the
|
|
1977
2211
|
result of `upload(...)` as the body posts `multipart/form-data`:
|
|
1978
2212
|
|
|
@@ -2005,6 +2239,151 @@ assertTrue(res.status == 202, 'ingestion not accepted');
|
|
|
2005
2239
|
|
|
2006
2240
|
---
|
|
2007
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
|
+
|
|
2008
2387
|
## Network mocks
|
|
2009
2388
|
|
|
2010
2389
|
What the page's requests get, for the rest of the scenario: a fixed
|
|
@@ -2039,7 +2418,10 @@ mockRoute('**/ads/**', { abort: true });
|
|
|
2039
2418
|
navigation to your site still loads. Only the document: its scripts,
|
|
2040
2419
|
styles, images and API calls are ordinary requests, and an abort mask
|
|
2041
2420
|
that matches them stops them.
|
|
2042
|
-
- 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
|
|
2043
2425
|
own pages and scripts (`chrome-extension://`) load under `**/*`, so
|
|
2044
2426
|
a network allowlist does not leave its UI dead. To mock one of them,
|
|
2045
2427
|
start the mask with its scheme: `chrome-extension://<id>/panel.js`.
|
|
@@ -2079,6 +2461,28 @@ assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
|
|
|
2079
2461
|
On any other mask only requests from the call on count — to catch one
|
|
2080
2462
|
the previous step sent, mock the mask with `{continue: true}` first.
|
|
2081
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.
|
|
2082
2486
|
|
|
2083
2487
|
### `assertNoRequest(glob, options?)`
|
|
2084
2488
|
|
|
@@ -2100,6 +2504,116 @@ assertNoRequest('**/*');
|
|
|
2100
2504
|
|
|
2101
2505
|
---
|
|
2102
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
|
+
|
|
2103
2617
|
## Typed getters
|
|
2104
2618
|
|
|
2105
2619
|
Read page properties directly into a local variable.
|
|
@@ -2183,6 +2697,28 @@ the rule `waitForAnimations` waits by.
|
|
|
2183
2697
|
assertTrue(hasAnimation(getByRole('dialog')) === false, 'dialog still moving');
|
|
2184
2698
|
```
|
|
2185
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
|
+
|
|
2186
2722
|
### `getTitle()` → `string`
|
|
2187
2723
|
|
|
2188
2724
|
Active page title.
|
|
@@ -2408,6 +2944,15 @@ to the page reads only its own parameters
|
|
|
2408
2944
|
run checks both rules before it starts, in the test and in every helper
|
|
2409
2945
|
of `_helpers/` it loads, and stops on them.
|
|
2410
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.
|
|
2955
|
+
|
|
2411
2956
|
A page whose main thread is busy — a script loop, a long task — cannot
|
|
2412
2957
|
start the script. `evaluate` then fails the step after the action timeout
|
|
2413
2958
|
(the config's `defaultTimeoutMs`) with `the page gave no answer` instead
|
|
@@ -2597,6 +3142,225 @@ step.soft("Question", {tag: q.id}, () => {
|
|
|
2597
3142
|
|
|
2598
3143
|
---
|
|
2599
3144
|
|
|
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
|
+
|
|
2600
3364
|
## The language — JavaScript
|
|
2601
3365
|
|
|
2602
3366
|
A scenario file is JavaScript (ES2020), run by unotest's own
|
|
@@ -2778,9 +3542,10 @@ Two lint rules guard templates:
|
|
|
2778
3542
|
variable ever given one): the value would become code of the page.
|
|
2779
3543
|
Write fixed text or a function, and pass the value as an argument.
|
|
2780
3544
|
- `validator:template-escape-changed` (warning) — a backtick string
|
|
2781
|
-
|
|
2782
|
-
a scenario written for the earlier raw backticks
|
|
2783
|
-
Double the backslash or use `` String.raw`…` ``.
|
|
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.
|
|
2784
3549
|
|
|
2785
3550
|
### Regex literals
|
|
2786
3551
|
|
|
@@ -2842,9 +3607,12 @@ lint error that names it: `validator:library-member` on a namespace
|
|
|
2842
3607
|
| `String(x)` | `raw` |
|
|
2843
3608
|
| `Array` | `isArray`, `from`, `of` |
|
|
2844
3609
|
| `Object` | `keys`, `values`, `entries`, `fromEntries`, `assign`, `hasOwn` |
|
|
2845
|
-
| `new Map(entries?)`, `new Set(items?)` | the only `new` in the language |
|
|
2846
3610
|
| functions | `parseInt`, `parseFloat`, `isNaN`, `isFinite` |
|
|
2847
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
|
+
|
|
2848
3616
|
| Value | Members |
|
|
2849
3617
|
|---|---|
|
|
2850
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` |
|
|
@@ -2890,7 +3658,8 @@ replacement:
|
|
|
2890
3658
|
| Not in the language | Write instead |
|
|
2891
3659
|
|---|---|
|
|
2892
3660
|
| `import`, `export`, `require(…)` | functions in `_helpers/` are visible by name in every scenario |
|
|
2893
|
-
| `class`, `this`, `super`, `new X(…)` other than
|
|
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'}` |
|
|
2894
3663
|
| `get` / `set` in an object literal | a plain property or a function |
|
|
2895
3664
|
| `function*`, `yield` | an array and a loop |
|
|
2896
3665
|
| `for await` | `for…of` — host calls are awaited already |
|