@unotest/web 0.49.2 → 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
  });
@@ -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
@@ -181,23 +195,15 @@ hasNotText})`) accept either:
181
195
 
182
196
  - A string literal — matched as substring by default, exactly with
183
197
  `{exact: true}`.
184
- - 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).
185
200
 
186
201
  ```js
187
202
  getByRole("link", {name: /^Sets/})
188
203
  getByText(/Items \d+/i)
189
- filter({hasText: /done/i})
204
+ getByRole('row').filter({hasText: /done/i})
190
205
  ```
191
206
 
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
207
  ## The `timeout` option
202
208
 
203
209
  Actions, navigation, waits and assertions take their time limit in
@@ -237,8 +243,8 @@ The other options narrow by ARIA state, as Playwright's `getByRole` does:
237
243
  `checked`, `disabled`, `expanded`, `pressed`, `selected` (true / false),
238
244
  `level` (a heading level from 1) and `includeHidden` (true — match
239
245
  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.
246
+ refused, at lint time (`validator:options`) and at run time — it would
247
+ otherwise match without it.
242
248
 
243
249
  ```js
244
250
  getByRole('button', {name: 'Save'})
@@ -307,8 +313,8 @@ Each requires a locator as the receiver / first argument.
307
313
  ### `filter(options)`
308
314
 
309
315
  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
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
312
318
  `locator(...)` instead.
313
319
 
314
320
  ```js
@@ -1142,7 +1148,7 @@ there rather than half-applied.
1142
1148
 
1143
1149
  `timezone` and `locale` in `unotest.config.mjs` set them for every page:
1144
1150
 
1145
- ```js
1151
+ ```js config
1146
1152
  export default {
1147
1153
  timezone: 'Europe/Madrid', // Date#toString, Intl, getTimezoneOffset
1148
1154
  locale: 'es-ES', // navigator.language, Intl defaults, Accept-Language
@@ -1400,7 +1406,7 @@ Where the window's size and scale come from, first match wins:
1400
1406
  first scenario starts, as in the config.
1401
1407
  3. **The config.** `unotest.config.mjs`:
1402
1408
 
1403
- ```js
1409
+ ```js config
1404
1410
  export default {
1405
1411
  viewport: { width: 390, height: 844, deviceScaleFactor: 2 },
1406
1412
  };
@@ -1416,7 +1422,7 @@ Where the window's size and scale come from, first match wins:
1416
1422
  has no window manager — the size comes from `--window-size` in
1417
1423
  `launch.args`:
1418
1424
 
1419
- ```js
1425
+ ```js config
1420
1426
  export default {
1421
1427
  viewport: null,
1422
1428
  launch: { args: ["--window-size=1440,900"] },
@@ -1477,7 +1483,8 @@ goto('chrome-extension://' + id + '/popup.html');
1477
1483
  `chrome-extension://<id>/sw.js`. A running worker comes back at once;
1478
1484
  otherwise it waits up to `timeoutMs` (default: the navigation timeout).
1479
1485
  `url` — a substring or `/regex/` when several extensions run.
1480
- - `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
1481
1488
  extras reach the body by the same rule as `evaluate`: none →
1482
1489
  `undefined`, one → the value itself, two or more → one array. JSON
1483
1490
  return; a returned Promise is awaited. Not discouraged by the
@@ -1555,7 +1562,7 @@ Project-agnostic core (D-13, D-27). Consumers wire connection / base-URL
1555
1562
  config in `unotest/unotest.config.{js,mjs,ts}` under `sandbox.{shellCwd, database,
1556
1563
  apiBaseUrl}` — the scenario **cannot** override.
1557
1564
 
1558
- ```js
1565
+ ```js config
1559
1566
  // unotest/unotest.config.mjs
1560
1567
  export default {
1561
1568
  sandbox: {
@@ -1679,7 +1686,7 @@ yet is judged by the nearest directory above it that does.
1679
1686
  A background process that writes outside the project (a listener's log
1680
1687
  in `/tmp`) needs its directory in the config:
1681
1688
 
1682
- ```js
1689
+ ```js config
1683
1690
  // unotest/unotest.config.mjs
1684
1691
  export default {
1685
1692
  sandbox: { readRoots: ['/tmp/my-listener'] },
@@ -1804,11 +1811,11 @@ An environment value the test can do without. It reads what a bare
1804
1811
  `unotest/.env` — but returns `fallback` for a name that is not set
1805
1812
  instead of failing the step, and `null` when no fallback is given.
1806
1813
 
1807
- The fallback is the one-line default — the DSL has no `??`, and `||`
1808
- answers `true` / `false`, not a value:
1814
+ The fallback is the one-line default; `??` says the same:
1809
1815
 
1810
1816
  ```js
