@unotest/web 0.49.1 → 0.50.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
  });
@@ -113,15 +115,28 @@ function test_control_questions() {
113
115
 
114
116
  Scenarios are plain `.js` with an implicit global vocabulary, so an
115
117
  untouched editor shows them as broken JavaScript. `npx @unotest/web init`
116
- wires the fix; on an existing project the first `lint` / `e2e` run after a
117
- package upgrade wires it automatically (announced with one line). What it
118
- consists of:
118
+ wires the fix; on an existing project, or a fresh checkout,
119
+ `npx @unotest/web types` does. A run never writes the editor config. What
120
+ it consists of:
119
121
 
120
- - `unotest/jsconfig.json` — points the IDE at the two declaration files
121
- below. Created once when missing; never rewritten silently. Type
122
+ - `unotest/jsconfig.json` — points the IDE at the declaration files
123
+ below. Written by `init` (which also adds it to `.gitignore`) and by
124
+ `types` when missing; never rewritten silently. Type
122
125
  CHECKING stays off (`checkJs: false`) on purpose: diagnostics come from
123
126
  the DSL validator (`npx @unotest/web lint`), the editor only gains
124
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.
125
140
  - `node_modules/@unotest/web/types/unotest-dsl.d.ts` — ambient
126
141
  declarations for every DSL function, generated from the same contracts
127
142
  the validator uses and shipped with the package, so it always matches
@@ -180,23 +195,15 @@ hasNotText})`) accept either:
180
195
 
181
196
  - A string literal — matched as substring by default, exactly with
182
197
  `{exact: true}`.
183
- - A regex literal `/pattern/flags` — ECMA-262 5.1 subset.
198
+ - A regex literal `/pattern/flags` — a JavaScript RegExp, any flag
199
+ included: see [Regex literals](#regex-literals).
184
200
 
185
201
  ```js
186
202
  getByRole("link", {name: /^Sets/})
187
203
  getByText(/Items \d+/i)
188
- filter({hasText: /done/i})
204
+ getByRole('row').filter({hasText: /done/i})
189
205
  ```
190
206
 
191
- **Supported regex flags:** `g`, `i`, `m`. Post-ES5 flags (`s u y d v`)
192
- are rejected at parse time with a message naming the spec they came
193
- from — write a separate plan if you need them
194
- (`docs/dsl/regex-literal-es5.md` out-of-scope section).
195
-
196
- **Escape rules:** standard ECMA-262 5.1 grammar — `\` introduces
197
- escape sequences, `[...]` is a character class where `/` does not
198
- close the literal. No literal line breaks inside a regex body.
199
-
200
207
  ## The `timeout` option
201
208
 
202
209
  Actions, navigation, waits and assertions take their time limit in
@@ -211,14 +218,19 @@ instead of waiting the default.
211
218
 
212
219
  ## Builders
213
220
 
214
- ### `locator(selector)`
221
+ ### `locator(selector, options?)`
215
222
 
216
223
  CSS selector, last-resort escape hatch. Use only when nothing else works
217
224
  — the linter discourages this with `lint:deep-css` for `>`-bearing
218
225
  selectors.
219
226
 
227
+ `options` narrows the matches exactly as [`filter`](#filteroptions)
228
+ does: the same keys (`hasText`, `hasNotText`, `has`, `hasNot`), the same
229
+ refusal of any other key, at lint time and at run time.
230
+
220
231
  ```js
221
232
  locator('.error-banner')
233
+ locator('option', {hasText: 'Beta'}) // = locator('option').filter({hasText: 'Beta'})
222
234
  ```
223
235
 
224
236
  ### `getByRole(role, options?)`
@@ -227,10 +239,20 @@ ARIA role. `options.name` is the accessible name — string or regex
227
239
  (see [Matcher arguments](#matcher-arguments--string--regexp)).
228
240
  Substring by default, exact with `{exact: true}`.
229
241
 
242
+ The other options narrow by ARIA state, as Playwright's `getByRole` does:
243
+ `checked`, `disabled`, `expanded`, `pressed`, `selected` (true / false),
244
+ `level` (a heading level from 1) and `includeHidden` (true — match
245
+ elements hidden from the accessibility tree too). Any other key is
246
+ refused, at lint time (`validator:options`) and at run time — it would
247
+ otherwise match without it.
248
+
230
249
  ```js
231
250
  getByRole('button', {name: 'Save'})
232
251
  getByRole('heading', {name: 'Welcome', exact: true})
233
252
  getByRole('link', {name: /^Sets/}) // regex matcher
253
+ getByRole('button', {name: 'Save', disabled: false}) // the enabled one
254
+ getByRole('checkbox', {checked: true})
255
+ getByRole('heading', {level: 2})
234
256
  ```
235
257
 
236
258
  ### `getByText(text, options?)`
@@ -291,8 +313,8 @@ Each requires a locator as the receiver / first argument.
291
313
  ### `filter(options)`
292
314
 
293
315
  Narrow down a locator. `hasText`, `hasNotText`, `has`, `hasNot` — any
294
- other key is refused, at lint time (`lint:filter-unknown-option`) and at
295
- run time. A class or an attribute of the element itself goes into a CSS
316
+ other key is refused, at lint time (`validator:options`) and at run
317
+ time. A class or an attribute of the element itself goes into a CSS
296
318
  `locator(...)` instead.
297
319
 
298
320
  ```js
@@ -375,10 +397,19 @@ press(getByLabel('Body'), 'Control+A')
375
397
 
376
398
  ### `check(loc, options?)` / `uncheck(loc, options?)`
377
399
 
378
- Idempotent — no-op if already in the target state.
400
+ Idempotent — no click if already in the target state. Otherwise one
401
+ click, then a wait until the element reads checked (unchecked) within
402
+ the action timeout (`options.timeout`, else the config default). A
403
+ controlled switch the app flips a beat after the click — once the server
404
+ confirms — passes; one that never flips fails, naming the state it
405
+ wanted and the last one it saw. Works on native checkboxes and radios
406
+ and on ARIA `checkbox` / `radio` / `switch` widgets. A `<label>` — or
407
+ anything inside one — stands for the control it names (`for=` or a
408
+ wrapped input). Any other element is refused — use `click` for it.
379
409
 
380
410
  ```js
381
411
  check(getByRole('checkbox', {name: 'Subscribe'}))
412
+ uncheck(getByRole('switch', {name: 'Notifications'}), {timeout: 5000})
382
413
  ```
383
414
 
384
415
  ### `hover(loc, options?)`
@@ -844,10 +875,36 @@ assertCount(getByRole('listitem').filter({hasNotText: 'Archived'}), 3)
844
875
 
845
876
  Empty string when the element has no text node (does not throw).
