@unotest/web 0.49.2 → 0.51.0

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