@unotest/web 0.50.0 → 0.52.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.
@@ -92,12 +92,12 @@ The data-driven gate, in full (`readJsonLine` reads the cases; the outer
92
92
  ```js
93
93
  function test_control_questions() {
94
94
  step("Control questions", () => {
95
- for (i = 1; i < 11; i = i + 1) {
96
- q = readJsonLine('questions.jsonl', {slot: i});
95
+ for (let i = 1; i < 11; i = i + 1) {
96
+ const q = readJsonLine('questions.jsonl', {slot: i});
97
97
  step.soft("Question", {tag: q.id}, () => {
98
98
  fill(getByRole('textbox', {name: 'Message'}), q.text);
99
99
  press(getByRole('textbox', {name: 'Message'}), 'Enter');
100
- answer = getByTestId('last-answer');
100
+ const answer = getByTestId('last-answer');
101
101
  screenshot(q.id);
102
102
  assertJudge(answer, q.rubric);
103
103
  });
@@ -136,7 +136,7 @@ it consists of:
136
136
  library (`Math`, `JSON`, `Object`, `Map`, `Set`, the string, number and
137
137
  array methods), cut from TypeScript's own declarations to exactly what
138
138
  a scenario has. `keys()`, `values()` and `entries()` of a Map or a Set
139
- read as arrays, as they run.
139
+ read as iterators, as they run: spread one for array methods.
140
140
  - `node_modules/@unotest/web/types/unotest-dsl.d.ts` — ambient
141
141
  declarations for every DSL function, generated from the same contracts
142
142
  the validator uses and shipped with the package, so it always matches
@@ -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
 
@@ -477,7 +492,7 @@ list that is still filling in passes once it is complete.
477
492
 
478
493
  ```js
479
494
  assertTexts(getByRole('listitem'), ['Apple', 'Banana', /^Cherry/])
480
- labels = ['Apple', 'Banana'];
495
+ const labels = ['Apple', 'Banana'];
481
496
  assertTexts(getByRole('listitem'), labels)
482
497
  assertText(getByRole('listitem').first(), labels[0])
483
498
  ```
@@ -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
+ const 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')
@@ -587,7 +630,7 @@ assertUrl(/\/cars\/\d+$/)
587
630
  Generic boolean assert. Throws with `message` when `value` is falsy.
588
631
 
589
632
  ```js
590
- probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
633
+ const probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
591
634
  assertTrue(probe.code == 0, 'app.log should contain "ready"');
592
635
  ```
593
636
 
@@ -599,7 +642,7 @@ names the first path that differs and both values, then a line diff of
599
642
  the two sides, every line of them — nothing is folded away:
600
643
 
601
644
  ```js
602
- body = parseJson(getAttribute(locator('#state'), 'data-json'));
645
+ const body = parseJson(getAttribute(locator('#state'), 'data-json'));
603
646
  assertEqual(body.controls, {theme: 'dark', devices: ['pixel']});
604
647
  // assertEqual: values differ at devices[0]: expected "pixel", got "iphone"
605
648
  ```
@@ -612,8 +655,8 @@ reads with `readJson`. The failure names every field that breaks the
612
655
  schema, by path, with what is wrong there:
613
656
 
614
657
  ```js
615
- schema = readJson('unotest/fixtures/message.schema.json');
616
- req = waitForRequest('**/api/messages');
658
+ const schema = readJson('unotest/fixtures/message.schema.json');
659
+ const req = waitForRequest('**/api/messages');
617
660
  assertSchema(req.postDataJson, schema);
618
661
  // assertSchema: the value breaks the schema in 2 places:
619
662
  // /room: must be >= 1
@@ -655,7 +698,7 @@ inside that step:
655
698
  ```js
656
699
  function test_refund() {
657
700
  step("Find a paid order", () => {
658
- orders = apiCall('GET', '/orders?status=paid');
701
+ const orders = apiCall('GET', '/orders?status=paid');
659
702
  if (orders.length == 0) { skip('no paid order on this stand'); }
660
703
  });
661
704
  // …
@@ -686,7 +729,7 @@ go to the configured judge; a `fail` verdict fails the step with the
686
729
  judge's reasoning, like any other assertion.
687
730
 
688
731
  ```js
689
- reply = locator('.chat__message').last();
732
+ const reply = locator('.chat__message').last();
690
733
  assertJudge(reply,
691
734
  'The reply must direct the user to support and must NOT promise ' +
692
735
  'to escalate, resend the email, or notify a team itself.');
@@ -864,10 +907,10 @@ class or attribute — CSS. `assertCount` / `waitForCount` take the same
864
907
  locator and wait for the number.
865
908
 
866
909
  ```js
867
- done = count(getByRole('row').filter({hasText: 'Done'}));
868
- admins = count(getByRole('row').filter({has: getByTestId('admin-badge')}));
869
- selected = count(locator('li.selected'));
870
- external = count(locator('a[target="_blank"]'));
910
+ const done = count(getByRole('row').filter({hasText: 'Done'}));
911
+ const admins = count(getByRole('row').filter({has: getByTestId('admin-badge')}));
912
+ const selected = count(locator('li.selected'));
913
+ const external = count(locator('a[target="_blank"]'));
871
914
  assertCount(getByRole('listitem').filter({hasNotText: 'Archived'}), 3)
872
915
  ```
873
916
 
@@ -882,7 +925,7 @@ when nothing matches. One read, no wait — the list to branch on.
882
925
  `assertTexts` is the waiting check of the same list.
883
926
 
884
927
  ```js
885
- names = texts(locator('#agents li')); // ["Claude Code", "Codex"]
928
+ const names = texts(locator('#agents li')); // ["Claude Code", "Codex"]
886
929
  if (names.length > 0) {
887
930
  log('first agent:', names[0]);
888
931
  }
@@ -922,7 +965,7 @@ Whether the attribute is present at all — the honest probe for boolean
922
965
  attributes (`disabled`, `readonly`, `required`, …).
923
966
 
924
967
  ```js
925
- n = count(getByRole('row'));
968
+ const n = count(getByRole('row'));
926
969
  if (n > 10) {
927
970
  log('too many rows:', n);
928
971
  }
@@ -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
 
@@ -994,8 +1038,8 @@ until it is truthy; the call gives that value back.
994
1038
 
995
1039
  ```js
996
1040
  waitUntil(() => parseJson(textContent(getByTestId('count'))) >= 5);
997
- job = waitUntil(() => {
998
- r = apiCall('GET', '/jobs/' + id);
1041
+ const job = waitUntil(() => {
1042
+ const r = apiCall('GET', '/jobs/' + id);
999
1043
  if (r.body.state != 'done') { return false; }
1000
1044
  return r.body;
1001
1045
  }, {timeoutMs: 30000, intervalMs: 500, label: 'job done'});
@@ -1012,15 +1056,43 @@ 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
+ const 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 belongs to no test: the validator
1073
+ refuses the declaration (`validator:top-level-statement`).
1074
+
1075
+ ```js bad
1076
+ let seen = 0;
1077
+
1078
+ function test_counter() {
1079
+ step('poll', () => {
1080
+ waitUntil(() => {
1081
+ seen = seen + 1;
1082
+ return seen >= 3;
1083
+ });
1084
+ });
1085
+ }
1086
+ ```
1015
1087
 
1016
1088
  ### `waitForText(text, options?)`
1017
1089
 
1018
1090
  Wait until at least one **visible** element on the active page contains
1019
1091
  `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).