846
877
 
878
+ ### `texts(loc)` → `string[]`
879
+
880
+ `textContent` of every element the locator matches, in page order; `[]`
881
+ when nothing matches. One read, no wait — the list to branch on.
882
+ `assertTexts` is the waiting check of the same list.
883
+
884
+ ```js
885
+ names = texts(locator('#agents li')); // ["Claude Code", "Codex"]
886
+ if (names.length > 0) {
887
+ log('first agent:', names[0]);
888
+ }
889
+ ```
890
+
847
891
  ### `inputValue(loc)` → `string`
848
892
 
849
893
  ### `isVisible(loc)` → `boolean`
850
894
 
895
+ ### `isChecked(loc)` → `boolean`
896
+
897
+ Checked state of a checkbox, radio or switch — native or ARIA role
898
+ (`aria-checked`); a `<label>` reads as the control it names. Any other
899
+ element fails the step instead of answering
900
+ `false`: "unchecked" and "has no checked state" are different answers.
901
+
902
+ ```js
903
+ if (isChecked(getByRole('switch', {name: 'Notifications'}))) {
904
+ uncheck(getByRole('switch', {name: 'Notifications'}));
905
+ }
906
+ ```
907
+
851
908
  ### `isDisabled(loc)` → `boolean` / `isEnabled(loc)` → `boolean`
852
909
 
853
910
  Disabled = native `:disabled` (covers `<fieldset disabled>` inheritance)
@@ -1091,7 +1148,7 @@ there rather than half-applied.
1091
1148
 
1092
1149
  `timezone` and `locale` in `unotest.config.mjs` set them for every page:
1093
1150
 
