@unotest/web 0.50.0 → 0.52.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/CHANGELOG.md +189 -3
- package/README.md +25 -0
- package/bin/unotest-web.js +2 -1
- package/dist/config/schema.d.ts +45 -18
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.d.ts +11 -2
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +389 -44
- package/dist/dsl/index.js +1 -1
- package/dist/dsl/v8/scenario-worker.d.ts +2 -0
- package/dist/dsl/v8/scenario-worker.js +1 -0
- package/dist/dsl/web-dsl-language-service.d.ts +6 -1
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/inspection/page-inject.d.ts +34 -7
- package/dist/inspection/page-inject.js +69 -4
- package/dist/{interfaces--zgFOUB6.d.ts → interfaces-BSGmF_Tv.d.ts} +92 -3
- package/dist/{linter-Ci17V2Sr.d.ts → linter-CYRlmOLy.d.ts} +19 -0
- 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 +25 -2
- package/guides/dsl-reference.md +958 -228
- package/llms.txt +223 -0
- package/package.json +17 -8
- package/types/unotest-dsl.d.ts +328 -101
- package/types/unotest-lib.d.ts +93 -27
package/guides/dsl-reference.md
CHANGED
|
@@ -92,12 +92,12 @@ The data-driven gate, in full (`readJsonLine` reads the cases; the outer
|
|
|
92
92
|
```js
|
|
93
93
|
function test_control_questions() {
|
|
94
94
|
step("Control questions", () => {
|
|
95
|
-
for (i = 1; i < 11; i = i + 1) {
|
|
96
|
-
q = readJsonLine('questions.jsonl', {slot: i});
|
|
95
|
+
for (let i = 1; i < 11; i = i + 1) {
|
|
96
|
+
const q = readJsonLine('questions.jsonl', {slot: i});
|
|
97
97
|
step.soft("Question", {tag: q.id}, () => {
|
|
98
98
|
fill(getByRole('textbox', {name: 'Message'}), q.text);
|
|
99
99
|
press(getByRole('textbox', {name: 'Message'}), 'Enter');
|
|
100
|
-
answer = getByTestId('last-answer');
|
|
100
|
+
const answer = getByTestId('last-answer');
|
|
101
101
|
screenshot(q.id);
|
|
102
102
|
assertJudge(answer, q.rubric);
|
|
103
103
|
});
|
|
@@ -136,7 +136,7 @@ it consists of:
|
|
|
136
136
|
library (`Math`, `JSON`, `Object`, `Map`, `Set`, the string, number and
|
|
137
137
|
array methods), cut from TypeScript's own declarations to exactly what
|
|
138
138
|
a scenario has. `keys()`, `values()` and `entries()` of a Map or a Set
|
|
139
|
-
read as
|
|
139
|
+
read as iterators, as they run: spread one for array methods.
|
|
140
140
|
- `node_modules/@unotest/web/types/unotest-dsl.d.ts` — ambient
|
|
141
141
|
declarations for every DSL function, generated from the same contracts
|
|
142
142
|
the validator uses and shipped with the package, so it always matches
|
|
@@ -178,11 +178,14 @@ Two squiggle sources remain that typings cannot fix, both cosmetic:
|
|
|
178
178
|
- [Storage](#storage) — localStorage / cookies
|
|
179
179
|
- [Edge actions](#edge-actions) — drag, upload, paste
|
|
180
180
|
- [Sandbox primitives](#sandbox-primitives) — shell / db / HTTP / files
|
|
181
|
+
- [MCP client](#mcp-client) — start an MCP server, call it, wait for it
|
|
181
182
|
- [Network mocks](#network-mocks) — what the page's requests get
|
|
183
|
+
- [Terminal (macOS)](#terminal-macos) — a real Terminal.app / iTerm2 window
|
|
182
184
|
- [Typed getters](#typed-getters) — page properties
|
|
183
185
|
- [Generators](#generators) — random fixture data + time
|
|
184
186
|
- [`evaluate`](#evaluate) — escape hatch into the page
|
|
185
187
|
- [Logging](#logging)
|
|
188
|
+
- [Signatures](#signatures) — every function with the types it takes
|
|
186
189
|
|
|
187
190
|
---
|
|
188
191
|
|
|
@@ -207,8 +210,9 @@ getByRole('row').filter({hasText: /done/i})
|
|
|
207
210
|
## The `timeout` option
|
|
208
211
|
|
|
209
212
|
Actions, navigation, waits and assertions take their time limit in
|
|
210
|
-
milliseconds as `
|
|
211
|
-
|
|
213
|
+
milliseconds as `timeoutMs`. Where a signature lists `timeoutMs?`, the
|
|
214
|
+
older spelling `timeout` is accepted as an alias for it; giving both in
|
|
215
|
+
one call is refused. The examples below use `timeoutMs`.
|
|
212
216
|
|
|
213
217
|
An option an action, a navigation, a wait or an assertion does not take
|
|
214
218
|
is refused with the ones it does, so a misspelled `{timout: 5000}` fails at once
|
|
@@ -370,7 +374,7 @@ click(getByRole('button', {name: 'Save'}))
|
|
|
370
374
|
click(getByText('Submit'), {force: true})
|
|
371
375
|
```
|
|
372
376
|
|
|
373
|
-
**Options:** `force?`, `
|
|
377
|
+
**Options:** `force?`, `timeoutMs?`, `position?`, `modifiers?`.
|
|
374
378
|
|
|
375
379
|
### `doubleClick(loc, options?)`
|
|
376
380
|
|
|
@@ -399,7 +403,7 @@ press(getByLabel('Body'), 'Control+A')
|
|
|
399
403
|
|
|
400
404
|
Idempotent — no click if already in the target state. Otherwise one
|
|
401
405
|
click, then a wait until the element reads checked (unchecked) within
|
|
402
|
-
the action timeout (`options.
|
|
406
|
+
the action timeout (`options.timeoutMs`, else the config default). A
|
|
403
407
|
controlled switch the app flips a beat after the click — once the server
|
|
404
408
|
confirms — passes; one that never flips fails, naming the state it
|
|
405
409
|
wanted and the last one it saw. Works on native checkboxes and radios
|
|
@@ -409,7 +413,7 @@ wrapped input). Any other element is refused — use `click` for it.
|
|
|
409
413
|
|
|
410
414
|
```js
|
|
411
415
|
check(getByRole('checkbox', {name: 'Subscribe'}))
|
|
412
|
-
uncheck(getByRole('switch', {name: 'Notifications'}), {
|
|
416
|
+
uncheck(getByRole('switch', {name: 'Notifications'}), {timeoutMs: 5000})
|
|
413
417
|
```
|
|
414
418
|
|
|
415
419
|
### `hover(loc, options?)`
|
|
@@ -421,17 +425,28 @@ hover(getByRole('button', {name: 'Help'}))
|
|
|
421
425
|
hover(getByTestId('message-42'), {position: {x: 24, y: 8}})
|
|
422
426
|
```
|
|
423
427
|
|
|
424
|
-
**Options:** `force?`, `
|
|
428
|
+
**Options:** `force?`, `timeoutMs?`, `position?` (no `modifiers` — that
|
|
425
429
|
is a `click` option).
|
|
426
430
|
|
|
427
431
|
### `selectOption(loc, value, options?)`
|
|
428
432
|
|
|
429
|
-
Native `<select>` only. `value`
|
|
430
|
-
|
|
433
|
+
Native `<select>` only. `value` picks the option:
|
|
434
|
+
|
|
435
|
+
- by its value — a string, `{value}`, or an array of strings for a
|
|
436
|
+
multi-select;
|
|
437
|
+
- by its visible text — `{label}`;
|
|
438
|
+
- by its position — `{index}`, from 0.
|
|
439
|
+
|
|
440
|
+
The call waits for the option to appear. A `{label}` or `{index}` no
|
|
441
|
+
option has fails with the labels the element holds:
|
|
442
|
+
`selectOption: … has no option labelled "Blue" — labels: "Red", "Dark
|
|
443
|
+
blue".` A misspelt key (`{lable}`) is `validator:options`.
|
|
431
444
|
|
|
432
445
|
```js
|
|
433
446
|
selectOption(getByLabel('Country'), 'US')
|
|
434
447
|
selectOption(getByLabel('Tags'), ['a', 'b'])
|
|
448
|
+
selectOption(getByLabel('Folder'), {label: 'Archive'})
|
|
449
|
+
selectOption(getByLabel('Folder'), {index: 0})
|
|
435
450
|
```
|
|
436
451
|
|
|
437
452
|
### `scrollIntoView(loc)`
|
|
@@ -445,7 +460,7 @@ scrollIntoView(getByText('Footer'))
|
|
|
445
460
|
## Assertions
|
|
446
461
|
|
|
447
462
|
Each polls until the condition holds or the timeout fires (default 5s;
|
|
448
|
-
override per-call with `{
|
|
463
|
+
override per-call with `{timeoutMs}`). Throw `AssertionError` on failure.
|
|
449
464
|
|
|
450
465
|
### `assertText(loc, expected, options?)`
|
|
451
466
|
|
|
@@ -466,7 +481,7 @@ assertText(getByRole('status'), 'Saving…', {not: true}) // waits until it ch
|
|
|
466
481
|
- Empty text: `assertText(loc, '')`. Any text at all:
|
|
467
482
|
`assertText(loc, '', {not: true})`.
|
|
468
483
|
|
|
469
|
-
**Options:** `
|
|
484
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`), `not?`.
|
|
470
485
|
|
|
471
486
|
### `assertTexts(loc, expected, options?)`
|
|
472
487
|
|
|
@@ -477,7 +492,7 @@ list that is still filling in passes once it is complete.
|
|
|
477
492
|
|
|
478
493
|
```js
|
|
479
494
|
assertTexts(getByRole('listitem'), ['Apple', 'Banana', /^Cherry/])
|
|
480
|
-
labels = ['Apple', 'Banana'];
|
|
495
|
+
const labels = ['Apple', 'Banana'];
|
|
481
496
|
assertTexts(getByRole('listitem'), labels)
|
|
482
497
|
assertText(getByRole('listitem').first(), labels[0])
|
|
483
498
|
```
|
|
@@ -487,7 +502,7 @@ an index read, a helper's result. A value known to be something else (a
|
|
|
487
502
|
string, a number) is refused by the linter; the rest is checked when the
|
|
488
503
|
step runs. The same holds for the expected text of `assertText`.
|
|
489
504
|
|
|
490
|
-
**Options:** `
|
|
505
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`).
|
|
491
506
|
|
|
492
507
|
### `assertAttribute(loc, name, expected, options?)`
|
|
493
508
|
|
|
@@ -503,15 +518,15 @@ assertAttribute(getByRole('link', {name: 'Docs'}), 'href', /\/docs\//)
|
|
|
503
518
|
assertAttribute(getByRole('form'), 'aria-busy', 'true', {not: true})
|
|
504
519
|
```
|
|
505
520
|
|
|
506
|
-
**Options:** `
|
|
521
|
+
**Options:** `timeoutMs?`, `exact?` (default `true`), `not?`.
|
|
507
522
|
|
|
508
523
|
### `assertVisible(loc, options?)` / `assertHidden(loc, options?)`
|
|
509
524
|
|
|
510
|
-
**Options:** `
|
|
525
|
+
**Options:** `timeoutMs?`.
|
|
511
526
|
|
|
512
527
|
```js
|
|
513
528
|
assertVisible(getByTestId('toast'))
|
|
514
|
-
assertHidden(getByTestId('spinner'), {
|
|
529
|
+
assertHidden(getByTestId('spinner'), {timeoutMs: 10000})
|
|
515
530
|
```
|
|
516
531
|
|
|
517
532
|
### `assertNeverAppears(loc, options)`
|
|
@@ -532,11 +547,39 @@ system under test could realistically react. Unlike `assertHidden`
|
|
|
532
547
|
(a poll that PASSES as soon as the element is gone), this one watches
|
|
533
548
|
the whole window.
|
|
534
549
|
|
|
550
|
+
### `assertNever(() => condition, options)`
|
|
551
|
+
|
|
552
|
+
The same window for a condition instead of a locator: poll the body for
|
|
553
|
+
`withinMs` (required) and **fail the moment** it is truthy; pass only
|
|
554
|
+
when the whole window elapsed clean. Use it where `pause()` and one
|
|
555
|
+
assertion afterwards would miss an event that came and went inside the
|
|
556
|
+
pause.
|
|
557
|
+
|
|
558
|
+
```js
|
|
559
|
+
assertNever(() => apiCall('GET', '/me', null, revokedAuth).status == 200,
|
|
560
|
+
{withinMs: 5000, label: 'revoked key rejected'});
|
|
561
|
+
assertNever(() => {
|
|
562
|
+
const n = parseJson(textContent(getByTestId('unread')));
|
|
563
|
+
if (n > 0) { return n; }
|
|
564
|
+
return false;
|
|
565
|
+
}, {withinMs: 3000, intervalMs: 100});
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
- The body is an arrow, as in `waitUntil`: an expression, or a block
|
|
569
|
+
that gives its value with `return`.
|
|
570
|
+
- Options: `{ withinMs, intervalMs?, label? }`. `intervalMs` defaults to
|
|
571
|
+
250; the last poll falls on the end of the window.
|
|
572
|
+
- The failure names the label, the moment and the value: `assertNever
|
|
573
|
+
"revoked key rejected": truthy at 1250 ms of the 5000 ms window (6
|
|
574
|
+
tries); value: true.`
|
|
575
|
+
- An error inside the body fails the step at once. A clean window costs
|
|
576
|
+
the whole `withinMs`.
|
|
577
|
+
|
|
535
578
|
### `assertValue(loc, expected, options?)`
|
|
536
579
|
|
|
537
580
|
Compares `inputValue()` (`<input>`, `<textarea>`, native `<select>`).
|
|
538
581
|
|
|
539
|
-
**Options:** `
|
|
582
|
+
**Options:** `timeoutMs?`.
|
|
540
583
|
|
|
541
584
|
```js
|
|
542
585
|
assertValue(getByLabel('Email'), 'a@b.c')
|
|
@@ -561,11 +604,11 @@ value, and so does the failure.
|
|
|
561
604
|
|
|
562
605
|
### `assertCount(loc, expected, options?)`
|
|
563
606
|
|
|
564
|
-
**Options:** `
|
|
607
|
+
**Options:** `timeoutMs?`.
|
|
565
608
|
|
|
566
609
|
```js
|
|
567
610
|
assertCount(getByRole('listitem'), 5)
|
|
568
|
-
assertCount(getByRole('row'), 20, {
|
|
611
|
+
assertCount(getByRole('row'), 20, {timeoutMs: 15000})
|
|
569
612
|
```
|
|
570
613
|
|
|
571
614
|
### `assertUrl(pattern, options?)`
|
|
@@ -574,7 +617,7 @@ A string is a substring match against the active page's URL. A
|
|
|
574
617
|
`/regex/` is tested against the whole URL, unanchored: add `^` or `$`
|
|
575
618
|
yourself. A failure names the regex as `/source/flags`.
|
|
576
619
|
|
|
577
|
-
**Options:** `
|
|
620
|
+
**Options:** `timeoutMs?`.
|
|
578
621
|
|
|
579
622
|
```js
|
|
580
623
|
assertUrl('/dashboard')
|
|
@@ -587,7 +630,7 @@ assertUrl(/\/cars\/\d+$/)
|
|
|
587
630
|
Generic boolean assert. Throws with `message` when `value` is falsy.
|
|
588
631
|
|
|
589
632
|
```js
|
|
590
|
-
probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
|
|
633
|
+
const probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
|
|
591
634
|
assertTrue(probe.code == 0, 'app.log should contain "ready"');
|
|
592
635
|
```
|
|
593
636
|
|
|
@@ -599,7 +642,7 @@ names the first path that differs and both values, then a line diff of
|
|
|
599
642
|
the two sides, every line of them — nothing is folded away:
|
|
600
643
|
|
|
601
644
|
```js
|
|
602
|
-
body = parseJson(getAttribute(locator('#state'), 'data-json'));
|
|
645
|
+
const body = parseJson(getAttribute(locator('#state'), 'data-json'));
|
|
603
646
|
assertEqual(body.controls, {theme: 'dark', devices: ['pixel']});
|
|
604
647
|
// assertEqual: values differ at devices[0]: expected "pixel", got "iphone"
|
|
605
648
|
```
|
|
@@ -612,8 +655,8 @@ reads with `readJson`. The failure names every field that breaks the
|
|
|
612
655
|
schema, by path, with what is wrong there:
|
|
613
656
|
|
|
614
657
|
```js
|
|
615
|
-
schema = readJson('unotest/fixtures/message.schema.json');
|
|
616
|
-
req = waitForRequest('**/api/messages');
|
|
658
|
+
const schema = readJson('unotest/fixtures/message.schema.json');
|
|
659
|
+
const req = waitForRequest('**/api/messages');
|
|
617
660
|
assertSchema(req.postDataJson, schema);
|
|
618
661
|
// assertSchema: the value breaks the schema in 2 places:
|
|
619
662
|
// /room: must be >= 1
|
|
@@ -655,7 +698,7 @@ inside that step:
|
|
|
655
698
|
```js
|
|
656
699
|
function test_refund() {
|
|
657
700
|
step("Find a paid order", () => {
|
|
658
|
-
orders = apiCall('GET', '/orders?status=paid');
|
|
701
|
+
const orders = apiCall('GET', '/orders?status=paid');
|
|
659
702
|
if (orders.length == 0) { skip('no paid order on this stand'); }
|
|
660
703
|
});
|
|
661
704
|
// …
|
|
@@ -686,7 +729,7 @@ go to the configured judge; a `fail` verdict fails the step with the
|
|
|
686
729
|
judge's reasoning, like any other assertion.
|
|
687
730
|
|
|
688
731
|
```js
|
|
689
|
-
reply = locator('.chat__message').last();
|
|
732
|
+
const reply = locator('.chat__message').last();
|
|
690
733
|
assertJudge(reply,
|
|
691
734
|
'The reply must direct the user to support and must NOT promise ' +
|
|
692
735
|
'to escalate, resend the email, or notify a team itself.');
|
|
@@ -864,10 +907,10 @@ class or attribute — CSS. `assertCount` / `waitForCount` take the same
|
|
|
864
907
|
locator and wait for the number.
|
|
865
908
|
|
|
866
909
|
```js
|
|
867
|
-
done = count(getByRole('row').filter({hasText: 'Done'}));
|
|
868
|
-
admins = count(getByRole('row').filter({has: getByTestId('admin-badge')}));
|
|
869
|
-
selected = count(locator('li.selected'));
|
|
870
|
-
external = count(locator('a[target="_blank"]'));
|
|
910
|
+
const done = count(getByRole('row').filter({hasText: 'Done'}));
|
|
911
|
+
const admins = count(getByRole('row').filter({has: getByTestId('admin-badge')}));
|
|
912
|
+
const selected = count(locator('li.selected'));
|
|
913
|
+
const external = count(locator('a[target="_blank"]'));
|
|
871
914
|
assertCount(getByRole('listitem').filter({hasNotText: 'Archived'}), 3)
|
|
872
915
|
```
|
|
873
916
|
|
|
@@ -882,7 +925,7 @@ when nothing matches. One read, no wait — the list to branch on.
|
|
|
882
925
|
`assertTexts` is the waiting check of the same list.
|
|
883
926
|
|
|
884
927
|
```js
|
|
885
|
-
names = texts(locator('#agents li')); // ["Claude Code", "Codex"]
|
|
928
|
+
const names = texts(locator('#agents li')); // ["Claude Code", "Codex"]
|
|
886
929
|
if (names.length > 0) {
|
|
887
930
|
log('first agent:', names[0]);
|
|
888
931
|
}
|
|
@@ -922,7 +965,7 @@ Whether the attribute is present at all — the honest probe for boolean
|
|
|
922
965
|
attributes (`disabled`, `readonly`, `required`, …).
|
|
923
966
|
|
|
924
967
|
```js
|
|
925
|
-
n = count(getByRole('row'));
|
|
968
|
+
const n = count(getByRole('row'));
|
|
926
969
|
if (n > 10) {
|
|
927
970
|
log('too many rows:', n);
|
|
928
971
|
}
|
|
@@ -940,7 +983,8 @@ goto('/dashboard') // relative — resolved against the
|
|
|
940
983
|
```
|
|
941
984
|
|
|
942
985
|
**Options:** `waitUntil?` (`'load'` | `'domcontentloaded'` |
|
|
943
|
-
`'networkidle'`), `
|
|
986
|
+
`'networkidle'` | `'commit'`), `timeoutMs?`. The same two keys go to
|
|
987
|
+
`reload`, `goBack`, `goForward` and `waitForUrl`.
|
|
944
988
|
|
|
945
989
|
### `reload(options?)` / `goBack(options?)` / `goForward(options?)`
|
|
946
990
|
|
|
@@ -950,7 +994,7 @@ Wait until the active page URL contains `pattern` (a string) or matches
|
|
|
950
994
|
it (a `/regex/`, unanchored). Useful after a click that triggers
|
|
951
995
|
navigation.
|
|
952
996
|
|
|
953
|
-
**Options:** `
|
|
997
|
+
**Options:** `waitUntil?` (as for `goto`), `timeoutMs?`.
|
|
954
998
|
|
|
955
999
|
```js
|
|
956
1000
|
click(getByRole('link', {name: 'Settings'}));
|
|
@@ -976,7 +1020,7 @@ waitFor(getByTestId('content-loaded'))
|
|
|
976
1020
|
|
|
977
1021
|
```js
|
|
978
1022
|
step("Wait until the widget re-enables the send button", () => {
|
|
979
|
-
waitFor(locator('.chat__send'), {state: 'enabled',
|
|
1023
|
+
waitFor(locator('.chat__send'), {state: 'enabled', timeoutMs: 30000});
|
|
980
1024
|
});
|
|
981
1025
|
```
|
|
982
1026
|
|
|
@@ -994,8 +1038,8 @@ until it is truthy; the call gives that value back.
|
|
|
994
1038
|
|
|
995
1039
|
```js
|
|
996
1040
|
waitUntil(() => parseJson(textContent(getByTestId('count'))) >= 5);
|
|
997
|
-
job = waitUntil(() => {
|
|
998
|
-
r = apiCall('GET', '/jobs/' + id);
|
|
1041
|
+
const job = waitUntil(() => {
|
|
1042
|
+
const r = apiCall('GET', '/jobs/' + id);
|
|
999
1043
|
if (r.body.state != 'done') { return false; }
|
|
1000
1044
|
return r.body;
|
|
1001
1045
|
}, {timeoutMs: 30000, intervalMs: 500, label: 'job done'});
|
|
@@ -1012,15 +1056,43 @@ job = waitUntil(() => {
|
|
|
1012
1056
|
- On timeout the step fails with the label, the number of tries and the
|
|
1013
1057
|
last value: `waitUntil "job done": still falsy after 30000 ms (60
|
|
1014
1058
|
tries); last value: false.`
|
|
1059
|
+
- State the body keeps between tries — a counter, the last value seen —
|
|
1060
|
+
lives in a variable declared with `let` inside the `test_` function or
|
|
1061
|
+
the step; the body writes it:
|
|
1062
|
+
|
|
1063
|
+
```js
|
|
1064
|
+
let tries = 0;
|
|
1065
|
+
const n = waitUntil(() => {
|
|
1066
|
+
tries = tries + 1;
|
|
1067
|
+
return tries >= 3 ? tries : false;
|
|
1068
|
+
});
|
|
1069
|
+
assertEqual(n, 3);
|
|
1070
|
+
```
|
|
1071
|
+
|
|
1072
|
+
A `let` at the top level of the file belongs to no test: the validator
|
|
1073
|
+
refuses the declaration (`validator:top-level-statement`).
|
|
1074
|
+
|
|
1075
|
+
```js bad
|
|
1076
|
+
let seen = 0;
|
|
1077
|
+
|
|
1078
|
+
function test_counter() {
|
|
1079
|
+
step('poll', () => {
|
|
1080
|
+
waitUntil(() => {
|
|
1081
|
+
seen = seen + 1;
|
|
1082
|
+
return seen >= 3;
|
|
1083
|
+
});
|
|
1084
|
+
});
|
|
1085
|
+
}
|
|
1086
|
+
```
|
|
1015
1087
|
|
|
1016
1088
|
### `waitForText(text, options?)`
|
|
1017
1089
|
|
|
1018
1090
|
Wait until at least one **visible** element on the active page contains
|
|
1019
1091
|
`text` (chat feeds and repeated labels legally duplicate text — ≥1
|
|
1020
|
-
visible match is the success condition; `
|
|
1021
|
-
|
|
1092
|
+
visible match is the success condition; the `first` option of older
|
|
1093
|
+
releases is gone and is refused).
|
|
1022
1094
|
|
|
1023
|
-
Options: `{ exact?, state?,
|
|
1095
|
+
Options: `{ exact?, state?, timeoutMs? }`. Default matching is substring —
|
|
1024
1096
|
it also matches *inside* a word (`'hi'` hits `'anything'`). For precise
|
|
1025
1097
|
matching pass `{exact: true}` (full-text equality) or a regex with word
|
|
1026
1098
|
boundaries:
|
|
@@ -1028,7 +1100,7 @@ boundaries:
|
|
|
1028
1100
|
```js
|
|
1029
1101
|
waitForText('Active'); // ≥1 visible occurrence
|
|
1030
1102
|
waitForText('Active', {exact: true}); // full-text equality
|
|
1031
|
-
waitForText(/\bhi\b/, {
|
|
1103
|
+
waitForText(/\bhi\b/, {timeoutMs: 60000}); // word-boundary, long poll
|
|
1032
1104
|
```
|
|
1033
1105
|
|
|
1034
1106
|
`state: 'hidden'` waits until **no** visible occurrence remains.
|
|
@@ -1043,11 +1115,11 @@ send, then wait for the count to grow — and only then assert on reply
|
|
|
1043
1115
|
content:
|
|
1044
1116
|
|
|
1045
1117
|
```js
|
|
1046
|
-
n = count(locator('[data-message]'));
|
|
1118
|
+
const n = count(locator('[data-message]'));
|
|
1047
1119
|
fill(getByRole('textbox'), '@Bot Service ' + question);
|
|
1048
1120
|
press(getByRole('textbox'), 'Enter');
|
|
1049
|
-
waitForCount(locator('[data-message]'), n + 2, {
|
|
1050
|
-
waitForText(/Ital/i, {
|
|
1121
|
+
waitForCount(locator('[data-message]'), n + 2, {timeoutMs: 90000}); // echo + reply
|
|
1122
|
+
waitForText(/Ital/i, {timeoutMs: 90000}); // reply content
|
|
1051
1123
|
```
|
|
1052
1124
|
|
|
1053
1125
|
A unique marker (`randomWord(8)`) in the outgoing message plus a wait on
|
|
@@ -1060,14 +1132,14 @@ pattern "wait for reply №N": at-least semantics don't flake when the
|
|
|
1060
1132
|
feed grows past N between polls. `{exact: true}` waits for exactly
|
|
1061
1133
|
`count` matches; timeout throws with the last observed count.
|
|
1062
1134
|
|
|
1063
|
-
Options: `{ exact?,
|
|
1135
|
+
Options: `{ exact?, timeoutMs? }` (default timeout 5000 ms — raise it for
|
|
1064
1136
|
slow producers like LLM replies).
|
|
1065
1137
|
|
|
1066
1138
|
```js
|
|
1067
1139
|
// Chat feed: the bot's reply is message #3 — wait for it, then assert
|
|
1068
1140
|
// on its text with a second, content-anchored wait:
|
|
1069
|
-
waitForCount(locator('[data-id]'), 3, {
|
|
1070
|
-
waitForText(/\bshipping\b/i, {
|
|
1141
|
+
waitForCount(locator('[data-id]'), 3, {timeoutMs: 90000});
|
|
1142
|
+
waitForText(/\bshipping\b/i, {timeoutMs: 90000});
|
|
1071
1143
|
```
|
|
1072
1144
|
|
|
1073
1145
|
### `waitForAnimations(loc, options?)`
|
|
@@ -1078,7 +1150,7 @@ or screenshotting it. Infinite animations (spinners) and paused ones are
|
|
|
1078
1150
|
not waited for: neither ends by itself, so waiting could only time out.
|
|
1079
1151
|
A static element returns at once. Same rule as `hasAnimation`.
|
|
1080
1152
|
|
|
1081
|
-
Options: `{
|
|
1153
|
+
Options: `{ timeoutMs? }` (default 5000 ms). A timeout is an error naming
|
|
1082
1154
|
the element and how many animations were still running.
|
|
1083
1155
|
|
|
1084
1156
|
```js
|
|
@@ -1214,6 +1286,44 @@ bringToFront(); // now tab 1 is shown too
|
|
|
1214
1286
|
bringToFront(0); // show the site again; steps stay on 1
|
|
1215
1287
|
```
|
|
1216
1288
|
|
|
1289
|
+
### `setPageHidden(hidden, index?)`
|
|
1290
|
+
|
|
1291
|
+
Emulates the tab's visibility for the page's scripts. `true` sends tab
|
|
1292
|
+
`index` to the background as its scripts see it: `document.hidden` is
|
|
1293
|
+
`true`, `document.visibilityState` is `'hidden'`, `document.hasFocus()`
|
|
1294
|
+
is `false`, and the page gets `blur` on `window`, then
|
|
1295
|
+
`visibilitychange`. `false` brings it back: `visibilitychange`, then
|
|
1296
|
+
`focus`. No index: the active tab. The steps keep acting on the hidden
|
|
1297
|
+
tab, as on any other.
|
|
1298
|
+
|
|
1299
|
+
A hidden tab stays hidden across navigations, and in its frames, until
|
|
1300
|
+
`setPageHidden(false)`. Asking for the state the tab is already in
|
|
1301
|
+
fires nothing. `setPage` and `bringToFront` do not show a hidden tab.
|
|
1302
|
+
|
|
1303
|
+
```js
|
|
1304
|
+
step("A message that arrives while the chat is in the background", () => {
|
|
1305
|
+
goto('/chat');
|
|
1306
|
+
clockFreeze('2026-01-15T10:00:00Z');
|
|
1307
|
+
setPageHidden(true);
|
|
1308
|
+
clockTick(6 * 60 * 1000); // six minutes away, on the page clock
|
|
1309
|
+
setPageHidden(false);
|
|
1310
|
+
assertVisible(getByText('New message'));
|
|
1311
|
+
});
|
|
1312
|
+
```
|
|
1313
|
+
|
|
1314
|
+
Time away is the page clock's
|
|
1315
|
+
([`clockTick`](#clockfreezeiso--clocktickms--clockrun)) or real
|
|
1316
|
+
(`pause(ms)`); hiding the tab does not move it.
|
|
1317
|
+
|
|
1318
|
+
Not emulated: what the browser itself does to a background tab.
|
|
1319
|
+
Timers are not throttled, animation frames keep running, the page is
|
|
1320
|
+
not frozen (`freeze` / `resume`), and a service worker's
|
|
1321
|
+
`clients.matchAll()` still reports the tab `visible`.
|
|
1322
|
+
|
|
1323
|
+
Engines: the same in Chromium, Firefox and WebKit. In Firefox a frame
|
|
1324
|
+
that loads while the tab is hidden sees it visible while it loads, and
|
|
1325
|
+
hidden from then on.
|
|
1326
|
+
|
|
1217
1327
|
### `newPage(url?)` → `number`
|
|
1218
1328
|
|
|
1219
1329
|
Open a new tab in the active browser context, make it active and bring
|
|
@@ -1255,7 +1365,7 @@ no new tab within it, the step fails with
|
|
|
1255
1365
|
|
|
1256
1366
|
```js
|
|
1257
1367
|
click(getByRole('button', {name: 'Open report'}));
|
|
1258
|
-
tab = waitForPage(); // e.g. 1, now active
|
|
1368
|
+
const tab = waitForPage(); // e.g. 1, now active
|
|
1259
1369
|
assertUrl('/report');
|
|
1260
1370
|
setPage(0);
|
|
1261
1371
|
```
|
|
@@ -1277,6 +1387,7 @@ back lands where the scenario left off.
|
|
|
1277
1387
|
|
|
1278
1388
|
```js
|
|
1279
1389
|
function test_second_client_writes_to_closed_thread() {
|
|
1390
|
+
let clientB;
|
|
1280
1391
|
step("Client A opens the thread", () => {
|
|
1281
1392
|
flow_login(LOGIN, PASSWORD);
|
|
1282
1393
|
goto('/support/thread/42');
|
|
@@ -1381,6 +1492,59 @@ again after `setPage` / `waitForPage`. An app that reads the color
|
|
|
1381
1492
|
scheme once at load sees the change on its next load (`reload()`), not
|
|
1382
1493
|
before.
|
|
1383
1494
|
|
|
1495
|
+
### `addVirtualAuthenticator(options?)` → `id` / `virtualCredentials(id?)` / `removeVirtualAuthenticator(id)`
|
|
1496
|
+
|
|
1497
|
+
A passkey without a person at a device: a virtual WebAuthn
|
|
1498
|
+
authenticator answers the page's `navigator.credentials.create()` and
|
|
1499
|
+
`.get()` as a phone or laptop would. **Chromium only**; Firefox and
|
|
1500
|
+
WebKit fail the call with an error naming the engine.
|
|
1501
|
+
|
|
1502
|
+
```js
|
|
1503
|
+
const key = addVirtualAuthenticator();
|
|
1504
|
+
click(getByRole('button', {name: 'Create a passkey'}));
|
|
1505
|
+
waitForText('Passkey saved');
|
|
1506
|
+
const [passkey] = virtualCredentials(key);
|
|
1507
|
+
assertTrue(passkey.rpId == 'app.example.com', json(passkey));
|
|
1508
|
+
click(getByRole('button', {name: 'Sign in with a passkey'}));
|
|
1509
|
+
waitForText('Welcome back');
|
|
1510
|
+
```
|
|
1511
|
+
|
|
1512
|
+
- Without options it is the passkey of a phone or laptop: `protocol:
|
|
1513
|
+
'ctap2'`, `transport: 'internal'`, a resident key, a verified user,
|
|
1514
|
+
and every request answered without a touch. Each option overrides one
|
|
1515
|
+
of these: `protocol` (`'ctap2'` | `'u2f'`), `transport`
|
|
1516
|
+
(`'internal'` | `'usb'` | `'nfc'` | `'ble'` | `'cable'`),
|
|
1517
|
+
`hasResidentKey`, `hasUserVerification`, `isUserVerified`,
|
|
1518
|
+
`automaticPresenceSimulation`.
|
|
1519
|
+
- `virtualCredentials(id?)` — `[{credentialId, rpId, userHandle,
|
|
1520
|
+
signCount, resident}]` of one authenticator, or of all. Ids are
|
|
1521
|
+
base64url, as the page's `PublicKeyCredential.id` spells them;
|
|
1522
|
+
`signCount` grows with every sign-in.
|
|
1523
|
+
- The authenticator belongs to the tab that was active when it was
|
|
1524
|
+
added: a tab opened later does not see it.
|
|
1525
|
+
- The page must be https or `localhost`: WebAuthn does not exist
|
|
1526
|
+
elsewhere.
|
|
1527
|
+
|
|
1528
|
+
### `grantPermissions(permissions, options?)` / `setOffline(offline)`
|
|
1529
|
+
|
|
1530
|
+
```js
|
|
1531
|
+
grantPermissions(['notifications']);
|
|
1532
|
+
grantPermissions(['geolocation'], {origin: 'https://maps.example.com'});
|
|
1533
|
+
setOffline(true); // every request of the context fails as offline
|
|
1534
|
+
click(getByRole('button', {name: 'Sync'}));
|
|
1535
|
+
waitForText('You are offline');
|
|
1536
|
+
setOffline(false);
|
|
1537
|
+
```
|
|
1538
|
+
|
|
1539
|
+
- `grantPermissions` gives the context the named permissions, for every
|
|
1540
|
+
origin or for `{origin}`. The names are the browser's — which ones an
|
|
1541
|
+
engine knows differs: a name the engine does not know fails the call
|
|
1542
|
+
naming the engine, and what was granted before stays granted.
|
|
1543
|
+
- `setOffline(true)` cuts every page of the context off the network;
|
|
1544
|
+
`setOffline(false)` connects it again.
|
|
1545
|
+
- Both, and the authenticators, are taken back when the context closes:
|
|
1546
|
+
the next scenario starts without them.
|
|
1547
|
+
|
|
1384
1548
|
#### Viewport and scale
|
|
1385
1549
|
|
|
1386
1550
|
Where the window's size and scale come from, first match wins:
|
|
@@ -1473,9 +1637,9 @@ Headless needs `channel: "chromium"` (the headless shell ignores
|
|
|
1473
1637
|
`--load-extension`).
|
|
1474
1638
|
|
|
1475
1639
|
```js
|
|
1476
|
-
id = extensionId();
|
|
1640
|
+
const id = extensionId();
|
|
1477
1641
|
evaluateInServiceWorker('(theme) => chrome.storage.local.set({theme: theme})', 'dark');
|
|
1478
|
-
stored = evaluateInServiceWorker('() => chrome.storage.local.get("theme")');
|
|
1642
|
+
const stored = evaluateInServiceWorker('() => chrome.storage.local.get("theme")');
|
|
1479
1643
|
goto('chrome-extension://' + id + '/popup.html');
|
|
1480
1644
|
```
|
|
1481
1645
|
|
|
@@ -1508,7 +1672,7 @@ Returns empty string when key is absent.
|
|
|
1508
1672
|
|
|
1509
1673
|
```js
|
|
1510
1674
|
setLocalStorage('feature-flag', 'enabled');
|
|
1511
|
-
v = getLocalStorage('feature-flag');
|
|
1675
|
+
const v = getLocalStorage('feature-flag');
|
|
1512
1676
|
```
|
|
1513
1677
|
|
|
1514
1678
|
### `setCookie(name, value, options?)` / `getCookie(name)` → `string`
|
|
@@ -1554,6 +1718,29 @@ real event won't accept formatting.
|
|
|
1554
1718
|
clipboardPaste(getByLabel('Notes'), 'pasted text');
|
|
1555
1719
|
```
|
|
1556
1720
|
|
|
1721
|
+
### `clipboardRead()` → `string` / `assertClipboard(expected, options?)`
|
|
1722
|
+
|
|
1723
|
+
What a "copy" button left in the clipboard — read by the active page,
|
|
1724
|
+
instead of intercepting `navigator.clipboard.writeText` in it.
|
|
1725
|
+
|
|
1726
|
+
```js
|
|
1727
|
+
click(getByRole('button', {name: 'Copy invite link'}));
|
|
1728
|
+
assertClipboard(/\/invite\/\d+$/);
|
|
1729
|
+
const link = clipboardRead();
|
|
1730
|
+
```
|
|
1731
|
+
|
|
1732
|
+
- `assertClipboard` waits until the clipboard holds `expected` — the
|
|
1733
|
+
whole text for a string, a match for a regex — `{timeoutMs}`, default
|
|
1734
|
+
5 s. A page writes the clipboard from a promise, so the text lands a
|
|
1735
|
+
beat after the click; `clipboardRead()` reads once, without waiting.
|
|
1736
|
+
- Engines: Chromium (the context is given clipboard read and write
|
|
1737
|
+
access when it is opened, so the page's own copy works too) and
|
|
1738
|
+
Firefox, on an https or `localhost` page — the clipboard API does not
|
|
1739
|
+
exist elsewhere. WebKit does not let a page read the clipboard: the
|
|
1740
|
+
call fails with an error naming the engine, never an empty string.
|
|
1741
|
+
- The clipboard belongs to the browser, not to one test: tests running
|
|
1742
|
+
in parallel in one browser share it.
|
|
1743
|
+
|
|
1557
1744
|
---
|
|
1558
1745
|
|
|
1559
1746
|
## Sandbox primitives
|
|
@@ -1607,8 +1794,8 @@ Semantics:
|
|
|
1607
1794
|
(values stay masked in logs).
|
|
1608
1795
|
|
|
1609
1796
|
```js
|
|
1610
|
-
out = shell('pnpm', 'db:create-user', 'alice'); // non-zero exit → step fails
|
|
1611
|
-
probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
|
|
1797
|
+
const out = shell('pnpm', 'db:create-user', 'alice'); // non-zero exit → step fails
|
|
1798
|
+
const probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
|
|
1612
1799
|
if (probe.code == 0) { /* … */ }
|
|
1613
1800
|
```
|
|
1614
1801
|
|
|
@@ -1659,7 +1846,7 @@ downloads that are there but did not match.
|
|
|
1659
1846
|
```js
|
|
1660
1847
|
step("Export the report", () => {
|
|
1661
1848
|
click(getByRole('button', {name: 'Export CSV'}));
|
|
1662
|
-
report = waitForDownload({name: /\.csv$/});
|
|
1849
|
+
const report = waitForDownload({name: /\.csv$/});
|
|
1663
1850
|
waitForFile(report.path, 'id,total');
|
|
1664
1851
|
});
|
|
1665
1852
|
```
|
|
@@ -1695,7 +1882,7 @@ export default {
|
|
|
1695
1882
|
|
|
1696
1883
|
```js
|
|
1697
1884
|
step("Wait for the bot reply in the JSONL feed", () => {
|
|
1698
|
-
line = waitForFile('events.jsonl', /"type":"reply"/, {timeoutMs: 30000});
|
|
1885
|
+
const line = waitForFile('events.jsonl', /"type":"reply"/, {timeoutMs: 30000});
|
|
1699
1886
|
});
|
|
1700
1887
|
```
|
|
1701
1888
|
|
|
@@ -1727,7 +1914,7 @@ its fields.
|
|
|
1727
1914
|
|
|
1728
1915
|
```js
|
|
1729
1916
|
step("Wait for the bot's reply event", () => {
|
|
1730
|
-
evt = waitForJsonLine('events.jsonl',
|
|
1917
|
+
const evt = waitForJsonLine('events.jsonl',
|
|
1731
1918
|
{userId: BOT_ID, roomId: room, isBot: true}, {timeoutMs: 30000});
|
|
1732
1919
|
assertTrue(textContains(evt.text, 'hello'), evt.text);
|
|
1733
1920
|
});
|
|
@@ -1766,7 +1953,7 @@ equality per key, dot paths for nesting, unparsable lines skipped).
|
|
|
1766
1953
|
|
|
1767
1954
|
```js
|
|
1768
1955
|
step("Ask control question 3", () => {
|
|
1769
|
-
q = readJsonLine('questions.jsonl', {slot: 3});
|
|
1956
|
+
const q = readJsonLine('questions.jsonl', {slot: 3});
|
|
1770
1957
|
fill(getByRole('textbox', {name: 'Message'}), q.text);
|
|
1771
1958
|
screenshot(q.id);
|
|
1772
1959
|
});
|
|
@@ -1789,7 +1976,7 @@ fixture object. Walk the result with `.` and `[]`.
|
|
|
1789
1976
|
|
|
1790
1977
|
```js
|
|
1791
1978
|
step("Send button uses the app's own label", () => {
|
|
1792
|
-
shared = readJson('unotest/fixtures/shared.json');
|
|
1979
|
+
const shared = readJson('unotest/fixtures/shared.json');
|
|
1793
1980
|
assertVisible(getByRole('button', {name: shared.chat.labels[0].send}));
|
|
1794
1981
|
});
|
|
1795
1982
|
```
|
|
@@ -1814,7 +2001,7 @@ instead of failing the step, and `null` when no fallback is given.
|
|
|
1814
2001
|
The fallback is the one-line default; `??` says the same:
|
|
1815
2002
|
|
|
1816
2003
|
```js
|
|
1817
|
-
api = env('API_URL', 'http://localhost:3000');
|
|
2004
|
+
let api = env('API_URL', 'http://localhost:3000');
|
|
1818
2005
|
api = env('API_URL') ?? 'http://localhost:3000';
|
|
1819
2006
|
```
|
|
1820
2007
|
|
|
@@ -1841,7 +2028,7 @@ download.
|
|
|
1841
2028
|
|
|
1842
2029
|
```js
|
|
1843
2030
|
step("Export is a PNG", () => {
|
|
1844
|
-
bytes = readFile('unotest/fixtures/files/image-3x2.png', {encoding: 'base64'});
|
|
2031
|
+
const bytes = readFile('unotest/fixtures/files/image-3x2.png', {encoding: 'base64'});
|
|
1845
2032
|
assertTrue(textContains(bytes, 'iVBORw0KGgo'), 'not a PNG signature');
|
|
1846
2033
|
});
|
|
1847
2034
|
```
|
|
@@ -1865,7 +2052,7 @@ The dimensions come from the PNG header, so a large image is not read.
|
|
|
1865
2052
|
|
|
1866
2053
|
```js
|
|
1867
2054
|
step("Fixture image is 3x2", () => {
|
|
1868
|
-
info = readFileInfo('unotest/fixtures/files/image-3x2.png');
|
|
2055
|
+
const info = readFileInfo('unotest/fixtures/files/image-3x2.png');
|
|
1869
2056
|
assertTrue(info.png.width == 3 && info.png.height == 2, 'size: ' + info.size);
|
|
1870
2057
|
});
|
|
1871
2058
|
```
|
|
@@ -1907,6 +2094,38 @@ step("The agent answered exactly once", () => {
|
|
|
1907
2094
|
Counting is per **line** (`grep -c` semantics), not per occurrence: two
|
|
1908
2095
|
matches on one line count once.
|
|
1909
2096
|
|
|
2097
|
+
### `assertFileHas(path, needle, options?)` / `assertFileLacks(path, needle, options?)`
|
|
2098
|
+
|
|
2099
|
+
A string or a regex must — or must not — appear in a file, or anywhere
|
|
2100
|
+
in a directory. The usual subject is what a run leaves behind: a secret
|
|
2101
|
+
must not reach a log or a database dump, while its ciphertext must.
|
|
2102
|
+
|
|
2103
|
+
```js
|
|
2104
|
+
step("The token is stored encrypted, never in plain text", () => {
|
|
2105
|
+
shell('sh', '-c', 'pg_dump app > tmp/dump.sql');
|
|
2106
|
+
assertFileLacks('tmp/dump.sql', API_TOKEN);
|
|
2107
|
+
assertFileLacks('logs', /sk-live-[0-9a-f]{24}/);
|
|
2108
|
+
assertFileHas('tmp/dump.sql', /v1:[A-Za-z0-9+\/=]{20,}/);
|
|
2109
|
+
});
|
|
2110
|
+
```
|
|
2111
|
+
|
|
2112
|
+
- `path` follows the rules of `readFile`: relative to `sandbox.shellCwd`,
|
|
2113
|
+
inside the project, the downloads dir or `sandbox.readRoots`. A
|
|
2114
|
+
directory is searched recursively; symlinks inside it are not followed.
|
|
2115
|
+
- A string `needle` is searched as **bytes**, so a binary file is
|
|
2116
|
+
searched too. A regex reads each file as UTF-8 text.
|
|
2117
|
+
- `assertFileHas` polls until the needle appears — `{timeoutMs}`, default
|
|
2118
|
+
20 s — and on a miss says how many files and bytes it searched, or
|
|
2119
|
+
that the path does not exist.
|
|
2120
|
+
- `assertFileLacks` searches **once**. `{withinMs}` watches a window
|
|
2121
|
+
instead and fails the moment the needle appears. A path that does not
|
|
2122
|
+
exist fails as well: nothing searched proves nothing absent.
|
|
2123
|
+
- A hit names the file and the line, with the line around it — the
|
|
2124
|
+
matched bytes themselves replaced by `‹match, N bytes›`, so a regex
|
|
2125
|
+
that catches an unregistered secret does not copy it into the report.
|
|
2126
|
+
The needle is quoted as written; a value from `unotest/.secrets` is
|
|
2127
|
+
masked in every report and log like anywhere else.
|
|
2128
|
+
|
|
1910
2129
|
### `dbQuery(sql, ...params)` → `rows[]`
|
|
1911
2130
|
|
|
1912
2131
|
Parameterized SELECT. Driver picked by URL scheme:
|
|
@@ -1916,7 +2135,7 @@ Parameterized SELECT. Driver picked by URL scheme:
|
|
|
1916
2135
|
- `sqlite:…` / `*.db` / `*.sqlite` — needs `better-sqlite3`
|
|
1917
2136
|
|
|
1918
2137
|
```js
|
|
1919
|
-
rows = dbQuery('select id from users where email = ?', 'a@b.c');
|
|
2138
|
+
const rows = dbQuery('select id from users where email = ?', 'a@b.c');
|
|
1920
2139
|
```
|
|
1921
2140
|
|
|
1922
2141
|
### `dbExec(sql, ...params)` → `number` (affected rows)
|
|
@@ -1933,18 +2152,18 @@ HTTP via global `fetch`. **`path` must be relative** (starts with `/`) —
|
|
|
1933
2152
|
absolute URLs throw to prevent scenarios from hitting arbitrary hosts.
|
|
1934
2153
|
|
|
1935
2154
|
```js
|
|
1936
|
-
res = apiCall('POST', '/auth/login', {email: 'a@b.c', password: 'x'});
|
|
2155
|
+
const res = apiCall('POST', '/auth/login', {email: 'a@b.c', password: 'x'});
|
|
1937
2156
|
assertTrue(res.status == 200, 'login failed');
|
|
1938
2157
|
```
|
|
1939
2158
|
|
|
1940
|
-
**Named API bases.** Without `
|
|
2159
|
+
**Named API bases.** Without `{base}` the path goes against
|
|
1941
2160
|
`sandbox.apiBaseUrl`. A setup that talks to more than one host names
|
|
1942
2161
|
the base per call — `{base: 'API_BASE_X'}` is the **name of a
|
|
1943
2162
|
variable** from `unotest/.env` (overlays apply as usual), never a URL:
|
|
1944
2163
|
|
|
1945
2164
|
```js
|
|
1946
2165
|
// unotest/.env: API_BASE_CHAT=https://chatbackend.example.com
|
|
1947
|
-
res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
|
|
2166
|
+
const res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
|
|
1948
2167
|
{base: 'API_BASE_CHAT'});
|
|
1949
2168
|
```
|
|
1950
2169
|
|
|
@@ -1973,11 +2192,26 @@ file the overlay was supposed to replace. The same rule covers
|
|
|
1973
2192
|
`APP_BASE_URL` (the base every relative `goto` resolves against) and a
|
|
1974
2193
|
variable used as the URL in `goto(NAME)`.
|
|
1975
2194
|
|
|
2195
|
+
**Per-call timeout — `{timeoutMs}`.** A call has no time limit of its
|
|
2196
|
+
own: it waits as long as the step and the test allow. An endpoint that
|
|
2197
|
+
must answer in a known time — or a slow one you would rather fail fast
|
|
2198
|
+
on — gets a budget for the whole call, the reply body included:
|
|
2199
|
+
|
|
2200
|
+
```js
|
|
2201
|
+
const res = apiCall('POST', '/live/start', {stand: 'a'}, null, {timeoutMs: 150000});
|
|
2202
|
+
```
|
|
2203
|
+
|
|
2204
|
+
Past the budget the request is aborted and the step fails as a timeout
|
|
2205
|
+
naming the call (`apiCall(POST /live/start) got no full reply within
|
|
2206
|
+
150000ms`), without the base or the query. The value is a positive
|
|
2207
|
+
number of milliseconds; `{timeout}` is not an alias here and is refused.
|
|
2208
|
+
It combines with `{base}` in the same object.
|
|
2209
|
+
|
|
1976
2210
|
**Multipart file upload — `upload(path, options?)`.** Passing the
|
|
1977
2211
|
result of `upload(...)` as the body posts `multipart/form-data`:
|
|
1978
2212
|
|
|
1979
2213
|
```js
|
|
1980
|
-
res = apiCall('POST', '/tenants/t1/documents',
|
|
2214
|
+
const res = apiCall('POST', '/tenants/t1/documents',
|
|
1981
2215
|
upload('fixtures/manual.pdf', {fields: {source: 'e2e'}}),
|
|
1982
2216
|
{Authorization: BEARER});
|
|
1983
2217
|
assertTrue(res.status == 202, 'ingestion not accepted');
|
|
@@ -2005,6 +2239,151 @@ assertTrue(res.status == 202, 'ingestion not accepted');
|
|
|
2005
2239
|
|
|
2006
2240
|
---
|
|
2007
2241
|
|
|
2242
|
+
## MCP client
|
|
2243
|
+
|
|
2244
|
+
A scenario can be the client of a stdio MCP server: start it, call its
|
|
2245
|
+
tools, wait for the notifications it sends. Every call, result and
|
|
2246
|
+
notification is a note in the run's journal, next to the browser steps,
|
|
2247
|
+
and a failing step quotes the server's last message — request, response
|
|
2248
|
+
or notification — in its error, so the failure bundle shows what the
|
|
2249
|
+
server said last.
|
|
2250
|
+
|
|
2251
|
+
```js
|
|
2252
|
+
function test_echo_notifies() {
|
|
2253
|
+
step('echo answers and notifies', () => {
|
|
2254
|
+
const srv = mcpStart('node', ['server.js'], {env: {API_TOKEN: API_TOKEN}});
|
|
2255
|
+
const res = mcpCall(srv, 'echo', {text: 'hi'});
|
|
2256
|
+
assertTrue(res.content[0].text == 'hi', 'echo answered something else');
|
|
2257
|
+
mcpWaitNotification(srv, 'notifications/message', {match: {'data.echoed': 'hi'}});
|
|
2258
|
+
});
|
|
2259
|
+
}
|
|
2260
|
+
```
|
|
2261
|
+
|
|
2262
|
+
A server the test leaves running is stopped when the test ends, passed
|
|
2263
|
+
or failed — a red step that never reached `mcpStop` leaves nothing
|
|
2264
|
+
behind.
|
|
2265
|
+
|
|
2266
|
+
### `mcpStart(command, args?, options?)` → server
|
|
2267
|
+
|
|
2268
|
+
Starts `command` with `args` (a list of strings) and finishes the MCP
|
|
2269
|
+
handshake. Returns the handle the other `mcp*` functions take.
|
|
2270
|
+
|
|
2271
|
+
- `env` — variables added to the environment the server inherits (the
|
|
2272
|
+
runner's own credentials are kept out of it, as for `shell()`). The
|
|
2273
|
+
journal names them, never their values.
|
|
2274
|
+
- `cwd` — relative to the project (`sandbox.shellCwd`), default the
|
|
2275
|
+
project itself.
|
|
2276
|
+
- `timeoutMs` — for the start and the handshake, default 30 s.
|
|
2277
|
+
|
|
2278
|
+
A server that does not come up — a missing command, an exit before the
|
|
2279
|
+
handshake — errors the test, with the tail of its stderr.
|
|
2280
|
+
|
|
2281
|
+
### `mcpCall(server, tool, args?, options?)` → `{content, structuredContent?, isError?}`
|
|
2282
|
+
|
|
2283
|
+
Calls `tool` with `args` (an object) and returns the result as the
|
|
2284
|
+
server sent it. These fail the step, quoting the last MCP message:
|
|
2285
|
+
|
|
2286
|
+
- a JSON-RPC error answer;
|
|
2287
|
+
- no answer within `timeoutMs` (default 30 s);
|
|
2288
|
+
- the server going away mid-call (its stderr tail is quoted);
|
|
2289
|
+
- a result marked `isError` — pass `{allowError: true}` to get it back
|
|
2290
|
+
and check it yourself.
|
|
2291
|
+
|
|
2292
|
+
### `mcpWaitNotification(server, method, options?)` → params
|
|
2293
|
+
|
|
2294
|
+
Waits for a notification of `method` and returns its `params`.
|
|
2295
|
+
Notifications are kept from the moment the server started and each one
|
|
2296
|
+
is handed out once, so the usual order — call, then wait for what the
|
|
2297
|
+
call set off — loses nothing even when the notification beats the
|
|
2298
|
+
response.
|
|
2299
|
+
|
|
2300
|
+
- `match` — scalars at dot paths of the params, as `waitForJsonLine`
|
|
2301
|
+
reads them: `{'data.status': 'done', 'level': 'info'}`.
|
|
2302
|
+
- `timeoutMs` — default 30 s. The failure names the notifications that
|
|
2303
|
+
did come and are still waiting to be taken.
|
|
2304
|
+
|
|
2305
|
+
### `mcpStop(server)`
|
|
2306
|
+
|
|
2307
|
+
Stops the server. Optional — see above.
|
|
2308
|
+
|
|
2309
|
+
---
|
|
2310
|
+
|
|
2311
|
+
## Virtual machines
|
|
2312
|
+
|
|
2313
|
+
A scenario can drive [Tart](https://tart.run) VMs: clone a ready image,
|
|
2314
|
+
boot it, reach it by its address — a clean machine to install on, per
|
|
2315
|
+
test. The image is yours, prepared once on the host; the scenario does
|
|
2316
|
+
not build it.
|
|
2317
|
+
|
|
2318
|
+
**Preparing the image, once.** A step that logs in to the VM over ssh
|
|
2319
|
+
(`openTerminal(app, {host})`) uses your key and never a password, and a
|
|
2320
|
+
clean Tart image takes only the password (`admin` / `admin`). Put your
|
|
2321
|
+
public key in the image before the first run:
|
|
2322
|
+
|
|
2323
|
+
```sh
|
|
2324
|
+
tart clone ghcr.io/cirruslabs/macos-sequoia-base:latest clean-mac
|
|
2325
|
+
tart run clean-mac & # boot it
|
|
2326
|
+
ssh-copy-id admin@"$(tart ip --wait 120 clean-mac)" # password: admin
|
|
2327
|
+
tart stop clean-mac # the image now holds the key
|
|
2328
|
+
```
|
|
2329
|
+
|
|
2330
|
+
Every VM `vmClone('clean-mac')` makes from then on holds it too. A key
|
|
2331
|
+
that is not the default one goes into your ssh agent (`ssh-add <key>`).
|
|
2332
|
+
Without it the step fails with `ssh could not reach or log in to …
|
|
2333
|
+
with a key (exit 255)` and these same three commands, `<image>` standing
|
|
2334
|
+
for your image: the VM the step reached is a clone the run deletes, so
|
|
2335
|
+
the key goes into the image. `ssh-copy-id` asks for the image's password
|
|
2336
|
+
(`admin` on Tart's images).
|
|
2337
|
+
|
|
2338
|
+
```js
|
|
2339
|
+
function test_install_on_clean_mac() {
|
|
2340
|
+
skip('no tart on this host', !vmAvailable());
|
|
2341
|
+
step('boot a clean mac', () => {
|
|
2342
|
+
const vm = vmClone('clean-mac');
|
|
2343
|
+
const ip = vmRun(vm);
|
|
2344
|
+
const res = shell('curl', '-fsS', `http://${ip}:8080/health`);
|
|
2345
|
+
assertTrue(res.stdout.includes('ok'), 'the service on the VM did not answer');
|
|
2346
|
+
});
|
|
2347
|
+
}
|
|
2348
|
+
```
|
|
2349
|
+
|
|
2350
|
+
The VMs are the test's. `vmClone` names each one `unotest-<id>-<n>`,
|
|
2351
|
+
the id random per test, so parallel runs never meet. Every VM the test
|
|
2352
|
+
cloned is stopped and deleted when it ends, passed or failed. The other
|
|
2353
|
+
`vm*` steps take only a name `vmClone` returned in this test: any other
|
|
2354
|
+
VM on the machine is refused, never stopped or deleted. Clone and boot
|
|
2355
|
+
are notes in the run's journal, with the VM's name and the run.
|
|
2356
|
+
|
|
2357
|
+
### `vmAvailable()` → `boolean`
|
|
2358
|
+
|
|
2359
|
+
Whether VMs can run here: Tart is installed and answers. `false`, not an
|
|
2360
|
+
error, where it is missing — guard a VM test with `skip`.
|
|
2361
|
+
|
|
2362
|
+
### `vmClone(image)` → name
|
|
2363
|
+
|
|
2364
|
+
A new VM from `image` — a local Tart VM or an OCI reference. Returns its
|
|
2365
|
+
name for the other `vm*` steps.
|
|
2366
|
+
|
|
2367
|
+
### `vmRun(name, options?)` → ip
|
|
2368
|
+
|
|
2369
|
+
Boots the VM without a window and waits for its address.
|
|
2370
|
+
|
|
2371
|
+
- `timeoutMs` — default 180 s, about what a macOS guest needs.
|
|
2372
|
+
|
|
2373
|
+
A boot that fails errors the step at once with Tart's output, without
|
|
2374
|
+
waiting the timeout out.
|
|
2375
|
+
|
|
2376
|
+
### `vmIp(name, options?)` → ip
|
|
2377
|
+
|
|
2378
|
+
The address of a running VM. `timeoutMs` — default 60 s.
|
|
2379
|
+
|
|
2380
|
+
### `vmStop(name)` / `vmDelete(name)`
|
|
2381
|
+
|
|
2382
|
+
Stop the VM; delete it, stopping it first if it runs. Both optional —
|
|
2383
|
+
see above.
|
|
2384
|
+
|
|
2385
|
+
---
|
|
2386
|
+
|
|
2008
2387
|
## Network mocks
|
|
2009
2388
|
|
|
2010
2389
|
What the page's requests get, for the rest of the scenario: a fixed
|
|
@@ -2039,7 +2418,10 @@ mockRoute('**/ads/**', { abort: true });
|
|
|
2039
2418
|
navigation to your site still loads. Only the document: its scripts,
|
|
2040
2419
|
styles, images and API calls are ordinary requests, and an abort mask
|
|
2041
2420
|
that matches them stops them.
|
|
2042
|
-
- A mask reaches
|
|
2421
|
+
- A mask reaches http(s) requests only. A WebSocket is no request: no
|
|
2422
|
+
mask reaches it, wait for one with
|
|
2423
|
+
[`waitForWebSocket`](#waitforwebsocketglob-options--url), and a
|
|
2424
|
+
`ws://` or `wss://` mask is named with a warning. An extension's
|
|
2043
2425
|
own pages and scripts (`chrome-extension://`) load under `**/*`, so
|
|
2044
2426
|
a network allowlist does not leave its UI dead. To mock one of them,
|
|
2045
2427
|
start the mask with its scheme: `chrome-extension://<id>/panel.js`.
|
|
@@ -2070,7 +2452,7 @@ JSON (null when it is not JSON).
|
|
|
2070
2452
|
```js
|
|
2071
2453
|
mockRoute('**/api/messages', { body: { ok: true } });
|
|
2072
2454
|
click(getByRole('button', { name: 'Send' }));
|
|
2073
|
-
req = waitForRequest('**/api/messages');
|
|
2455
|
+
const req = waitForRequest('**/api/messages');
|
|
2074
2456
|
assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
|
|
2075
2457
|
```
|
|
2076
2458
|
|
|
@@ -2079,6 +2461,28 @@ assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
|
|
|
2079
2461
|
On any other mask only requests from the call on count — to catch one
|
|
2080
2462
|
the previous step sent, mock the mask with `{continue: true}` first.
|
|
2081
2463
|
- `{timeoutMs}` — default 20 000.
|
|
2464
|
+
- A `ws://` or `wss://` mask is refused: a WebSocket is no request.
|
|
2465
|
+
|
|
2466
|
+
### `waitForWebSocket(glob, options?)` → `{url}`
|
|
2467
|
+
|
|
2468
|
+
Waits until the active page has opened a WebSocket whose URL matches
|
|
2469
|
+
`glob` and returns its URL. The mask is a Playwright URL glob, as for
|
|
2470
|
+
`mockRoute`; one starting with `/` is a path on your site
|
|
2471
|
+
(`/live` → `ws://<host>/live`, `wss://` for an `https` site).
|
|
2472
|
+
|
|
2473
|
+
```js
|
|
2474
|
+
goto('/chat');
|
|
2475
|
+
const socket = waitForWebSocket('**/ws');
|
|
2476
|
+
assertTrue(socket.url.endsWith('/ws'));
|
|
2477
|
+
```
|
|
2478
|
+
|
|
2479
|
+
- A socket opened before the call counts, from the page's last load on:
|
|
2480
|
+
a page that connects as it loads has done so by the time the step
|
|
2481
|
+
asks. A new document starts the list again; a single-page app moving
|
|
2482
|
+
between its routes does not.
|
|
2483
|
+
- Two waits on one mask find the same socket.
|
|
2484
|
+
- A timeout names the mask and the sockets the page did open.
|
|
2485
|
+
- `{timeoutMs}` — default 20 000.
|
|
2082
2486
|
|
|
2083
2487
|
### `assertNoRequest(glob, options?)`
|
|
2084
2488
|
|
|
@@ -2100,6 +2504,116 @@ assertNoRequest('**/*');
|
|
|
2100
2504
|
|
|
2101
2505
|
---
|
|
2102
2506
|
|
|
2507
|
+
## Terminal (macOS)
|
|
2508
|
+
|
|
2509
|
+
A real terminal window: Terminal.app or iTerm2, driven by real key
|
|
2510
|
+
events, read as screen text, framed as a picture. For a CLI or a TUI
|
|
2511
|
+
(an agent in a terminal, an installer, a `--watch` mode) the bugs a
|
|
2512
|
+
pseudo-terminal hides live here: a key the terminal encodes itself
|
|
2513
|
+
(Shift+Enter under the kitty keyboard protocol), the window's width, the
|
|
2514
|
+
`PATH` of the shell the user actually has.
|
|
2515
|
+
|
|
2516
|
+
The verbs are the page's ones with a `terminal` prefix:
|
|
2517
|
+
`terminalType`, `terminalPress`, `terminalWaitForText`,
|
|
2518
|
+
`terminalAssertText`, `terminalScreenshot`. The bare names act on the
|
|
2519
|
+
page, and a test can drive both.
|
|
2520
|
+
|
|
2521
|
+
```js
|
|
2522
|
+
step("The CLI answers in a real terminal", () => {
|
|
2523
|
+
openTerminal('Terminal');
|
|
2524
|
+
terminalResize(100, 30);
|
|
2525
|
+
terminalType('my-cli --version');
|
|
2526
|
+
terminalPress('Enter');
|
|
2527
|
+
terminalWaitForText(/my-cli \d+\.\d+/);
|
|
2528
|
+
});
|
|
2529
|
+
```
|
|
2530
|
+
|
|
2531
|
+
Every step lands in the run's report like a page step, without a frame
|
|
2532
|
+
of the terminal per step: frames are taken by `terminalScreenshot()`
|
|
2533
|
+
and on failure. A failed test
|
|
2534
|
+
keeps the active window in the failure bundle: `terminal.png` (its last
|
|
2535
|
+
frame), `terminal.txt` (its screen text, secrets redacted) and
|
|
2536
|
+
`terminal.json` (which app, on which host).
|
|
2537
|
+
|
|
2538
|
+
**Where it runs.** macOS, through `osascript` and `screencapture`.
|
|
2539
|
+
|
|
2540
|
+
- On this Mac, the default. macOS asks once to let the app the run starts
|
|
2541
|
+
from (Terminal, iTerm2, your editor) control the computer and record
|
|
2542
|
+
the screen. While the test types, **it has the keyboard**: keys go to
|
|
2543
|
+
the terminal window only while it is in front, and a step fails rather
|
|
2544
|
+
than type into a window that took the focus. Leave the machine alone,
|
|
2545
|
+
or run it in a VM.
|
|
2546
|
+
- On another Mac, a Tart VM: `openTerminal('Terminal', {host:
|
|
2547
|
+
'admin@192.168.64.38'})`. The run reaches it over ssh with your key
|
|
2548
|
+
(ssh agent or `~/.ssh`; a password is never passed) and drives the
|
|
2549
|
+
terminal through a small controller it starts in the logged-in session
|
|
2550
|
+
there — macOS gives an ssh session itself no control of the screen.
|
|
2551
|
+
A VM just booted by `vmRun` answers ssh before its automatic login
|
|
2552
|
+
is done: the run waits up to 90 s for that session, and an image that
|
|
2553
|
+
logs no one in fails the step saying so.
|
|
2554
|
+
A clean Tart macOS image needs no extra permission for Terminal.app,
|
|
2555
|
+
but it needs your key once: see
|
|
2556
|
+
[Preparing the image](#virtual-machines).
|
|
2557
|
+
- A Linux terminal is not driven yet.
|
|
2558
|
+
|
|
2559
|
+
### `openTerminal(app, options?)` → `number`
|
|
2560
|
+
|
|
2561
|
+
Opens a window of `'Terminal'` or `'iTerm2'` with a login shell, makes it
|
|
2562
|
+
active, returns its index. Options: `{host: 'user@address'}` — the Mac to
|
|
2563
|
+
open it on. Every window the test opened closes when it ends, green or
|
|
2564
|
+
red; its shell and what runs in it are stopped.
|
|
2565
|
+
|
|
2566
|
+
### `setTerminal(index)` / `closeTerminal()`
|
|
2567
|
+
|
|
2568
|
+
`setTerminal` moves the terminal steps to another window, as `setContext`
|
|
2569
|
+
does for browser contexts; indices stay put when a window closes.
|
|
2570
|
+
`closeTerminal` closes the active one.
|
|
2571
|
+
|
|
2572
|
+
### `terminalType(text)` / `terminalPress(key)`
|
|
2573
|
+
|
|
2574
|
+
`terminalType` puts the text in as a paste, line by line: a line goes on
|
|
2575
|
+
the clipboard, then ⌘V, and a line break presses Return. The Mac's
|
|
2576
|
+
keyboard layout does not change what arrives — Cyrillic and emoji
|
|
2577
|
+
included — and the clipboard holds what you copied again when the step
|
|
2578
|
+
ends. A program in the terminal sees a paste, not typing: a TUI that
|
|
2579
|
+
turned bracketed paste on gets the text as one paste.
|
|
2580
|
+
|
|
2581
|
+
Each line must show on the screen within 2 s, or the step fails and its
|
|
2582
|
+
message ends with the screen's last rows — what arrived instead. Input a
|
|
2583
|
+
program does not echo goes with `{echo: false}`:
|
|
2584
|
+
|
|
2585
|
+
```js
|
|
2586
|
+
terminalWaitForText('Password:');
|
|
2587
|
+
terminalType(env('ADMIN_PASSWORD'), {echo: false});
|
|
2588
|
+
terminalPress('Enter');
|
|
2589
|
+
```
|
|
2590
|
+
|
|
2591
|
+
`terminalPress` presses one key with modifiers, spelled as `press()`
|
|
2592
|
+
spells them: `'Enter'`, `'Shift+Enter'`, `'Control+]'`, `'Escape'`,
|
|
2593
|
+
`'ArrowUp'`, `'F5'`, a single character. Modifiers: `Shift`, `Control`,
|
|
2594
|
+
`Alt`, `Meta`. A character held with a modifier (`'Control+c'`) presses
|
|
2595
|
+
that key of a US keyboard, whatever the layout; a character with no key
|
|
2596
|
+
of its own there names the key it is on (`'Control+Shift+='`, not
|
|
2597
|
+
`'Control++'`). A single character alone is pasted, as `terminalType`
|
|
2598
|
+
does it, without the wait for the echo: a shell prompt (`y/n`) takes it
|
|
2599
|
+
as the key, while a TUI with bracketed paste on (vim in normal mode)
|
|
2600
|
+
sees a paste.
|
|
2601
|
+
|
|
2602
|
+
### `terminalWaitForText(text, options?)` / `terminalAssertText(text, options?)`
|
|
2603
|
+
|
|
2604
|
+
The screen is the window's visible text, rows without their padding. A
|
|
2605
|
+
string matches anywhere on it, a `/regex/` is tested against it.
|
|
2606
|
+
`{not: true}` waits for the text to go. `terminalWaitForText` waits up to
|
|
2607
|
+
30 s, `terminalAssertText` 5000 ms; `{timeoutMs}` sets either.
|
|
2608
|
+
|
|
2609
|
+
### `terminalResize(cols, rows)`
|
|
2610
|
+
|
|
2611
|
+
Resizes the active window to `cols` × `rows` character cells.
|
|
2612
|
+
|
|
2613
|
+
### `terminalScreenshot(name?)` → `string`
|
|
2614
|
+
|
|
2615
|
+
A PNG of the active window, saved with the run like `screenshot()`.
|
|
2616
|
+
|
|
2103
2617
|
## Typed getters
|
|
2104
2618
|
|
|
2105
2619
|
Read page properties directly into a local variable.
|
|
@@ -2107,7 +2621,7 @@ Read page properties directly into a local variable.
|
|
|
2107
2621
|
### `getAttribute(loc, name)` → `string`
|
|
2108
2622
|
|
|
2109
2623
|
```js
|
|
2110
|
-
href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
|
|
2624
|
+
const href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
|
|
2111
2625
|
```
|
|
2112
2626
|
|
|
2113
2627
|
Returns `""` when the attribute is missing — which makes it **blind to
|
|
@@ -2133,7 +2647,7 @@ Where the element lies in the viewport, CSS pixels. `null` when it is
|
|
|
2133
2647
|
not rendered (`display:none`, detached). Does not scroll it into view.
|
|
2134
2648
|
|
|
2135
2649
|
```js
|
|
2136
|
-
box = boundingBox(getByRole('dialog'));
|
|
2650
|
+
const box = boundingBox(getByRole('dialog'));
|
|
2137
2651
|
assertTrue(box.width <= 480, json(box));
|
|
2138
2652
|
```
|
|
2139
2653
|
|
|
@@ -2147,7 +2661,7 @@ not set reads `""`. A missing or ambiguous element fails as
|
|
|
2147
2661
|
|
|
2148
2662
|
```js
|
|
2149
2663
|
assertTrue(computedStyle(getByRole('dialog'), 'opacity') == 1, 'dialog is faded');
|
|
2150
|
-
accent = computedStyle(locator('body'), '--accent');
|
|
2664
|
+
const accent = computedStyle(locator('body'), '--accent');
|
|
2151
2665
|
```
|
|
2152
2666
|
|
|
2153
2667
|
### `getImageSize(loc)` → `{width, height}` | `null`
|
|
@@ -2168,7 +2682,7 @@ image is never read too early as broken.
|
|
|
2168
2682
|
numbers.
|
|
2169
2683
|
|
|
2170
2684
|
```js
|
|
2171
|
-
size = getImageSize(getByRole('img', {name: 'Avatar'}));
|
|
2685
|
+
const size = getImageSize(getByRole('img', {name: 'Avatar'}));
|
|
2172
2686
|
assertTrue(size !== null, 'avatar is broken');
|
|
2173
2687
|
assertTrue(size.width >= 256, json(size));
|
|
2174
2688
|
```
|
|
@@ -2183,6 +2697,28 @@ the rule `waitForAnimations` waits by.
|
|
|
2183
2697
|
assertTrue(hasAnimation(getByRole('dialog')) === false, 'dialog still moving');
|
|
2184
2698
|
```
|
|
2185
2699
|
|
|
2700
|
+
### `animations(loc)` → `[{name, kind, playState, currentTime?, infinite}]`
|
|
2701
|
+
|
|
2702
|
+
Every animation of the element and its descendants, as the page has
|
|
2703
|
+
them now. The typed read instead of `getAnimations()` through
|
|
2704
|
+
`evaluateOnLocator`.
|
|
2705
|
+
|
|
2706
|
+
- `name` — the `@keyframes` name, the property a transition moves, or a
|
|
2707
|
+
script animation's `id`.
|
|
2708
|
+
- `kind` — `'animation'`, `'transition'` or `'script'`.
|
|
2709
|
+
- `playState` — `'running'`, `'paused'`, `'finished'` or `'idle'`.
|
|
2710
|
+
- `currentTime` — milliseconds into it; left out when it has no time.
|
|
2711
|
+
- `infinite` — `true` for one that repeats forever (a spinner).
|
|
2712
|
+
|
|
2713
|
+
Infinite and paused animations are listed too. `hasAnimation` counts
|
|
2714
|
+
only those with `playState: 'running'` and `infinite: false`.
|
|
2715
|
+
|
|
2716
|
+
```js
|
|
2717
|
+
const list = animations(getByTestId('status'));
|
|
2718
|
+
const pulse = list.find((a) => a.name == 'pulse');
|
|
2719
|
+
assertTrue(pulse !== undefined && pulse.playState == 'running', json(list));
|
|
2720
|
+
```
|
|
2721
|
+
|
|
2186
2722
|
### `getTitle()` → `string`
|
|
2187
2723
|
|
|
2188
2724
|
Active page title.
|
|
@@ -2220,7 +2756,7 @@ Random lowercase letters, default 8 — digit-free unique markers for apps
|
|
|
2220
2756
|
whose content filters reject numbers in text.
|
|
2221
2757
|
|
|
2222
2758
|
```js
|
|
2223
|
-
marker = randomWord(10);
|
|
2759
|
+
const marker = randomWord(10);
|
|
2224
2760
|
fill(getByRole('textbox'), textJoin(['ping ', marker]));
|
|
2225
2761
|
waitForText(marker);
|
|
2226
2762
|
```
|
|
@@ -2231,7 +2767,7 @@ Substring probe for data that came back as a string — shell stdout,
|
|
|
2231
2767
|
apiCall bodies. The read-side counterpart of `textJoin`.
|
|
2232
2768
|
|
|
2233
2769
|
```js
|
|
2234
|
-
out = shell('./status.sh');
|
|
2770
|
+
const out = shell('./status.sh');
|
|
2235
2771
|
assertTrue(textContains(out.stdout, 'ready'), out.stderr);
|
|
2236
2772
|
```
|
|
2237
2773
|
|
|
@@ -2243,9 +2779,9 @@ took no part in the match is `null`. The array is truthy, so the call
|
|
|
2243
2779
|
also works as a test.
|
|
2244
2780
|
|
|
2245
2781
|
```js
|
|
2246
|
-
m = textMatches(getUrl(), /room=(\d+)/);
|
|
2782
|
+
const m = textMatches(getUrl(), /room=(\d+)/);
|
|
2247
2783
|
assertTrue(m, getUrl());
|
|
2248
|
-
roomId = m[1];
|
|
2784
|
+
const roomId = m[1];
|
|
2249
2785
|
```
|
|
2250
2786
|
|
|
2251
2787
|
A string pattern is refused: for a plain substring use `textContains`.
|
|
@@ -2259,7 +2795,7 @@ setting. Invalid JSON fails the step and quotes the input; an empty
|
|
|
2259
2795
|
string is not JSON.
|
|
2260
2796
|
|
|
2261
2797
|
```js
|
|
2262
|
-
saved = parseJson(getLocalStorage('messages'));
|
|
2798
|
+
const saved = parseJson(getLocalStorage('messages'));
|
|
2263
2799
|
assertEqual(saved[0].type, 'hello');
|
|
2264
2800
|
```
|
|
2265
2801
|
|
|
@@ -2269,7 +2805,7 @@ A query parameter, decoded. `null` when the key is absent, `''` when it
|
|
|
2269
2805
|
is present but empty. A path without a host (`/room?id=7`) works too.
|
|
2270
2806
|
|
|
2271
2807
|
```js
|
|
2272
|
-
src = getAttribute(locator('iframe#chat'), 'src');
|
|
2808
|
+
const src = getAttribute(locator('iframe#chat'), 'src');
|
|
2273
2809
|
assertEqual(urlParam(src, 'roomId'), 'r-7');
|
|
2274
2810
|
```
|
|
2275
2811
|
|
|
@@ -2293,9 +2829,9 @@ A number as a page writes it, for arithmetic and comparison. What
|
|
|
2293
2829
|
- A number passes through unchanged.
|
|
2294
2830
|
|
|
2295
2831
|
```js
|
|
2296
|
-
total = toNumber(getInnerText(getByTestId('total'))); // "1 234,50"
|
|
2832
|
+
const total = toNumber(getInnerText(getByTestId('total'))); // "1 234,50"
|
|
2297
2833
|
assertTrue(total > 1000, 'total: ' + total);
|
|
2298
|
-
width = toNumber(textMatches(computedStyle(phone, '--phone-w'), /(\d+)px/)[1]);
|
|
2834
|
+
const width = toNumber(textMatches(computedStyle(phone, '--phone-w'), /(\d+)px/)[1]);
|
|
2299
2835
|
```
|
|
2300
2836
|
|
|
2301
2837
|
### `round(n, digits?)` → `number`
|
|
@@ -2306,7 +2842,7 @@ zero, on the decimal as written: `round(2.5)` is 3, `round(-2.5)` is
|
|
|
2306
2842
|
`toNumber` first.
|
|
2307
2843
|
|
|
2308
2844
|
```js
|
|
2309
|
-
payout = round(stake * odds, 2);
|
|
2845
|
+
const payout = round(stake * odds, 2);
|
|
2310
2846
|
```
|
|
2311
2847
|
|
|
2312
2848
|
### `formatNumber(n, options?)` → `string`
|
|
@@ -2335,7 +2871,7 @@ steps: an object concatenated with `+` collapses into
|
|
|
2335
2871
|
body that explained it.
|
|
2336
2872
|
|
|
2337
2873
|
```js
|
|
2338
|
-
res = apiCall('POST', '/documents', upload('fixtures/doc.pdf'));
|
|
2874
|
+
const res = apiCall('POST', '/documents', upload('fixtures/doc.pdf'));
|
|
2339
2875
|
assertTrue(res.status == 202, json(res.body));
|
|
2340
2876
|
```
|
|
2341
2877
|
|
|
@@ -2379,7 +2915,7 @@ written, the way Playwright sends `fn.toString()`: the page sees none of
|
|
|
2379
2915
|
the scenario's variables, only the arguments after it.
|
|
2380
2916
|
|
|
2381
2917
|
```js
|
|
2382
|
-
height = evaluate(() => document.documentElement.scrollHeight);
|
|
2918
|
+
let height = evaluate(() => document.documentElement.scrollHeight);
|
|
2383
2919
|
height = evaluate(`document.documentElement.scrollHeight`); // the string form
|
|
2384
2920
|
```
|
|
2385
2921
|
|
|
@@ -2389,8 +2925,8 @@ destructures. So one argument is `function(x)`, not `function([x])` —
|
|
|
2389
2925
|
that one fails with `2 is not iterable`.
|
|
2390
2926
|
|
|
2391
2927
|
```js
|
|
2392
|
-
doubled = evaluate((n) => n * 2, 21); // one → the value
|
|
2393
|
-
result = evaluate(
|
|
2928
|
+
const doubled = evaluate((n) => n * 2, 21); // one → the value
|
|
2929
|
+
const result = evaluate(
|
|
2394
2930
|
([a, b]) => window.myApp.compute(a, b),
|
|
2395
2931
|
10, 20 // two → one array
|
|
2396
2932
|
);
|
|
@@ -2408,6 +2944,15 @@ to the page reads only its own parameters
|
|
|
2408
2944
|
run checks both rules before it starts, in the test and in every helper
|
|
2409
2945
|
of `_helpers/` it loads, and stops on them.
|
|
2410
2946
|
|
|
2947
|
+
The validator reads a function literal with the file: its syntax, and
|
|
2948
|
+
the scenario names it must not read. A string the source spells out (a
|
|
2949
|
+
literal, or a template without `${…}`) is parsed only as one JavaScript
|
|
2950
|
+
expression: a syntax error is reported with its line and column inside
|
|
2951
|
+
the string (`validator:page-code-syntax`), and the run refuses the step.
|
|
2952
|
+
A string that parses gets an info with the rewrite to a function
|
|
2953
|
+
(`validator:page-code-string`). Text built with `+` or held in a
|
|
2954
|
+
variable is not parsed at all.
|
|
2955
|
+
|
|
2411
2956
|
A page whose main thread is busy — a script loop, a long task — cannot
|
|
2412
2957
|
start the script. `evaluate` then fails the step after the action timeout
|
|
2413
2958
|
(the config's `defaultTimeoutMs`) with `the page gave no answer` instead
|
|
@@ -2420,7 +2965,7 @@ The body gets the element first, then the extras by the same rule as
|
|
|
2420
2965
|
array.
|
|
2421
2966
|
|
|
2422
2967
|
```js
|
|
2423
|
-
ok = evaluateOnLocator(getByRole('main'), (el, [a, b]) => el.children.length > a + b, 1, 2);
|
|
2968
|
+
const ok = evaluateOnLocator(getByRole('main'), (el, [a, b]) => el.children.length > a + b, 1, 2);
|
|
2424
2969
|
```
|
|
2425
2970
|
|
|
2426
2971
|
Reach for it only for what no typed call reads — a style is
|
|
@@ -2430,7 +2975,7 @@ why it uses the hatch, and the linter takes the reason:
|
|
|
2430
2975
|
|
|
2431
2976
|
```js
|
|
2432
2977
|
// Truncated with an ellipsis: the content is wider than the cell.
|
|
2433
|
-
overflows = evaluateOnLocator(getByRole('cell', {name: /^R-00001/}), `(el) => el.scrollWidth > el.clientWidth`); // lint-ok: no typed getter reads scrollWidth
|
|
2978
|
+
const overflows = evaluateOnLocator(getByRole('cell', {name: /^R-00001/}), `(el) => el.scrollWidth > el.clientWidth`); // lint-ok: no typed getter reads scrollWidth
|
|
2434
2979
|
assertTrue(overflows === false, 'the id is cut off');
|
|
2435
2980
|
```
|
|
2436
2981
|
|
|
@@ -2457,7 +3002,7 @@ screenshot('landing', {fullPage: true}); // full scroll height
|
|
|
2457
3002
|
names its evidence after the case it is on:
|
|
2458
3003
|
|
|
2459
3004
|
```js
|
|
2460
|
-
q = waitForJsonLine('questions.jsonl', {slot: 3});
|
|
3005
|
+
const q = waitForJsonLine('questions.jsonl', {slot: 3});
|
|
2461
3006
|
screenshot(q.id); // 003-q-17.png
|
|
2462
3007
|
screenshot(textJoin(['q-', q.id, '-answer']));
|
|
2463
3008
|
```
|
|
@@ -2493,10 +3038,10 @@ page like any other.
|
|
|
2493
3038
|
|
|
2494
3039
|
```js
|
|
2495
3040
|
click(getByRole('button', { name: 'Save' }));
|
|
2496
|
-
errors = consoleEntries({ level: 'error' });
|
|
3041
|
+
const errors = consoleEntries({ level: 'error' });
|
|
2497
3042
|
assertTrue(errors.length == 0, json(errors));
|
|
2498
3043
|
|
|
2499
|
-
before = nowMs();
|
|
3044
|
+
const before = nowMs();
|
|
2500
3045
|
click(getByRole('button', { name: 'Retry' }));
|
|
2501
3046
|
assertTrue(consoleEntries({ level: ['warn', 'error'], since: before }).length == 1, 'one complaint');
|
|
2502
3047
|
```
|
|
@@ -2519,7 +3064,7 @@ is empty when the browser gave none. The last 100 are kept.
|
|
|
2519
3064
|
|
|
2520
3065
|
```js
|
|
2521
3066
|
click(getByRole('button', { name: 'Load' }));
|
|
2522
|
-
thrown = pageErrors();
|
|
3067
|
+
const thrown = pageErrors();
|
|
2523
3068
|
assertTrue(thrown.length == 0, json(thrown));
|
|
2524
3069
|
```
|
|
2525
3070
|
|
|
@@ -2569,7 +3114,7 @@ step.soft("Question", {tag: q.id}, () => {
|
|
|
2569
3114
|
note('question', q.text);
|
|
2570
3115
|
fill(getByRole('textbox', {name: 'Message'}), q.text);
|
|
2571
3116
|
press(getByRole('textbox', {name: 'Message'}), 'Enter');
|
|
2572
|
-
answer = textContent(getByTestId('last-answer'));
|
|
3117
|
+
const answer = textContent(getByTestId('last-answer'));
|
|
2573
3118
|
note('answer', answer);
|
|
2574
3119
|
assertJudge(getByTestId('last-answer'), q.rubric);
|
|
2575
3120
|
});
|
|
@@ -2597,28 +3142,251 @@ step.soft("Question", {tag: q.id}, () => {
|
|
|
2597
3142
|
|
|
2598
3143
|
---
|
|
2599
3144
|
|
|
3145
|
+
## Signatures
|
|
3146
|
+
|
|
3147
|
+
Every function with the types it takes, read from the same contract the
|
|
3148
|
+
linter and the run check a call against: a call these lines refuse is
|
|
3149
|
+
refused before the run and at the call. Each options object lists one key
|
|
3150
|
+
per option; an older spelling it still takes is named after the line.
|
|
3151
|
+
|
|
3152
|
+
<!-- generated:signatures — pnpm build:dsl-types writes this from the contracts -->
|
|
3153
|
+
**Navigation**
|
|
3154
|
+
|
|
3155
|
+
- `goto(url: string, options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3156
|
+
- `reload(options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3157
|
+
- `goBack(options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3158
|
+
- `goForward(options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3159
|
+
- `waitForUrl(pattern: string | RegExp, options?: { waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3160
|
+
- `waitForNavigation(options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3161
|
+
|
|
3162
|
+
**Locators**
|
|
3163
|
+
|
|
3164
|
+
- `locator(selector: string, options?: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator`
|
|
3165
|
+
- `getByRole(role: string, options?: { name?: string | RegExp; exact?: boolean; checked?: boolean; disabled?: boolean; expanded?: boolean; includeHidden?: boolean; level?: number; pressed?: boolean; selected?: boolean }): Locator`
|
|
3166
|
+
- `getByText(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3167
|
+
- `getByLabel(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3168
|
+
- `getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3169
|
+
- `getByAltText(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3170
|
+
- `getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator`
|
|
3171
|
+
- `getByTestId(id: string): Locator`
|
|
3172
|
+
- `contentFrame(frame?: Locator): Locator`
|
|
3173
|
+
|
|
3174
|
+
**Refining a locator**
|
|
3175
|
+
|
|
3176
|
+
- `filter(receiver: Locator, options: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator`
|
|
3177
|
+
- `first(receiver: Locator): Locator`
|
|
3178
|
+
- `last(receiver: Locator): Locator`
|
|
3179
|
+
- `nth(receiver: Locator, index: number): Locator`
|
|
3180
|
+
- `randomNth(receiver: Locator): Locator`
|
|
3181
|
+
|
|
3182
|
+
**Actions**
|
|
3183
|
+
|
|
3184
|
+
- `click(locator: Locator, options?: { force?: boolean; position?: any; modifiers?: unknown[]; button?: any; clickCount?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3185
|
+
- `doubleClick(locator: Locator, options?: { force?: boolean; position?: any; modifiers?: unknown[]; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3186
|
+
- `check(locator: Locator, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3187
|
+
- `uncheck(locator: Locator, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3188
|
+
- `hover(locator: Locator, options?: { force?: boolean; position?: any; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3189
|
+
- `scrollIntoView(locator: Locator): void`
|
|
3190
|
+
- `fill(locator: Locator, text: string, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3191
|
+
- `press(locator: Locator, key: string, options?: { delay?: number; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3192
|
+
- `selectOption(locator: Locator, value: string | string[] | { value?: string; label?: string; index?: number }, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3193
|
+
- `dragAndDrop(source: Locator, target: Locator, options?: { force?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3194
|
+
- `uploadFile(input: Locator, files: any): void`
|
|
3195
|
+
- `clipboardPaste(target: Locator, text: string): void`
|
|
3196
|
+
|
|
3197
|
+
**Waits and the page clock**
|
|
3198
|
+
|
|
3199
|
+
- `waitFor(locator: Locator, options?: { state?: string; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3200
|
+
- `waitForText(text: string | RegExp, options?: { state?: string; exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3201
|
+
- `waitForCount(locator: Locator, count: number, options?: { exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3202
|
+
- `waitForAnimations(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3203
|
+
- `pause(ms: number): void`
|
|
3204
|
+
- `waitForDownload(options?: { timeoutMs?: number; name?: string | RegExp }): any`
|
|
3205
|
+
- `clockFreeze(iso: string): void`
|
|
3206
|
+
- `clockTick(ms: number): void`
|
|
3207
|
+
- `clockRun(): void`
|
|
3208
|
+
|
|
3209
|
+
**Assertions**
|
|
3210
|
+
|
|
3211
|
+
- `assertText(locator: Locator, text: string | RegExp, options?: { exact?: boolean; not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3212
|
+
- `assertTexts(locator: Locator, expected: unknown[], options?: { exact?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3213
|
+
- `assertAttribute(locator: Locator, name: string, value: string | RegExp, options?: { exact?: boolean; not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3214
|
+
- `assertVisible(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3215
|
+
- `assertHidden(locator: Locator, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3216
|
+
- `assertNeverAppears(locator: Locator, options: { withinMs?: number }): void`
|
|
3217
|
+
- `assertValue(locator: Locator, value: string, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3218
|
+
- `assertCount(locator: Locator, count: number, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3219
|
+
- `assertUrl(pattern: string | RegExp, options?: { timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3220
|
+
- `assertJudge(locator: Locator, rubric: string): void`
|
|
3221
|
+
- `assertScreenshot(nameOrLocator: any, nameOrOptions?: any, options?: { maxDiffRatio?: number; threshold?: number; mask?: unknown[]; ignore?: unknown[]; fullPage?: boolean }): void`
|
|
3222
|
+
- `assertEqual(actual: any, expected: any): void`
|
|
3223
|
+
- `assertTrue(condition: boolean, message?: string): void`
|
|
3224
|
+
- `assertSchema(value: any, schema: any): void`
|
|
3225
|
+
- `assertFileHas(path: string, needle: string | RegExp, options?: { timeoutMs?: number }): void`
|
|
3226
|
+
- `assertFileLacks(path: string, needle: string | RegExp, options?: { withinMs?: number }): void`
|
|
3227
|
+
- `skip(reason: string, condition?: boolean): void`
|
|
3228
|
+
- `setTestTimeout(ms: number): void`
|
|
3229
|
+
|
|
3230
|
+
**Reading the page and values**
|
|
3231
|
+
|
|
3232
|
+
- `clipboardRead(): string`
|
|
3233
|
+
- `assertClipboard(expected: string | RegExp, options?: { timeoutMs?: number }): void`
|
|
3234
|
+
- `count(locator: Locator): number`
|
|
3235
|
+
- `textContent(locator: Locator): string`
|
|
3236
|
+
- `texts(locator: Locator): any`
|
|
3237
|
+
- `inputValue(locator: Locator): string`
|
|
3238
|
+
- `isVisible(locator: Locator): boolean`
|
|
3239
|
+
- `isChecked(locator: Locator): boolean`
|
|
3240
|
+
- `isDisabled(locator: Locator): boolean`
|
|
3241
|
+
- `isEnabled(locator: Locator): boolean`
|
|
3242
|
+
- `hasAttribute(locator: Locator, name: string): boolean`
|
|
3243
|
+
- `computedStyle(locator: Locator, property: string): string`
|
|
3244
|
+
- `getImageSize(locator: Locator): any`
|
|
3245
|
+
- `hasAnimation(locator: Locator): boolean`
|
|
3246
|
+
- `animations(locator: Locator): any`
|
|
3247
|
+
- `randomFirstName(): string`
|
|
3248
|
+
- `randomLastName(): string`
|
|
3249
|
+
- `randomEmail(): string`
|
|
3250
|
+
- `randomText(length: number): string`
|
|
3251
|
+
- `randomWord(length?: number): string`
|
|
3252
|
+
- `json(value: any): string`
|
|
3253
|
+
- `textContains(haystack: string, needle: string): boolean`
|
|
3254
|
+
- `textJoin(parts: unknown[]): string`
|
|
3255
|
+
- `nowMs(): number`
|
|
3256
|
+
- `today(): string`
|
|
3257
|
+
- `daysFromNow(days: number): string`
|
|
3258
|
+
- `textMatches(text: string, pattern: any): any`
|
|
3259
|
+
- `parseJson(text: string): any`
|
|
3260
|
+
- `urlParam(url: string, key: string): any`
|
|
3261
|
+
- `toNumber(text: any, options?: { decimal?: string }): number`
|
|
3262
|
+
- `round(n: number, digits?: number): number`
|
|
3263
|
+
- `formatNumber(n: number, options?: { locale?: string; minFractionDigits?: number; maxFractionDigits?: number }): string`
|
|
3264
|
+
- `env(name: string, fallback?: any): any`
|
|
3265
|
+
|
|
3266
|
+
**Page state**
|
|
3267
|
+
|
|
3268
|
+
- `getAttribute(locator: Locator, attribute: string): string`
|
|
3269
|
+
- `getInnerText(locator: Locator): string`
|
|
3270
|
+
- `getInputValue(locator: Locator): string`
|
|
3271
|
+
- `boundingBox(locator: Locator): any`
|
|
3272
|
+
- `getTitle(): string`
|
|
3273
|
+
- `getUrl(): string`
|
|
3274
|
+
- `log(message: any, ...args: unknown[]): void`
|
|
3275
|
+
|
|
3276
|
+
**Storage and cookies**
|
|
3277
|
+
|
|
3278
|
+
- `setLocalStorage(key: string, value: string): void`
|
|
3279
|
+
- `getLocalStorage(key: string): string`
|
|
3280
|
+
- `setCookie(name: string, value: string, options?: { domain?: string; path?: string; expires?: number; httpOnly?: boolean; secure?: boolean; sameSite?: string }): void`
|
|
3281
|
+
- `getCookie(name: string): string`
|
|
3282
|
+
|
|
3283
|
+
**Tabs, frames, contexts, extensions**
|
|
3284
|
+
|
|
3285
|
+
- `setPage(indexOrTitle: string | number, options?: { activate?: boolean }): void`
|
|
3286
|
+
- `waitForPage(options?: { timeoutMs?: number }): number`
|
|
3287
|
+
- `bringToFront(index?: number): void`
|
|
3288
|
+
- `setPageHidden(hidden: boolean, index?: number): void`
|
|
3289
|
+
- `newPage(url?: string): number`
|
|
3290
|
+
- `closePage(index?: number): void`
|
|
3291
|
+
- `setViewport(size: { width?: number; height?: number } | null): void`
|
|
3292
|
+
- `emulateMedia(media: { reducedMotion?: "reduce" | "no-preference"; colorScheme?: "light" | "dark" | "no-preference" }): void`
|
|
3293
|
+
- `newContext(): number`
|
|
3294
|
+
- `setContext(index: number): void`
|
|
3295
|
+
- `enterFrame(frame: Locator): void`
|
|
3296
|
+
- `exitFrame(): void`
|
|
3297
|
+
- `addVirtualAuthenticator(options?: { protocol?: string; transport?: string; hasResidentKey?: boolean; hasUserVerification?: boolean; isUserVerified?: boolean; automaticPresenceSimulation?: boolean }): string`
|
|
3298
|
+
- `virtualCredentials(id?: string): any`
|
|
3299
|
+
- `removeVirtualAuthenticator(id: string): void`
|
|
3300
|
+
- `grantPermissions(permissions: string[], options?: { origin?: string }): void`
|
|
3301
|
+
- `setOffline(offline: boolean): void`
|
|
3302
|
+
- `waitForServiceWorker(options?: { timeoutMs?: number; url?: string | RegExp }): string`
|
|
3303
|
+
- `extensionId(): string`
|
|
3304
|
+
- `evaluateInServiceWorker(jsBody: any, ...args: unknown[]): any`
|
|
3305
|
+
|
|
3306
|
+
**Data, files, network, processes**
|
|
3307
|
+
|
|
3308
|
+
- `shell(cmd: string, ...args: unknown[]): any`
|
|
3309
|
+
- `waitForFile(path: string, pattern?: any, options?: { timeoutMs?: number }): string`
|
|
3310
|
+
- `assertNoFile(path: string, pattern?: any, options?: { withinMs?: number }): void`
|
|
3311
|
+
- `waitForJsonLine(path: string, filter: any, options?: { timeoutMs?: number }): any`
|
|
3312
|
+
- `assertNoJsonLine(path: string, filter: any, options?: { withinMs?: number }): void`
|
|
3313
|
+
- `readJsonLine(path: string, filter: any): any`
|
|
3314
|
+
- `readJson(path: string): any`
|
|
3315
|
+
- `readFile(path: string, options?: { encoding?: string }): string`
|
|
3316
|
+
- `readFileInfo(path: string): any`
|
|
3317
|
+
- `waitForFileCount(path: string, pattern: any, count: number, options?: { timeoutMs?: number }): number`
|
|
3318
|
+
- `assertFileCount(path: string, pattern: any, count: number): void`
|
|
3319
|
+
- `dbQuery(sql: string, ...args: unknown[]): any`
|
|
3320
|
+
- `dbExec(sql: string, ...args: unknown[]): number`
|
|
3321
|
+
- `apiCall(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS", path: string, body?: any, headers?: any, options?: { base?: string; timeoutMs?: number }): any`
|
|
3322
|
+
- `upload(path: string, options?: { field?: string; fields?: any }): any`
|
|
3323
|
+
- `mockRoute(glob: string, response: any): void`
|
|
3324
|
+
- `unmockRoute(glob?: string): void`
|
|
3325
|
+
- `waitForRequest(glob: string, options?: { timeoutMs?: number }): any`
|
|
3326
|
+
- `waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any`
|
|
3327
|
+
- `assertNoRequest(glob: string, options?: { since?: number }): void`
|
|
3328
|
+
- `openTerminal(app: string, options?: { host?: any }): number`
|
|
3329
|
+
- `setTerminal(index: number): void`
|
|
3330
|
+
- `closeTerminal(): void`
|
|
3331
|
+
- `terminalType(text: string, options?: { echo?: boolean }): void`
|
|
3332
|
+
- `terminalPress(key: string): void`
|
|
3333
|
+
- `terminalWaitForText(text: string | RegExp, options?: { not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3334
|
+
- `terminalAssertText(text: string | RegExp, options?: { not?: boolean; timeoutMs?: number }): void` (alias: timeout → timeoutMs)
|
|
3335
|
+
- `terminalResize(cols: number, rows: number): void`
|
|
3336
|
+
- `terminalScreenshot(name?: string): string`
|
|
3337
|
+
- `mcpStart(command: string, args?: string[], options?: { env?: any; cwd?: any; timeoutMs?: number }): any`
|
|
3338
|
+
- `mcpCall(server: any, tool: string, args?: any, options?: { timeoutMs?: number; allowError?: any }): any`
|
|
3339
|
+
- `mcpWaitNotification(server: any, method: string, options?: { timeoutMs?: number; match?: any }): any`
|
|
3340
|
+
- `mcpStop(server: any): void`
|
|
3341
|
+
- `vmAvailable(): boolean`
|
|
3342
|
+
- `vmClone(image: string): string`
|
|
3343
|
+
- `vmRun(name: string, options?: { timeoutMs?: number }): string`
|
|
3344
|
+
- `vmIp(name: string, options?: { timeoutMs?: number }): string`
|
|
3345
|
+
- `vmStop(name: string): void`
|
|
3346
|
+
- `vmDelete(name: string): void`
|
|
3347
|
+
|
|
3348
|
+
**Diagnostics**
|
|
3349
|
+
|
|
3350
|
+
- `screenshot(name?: string, options?: { fullPage?: boolean }): string`
|
|
3351
|
+
- `note(label: string, value: any): void`
|
|
3352
|
+
- `consoleEntries(options?: { level?: any; since?: number }): any`
|
|
3353
|
+
- `pageErrors(options?: { since?: number }): any`
|
|
3354
|
+
- `assertNoConsoleErrors(options?: { includePageErrors?: boolean; since?: number }): void`
|
|
3355
|
+
|
|
3356
|
+
**Page code (last resort)**
|
|
3357
|
+
|
|
3358
|
+
- `evaluate(jsBody: any, ...args: unknown[]): any`
|
|
3359
|
+
- `evaluateOnLocator(locator: Locator, jsBody: any, ...args: unknown[]): any`
|
|
3360
|
+
<!-- /generated:signatures -->
|
|
3361
|
+
|
|
3362
|
+
---
|
|
3363
|
+
|
|
2600
3364
|
## The language — JavaScript
|
|
2601
3365
|
|
|
2602
|
-
A scenario file is JavaScript
|
|
2603
|
-
|
|
2604
|
-
|
|
2605
|
-
|
|
2606
|
-
|
|
2607
|
-
|
|
2608
|
-
|
|
2609
|
-
|
|
2610
|
-
`?.` and `??`.
|
|
3366
|
+
A scenario file is JavaScript, and it runs as JavaScript: on V8, the
|
|
3367
|
+
engine of Node and Chrome, with the semantics of the language as it is.
|
|
3368
|
+
All of it runs — classes, getters, generators, labels, `instanceof`,
|
|
3369
|
+
`Date`, the built-in objects and their methods. What a scenario adds is
|
|
3370
|
+
the vocabulary (`click`, `getByRole`, `apiCall`, …). The file is parsed
|
|
3371
|
+
first, so a syntax error is reported before anything runs, and `lint`
|
|
3372
|
+
reads the same tree; its type check (`ts:*`) reports a name nothing
|
|
3373
|
+
declares.
|
|
2611
3374
|
|
|
2612
3375
|
Two things set it apart:
|
|
2613
3376
|
|
|
2614
|
-
- **Every call to the page or the system
|
|
2615
|
-
`click(…)`, `apiCall(…)`, `textContent(…)`
|
|
2616
|
-
promise
|
|
2617
|
-
|
|
2618
|
-
|
|
2619
|
-
|
|
2620
|
-
|
|
2621
|
-
`
|
|
3377
|
+
- **Every call to the page or the system returns its result.**
|
|
3378
|
+
`click(…)`, `apiCall(…)`, `textContent(…)` give the value, not a
|
|
3379
|
+
promise: the runner does the waiting, so a scenario has nothing to
|
|
3380
|
+
await. `async` and `await` are a lint error (`validator:async-await`),
|
|
3381
|
+
and `lint --fix` drops them. A function marked `async` would return at
|
|
3382
|
+
its first `await` and run the rest after the test is over, so the run
|
|
3383
|
+
refuses it too: a test, a step, a rollback block, a `waitUntil` or an
|
|
3384
|
+
`assertNever` body that returns a promise fails the test with
|
|
3385
|
+
`… returned a promise: … drop async and await`. Async code handed to
|
|
3386
|
+
the page, `evaluate(async () => …)`, is the page's and is allowed.
|
|
3387
|
+
- **The scenario has its own context, on its own thread.** It holds the
|
|
3388
|
+
vocabulary and JavaScript's built-in objects, not the APIs of Node or
|
|
3389
|
+
of a browser — see [Outside the language](#outside-the-language).
|
|
2622
3390
|
|
|
2623
3391
|
### A file: tests, helpers, constants
|
|
2624
3392
|
|
|
@@ -2628,8 +3396,8 @@ Two things set it apart:
|
|
|
2628
3396
|
in order; `e2e <file> --test <name>` plays one. Functions of the file
|
|
2629
3397
|
are shared between its tests, state is not.
|
|
2630
3398
|
- **Top level of a file — function declarations and `const` literals.**
|
|
2631
|
-
Nothing else there
|
|
2632
|
-
is refused (`validator:
|
|
3399
|
+
Nothing else belongs there: `let BASE = 'x'` or a call above `test_*`
|
|
3400
|
+
is refused (`validator:top-level-statement`). A shared fixed value is
|
|
2633
3401
|
a const holding a literal — a number, a string, `true` / `false` /
|
|
2634
3402
|
`null`, or an array or object of those — visible in every function, as
|
|
2635
3403
|
helper functions are (`const BASE = 'https://x.test';`). A computed
|
|
@@ -2666,11 +3434,11 @@ function test_order() {
|
|
|
2666
3434
|
}
|
|
2667
3435
|
```
|
|
2668
3436
|
|
|
2669
|
-
**Assignment without a declaration**
|
|
2670
|
-
|
|
2671
|
-
|
|
2672
|
-
|
|
2673
|
-
|
|
3437
|
+
**Assignment without a declaration** is a `lint` error
|
|
3438
|
+
(`validator:implicit-global`): JavaScript makes the name a global,
|
|
3439
|
+
shared by every test of the run. `lint --fix` writes the declaration —
|
|
3440
|
+
`let id;` at the start of the `test_*`, the `flow_*` or the helper,
|
|
3441
|
+
where every step sees it.
|
|
2674
3442
|
|
|
2675
3443
|
### Functions and callbacks
|
|
2676
3444
|
|
|
@@ -2693,9 +3461,8 @@ everywhere.
|
|
|
2693
3461
|
### Control flow
|
|
2694
3462
|
|
|
2695
3463
|
`if` / `else`, `for`, `for…of`, `for…in` (own keys), `while`,
|
|
2696
|
-
`do…while`, `break`, `continue`, `switch`, `return`, `throw`,
|
|
2697
|
-
`catch` / `finally`, `cond ? a : b` — as in JavaScript.
|
|
2698
|
-
outside the language.
|
|
3464
|
+
`do…while`, `break`, `continue`, labels, `switch`, `return`, `throw`,
|
|
3465
|
+
`try` / `catch` / `finally`, `cond ? a : b` — as in JavaScript.
|
|
2699
3466
|
|
|
2700
3467
|
One check is stricter than JavaScript: an `if` whose condition `lint`
|
|
2701
3468
|
knows to be a number, a string or a locator is `validator:if-shape` —
|
|
@@ -2712,18 +3479,27 @@ do {
|
|
|
2712
3479
|
assertEqual(job.body.status, 'DONE');
|
|
2713
3480
|
```
|
|
2714
3481
|
|
|
2715
|
-
A loop that never ends does not hang the run: the
|
|
2716
|
-
|
|
2717
|
-
|
|
2718
|
-
|
|
3482
|
+
A loop that never ends does not hang the run: the test's time budget
|
|
3483
|
+
cuts it (`setTestTimeout(ms)`, else `testTimeoutMs` in the config), and
|
|
3484
|
+
the test fails naming the budget and the statement it was on —
|
|
3485
|
+
`maxDurationMs budget (60000ms) exhausted at unotest/e2e/jobs.js:12`.
|
|
3486
|
+
Code that never comes back to the runner at all, a regular expression
|
|
3487
|
+
that backtracks for minutes, is stopped a second after the budget; its
|
|
3488
|
+
teardown blocks cannot play then. A run that keeps too much in memory
|
|
3489
|
+
ends on its memory limit, and the message says so. There is no step
|
|
3490
|
+
count.
|
|
2719
3491
|
|
|
2720
3492
|
**`try` / `catch`.** `catch (e)` takes what was thrown, as thrown:
|
|
2721
|
-
`throw
|
|
2722
|
-
|
|
2723
|
-
|
|
3493
|
+
`throw new Error('x')` gives an `Error`, `throw {code: 7}` gives
|
|
3494
|
+
`e.code`. A failed action — a click that found nothing, a failed
|
|
3495
|
+
assertion — arrives as a plain object `{name, message}`, not an
|
|
3496
|
+
`Error`. An error of the language is the class JavaScript gives it:
|
|
3497
|
+
`null.x` throws a `TypeError`, a name nothing declares a
|
|
3498
|
+
`ReferenceError`. The parameter may be left out (`catch { … }`). An error caught by
|
|
2724
3499
|
the scenario is not a failure: the run goes on, and the debugger does
|
|
2725
3500
|
not stop on it. `catch` does not take control flow — a `skip()`, a
|
|
2726
|
-
`return`, `break` / `continue` — nor
|
|
3501
|
+
`return`, `break` / `continue` — nor a spent time budget: the run ends
|
|
3502
|
+
all the same. To give the stand back
|
|
2727
3503
|
whatever happens, use [`teardown`](#teardown--give-the-stand-back), not
|
|
2728
3504
|
`finally`: a teardown also plays when the run is stopped or times out.
|
|
2729
3505
|
|
|
@@ -2744,12 +3520,10 @@ it returns from them. Directly in a `test_*` body it is
|
|
|
2744
3520
|
The right side runs only when the left one does not decide.
|
|
2745
3521
|
- **`?.`** reads through a missing value: `res.body?.items?.[0]?.id`,
|
|
2746
3522
|
`o.callback?.()`.
|
|
2747
|
-
-
|
|
2748
|
-
|
|
2749
|
-
|
|
2750
|
-
|
|
2751
|
-
array they fail the step (`Operator "+" does not apply to an object`)
|
|
2752
|
-
instead of giving `[object Object]`: combine or compare the fields.
|
|
3523
|
+
- **Every operator is JavaScript's**, `typeof`, `in`, `delete`,
|
|
3524
|
+
`instanceof`, `++` / `--`, the compound and logical assignments
|
|
3525
|
+
(`??=`) and the comma operator included. `+` on an object gives
|
|
3526
|
+
`[object Object]`, as in JavaScript: combine the fields instead.
|
|
2753
3527
|
- **A missing property or argument is `undefined`.** A host function
|
|
2754
3528
|
that finds nothing returns `null`; `x == null` is true for both.
|
|
2755
3529
|
|
|
@@ -2762,8 +3536,8 @@ character is dropped, as JavaScript drops it: `'\d+'` is `d+`. For a
|
|
|
2762
3536
|
regex write a `/…/` literal, or double the backslash (`'\\d+'`).
|
|
2763
3537
|
|
|
2764
3538
|
Backticks are template strings, with `${…}` interpolation and the same
|
|
2765
|
-
escapes. `` String.raw`…` `` keeps backslashes as written
|
|
2766
|
-
|
|
3539
|
+
escapes. `` String.raw`…` `` keeps backslashes as written; a tag of
|
|
3540
|
+
your own is a function, as in JavaScript.
|
|
2767
3541
|
|
|
2768
3542
|
```js
|
|
2769
3543
|
const n = 3;
|
|
@@ -2778,21 +3552,18 @@ Two lint rules guard templates:
|
|
|
2778
3552
|
variable ever given one): the value would become code of the page.
|
|
2779
3553
|
Write fixed text or a function, and pass the value as an argument.
|
|
2780
3554
|
- `validator:template-escape-changed` (warning) — a backtick string
|
|
2781
|
-
|
|
2782
|
-
a scenario written for the earlier raw backticks
|
|
2783
|
-
Double the backslash or use `` String.raw`…` ``.
|
|
3555
|
+
with a backslash escape JavaScript drops (`\s` reads as `s`, `\.`
|
|
3556
|
+
as `.`): a scenario written for the earlier raw backticks loses
|
|
3557
|
+
characters. Double the backslash or use `` String.raw`…` ``. Escapes
|
|
3558
|
+
JavaScript reads as meant (`\n`, `\\`, `\u…`) are not reported.
|
|
2784
3559
|
|
|
2785
3560
|
### Regex literals
|
|
2786
3561
|
|
|
2787
3562
|
A `/…/flags` literal is a JavaScript RegExp: every flag and syntax
|
|
2788
3563
|
Node accepts — `i`, `g`, `m`, `s`, `u`, `y`, `d`, `v`, named groups,
|
|
2789
3564
|
lookbehind. In a matcher slot (`getByText(/Items \d+/i)`) it goes to
|
|
2790
|
-
Playwright as that RegExp; in the scenario it
|
|
2791
|
-
|
|
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]`.
|
|
3565
|
+
Playwright as that RegExp; in the scenario it is a RegExp with all its
|
|
3566
|
+
members, and `match(…).groups` reads a named group.
|
|
2796
3567
|
|
|
2797
3568
|
### Objects, arrays, indexes
|
|
2798
3569
|
|
|
@@ -2807,11 +3578,12 @@ for (const [key, value] of Object.entries(counts)) note(key, value);
|
|
|
2807
3578
|
```
|
|
2808
3579
|
|
|
2809
3580
|
A variable holds the array or object itself, not a copy: after
|
|
2810
|
-
`b = a; a.push(1)`, `b` has the new element too.
|
|
2811
|
-
|
|
2812
|
-
|
|
2813
|
-
|
|
2814
|
-
|
|
3581
|
+
`b = a; a.push(1)`, `b` has the new element too.
|
|
3582
|
+
|
|
3583
|
+
**An object handed to a DSL function crosses with its own keys only.**
|
|
3584
|
+
A key it inherits — written under `__proto__:` or made by
|
|
3585
|
+
`Object.create(…)` — would be lost on the way, so the call fails
|
|
3586
|
+
instead: write each key on the object itself.
|
|
2815
3587
|
|
|
2816
3588
|
**Locators are not arrays.** An index on a locator is refused
|
|
2817
3589
|
(`validator:locator-index-access`):
|
|
@@ -2829,53 +3601,27 @@ const third = getByRole('row').nth(2);
|
|
|
2829
3601
|
|
|
2830
3602
|
### The library
|
|
2831
3603
|
|
|
2832
|
-
|
|
2833
|
-
|
|
2834
|
-
|
|
2835
|
-
`validator:unknown-member` on
|
|
2836
|
-
|
|
2837
|
-
|
|
2838
|
-
|
|
2839
|
-
|
|
2840
|
-
|
|
2841
|
-
|
|
2842
|
-
|
|
2843
|
-
|
|
2844
|
-
|
|
2845
|
-
|
|
2846
|
-
|
|
2847
|
-
|
|
2848
|
-
|
|
2849
|
-
|
|
2850
|
-
|
|
2851
|
-
|
|
2852
|
-
|
|
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.
|
|
2867
|
-
|
|
2868
|
-
**`arr.sortBy(key?, {desc?})`** sorts the array in place and returns it.
|
|
2869
|
-
With a key every element is an object and its field is compared;
|
|
2870
|
-
without one (`sortBy()`, or `sortBy(null, {desc: true})`) the elements
|
|
2871
|
-
themselves. The compared values are all numbers or all strings —
|
|
2872
|
-
anything else fails the step. The sort is stable.
|
|
2873
|
-
|
|
2874
|
-
```js
|
|
2875
|
-
const controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
|
|
2876
|
-
controls.sortBy('order'); // a, b
|
|
2877
|
-
controls.sortBy('order', {desc: true});
|
|
2878
|
-
```
|
|
3604
|
+
JavaScript's built-in objects, with all their members: `Math`, `JSON`,
|
|
3605
|
+
`Number`, `String`, `Array`, `Object`, `Date`, `Map`, `Set`, `RegExp`,
|
|
3606
|
+
`Promise`, `Symbol`, the errors, typed arrays. `lint` reports a member
|
|
3607
|
+
a value does not have in JavaScript: `validator:unknown-member` on a
|
|
3608
|
+
string, an array, a number, a Map or a Set, and its type check (`ts:*`)
|
|
3609
|
+
on the rest (`Math.tau`).
|
|
3610
|
+
|
|
3611
|
+
**A DSL function does not take an iterator.** `matchAll`, and `keys()`,
|
|
3612
|
+
`values()` and `entries()` of a Map or a Set, give iterators, as in
|
|
3613
|
+
JavaScript; `for…of`, a spread and `Array.from` read them. For array
|
|
3614
|
+
methods, and for a DSL function, spread first:
|
|
3615
|
+
`assertEqual([...m.keys()], ['a'])`, or pass the Map itself
|
|
3616
|
+
(`assertEqual(m.keys(), …)` fails, naming the line and the spread to
|
|
3617
|
+
write). `note`, `log` and the viewer show a Map as `Map(1) {"a" => 1}`.
|
|
3618
|
+
|
|
3619
|
+
`Date` reads the clock of the machine the runner is on. `clockFreeze`
|
|
3620
|
+
and `clockTick` move the page's clock, not this one; read the page's
|
|
3621
|
+
time through `evaluate`, or with `nowMs()` / `today()`.
|
|
3622
|
+
`Math.random()` draws a new number on every call, so a run that uses
|
|
3623
|
+
it differs from the last one; for fresh test data `randomWord(n)` and
|
|
3624
|
+
`randomEmail()` read better.
|
|
2879
3625
|
|
|
2880
3626
|
With a function argument `filter` is the array method; with an options
|
|
2881
3627
|
object it is still the locator step:
|
|
@@ -2883,37 +3629,21 @@ object it is still the locator step:
|
|
|
2883
3629
|
|
|
2884
3630
|
### Outside the language
|
|
2885
3631
|
|
|
2886
|
-
|
|
2887
|
-
|
|
2888
|
-
replacement:
|
|
3632
|
+
The scenario's context has the vocabulary, the built-in forms and
|
|
3633
|
+
JavaScript's built-in objects — not the APIs of Node or of a browser:
|
|
2889
3634
|
|
|
2890
|
-
| Not
|
|
3635
|
+
| Not there | Write instead |
|
|
2891
3636
|
|---|---|
|
|
2892
3637
|
| `import`, `export`, `require(…)` | functions in `_helpers/` are visible by name in every scenario |
|
|
2893
|
-
| `
|
|
2894
|
-
| `
|
|
2895
|
-
| `
|
|
2896
|
-
| `
|
|
2897
|
-
| `
|
|
2898
|
-
|
|
2899
|
-
|
|
2900
|
-
|
|
2901
|
-
|
|
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.
|
|
3638
|
+
| `process`, `fetch` | `apiCall(…)` for HTTP, `shell(…)` for a command, `UPPER_SNAKE` variables or `env(…)` for external values |
|
|
3639
|
+
| `window`, `document`, `localStorage`, `navigator`, `location` | `evaluate(fn, arg)`: it runs the function in the page |
|
|
3640
|
+
| `setTimeout`, `setInterval`, `queueMicrotask` | `pause(ms)` or `waitUntil(() => …)` |
|
|
3641
|
+
| `console.log` | `log(…)` or `note(label, value)`: `console` is there and prints nowhere |
|
|
3642
|
+
| `eval(…)`, `new Function(…)` | the code itself: both are refused when called |
|
|
3643
|
+
|
|
3644
|
+
The context keeps the vocabulary apart from the runner. It is not a
|
|
3645
|
+
security boundary: a scenario runs with the rights of the user who
|
|
3646
|
+
started it, as a Playwright test does.
|
|
2917
3647
|
|
|
2918
3648
|
A method call on a name nothing declares — `clock.freeze(…)`,
|
|
2919
3649
|
`page.waitForTimeout(…)` as another framework spells it — is an
|