@unotest/web 0.51.0 → 0.52.1
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 +91 -3
- package/README.md +22 -13
- package/bin/unotest-web.js +2 -1
- package/dist/config/schema.d.ts +17 -12
- package/dist/config/schema.js +1 -1
- package/dist/driver/index.js +1 -1
- package/dist/dsl/index.d.ts +39 -41
- 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 +5 -0
- package/dist/dsl/web-dsl-language-service.js +1 -1
- package/dist/mcp/server.js +1 -1
- package/dist/runner/cli.js +1 -1
- package/dist/runner/init/chrome-probe.js +1 -1
- package/dist/runner/init.js +1 -1
- package/dist/runner/install-chromium.js +1 -1
- package/dist/runner/prepare-fix.js +1 -1
- package/dist/runner/scaffold-workspace.js +1 -1
- package/dist/runner/serve-fixture.js +1 -1
- package/dist/runner/web-runner-adapter.js +1 -1
- package/guides/dsl-reference.md +166 -205
- package/package.json +16 -8
- 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
|
|
@@ -492,7 +492,7 @@ list that is still filling in passes once it is complete.
|
|
|
492
492
|
|
|
493
493
|
```js
|
|
494
494
|
assertTexts(getByRole('listitem'), ['Apple', 'Banana', /^Cherry/])
|
|
495
|
-
labels = ['Apple', 'Banana'];
|
|
495
|
+
const labels = ['Apple', 'Banana'];
|
|
496
496
|
assertTexts(getByRole('listitem'), labels)
|
|
497
497
|
assertText(getByRole('listitem').first(), labels[0])
|
|
498
498
|
```
|
|
@@ -559,7 +559,7 @@ pause.
|
|
|
559
559
|
assertNever(() => apiCall('GET', '/me', null, revokedAuth).status == 200,
|
|
560
560
|
{withinMs: 5000, label: 'revoked key rejected'});
|
|
561
561
|
assertNever(() => {
|
|
562
|
-
n = parseJson(textContent(getByTestId('unread')));
|
|
562
|
+
const n = parseJson(textContent(getByTestId('unread')));
|
|
563
563
|
if (n > 0) { return n; }
|
|
564
564
|
return false;
|
|
565
565
|
}, {withinMs: 3000, intervalMs: 100});
|
|
@@ -630,7 +630,7 @@ assertUrl(/\/cars\/\d+$/)
|
|
|
630
630
|
Generic boolean assert. Throws with `message` when `value` is falsy.
|
|
631
631
|
|
|
632
632
|
```js
|
|
633
|
-
probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
|
|
633
|
+
const probe = shell('grep', '-q', 'ready', 'app.log', {allowNonZero: true});
|
|
634
634
|
assertTrue(probe.code == 0, 'app.log should contain "ready"');
|
|
635
635
|
```
|
|
636
636
|
|
|
@@ -642,7 +642,7 @@ names the first path that differs and both values, then a line diff of
|
|
|
642
642
|
the two sides, every line of them — nothing is folded away:
|
|
643
643
|
|
|
644
644
|
```js
|
|
645
|
-
body = parseJson(getAttribute(locator('#state'), 'data-json'));
|
|
645
|
+
const body = parseJson(getAttribute(locator('#state'), 'data-json'));
|
|
646
646
|
assertEqual(body.controls, {theme: 'dark', devices: ['pixel']});
|
|
647
647
|
// assertEqual: values differ at devices[0]: expected "pixel", got "iphone"
|
|
648
648
|
```
|
|
@@ -655,8 +655,8 @@ reads with `readJson`. The failure names every field that breaks the
|
|
|
655
655
|
schema, by path, with what is wrong there:
|
|
656
656
|
|
|
657
657
|
```js
|
|
658
|
-
schema = readJson('unotest/fixtures/message.schema.json');
|
|
659
|
-
req = waitForRequest('**/api/messages');
|
|
658
|
+
const schema = readJson('unotest/fixtures/message.schema.json');
|
|
659
|
+
const req = waitForRequest('**/api/messages');
|
|
660
660
|
assertSchema(req.postDataJson, schema);
|
|
661
661
|
// assertSchema: the value breaks the schema in 2 places:
|
|
662
662
|
// /room: must be >= 1
|
|
@@ -698,7 +698,7 @@ inside that step:
|
|
|
698
698
|
```js
|
|
699
699
|
function test_refund() {
|
|
700
700
|
step("Find a paid order", () => {
|
|
701
|
-
orders = apiCall('GET', '/orders?status=paid');
|
|
701
|
+
const orders = apiCall('GET', '/orders?status=paid');
|
|
702
702
|
if (orders.length == 0) { skip('no paid order on this stand'); }
|
|
703
703
|
});
|
|
704
704
|
// …
|
|
@@ -729,7 +729,7 @@ go to the configured judge; a `fail` verdict fails the step with the
|
|
|
729
729
|
judge's reasoning, like any other assertion.
|
|
730
730
|
|
|
731
731
|
```js
|
|
732
|
-
reply = locator('.chat__message').last();
|
|
732
|
+
const reply = locator('.chat__message').last();
|
|
733
733
|
assertJudge(reply,
|
|
734
734
|
'The reply must direct the user to support and must NOT promise ' +
|
|
735
735
|
'to escalate, resend the email, or notify a team itself.');
|
|
@@ -907,10 +907,10 @@ class or attribute — CSS. `assertCount` / `waitForCount` take the same
|
|
|
907
907
|
locator and wait for the number.
|
|
908
908
|
|
|
909
909
|
```js
|
|
910
|
-
done = count(getByRole('row').filter({hasText: 'Done'}));
|
|
911
|
-
admins = count(getByRole('row').filter({has: getByTestId('admin-badge')}));
|
|
912
|
-
selected = count(locator('li.selected'));
|
|
913
|
-
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"]'));
|
|
914
914
|
assertCount(getByRole('listitem').filter({hasNotText: 'Archived'}), 3)
|
|
915
915
|
```
|
|
916
916
|
|
|
@@ -925,7 +925,7 @@ when nothing matches. One read, no wait — the list to branch on.
|
|
|
925
925
|
`assertTexts` is the waiting check of the same list.
|
|
926
926
|
|
|
927
927
|
```js
|
|
928
|
-
names = texts(locator('#agents li')); // ["Claude Code", "Codex"]
|
|
928
|
+
const names = texts(locator('#agents li')); // ["Claude Code", "Codex"]
|
|
929
929
|
if (names.length > 0) {
|
|
930
930
|
log('first agent:', names[0]);
|
|
931
931
|
}
|
|
@@ -965,7 +965,7 @@ Whether the attribute is present at all — the honest probe for boolean
|
|
|
965
965
|
attributes (`disabled`, `readonly`, `required`, …).
|
|
966
966
|
|
|
967
967
|
```js
|
|
968
|
-
n = count(getByRole('row'));
|
|
968
|
+
const n = count(getByRole('row'));
|
|
969
969
|
if (n > 10) {
|
|
970
970
|
log('too many rows:', n);
|
|
971
971
|
}
|
|
@@ -1038,8 +1038,8 @@ until it is truthy; the call gives that value back.
|
|
|
1038
1038
|
|
|
1039
1039
|
```js
|
|
1040
1040
|
waitUntil(() => parseJson(textContent(getByTestId('count'))) >= 5);
|
|
1041
|
-
job = waitUntil(() => {
|
|
1042
|
-
r = apiCall('GET', '/jobs/' + id);
|
|
1041
|
+
const job = waitUntil(() => {
|
|
1042
|
+
const r = apiCall('GET', '/jobs/' + id);
|
|
1043
1043
|
if (r.body.state != 'done') { return false; }
|
|
1044
1044
|
return r.body;
|
|
1045
1045
|
}, {timeoutMs: 30000, intervalMs: 500, label: 'job done'});
|
|
@@ -1062,16 +1062,15 @@ job = waitUntil(() => {
|
|
|
1062
1062
|
|
|
1063
1063
|
```js
|
|
1064
1064
|
let tries = 0;
|
|
1065
|
-
n = waitUntil(() => {
|
|
1065
|
+
const n = waitUntil(() => {
|
|
1066
1066
|
tries = tries + 1;
|
|
1067
1067
|
return tries >= 3 ? tries : false;
|
|
1068
1068
|
});
|
|
1069
1069
|
assertEqual(n, 3);
|
|
1070
1070
|
```
|
|
1071
1071
|
|
|
1072
|
-
A `let` at the top level of the file
|
|
1073
|
-
the declaration (`validator:
|
|
1074
|
-
finds no such variable.
|
|
1072
|
+
A `let` at the top level of the file belongs to no test: the validator
|
|
1073
|
+
refuses the declaration (`validator:top-level-statement`).
|
|
1075
1074
|
|
|
1076
1075
|
```js bad
|
|
1077
1076
|
let seen = 0;
|
|
@@ -1116,7 +1115,7 @@ send, then wait for the count to grow — and only then assert on reply
|
|
|
1116
1115
|
content:
|
|
1117
1116
|
|
|
1118
1117
|
```js
|
|
1119
|
-
n = count(locator('[data-message]'));
|
|
1118
|
+
const n = count(locator('[data-message]'));
|
|
1120
1119
|
fill(getByRole('textbox'), '@Bot Service ' + question);
|
|
1121
1120
|
press(getByRole('textbox'), 'Enter');
|
|
1122
1121
|
waitForCount(locator('[data-message]'), n + 2, {timeoutMs: 90000}); // echo + reply
|
|
@@ -1366,7 +1365,7 @@ no new tab within it, the step fails with
|
|
|
1366
1365
|
|
|
1367
1366
|
```js
|
|
1368
1367
|
click(getByRole('button', {name: 'Open report'}));
|
|
1369
|
-
tab = waitForPage(); // e.g. 1, now active
|
|
1368
|
+
const tab = waitForPage(); // e.g. 1, now active
|
|
1370
1369
|
assertUrl('/report');
|
|
1371
1370
|
setPage(0);
|
|
1372
1371
|
```
|
|
@@ -1388,6 +1387,7 @@ back lands where the scenario left off.
|
|
|
1388
1387
|
|
|
1389
1388
|
```js
|
|
1390
1389
|
function test_second_client_writes_to_closed_thread() {
|
|
1390
|
+
let clientB;
|
|
1391
1391
|
step("Client A opens the thread", () => {
|
|
1392
1392
|
flow_login(LOGIN, PASSWORD);
|
|
1393
1393
|
goto('/support/thread/42');
|
|
@@ -1637,9 +1637,9 @@ Headless needs `channel: "chromium"` (the headless shell ignores
|
|
|
1637
1637
|
`--load-extension`).
|
|
1638
1638
|
|
|
1639
1639
|
```js
|
|
1640
|
-
id = extensionId();
|
|
1640
|
+
const id = extensionId();
|
|
1641
1641
|
evaluateInServiceWorker('(theme) => chrome.storage.local.set({theme: theme})', 'dark');
|
|
1642
|
-
stored = evaluateInServiceWorker('() => chrome.storage.local.get("theme")');
|
|
1642
|
+
const stored = evaluateInServiceWorker('() => chrome.storage.local.get("theme")');
|
|
1643
1643
|
goto('chrome-extension://' + id + '/popup.html');
|
|
1644
1644
|
```
|
|
1645
1645
|
|
|
@@ -1672,7 +1672,7 @@ Returns empty string when key is absent.
|
|
|
1672
1672
|
|
|
1673
1673
|
```js
|
|
1674
1674
|
setLocalStorage('feature-flag', 'enabled');
|
|
1675
|
-
v = getLocalStorage('feature-flag');
|
|
1675
|
+
const v = getLocalStorage('feature-flag');
|
|
1676
1676
|
```
|
|
1677
1677
|
|
|
1678
1678
|
### `setCookie(name, value, options?)` / `getCookie(name)` → `string`
|
|
@@ -1794,8 +1794,8 @@ Semantics:
|
|
|
1794
1794
|
(values stay masked in logs).
|
|
1795
1795
|
|
|
1796
1796
|
```js
|
|
1797
|
-
out = shell('pnpm', 'db:create-user', 'alice'); // non-zero exit → step fails
|
|
1798
|
-
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});
|
|
1799
1799
|
if (probe.code == 0) { /* … */ }
|
|
1800
1800
|
```
|
|
1801
1801
|
|
|
@@ -1846,7 +1846,7 @@ downloads that are there but did not match.
|
|
|
1846
1846
|
```js
|
|
1847
1847
|
step("Export the report", () => {
|
|
1848
1848
|
click(getByRole('button', {name: 'Export CSV'}));
|
|
1849
|
-
report = waitForDownload({name: /\.csv$/});
|
|
1849
|
+
const report = waitForDownload({name: /\.csv$/});
|
|
1850
1850
|
waitForFile(report.path, 'id,total');
|
|
1851
1851
|
});
|
|
1852
1852
|
```
|
|
@@ -1882,7 +1882,7 @@ export default {
|
|
|
1882
1882
|
|
|
1883
1883
|
```js
|
|
1884
1884
|
step("Wait for the bot reply in the JSONL feed", () => {
|
|
1885
|
-
line = waitForFile('events.jsonl', /"type":"reply"/, {timeoutMs: 30000});
|
|
1885
|
+
const line = waitForFile('events.jsonl', /"type":"reply"/, {timeoutMs: 30000});
|
|
1886
1886
|
});
|
|
1887
1887
|
```
|
|
1888
1888
|
|
|
@@ -1914,7 +1914,7 @@ its fields.
|
|
|
1914
1914
|
|
|
1915
1915
|
```js
|
|
1916
1916
|
step("Wait for the bot's reply event", () => {
|
|
1917
|
-
evt = waitForJsonLine('events.jsonl',
|
|
1917
|
+
const evt = waitForJsonLine('events.jsonl',
|
|
1918
1918
|
{userId: BOT_ID, roomId: room, isBot: true}, {timeoutMs: 30000});
|
|
1919
1919
|
assertTrue(textContains(evt.text, 'hello'), evt.text);
|
|
1920
1920
|
});
|
|
@@ -1953,7 +1953,7 @@ equality per key, dot paths for nesting, unparsable lines skipped).
|
|
|
1953
1953
|
|
|
1954
1954
|
```js
|
|
1955
1955
|
step("Ask control question 3", () => {
|
|
1956
|
-
q = readJsonLine('questions.jsonl', {slot: 3});
|
|
1956
|
+
const q = readJsonLine('questions.jsonl', {slot: 3});
|
|
1957
1957
|
fill(getByRole('textbox', {name: 'Message'}), q.text);
|
|
1958
1958
|
screenshot(q.id);
|
|
1959
1959
|
});
|
|
@@ -1976,7 +1976,7 @@ fixture object. Walk the result with `.` and `[]`.
|
|
|
1976
1976
|
|
|
1977
1977
|
```js
|
|
1978
1978
|
step("Send button uses the app's own label", () => {
|
|
1979
|
-
shared = readJson('unotest/fixtures/shared.json');
|
|
1979
|
+
const shared = readJson('unotest/fixtures/shared.json');
|
|
1980
1980
|
assertVisible(getByRole('button', {name: shared.chat.labels[0].send}));
|
|
1981
1981
|
});
|
|
1982
1982
|
```
|
|
@@ -2001,7 +2001,7 @@ instead of failing the step, and `null` when no fallback is given.
|
|
|
2001
2001
|
The fallback is the one-line default; `??` says the same:
|
|
2002
2002
|
|
|
2003
2003
|
```js
|
|
2004
|
-
api = env('API_URL', 'http://localhost:3000');
|
|
2004
|
+
let api = env('API_URL', 'http://localhost:3000');
|
|
2005
2005
|
api = env('API_URL') ?? 'http://localhost:3000';
|
|
2006
2006
|
```
|
|
2007
2007
|
|
|
@@ -2028,7 +2028,7 @@ download.
|
|
|
2028
2028
|
|
|
2029
2029
|
```js
|
|
2030
2030
|
step("Export is a PNG", () => {
|
|
2031
|
-
bytes = readFile('unotest/fixtures/files/image-3x2.png', {encoding: 'base64'});
|
|
2031
|
+
const bytes = readFile('unotest/fixtures/files/image-3x2.png', {encoding: 'base64'});
|
|
2032
2032
|
assertTrue(textContains(bytes, 'iVBORw0KGgo'), 'not a PNG signature');
|
|
2033
2033
|
});
|
|
2034
2034
|
```
|
|
@@ -2052,7 +2052,7 @@ The dimensions come from the PNG header, so a large image is not read.
|
|
|
2052
2052
|
|
|
2053
2053
|
```js
|
|
2054
2054
|
step("Fixture image is 3x2", () => {
|
|
2055
|
-
info = readFileInfo('unotest/fixtures/files/image-3x2.png');
|
|
2055
|
+
const info = readFileInfo('unotest/fixtures/files/image-3x2.png');
|
|
2056
2056
|
assertTrue(info.png.width == 3 && info.png.height == 2, 'size: ' + info.size);
|
|
2057
2057
|
});
|
|
2058
2058
|
```
|
|
@@ -2135,7 +2135,7 @@ Parameterized SELECT. Driver picked by URL scheme:
|
|
|
2135
2135
|
- `sqlite:…` / `*.db` / `*.sqlite` — needs `better-sqlite3`
|
|
2136
2136
|
|
|
2137
2137
|
```js
|
|
2138
|
-
rows = dbQuery('select id from users where email = ?', 'a@b.c');
|
|
2138
|
+
const rows = dbQuery('select id from users where email = ?', 'a@b.c');
|
|
2139
2139
|
```
|
|
2140
2140
|
|
|
2141
2141
|
### `dbExec(sql, ...params)` → `number` (affected rows)
|
|
@@ -2152,7 +2152,7 @@ HTTP via global `fetch`. **`path` must be relative** (starts with `/`) —
|
|
|
2152
2152
|
absolute URLs throw to prevent scenarios from hitting arbitrary hosts.
|
|
2153
2153
|
|
|
2154
2154
|
```js
|
|
2155
|
-
res = apiCall('POST', '/auth/login', {email: 'a@b.c', password: 'x'});
|
|
2155
|
+
const res = apiCall('POST', '/auth/login', {email: 'a@b.c', password: 'x'});
|
|
2156
2156
|
assertTrue(res.status == 200, 'login failed');
|
|
2157
2157
|
```
|
|
2158
2158
|
|
|
@@ -2163,7 +2163,7 @@ variable** from `unotest/.env` (overlays apply as usual), never a URL:
|
|
|
2163
2163
|
|
|
2164
2164
|
```js
|
|
2165
2165
|
// unotest/.env: API_BASE_CHAT=https://chatbackend.example.com
|
|
2166
|
-
res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
|
|
2166
|
+
const res = apiCall('DELETE', '/external/room/r1', null, {'x-api-key': KEY},
|
|
2167
2167
|
{base: 'API_BASE_CHAT'});
|
|
2168
2168
|
```
|
|
2169
2169
|
|
|
@@ -2198,7 +2198,7 @@ must answer in a known time — or a slow one you would rather fail fast
|
|
|
2198
2198
|
on — gets a budget for the whole call, the reply body included:
|
|
2199
2199
|
|
|
2200
2200
|
```js
|
|
2201
|
-
res = apiCall('POST', '/live/start', {stand: 'a'}, null, {timeoutMs: 150000});
|
|
2201
|
+
const res = apiCall('POST', '/live/start', {stand: 'a'}, null, {timeoutMs: 150000});
|
|
2202
2202
|
```
|
|
2203
2203
|
|
|
2204
2204
|
Past the budget the request is aborted and the step fails as a timeout
|
|
@@ -2211,7 +2211,7 @@ It combines with `{base}` in the same object.
|
|
|
2211
2211
|
result of `upload(...)` as the body posts `multipart/form-data`:
|
|
2212
2212
|
|
|
2213
2213
|
```js
|
|
2214
|
-
res = apiCall('POST', '/tenants/t1/documents',
|
|
2214
|
+
const res = apiCall('POST', '/tenants/t1/documents',
|
|
2215
2215
|
upload('fixtures/manual.pdf', {fields: {source: 'e2e'}}),
|
|
2216
2216
|
{Authorization: BEARER});
|
|
2217
2217
|
assertTrue(res.status == 202, 'ingestion not accepted');
|
|
@@ -2452,7 +2452,7 @@ JSON (null when it is not JSON).
|
|
|
2452
2452
|
```js
|
|
2453
2453
|
mockRoute('**/api/messages', { body: { ok: true } });
|
|
2454
2454
|
click(getByRole('button', { name: 'Send' }));
|
|
2455
|
-
req = waitForRequest('**/api/messages');
|
|
2455
|
+
const req = waitForRequest('**/api/messages');
|
|
2456
2456
|
assertTrue(req.postDataJson.text == 'hello', 'sent: ' + req.postData);
|
|
2457
2457
|
```
|
|
2458
2458
|
|
|
@@ -2472,7 +2472,7 @@ Waits until the active page has opened a WebSocket whose URL matches
|
|
|
2472
2472
|
|
|
2473
2473
|
```js
|
|
2474
2474
|
goto('/chat');
|
|
2475
|
-
socket = waitForWebSocket('**/ws');
|
|
2475
|
+
const socket = waitForWebSocket('**/ws');
|
|
2476
2476
|
assertTrue(socket.url.endsWith('/ws'));
|
|
2477
2477
|
```
|
|
2478
2478
|
|
|
@@ -2621,7 +2621,7 @@ Read page properties directly into a local variable.
|
|
|
2621
2621
|
### `getAttribute(loc, name)` → `string`
|
|
2622
2622
|
|
|
2623
2623
|
```js
|
|
2624
|
-
href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
|
|
2624
|
+
const href = getAttribute(getByRole('link', {name: 'Docs'}), 'href');
|
|
2625
2625
|
```
|
|
2626
2626
|
|
|
2627
2627
|
Returns `""` when the attribute is missing — which makes it **blind to
|
|
@@ -2647,7 +2647,7 @@ Where the element lies in the viewport, CSS pixels. `null` when it is
|
|
|
2647
2647
|
not rendered (`display:none`, detached). Does not scroll it into view.
|
|
2648
2648
|
|
|
2649
2649
|
```js
|
|
2650
|
-
box = boundingBox(getByRole('dialog'));
|
|
2650
|
+
const box = boundingBox(getByRole('dialog'));
|
|
2651
2651
|
assertTrue(box.width <= 480, json(box));
|
|
2652
2652
|
```
|
|
2653
2653
|
|
|
@@ -2661,7 +2661,7 @@ not set reads `""`. A missing or ambiguous element fails as
|
|
|
2661
2661
|
|
|
2662
2662
|
```js
|
|
2663
2663
|
assertTrue(computedStyle(getByRole('dialog'), 'opacity') == 1, 'dialog is faded');
|
|
2664
|
-
accent = computedStyle(locator('body'), '--accent');
|
|
2664
|
+
const accent = computedStyle(locator('body'), '--accent');
|
|
2665
2665
|
```
|
|
2666
2666
|
|
|
2667
2667
|
### `getImageSize(loc)` → `{width, height}` | `null`
|
|
@@ -2682,7 +2682,7 @@ image is never read too early as broken.
|
|
|
2682
2682
|
numbers.
|
|
2683
2683
|
|
|
2684
2684
|
```js
|
|
2685
|
-
size = getImageSize(getByRole('img', {name: 'Avatar'}));
|
|
2685
|
+
const size = getImageSize(getByRole('img', {name: 'Avatar'}));
|
|
2686
2686
|
assertTrue(size !== null, 'avatar is broken');
|
|
2687
2687
|
assertTrue(size.width >= 256, json(size));
|
|
2688
2688
|
```
|
|
@@ -2714,8 +2714,8 @@ Infinite and paused animations are listed too. `hasAnimation` counts
|
|
|
2714
2714
|
only those with `playState: 'running'` and `infinite: false`.
|
|
2715
2715
|
|
|
2716
2716
|
```js
|
|
2717
|
-
list = animations(getByTestId('status'));
|
|
2718
|
-
pulse = list.find((a) => a.name == 'pulse');
|
|
2717
|
+
const list = animations(getByTestId('status'));
|
|
2718
|
+
const pulse = list.find((a) => a.name == 'pulse');
|
|
2719
2719
|
assertTrue(pulse !== undefined && pulse.playState == 'running', json(list));
|
|
2720
2720
|
```
|
|
2721
2721
|
|
|
@@ -2756,7 +2756,7 @@ Random lowercase letters, default 8 — digit-free unique markers for apps
|
|
|
2756
2756
|
whose content filters reject numbers in text.
|
|
2757
2757
|
|
|
2758
2758
|
```js
|
|
2759
|
-
marker = randomWord(10);
|
|
2759
|
+
const marker = randomWord(10);
|
|
2760
2760
|
fill(getByRole('textbox'), textJoin(['ping ', marker]));
|
|
2761
2761
|
waitForText(marker);
|
|
2762
2762
|
```
|
|
@@ -2767,7 +2767,7 @@ Substring probe for data that came back as a string — shell stdout,
|
|
|
2767
2767
|
apiCall bodies. The read-side counterpart of `textJoin`.
|
|
2768
2768
|
|
|
2769
2769
|
```js
|
|
2770
|
-
out = shell('./status.sh');
|
|
2770
|
+
const out = shell('./status.sh');
|
|
2771
2771
|
assertTrue(textContains(out.stdout, 'ready'), out.stderr);
|
|
2772
2772
|
```
|
|
2773
2773
|
|
|
@@ -2779,9 +2779,9 @@ took no part in the match is `null`. The array is truthy, so the call
|
|
|
2779
2779
|
also works as a test.
|
|
2780
2780
|
|
|
2781
2781
|
```js
|
|
2782
|
-
m = textMatches(getUrl(), /room=(\d+)/);
|
|
2782
|
+
const m = textMatches(getUrl(), /room=(\d+)/);
|
|
2783
2783
|
assertTrue(m, getUrl());
|
|
2784
|
-
roomId = m[1];
|
|
2784
|
+
const roomId = m[1];
|
|
2785
2785
|
```
|
|
2786
2786
|
|
|
2787
2787
|
A string pattern is refused: for a plain substring use `textContains`.
|
|
@@ -2795,7 +2795,7 @@ setting. Invalid JSON fails the step and quotes the input; an empty
|
|
|
2795
2795
|
string is not JSON.
|
|
2796
2796
|
|
|
2797
2797
|
```js
|
|
2798
|
-
saved = parseJson(getLocalStorage('messages'));
|
|
2798
|
+
const saved = parseJson(getLocalStorage('messages'));
|
|
2799
2799
|
assertEqual(saved[0].type, 'hello');
|
|
2800
2800
|
```
|
|
2801
2801
|
|
|
@@ -2805,7 +2805,7 @@ A query parameter, decoded. `null` when the key is absent, `''` when it
|
|
|
2805
2805
|
is present but empty. A path without a host (`/room?id=7`) works too.
|
|
2806
2806
|
|
|
2807
2807
|
```js
|
|
2808
|
-
src = getAttribute(locator('iframe#chat'), 'src');
|
|
2808
|
+
const src = getAttribute(locator('iframe#chat'), 'src');
|
|
2809
2809
|
assertEqual(urlParam(src, 'roomId'), 'r-7');
|
|
2810
2810
|
```
|
|
2811
2811
|
|
|
@@ -2829,9 +2829,9 @@ A number as a page writes it, for arithmetic and comparison. What
|
|
|
2829
2829
|
- A number passes through unchanged.
|
|
2830
2830
|
|
|
2831
2831
|
```js
|
|
2832
|
-
total = toNumber(getInnerText(getByTestId('total'))); // "1 234,50"
|
|
2832
|
+
const total = toNumber(getInnerText(getByTestId('total'))); // "1 234,50"
|
|
2833
2833
|
assertTrue(total > 1000, 'total: ' + total);
|
|
2834
|
-
width = toNumber(textMatches(computedStyle(phone, '--phone-w'), /(\d+)px/)[1]);
|
|
2834
|
+
const width = toNumber(textMatches(computedStyle(phone, '--phone-w'), /(\d+)px/)[1]);
|
|
2835
2835
|
```
|
|
2836
2836
|
|
|
2837
2837
|
### `round(n, digits?)` → `number`
|
|
@@ -2842,7 +2842,7 @@ zero, on the decimal as written: `round(2.5)` is 3, `round(-2.5)` is
|
|
|
2842
2842
|
`toNumber` first.
|
|
2843
2843
|
|
|
2844
2844
|
```js
|
|
2845
|
-
payout = round(stake * odds, 2);
|
|
2845
|
+
const payout = round(stake * odds, 2);
|
|
2846
2846
|
```
|
|
2847
2847
|
|
|
2848
2848
|
### `formatNumber(n, options?)` → `string`
|
|
@@ -2871,7 +2871,7 @@ steps: an object concatenated with `+` collapses into
|
|
|
2871
2871
|
body that explained it.
|
|
2872
2872
|
|
|
2873
2873
|
```js
|
|
2874
|
-
res = apiCall('POST', '/documents', upload('fixtures/doc.pdf'));
|
|
2874
|
+
const res = apiCall('POST', '/documents', upload('fixtures/doc.pdf'));
|
|
2875
2875
|
assertTrue(res.status == 202, json(res.body));
|
|
2876
2876
|
```
|
|
2877
2877
|
|
|
@@ -2915,7 +2915,7 @@ written, the way Playwright sends `fn.toString()`: the page sees none of
|
|
|
2915
2915
|
the scenario's variables, only the arguments after it.
|
|
2916
2916
|
|
|
2917
2917
|
```js
|
|
2918
|
-
height = evaluate(() => document.documentElement.scrollHeight);
|
|
2918
|
+
let height = evaluate(() => document.documentElement.scrollHeight);
|
|
2919
2919
|
height = evaluate(`document.documentElement.scrollHeight`); // the string form
|
|
2920
2920
|
```
|
|
2921
2921
|
|
|
@@ -2925,8 +2925,8 @@ destructures. So one argument is `function(x)`, not `function([x])` —
|
|
|
2925
2925
|
that one fails with `2 is not iterable`.
|
|
2926
2926
|
|
|
2927
2927
|
```js
|
|
2928
|
-
doubled = evaluate((n) => n * 2, 21); // one → the value
|
|
2929
|
-
result = evaluate(
|
|
2928
|
+
const doubled = evaluate((n) => n * 2, 21); // one → the value
|
|
2929
|
+
const result = evaluate(
|
|
2930
2930
|
([a, b]) => window.myApp.compute(a, b),
|
|
2931
2931
|
10, 20 // two → one array
|
|
2932
2932
|
);
|
|
@@ -2965,7 +2965,7 @@ The body gets the element first, then the extras by the same rule as
|
|
|
2965
2965
|
array.
|
|
2966
2966
|
|
|
2967
2967
|
```js
|
|
2968
|
-
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);
|
|
2969
2969
|
```
|
|
2970
2970
|
|
|
2971
2971
|
Reach for it only for what no typed call reads — a style is
|
|
@@ -2975,7 +2975,7 @@ why it uses the hatch, and the linter takes the reason:
|
|
|
2975
2975
|
|
|
2976
2976
|
```js
|
|
2977
2977
|
// Truncated with an ellipsis: the content is wider than the cell.
|
|
2978
|
-
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
|
|
2979
2979
|
assertTrue(overflows === false, 'the id is cut off');
|
|
2980
2980
|
```
|
|
2981
2981
|
|
|
@@ -3002,7 +3002,7 @@ screenshot('landing', {fullPage: true}); // full scroll height
|
|
|
3002
3002
|
names its evidence after the case it is on:
|
|
3003
3003
|
|
|
3004
3004
|
```js
|
|
3005
|
-
q = waitForJsonLine('questions.jsonl', {slot: 3});
|
|
3005
|
+
const q = waitForJsonLine('questions.jsonl', {slot: 3});
|
|
3006
3006
|
screenshot(q.id); // 003-q-17.png
|
|
3007
3007
|
screenshot(textJoin(['q-', q.id, '-answer']));
|
|
3008
3008
|
```
|
|
@@ -3038,10 +3038,10 @@ page like any other.
|
|
|
3038
3038
|
|
|
3039
3039
|
```js
|
|
3040
3040
|
click(getByRole('button', { name: 'Save' }));
|
|
3041
|
-
errors = consoleEntries({ level: 'error' });
|
|
3041
|
+
const errors = consoleEntries({ level: 'error' });
|
|
3042
3042
|
assertTrue(errors.length == 0, json(errors));
|
|
3043
3043
|
|
|
3044
|
-
before = nowMs();
|
|
3044
|
+
const before = nowMs();
|
|
3045
3045
|
click(getByRole('button', { name: 'Retry' }));
|
|
3046
3046
|
assertTrue(consoleEntries({ level: ['warn', 'error'], since: before }).length == 1, 'one complaint');
|
|
3047
3047
|
```
|
|
@@ -3064,7 +3064,7 @@ is empty when the browser gave none. The last 100 are kept.
|
|
|
3064
3064
|
|
|
3065
3065
|
```js
|
|
3066
3066
|
click(getByRole('button', { name: 'Load' }));
|
|
3067
|
-
thrown = pageErrors();
|
|
3067
|
+
const thrown = pageErrors();
|
|
3068
3068
|
assertTrue(thrown.length == 0, json(thrown));
|
|
3069
3069
|
```
|
|
3070
3070
|
|
|
@@ -3114,7 +3114,7 @@ step.soft("Question", {tag: q.id}, () => {
|
|
|
3114
3114
|
note('question', q.text);
|
|
3115
3115
|
fill(getByRole('textbox', {name: 'Message'}), q.text);
|
|
3116
3116
|
press(getByRole('textbox', {name: 'Message'}), 'Enter');
|
|
3117
|
-
answer = textContent(getByTestId('last-answer'));
|
|
3117
|
+
const answer = textContent(getByTestId('last-answer'));
|
|
3118
3118
|
note('answer', answer);
|
|
3119
3119
|
assertJudge(getByTestId('last-answer'), q.rubric);
|
|
3120
3120
|
});
|
|
@@ -3363,26 +3363,30 @@ per option; an older spelling it still takes is named after the line.
|
|
|
3363
3363
|
|
|
3364
3364
|
## The language — JavaScript
|
|
3365
3365
|
|
|
3366
|
-
A scenario file is JavaScript
|
|
3367
|
-
|
|
3368
|
-
|
|
3369
|
-
|
|
3370
|
-
|
|
3371
|
-
|
|
3372
|
-
|
|
3373
|
-
|
|
3374
|
-
`?.` 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.
|
|
3375
3374
|
|
|
3376
3375
|
Two things set it apart:
|
|
3377
3376
|
|
|
3378
|
-
- **Every call to the page or the system
|
|
3379
|
-
`click(…)`, `apiCall(…)`, `textContent(…)`
|
|
3380
|
-
promise
|
|
3381
|
-
|
|
3382
|
-
|
|
3383
|
-
|
|
3384
|
-
|
|
3385
|
-
`
|
|
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).
|
|
3386
3390
|
|
|
3387
3391
|
### A file: tests, helpers, constants
|
|
3388
3392
|
|
|
@@ -3392,8 +3396,8 @@ Two things set it apart:
|
|
|
3392
3396
|
in order; `e2e <file> --test <name>` plays one. Functions of the file
|
|
3393
3397
|
are shared between its tests, state is not.
|
|
3394
3398
|
- **Top level of a file — function declarations and `const` literals.**
|
|
3395
|
-
Nothing else there
|
|
3396
|
-
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
|
|
3397
3401
|
a const holding a literal — a number, a string, `true` / `false` /
|
|
3398
3402
|
`null`, or an array or object of those — visible in every function, as
|
|
3399
3403
|
helper functions are (`const BASE = 'https://x.test';`). A computed
|
|
@@ -3430,11 +3434,11 @@ function test_order() {
|
|
|
3430
3434
|
}
|
|
3431
3435
|
```
|
|
3432
3436
|
|
|
3433
|
-
**Assignment without a declaration**
|
|
3434
|
-
|
|
3435
|
-
|
|
3436
|
-
|
|
3437
|
-
|
|
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.
|
|
3438
3442
|
|
|
3439
3443
|
### Functions and callbacks
|
|
3440
3444
|
|
|
@@ -3457,9 +3461,8 @@ everywhere.
|
|
|
3457
3461
|
### Control flow
|
|
3458
3462
|
|
|
3459
3463
|
`if` / `else`, `for`, `for…of`, `for…in` (own keys), `while`,
|
|
3460
|
-
`do…while`, `break`, `continue`, `switch`, `return`, `throw`,
|
|
3461
|
-
`catch` / `finally`, `cond ? a : b` — as in JavaScript.
|
|
3462
|
-
outside the language.
|
|
3464
|
+
`do…while`, `break`, `continue`, labels, `switch`, `return`, `throw`,
|
|
3465
|
+
`try` / `catch` / `finally`, `cond ? a : b` — as in JavaScript.
|
|
3463
3466
|
|
|
3464
3467
|
One check is stricter than JavaScript: an `if` whose condition `lint`
|
|
3465
3468
|
knows to be a number, a string or a locator is `validator:if-shape` —
|
|
@@ -3476,18 +3479,27 @@ do {
|
|
|
3476
3479
|
assertEqual(job.body.status, 'DONE');
|
|
3477
3480
|
```
|
|
3478
3481
|
|
|
3479
|
-
A loop that never ends does not hang the run: the
|
|
3480
|
-
|
|
3481
|
-
|
|
3482
|
-
|
|
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.
|
|
3483
3491
|
|
|
3484
3492
|
**`try` / `catch`.** `catch (e)` takes what was thrown, as thrown:
|
|
3485
|
-
`throw
|
|
3486
|
-
|
|
3487
|
-
|
|
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
|
|
3488
3499
|
the scenario is not a failure: the run goes on, and the debugger does
|
|
3489
3500
|
not stop on it. `catch` does not take control flow — a `skip()`, a
|
|
3490
|
-
`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
|
|
3491
3503
|
whatever happens, use [`teardown`](#teardown--give-the-stand-back), not
|
|
3492
3504
|
`finally`: a teardown also plays when the run is stopped or times out.
|
|
3493
3505
|
|
|
@@ -3508,12 +3520,10 @@ it returns from them. Directly in a `test_*` body it is
|
|
|
3508
3520
|
The right side runs only when the left one does not decide.
|
|
3509
3521
|
- **`?.`** reads through a missing value: `res.body?.items?.[0]?.id`,
|
|
3510
3522
|
`o.callback?.()`.
|
|
3511
|
-
-
|
|
3512
|
-
|
|
3513
|
-
|
|
3514
|
-
|
|
3515
|
-
array they fail the step (`Operator "+" does not apply to an object`)
|
|
3516
|
-
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.
|
|
3517
3527
|
- **A missing property or argument is `undefined`.** A host function
|
|
3518
3528
|
that finds nothing returns `null`; `x == null` is true for both.
|
|
3519
3529
|
|
|
@@ -3526,8 +3536,8 @@ character is dropped, as JavaScript drops it: `'\d+'` is `d+`. For a
|
|
|
3526
3536
|
regex write a `/…/` literal, or double the backslash (`'\\d+'`).
|
|
3527
3537
|
|
|
3528
3538
|
Backticks are template strings, with `${…}` interpolation and the same
|
|
3529
|
-
escapes. `` String.raw`…` `` keeps backslashes as written
|
|
3530
|
-
|
|
3539
|
+
escapes. `` String.raw`…` `` keeps backslashes as written; a tag of
|
|
3540
|
+
your own is a function, as in JavaScript.
|
|
3531
3541
|
|
|
3532
3542
|
```js
|
|
3533
3543
|
const n = 3;
|
|
@@ -3552,12 +3562,8 @@ Two lint rules guard templates:
|
|
|
3552
3562
|
A `/…/flags` literal is a JavaScript RegExp: every flag and syntax
|
|
3553
3563
|
Node accepts — `i`, `g`, `m`, `s`, `u`, `y`, `d`, `v`, named groups,
|
|
3554
3564
|
lookbehind. In a matcher slot (`getByText(/Items \d+/i)`) it goes to
|
|
3555
|
-
Playwright as that RegExp; in the scenario it
|
|
3556
|
-
|
|
3557
|
-
`replaceAll`, `search` and `split` take it.
|
|
3558
|
-
|
|
3559
|
-
`match` gives an array of the match and its groups, or `null`; there is
|
|
3560
|
-
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.
|
|
3561
3567
|
|
|
3562
3568
|
### Objects, arrays, indexes
|
|
3563
3569
|
|
|
@@ -3572,11 +3578,12 @@ for (const [key, value] of Object.entries(counts)) note(key, value);
|
|
|
3572
3578
|
```
|
|
3573
3579
|
|
|
3574
3580
|
A variable holds the array or object itself, not a copy: after
|
|
3575
|
-
`b = a; a.push(1)`, `b` has the new element too.
|
|
3576
|
-
|
|
3577
|
-
|
|
3578
|
-
|
|
3579
|
-
|
|
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.
|
|
3580
3587
|
|
|
3581
3588
|
**Locators are not arrays.** An index on a locator is refused
|
|
3582
3589
|
(`validator:locator-index-access`):
|
|
@@ -3594,56 +3601,27 @@ const third = getByRole('row').nth(2);
|
|
|
3594
3601
|
|
|
3595
3602
|
### The library
|
|
3596
3603
|
|
|
3597
|
-
|
|
3598
|
-
|
|
3599
|
-
|
|
3600
|
-
`validator:unknown-member` on
|
|
3601
|
-
|
|
3602
|
-
|
|
3603
|
-
|
|
3604
|
-
|
|
3605
|
-
|
|
3606
|
-
|
|
3607
|
-
|
|
3608
|
-
|
|
3609
|
-
|
|
3610
|
-
|
|
3611
|
-
|
|
3612
|
-
|
|
3613
|
-
|
|
3614
|
-
|
|
3615
|
-
|
|
3616
|
-
|
|
3617
|
-
|
|
3618
|
-
| string | `length`, `at` `charAt` `includes` `startsWith` `endsWith` `indexOf` `lastIndexOf` `slice` `substring` `split` `trim` `trimStart` `trimEnd` `padStart` `padEnd` `repeat` `replace` `replaceAll` `toLowerCase` `toUpperCase` `match` `matchAll` `search` `localeCompare` `normalize` |
|
|
3619
|
-
| number | `toFixed`, `toPrecision`, `toString(radix)` |
|
|
3620
|
-
| regex | `source`, `flags`, `test` |
|
|
3621
|
-
| 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` |
|
|
3622
|
-
| Map | `size`, `get` `set` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
|
|
3623
|
-
| Set | `size`, `add` `has` `delete` `clear` `keys` `values` `entries` `forEach` |
|
|
3624
|
-
|
|
3625
|
-
The methods behave as in JavaScript; `matchAll` gives an array, and so
|
|
3626
|
-
do `keys()`, `values()` and `entries()` of a Map or a Set
|
|
3627
|
-
(`m.keys().map(…)` works directly). `for…of`, a spread and `Array.from`
|
|
3628
|
-
iterate a Map or a Set as in JavaScript; `note`, `log` and the viewer
|
|
3629
|
-
show one as `Map(1) {"a" => 1}`. A Map keeps its entries apart from its
|
|
3630
|
-
members: `m.length` is a lint error, the count is `m.size`.
|
|
3631
|
-
`Math.random()` draws a new number on every call, so a run that uses it
|
|
3632
|
-
differs from the last one; for fresh test data `randomWord(n)` and
|
|
3633
|
-
`randomEmail()` read better. `undefined`, `NaN` and `Infinity` are
|
|
3634
|
-
values too.
|
|
3635
|
-
|
|
3636
|
-
**`arr.sortBy(key?, {desc?})`** sorts the array in place and returns it.
|
|
3637
|
-
With a key every element is an object and its field is compared;
|
|
3638
|
-
without one (`sortBy()`, or `sortBy(null, {desc: true})`) the elements
|
|
3639
|
-
themselves. The compared values are all numbers or all strings —
|
|
3640
|
-
anything else fails the step. The sort is stable.
|
|
3641
|
-
|
|
3642
|
-
```js
|
|
3643
|
-
const controls = [{id: 'b', order: 2}, {id: 'a', order: 1}];
|
|
3644
|
-
controls.sortBy('order'); // a, b
|
|
3645
|
-
controls.sortBy('order', {desc: true});
|
|
3646
|
-
```
|
|
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.
|
|
3647
3625
|
|
|
3648
3626
|
With a function argument `filter` is the array method; with an options
|
|
3649
3627
|
object it is still the locator step:
|
|
@@ -3651,38 +3629,21 @@ object it is still the locator step:
|
|
|
3651
3629
|
|
|
3652
3630
|
### Outside the language
|
|
3653
3631
|
|
|
3654
|
-
|
|
3655
|
-
|
|
3656
|
-
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:
|
|
3657
3634
|
|
|
3658
|
-
| Not
|
|
3635
|
+
| Not there | Write instead |
|
|
3659
3636
|
|---|---|
|
|
3660
3637
|
| `import`, `export`, `require(…)` | functions in `_helpers/` are visible by name in every scenario |
|
|
3661
|
-
| `
|
|
3662
|
-
| `
|
|
3663
|
-
| `
|
|
3664
|
-
| `
|
|
3665
|
-
| `
|
|
3666
|
-
|
|
3667
|
-
|
|
3668
|
-
|
|
3669
|
-
|
|
3670
|
-
| `process`, `window`, `document`, `globalThis`, `fetch`, `console`, `localStorage`, `navigator`, `location` | an `UPPER_SNAKE` external variable or `env(…)`; the page via `evaluate(…)`; HTTP via `apiCall(…)`; output via `note(…)` / `log(…)` |
|
|
3671
|
-
| `WeakMap`, `WeakSet`, `WeakRef` | a `Map` or a `Set` |
|
|
3672
|
-
| `Symbol`, `Proxy`, `Reflect` | plain objects |
|
|
3673
|
-
| `instanceof` | `Array.isArray(x)` or `typeof x` |
|
|
3674
|
-
| `with` | name the object: `obj.prop` |
|
|
3675
|
-
| labels | a helper function and `return` |
|
|
3676
|
-
| `debugger` | a breakpoint in the viewer, or `pause()` |
|
|
3677
|
-
| BigInt (`1n`) | a number |
|
|
3678
|
-
| `&&=`, `\|\|=`, `??=` | the full form: `x = x ?? value` |
|
|
3679
|
-
| tagged templates | `` String.raw`…` `` is the only tag |
|
|
3680
|
-
| `new.target`, `import.meta` | pass the value as a parameter |
|
|
3681
|
-
|
|
3682
|
-
A name in the table is refused only when the scenario does not declare
|
|
3683
|
-
it: `const window = 1;` is an ordinary variable. `new` is the other way
|
|
3684
|
-
round: it applies to the library's `Map` and `Set` only, never to a
|
|
3685
|
-
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.
|
|
3686
3647
|
|
|
3687
3648
|
A method call on a name nothing declares — `clock.freeze(…)`,
|
|
3688
3649
|
`page.waitForTimeout(…)` as another framework spells it — is an
|