1811
1817
  api = env('API_URL', 'http://localhost:3000');
1818
+ api = env('API_URL') ?? 'http://localhost:3000';
1812
1819
  ```
1813
1820
 
1814
1821
  Without a fallback, use the `null` to decide:
@@ -1941,9 +1948,11 @@ res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
1941
1948
  {base: 'API_BASE_CHAT'});
1942
1949
  ```
1943
1950
 
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.
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.
1947
1956
 
1948
1957
  **With an environment overlay active, the base must come from it.**
1949
1958
  Running `--env dev` while `API_BASE_CHAT` is set only in the base
@@ -1953,7 +1962,7 @@ base host while everything else in the run resolves against `dev`. Set
1953
1962
  the name in `unotest/.env.dev`, or, when the base value really is meant
1954
1963
  for every environment, list the name in the config:
1955
1964
 
1956
- ```js
1965
+ ```js config
1957
1966
  // unotest/unotest.config.mjs
1958
1967
  export default { env: { shared: ['API_BASE_CHAT'] } };
1959
1968
  ```
@@ -2365,8 +2374,13 @@ dates.
2365
2374
  context. Discouraged (`lint:evaluate-discouraged`) — prefer typed
2366
2375
  getters or the action API.
2367
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
+
2368
2381
  ```js
2369
- height = evaluate(`document.documentElement.scrollHeight`);
2382
+ height = evaluate(() => document.documentElement.scrollHeight);
2383
+ height = evaluate(`document.documentElement.scrollHeight`); // the string form
2370
2384
  ```
2371
2385
 
2372
2386
  The extra arguments reach the body by one rule: none → `undefined`,
@@ -2375,15 +2389,24 @@ destructures. So one argument is `function(x)`, not `function([x])` —
2375
2389
  that one fails with `2 is not iterable`.
2376
2390
 
2377
2391
  ```js
2378
- doubled = evaluate(`function(n) { return n * 2; }`, 21); // one → the value
2392
+ doubled = evaluate((n) => n * 2, 21); // one → the value
2379
2393
  result = evaluate(
2380
- `function([a, b]) { return window.myApp.compute(a, b); }`,
2394
+ ([a, b]) => window.myApp.compute(a, b),
2381
2395
  10, 20 // two → one array
2382
2396
  );
2383
2397
  ```
2384
2398
 
2385
- Backticks are **raw** — `${…}` interpolation is rejected at parse time
2386
- (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.
2387
2410
 
2388
2411
  A page whose main thread is busy — a script loop, a long task — cannot
2389
2412
  start the script. `evaluate` then fails the step after the action timeout
@@ -2397,7 +2420,7 @@ The body gets the element first, then the extras by the same rule as
2397
2420
  array.
2398
2421
 
2399
2422
  ```js
2400
- 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);
2401
2424
  ```
2402
2425
 
2403
2426
  Reach for it only for what no typed call reads — a style is
@@ -2574,273 +2597,328 @@ step.soft("Question", {tag: q.id}, () => {
2574
2597
 
2575
2598
  ---
2576
2599
 
2577
- ## 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:
2613
+
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.
2578
2622
 
2579
- The DSL is JavaScript-shaped but parsed by a small AST engine
2580
- (`vendor/dsl/`), not V8. What's supported in scenario files:
2623
+ ### A file: tests, helpers, constants
2581
2624
 
2582
- - **`function test_*(): { … }`** — a test. A file may hold several; each
2625
+ - **`function test_*() { … }`** — a test. A file may hold several; each
2583
2626
  is its own run with its own browser context, retry and verdict, and the
2584
2627
  viewer shows it as its own row under the file. `e2e <file>` plays them
2585
2628
  in order; `e2e <file> --test <name>` plays one. Functions of the file
2586
2629
  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:
2603
-
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
- ```
2616
-
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'` |
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
+ ```
2683
2668
 
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 `` `…` ``.
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 != '')`.
2690
2703
 
2691
2704
  ```js
2692
- 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');
2693
2713
  ```
2694
2714
 
2695
- ### 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.
2696
2729
 
2697
- 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
2737
+
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.
2698
2755
 
2699
- **Strings** answer these members — the whole list:
2756
+ ### Strings and templates
2700
2757
 
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 |
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+'`).
2708
2763
 
2709
- They work wherever an expression does — in `assertTrue`, in `if`, on a
2710
- literal, on a call result:
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.
2711
2767
 
