@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.
- package/.claude/skills/write-e2e-test/SKILL.md +6 -7
- package/.claude/skills/write-e2e-test-ground/SKILL.md +6 -7
- package/CHANGELOG.md +242 -3
- package/dist/config/schema.d.ts +11 -11
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +4 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +41 -28
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/web-dsl-language-service.d.ts +18 -6
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +1 -1
- package/dist/{interfaces-mlRtu8mL.d.ts → interfaces--zgFOUB6.d.ts} +7 -0
- package/dist/{linter-RrjB1n9R.d.ts → linter-Ci17V2Sr.d.ts} +13 -5
- package/dist/mcp/server.js +1 -1
- package/dist/runner/cli.d.ts +1 -1
- package/dist/runner/cli.js +1 -1
- package/dist/runner/init/chrome-probe.js +1 -1
- package/dist/runner/init.js +1 -1
- package/dist/runner/install-chromium.js +1 -1
- package/dist/runner/prepare-fix.js +1 -1
- package/dist/runner/scaffold-workspace.js +1 -1
- package/dist/runner/serve-fixture.js +1 -1
- package/dist/runner/web-runner-adapter.js +1 -1
- package/guides/dsl-reference.md +337 -260
- package/package.json +8 -8
- package/types/unotest-dsl.d.ts +88 -71
- package/types/unotest-lib.d.ts +1289 -0
package/guides/dsl-reference.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
status: stable
|
|
3
|
-
last_updated: 2026-
|
|
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
|
|
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`
|
|
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 =
|
|
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
|
|
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` —
|
|
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 (`
|
|
241
|
-
|
|
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 (`
|
|
311
|
-
|
|
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.
|
|
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
|
|
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
|
|
1945
|
-
|
|
1946
|
-
|
|
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(
|
|
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(
|
|
2392
|
+
doubled = evaluate((n) => n * 2, 21); // one → the value
|
|
2379
2393
|
result = evaluate(
|
|
2380
|
-
|
|
2394
|
+
([a, b]) => window.myApp.compute(a, b),
|
|
2381
2395
|
10, 20 // two → one array
|
|
2382
2396
|
);
|
|
2383
2397
|
```
|
|
2384
2398
|
|
|
2385
|
-
|
|
2386
|
-
(
|
|
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'),
|
|
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
|
-
##
|
|
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
|
-
|
|
2580
|
-
(`vendor/dsl/`), not V8. What's supported in scenario files:
|
|
2623
|
+
### A file: tests, helpers, constants
|
|
2581
2624
|
|
|
2582
|
-
- **`function test_*()
|
|
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
|
|
2588
|
-
Nothing else there runs: `BASE = 'x'` above `test_*`
|
|
2589
|
-
`
|
|
2590
|
-
|
|
2591
|
-
`
|
|
2592
|
-
|
|
2593
|
-
|
|
2594
|
-
`function base_url() { return
|
|
2595
|
-
|
|
2596
|
-
|
|
2597
|
-
`
|
|
2598
|
-
|
|
2599
|
-
`
|
|
2600
|
-
|
|
2601
|
-
|
|
2602
|
-
|
|
2603
|
-
|
|
2604
|
-
|
|
2605
|
-
|
|
2606
|
-
|
|
2607
|
-
|
|
2608
|
-
|
|
2609
|
-
|
|
2610
|
-
|
|
2611
|
-
|
|
2612
|
-
|
|
2613
|
-
|
|
2614
|
-
|
|
2615
|
-
|
|
2616
|
-
|
|
2617
|
-
|
|
2618
|
-
|
|
2619
|
-
|
|
2620
|
-
|
|
2621
|
-
|
|
2622
|
-
|
|
2623
|
-
|
|
2624
|
-
|
|
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
|
-
|
|
2685
|
-
|
|
2686
|
-
|
|
2687
|
-
|
|
2688
|
-
|
|
2689
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2756
|
+
### Strings and templates
|
|
2700
2757
|
|
|
2701
|
-
|
|
2702
|
-
|
|
2703
|
-
|
|
2704
|
-
|
|
2705
|
-
|
|
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
|
-
|
|
2710
|
-
|
|
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
|
-
|
|
2714
|
-
|
|
2715
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2727
|
-
|
|
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
|
-
|
|
2730
|
-
|
|
2731
|
-
|
|
2732
|
-
|
|
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
|
-
|
|
2736
|
-
object in that slot is still an `arg-kind` error.
|
|
2797
|
+
### Objects, arrays, indexes
|
|
2737
2798
|
|
|
2738
|
-
|
|
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
|
-
|
|
2742
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2816
|
+
**Locators are not arrays.** An index on a locator is refused
|
|
2817
|
+
(`validator:locator-index-access`):
|
|
2749
2818
|
|
|
2750
|
-
|
|
2751
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2767
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2783
|
-
|
|
2784
|
-
`
|
|
2785
|
-
|
|
2786
|
-
|
|
2787
|
-
|
|
2788
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2816
|
-
|
|
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
|
-
|
|
|
2890
|
+
| Not in the language | Write instead |
|
|
2819
2891
|
|---|---|
|
|
2820
|
-
| `
|
|
2821
|
-
| `
|
|
2822
|
-
| `
|
|
2823
|
-
| `
|
|
2824
|
-
|
|
2825
|
-
|
|
2826
|
-
|
|
2827
|
-
|
|
2828
|
-
|
|
2829
|
-
|
|
2830
|
-
|
|
2831
|
-
|
|
2832
|
-
|
|
2833
|
-
|
|
2834
|
-
|
|
2835
|
-
|
|
2836
|
-
|
|
2837
|
-
|
|
2838
|
-
|
|
2839
|
-
`
|
|
2840
|
-
|
|
2841
|
-
|
|
2842
|
-
`
|
|
2843
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|