1094
- ```js
1151
+ ```js config
1095
1152
  export default {
1096
1153
  timezone: 'Europe/Madrid', // Date#toString, Intl, getTimezoneOffset
1097
1154
  locale: 'es-ES', // navigator.language, Intl defaults, Accept-Language
@@ -1349,7 +1406,7 @@ Where the window's size and scale come from, first match wins:
1349
1406
  first scenario starts, as in the config.
1350
1407
  3. **The config.** `unotest.config.mjs`:
1351
1408
 
1352
- ```js
1409
+ ```js config
1353
1410
  export default {
1354
1411
  viewport: { width: 390, height: 844, deviceScaleFactor: 2 },
1355
1412
  };
@@ -1365,7 +1422,7 @@ Where the window's size and scale come from, first match wins:
1365
1422
  has no window manager — the size comes from `--window-size` in
1366
1423
  `launch.args`:
1367
1424
 
1368
- ```js
1425
+ ```js config
1369
1426
  export default {
1370
1427
  viewport: null,
1371
1428
  launch: { args: ["--window-size=1440,900"] },
@@ -1426,7 +1483,8 @@ goto('chrome-extension://' + id + '/popup.html');
1426
1483
  `chrome-extension://<id>/sw.js`. A running worker comes back at once;
1427
1484
  otherwise it waits up to `timeoutMs` (default: the navigation timeout).
1428
1485
  `url` — a substring or `/regex/` when several extensions run.
1429
- - `evaluateInServiceWorker(js, ...args)` — `evaluate` in the worker. The
1486
+ - `evaluateInServiceWorker(js, ...args)` — `evaluate` in the worker.
1487
+ `js` is a function or a string, under the same page-code rules. The
1430
1488
  extras reach the body by the same rule as `evaluate`: none →
1431
1489
  `undefined`, one → the value itself, two or more → one array. JSON
1432
1490
  return; a returned Promise is awaited. Not discouraged by the
@@ -1504,7 +1562,7 @@ Project-agnostic core (D-13, D-27). Consumers wire connection / base-URL
1504
1562
  config in `unotest/unotest.config.{js,mjs,ts}` under `sandbox.{shellCwd, database,
1505
1563
  apiBaseUrl}` — the scenario **cannot** override.
1506
1564
 
1507
- ```js
1565
+ ```js config
1508
1566
  // unotest/unotest.config.mjs
1509
1567
  export default {
1510
1568
  sandbox: {
@@ -1628,7 +1686,7 @@ yet is judged by the nearest directory above it that does.
1628
1686
  A background process that writes outside the project (a listener's log
1629
1687
  in `/tmp`) needs its directory in the config:
1630
1688
 
1631
- ```js
1689
+ ```js config
1632
1690
  // unotest/unotest.config.mjs
1633
1691
  export default {
1634
1692
  sandbox: { readRoots: ['/tmp/my-listener'] },
@@ -1746,12 +1804,21 @@ step("Send button uses the app's own label", () => {
1746
1804
  generate the JSON from them instead — see
1747
1805
  [App constants in scenarios](https://docs.unotest.com/concepts/scenarios/#app-constants-in-scenarios).
1748
1806
 
1749
- ### `env(name)` → `string | null`
1807
+ ### `env(name, fallback?)` → `string | null`
1750
1808
 
1751
1809
  An environment value the test can do without. It reads what a bare
1752
1810
  `UPPER_SNAKE` name reads — the environment the run started in, then
1753
- `unotest/.env` — but returns `null` for a name that is not set instead
1754
- of failing the step. Use it to decide:
1811
+ `unotest/.env` — but returns `fallback` for a name that is not set
1812
+ instead of failing the step, and `null` when no fallback is given.
1813
+
1814
+ The fallback is the one-line default; `??` says the same:
1815
+
1816
+ ```js
1817
+ api = env('API_URL', 'http://localhost:3000');
1818
+ api = env('API_URL') ?? 'http://localhost:3000';
1819
+ ```
1820
+
1821
+ Without a fallback, use the `null` to decide:
1755
1822
 
1756
1823
  ```js
1757
1824
  if (env('LIVE_API') == null) {
@@ -1762,8 +1829,8 @@ if (env('LIVE_API') == null) {
1762
1829
  ```
1763
1830
 
1764
1831
  A secret — a name from `unotest/.secrets`, or one a box injects — is
1765
- refused: `env()` returns a plain string, and a credential must stay
1766
- masked. Write the secret's bare name where its value is typed instead.
1832
+ refused, with a fallback or without: `env()` returns a plain string, and
1833
+ a credential must stay masked. Write the secret's bare name where its value is typed instead.
1767
1834
 
1768
1835
  ### `readFile(path, options?)` → `string`
1769
1836
 
@@ -1881,9 +1948,11 @@ res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
1881
1948
  {base: 'API_BASE_CHAT'});
1882
1949
  ```
1883
1950
 
1884
- The variable must hold an http(s) URL; an unknown name fails with the
1885
- usual "add it to unotest/.env" message. URLs never appear in the
1886
- scenario — hosts are controlled by project env files only.
1951
+ The variable must hold an http(s) URL. It is read from the project's
1952
+ environment only: a scenario variable of the same name is not a base,
1953
+ and a name the environment does not hold is refused with where to put
1954
+ it. URLs never appear in the scenario — hosts are controlled by project
1955
+ env files only.
1887
1956
 
1888
1957
  **With an environment overlay active, the base must come from it.**
1889
1958
  Running `--env dev` while `API_BASE_CHAT` is set only in the base
@@ -1893,7 +1962,7 @@ base host while everything else in the run resolves against `dev`. Set
1893
1962
  the name in `unotest/.env.dev`, or, when the base value really is meant
1894
1963
  for every environment, list the name in the config:
1895
1964
 
1896
- ```js
1965
+ ```js config
1897
1966
  // unotest/unotest.config.mjs
1898
1967
  export default { env: { shared: ['API_BASE_CHAT'] } };
1899
1968
  ```
@@ -2305,8 +2374,13 @@ dates.
2305
2374
  context. Discouraged (`lint:evaluate-discouraged`) — prefer typed
2306
2375
  getters or the action API.
2307
2376
 
2377
+ `js` is a function or a string. A function is sent to the page as it is
2378
+ written, the way Playwright sends `fn.toString()`: the page sees none of
2379
+ the scenario's variables, only the arguments after it.
2380
+
2308
2381
  ```js
2309
- height = evaluate(`document.documentElement.scrollHeight`);
2382
+ height = evaluate(() => document.documentElement.scrollHeight);
2383
+ height = evaluate(`document.documentElement.scrollHeight`); // the string form
2310
2384
  ```
2311
2385
 
2312
2386
  The extra arguments reach the body by one rule: none → `undefined`,
@@ -2315,15 +2389,30 @@ destructures. So one argument is `function(x)`, not `function([x])` —
2315
2389
  that one fails with `2 is not iterable`.
2316
2390
 
2317
2391
  ```js
2318
- doubled = evaluate(`function(n) { return n * 2; }`, 21); // one → the value
2392
+ doubled = evaluate((n) => n * 2, 21); // one → the value
2319
2393
  result = evaluate(
2320
- `function([a, b]) { return window.myApp.compute(a, b); }`,
2394
+ ([a, b]) => window.myApp.compute(a, b),
2321
2395
  10, 20 // two → one array
2322
2396
  );
2323
2397
  ```
2324
2398
 
2325
- Backticks are **raw** — `${…}` interpolation is rejected at parse time
2326
- (see `vendor/dsl/EXTENSIONS.md`).
2399
+ Page code built from scenario values is an error
2400
+ (`validator:evaluate-interpolation`): a `${…}` in it, a `+` of a value,
2401
+ or a variable that is ever given one — a value in it would become code
2402
+ of the page. Text the source spells out passes: a string, a template
2403
+ without `${…}`, `+` of those, or a variable every assignment of which
2404
+ is one, declared with `let` or `const` or not at all, or the variable
2405
+ of a `for…of` over an array literal of such texts. A function handed
2406
+ to the page reads only its own parameters
2407
+ (`validator:page-code-closure`). Pass values as arguments instead. The
2408
+ run checks both rules before it starts, in the test and in every helper
2409
+ of `_helpers/` it loads, and stops on them.
2410
+
2411
+ A page whose main thread is busy — a script loop, a long task — cannot
2412
+ start the script. `evaluate` then fails the step after the action timeout
2413
+ (the config's `defaultTimeoutMs`) with `the page gave no answer` instead
2414
+ of waiting forever. Once the script has started, it runs as long as it
2415
+ needs: an `async` body that awaits a slow promise is not cut off.
2327
2416
 
2328
2417
  `evaluateOnLocator(loc, js, ...args)` — the same hatch on one element.
2329
2418
  The body gets the element first, then the extras by the same rule as
@@ -2331,7 +2420,7 @@ The body gets the element first, then the extras by the same rule as
2331
2420
  array.
2332
2421
 
2333
2422
  ```js
2334
- ok = evaluateOnLocator(getByRole('main'), `(el, [a, b]) => el.children.length > a + b`, 1, 2);
2423
+ ok = evaluateOnLocator(getByRole('main'), (el, [a, b]) => el.children.length > a + b, 1, 2);
2335
2424
  ```
2336
2425
 
2337
2426
  Reach for it only for what no typed call reads — a style is
@@ -2499,268 +2588,337 @@ step.soft("Question", {tag: q.id}, () => {
2499
2588
  - When a statement fails, the notes of its `step(...)` block (the
2500
2589
  innermost one, in call order) come with the failure: under the error
2501
2590
  in the `e2e` output as `note label: value`, and as `notes` in the
2502
- failure `run_test` returns. A green step prints nothing extra.
2591
+ failure `run_test` returns. Without `--notes` a green step prints
2592
+ nothing extra.
2593
+ - `e2e --notes` / `collection --notes` print every note of every test
2594
+ under its line, a passing test's too, as
2595
+ `note label: value — step "<step>"`. A failed test then lists them in
2596
+ place of the failing step's own, so each note prints once.
2503
2597
 
2504
2598
  ---
2505
2599
 
2506
- ## Variables, control flow, types
2600
+ ## The language — JavaScript
2601
+
2602
+ A scenario file is JavaScript (ES2020), run by unotest's own
2603
+ interpreter, not by Node. The parser reads all of JavaScript; what the
2604
+ scenario language leaves out is refused with what to write instead —
2605
+ by `lint`, by `e2e` before the browser starts, and by the run when it
2606
+ gets there. The list is the table in
2607
+ [Outside the language](#outside-the-language). Everything else works as
2608
+ in JavaScript: `let` / `const` / `var`, arrows and closures, `while`,
2609
+ `for…of`, `try` / `catch`, destructuring, spread, template strings,
2610
+ `?.` and `??`.
2611
+
2612
+ Two things set it apart:
2507
2613
 
2508
- The DSL is JavaScript-shaped but parsed by a small AST engine
2509
- (`vendor/dsl/`), not V8. What's supported in scenario files:
2614
+ - **Every call to the page or the system is awaited for you.**
2615
+ `click(…)`, `apiCall(…)`, `textContent(…)` return their result, not a
2616
+ promise. `await` is allowed inside an `async function` and changes
2617
+ nothing.
2618
+ - **The library is a white list.** `Math`, `JSON`, `Object`, string,
2619
+ number and array methods are the ones in
2620
+ [The library](#the-library); a member outside it is a lint error, not
2621
+ `undefined` at run time.
2510
2622
 
2511
- - **`function test_*(): { … }`** — a test. A file may hold several; each
2623
+ ### A file: tests, helpers, constants
2624
+
2625
+ - **`function test_*() { … }`** — a test. A file may hold several; each
2512
2626
  is its own run with its own browser context, retry and verdict, and the
2513
2627
  viewer shows it as its own row under the file. `e2e <file>` plays them
2514
2628
  in order; `e2e <file> --test <name>` plays one. Functions of the file
2515
2629
  are shared between its tests, state is not.
2516
- - **Top level of a file — function definitions and `const` literals.**
2517
- Nothing else there runs: `BASE = 'x'` above `test_*` would leave
2518
- `BASE` undefined in the test, so `lint` refuses it
2519
- (`validator:unsupported-statement`). A shared fixed value is a const:
2520
- `const BASE = 'https://x.test';` — a literal only (number, string,
2521
- `true` / `false` / `null`, or an array or object of those), visible in
2522
- every function, as helper functions are. A computed one is a function:
2523
- `function base_url() { return env('BASE'); }`.
2524
- - **Assignments** — `name = expression;`, or `let name = …;` /
2525
- `const name = …;`: see [let, const and lambdas](#let-const-and-lambdas).
2526
- `var` is refused.
2527
- - **`if` / `else`** and **`for` in the canonical shape**
2528
- `for (i = 0; i < N; i = i + 1) { … }` (increment must be an
2529
- assignment — `i++` is rejected everywhere). A loop over cases, each a
2530
- tagged soft step: [Port a @playwright/test spec](https://docs.unotest.com/guides/port-a-spec/).
2531
- - **`break`** — inside a loop body only. Typical polling loop:
2532
-
2533
- ```js
2534
- done = false;
2535
- for (i = 0; i < 60; i = i + 1) {
2536
- job = apiCall('GET', '/jobs/1');
2537
- if (job.body.status == 'DONE') {
2538
- done = true;
2539
- break;
2540
- }
2541
- pause(2000); // reason: ingestion job is async, poll every 2s
2542
- }
2543
- assertTrue(done, 'job never reached DONE');
2544
- ```
2545
-
2546
- - **Array literals** — `[1, 2, 3]`.
2547
- - **Index access on data** — `docs[0]`, `docs[0].objectsCount`,
2548
- `res.body.items[0].id`: see [Strings, objects, indexes](#strings-objects-indexes).
2549
- Indexing a **Locator** is rejected — disambiguate with chain methods
2550
- (`.filter(...)`). `arr[i] = v` replaces an element, `arr.push(v)`
2551
- appends, `arr.sortBy(key)` sorts: see [Logical not and arrays](#logical-not-and-arrays).
2552
- - **Object literals** — as call arguments (`click(loc, {force: true})`)
2553
- and as values in a variable: see [Strings, objects, indexes](#strings-objects-indexes).
2554
- - **Member access** — `row.email` (dot form; `obj['key']` doesn't
2555
- parse).
2556
- - **Method chains** — `getByRole('row').filter({hasText:'X'}).click()`.
2557
- - **Backticks** — multi-line raw strings, no `${}` interpolation.
2558
- - **Booleans, numbers, strings, `null`** — escapes in strings: see
2559
- [Escape rules](#escape-rules).
2560
- - **Comparison operators** — `==` / `!=` (loose: `"1" == 1` is true,
2561
- numeric strings coerce), `===` / `!==` (strict: type AND value must
2562
- match, `1 === "1"` is false), `<` `<=` `>` `>=`, logical `&&` / `||`
2563
- and `!` (see [Logical not and arrays](#logical-not-and-arrays)).
2564
- `&&` and `||` short-circuit as in JS and give a boolean: the right side
2565
- is skipped once the left one decides, so `x != null && x.a == 1` is a
2566
- safe null guard (also inside `waitUntil`).
2567
- Caveat: DOM reads (`textContent`, `getInputValue`, `getAttribute`)
2568
- return **strings** — for comparing against a number use `==`
2569
- (`getAttribute(loc, "data-count") === 5` is always false; write
2570
- `== 5` or compare with a string).
2571
-
2572
- Not supported (and intentionally so): `while` / `do…while` /
2573
- `continue` (bound loops keep every scenario terminating), `++`/`--`,
2574
- functions as values (a lambda goes only into `filter` / `map` / `find` /
2575
- `some`), async/await (everything is sequenced by the AST
2576
- executor), classes, modules, promises, `try/catch` — for cleanup that
2577
- must run whatever happens, see [`teardown`](#teardown--give-the-stand-back).
2578
- Errors thrown from a primitive abort the scenario; if the runtime is
2579
- paused (debugger / MCP step mode), the failure is captured for
2580
- inspection.
2581
-
2582
- The only arrows are the fixed ones of `step(...)`, `teardown(...)` and
2583
- `waitUntil(...)`, and their body may be a block: `waitUntil(() => {
2584
- n = count(rows); return n > 3; })`. A callback (`a.map(x => …)`), a
2585
- ternary, `+=`, `for…of`, `o.a = 2` and the like are refused by `lint`
2586
- with what to write instead.
2587
-
2588
- See `vendor/dsl/EXTENSIONS.md` for the
2589
- exact grammar deltas from the upstream parser.
2590
-
2591
- ### Escape rules
2592
-
2593
- In a quoted string (`'…'` or `"…"`):
2594
-
2595
- | Escape | Gives |
2596
- |---|---|
2597
- | `\n` `\t` `\r` `\f` `\v` | the control character |
2598
- | `\\` | one backslash |
2599
- | `\'` in `'…'`, `\"` in `"…"` | the quote |
2600
- | `\0` (no digit after it) | the NUL character |
2601
- | `\xHH` | the character with that hex code: `"\xA0"` is a non-breaking space |
2602
- | `\uXXXX` | the same with four hex digits: `'\u00A0'` |
2630
+ - **Top level of a file — function declarations and `const` literals.**
2631
+ Nothing else there runs: `let BASE = 'x'` or a call above `test_*`
2632
+ is refused (`validator:unsupported-statement`). A shared fixed value is
2633
+ a const holding a literal — a number, a string, `true` / `false` /
2634
+ `null`, or an array or object of those — visible in every function, as
2635
+ helper functions are (`const BASE = 'https://x.test';`). A computed
2636
+ value or an arrow is a function instead
2637
+ (`validator:top-level-const`): `function base_url() { return
2638
+ env('BASE'); }`.
2639
+ - **A `test_*` body is a list of steps.** Each statement directly in
2640
+ it is a `step(…)` / `step.soft(…)`, a `teardown(…)`, `skip(…)` /
2641
+ `setTestTimeout(…)`, or a declaration that runs nothing — `let id;`,
2642
+ `const LIMIT = 5;`, a literal at most. Anything else there — a call,
2643
+ an `if`, a `return` — is `validator:step-coverage`. Inside a step, and
2644
+ in a helper or a `flow_*`, everything below works.
2645
+
2646
+ ### Variables and scope
2647
+
2648
+ `let` and `const` are block-scoped, `var` and parameters belong to the
2649
+ function, as in JavaScript. A `const` is not assigned again: `lint`
2650
+ refuses it (`validator:const-assign`) and a run fails at that line. The
2651
+ array or object it holds can still change (`ids.push(x)`).
2652
+
2653
+ **A value one step hands to the next** is declared in the `test_*`
2654
+ body, above the steps; a `let` inside a step stays in that step, as in
2655
+ JavaScript:
2656
+
2657
+ ```js
2658
+ function test_order() {
2659
+ let orderId;
2660
+ step('Place the order', () => {
2661
+ orderId = textContent(getByTestId('order-id'));
2662
+ });
2663
+ step('Find it in the list', () => {
2664
+ assertVisible(getByRole('row', {name: orderId}));
2665
+ });
2666
+ }
2667
+ ```
2603
2668
 
2604
- A malformed `\x` / `\u` (`'\u12'`, `'\xG1'`) is a parse error at the
2605
- backslash. Any other backslash pair stays **as written** — `'\d+'` is
2606
- three characters, which is what a regex built from a string needs. The
2607
- same goes for `\b`: a word boundary there, never a backspace. `\01` and
2608
- the other quote (`"\'"`) are kept as written too. Backtick strings are raw: no
2609
- escape decodes inside `` `…` ``.
2669
+ **Assignment without a declaration** works too: it declares the name in
2670
+ the nearest top-level function — the `test_*`, the `flow_*` or the
2671
+ helper. `lint` notes such a name once, as information
2672
+ (`validator:implicit-declaration`), with the declaration to write. A
2673
+ helper's names do not leak into its caller.
2674
+
2675
+ ### Functions and callbacks
2676
+
2677
+ Functions are values: an arrow or a `function` can be kept in a
2678
+ variable, passed to a helper, returned, and it closes over the variables
2679
+ around it. Parameters take defaults and rest (`function f(a, b = 2,
2680
+ ...more)`), nested functions are hoisted in their function.
2681
+
2682
+ ```js
2683
+ const byStatus = (status) => (row) => row.status == status;
2684
+ const open = rows.filter(byStatus('open'));
2685
+ let total = 0;
2686
+ rows.forEach((r) => { total += r.amount; });
2687
+ ```
2688
+
2689
+ A callback writes the outer variable for real, as `total` above shows.
2690
+ Every call inside a callback is a step of its own in the run, as
2691
+ everywhere.
2692
+
2693
+ ### Control flow
2694
+
2695
+ `if` / `else`, `for`, `for…of`, `for…in` (own keys), `while`,
2696
+ `do…while`, `break`, `continue`, `switch`, `return`, `throw`, `try` /
2697
+ `catch` / `finally`, `cond ? a : b` — as in JavaScript. Labels are
2698
+ outside the language.
2699
+
2700
+ One check is stricter than JavaScript: an `if` whose condition `lint`
2701
+ knows to be a number, a string or a locator is `validator:if-shape` —
2702
+ write the comparison, `if (rows.length > 0)`, `if (name != '')`.
2610
2703
 
2611
2704
  ```js
2612
- assertText(getByRole('cell', {name: /^Total/}), '1\u00A0250'); // NBSP between digit groups
2705
+ let job;
2706
+ let tries = 0;
2707
+ do {
2708
+ job = apiCall('GET', '/jobs/1');
2709
+ if (job.body.status != 'DONE') pause(2000); // reason: the job is async
2710
+ tries++;
2711
+ } while (job.body.status != 'DONE' && tries < 30);
2712
+ assertEqual(job.body.status, 'DONE');
2613
2713
  ```
2614
2714
 
2615
- ### Strings, objects, indexes
2715
+ A loop that never ends does not hang the run: the run counts the
2716
+ statements it plays and stops at its budget (`maxSteps budget (100000)
2717
+ exhausted`); the test ends as errored ‼, a fault of the script, not
2718
+ failed.
2719
+
2720
+ **`try` / `catch`.** `catch (e)` takes what was thrown, as thrown:
2721
+ `throw {code: 7}` gives `e.code`. A failed action — a click that found
2722
+ nothing, a failed assertion — arrives as `{name, message}`, with no
2723
+ stack. The parameter may be left out (`catch { … }`). An error caught by
2724
+ the scenario is not a failure: the run goes on, and the debugger does
2725
+ not stop on it. `catch` does not take control flow — a `skip()`, a
2726
+ `return`, `break` / `continue` — nor the step budget. To give the stand back
2727
+ whatever happens, use [`teardown`](#teardown--give-the-stand-back), not
2728
+ `finally`: a teardown also plays when the run is stopped or times out.
2616
2729
 
2617
- Since 0.44.0.
2730
+ **`return`** leaves the function it is in. Inside a step it leaves
2731
+ that step's callback, and the next step runs; in a helper or a callback
2732
+ it returns from them. Directly in a `test_*` body it is
2733
+ `validator:step-coverage`: a test that does not apply here ends with
2734
+ `skip(reason)`.
2735
+
2736
+ ### Values and operators
2618
2737
 
2619
- **Strings** answer these members — the whole list:
2738
+ - **Equality and arithmetic** are JavaScript's: `==` is loose (`"1" ==
2739
+ 1`), `===` strict, `null == undefined`. DOM reads (`textContent`,
2740
+ `getInputValue`, `getAttribute`) return strings — compare them with a
2741
+ number by `==`, or convert with `Number(s)` / `toNumber(s)`.
2742
+ - **`&&`, `||` and `??` give an operand**, as in JavaScript:
2743
+ `env('API_URL') ?? 'http://localhost:3000'`, `name || 'anonymous'`.
2744
+ The right side runs only when the left one does not decide.
2745
+ - **`?.`** reads through a missing value: `res.body?.items?.[0]?.id`,
2746
+ `o.callback?.()`.
2747
+ - **`typeof`, `in`** (own keys), `delete`, `void`, `++` / `--`, the
2748
+ compound assignments up to `**=`, the comma operator — as in
2749
+ JavaScript.
2750
+ - **`+` and `<` apply to numbers and strings only.** On an object or an
2751
+ array they fail the step (`Operator "+" does not apply to an object`)
2752
+ instead of giving `[object Object]`: combine or compare the fields.
2753
+ - **A missing property or argument is `undefined`.** A host function
2754
+ that finds nothing returns `null`; `x == null` is true for both.
2620
2755
 
2621
- | Member | Returns | |
2622
- |---|---|---|
2623
- | `s.length` | `number` | a property: no parentheses |
2624
- | `s.trim()` | `string` | whitespace off both ends |
2625
- | `s.includes(search)` | `boolean` | substring probe, same as `textContains(s, search)` |
2626
- | `s.startsWith(prefix)` | `boolean` | |
2627
- | `s.split(separator)` | array of strings | as in JS: parts keep their spaces, a missing separator gives one part |
2756
+ ### Strings and templates
2628
2757
 
2629
- They work wherever an expression does — in `assertTrue`, in `if`, on a
2630
- literal, on a call result:
2758
+ Quoted strings decode escapes as in JavaScript: `'\n'` is a line break,
2759
+ `'\u00A0'` a non-breaking space, `'\\'` one backslash. A malformed `\x`
2760
+ or `\u` (`'\u12'`) is a parse error. A backslash before any other
2761
+ character is dropped, as JavaScript drops it: `'\d+'` is `d+`. For a
2762
+ regex write a `/…/` literal, or double the backslash (`'\\d+'`).
2763
+
2764
+ Backticks are template strings, with `${…}` interpolation and the same
2765
+ escapes. `` String.raw`…` `` keeps backslashes as written — the only tag
2766
+ the language has.
2631
2767
 
2632
2768
  ```js
2633
- title = getTitle();
2634
- assertTrue(title.trim().length > 0, 'empty title');
2635
- if (out.stdout.includes('ready')) { log('up'); }
2636
- assertTrue(getUrl().startsWith('https://'), getUrl());
2637
- ids = 'a, b'.split(', '); // ['a', 'b']
2769
+ const n = 3;
2770
+ note('rows', `found ${n} rows`);
2771
+ assertText(getByRole('cell', {name: /^Total/}), '1\u00A0250');
2638
2772
  ```
2639
2773
 
2640
- Any other member is a lint error that names it and lists them
2641
- (`validator:unsupported-string-member`); `s.padStart(3)` does not
2642
- reach the browser. A member of the list used on a value that turns out
2643
- not to be a string at run time — a number, or `null` from a missing
2644
- field — fails the step with the value's type in the message.
2774
+ Two lint rules guard templates:
2645
2775
 
2646
- **Object literals** are values: keep one in a variable, read it back by
2647
- field, hand it to a helper.
2776
+ - `validator:evaluate-interpolation` (error) — code handed to the page
2777
+ that the scenario builds from values (`${…}`, `+` of a value, a
2778
+ variable ever given one): the value would become code of the page.
2779
+ Write fixed text or a function, and pass the value as an argument.
2780
+ - `validator:template-escape-changed` (warning) — a backtick string
2781
+ whose backslash escape decodes now (`` `a\nb` `` is a line break):
2782
+ a scenario written for the earlier raw backticks reads differently.
2783
+ Double the backslash or use `` String.raw`…` ``.
2648
2784
 
2649
- ```js
2650
- user = {name: 'Alice', tags: ['admin'], address: {city: 'Riga'}};
2651
- flow_sign_up(user);
2652
- assertTrue(user.address.city == 'Riga');
2653
- ```
2785
+ ### Regex literals
2786
+
2787
+ A `/…/flags` literal is a JavaScript RegExp: every flag and syntax
2788
+ Node accepts — `i`, `g`, `m`, `s`, `u`, `y`, `d`, `v`, named groups,
2789
+ lookbehind. In a matcher slot (`getByText(/Items \d+/i)`) it goes to
2790
+ Playwright as that RegExp; in the scenario it answers `test`, `source` and
2791
+ `flags`, and the string methods `match`, `matchAll`, `replace`,
2792
+ `replaceAll`, `search` and `split` take it.
2654
2793
 
2655
- Where a function wants a specific kind (a string, a locator), an
2656
- object in that slot is still an `arg-kind` error.
2794
+ `match` gives an array of the match and its groups, or `null`; there is
2795
+ no `.groups` — read a named group by its index: `s.match(/(?<id>\d+)/)[1]`.
2657
2796
 
2658
- **Indexes** go anywhere in a chain — no temporary variable:
2797
+ ### Objects, arrays, indexes
2798
+
2799
+ Object literals take shorthand, computed keys, methods and spread
2800
+ (`{...base, id}`); a property is set as in JavaScript (`o.k = v`,
2801
+ `o['k'] = v`, nested too). Destructuring works in declarations,
2802
+ parameters, `for…of` and `catch`:
2659
2803
 
2660
2804
  ```js
2661
- res = apiCall('GET', '/documents');
2662
- assertTrue(res.body.items[0].status == 'ready', json(res.body));
2663
- first = dbQuery('SELECT id FROM users ORDER BY id')[0].id;
2805
+ const {status, body: {items = []}} = apiCall('GET', '/documents');
2806
+ for (const [key, value] of Object.entries(counts)) note(key, value);
2664
2807
  ```
2665
2808
 
2666
- ### Logical not and arrays
2667
-
2668
- Since 0.48.0.
2809
+ A variable holds the array or object itself, not a copy: after
2810
+ `b = a; a.push(1)`, `b` has the new element too. `arr[i] = v` takes an
2811
+ index from `0` to `arr.length` — the length appends, an index further
2812
+ out fails the step instead of leaving holes. The keys `__proto__`,
2813
+ `constructor` and `prototype` cannot be assigned, and a value has no
2814
+ prototype to reach: `o.constructor` and `[].map.call` are `undefined`.
2669
2815
 
2670
- **`!x`** negates, as in JS: the result is always `true` or `false`, and
2671
- `0`, `""`, `null` and `false` are the falsy values — the same ones `if`
2672
- treats as false. An array or an object is truthy, empty or not. `!`
2673
- binds tighter than any other operator: `!a && b` is `(!a) && b`.
2816
+ **Locators are not arrays.** An index on a locator is refused
2817
+ (`validator:locator-index-access`):
2674
2818
 
2675
- ```js
2676
- if (!isVisible(getByRole('dialog'))) { log('dialog closed'); }
2677
- assertTrue(!out.stdout.includes('error'), out.stdout);
2819
+ ```js bad
2820
+ const first = getByRole('row')[0];
2678
2821
  ```
2679
2822
 
2680
- **`arr.push(x, …)`** appends to the array in place and returns its new
2681
- length. Other JS array methods (`pop`, `join`, `reduce`, …) are not
2682
- there; `length`, `sortBy` and the lambda methods `filter` / `map` /
2683
- `find` / `some` ([let, const and lambdas](#let-const-and-lambdas)) are.
2823
+ Pick one with `.nth(i)`, `.first()`, `.filter({…})`:
2684
2824
 
2685
2825
  ```js
2686
- rows = getByRole('row');
2687
- ids = [];
2688
- for (i = 0; i < count(rows); i = i + 1) {
2689
- ids.push(textContent(rows.nth(i)));
2690
- }
2691
- assertTrue(ids.length > 0, json(ids));
2826
+ const first = getByRole('row').first();
2827
+ const third = getByRole('row').nth(2);
2692
2828
  ```
2693
2829
 
2694
- A variable holds the array itself, not a copy, as in JS: after
2695
- `b = a; a.push(1)`, `b` has the new element too. So does a caller whose
2696
- array a helper pushed onto. A helper that assigns a new array to its
2697
- parameter (`list = []`) changes only its own name. `push` on a value
2698
- that is not an array — a string, a number, a `null` field — fails the
2699
- step with that type in the message; on a string the linter flags it
2700
- first.
2830
+ ### The library
2831
+
2832
+ A scenario reads these names — the whole list. A member outside it is a
2833
+ lint error that names it: `validator:library-member` on a namespace
2834
+ (`Math.tau`), `validator:unsupported-string-member` on a string,
2835
+ `validator:unknown-member` on an array, a number, a Map or a Set.
2701
2836
 
2702
- **`arr[i] = v`** replaces element `i`, nested too (`grid[r][c] = v`); on
2703
- an object it sets the key (`o["k"] = v`). The index is an integer from
2704
- `0` to `arr.length`: the length itself appends, anything further out
2705
- fails the step instead of leaving holes. The keys `__proto__`,
2706
- `constructor` and `prototype` cannot be assigned, and an index read on
2707
- an object sees its own keys only. Property assignment (`o.k = v`) stays
2708
- unsupported.
2837
+ | Global | Members |
2838
+ |---|---|
2839
+ | `Math` | `E` `LN10` `LN2` `LOG10E` `LOG2E` `PI` `SQRT1_2` `SQRT2`, `abs` `acos` `acosh` `asin` `asinh` `atan` `atan2` `atanh` `cbrt` `ceil` `clz32` `cos` `cosh` `exp` `expm1` `floor` `fround` `hypot` `imul` `log` `log10` `log1p` `log2` `max` `min` `pow` `round` `sign` `sin` `sinh` `random` `sqrt` `tan` `tanh` `trunc` |
2840
+ | `JSON` | `parse`, `stringify` |
2841
+ | `Number(x)` | `EPSILON` `MAX_SAFE_INTEGER` `MAX_VALUE` `MIN_SAFE_INTEGER` `MIN_VALUE` `NaN` `NEGATIVE_INFINITY` `POSITIVE_INFINITY`, `isFinite` `isInteger` `isNaN` `isSafeInteger` `parseFloat` `parseInt` |
2842
+ | `String(x)` | `raw` |
2843
+ | `Array` | `isArray`, `from`, `of` |
2844
+ | `Object` | `keys`, `values`, `entries`, `fromEntries`, `assign`, `hasOwn` |
2845
+ | `new Map(entries?)`, `new Set(items?)` | the only `new` in the language |
2846
+ | functions | `parseInt`, `parseFloat`, `isNaN`, `isFinite` |
2847
+
2848
+ | Value | Members |
2849
+ |---|---|
2850
+ | string | `length`, `at` `charAt` `includes` `startsWith` `endsWith` `indexOf` `lastIndexOf` `slice` `substring` `split` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `replace` `replaceAll` `toLowerCase` `toUpperCase` `match` `matchAll` `search` `localeCompare` `normalize` |
2851
+ | number | `toFixed`, `toPrecision`, `toString(radix)` |
2852
+ | regex | `source`, `flags`, `test` |
2853
+ | array | `length`, `push` `pop` `shift` `unshift` `slice` `splice` `concat` `join` `reverse` `indexOf` `lastIndexOf` `includes` `at` `flat` `fill` `toReversed` `toSpliced` `with`; with a callback: `forEach` `map` `filter` `flatMap` `some` `every` `find` `findIndex` `findLast` `findLastIndex` `reduce` `reduceRight` `sort` `toSorted`; and `sortBy` |
2854
+ | Map | `size`, `get` `set` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
2855
+ | Set | `size`, `add` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
2856
+
2857
+ The methods behave as in JavaScript; `matchAll` gives an array, and so
2858
+ do `keys()`, `values()` and `entries()` of a Map or a Set
2859
+ (`m.keys().map(…)` works directly). `for…of`, a spread and `Array.from`
2860
+ iterate a Map or a Set as in JavaScript; `note`, `log` and the viewer
2861
+ show one as `Map(1) {"a" => 1}`. A Map keeps its entries apart from its
2862
+ members: `m.length` is a lint error, the count is `m.size`.
2863
+ `Math.random()` draws a new number on every call, so a run that uses it
2864
+ differs from the last one; for fresh test data `randomWord(n)` and
2865
+ `randomEmail()` read better. `undefined`, `NaN` and `Infinity` are
2866
+ values too.
2709
2867
 
2710
2868
  **`arr.sortBy(key?, {desc?})`** sorts the array in place and returns it.
2711
2869
  With a key every element is an object and its field is compared;
2712
2870
  without one (`sortBy()`, or `sortBy(null, {desc: true})`) the elements
2713
2871
  themselves. The compared values are all numbers or all strings —
2714
- anything else fails the step. The sort is stable: equal keys keep their
2715
- order.
2872
+ anything else fails the step. The sort is stable.
2716
2873
 
2717
2874
  ```js
2718
- controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
2875
+ const controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
2719
2876
  controls.sortBy('order'); // a, b
2720
2877
  controls.sortBy('order', {desc: true});
2721
- controls[0] = {id: 'z', order: 0};
2722
2878
  ```
2723
2879
 
2724
- ### let, const and lambdas
2880
+ With a function argument `filter` is the array method; with an options
2881
+ object it is still the locator step:
2882
+ `getByRole('row').filter({hasText: 'x'})`.
2725
2883
 
2726
- **`let x = …;`** and **`const x = …;`** declare a variable. They are the
2727
- bare assignment `x = …;` with a name for intent: the scope is the
2728
- function's, as for any variable here — a block does not make one.
2729
- `for (let i = 0; i < n; i = i + 1)` declares the loop variable. A const
2730
- needs a value and is not assigned again: `lint` refuses it
2731
- (`validator:const-assign`) and a run fails at that line, as JavaScript
2732
- does. The array or object it holds can still change (`ids.push(x)`). `var`
2733
- is refused.
2884
+ ### Outside the language
2734
2885
 
2735
- A **lambda** — `x => expr`, `(x, i) => expr`, or a block with `return` —
2736
- goes into exactly four array methods, as their argument:
2886
+ What JavaScript has and a scenario does not — refused by `lint`
2887
+ (`validator:out-of-language`, error) and by the run, with the
2888
+ replacement:
2737
2889
 
2738
- | Call | Returns |
2890
+ | Not in the language | Write instead |
2739
2891
  |---|---|
2740
- | `a.filter(x => cond)` | a new array of the elements for which `cond` is truthy |
2741
- | `a.map((x, i) => value)` | a new array of the values |
2742
- | `a.find(x => cond)` | the first element for which `cond` is truthy, or `null` |
2743
- | `a.some(x => cond)` | `true` if `cond` is truthy for any element |
2744
-
2745
- ```js
2746
- const rows = fetchData('orders');
2747
- let open = rows.filter(r => r.status == 'open');
2748
- ids = open.map((r, i) => i + ': ' + r.id);
2749
- first = rows.find(r => {
2750
- if (r.total > 100) { return true; }
2751
- return false;
2752
- });
2753
- assertTrue(rows.some(r => r.id == '42'), json(ids));
2754
- ```
2755
-
2756
- The parameters live in a scope of their own, like a helper's: the body
2757
- reads the variables around it, and what it assigns stays inside. The
2758
- body runs element by element, so a call in it — `textContent(…)`,
2759
- `count(…)` — is a step of its own. A lambda is not a value: it cannot be
2760
- assigned, returned or passed anywhere else (`validator:lambda-position`),
2761
- and on a value that is not an array the step fails. With a lambda,
2762
- `filter` is the array method; with an options object it is still the
2763
- locator step `getByRole('row').filter({hasText: 'x'})`.
2892
+ | `import`, `export`, `require(…)` | functions in `_helpers/` are visible by name in every scenario |
2893
+ | `class`, `this`, `super`, `new X(…)` other than `new Map` / `new Set` | an object literal and functions; a regex is a `/…/` literal |
2894
+ | `get` / `set` in an object literal | a plain property or a function |
2895
+ | `function*`, `yield` | an array and a loop |
2896
+ | `for await` | `for…of` — host calls are awaited already |
2897
+ | `Date`, `new Date()` | `clockFreeze` / `clockTick` / `clockRun`; the page's time via `evaluate`; `nowMs()`, `today()` |
2898
+ | `setTimeout`, `setInterval` and the other timers | `pause(ms)` or `waitUntil(() => …)` |
2899
+ | `Promise`, `.then` | nothing: host calls are awaited already |
2900
+ | `eval`, `Function(…)` | page code goes to `evaluate(fn, arg)` |
2901
+ | `process`, `window`, `document`, `globalThis`, `fetch`, `console`, `localStorage`, `navigator`, `location` | an `UPPER_SNAKE` external variable or `env(…)`; the page via `evaluate(…)`; HTTP via `apiCall(…)`; output via `note(…)` / `log(…)` |
2902
+ | `WeakMap`, `WeakSet`, `WeakRef` | a `Map` or a `Set` |
2903
+ | `Symbol`, `Proxy`, `Reflect` | plain objects |
2904
+ | `instanceof` | `Array.isArray(x)` or `typeof x` |
2905
+ | `with` | name the object: `obj.prop` |
2906
+ | labels | a helper function and `return` |
2907
+ | `debugger` | a breakpoint in the viewer, or `pause()` |
2908
+ | BigInt (`1n`) | a number |
2909
+ | `&&=`, `\|\|=`, `??=` | the full form: `x = x ?? value` |
2910
+ | tagged templates | `` String.raw`…` `` is the only tag |
2911
+ | `new.target`, `import.meta` | pass the value as a parameter |
2912
+
2913
+ A name in the table is refused only when the scenario does not declare
2914
+ it: `const window = 1;` is an ordinary variable. `new` is the other way
2915
+ round: it applies to the library's `Map` and `Set` only, never to a
2916
+ name the scenario declares.
2917
+
2918
+ A method call on a name nothing declares — `clock.freeze(…)`,
2919
+ `page.waitForTimeout(…)` as another framework spells it — is an
2920
+ unknown function (`validator:unknown-function`), with the name to use
2921
+ here when there is one: `use clockFreeze("2026-01-15T10:00:00Z")`.
2764
2922
 
2765
2923
  ### `teardown` — give the stand back
2766
2924
 
@@ -2774,7 +2932,7 @@ function test_ticket_closed_in_second_client() {
2774
2932
  });
2775
2933
  apiCall('POST', '/stand/flags', {closeTickets: true});
2776
2934
  });
2777
- step("…", () => { … });
2935
+ step("…", () => { /* … */ });
2778
2936
  }
2779
2937
  ```
2780
2938
 
@@ -2851,7 +3009,7 @@ function test_theme_rebuild() {
2851
3009
  ```
2852
3010
 
2853
3011
  Running out is a failure, not a stop: the test is red — counted as
2854
- errored (`‼`), like any run budget — with
3012
+ failed (`✗`), like any run budget — with
2855
3013
  `setTestTimeout(90000) budget exhausted` (or `testTimeoutMs budget
2856
3014
  (30000ms) exhausted`), the action it cut is abandoned, and the teardown
2857
3015
  blocks play. Stop in the viewer aborts the run instead — same teardown,
@@ -2859,7 +3017,7 @@ but the run reads as stopped, not failed. Call it in the `test_*` body:
2859
3017
  in a helper or a `flow_*` it is reported by
2860
3018
  `lint:set-test-timeout-outside-test`.
2861
3019
 
2862
- Rules (lint, `teardown-shape`): the label is a string literal; no
3020
+ Rules (lint, `teardown-shape`): the label is text written out; no
2863
3021
  `return` inside, no `break` out of it (a `break` in a loop inside is
2864
3022
  fine); no `teardown` inside a `teardown`. Allowed in tests, flows and
2865
3023
  helpers. A function, parameter or variable of your own named
@@ -2883,7 +3041,7 @@ helpers. A function, parameter or variable of your own named
2883
3041
 
2884
3042
  // The badge must stay hidden.
2885
3043
  // @expect-fail <- test_badge_hidden only
2886
- function test_badge_hidden() { … }
3044
+ function test_badge_hidden() { /* … */ }
2887
3045
  ```
2888
3046
 
2889
3047
  The `//` lines directly above a `function test_*` — no blank line
@@ -2921,8 +3079,7 @@ helpers. A function, parameter or variable of your own named
2921
3079
  }
2922
3080
  ```
2923
3081
 
2924
- `return` is legal in either kind, and NOT in a `test_*` entry — there it
2925
- would mean the scenario silently ended halfway. A `flow_*` that returns a
3082
+ `return` is legal in either kind. A `flow_*` that returns a
2926
3083
  value gets `lint:flow-returns-value` (warning): fine when the flow acts
2927
3084
  and yields its result (`email = flow_signup()`), a rename hint when it
2928
3085
  only reads.