@unotest/web 0.56.0 → 0.57.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.
Files changed (35) hide show
  1. package/.claude/skills/write-e2e-test/SKILL.md +14 -0
  2. package/.claude/skills/write-e2e-test-ground/SKILL.md +14 -0
  3. package/CHANGELOG.md +147 -3
  4. package/README.md +3 -3
  5. package/bin/unotest-web.js +13 -0
  6. package/dist/config/schema.d.ts +15 -15
  7. package/dist/config/schema.js +1 -1
  8. package/dist/driver/index.d.ts +10 -2
  9. package/dist/driver/index.js +1 -1
  10. package/dist/dsl/index.d.ts +66 -16
  11. package/dist/dsl/index.js +1 -1
  12. package/dist/dsl/v8/scenario-worker.js +1 -1
  13. package/dist/dsl/web-dsl-language-service.d.ts +2 -2
  14. package/dist/dsl/web-dsl-language-service.js +1 -1
  15. package/dist/inspection/page-inject.d.ts +34 -2
  16. package/dist/inspection/page-inject.js +119 -0
  17. package/dist/{interfaces-BiGd3BdD.d.ts → interfaces-DDp6Chwx.d.ts} +148 -6
  18. package/dist/{linter-DIAb0JOB.d.ts → linter-q4UNIeGI.d.ts} +12 -0
  19. package/dist/mcp/server.js +1 -1
  20. package/dist/runner/cli.d.ts +1 -1
  21. package/dist/runner/cli.js +1 -1
  22. package/dist/runner/init/chrome-probe.js +1 -1
  23. package/dist/runner/init.js +1 -1
  24. package/dist/runner/install-chromium.js +1 -1
  25. package/dist/runner/prepare-fix.js +1 -1
  26. package/dist/runner/scaffold-workspace.js +1 -1
  27. package/dist/runner/serve-fixture.js +1 -1
  28. package/dist/runner/web-runner-adapter.js +1 -1
  29. package/dist/{scenario-variables-B-ULUTHt.d.ts → scenario-variables-CGexnWK4.d.ts} +18 -0
  30. package/examples/idioms/wait-enabled.js +6 -3
  31. package/guides/agent-integration.md +2 -2
  32. package/guides/dsl-reference.md +388 -17
  33. package/llms.txt +14 -4
  34. package/package.json +8 -8
  35. package/types/unotest-dsl.d.ts +80 -10
package/llms.txt CHANGED
@@ -47,7 +47,11 @@ Full reference: https://docs.unotest.com/reference/dsl/
47
47
  - `fill(locator, value, { force?, timeoutMs? })` · options `{force?, timeoutMs?}` (alias: timeout → timeoutMs) — Clear and type a value into an input.
48
48
  - `press(locator, key, { delay?, timeoutMs? })` · options `{delay?, timeoutMs?}` (alias: timeout → timeoutMs) — Press a key (e.g. 'Enter', 'Control+A').
49
49
  - `selectOption(locator, value, { force?, timeoutMs? })` · options `{force?, timeoutMs?}` (alias: timeout → timeoutMs) — Select option(s) in a `<select>`.