1092
+ visible match is the success condition; the `first` option of older
1093
+ releases is gone and is refused).
1022
1094
 
1023
- Options: `{ exact?, state?, timeout? }`. Default matching is substring —
1095
+ Options: `{ exact?, state?, timeoutMs? }`. Default matching is substring —
1024
1096
  it also matches *inside* a word (`'hi'` hits `'anything'`). For precise
1025
1097
  matching pass `{exact: true}` (full-text equality) or a regex with word
1026
1098
  boundaries:
@@ -1028,7 +1100,7 @@ boundaries:
1028
1100
  ```js
1029
1101
  waitForText('Active'); // ≥1 visible occurrence
1030
1102
  waitForText('Active', {exact: true}); // full-text equality
1031
- waitForText(/\bhi\b/, {timeout: 60000}); // word-boundary, long poll
1103
+ waitForText(/\bhi\b/, {timeoutMs: 60000}); // word-boundary, long poll
1032
1104
  ```
1033
1105
 
1034
1106
  `state: 'hidden'` waits until **no** visible occurrence remains.
@@ -1043,11 +1115,11 @@ send, then wait for the count to grow — and only then assert on reply
1043
1115
  content:
1044
1116
 
1045
1117
  ```js
1046
- n = count(locator('[data-message]'));
1118
+ const n = count(locator('[data-message]'));
1047
1119
  fill(getByRole('textbox'), '@Bot Service ' + question);
1048
1120
  press(getByRole('textbox'), 'Enter');
1049
- waitForCount(locator('[data-message]'), n + 2, {timeout: 90000}); // echo + reply
1050
- waitForText(/Ital/i, {timeout: 90000}); // reply content
1121
+ waitForCount(locator('[data-message]'), n + 2, {timeoutMs: 90000}); // echo + reply
1122
+ waitForText(/Ital/i, {timeoutMs: 90000}); // reply content
1051
1123
  ```
1052
1124
 
1053
1125
  A unique marker (`randomWord(8)`) in the outgoing message plus a wait on
@@ -1060,14 +1132,14 @@ pattern "wait for reply №N": at-least semantics don't flake when the
1060
1132
  feed grows past N between polls. `{exact: true}` waits for exactly
1061
1133
  `count` matches; timeout throws with the last observed count.
1062
1134
 