2712
2768
  ```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']
2769
+ const n = 3;
2770
+ note('rows', `found ${n} rows`);
2771
+ assertText(getByRole('cell', {name: /^Total/}), '1\u00A0250');
2718
2772
  ```
2719
2773
 
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.
2774
+ Two lint rules guard templates:
2725
2775
 
2726
- **Object literals** are values: keep one in a variable, read it back by
2727
- 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`…` ``.
2728
2784
 
2729
- ```js
2730
- user = {name: 'Alice', tags: ['admin'], address: {city: 'Riga'}};
2731
- flow_sign_up(user);
2732
- assertTrue(user.address.city == 'Riga');
2733
- ```
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.
2793
+
2794
+ `match` gives an array of the match and its groups, or `null`; there is
2795
+ no `.groups` — read a named group by its index: `s.match(/(?<id>\d+)/)[1]`.
2734
2796
 
2735
- Where a function wants a specific kind (a string, a locator), an
2736
- object in that slot is still an `arg-kind` error.
2797
+ ### Objects, arrays, indexes
2737
2798
 
2738
- **Indexes** go anywhere in a chain — no temporary variable:
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`:
2739
2803
 
2740
2804
  ```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;
2805
+ const {status, body: {items = []}} = apiCall('GET', '/documents');
2806
+ for (const [key, value] of Object.entries(counts)) note(key, value);
2744
2807
  ```
2745
2808
 
2746
- ### Logical not and arrays
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`.
2747
2815
 
2748
- Since 0.48.0.
2816
+ **Locators are not arrays.** An index on a locator is refused
2817
+ (`validator:locator-index-access`):
2749
2818
 
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);
2819
+ ```js bad
2820
+ const first = getByRole('row')[0];
2758
2821
  ```
2759
2822
 
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.
2823
+ Pick one with `.nth(i)`, `.first()`, `.filter({…})`:
2764
2824
 
2765
2825
  ```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));
2826
+ const first = getByRole('row').first();
2827
+ const third = getByRole('row').nth(2);
2772
2828
  ```
2773
2829
 
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.
2830
+ ### The library
2781
2831
 
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.
2832
+ A scenario reads these names — the whole list. A member outside it is a
2833
+ lint error that names it: `validator:library-member` on a namespace
2834
+ (`Math.tau`), `validator:unsupported-string-member` on a string,
2835
+ `validator:unknown-member` on an array, a number, a Map or a Set.
2836
+
2837
+ | Global | Members |
2838
+ |---|---|
2839
+ | `Math` | `E` `LN10` `LN2` `LOG10E` `LOG2E` `PI` `SQRT1_2` `SQRT2`, `abs` `acos` `acosh` `asin` `asinh` `atan` `atan2` `atanh` `cbrt` `ceil` `clz32` `cos` `cosh` `exp` `expm1` `floor` `fround` `hypot` `imul` `log` `log10` `log1p` `log2` `max` `min` `pow` `round` `sign` `sin` `sinh` `random` `sqrt` `tan` `tanh` `trunc` |
2840
+ | `JSON` | `parse`, `stringify` |
2841
+ | `Number(x)` | `EPSILON` `MAX_SAFE_INTEGER` `MAX_VALUE` `MIN_SAFE_INTEGER` `MIN_VALUE` `NaN` `NEGATIVE_INFINITY` `POSITIVE_INFINITY`, `isFinite` `isInteger` `isNaN` `isSafeInteger` `parseFloat` `parseInt` |
2842
+ | `String(x)` | `raw` |
2843
+ | `Array` | `isArray`, `from`, `of` |
2844
+ | `Object` | `keys`, `values`, `entries`, `fromEntries`, `assign`, `hasOwn` |
2845
+ | `new Map(entries?)`, `new Set(items?)` | the only `new` in the language |
2846
+ | functions | `parseInt`, `parseFloat`, `isNaN`, `isFinite` |
2847
+
2848
+ | Value | Members |
2849
+ |---|---|
2850
+ | string | `length`, `at` `charAt` `includes` `startsWith` `endsWith` `indexOf` `lastIndexOf` `slice` `substring` `split` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `replace` `replaceAll` `toLowerCase` `toUpperCase` `match` `matchAll` `search` `localeCompare` `normalize` |
2851
+ | number | `toFixed`, `toPrecision`, `toString(radix)` |
2852
+ | regex | `source`, `flags`, `test` |
2853
+ | array | `length`, `push` `pop` `shift` `unshift` `slice` `splice` `concat` `join` `reverse` `indexOf` `lastIndexOf` `includes` `at` `flat` `fill` `toReversed` `toSpliced` `with`; with a callback: `forEach` `map` `filter` `flatMap` `some` `every` `find` `findIndex` `findLast` `findLastIndex` `reduce` `reduceRight` `sort` `toSorted`; and `sortBy` |
2854
+ | Map | `size`, `get` `set` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
2855
+ | Set | `size`, `add` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
2856
+
2857
+ The methods behave as in JavaScript; `matchAll` gives an array, and so
2858
+ do `keys()`, `values()` and `entries()` of a Map or a Set
2859
+ (`m.keys().map(…)` works directly). `for…of`, a spread and `Array.from`
2860
+ iterate a Map or a Set as in JavaScript; `note`, `log` and the viewer
2861
+ show one as `Map(1) {"a" => 1}`. A Map keeps its entries apart from its
2862
+ members: `m.length` is a lint error, the count is `m.size`.
2863
+ `Math.random()` draws a new number on every call, so a run that uses it
2864
+ differs from the last one; for fresh test data `randomWord(n)` and
2865
+ `randomEmail()` read better. `undefined`, `NaN` and `Infinity` are
2866
+ values too.
2789
2867
 
