@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.
- package/.claude/skills/write-e2e-test/SKILL.md +6 -7
- package/.claude/skills/write-e2e-test-ground/SKILL.md +6 -7
- package/CHANGELOG.md +294 -3
- package/README.md +5 -4
- package/bin/unotest-web.js +10 -9
- 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 +43 -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/inspection/page-inject.js +15 -9
- package/dist/{interfaces-D5ePwBX6.d.ts → interfaces--zgFOUB6.d.ts} +17 -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/agent-integration.md +15 -1
- package/guides/dsl-reference.md +416 -259
- package/package.json +8 -8
- package/types/unotest-dsl.d.ts +115 -84
- 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
|
});
|
|
@@ -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
|
|
117
|
-
|
|
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
|
|
121
|
-
below.
|
|
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` —
|
|
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 (`
|
|
295
|
-
|
|
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
|
|
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.
|
|
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 `
|
|
1754
|
-
of failing the step
|
|
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
|
|
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
|
|
1885
|
-
|
|
1886
|
-
|
|
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(
|
|
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(
|
|
2392
|
+
doubled = evaluate((n) => n * 2, 21); // one → the value
|
|
2319
2393
|
result = evaluate(
|
|
2320
|
-
|
|
2394
|
+
([a, b]) => window.myApp.compute(a, b),
|
|
2321
2395
|
10, 20 // two → one array
|
|
2322
2396
|
);
|
|
2323
2397
|
```
|
|
2324
2398
|
|
|
2325
|
-
|
|
2326
|
-
(
|
|
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'),
|
|
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.
|
|
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
|
-
##
|
|
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
|
-
|
|
2509
|
-
(`
|
|
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
|
-
|
|
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
|
|
2517
|
-
Nothing else there runs: `BASE = 'x'` above `test_*`
|
|
2518
|
-
`
|
|
2519
|
-
|
|
2520
|
-
`
|
|
2521
|
-
|
|
2522
|
-
|
|
2523
|
-
`function base_url() { return
|
|
2524
|
-
|
|
2525
|
-
|
|
2526
|
-
`
|
|
2527
|
-
|
|
2528
|
-
`
|
|
2529
|
-
|
|
2530
|
-
|
|
2531
|
-
|
|
2532
|
-
|
|
2533
|
-
|
|
2534
|
-
|
|
2535
|
-
|
|
2536
|
-
|
|
2537
|
-
|
|
2538
|
-
|
|
2539
|
-
|
|
2540
|
-
|
|
2541
|
-
|
|
2542
|
-
|
|
2543
|
-
|
|
2544
|
-
|
|
2545
|
-
|
|
2546
|
-
|
|
2547
|
-
|
|
2548
|
-
|
|
2549
|
-
|
|
2550
|
-
|
|
2551
|
-
|
|
2552
|
-
|
|
2553
|
-
|
|
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
|
-
|
|
2605
|
-
|
|
2606
|
-
|
|
2607
|
-
|
|
2608
|
-
|
|
2609
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
2630
|
-
|
|
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
|
-
|
|
2634
|
-
|
|
2635
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2647
|
-
|
|
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
|
-
|
|
2650
|
-
|
|
2651
|
-
|
|
2652
|
-
|
|
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
|
-
|
|
2656
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2662
|
-
|
|
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
|
-
|
|
2667
|
-
|
|
2668
|
-
|
|
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
|
-
|
|
2671
|
-
`
|
|
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
|
-
|
|
2677
|
-
assertTrue(!out.stdout.includes('error'), out.stdout);
|
|
2819
|
+
```js bad
|
|
2820
|
+
const first = getByRole('row')[0];
|
|
2678
2821
|
```
|
|
2679
2822
|
|
|
2680
|
-
|
|
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
|
-
|
|
2687
|
-
|
|
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
|
-
|
|
2695
|
-
|
|
2696
|
-
|
|
2697
|
-
|
|
2698
|
-
|
|
2699
|
-
|
|
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
|
-
|
|
2703
|
-
|
|
2704
|
-
`
|
|
2705
|
-
|
|
2706
|
-
`
|
|
2707
|
-
|
|
2708
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
2736
|
-
|
|
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
|
-
|
|
|
2890
|
+
| Not in the language | Write instead |
|
|
2739
2891
|
|---|---|
|
|
2740
|
-
| `
|
|
2741
|
-
| `
|
|
2742
|
-
| `
|
|
2743
|
-
| `
|
|
2744
|
-
|
|
2745
|
-
|
|
2746
|
-
|
|
2747
|
-
|
|
2748
|
-
|
|
2749
|
-
|
|
2750
|
-
|
|
2751
|
-
|
|
2752
|
-
|
|
2753
|
-
|
|
2754
|
-
|
|
2755
|
-
|
|
2756
|
-
|
|
2757
|
-
|
|
2758
|
-
|
|
2759
|
-
`
|
|
2760
|
-
|
|
2761
|
-
|
|
2762
|
-
`
|
|
2763
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|