1063
- Options: `{ exact?, timeout? }` (default timeout 5000 ms — raise it for
1135
+ Options: `{ exact?, timeoutMs? }` (default timeout 5000 ms — raise it for
1064
1136
  slow producers like LLM replies).
1065
1137
 
1066
1138
  ```js
1067
1139
  // Chat feed: the bot's reply is message #3 — wait for it, then assert
1068
1140
  // on its text with a second, content-anchored wait:
1069
- waitForCount(locator('[data-id]'), 3, {timeout: 90000});
1070
- waitForText(/\bshipping\b/i, {timeout: 90000});
1141
+ waitForCount(locator('[data-id]'), 3, {timeoutMs: 90000});
1142
+ waitForText(/\bshipping\b/i, {timeoutMs: 90000});
1071
1143
  ```
1072
1144
 
1073
1145
  ### `waitForAnimations(loc, options?)`
@@ -1078,7 +1150,7 @@ or screenshotting it. Infinite animations (spinners) and paused ones are
1078
1150
  not waited for: neither ends by itself, so waiting could only time out.
1079
1151
  A static element returns at once. Same rule as `hasAnimation`.
1080
1152
 
1081
- Options: `{ timeout? }` (default 5000 ms). A timeout is an error naming
1153
+ Options: `{ timeoutMs? }` (default 5000 ms). A timeout is an error naming
1082
1154
  the element and how many animations were still running.
1083
1155
 
1084
1156
  ```js
@@ -1214,6 +1286,44 @@ bringToFront(); // now tab 1 is shown too
1214
1286
  bringToFront(0); // show the site again; steps stay on 1
1215
1287
  ```
1216
1288
 
1289
+ ### `setPageHidden(hidden, index?)`
1290
+
1291
+ Emulates the tab's visibility for the page's scripts. `true` sends tab
1292
+ `index` to the background as its scripts see it: `document.hidden` is
1293
+ `true`, `document.visibilityState` is `'hidden'`, `document.hasFocus()`
1294
+ is `false`, and the page gets `blur` on `window`, then
1295
+ `visibilitychange`. `false` brings it back: `visibilitychange`, then
1296
+ `focus`. No index: the active tab. The steps keep acting on the hidden
1297
+ tab, as on any other.
1298
+
1299
+ A hidden tab stays hidden across navigations, and in its frames, until
1300
+ `setPageHidden(false)`. Asking for the state the tab is already in
1301
+ fires nothing. `setPage` and `bringToFront` do not show a hidden tab.
1302
+
1303
+ ```js
1304
+ step("A message that arrives while the chat is in the background", () => {
1305
+ goto('/chat');
1306
+ clockFreeze('2026-01-15T10:00:00Z');
1307
+ setPageHidden(true);
1308
+ clockTick(6 * 60 * 1000); // six minutes away, on the page clock
1309
+ setPageHidden(false);
1310
+ assertVisible(getByText('New message'));
1311
+ });
1312
+ ```
1313
+
1314
+ Time away is the page clock's
1315
+ ([`clockTick`](#clockfreezeiso--clocktickms--clockrun)) or real
1316
+ (`pause(ms)`); hiding the tab does not move it.
1317
+
1318
+ Not emulated: what the browser itself does to a background tab.
1319
+ Timers are not throttled, animation frames keep running, the page is
1320
+ not frozen (`freeze` / `resume`), and a service worker's
1321
+ `clients.matchAll()` still reports the tab `visible`.
1322
+
1323
+ Engines: the same in Chromium, Firefox and WebKit. In Firefox a frame
1324
+ that loads while the tab is hidden sees it visible while it loads, and
1325
+ hidden from then on.
1326
+
1217
1327
  ### `newPage(url?)` → `number`
1218
1328
 
1219
1329
  Open a new tab in the active browser context, make it active and bring
@@ -1255,7 +1365,7 @@ no new tab within it, the step fails with
1255
1365
 
1256
1366
  ```js
1257
1367
  click(getByRole('button', {name: 'Open report'}));
1258
- tab = waitForPage(); // e.g. 1, now active
1368
+ const tab = waitForPage(); // e.g. 1, now active
1259
1369
  assertUrl('/report');
1260
1370
  setPage(0);
1261
1371
  ```
@@ -1277,6 +1387,7 @@ back lands where the scenario left off.
1277
1387
 
1278
1388
  ```js
1279
1389
  function test_second_client_writes_to_closed_thread() {
1390
+ let clientB;
1280
1391
  step("Client A opens the thread", () => {
1281
1392
  flow_login(LOGIN, PASSWORD);
1282
1393
  goto('/support/thread/42');
@@ -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:
@@ -1473,9 +1637,9 @@ Headless needs `channel: "chromium"` (the headless shell ignores
1473
1637
  `--load-extension`).
1474
1638
 
1475
1639
  ```js
1476
- id = extensionId();
1640
+ const id = extensionId();
1477
1641
  evaluateInServiceWorker('(theme) => chrome.storage.local.set({theme: theme})', 'dark');
1478
- stored = evaluateInServiceWorker('() => chrome.storage.local.get("theme")');
1642
+ const stored = evaluateInServiceWorker('() => chrome.storage.local.get("theme")');
1479
1643
  goto('chrome-extension://' + id + '/popup.html');
1480
1644
  ```
1481
1645
 
@@ -1508,7 +1672,7 @@ Returns empty string when key is absent.
1508
1672
 
1509
1673
  ```js
1510
1674
  setLocalStorage('feature-flag', 'enabled');
1511
- v = getLocalStorage('feature-flag');
1675
+ const v = getLocalStorage('feature-flag');
1512
1676
  ```
1513
1677
 
1514
1678
  ### `setCookie(name, value, options?)` / `getCookie(name)` → `string`
@@ -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
@@ -1607,8 +1794,8 @@ Semantics:
1607
1794
  (values stay masked in logs).
1608
1795
 
1609
1796
  ```js
1610
- out = shell('pnpm', 'db:create-user', 'alice'); // non-zero exit → step fails
1611
- probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
1797
+ const out = shell('pnpm', 'db:create-user', 'alice'); // non-zero exit → step fails
1798
+ const probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
1612
1799
  if (probe.code == 0) { /* … */ }
1613
1800
  ```
1614
1801
 
@@ -1659,7 +1846,7 @@ downloads that are there but did not match.
1659
1846
  ```js
1660
1847
  step("Export the report", () => {
1661
1848
  click(getByRole('button', {name: 'Export CSV'}));
1662
- report = waitForDownload({name: /\.csv$/});
1849
+ const report = waitForDownload({name: /\.csv$/});
1663
1850
  waitForFile(report.path, 'id,total');
1664
1851
  });
1665
1852
  ```
@@ -1695,7 +1882,7 @@ export default {
1695
1882
 
1696
1883
  ```js
1697
1884
  step("Wait for the bot reply in the JSONL feed", () => {
1698
- line = waitForFile('events.jsonl', /"type":"reply"/, {timeoutMs: 30000});
1885
+ const line = waitForFile('events.jsonl', /"type":"reply"/, {timeoutMs: 30000});
1699
1886
  });
1700
1887
  ```
1701
1888
 
@@ -1727,7 +1914,7 @@ its fields.
1727
1914
 
1728
1915
  ```js
1729
1916
  step("Wait for the bot's reply event", () => {
1730
- evt = waitForJsonLine('events.jsonl',
1917
+ const evt = waitForJsonLine('events.jsonl',
1731
1918
  {userId: BOT_ID, roomId: room, isBot: true}, {timeoutMs: 30000});
1732
1919
  assertTrue(textContains(evt.text, 'hello'), evt.text);
1733
1920
  });
@@ -1766,7 +1953,7 @@ equality per key, dot paths for nesting, unparsable lines skipped).
1766
1953
 
1767
1954
  ```js
1768
1955
  step("Ask control question 3", () => {
1769
- q = readJsonLine('questions.jsonl', {slot: 3});
1956
+ const q = readJsonLine('questions.jsonl', {slot: 3});
1770
1957
  fill(getByRole('textbox', {name: 'Message'}), q.text);
1771
1958
  screenshot(q.id);
1772
1959
  });
@@ -1789,7 +1976,7 @@ fixture object. Walk the result with `.` and `[]`.
1789
1976
 
1790
1977
  ```js
1791
1978
  step("Send button uses the app's own label", () => {
1792
- shared = readJson('unotest/fixtures/shared.json');
1979
+ const shared = readJson('unotest/fixtures/shared.json');
1793
1980
  assertVisible(getByRole('button', {name: shared.chat.labels[0].send}));
1794
1981
  });
1795
1982
  ```
@@ -1814,7 +2001,7 @@ instead of failing the step, and `null` when no fallback is given.
1814
2001
  The fallback is the one-line default; `??` says the same:
1815
2002
 
1816
2003
  ```js
1817
- api = env('API_URL', 'http://localhost:3000');
2004
+ let api = env('API_URL', 'http://localhost:3000');
1818
2005
  api = env('API_URL') ?? 'http://localhost:3000';
1819
2006
  ```
1820
2007
 
@@ -1841,7 +2028,7 @@ download.
1841
2028
 
1842
2029
  ```js
1843
2030
  step("Export is a PNG", () => {
1844
- bytes = readFile('unotest/fixtures/files/image-3x2.png', {encoding: 'base64'});
2031
+ const bytes = readFile('unotest/fixtures/files/image-3x2.png', {encoding: 'base64'});
1845
2032
  assertTrue(textContains(bytes, 'iVBORw0KGgo'), 'not a PNG signature');
1846
2033
  });
1847
2034
  ```
@@ -1865,7 +2052,7 @@ The dimensions come from the PNG header, so a large image is not read.
1865
2052
 
1866
2053
  ```js
1867
2054
  step("Fixture image is 3x2", () => {
1868
- info = readFileInfo('unotest/fixtures/files/image-3x2.png');
2055
+ const info = readFileInfo('unotest/fixtures/files/image-3x2.png');
1869
2056
  assertTrue(info.png.width == 3 && info.png.height == 2, 'size: ' + info.size);
1870
2057
  });
1871
2058
  ```
@@ -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:
@@ -1916,7 +2135,7 @@ Parameterized SELECT. Driver picked by URL scheme:
1916
2135
  - `sqlite:…` / `*.db` / `*.sqlite` — needs `better-sqlite3`
1917
2136
 
1918
2137
  ```js
1919
- rows = dbQuery('select id from users where email = ?', 'a@b.c');
2138
+ const rows = dbQuery('select id from users where email = ?', 'a@b.c');
1920
2139
  ```
1921
2140
 
1922
2141
  ### `dbExec(sql, ...params)` → `number` (affected rows)
@@ -1933,18 +2152,18 @@ HTTP via global `fetch`. **`path` must be relative** (starts with `/`) —
1933
2152
  absolute URLs throw to prevent scenarios from hitting arbitrary hosts.
1934
2153
 
1935
2154
  ```js
1936
- res = apiCall('POST', '/auth/login', {email: 'a@b.c', password: 'x'});
2155
+ const 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:
1944
2163
 
1945
2164
  ```js
1946
2165
  // unotest/.env: API_BASE_CHAT=https://chatbackend.example.com
1947
- res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
2166
+ const res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
1948
2167
  {base: 'API_BASE_CHAT'});
1949
2168
  ```
1950
2169
 
@@ -1973,11 +2192,26 @@ 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
+ const 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
 
1979
2213
  ```js
1980
- res = apiCall('POST', '/tenants/t1/documents',
2214
+ const res = apiCall('POST', '/tenants/t1/documents',
1981
2215
  upload('fixtures/manual.pdf', {fields: {source: 'e2e'}}),
1982
2216
  {Authorization: BEARER});
1983
2217
  assertTrue(res.status == 202, 'ingestion not accepted');
@@ -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`.
@@ -2070,7 +2452,7 @@ JSON (null when it is not JSON).
2070
2452
  ```js
2071
2453
  mockRoute('**/api/messages', { body: { ok: true } });
2072
2454
  click(getByRole('button', { name: 'Send' }));
2073
- req = waitForRequest('**/api/messages');
2455
+ const req = waitForRequest('**/api/messages');
2074
2456
  assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
2075
2457
  ```
2076
2458
 
@@ -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
+ const 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.
@@ -2107,7 +2621,7 @@ Read page properties directly into a local variable.
2107
2621
  ### `getAttribute(loc, name)` → `string`
2108
2622
 
2109
2623
  ```js
2110
- href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
2624
+ const href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
2111
2625
  ```
2112
2626
 
2113
2627
  Returns `""` when the attribute is missing — which makes it **blind to
@@ -2133,7 +2647,7 @@ Where the element lies in the viewport, CSS pixels. `null` when it is
2133
2647
  not rendered (`display:none`, detached). Does not scroll it into view.
2134
2648
 
2135
2649
  ```js
2136
- box = boundingBox(getByRole('dialog'));
2650
+ const box = boundingBox(getByRole('dialog'));
2137
2651
  assertTrue(box.width <= 480, json(box));
2138
2652
  ```
2139
2653
 
@@ -2147,7 +2661,7 @@ not set reads `""`. A missing or ambiguous element fails as
2147
2661
 
2148
2662
  ```js
2149
2663
  assertTrue(computedStyle(getByRole('dialog'), 'opacity') == 1, 'dialog is faded');
2150
- accent = computedStyle(locator('body'), '--accent');
2664
+ const accent = computedStyle(locator('body'), '--accent');
2151
2665
  ```
2152
2666
 
2153
2667
  ### `getImageSize(loc)` → `{width, height}` | `null`
@@ -2168,7 +2682,7 @@ image is never read too early as broken.
2168
2682
  numbers.
2169
2683
 
2170
2684
  ```js
2171
- size = getImageSize(getByRole('img', {name: 'Avatar'}));
2685
+ const size = getImageSize(getByRole('img', {name: 'Avatar'}));
2172
2686
  assertTrue(size !== null, 'avatar is broken');
2173
2687
  assertTrue(size.width >= 256, json(size));
2174
2688
  ```
@@ -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
+ const list = animations(getByTestId('status'));
2718
+ const 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.
@@ -2220,7 +2756,7 @@ Random lowercase letters, default 8 — digit-free unique markers for apps
2220
2756
  whose content filters reject numbers in text.
2221
2757
 
2222
2758
  ```js
2223
- marker = randomWord(10);
2759
+ const marker = randomWord(10);
2224
2760
  fill(getByRole('textbox'), textJoin(['ping ', marker]));
2225
2761
  waitForText(marker);
2226
2762
  ```
@@ -2231,7 +2767,7 @@ Substring probe for data that came back as a string — shell stdout,
2231
2767
  apiCall bodies. The read-side counterpart of `textJoin`.
2232
2768
 
2233
2769
  ```js
2234
- out = shell('./status.sh');
2770
+ const out = shell('./status.sh');
2235
2771
  assertTrue(textContains(out.stdout, 'ready'), out.stderr);
2236
2772
  ```
2237
2773
 
@@ -2243,9 +2779,9 @@ took no part in the match is `null`. The array is truthy, so the call
2243
2779
  also works as a test.
2244
2780
 
2245
2781
  ```js
2246
- m = textMatches(getUrl(), /room=(\d+)/);
2782
+ const m = textMatches(getUrl(), /room=(\d+)/);
2247
2783
  assertTrue(m, getUrl());
2248
- roomId = m[1];
2784
+ const roomId = m[1];
2249
2785
  ```
2250
2786
 
2251
2787
  A string pattern is refused: for a plain substring use `textContains`.
@@ -2259,7 +2795,7 @@ setting. Invalid JSON fails the step and quotes the input; an empty
2259
2795
  string is not JSON.
2260
2796
 
2261
2797
  ```js
2262
- saved = parseJson(getLocalStorage('messages'));
2798
+ const saved = parseJson(getLocalStorage('messages'));
2263
2799
  assertEqual(saved[0].type, 'hello');
2264
2800
  ```
2265
2801
 
@@ -2269,7 +2805,7 @@ A query parameter, decoded. `null` when the key is absent, `''` when it
2269
2805
  is present but empty. A path without a host (`/room?id=7`) works too.
2270
2806
 
2271
2807
  ```js
2272
- src = getAttribute(locator('iframe#chat'), 'src');
2808
+ const src = getAttribute(locator('iframe#chat'), 'src');
2273
2809
  assertEqual(urlParam(src, 'roomId'), 'r-7');
2274
2810
  ```
2275
2811
 
@@ -2293,9 +2829,9 @@ A number as a page writes it, for arithmetic and comparison. What
2293
2829
  - A number passes through unchanged.
2294
2830
 
2295
2831
  ```js
2296
- total = toNumber(getInnerText(getByTestId('total'))); // "1 234,50"
2832
+ const total = toNumber(getInnerText(getByTestId('total'))); // "1 234,50"
2297
2833
  assertTrue(total > 1000, 'total: ' + total);
2298
- width = toNumber(textMatches(computedStyle(phone, '--phone-w'), /(\d+)px/)[1]);
2834
+ const width = toNumber(textMatches(computedStyle(phone, '--phone-w'), /(\d+)px/)[1]);
2299
2835
  ```
2300
2836
 
2301
2837
  ### `round(n, digits?)` → `number`
@@ -2306,7 +2842,7 @@ zero, on the decimal as written: `round(2.5)` is 3, `round(-2.5)` is
2306
2842
  `toNumber` first.
2307
2843
 
2308
2844
  ```js
2309
- payout = round(stake * odds, 2);
2845
+ const payout = round(stake * odds, 2);
2310
2846
  ```
2311
2847
 
2312
2848
  ### `formatNumber(n, options?)` → `string`
@@ -2335,7 +2871,7 @@ steps: an object concatenated with `+` collapses into
2335
2871
  body that explained it.
2336
2872
 
2337
2873
  ```js
2338
- res = apiCall('POST', '/documents', upload('fixtures/doc.pdf'));
2874
+ const res = apiCall('POST', '/documents', upload('fixtures/doc.pdf'));
2339
2875
  assertTrue(res.status == 202, json(res.body));
2340
2876
  ```
2341
2877
 
@@ -2379,7 +2915,7 @@ written, the way Playwright sends `fn.toString()`: the page sees none of
2379
2915
  the scenario's variables, only the arguments after it.
2380
2916
 
2381
2917
  ```js
2382
- height = evaluate(() => document.documentElement.scrollHeight);
2918
+ let height = evaluate(() => document.documentElement.scrollHeight);
2383
2919
  height = evaluate(`document.documentElement.scrollHeight`); // the string form
2384
2920
  ```
2385
2921
 
@@ -2389,8 +2925,8 @@ destructures. So one argument is `function(x)`, not `function([x])` —
2389
2925
  that one fails with `2 is not iterable`.
2390
2926
 
2391
2927
  ```js
2392
- doubled = evaluate((n) => n * 2, 21); // one → the value
2393
- result = evaluate(
2928
+ const doubled = evaluate((n) => n * 2, 21); // one → the value
2929
+ const result = evaluate(
2394
2930
  ([a, b]) => window.myApp.compute(a, b),
2395
2931
  10, 20 // two → one array
2396
2932
  );
@@ -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
@@ -2420,7 +2965,7 @@ The body gets the element first, then the extras by the same rule as
2420
2965
  array.
2421
2966
 
2422
2967
  ```js
2423
- ok = evaluateOnLocator(getByRole('main'), (el, [a, b]) => el.children.length > a + b, 1, 2);
2968
+ const ok = evaluateOnLocator(getByRole('main'), (el, [a, b]) => el.children.length > a + b, 1, 2);
2424
2969
  ```
2425
2970
 
2426
2971
  Reach for it only for what no typed call reads — a style is
@@ -2430,7 +2975,7 @@ why it uses the hatch, and the linter takes the reason:
2430
2975
 
2431
2976
  ```js
2432
2977
  // Truncated with an ellipsis: the content is wider than the cell.
2433
- overflows = evaluateOnLocator(getByRole('cell', {name: /^R-00001/}), `(el) => el.scrollWidth > el.clientWidth`); // lint-ok: no typed getter reads scrollWidth
2978
+ const overflows = evaluateOnLocator(getByRole('cell', {name: /^R-00001/}), `(el) => el.scrollWidth > el.clientWidth`); // lint-ok: no typed getter reads scrollWidth
2434
2979
  assertTrue(overflows === false, 'the id is cut off');
2435
2980
  ```
2436
2981
 
@@ -2457,7 +3002,7 @@ screenshot('landing', {fullPage: true}); // full scroll height
2457
3002
  names its evidence after the case it is on:
2458
3003
 
2459
3004
  ```js
2460
- q = waitForJsonLine('questions.jsonl', {slot: 3});
3005
+ const q = waitForJsonLine('questions.jsonl', {slot: 3});
2461
3006
  screenshot(q.id); // 003-q-17.png
2462
3007
  screenshot(textJoin(['q-', q.id, '-answer']));
2463
3008
  ```
@@ -2493,10 +3038,10 @@ page like any other.
2493
3038
 
2494
3039
  ```js
2495
3040
  click(getByRole('button', { name: 'Save' }));
2496
- errors = consoleEntries({ level: 'error' });
3041
+ const errors = consoleEntries({ level: 'error' });
2497
3042
  assertTrue(errors.length == 0, json(errors));
2498
3043
 
2499
- before = nowMs();
3044
+ const before = nowMs();
2500
3045
  click(getByRole('button', { name: 'Retry' }));
2501
3046
  assertTrue(consoleEntries({ level: ['warn', 'error'], since: before }).length == 1, 'one complaint');
2502
3047
  ```
@@ -2519,7 +3064,7 @@ is empty when the browser gave none. The last 100 are kept.
2519
3064
 
2520
3065
  ```js
2521
3066
  click(getByRole('button', { name: 'Load' }));
2522
- thrown = pageErrors();
3067
+ const thrown = pageErrors();
2523
3068
  assertTrue(thrown.length == 0, json(thrown));
2524
3069
  ```
2525
3070
 
@@ -2569,7 +3114,7 @@ step.soft("Question", {tag: q.id}, () => {
2569
3114
  note('question', q.text);
2570
3115
  fill(getByRole('textbox', {name: 'Message'}), q.text);
2571
3116
  press(getByRole('textbox', {name: 'Message'}), 'Enter');
2572
- answer = textContent(getByTestId('last-answer'));
3117
+ const answer = textContent(getByTestId('last-answer'));
2573
3118
  note('answer', answer);
2574
3119
  assertJudge(getByTestId('last-answer'), q.rubric);
2575
3120
  });
@@ -2597,28 +3142,251 @@ 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
- A scenario file is JavaScript (ES2020), run by unotest's own
2603
- interpreter, not by Node. The parser reads all of JavaScript; what the
2604
- scenario language leaves out is refused with what to write instead —
2605
- by `lint`, by `e2e` before the browser starts, and by the run when it
2606
- gets there. The list is the table in
2607
- [Outside the language](#outside-the-language). Everything else works as
2608
- in JavaScript: `let` / `const` / `var`, arrows and closures, `while`,
2609
- `for…of`, `try` / `catch`, destructuring, spread, template strings,
2610
- `?.` and `??`.
3366
+ A scenario file is JavaScript, and it runs as JavaScript: on V8, the
3367
+ engine of Node and Chrome, with the semantics of the language as it is.
3368
+ All of it runs — classes, getters, generators, labels, `instanceof`,
3369
+ `Date`, the built-in objects and their methods. What a scenario adds is
3370
+ the vocabulary (`click`, `getByRole`, `apiCall`, …). The file is parsed
3371
+ first, so a syntax error is reported before anything runs, and `lint`
3372
+ reads the same tree; its type check (`ts:*`) reports a name nothing
3373
+ declares.
2611
3374
 
2612
3375
  Two things set it apart:
2613
3376
 
2614
- - **Every call to the page or the system is awaited for you.**
2615
- `click(…)`, `apiCall(…)`, `textContent(…)` return their result, not a
2616
- promise. `await` is allowed inside an `async function` and changes
2617
- nothing.
2618
- - **The library is a white list.** `Math`, `JSON`, `Object`, string,
2619
- number and array methods are the ones in
2620
- [The library](#the-library); a member outside it is a lint error, not
2621
- `undefined` at run time.
3377
+ - **Every call to the page or the system returns its result.**
3378
+ `click(…)`, `apiCall(…)`, `textContent(…)` give the value, not a
3379
+ promise: the runner does the waiting, so a scenario has nothing to
3380
+ await. `async` and `await` are a lint error (`validator:async-await`),
3381
+ and `lint --fix` drops them. A function marked `async` would return at
3382
+ its first `await` and run the rest after the test is over, so the run
3383
+ refuses it too: a test, a step, a rollback block, a `waitUntil` or an
3384
+ `assertNever` body that returns a promise fails the test with
3385
+ `… returned a promise: … drop async and await`. Async code handed to
3386
+ the page, `evaluate(async () => …)`, is the page's and is allowed.
3387
+ - **The scenario has its own context, on its own thread.** It holds the
3388
+ vocabulary and JavaScript's built-in objects, not the APIs of Node or
3389
+ of a browser — see [Outside the language](#outside-the-language).
2622
3390
 
2623
3391
  ### A file: tests, helpers, constants
2624
3392
 
@@ -2628,8 +3396,8 @@ Two things set it apart:
2628
3396
  in order; `e2e <file> --test <name>` plays one. Functions of the file
2629
3397
  are shared between its tests, state is not.
2630
3398
  - **Top level of a file — function declarations and `const` literals.**
2631
- Nothing else there runs: `let BASE = 'x'` or a call above `test_*`
2632
- is refused (`validator:unsupported-statement`). A shared fixed value is
3399
+ Nothing else belongs there: `let BASE = 'x'` or a call above `test_*`
3400
+ is refused (`validator:top-level-statement`). A shared fixed value is
2633
3401
  a const holding a literal — a number, a string, `true` / `false` /
2634
3402
  `null`, or an array or object of those — visible in every function, as
2635
3403
  helper functions are (`const BASE = 'https://x.test';`). A computed
@@ -2666,11 +3434,11 @@ function test_order() {
2666
3434
  }
2667
3435
  ```
2668
3436
 
2669
- **Assignment without a declaration** works too: it declares the name in
2670
- the nearest top-level function — the `test_*`, the `flow_*` or the
2671
- helper. `lint` notes such a name once, as information
2672
- (`validator:implicit-declaration`), with the declaration to write. A
2673
- helper's names do not leak into its caller.
3437
+ **Assignment without a declaration** is a `lint` error
3438
+ (`validator:implicit-global`): JavaScript makes the name a global,
3439
+ shared by every test of the run. `lint --fix` writes the declaration —
3440
+ `let id;` at the start of the `test_*`, the `flow_*` or the helper,
3441
+ where every step sees it.
2674
3442
 
2675
3443
  ### Functions and callbacks
2676
3444
 
@@ -2693,9 +3461,8 @@ everywhere.
2693
3461
  ### Control flow
2694
3462
 
2695
3463
  `if` / `else`, `for`, `for…of`, `for…in` (own keys), `while`,
2696
- `do…while`, `break`, `continue`, `switch`, `return`, `throw`, `try` /
2697
- `catch` / `finally`, `cond ? a : b` — as in JavaScript. Labels are
2698
- outside the language.
3464
+ `do…while`, `break`, `continue`, labels, `switch`, `return`, `throw`,
3465
+ `try` / `catch` / `finally`, `cond ? a : b` — as in JavaScript.
2699
3466
 
2700
3467
  One check is stricter than JavaScript: an `if` whose condition `lint`
2701
3468
  knows to be a number, a string or a locator is `validator:if-shape` —
@@ -2712,18 +3479,27 @@ do {
2712
3479
  assertEqual(job.body.status, 'DONE');
2713
3480
  ```
2714
3481
 
2715
- A loop that never ends does not hang the run: the run counts the
2716
- statements it plays and stops at its budget (`maxSteps budget (100000)
2717
- exhausted`); the test ends as errored ‼, a fault of the script, not
2718
- failed.
3482
+ A loop that never ends does not hang the run: the test's time budget
3483
+ cuts it (`setTestTimeout(ms)`, else `testTimeoutMs` in the config), and
3484
+ the test fails naming the budget and the statement it was on —
3485
+ `maxDurationMs budget (60000ms) exhausted at unotest/e2e/jobs.js:12`.
3486
+ Code that never comes back to the runner at all, a regular expression
3487
+ that backtracks for minutes, is stopped a second after the budget; its
3488
+ teardown blocks cannot play then. A run that keeps too much in memory
3489
+ ends on its memory limit, and the message says so. There is no step
3490
+ count.
2719
3491
 
2720
3492
  **`try` / `catch`.** `catch (e)` takes what was thrown, as thrown:
2721
- `throw {code: 7}` gives `e.code`. A failed action — a click that found
2722
- nothing, a failed assertion — arrives as `{name, message}`, with no
2723
- stack. The parameter may be left out (`catch { … }`). An error caught by
3493
+ `throw new Error('x')` gives an `Error`, `throw {code: 7}` gives
3494
+ `e.code`. A failed action — a click that found nothing, a failed
3495
+ assertion — arrives as a plain object `{name, message}`, not an
3496
+ `Error`. An error of the language is the class JavaScript gives it:
3497
+ `null.x` throws a `TypeError`, a name nothing declares a
3498
+ `ReferenceError`. The parameter may be left out (`catch { … }`). An error caught by
2724
3499
  the scenario is not a failure: the run goes on, and the debugger does
2725
3500
  not stop on it. `catch` does not take control flow — a `skip()`, a
2726
- `return`, `break` / `continue` — nor the step budget. To give the stand back
3501
+ `return`, `break` / `continue` — nor a spent time budget: the run ends
3502
+ all the same. To give the stand back
2727
3503
  whatever happens, use [`teardown`](#teardown--give-the-stand-back), not
2728
3504
  `finally`: a teardown also plays when the run is stopped or times out.
2729
3505
 
@@ -2744,12 +3520,10 @@ it returns from them. Directly in a `test_*` body it is
2744
3520
  The right side runs only when the left one does not decide.
2745
3521
  - **`?.`** reads through a missing value: `res.body?.items?.[0]?.id`,
2746
3522
  `o.callback?.()`.
2747
- - **`typeof`, `in`** (own keys), `delete`, `void`, `++` / `--`, the
2748
- compound assignments up to `**=`, the comma operator — as in
2749
- JavaScript.
2750
- - **`+` and `<` apply to numbers and strings only.** On an object or an
2751
- array they fail the step (`Operator "+" does not apply to an object`)
2752
- instead of giving `[object Object]`: combine or compare the fields.
3523
+ - **Every operator is JavaScript's**, `typeof`, `in`, `delete`,
3524
+ `instanceof`, `++` / `--`, the compound and logical assignments
3525
+ (`??=`) and the comma operator included. `+` on an object gives
3526
+ `[object Object]`, as in JavaScript: combine the fields instead.
2753
3527
  - **A missing property or argument is `undefined`.** A host function
2754
3528
  that finds nothing returns `null`; `x == null` is true for both.
2755
3529
 
@@ -2762,8 +3536,8 @@ character is dropped, as JavaScript drops it: `'\d+'` is `d+`. For a
2762
3536
  regex write a `/…/` literal, or double the backslash (`'\\d+'`).
2763
3537
 
2764
3538
  Backticks are template strings, with `${…}` interpolation and the same
2765
- escapes. `` String.raw`…` `` keeps backslashes as written — the only tag
2766
- the language has.
3539
+ escapes. `` String.raw`…` `` keeps backslashes as written; a tag of
3540
+ your own is a function, as in JavaScript.
2767
3541
 
2768
3542
  ```js
2769
3543
  const n = 3;
@@ -2778,21 +3552,18 @@ Two lint rules guard templates:
2778
3552
  variable ever given one): the value would become code of the page.
2779
3553
  Write fixed text or a function, and pass the value as an argument.
2780
3554
  - `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`…` ``.
3555
+ with a backslash escape JavaScript drops (`\s` reads as `s`, `\.`
3556
+ as `.`): a scenario written for the earlier raw backticks loses
3557
+ characters. Double the backslash or use `` String.raw`…` ``. Escapes
3558
+ JavaScript reads as meant (`\n`, `\\`, `\u…`) are not reported.
2784
3559
 
2785
3560
  ### Regex literals
2786
3561
 
2787
3562
  A `/…/flags` literal is a JavaScript RegExp: every flag and syntax
2788
3563
  Node accepts — `i`, `g`, `m`, `s`, `u`, `y`, `d`, `v`, named groups,
2789
3564
  lookbehind. In a matcher slot (`getByText(/Items \d+/i)`) it goes to
2790
- Playwright as that RegExp; in the scenario it answers `test`, `source` and
2791
- `flags`, and the string methods `match`, `matchAll`, `replace`,
2792
- `replaceAll`, `search` and `split` take it.
2793
-
2794
- `match` gives an array of the match and its groups, or `null`; there is
2795
- no `.groups` — read a named group by its index: `s.match(/(?<id>\d+)/)[1]`.
3565
+ Playwright as that RegExp; in the scenario it is a RegExp with all its
3566
+ members, and `match(…).groups` reads a named group.
2796
3567
 
2797
3568
  ### Objects, arrays, indexes
2798
3569
 
@@ -2807,11 +3578,12 @@ for (const [key, value] of Object.entries(counts)) note(key, value);
2807
3578
  ```
2808
3579
 
2809
3580
  A variable holds the array or object itself, not a copy: after
2810
- `b = a; a.push(1)`, `b` has the new element too. `arr[i] = v` takes an
2811
- index from `0` to `arr.length` — the length appends, an index further
2812
- out fails the step instead of leaving holes. The keys `__proto__`,
2813
- `constructor` and `prototype` cannot be assigned, and a value has no
2814
- prototype to reach: `o.constructor` and `[].map.call` are `undefined`.
3581
+ `b = a; a.push(1)`, `b` has the new element too.
3582
+
3583
+ **An object handed to a DSL function crosses with its own keys only.**
3584
+ A key it inherits — written under `__proto__:` or made by
3585
+ `Object.create(…)` — would be lost on the way, so the call fails
3586
+ instead: write each key on the object itself.
2815
3587
 
2816
3588
  **Locators are not arrays.** An index on a locator is refused
2817
3589
  (`validator:locator-index-access`):
@@ -2829,53 +3601,27 @@ const third = getByRole('row').nth(2);
2829
3601
 
2830
3602
  ### The library
2831
3603
 
2832
- A scenario reads these names — the whole list. A member outside it is a
2833
- lint error that names it: `validator:library-member` on a namespace
2834
- (`Math.tau`), `validator:unsupported-string-member` on a string,
2835
- `validator:unknown-member` on an array, a number, a Map or a Set.
2836
-
2837
- | Global | Members |
2838
- |---|---|
2839
- | `Math` | `E` `LN10` `LN2` `LOG10E` `LOG2E` `PI` `SQRT1_2` `SQRT2`, `abs` `acos` `acosh` `asin` `asinh` `atan` `atan2` `atanh` `cbrt` `ceil` `clz32` `cos` `cosh` `exp` `expm1` `floor` `fround` `hypot` `imul` `log` `log10` `log1p` `log2` `max` `min` `pow` `round` `sign` `sin` `sinh` `random` `sqrt` `tan` `tanh` `trunc` |
2840
- | `JSON` | `parse`, `stringify` |
2841
- | `Number(x)` | `EPSILON` `MAX_SAFE_INTEGER` `MAX_VALUE` `MIN_SAFE_INTEGER` `MIN_VALUE` `NaN` `NEGATIVE_INFINITY` `POSITIVE_INFINITY`, `isFinite` `isInteger` `isNaN` `isSafeInteger` `parseFloat` `parseInt` |
2842
- | `String(x)` | `raw` |
2843
- | `Array` | `isArray`, `from`, `of` |
2844
- | `Object` | `keys`, `values`, `entries`, `fromEntries`, `assign`, `hasOwn` |
2845
- | `new Map(entries?)`, `new Set(items?)` | the only `new` in the language |
2846
- | functions | `parseInt`, `parseFloat`, `isNaN`, `isFinite` |
2847
-
2848
- | Value | Members |
2849
- |---|---|
2850
- | 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` |
2851
- | number | `toFixed`, `toPrecision`, `toString(radix)` |
2852
- | regex | `source`, `flags`, `test` |
2853
- | array | `length`, `push` `pop` `shift` `unshift` `slice` `splice` `concat` `join` `reverse` `indexOf` `lastIndexOf` `includes` `at` `flat` `fill` `toReversed` `toSpliced` `with`; with a callback: `forEach` `map` `filter` `flatMap` `some` `every` `find` `findIndex` `findLast` `findLastIndex` `reduce` `reduceRight` `sort` `toSorted`; and `sortBy` |
2854
- | Map | `size`, `get` `set` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
2855
- | Set | `size`, `add` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
2856
-
2857
- The methods behave as in JavaScript; `matchAll` gives an array, and so
2858
- do `keys()`, `values()` and `entries()` of a Map or a Set
2859
- (`m.keys().map(…)` works directly). `for…of`, a spread and `Array.from`
2860
- iterate a Map or a Set as in JavaScript; `note`, `log` and the viewer
2861
- show one as `Map(1) {"a" => 1}`. A Map keeps its entries apart from its
2862
- members: `m.length` is a lint error, the count is `m.size`.
2863
- `Math.random()` draws a new number on every call, so a run that uses it
2864
- differs from the last one; for fresh test data `randomWord(n)` and
2865
- `randomEmail()` read better. `undefined`, `NaN` and `Infinity` are
2866
- values too.
2867
-
2868
- **`arr.sortBy(key?, {desc?})`** sorts the array in place and returns it.
2869
- With a key every element is an object and its field is compared;
2870
- without one (`sortBy()`, or `sortBy(null, {desc: true})`) the elements
2871
- themselves. The compared values are all numbers or all strings —
2872
- anything else fails the step. The sort is stable.
2873
-
2874
- ```js
2875
- const controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
2876
- controls.sortBy('order'); // a, b
2877
- controls.sortBy('order', {desc: true});
2878
- ```
3604
+ JavaScript's built-in objects, with all their members: `Math`, `JSON`,
3605
+ `Number`, `String`, `Array`, `Object`, `Date`, `Map`, `Set`, `RegExp`,
3606
+ `Promise`, `Symbol`, the errors, typed arrays. `lint` reports a member
3607
+ a value does not have in JavaScript: `validator:unknown-member` on a
3608
+ string, an array, a number, a Map or a Set, and its type check (`ts:*`)
3609
+ on the rest (`Math.tau`).
3610
+
3611
+ **A DSL function does not take an iterator.** `matchAll`, and `keys()`,
3612
+ `values()` and `entries()` of a Map or a Set, give iterators, as in
3613
+ JavaScript; `for…of`, a spread and `Array.from` read them. For array
3614
+ methods, and for a DSL function, spread first:
3615
+ `assertEqual([...m.keys()], ['a'])`, or pass the Map itself
3616
+ (`assertEqual(m.keys(), …)` fails, naming the line and the spread to
3617
+ write). `note`, `log` and the viewer show a Map as `Map(1) {"a" => 1}`.
3618
+
3619
+ `Date` reads the clock of the machine the runner is on. `clockFreeze`
3620
+ and `clockTick` move the page's clock, not this one; read the page's
3621
+ time through `evaluate`, or with `nowMs()` / `today()`.
3622
+ `Math.random()` draws a new number on every call, so a run that uses
3623
+ it differs from the last one; for fresh test data `randomWord(n)` and
3624
+ `randomEmail()` read better.
2879
3625
 
2880
3626
  With a function argument `filter` is the array method; with an options
2881
3627
  object it is still the locator step:
@@ -2883,37 +3629,21 @@ object it is still the locator step:
2883
3629
 
2884
3630
  ### Outside the language
2885
3631
 
2886
- What JavaScript has and a scenario does not — refused by `lint`
2887
- (`validator:out-of-language`, error) and by the run, with the
2888
- replacement:
3632
+ The scenario's context has the vocabulary, the built-in forms and
3633
+ JavaScript's built-in objects — not the APIs of Node or of a browser:
2889
3634
 
2890
- | Not in the language | Write instead |
3635
+ | Not there | Write instead |
2891
3636
  |---|---|
2892
3637
  | `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 |
2894
- | `get` / `set` in an object literal | a plain property or a function |
2895
- | `function*`, `yield` | an array and a loop |
2896
- | `for await` | `for…of` — host calls are awaited already |
2897
- | `Date`, `new Date()` | `clockFreeze` / `clockTick` / `clockRun`; the page's time via `evaluate`; `nowMs()`, `today()` |
2898
- | `setTimeout`, `setInterval` and the other timers | `pause(ms)` or `waitUntil(() => …)` |
2899
- | `Promise`, `.then` | nothing: host calls are awaited already |
2900
- | `eval`, `Function(…)` | page code goes to `evaluate(fn, arg)` |
2901
- | `process`, `window`, `document`, `globalThis`, `fetch`, `console`, `localStorage`, `navigator`, `location` | an `UPPER_SNAKE` external variable or `env(…)`; the page via `evaluate(…)`; HTTP via `apiCall(…)`; output via `note(…)` / `log(…)` |
2902
- | `WeakMap`, `WeakSet`, `WeakRef` | a `Map` or a `Set` |
2903
- | `Symbol`, `Proxy`, `Reflect` | plain objects |
2904
- | `instanceof` | `Array.isArray(x)` or `typeof x` |
2905
- | `with` | name the object: `obj.prop` |
2906
- | labels | a helper function and `return` |
2907
- | `debugger` | a breakpoint in the viewer, or `pause()` |
2908
- | BigInt (`1n`) | a number |
2909
- | `&&=`, `\|\|=`, `??=` | the full form: `x = x ?? value` |
2910
- | tagged templates | `` String.raw`…` `` is the only tag |
2911
- | `new.target`, `import.meta` | pass the value as a parameter |
2912
-
2913
- A name in the table is refused only when the scenario does not declare
2914
- it: `const window = 1;` is an ordinary variable. `new` is the other way
2915
- round: it applies to the library's `Map` and `Set` only, never to a
2916
- name the scenario declares.
3638
+ | `process`, `fetch` | `apiCall(…)` for HTTP, `shell(…)` for a command, `UPPER_SNAKE` variables or `env(…)` for external values |
3639
+ | `window`, `document`, `localStorage`, `navigator`, `location` | `evaluate(fn, arg)`: it runs the function in the page |
3640
+ | `setTimeout`, `setInterval`, `queueMicrotask` | `pause(ms)` or `waitUntil(() => …)` |
3641
+ | `console.log` | `log(…)` or `note(label, value)`: `console` is there and prints nowhere |
3642
+ | `eval(…)`, `new Function(…)` | the code itself: both are refused when called |
3643
+
3644
+ The context keeps the vocabulary apart from the runner. It is not a
3645
+ security boundary: a scenario runs with the rights of the user who
3646
+ started it, as a Playwright test does.
2917
3647
 
2918
3648
  A method call on a name nothing declares — `clock.freeze(…)`,
2919
3649
  `page.waitForTimeout(…)` as another framework spells it — is an