2790
2868
  **`arr.sortBy(key?, {desc?})`** sorts the array in place and returns it.
2791
2869
  With a key every element is an object and its field is compared;
2792
2870
  without one (`sortBy()`, or `sortBy(null, {desc: true})`) the elements
2793
2871
  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.
2872
+ anything else fails the step. The sort is stable.
2796
2873
 
2797
2874
  ```js
2798
- controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
2875
+ const controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
2799
2876
  controls.sortBy('order'); // a, b
2800
2877
  controls.sortBy('order', {desc: true});
2801
- controls[0] = {id: 'z', order: 0};
2802
2878
  ```
2803
2879
 
2804
- ### 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'})`.
2805
2883
 
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.
2884
+ ### Outside the language
2814
2885
 
2815
- A **lambda** — `x => expr`, `(x, i) => expr`, or a block with `return` —
2816
- 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:
2817
2889
 
2818
- | Call | Returns |
2890
+ | Not in the language | Write instead |
2819
2891
  |---|---|
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'})`.
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")`.
2844
2922
 
2845
2923
  ### `teardown` — give the stand back
2846
2924
 
@@ -2854,7 +2932,7 @@ function test_ticket_closed_in_second_client() {
2854
2932
  });
2855
2933
  apiCall('POST', '/stand/flags', {closeTickets: true});
2856
2934
  });
2857
- step("…", () => { … });
2935
+ step("…", () => { /* … */ });
2858
2936
  }
2859
2937
  ```
2860
2938
 
@@ -2931,7 +3009,7 @@ function test_theme_rebuild() {
2931
3009
  ```
2932
3010
 
2933
3011
  Running out is a failure, not a stop: the test is red — counted as
2934
- errored (`‼`), like any run budget — with
3012
+ failed (`✗`), like any run budget — with
2935
3013
  `setTestTimeout(90000) budget exhausted` (or `testTimeoutMs budget
2936
3014
  (30000ms) exhausted`), the action it cut is abandoned, and the teardown
2937
3015
  blocks play. Stop in the viewer aborts the run instead — same teardown,
@@ -2939,7 +3017,7 @@ but the run reads as stopped, not failed. Call it in the `test_*` body:
2939
3017
  in a helper or a `flow_*` it is reported by
2940
3018
  `lint:set-test-timeout-outside-test`.
2941
3019
 
2942
- Rules (lint, `teardown-shape`): the label is a string literal; no
3020
+ Rules (lint, `teardown-shape`): the label is text written out; no
2943
3021
  `return` inside, no `break` out of it (a `break` in a loop inside is
2944
3022
  fine); no `teardown` inside a `teardown`. Allowed in tests, flows and
2945
3023
  helpers. A function, parameter or variable of your own named
@@ -2963,7 +3041,7 @@ helpers. A function, parameter or variable of your own named
2963
3041
 
2964
3042
  // The badge must stay hidden.
2965
3043
  // @expect-fail <- test_badge_hidden only
2966
- function test_badge_hidden() { … }
3044
+ function test_badge_hidden() { /* … */ }
2967
3045
  ```
2968
3046
 
2969
3047
  The `//` lines directly above a `function test_*` — no blank line
@@ -3001,8 +3079,7 @@ helpers. A function, parameter or variable of your own named
3001
3079
  }
3002
3080
  ```
3003
3081
 
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
3082
+ `return` is legal in either kind. A `flow_*` that returns a
3006
3083
  value gets `lint:flow-returns-value` (warning): fine when the flow acts
3007
3084
  and yields its result (`email = flow_signup()`), a rename hint when it
3008
3085
  only reads.