50
- - `dragAndDrop(from, to, { force?, timeoutMs? })` · options `{force?, timeoutMs?}` (alias: timeout → timeoutMs) — Drag one element onto another.
50
+ - `dragAndDrop(from, to, { force?, sourcePosition?, targetPosition?, timeoutMs? })` · options `{force?, sourcePosition?, targetPosition?, timeoutMs?}` (alias: timeout → timeoutMs) — Drag one element onto another.
51
+ - `dragBy(locator, dx, dy, { force?, sourcePosition?, timeoutMs? })` · options `{force?, sourcePosition?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.57.0 — Take hold of an element (its centre, or the {x, y} point `sourcePosition` inside it) and move the pointer dx, dy CSS pixels before letting go — a resize handle, a slider, a selection box on a canvas.
52
+ - `tap(locator, { position?, timeoutMs? })` · options `{position?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.57.0 — Touch the element with one finger, down and up, after the same wait for the element as any action.
53
+ - `longPress(locator, { durationMs?, position?, timeoutMs? })` · options `{position?, durationMs?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.57.0 — Hold one finger on the element for `durationMs` (default 800) before it lifts — a row's context menu on a phone.
54
+ - `swipe(locator, dx, dy, { durationMs?, sourcePosition?, timeoutMs? })` · options `{sourcePosition?, durationMs?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.57.0 — Put one finger on the element (its centre, or the {x, y} point `sourcePosition` inside it), move it dx, dy CSS pixels over `durationMs` (default 300) and lift it — a row swiped aside, a carousel.
51
55
  - `uploadFile(locator, files)` — Set files on a file input.
52
56
  - `clipboardPaste(locator, text)` — Paste text.
53
57
 
@@ -70,6 +74,8 @@ Full reference: https://docs.unotest.com/reference/dsl/
70
74
  - `assertAttribute(locator, name, expected, { exact?, not?, timeoutMs? })` · options `{exact?, not?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.46.0 — Polls the attribute `name` until it equals `expected` (exact: false — contains) or matches a /regex/.
71
75
  - `assertVisible(locator, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Element is visible.
72
76
  - `assertHidden(locator, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Element is hidden or detached.
77
+ - `assertInViewport(locator, { ratio?, timeoutMs? })` · options `{ratio?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.57.0 — Element intersects the viewport — the visible area of the page, with scroll containers that clip it.
78
+ - `assertNoFocusZoom(scope?, { minFontPx?, timeoutMs? })` · options `{minFontPx?, timeoutMs?}` (alias: timeout → timeoutMs) · since 0.57.0 — No text field zooms the page on focus on iOS: Safari zooms into a field whose text is under 16px and stays zoomed.
73
79
  - `assertNeverAppears(locator, { withinMs })` · options `{withinMs?}` — Negative window assert: FAIL the moment the locator becomes visible; pass when the whole window elapsed clean.
74
80
  - `assertValue(locator, expected, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Input's value equals `expected`.
75
81
  - `assertCount(locator, expected, { timeoutMs? })` · options `{timeoutMs?}` (alias: timeout → timeoutMs) — Number of matches equals `expected`.
@@ -122,7 +128,7 @@ Full reference: https://docs.unotest.com/reference/dsl/
122
128
 
123
129
  ## Page state
124
130
 
125
- - `getAttribute(locator, name) → string` — Attribute value ("" if missing).
131
+ - `getAttribute(locator, name) → string` — Attribute value ("" if missing, never null — so `== null` is never true; check presence with hasAttribute).
126
132
  - `getInnerText(locator) → string` — Rendered inner text.
127
133
  - `getInputValue(locator) → string` — Input value (alias of inputValue).
128
134
  - `boundingBox(locator) → {x, y, width, height} | null` · since 0.45.0 — Where the element lies in the viewport, CSS pixels; null when it is not rendered (display:none, detached).
@@ -145,10 +151,10 @@ Full reference: https://docs.unotest.com/reference/dsl/
145
151
  - `bringToFront(index?)` · since 0.45.0 — Bring a tab to front — the visible one — without changing the tab the steps act on.
146
152
  - `setPageHidden(hidden, index?)` · since 0.51.0 — Emulates the tab's visibility for its scripts: true sends it to the background (document.hidden, visibilityState 'hidden', blur + visibilitychange), false brings it back.
147
153
  - `newPage(url?) → number` · since 0.45.0 — Open a new tab in the active browser context, make it active and return its index.
148
- - `closePage(index?)` · since 0.45.0 — Close a tab; no index: the active one.
154
+ - `closePage(index?, {beforeUnload?}?)` · options `{beforeUnload?}` · since 0.45.0 — Close a tab; no index: the active one.
149
155
  - `setViewport({width, height})` · since 0.44.0 — Resize every tab of the browser, and the ones it opens later, without reloading.
150
156
  - `emulateMedia({ reducedMotion?, colorScheme? })` · options `{reducedMotion?, colorScheme?}` · since 0.47.0 — Change the media features the current tab reports from now on — what matchMedia and CSS @media see: reducedMotion 'reduce' | 'no-preference', colorScheme 'light' | 'dark' | 'no-preference'.
151
- - `newContext({ profile?, cdpEndpoint? }) → number` · options `{profile?, cdpEndpoint?}` · since 0.44.0 — Open another browser context — a separate client with its own cookies, storage and tabs — and make it active.
157
+ - `newContext({ profile?, cdpEndpoint?, headers?, viewport? }) → number` · options `{profile?, cdpEndpoint?, headers?, viewport?}` · since 0.44.0 — Open another browser context — a separate client with its own cookies, storage and tabs — and make it active.
152
158
  - `setContext(index)` · since 0.44.0 — Make browser context `index` active.
153
159
  - `enterFrame(locator)` — Scope subsequent calls to an iframe (persists until exitFrame).
154
160
  - `exitFrame()` — Exit the innermost iframe scope.
@@ -183,6 +189,8 @@ Full reference: https://docs.unotest.com/reference/dsl/
183
189
  - `waitForRequest(glob, { timeoutMs?, method? }) → { url, method, headers, postData, postDataJson }` · options `{timeoutMs?, method?}` · since 0.45.0 — Wait for a request matching `glob` and return it; `postDataJson` is the body read as JSON (null when it is not).
184
190
  - `waitForResponse(glob, { status?, method?, since?, timeoutMs? }) → { url, method, status, ok, headers, json, text, truncated?, mocked? }` · options `{status?, method?, since?, timeoutMs?}` · since 0.55.0 — Wait for the answer to a request matching `glob` and return it: `headers` of the response (names in lower case), `json` (null when the body is not JSON, was not read or was cut), `text` (text or JSON bodies of `fetch` / `xhr`, at most 64 KB, then `truncated`).
185
191
  - `waitForWebSocket(glob, { timeoutMs? }) → { url }` · options `{timeoutMs?}` · since 0.51.0 — Wait until the active page has opened a WebSocket whose URL matches `glob` (a Playwright URL glob: `**/ws`, `ws://localhost:*/live`) and return its URL.
192
+ - `waitForWebSocketFrame(glob, { direction?, match?, timeoutMs? }) → { url, direction, text, json, at }` · options `{direction?, match?, timeoutMs?}` · since 0.57.0 — Wait for a frame of a WebSocket of the active page whose URL matches `glob`, and take it: the next call gives the next frame.
193
+ - `webSocketFrames(glob, { direction? }) → [{ url, direction, text, json, at }]` · options `{direction?}` · since 0.57.0 — Every frame kept of the active page's WebSockets whose URL matches `glob`, oldest first, from the page's last load on; takes none, so waitForWebSocketFrame still gives them.
186
194
  - `networkEntries({ since?, glob? }) → [{ url, method, status, ok, headers, failureText?, mocked?, requestJson, responseJson, responseText, truncated?, at }]` · options `{since?, glob?}` · since 0.53.0 — What the active page requested and was answered, oldest first: the status and, for `fetch` / `xhr` with a text or JSON content type, the bodies (`requestJson` as `postDataJson` of `waitForRequest`; `responseJson` is null when the body is not JSON; at most 64 KB each, then `truncated`).
187
195
  - `assertNoRequest(glob, { since?, method? })` · options `{since?, method?}` · since 0.45.0 — FAIL if the recording abort at `glob` — mockRoute(glob, {abort: true, record: true}) — stopped any request; with `since` (epoch ms, from nowMs()) only from then on, with `method` (`'POST'`, any case) only requests of that method.
188
196
  - `openTerminal(app?, { host?, leaveOpen?, env?, cwd?, shell?, cols?, rows?, term?, locale?, cleanProfile? }) → number` · options `{host?, leaveOpen?, env?, cwd?, shell?, cols?, rows?, term?, locale?, cleanProfile?}` · since 0.51.0 — Open a terminal and make it the one the terminal steps act on; returns its index for setTerminal.
@@ -200,6 +208,8 @@ Full reference: https://docs.unotest.com/reference/dsl/
200
208
  - `terminalScreenshot(name?) → string` · since 0.51.0 — A PNG of the active terminal, saved with the run — a window's own picture, or the 'shell' terminal's screen drawn by the headless browser; returns its project-relative path.
201
209
  - `mcpStart(command, args?, { env?, cwd?, timeoutMs? }) → server` · options `{env?, cwd?, timeoutMs?}` · since 0.51.0 — Start a stdio MCP server and finish its handshake; returns the handle the other mcp* functions take.
202
210
  - `mcpCall(server, tool, args?, { timeoutMs?, allowError? }) → { content, structuredContent?, isError? }` · options `{timeoutMs?, allowError?}` · since 0.51.0 — Call a tool and return its result.
211
+ - `mcpCallStart(server, tool, args?) → call` · since 0.57.0 — Send a tool call and go on without waiting for its answer — for a tool that waits on something the test does next, like a person's answer on a card.
212
+ - `mcpCallResult(call, { timeoutMs?, allowError? }) → { content, structuredContent?, isError? }` · options `{timeoutMs?, allowError?}` · since 0.57.0 — Wait for the answer of a call mcpCallStart sent and return it, as mcpCall would.
203
213
  - `mcpWaitNotification(server, method, { match?, timeoutMs? }) → params` · options `{timeoutMs?, match?}` · since 0.51.0 — Wait for a notification of `method` and return its params.
204
214
  - `mcpStop(server)` · since 0.51.0 — Stop the server.
205
215
  - `vmAvailable() → bool` · since 0.51.0 — Whether VMs can run here: Tart is installed and answers.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unotest/web",
3
- "version": "0.56.0",
3
+ "version": "0.57.0",
4
4
  "description": "AI-native E2E testing for web applications. MCP server (run_test / step / resume / inspect_runtime / agent_fix) + CLI runner + JavaScript DSL scenarios on a sandboxed AST engine + semantic DOM snapshots.",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -89,11 +89,11 @@
89
89
  "tsx": "^4.19.2",
90
90
  "yaml": "^2.6.0",
91
91
  "zod": "^3.23.8",
92
- "@unotest/core": "^0.56.0",
93
- "@unotest/dsl": "^0.56.0",
94
- "@unotest/viewer": "^0.56.0",
95
- "@unotest/grounder-client": "^0.56.0",
96
- "@unotest/protocol": "^0.56.0"
92
+ "@unotest/core": "^0.57.0",
93
+ "@unotest/dsl": "^0.57.0",
94
+ "@unotest/protocol": "^0.57.0",
95
+ "@unotest/grounder-client": "^0.57.0",
96
+ "@unotest/viewer": "^0.57.0"
97
97
  },
98
98
  "optionalDependencies": {
99
99
  "node-pty": "1.2.0-beta.15"
@@ -103,8 +103,8 @@
103
103
  "javascript-obfuscator": "^4.1.1",
104
104
  "tsup": "^8.5.1",
105
105
  "typescript": "^5.7.2",
106
- "@unotest/grounder": "^0.56.0",
107
- "@unotest/judge": "^0.56.0"
106
+ "@unotest/grounder": "^0.57.0",
107
+ "@unotest/judge": "^0.57.0"
108
108
  },
109
109
  "peerDependencies": {
110
110
  "typescript": ">=5.0.0 <7"
@@ -155,11 +155,39 @@ declare function press(locator: Locator, key: string, options?: { timeout?: numb
155
155
  declare function selectOption(locator: Locator, value: string | string[] | { value?: string; label?: string; index?: number }, options?: { timeout?: number; force?: boolean; timeoutMs?: number }): void;
156
156
 
157
157
  /**
158
- * dragAndDrop(from, to, { force?, timeoutMs? })
158
+ * dragAndDrop(from, to, { force?, sourcePosition?, targetPosition?, timeoutMs? })
159
159
  *
160
- * Drag one element onto another. Uses synthetic mouse events (not native HTML5 DragEvent).
160
+ * Drag one element onto another. Uses synthetic mouse events (not native HTML5 DragEvent). `sourcePosition` / `targetPosition` are {x, y} points inside each element (CSS pixels from its top-left corner; default its centre) — from and to may be the same element, to sweep a selection inside one frame.
161
161
  */
162
- declare function dragAndDrop(source: Locator, target: Locator, options?: { timeout?: number; force?: boolean; timeoutMs?: number }): void;
162
+ declare function dragAndDrop(source: Locator, target: Locator, options?: { timeout?: number; force?: boolean; sourcePosition?: { x?: number; y?: number }; targetPosition?: { x?: number; y?: number }; timeoutMs?: number }): void;
163
+
164
+ /**
165
+ * dragBy(locator, dx, dy, { force?, sourcePosition?, timeoutMs? })
166
+ *
167
+ * Take hold of an element (its centre, or the {x, y} point `sourcePosition` inside it) and move the pointer dx, dy CSS pixels before letting go — a resize handle, a slider, a selection box on a canvas. Synthetic mouse events in several steps.
168
+ */
169
+ declare function dragBy(source: Locator, dx: number, dy: number, options?: { timeout?: number; force?: boolean; sourcePosition?: { x?: number; y?: number }; timeoutMs?: number }): void;
170
+
171
+ /**
172
+ * tap(locator, { position?, timeoutMs? })
173
+ *
174
+ * Touch the element with one finger, down and up, after the same wait for the element as any action. `position` is the {x, y} point inside it (default its centre). Needs a context with a touch screen (`profile: 'ios'` or a touch `device`); without one the step fails before touching anything.
175
+ */
176
+ declare function tap(locator: Locator, options?: { timeout?: number; position?: any; timeoutMs?: number }): void;
177
+
178
+ /**
179
+ * longPress(locator, { durationMs?, position?, timeoutMs? })
180
+ *
181
+ * Hold one finger on the element for `durationMs` (default 800) before it lifts — a row's context menu on a phone. Needs a touch screen, like tap. Chromium drives its own touch input; WebKit and Firefox get touch events dispatched from the page, with `pointerType: 'touch'` pointer events — in WebKit those touch events are not `instanceof TouchEvent`.
182
+ */
183
+ declare function longPress(locator: Locator, options?: { timeout?: number; position?: any; durationMs?: number; timeoutMs?: number }): void;
184
+
185
+ /**
186
+ * swipe(locator, dx, dy, { durationMs?, sourcePosition?, timeoutMs? })
187
+ *
188
+ * Put one finger on the element (its centre, or the {x, y} point `sourcePosition` inside it), move it dx, dy CSS pixels over `durationMs` (default 300) and lift it — a row swiped aside, a carousel. The offset reads as in dragBy. Needs a touch screen, like tap; the engines differ as in longPress.
189
+ */
190
+ declare function swipe(locator: Locator, dx: number, dy: number, options?: { timeout?: number; sourcePosition?: { x?: number; y?: number }; durationMs?: number; timeoutMs?: number }): void;
163
191
 
164
192
  /**
165
193
  * uploadFile(locator, files)
@@ -210,6 +238,20 @@ declare function assertVisible(locator: Locator, options?: { timeout?: number; t
210
238
  */
211
239
  declare function assertHidden(locator: Locator, options?: { timeout?: number; timeoutMs?: number }): void;
212
240
 
241
+ /**
242
+ * assertInViewport(locator, { ratio?, timeoutMs? })
243
+ *
244
+ * Element intersects the viewport — the visible area of the page, with scroll containers that clip it. `ratio` (0..1): at least that share of the element is in view; absent — any part. Waits like the other asserts; scrolls nothing. Visible but scrolled away fails here, while assertVisible passes.
245
+ */
246
+ declare function assertInViewport(locator: Locator, options?: { timeout?: number; ratio?: number; timeoutMs?: number }): void;
247
+
248
+ /**
249
+ * assertNoFocusZoom(scope?, { minFontPx?, timeoutMs? })
250
+ *
251
+ * No text field zooms the page on focus on iOS: Safari zooms into a field whose text is under 16px and stays zoomed. Reads every visible, enabled, writable input, textarea, select and contenteditable in `scope` (the page when absent; the options may take its place): computed font size times the page scale, against `minFontPx` (default 16). A viewport meta with maximum-scale at 1 or below forbids the zoom, and the check passes. Waits like the other asserts. No browser engine does the zoom itself, so this reads its cause; run it on an iPhone device preset. The on-screen keyboard is not emulated: a composer hidden under it is not caught.
252
+ */
253
+ declare function assertNoFocusZoom(scopeOrOptions?: Locator | { timeout?: number; minFontPx?: number; timeoutMs?: number }, options?: { timeout?: number; minFontPx?: number; timeoutMs?: number }): void;
254
+
213
255
  /**
214
256
  * assertNeverAppears(locator, { withinMs })
215
257
  *
@@ -421,11 +463,11 @@ declare function setPageHidden(hidden: boolean, index?: number): void;
421
463
  declare function newPage(url?: string): number;
422
464
 
423
465
  /**
424
- * closePage(index?)
466
+ * closePage(index?, {beforeUnload?}?)
425
467
  *
426
- * Close a tab; no index: the active one. Closing the active tab makes the tab that was active before it active again. The only open tab cannot be closed.
468
+ * Close a tab; no index: the active one. Closing the active tab makes the tab that was active before it active again. Without options the only open tab cannot be closed. {beforeUnload: 'leave' | 'stay'} closes as a person does: the page's beforeunload runs and its "Leave site?" gets that answer, whatever the dialog policy; 'stay' keeps the tab and the active page. With it the only open tab closes too: a blank tab is left at index 0 and the scenario goes on there. A browser asks only after real user input on the page: a click (a fill alone does not count in Firefox). Returns {asked, closed}; without the option the tab closes with no prompt: {asked: false, closed: true}.
427
469
  */
428
- declare function closePage(index?: number): void;
470
+ declare function closePage(indexOrOptions?: number | { beforeUnload?: "leave" | "stay" }, options?: { beforeUnload?: "leave" | "stay" }): any;
429
471
 
430
472
  /**
431
473
  * setViewport({width, height})
@@ -442,11 +484,11 @@ declare function setViewport(size: { width?: number; height?: number } | null):
442
484
  declare function emulateMedia(media: { reducedMotion?: "reduce" | "no-preference"; colorScheme?: "light" | "dark" | "no-preference" }): void;
443
485
 
444
486
  /**
445
- * newContext({ profile?, cdpEndpoint? }) → number
487
+ * newContext({ profile?, cdpEndpoint?, headers?, viewport? }) → number
446
488
  *
447
- * Open another browser context — a separate client with its own cookies, storage and tabs — and make it active. Returns its number (the run's own is 0). With `profile: '<dir>'` the context runs on a browser profile of its own in that directory (a relative one starts at the project root; made if missing, kept after the run): two devices side by side, each keeping what it stored. The same directory twice in a run is refused. With `cdpEndpoint: 'http://<ip>:9222'` the context opens in a Chrome somebody else started with remote debugging (a VM's browser: `vmRun` gives the address) and the test only disconnects at the end; it cannot be combined with `profile`.
489
+ * Open another browser context — a separate client with its own cookies, storage and tabs — and make it active. Returns its number (the run's own is 0). With `profile: '<dir>'` the context runs on a browser profile of its own in that directory (a relative one starts at the project root; made if missing, kept after the run): two devices side by side, each keeping what it stored. The same directory twice in a run is refused. With `cdpEndpoint: 'http://<ip>:9222'` the context opens in a Chrome somebody else started with remote debugging (a VM's browser: `vmRun` gives the address) and the test only disconnects at the end; it cannot be combined with `profile`. With `headers: { Authorization: API_TOKEN }` every page of the new context sends those request headers with every request — a host that lets the app in by a token; the run's own context does not. With `viewport: { width, height, deviceScaleFactor }` (all optional, the config's fields) the new context opens on that window instead of the config's — the whole of it: a scale not given is 1, and the config's `device` is not applied under it; the scale is fixed when a context opens, so this is the way to a second one in a scenario. A stray field or a value that is not a positive number is refused, naming the fields.
448
490
  */
449
- declare function newContext(options?: { profile?: string; cdpEndpoint?: string }): number;
491
+ declare function newContext(options?: { profile?: string; cdpEndpoint?: string; headers?: any; viewport?: { width?: number; height?: number; deviceScaleFactor?: number } }): number;
450
492
 
451
493
  /**
452
494
  * setContext(index)
@@ -948,7 +990,7 @@ declare function contentFrame(frame?: Locator): Locator;
948
990
  /**
949
991
  * getAttribute(locator, name) → string
950
992
  *
951
- * Attribute value ("" if missing). Boolean attributes (disabled, readonly) read "" whether present or absent — use isDisabled / hasAttribute for those.
993
+ * Attribute value ("" if missing, never null — so `== null` is never true; check presence with hasAttribute). Boolean attributes (disabled, readonly) read "" whether present or absent — use isDisabled / hasAttribute for those.
952
994
  */
953
995
  declare function getAttribute(locator: Locator, attribute: string): string;
954
996
 
@@ -1127,6 +1169,20 @@ declare function waitForResponse(glob: string, options?: { status?: number; meth
1127
1169
  */
1128
1170
  declare function waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any;
1129
1171
 
1172
+ /**
1173
+ * waitForWebSocketFrame(glob, { direction?, match?, timeoutMs? }) → { url, direction, text, json, at }
1174
+ *
1175
+ * Wait for a frame of a WebSocket of the active page whose URL matches `glob`, and take it: the next call gives the next frame. Frames are kept from the socket's first one, so a frame the page sent on open, before the call, counts; a new document starts the list again. `direction` is 'sent' (by the page) or 'received'; `match` is a JSON key filter on the frame's `json` (scalar values, dot paths: `{type: 'hello'}`, `{'user.id': 2}`). `json` is the text parsed, null when it is not JSON; a binary frame has `size` (bytes) instead of `text`; `at` is epoch ms. A timeout names the sockets and the last frames. Default timeout 20 s.
1176
+ */
1177
+ declare function waitForWebSocketFrame(glob: string, options?: { direction?: any; match?: any; timeoutMs?: number }): any;
1178
+
1179
+ /**
1180
+ * webSocketFrames(glob, { direction? }) → [{ url, direction, text, json, at }]
1181
+ *
1182
+ * Every frame kept of the active page's WebSockets whose URL matches `glob`, oldest first, from the page's last load on; takes none, so waitForWebSocketFrame still gives them. The oldest go first past 1000 frames a tab.
1183
+ */
1184
+ declare function webSocketFrames(glob: string, options?: { direction?: any }): any;
1185
+
1130
1186
  /**
1131
1187
  * networkEntries({ since?, glob? }) → [{ url, method, status, ok, headers, failureText?, mocked?, requestJson, responseJson, responseText, truncated?, at }]
1132
1188
  *
@@ -1246,6 +1302,20 @@ declare function mcpStart(command: string, args?: string[], options?: { env?: an
1246
1302
  */
1247
1303
  declare function mcpCall(server: any, tool: string, args?: any, options?: { timeoutMs?: number; allowError?: any }): any;
1248
1304
 
1305
+ /**
1306
+ * mcpCallStart(server, tool, args?) → call
1307
+ *
1308
+ * Send a tool call and go on without waiting for its answer — for a tool that waits on something the test does next, like a person's answer on a card. Take the answer with mcpCallResult. A call never taken is a warning in the run when the server stops, not a failure.
1309
+ */
1310
+ declare function mcpCallStart(server: any, tool: string, args?: any): any;
1311
+
1312
+ /**
1313
+ * mcpCallResult(call, { timeoutMs?, allowError? }) → { content, structuredContent?, isError? }
1314
+ *
1315
+ * Wait for the answer of a call mcpCallStart sent and return it, as mcpCall would. `timeoutMs` (default 30 s) counts from this step; running out cancels the call — there is no polling with short waits. Each call's result is taken once.
1316
+ */
1317
+ declare function mcpCallResult(call: any, options?: { timeoutMs?: number; allowError?: any }): any;
1318
+
1249
1319
  /**
1250
1320
  * mcpWaitNotification(server, method, { match?, timeoutMs? }) → params
1251
1321
  *