@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.
@@ -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 `timeout` (`timeoutMs` is accepted too, the name the
211
- newer functions use); giving both in one call is refused.
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?`, `timeout?`, `position?`, `modifiers?`.
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.timeout`, else the config default). A
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'}), {timeout: 5000})
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?`, `timeout?`, `position?` (no `modifiers` — that
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` can be a string, an array of strings, or
430
- `{label}` / `{value}` / `{index}`.
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 `{timeout}`). Throw `AssertionError` on failure.
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:** `timeout?`, `exact?` (default `true`), `not?`.
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:** `timeout?`, `exact?` (default `true`).
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:** `timeout?`, `exact?` (default `true`), `not?`.
521
+ **Options:** `timeoutMs?`, `exact?` (default `true`), `not?`.
507
522
 
508
523
  ### `assertVisible(loc, options?)` / `assertHidden(loc, options?)`
509
524
 
510
- **Options:** `timeout?`.
525
+ **Options:** `timeoutMs?`.
511
526
 
512
527
  ```js
513
528
  assertVisible(getByTestId('toast'))
514
- assertHidden(getByTestId('spinner'), {timeout: 10000})
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:** `timeout?`.
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:** `timeout?`.
607
+ **Options:** `timeoutMs?`.
565
608
 
566
609
  ```js
567
610
  assertCount(getByRole('listitem'), 5)
568
- assertCount(getByRole('row'), 20, {timeout: 15000})
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:** `timeout?`.
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'`), `timeout?`.
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:** `timeout?`.
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', timeout: 30000});
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; `{first: true}` from older
1021
- scenarios is accepted as a no-op).
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?, timeout? }`. Default matching is substring —
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/, {timeout: 60000}); // word-boundary, long poll
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, {timeout: 90000}); // echo + reply
1050
- waitForText(/Ital/i, {timeout: 90000}); // reply content
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?, timeout? }` (default timeout 5000 ms — raise it for
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, {timeout: 90000});
1070
- waitForText(/\bshipping\b/i, {timeout: 90000});
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: `{ timeout? }` (default 5000 ms). A timeout is an error naming
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 `options` the path goes against
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 web requests only: http(s) and ws(s). An extension's
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
- whose backslash escape decodes now (`` `a\nb` `` is a line break):
2782
- a scenario written for the earlier raw backticks reads differently.
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 `new Map` / `new Set` | an object literal and functions; a regex is a `/…/` literal |
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 |