@unotest/web 0.49.2 → 0.51.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.
@@ -10,7 +10,7 @@ interface Locator {
10
10
  *
11
11
  * Keep matches by contained text or a nested child locator.
12
12
  */
13
- filter(options: any): Locator;
13
+ filter(options: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator;
14
14
  /**
15
15
  * first(locator)
16
16
  *
@@ -40,43 +40,43 @@ interface Locator {
40
40
  *
41
41
  * Match by raw CSS selector. Last resort — the linter warns on deep/brittle CSS. Options narrow the matches exactly as filter() does.
42
42
  */
43
- locator(selector: string, options?: any): Locator;
43
+ locator(selector: string, options?: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator;
44
44
  /**
45
45
  * getByRole(role, { name?, exact?, checked?, disabled?, expanded?, includeHidden?, level?, pressed?, selected? })
46
46
  *
47
47
  * Match by ARIA role + accessible name. `name` accepts a string or `/regex/`; the state options narrow by ARIA state (`{disabled: false}` skips a disabled button). Any other key is refused.
48
48
  */
49
- getByRole(role: string, options?: any): Locator;
49
+ getByRole(role: string, options?: { name?: string | RegExp; exact?: boolean; checked?: boolean; disabled?: boolean; expanded?: boolean; includeHidden?: boolean; level?: number; pressed?: boolean; selected?: boolean }): Locator;
50
50
  /**
51
51
  * getByText(text, { exact? })
52
52
  *
53
53
  * Match by visible text content.
54
54
  */
55
- getByText(text: string | RegExp, options?: any): Locator;
55
+ getByText(text: string | RegExp, options?: { exact?: boolean }): Locator;
56
56
  /**
57
57
  * getByLabel(text, { exact? })
58
58
  *
59
59
  * Match a form control by its associated label.
60
60
  */
61
- getByLabel(text: string | RegExp, options?: any): Locator;
61
+ getByLabel(text: string | RegExp, options?: { exact?: boolean }): Locator;
62
62
  /**
63
63
  * getByPlaceholder(text, { exact? })
64
64
  *
65
65
  * Match an input by its placeholder.
66
66
  */
67
- getByPlaceholder(text: string | RegExp, options?: any): Locator;
67
+ getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): Locator;
68
68
  /**
69
69
  * getByAltText(text, { exact? })
70
70
  *
71
71
  * Match an image by its `alt` text.
72
72
  */
73
- getByAltText(text: string | RegExp, options?: any): Locator;
73
+ getByAltText(text: string | RegExp, options?: { exact?: boolean }): Locator;
74
74
  /**
75
75
  * getByTitle(text, { exact? })
76
76
  *
77
77
  * Match by `title` attribute.
78
78
  */
79
- getByTitle(text: string | RegExp, options?: any): Locator;
79
+ getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator;
80
80
  /**
81
81
  * getByTestId(id)
82
82
  *
@@ -92,74 +92,74 @@ interface Locator {
92
92
  }
93
93
 
94
94
  /**
95
- * click(locator, { force?, timeout?, position?, modifiers?, button?, clickCount? })
95
+ * click(locator, { force?, timeoutMs?, position?, modifiers?, button?, clickCount? })
96
96
  *
97
97
  * Click an element.
98
98
  */
99
- declare function click(locator: Locator, options?: any): void;
99
+ declare function click(locator: Locator, options?: { timeout?: number; force?: boolean; position?: any; modifiers?: unknown[]; button?: any; clickCount?: number; timeoutMs?: number }): void;
100
100
 
101
101
  /**
102
- * doubleClick(locator, { force?, timeout? })
102
+ * doubleClick(locator, { force?, position?, modifiers?, timeoutMs? })
103
103
  *
104
104
  * Double-click an element.
105
105
  */
106
- declare function doubleClick(locator: Locator, options?: any): void;
106
+ declare function doubleClick(locator: Locator, options?: { timeout?: number; force?: boolean; position?: any; modifiers?: unknown[]; timeoutMs?: number }): void;
107
107
 
108
108
  /**
109
- * check(locator, { force?, timeout? })
109
+ * check(locator, { force?, timeoutMs? })
110
110
  *
111
111
  * Check a checkbox/radio/switch: click, then wait until it reads checked (a controlled widget may flip a beat later). Already checked → no click.
112
112
  */
113
- declare function check(locator: Locator, options?: any): void;
113
+ declare function check(locator: Locator, options?: { timeout?: number; force?: boolean; timeoutMs?: number }): void;
114
114
 
115
115
  /**
116
- * uncheck(locator, { force?, timeout? })
116
+ * uncheck(locator, { force?, timeoutMs? })
117
117
  *
118
118
  * Uncheck a checkbox/switch: click, then wait until it reads unchecked. Already unchecked → no click.
119
119
  */
120
- declare function uncheck(locator: Locator, options?: any): void;
120
+ declare function uncheck(locator: Locator, options?: { timeout?: number; force?: boolean; timeoutMs?: number }): void;
121
121
 
122
122
  /**
123
- * hover(locator, { force?, position?, timeout? })
123
+ * hover(locator, { force?, position?, timeoutMs? })
124
124
  *
125
125
  * Hover over an element. `position` is an {x, y} offset inside it — for a menu that only appears at one edge of a tall element.
126
126
  */
127
- declare function hover(locator: Locator, options?: any): void;
127
+ declare function hover(locator: Locator, options?: { timeout?: number; force?: boolean; position?: any; timeoutMs?: number }): void;
128
128
 
129
129
  /**
130
130
  * scrollIntoView(locator)
131
131
  *
132
132
  * Scroll an element into the viewport.
133
133
  */
134
- declare function scrollIntoView(locator: Locator, options?: any): void;
134
+ declare function scrollIntoView(locator: Locator): void;
135
135
 
136
136
  /**
137
- * fill(locator, value, { force?, timeout? })
137
+ * fill(locator, value, { force?, timeoutMs? })
138
138
  *
139
139
  * Clear and type a value into an input.
140
140
  */
141
- declare function fill(locator: Locator, text: string, options?: any): void;
141
+ declare function fill(locator: Locator, text: string, options?: { timeout?: number; force?: boolean; timeoutMs?: number }): void;
142
142
 
143
143
  /**
144
- * press(locator, key, { delay?, timeout? })
144
+ * press(locator, key, { delay?, timeoutMs? })
145
145
  *
146
146
  * Press a key (e.g. 'Enter', 'Control+A').
147
147
  */
148
- declare function press(locator: Locator, key: string, options?: any): void;
148
+ declare function press(locator: Locator, key: string, options?: { timeout?: number; delay?: number; timeoutMs?: number }): void;
149
149
 
150
150
  /**
151
- * selectOption(locator, value, { timeout? })
151
+ * selectOption(locator, value, { force?, timeoutMs? })
152
152
  *
153
- * Select option(s) in a `<select>`. `value` is a string or string[].
153
+ * Select option(s) in a `<select>`. `value` is the option's value (a string, {value}, or string[] for a multi-select), its visible text {label: 'Dark blue'}, or its position {index: 0}. Waits for the option; a {label} or {index} no option has fails naming the labels the element holds.
154
154
  */
155
- declare function selectOption(locator: Locator, value: any): void;
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?, timeout? })
158
+ * dragAndDrop(from, to, { force?, timeoutMs? })
159
159
  *
160
160
  * Drag one element onto another. Uses synthetic mouse events (not native HTML5 DragEvent).
161
161
  */
162
- declare function dragAndDrop(source: Locator, target: Locator): void;
162
+ declare function dragAndDrop(source: Locator, target: Locator, options?: { timeout?: number; force?: boolean; timeoutMs?: number }): void;
163
163
 
164
164
  /**
165
165
  * uploadFile(locator, files)
@@ -176,67 +176,67 @@ declare function uploadFile(input: Locator, files: any): void;
176
176
  declare function clipboardPaste(target: Locator, text: string): void;
177
177
 
178
178
  /**
179
- * assertText(locator, expected, { exact?, not?, timeout? })
179
+ * assertText(locator, expected, { exact?, not?, timeoutMs? })
180
180
  *
181
181
  * Element's text equals `expected` (a string; exact: false — contains it) or matches it (a /regex/). {not: true} waits until it no longer does. Empty: assertText(loc, ''); not empty: assertText(loc, '', {not: true}).
182
182
  */
183
- declare function assertText(locator: Locator, text: string | RegExp, options?: any): void;
183
+ declare function assertText(locator: Locator, text: string | RegExp, options?: { timeout?: number; exact?: boolean; not?: boolean; timeoutMs?: number }): void;
184
184
 
185
185
  /**
186
- * assertTexts(locator, expected, { exact?, timeout? })
186
+ * assertTexts(locator, expected, { exact?, timeoutMs? })
187
187
  *
188
188
  * The locator matches exactly expected.length elements, and element i's text matches expected[i] (string or /regex/, same rules as assertText), in order.
189
189
  */
190
- declare function assertTexts(locator: Locator, expected: unknown[], options?: any): void;
190
+ declare function assertTexts(locator: Locator, expected: unknown[], options?: { timeout?: number; exact?: boolean; timeoutMs?: number }): void;
191
191
 
192
192
  /**
193
- * assertAttribute(locator, name, expected, { exact?, not?, timeout? })
193
+ * assertAttribute(locator, name, expected, { exact?, not?, timeoutMs? })
194
194
  *
195
195
  * Polls the attribute `name` until it equals `expected` (exact: false — contains) or matches a /regex/. An absent attribute matches nothing. {not: true} waits until it no longer matches or is gone.
196
196
  */
197
- declare function assertAttribute(locator: Locator, name: string, value: string | RegExp, options?: any): void;
197
+ declare function assertAttribute(locator: Locator, name: string, value: string | RegExp, options?: { timeout?: number; exact?: boolean; not?: boolean; timeoutMs?: number }): void;
198
198
 
199
199
  /**
200
- * assertVisible(locator, { timeout? })
200
+ * assertVisible(locator, { timeoutMs? })
201
201
  *
202
202
  * Element is visible.
203
203
  */
204
- declare function assertVisible(locator: Locator, options?: any): void;
204
+ declare function assertVisible(locator: Locator, options?: { timeout?: number; timeoutMs?: number }): void;
205
205
 
206
206
  /**
207
- * assertHidden(locator, { timeout? })
207
+ * assertHidden(locator, { timeoutMs? })
208
208
  *
209
209
  * Element is hidden or detached.
210
210
  */
211
- declare function assertHidden(locator: Locator, options?: any): void;
211
+ declare function assertHidden(locator: Locator, options?: { timeout?: number; timeoutMs?: number }): void;
212
212
 
213
213
  /**
214
214
  * assertNeverAppears(locator, { withinMs })
215
215
  *
216
216
  * Negative window assert: FAIL the moment the locator becomes visible; pass when the whole window elapsed clean. withinMs required; the step always costs that long.
217
217
  */
218
- declare function assertNeverAppears(locator: Locator, options: any): void;
218
+ declare function assertNeverAppears(locator: Locator, options: { withinMs?: number }): void;
219
219
 
220
220
  /**
221
- * assertValue(locator, expected, { timeout? })
221
+ * assertValue(locator, expected, { timeoutMs? })
222
222
  *
223
223
  * Input's value equals `expected`. On a checkbox/radio/switch: its checked state — pass 'true' or 'false'.
224
224
  */
225
- declare function assertValue(locator: Locator, value: string, options?: any): void;
225
+ declare function assertValue(locator: Locator, value: string, options?: { timeout?: number; timeoutMs?: number }): void;
226
226
 
227
227
  /**
228
- * assertCount(locator, expected, { timeout? })
228
+ * assertCount(locator, expected, { timeoutMs? })
229
229
  *
230
230
  * Number of matches equals `expected`.
231
231
  */
232
- declare function assertCount(locator: Locator, count: number, options?: any): void;
232
+ declare function assertCount(locator: Locator, count: number, options?: { timeout?: number; timeoutMs?: number }): void;
233
233
 
234
234
  /**
235
- * assertUrl(pattern, { timeout? })
235
+ * assertUrl(pattern, { timeoutMs? })
236
236
  *
237
237
  * Current URL contains `pattern` (a string) or matches it (a /regex/, unanchored). A failure names the pattern as /source/flags.
238
238
  */
239
- declare function assertUrl(pattern: string | RegExp, options?: any): void;
239
+ declare function assertUrl(pattern: string | RegExp, options?: { timeout?: number; timeoutMs?: number }): void;
240
240
 
241
241
  /**
242
242
  * assertJudge(locator, rubric)
@@ -250,7 +250,7 @@ declare function assertJudge(locator: Locator, rubric: string): void;
250
250
  *
251
251
  * The page (or an element) against the PNG baseline unotest/e2e/<scenario>.screenshots/<name>.png. A pixel differs when any channel differs by more than threshold (default 32); fails when the share of differing pixels is MORE than maxDiffRatio (default 0). mask: locators, ignore: rectangles in baseline pixels — both left out of the comparison. No baseline: fails and saves the snapshot as a candidate; accept with e2e --update-screenshots. On failure the run keeps expected / actual / diff.
252
252
  */
253
- declare function assertScreenshot(nameOrLocator: any, nameOrOptions?: any, options?: any): void;
253
+ declare function assertScreenshot(nameOrLocator: any, nameOrOptions?: any, options?: { maxDiffRatio?: number; threshold?: number; mask?: unknown[]; ignore?: unknown[]; fullPage?: boolean }): void;
254
254
 
255
255
  /**
256
256
  * assertEqual(actual, expected)
@@ -273,6 +273,20 @@ declare function assertTrue(condition: boolean, message?: string): void;
273
273
  */
274
274
  declare function assertSchema(value: any, schema: any): void;
275
275
 
276
+ /**
277
+ * assertFileHas(path, needle, { timeoutMs? })
278
+ *
279
+ * A string or a regex must appear in a file, or anywhere in a directory (searched recursively; symlinks inside are not followed). Polls until found; options: {timeoutMs} (default 20s). A string is searched as bytes, so binary files count; a regex reads the file as UTF-8. A miss FAILS saying how many files and bytes it searched.
280
+ */
281
+ declare function assertFileHas(path: string, needle: string | RegExp, options?: { timeoutMs?: number }): void;
282
+
283
+ /**
284
+ * assertFileLacks(path, needle, { withinMs? })
285
+ *
286
+ * A string or a regex must NOT appear in a file or a directory tree — a secret in a log or a DB dump. Searches once; {withinMs} watches that window instead. A hit FAILS naming the file and line, the matched bytes replaced by ‹match, N bytes›. A path that does not exist FAILS too: nothing searched proves nothing.
287
+ */
288
+ declare function assertFileLacks(path: string, needle: string | RegExp, options?: { withinMs?: number }): void;
289
+
276
290
  /**
277
291
  * skip(reason, condition?)
278
292
  *
@@ -292,7 +306,7 @@ declare function setTestTimeout(ms: number): void;
292
306
  *
293
307
  * Keep matches by contained text or a nested child locator.
294
308
  */
295
- declare function filter(receiver: Locator, options: any): Locator;
309
+ declare function filter(receiver: Locator, options: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator;
296
310
 
297
311
  /**
298
312
  * first(locator)
@@ -327,7 +341,7 @@ declare function randomNth(receiver: Locator): Locator;
327
341
  *
328
342
  * Capture the active page into the run's artifact dir; returns the project-relative path. For a PNG after EVERY step without calling it, set UNOTEST_STEP_SCREENSHOTS=1 in the run's environment.
329
343
  */
330
- declare function screenshot(name?: string, options?: any): string;
344
+ declare function screenshot(name?: string, options?: { fullPage?: boolean }): string;
331
345
 
332
346
  /**
333
347
  * note(label, value)
@@ -341,49 +355,49 @@ declare function note(label: string, value: any): void;
341
355
  *
342
356
  * What the active page wrote to its console, oldest first: `level` is log, info, warn, error or debug. Recorded from the moment the page opened, so act first, then ask. Extension pages (chrome-extension://) too. options: {level} (one level or a list), {since} (epoch ms, from nowMs()).
343
357
  */
344
- declare function consoleEntries(options?: any): any;
358
+ declare function consoleEntries(options?: { level?: any; since?: number }): any;
345
359
 
346
360
  /**
347
361
  * pageErrors({ since? }) → [{ message, stack }]
348
362
  *
349
363
  * Errors the active page threw and nothing caught (an uncaught exception, a rejected promise), oldest first; `stack` is empty when the browser gave none. options: {since} (epoch ms, from nowMs()).
350
364
  */
351
- declare function pageErrors(options?: any): any;
365
+ declare function pageErrors(options?: { since?: number }): any;
352
366
 
353
367
  /**
354
368
  * assertNoConsoleErrors({ includePageErrors?, since? })
355
369
  *
356
370
  * FAIL when the active page logged console errors, or threw uncaught ones (unless {includePageErrors: false}), quoting the first three. With `since` (epoch ms, from nowMs()) only from then on.
357
371
  */
358
- declare function assertNoConsoleErrors(options?: any): void;
372
+ declare function assertNoConsoleErrors(options?: { includePageErrors?: boolean; since?: number }): void;
359
373
 
360
374
  /**
361
375
  * evaluate(js, arg?) → any
362
376
  *
363
377
  * Run raw JS in the page context. Last resort — prefer typed helpers. Returns JSON-serializable values only. Extra arguments reach the body as: none → nothing, exactly one → the value itself, two or more → ONE array (destructure `([a, b]) => …`).
364
378
  */
365
- declare function evaluate(jsBody: string, ...args: unknown[]): any;
379
+ declare function evaluate(jsBody: any, ...args: unknown[]): any;
366
380
 
367
381
  /**
368
382
  * evaluateOnLocator(locator, js, ...args) → any
369
383
  *
370
384
  * Like evaluate, on the matched element: the body is called with the element, then the extra arguments by the same rule (`(el, x) => …`, two or more → `(el, [a, b]) => …`). Last resort — prefer typed getters.
371
385
  */
372
- declare function evaluateOnLocator(locator: Locator, jsBody: string, ...args: unknown[]): any;
386
+ declare function evaluateOnLocator(locator: Locator, jsBody: any, ...args: unknown[]): any;
373
387
 
374
388
  /**
375
389
  * setPage(index, options?)
376
390
  *
377
391
  * Switch the active tab/page by index (0-based) and bring it to front. {activate: false} switches only the tab the steps act on and leaves the visible tab as is.
378
392
  */
379
- declare function setPage(indexOrTitle: string | number, options?: any): void;
393
+ declare function setPage(indexOrTitle: string | number, options?: { activate?: boolean }): void;
380
394
 
381
395
  /**
382
396
  * waitForPage(options?) → number
383
397
  *
384
398
  * Wait for a tab the scenario has not been handed yet (window.open, target=_blank, an extension), switch to it and return its index. Counts a tab that opened before the call. {timeoutMs} defaults to the navigation timeout.
385
399
  */
386
- declare function waitForPage(options?: any): number;
400
+ declare function waitForPage(options?: { timeoutMs?: number }): number;
387
401
 
388
402
  /**
389
403
  * bringToFront(index?)
@@ -392,6 +406,13 @@ declare function waitForPage(options?: any): number;
392
406
  */
393
407
  declare function bringToFront(index?: number): void;
394
408
 
409
+ /**
410
+ * setPageHidden(hidden, index?)
411
+ *
412
+ * Emulates the tab's visibility for its scripts: true sends it to the background (document.hidden, visibilityState 'hidden', blur + visibilitychange), false brings it back. Stays across navigations. Timers, animation frames and freeze are not emulated. No index: the active tab.
413
+ */
414
+ declare function setPageHidden(hidden: boolean, index?: number): void;
415
+
395
416
  /**
396
417
  * newPage(url?) → number
397
418
  *
@@ -411,14 +432,14 @@ declare function closePage(index?: number): void;
411
432
  *
412
433
  * Resize every tab of the browser, and the ones it opens later, without reloading. The scale (deviceScaleFactor) is set in the config, not here.
413
434
  */
414
- declare function setViewport(size: any): void;
435
+ declare function setViewport(size: { width?: number; height?: number } | null): void;
415
436
 
416
437
  /**
417
438
  * emulateMedia({ reducedMotion?, colorScheme? })
418
439
  *
419
440
  * 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'. This tab only: a tab or popup opened later starts without it.
420
441
  */
421
- declare function emulateMedia(media: any): void;
442
+ declare function emulateMedia(media: { reducedMotion?: "reduce" | "no-preference"; colorScheme?: "light" | "dark" | "no-preference" }): void;
422
443
 
423
444
  /**
424
445
  * newContext() → number
@@ -449,46 +470,95 @@ declare function enterFrame(frame: Locator): void;
449
470
  declare function exitFrame(): void;
450
471
 
451
472
  /**
452
- * goto(url, { waitUntil?, timeout? })
473
+ * addVirtualAuthenticator({ protocol?, transport?, hasResidentKey?, hasUserVerification?, isUserVerified?, automaticPresenceSimulation? }) → id
474
+ *
475
+ * A passkey without a person at a device: a virtual WebAuthn authenticator on the active tab answers navigator.credentials.create/get. Default: a phone or laptop passkey (ctap2, internal, resident key, verified user, no touch needed). Chromium only; the page must be https or localhost. A tab opened later does not see it.
476
+ */
477
+ declare function addVirtualAuthenticator(options?: { protocol?: string; transport?: string; hasResidentKey?: boolean; hasUserVerification?: boolean; isUserVerified?: boolean; automaticPresenceSimulation?: boolean }): string;
478
+
479
+ /**
480
+ * virtualCredentials(id?) → [{ credentialId, rpId, userHandle, signCount, resident }]
453
481
  *
454
- * Navigate to a URL. `waitUntil`: 'load' | 'domcontentloaded' | 'networkidle'. Relative paths resolve against `baseUrl`.
482
+ * The credentials a virtual authenticator holds — one, or all of them. Ids are base64url, as the page sees them; signCount grows with each sign-in.
455
483
  */
456
- declare function goto(url: string, options?: any): void;
484
+ declare function virtualCredentials(id?: string): any;
457
485
 
458
486
  /**
459
- * reload({ waitUntil?, timeout? })
487
+ * removeVirtualAuthenticator(id)
488
+ *
489
+ * Take a virtual authenticator off; its passkeys go with it. Optional: the context's close removes them all.
490
+ */
491
+ declare function removeVirtualAuthenticator(id: string): void;
492
+
493
+ /**
494
+ * grantPermissions(permissions, { origin? })
495
+ *
496
+ * Grant browser permissions to the context — ['notifications'], ['geolocation'] — for every origin or {origin}. A name the engine does not know fails naming the engine; earlier grants stay.
497
+ */
498
+ declare function grantPermissions(permissions: string[], options?: { origin?: string }): void;
499
+
500
+ /**
501
+ * setOffline(offline)
502
+ *
503
+ * setOffline(true) cuts every page of the context off the network; setOffline(false) connects it again. Undone when the context closes.
504
+ */
505
+ declare function setOffline(offline: boolean): void;
506
+
507
+ /**
508
+ * goto(url, { waitUntil?, timeoutMs? })
509
+ *
510
+ * Navigate to a URL. `waitUntil`: 'load' | 'domcontentloaded' | 'networkidle' | 'commit'. Relative paths resolve against `baseUrl`.
511
+ */
512
+ declare function goto(url: string, options?: { timeout?: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void;
513
+
514
+ /**
515
+ * reload({ waitUntil?, timeoutMs? })
460
516
  *
461
517
  * Reload the current page.
462
518
  */
463
- declare function reload(options?: any): void;
519
+ declare function reload(options?: { timeout?: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void;
464
520
 
465
521
  /**
466
- * goBack({ timeout? })
522
+ * goBack({ waitUntil?, timeoutMs? })
467
523
  *
468
524
  * Navigate back in history.
469
525
  */
470
- declare function goBack(): void;
526
+ declare function goBack(options?: { timeout?: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void;
471
527
 
472
528
  /**
473
- * goForward({ timeout? })
529
+ * goForward({ waitUntil?, timeoutMs? })
474
530
  *
475
531
  * Navigate forward in history.
476
532
  */
477
- declare function goForward(): void;
533
+ declare function goForward(options?: { timeout?: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void;
478
534
 
479
535
  /**
480
- * waitForUrl(pattern, { timeout? })
536
+ * waitForUrl(pattern, { waitUntil?, timeoutMs? })
481
537
  *
482
538
  * Wait until the URL contains `pattern` (a string, substring match) or matches it (a /regex/, unanchored).
483
539
  */
484
- declare function waitForUrl(pattern: string | RegExp, options?: any): void;
540
+ declare function waitForUrl(pattern: string | RegExp, options?: { timeout?: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit"; timeoutMs?: number }): void;
485
541
 
486
542
  /**
487
- * waitForNavigation({ timeout? })
543
+ * waitForNavigation({ timeoutMs? })
488
544
  *
489
545
  * Wait for the next navigation event.
490
546
  */
491
- declare function waitForNavigation(options?: any): void;
547
+ declare function waitForNavigation(options?: { timeout?: number; timeoutMs?: number }): void;
548
+
549
+ /**
550
+ * clipboardRead() → string
551
+ *
552
+ * The clipboard's text as the active page reads it — what a 'copy' button left there. Chromium and Firefox, on an https or localhost page; WebKit refuses with an error, never an empty string. No wait: use assertClipboard for a write that lands after the click.
553
+ */
554
+ declare function clipboardRead(): string;
555
+
556
+ /**
557
+ * assertClipboard(expected, { timeoutMs? })
558
+ *
559
+ * Wait until the clipboard holds `expected`: the whole text for a string, a match for a regex. options: {timeoutMs} (default 5s). Same engines as clipboardRead.
560
+ */
561
+ declare function assertClipboard(expected: string | RegExp, options?: { timeoutMs?: number }): void;
492
562
 
493
563
  /**
494
564
  * count(locator) → number
@@ -574,6 +644,13 @@ declare function getImageSize(locator: Locator): any;
574
644
  */
575
645
  declare function hasAnimation(locator: Locator): boolean;
576
646
 
647
+ /**
648
+ * animations(locator) → [{ name, kind, playState, currentTime?, infinite }]
649
+ *
650
+ * Every animation of the element and its descendants: `name` is the @keyframes name, the transitioned property or a script animation's id; `kind` is animation, transition or script; `playState` is running, paused, finished or idle; `currentTime` in ms, left out when it has none; `infinite` for one that repeats forever. Infinite and paused ones are listed too — hasAnimation counts only `playState: 'running'` with `infinite: false`.
651
+ */
652
+ declare function animations(locator: Locator): any;
653
+
577
654
  /**
578
655
  * randomFirstName() → string
579
656
  *
@@ -677,7 +754,7 @@ declare function urlParam(url: string, key: string): any;
677
754
  *
678
755
  * A number as a page writes it: '1 234,5', '1,234.56', '−12'. Spaces (NBSP too) group digits; with both ',' and '.' the last one is the decimal mark; one mark used twice groups. '1,234' and '1.234' read both ways and FAIL unless {decimal: ',' | '.'} says which. Units and currency ('440px', '€12') FAIL, quoting the input — cut the number out with textMatches first. A number passes through.
679
756
  */
680
- declare function toNumber(text: any, options?: any): number;
757
+ declare function toNumber(text: any, options?: { decimal?: string }): number;
681
758
 
682
759
  /**
683
760
  * round(n, digits?) → number
@@ -691,7 +768,7 @@ declare function round(n: number, digits?: number): number;
691
768
  *
692
769
  * A number as text, via Intl.NumberFormat with digit grouping. Without a locale it is en-US on every machine: formatNumber(1234.5) → '1,234.5'. Another locale's output (its spaces and marks) comes from the ICU of the Node that runs it.
693
770
  */
694
- declare function formatNumber(n: number, options?: any): string;
771
+ declare function formatNumber(n: number, options?: { locale?: string; minFractionDigits?: number; maxFractionDigits?: number }): string;
695
772
 
696
773
  /**
697
774
  * env(name, fallback?) → string | fallback | null
@@ -712,28 +789,28 @@ declare function shell(cmd: string, ...args: unknown[]): any;
712
789
  *
713
790
  * Poll a file (relative to config `shellCwd`) until it exists / contains a substring or regex, then return its content. options: {timeoutMs} (default 20s). The waitForText of background processes.
714
791
  */
715
- declare function waitForFile(path: string, pattern?: any, options?: any): string;
792
+ declare function waitForFile(path: string, pattern?: any, options?: { timeoutMs?: number }): string;
716
793
 
717
794
  /**
718
795
  * assertNoFile(path, pattern?, { withinMs })
719
796
  *
720
797
  * Mirror of waitForFile with inverted polarity: FAIL the moment the file exists (and matches pattern); pass when the window elapsed clean. withinMs required.
721
798
  */
722
- declare function assertNoFile(path: string, pattern?: any, options?: any): void;
799
+ declare function assertNoFile(path: string, pattern?: any, options?: { withinMs?: number }): void;
723
800
 
724
801
  /**
725
802
  * waitForJsonLine(path, filter, options?) → object
726
803
  *
727
804
  * Wait for a LINE of a JSONL file that matches every key of `filter` (strict equality, dot paths for nesting), then return it parsed. What a substring cannot express: JSON key order is not guaranteed. options: {timeoutMs} (default 20s).
728
805
  */
729
- declare function waitForJsonLine(path: string, filter: any, options?: any): any;
806
+ declare function waitForJsonLine(path: string, filter: any, options?: { timeoutMs?: number }): any;
730
807
 
731
808
  /**
732
809
  * assertNoJsonLine(path, filter, { withinMs })
733
810
  *
734
811
  * Negative twin of waitForJsonLine: FAIL the moment a matching line appears; pass when the window elapsed clean. withinMs required.
735
812
  */
736
- declare function assertNoJsonLine(path: string, filter: any, options?: any): void;
813
+ declare function assertNoJsonLine(path: string, filter: any, options?: { withinMs?: number }): void;
737
814
 
738
815
  /**
739
816
  * readJsonLine(path, filter) → object
@@ -754,7 +831,7 @@ declare function readJson(path: string): any;
754
831
  *
755
832
  * A whole file, read once: its text, or its bytes as base64 with {encoding: 'base64'}. Path is relative to config `shellCwd`, or absolute inside the project or to a file waitForDownload saved (its .path). FAILS at once when the path or a symlink leads out, the file is missing or the encoding is unknown.
756
833
  */
757
- declare function readFile(path: string, options?: any): string;
834
+ declare function readFile(path: string, options?: { encoding?: string }): string;
758
835
 
759
836
  /**
760
837
  * readFileInfo(path) → object
@@ -768,7 +845,7 @@ declare function readFileInfo(path: string): any;
768
845
  *
769
846
  * Wait until AT LEAST `count` lines match, then return how many there are. `pattern` is a substring, a regex or a JSON key filter. options: {timeoutMs} (default 20s).
770
847
  */
771
- declare function waitForFileCount(path: string, pattern: any, count: number, options?: any): number;
848
+ declare function waitForFileCount(path: string, pattern: any, count: number, options?: { timeoutMs?: number }): number;
772
849
 
773
850
  /**
774
851
  * assertFileCount(path, pattern, count)
@@ -792,67 +869,67 @@ declare function dbQuery(sql: string, ...args: unknown[]): any;
792
869
  declare function dbExec(sql: string, ...args: unknown[]): number;
793
870
 
794
871
  /**
795
- * apiCall(method, path, body?, headers?) → { status, body, headers }
872
+ * apiCall(method, path, body?, headers?, { base?, timeoutMs? }) → { status, body, headers }
796
873
  *
797
- * HTTP call. `path` is relative — base is the config `apiBaseUrl`. Multipart: pass upload(...) as the body.
874
+ * HTTP call. `path` is relative — base is the config `apiBaseUrl`, or `{base: 'API_BASE_X'}` names an env variable holding another. Multipart: pass upload(...) as the body. `{timeoutMs}` bounds the whole call, reply body included; past it the request is aborted and the step fails naming the call. Without it the call waits as long as the step does.
798
875
  */
799
- declare function apiCall(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS", path: string, body?: any, headers?: any, options?: any): any;
876
+ declare function apiCall(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS", path: string, body?: any, headers?: any, options?: { base?: string; timeoutMs?: number }): any;
800
877
 
801
878
  /**
802
879
  * upload(path, options?) → UploadRef
803
880
  *
804
881
  * Multipart marker for apiCall's body (options: field, fields). Path is relative to the project root / config `uploadDir`.
805
882
  */
806
- declare function upload(path: string, options?: any): any;
883
+ declare function upload(path: string, options?: { field?: string; fields?: any }): any;
807
884
 
808
885
  /**
809
886
  * locator(css, { hasText?, hasNotText?, has?, hasNot? }?)
810
887
  *
811
888
  * Match by raw CSS selector. Last resort — the linter warns on deep/brittle CSS. Options narrow the matches exactly as filter() does.
812
889
  */
813
- declare function locator(selector: string, options?: any): Locator;
890
+ declare function locator(selector: string, options?: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator;
814
891
 
815
892
  /**
816
893
  * getByRole(role, { name?, exact?, checked?, disabled?, expanded?, includeHidden?, level?, pressed?, selected? })
817
894
  *
818
895
  * Match by ARIA role + accessible name. `name` accepts a string or `/regex/`; the state options narrow by ARIA state (`{disabled: false}` skips a disabled button). Any other key is refused.
819
896
  */
820
- declare function getByRole(role: string, options?: any): Locator;
897
+ declare function getByRole(role: string, options?: { name?: string | RegExp; exact?: boolean; checked?: boolean; disabled?: boolean; expanded?: boolean; includeHidden?: boolean; level?: number; pressed?: boolean; selected?: boolean }): Locator;
821
898
 
822
899
  /**
823
900
  * getByText(text, { exact? })
824
901
  *
825
902
  * Match by visible text content.
826
903
  */
827
- declare function getByText(text: string | RegExp, options?: any): Locator;
904
+ declare function getByText(text: string | RegExp, options?: { exact?: boolean }): Locator;
828
905
 
829
906
  /**
830
907
  * getByLabel(text, { exact? })
831
908
  *
832
909
  * Match a form control by its associated label.
833
910
  */
834
- declare function getByLabel(text: string | RegExp, options?: any): Locator;
911
+ declare function getByLabel(text: string | RegExp, options?: { exact?: boolean }): Locator;
835
912
 
836
913
  /**
837
914
  * getByPlaceholder(text, { exact? })
838
915
  *
839
916
  * Match an input by its placeholder.
840
917
  */
841
- declare function getByPlaceholder(text: string | RegExp, options?: any): Locator;
918
+ declare function getByPlaceholder(text: string | RegExp, options?: { exact?: boolean }): Locator;
842
919
 
843
920
  /**
844
921
  * getByAltText(text, { exact? })
845
922
  *
846
923
  * Match an image by its `alt` text.
847
924
  */
848
- declare function getByAltText(text: string | RegExp, options?: any): Locator;
925
+ declare function getByAltText(text: string | RegExp, options?: { exact?: boolean }): Locator;
849
926
 
850
927
  /**
851
928
  * getByTitle(text, { exact? })
852
929
  *
853
930
  * Match by `title` attribute.
854
931
  */
855
- declare function getByTitle(text: string | RegExp, options?: any): Locator;
932
+ declare function getByTitle(text: string | RegExp, options?: { exact?: boolean }): Locator;
856
933
 
857
934
  /**
858
935
  * getByTestId(id)
@@ -936,7 +1013,7 @@ declare function getLocalStorage(key: string): string;
936
1013
  *
937
1014
  * Set a cookie (options: path, domain, expires, httpOnly, secure, sameSite).
938
1015
  */
939
- declare function setCookie(name: string, value: string, options?: any): void;
1016
+ declare function setCookie(name: string, value: string, options?: { domain?: string; path?: string; expires?: number; httpOnly?: boolean; secure?: boolean; sameSite?: string }): void;
940
1017
 
941
1018
  /**
942
1019
  * getCookie(name) → string
@@ -946,32 +1023,32 @@ declare function setCookie(name: string, value: string, options?: any): void;
946
1023
  declare function getCookie(name: string): string;
947
1024
 
948
1025
  /**
949
- * waitFor(locator, { state?, timeout? })
1026
+ * waitFor(locator, { state?, timeoutMs? })
950
1027
  *
951
1028
  * Wait for an element state: DOM presence ('visible' default, 'hidden', 'attached', 'detached') or interaction ('enabled' / 'disabled' — same probe as isEnabled, so aria-disabled counts).
952
1029
  */
953
- declare function waitFor(locator: Locator, options?: any): void;
1030
+ declare function waitFor(locator: Locator, options?: { timeout?: number; state?: string; timeoutMs?: number }): void;
954
1031
 
955
1032
  /**
956
- * waitForText(text, { first?, timeout? })
1033
+ * waitForText(text, { exact?, state?, timeoutMs? })
957
1034
  *
958
- * Wait until `text` appears anywhere on the page. `first: true` waits for the first VISIBLE occurrence when the text is duplicated (otherwise duplicates fail strict mode).
1035
+ * Wait until `text` appears anywhere on the page. Duplicated text is fine: the wait looks at its first VISIBLE occurrence.
959
1036
  */
960
- declare function waitForText(text: string | RegExp, options?: any): void;
1037
+ declare function waitForText(text: string | RegExp, options?: { timeout?: number; state?: string; exact?: boolean; timeoutMs?: number }): void;
961
1038
 
962
1039
  /**
963
- * waitForCount(locator, count, { exact?, timeout? })
1040
+ * waitForCount(locator, count, { exact?, timeoutMs? })
964
1041
  *
965
1042
  * Poll until the locator matches AT LEAST `count` elements (`{exact: true}` for exactly). Default timeout 5000 ms.
966
1043
  */
967
- declare function waitForCount(locator: Locator, count: number, options?: any): void;
1044
+ declare function waitForCount(locator: Locator, count: number, options?: { timeout?: number; exact?: boolean; timeoutMs?: number }): void;
968
1045
 
969
1046
  /**
970
- * waitForAnimations(locator, { timeout? })
1047
+ * waitForAnimations(locator, { timeoutMs? })
971
1048
  *
972
1049
  * Wait until the element and its descendants have no animation still running — a dialog done fading in, a card done sliding. Infinite ones (spinners) and paused ones are not waited for. Default timeout 5000 ms; a timeout names the element and how many were left.
973
1050
  */
974
- declare function waitForAnimations(locator: Locator, options?: any): void;
1051
+ declare function waitForAnimations(locator: Locator, options?: { timeout?: number; timeoutMs?: number }): void;
975
1052
 
976
1053
  /**
977
1054
  * pause(ms)
@@ -985,7 +1062,7 @@ declare function pause(ms: number): void;
985
1062
  *
986
1063
  * The first file the page downloaded that the scenario has not taken yet, saved with the run: `path` is absolute (read it with waitForFile), `name` is the name the site suggested. Downloads are recorded from the start, so click first, then call this. options: {timeoutMs} (default: the navigation timeout), {name} (substring or regex of the file name).
987
1064
  */
988
- declare function waitForDownload(options?: any): any;
1065
+ declare function waitForDownload(options?: { timeoutMs?: number; name?: string | RegExp }): any;
989
1066
 
990
1067
  /**
991
1068
  * clockFreeze(iso)
@@ -1011,7 +1088,7 @@ declare function clockRun(): void;
1011
1088
  /**
1012
1089
  * mockRoute(glob, response)
1013
1090
  *
1014
- * From now on, requests matching `glob` (a Playwright URL glob: `**\/api/items*`) get a fixed answer: `{status?, body?, headers?, contentType?}` (an object body goes as JSON), `{abort: true, record?}` or `{continue: true}` (to the network). Where several masks match, the one mocked last answers; mocking a mask again replaces its answer. A response to `**\/*` is refused; the site's own page is never aborted. A mask reaches http(s) and ws(s) only, so an extension's own pages and scripts load under `**\/*`; to mock them, start the mask with their scheme (`chrome-extension://<id>/x.js`). Mocks last until the scenario ends.
1091
+ * From now on, requests matching `glob` (a Playwright URL glob: `**\/api/items*`) get a fixed answer: `{status?, body?, headers?, contentType?}` (an object body goes as JSON), `{abort: true, record?}` or `{continue: true}` (to the network). Where several masks match, the one mocked last answers; mocking a mask again replaces its answer. A response to `**\/*` is refused; the site's own page is never aborted. A mask reaches http(s) requests only — never a WebSocket, which waitForWebSocket waits for — so an extension's own pages and scripts load under `**\/*`; to mock them, start the mask with their scheme (`chrome-extension://<id>/x.js`). Mocks last until the scenario ends.
1015
1092
  */
1016
1093
  declare function mockRoute(glob: string, response: any): void;
1017
1094
 
@@ -1027,21 +1104,161 @@ declare function unmockRoute(glob?: string): void;
1027
1104
  *
1028
1105
  * Wait for a request matching `glob` and return it; `postDataJson` is the body read as JSON (null when it is not). On a mocked mask it also finds a request sent before the call, each one returned once; on any other mask only requests from the call on. Default timeout 20 s.
1029
1106
  */
1030
- declare function waitForRequest(glob: string, options?: any): any;
1107
+ declare function waitForRequest(glob: string, options?: { timeoutMs?: number }): any;
1108
+
1109
+ /**
1110
+ * waitForWebSocket(glob, { timeoutMs? }) → { url }
1111
+ *
1112
+ * 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. A socket opened before the call counts, from the page's last load on: a new document starts the list again. A socket is no request: waitForRequest and mockRoute never see one. A timeout names the mask and the sockets the page did open. Default timeout 20 s.
1113
+ */
1114
+ declare function waitForWebSocket(glob: string, options?: { timeoutMs?: number }): any;
1031
1115
 
1032
1116
  /**
1033
1117
  * assertNoRequest(glob, { since? })
1034
1118
  *
1035
1119
  * 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. A mask without a recording abort is an error, not a pass.
1036
1120
  */
1037
- declare function assertNoRequest(glob: string, options?: any): void;
1121
+ declare function assertNoRequest(glob: string, options?: { since?: number }): void;
1122
+
1123
+ /**
1124
+ * openTerminal(app, { host? }) → number
1125
+ *
1126
+ * Open a real terminal window — 'Terminal' (Terminal.app) or 'iTerm2' — and make it the one the terminal steps act on; returns its index for setTerminal. On this Mac by default (it takes the keyboard while the test types); {host: 'user@address'} opens it on another Mac over ssh, a Tart VM, whose logged-in session runs it — the key comes from your ssh agent or ~/.ssh. Every window closes when the test ends.
1127
+ */
1128
+ declare function openTerminal(app: string, options?: { host?: any }): number;
1129
+
1130
+ /**
1131
+ * setTerminal(index)
1132
+ *
1133
+ * Make the terminal window `index` (from openTerminal) the one the terminal steps act on.
1134
+ */
1135
+ declare function setTerminal(index: number): void;
1136
+
1137
+ /**
1138
+ * closeTerminal()
1139
+ *
1140
+ * Close the active terminal window and stop what runs in it. Windows left open close when the test ends anyway.
1141
+ */
1142
+ declare function closeTerminal(): void;
1143
+
1144
+ /**
1145
+ * terminalType(text, { echo? })
1146
+ *
1147
+ * Put `text` into the active terminal window as a paste, line by line with Return between the lines, so the keyboard layout does not change it; the clipboard is restored after. Each line must show on the screen within 2 s, or the step fails quoting the screen's last rows; {echo: false} skips that wait for input a program does not echo (a password). Nothing is sent when another window took the focus — the step fails instead.
1148
+ */
1149
+ declare function terminalType(text: string, options?: { echo?: boolean }): void;
1150
+
1151
+ /**
1152
+ * terminalPress(key)
1153
+ *
1154
+ * Press a key in the active terminal window, with modifiers held as press() spells them: 'Enter', 'Shift+Enter', 'Control+]', 'Escape', 'ArrowUp', 'F5'; a character with a modifier is that key of a US keyboard. A single character alone is pasted as terminalType does, without the echo wait. A real key event — the terminal encodes it itself (iTerm2 under the kitty keyboard protocol sends Shift+Enter as CSI 13;2 u).
1155
+ */
1156
+ declare function terminalPress(key: string): void;
1157
+
1158
+ /**
1159
+ * terminalWaitForText(text, { not?, timeoutMs? })
1160
+ *
1161
+ * Wait until `text` (a substring, or a /regex/) is on the active terminal's screen; {not: true} waits for it to go. Default timeout 30 s. A failed test keeps the window's last frame and screen text (terminal.png, terminal.txt).
1162
+ */
1163
+ declare function terminalWaitForText(text: string | RegExp, options?: { timeout?: number; not?: boolean; timeoutMs?: number }): void;
1164
+
1165
+ /**
1166
+ * terminalAssertText(text, { not?, timeoutMs? })
1167
+ *
1168
+ * FAIL unless `text` (a substring, or a /regex/) is on the active terminal's screen within the timeout (default 5000 ms); {not: true} fails while it is there.
1169
+ */
1170
+ declare function terminalAssertText(text: string | RegExp, options?: { timeout?: number; not?: boolean; timeoutMs?: number }): void;
1171
+
1172
+ /**
1173
+ * terminalResize(cols, rows)
1174
+ *
1175
+ * Resize the active terminal window to `cols` × `rows` character cells.
1176
+ */
1177
+ declare function terminalResize(cols: number, rows: number): void;
1178
+
1179
+ /**
1180
+ * terminalScreenshot(name?) → string
1181
+ *
1182
+ * A PNG of the active terminal window, saved with the run; returns its project-relative path.
1183
+ */
1184
+ declare function terminalScreenshot(name?: string): string;
1185
+
1186
+ /**
1187
+ * mcpStart(command, args?, { env?, cwd?, timeoutMs? }) → server
1188
+ *
1189
+ * Start a stdio MCP server and finish its handshake; returns the handle the other mcp* functions take. `env` adds variables to the inherited environment (the journal names them, never their values); `cwd` is relative to the project. A server the test did not stop is stopped when the test ends, red or green. Default timeout 30 s.
1190
+ */
1191
+ declare function mcpStart(command: string, args?: string[], options?: { env?: any; cwd?: any; timeoutMs?: number }): any;
1192
+
1193
+ /**
1194
+ * mcpCall(server, tool, args?, { timeoutMs?, allowError? }) → { content, structuredContent?, isError? }
1195
+ *
1196
+ * Call a tool and return its result. A JSON-RPC error, no answer within `timeoutMs` (default 30 s), or a result marked isError fails the step — `{allowError: true}` returns that result instead. The call and the result are notes in the run.
1197
+ */
1198
+ declare function mcpCall(server: any, tool: string, args?: any, options?: { timeoutMs?: number; allowError?: any }): any;
1199
+
1200
+ /**
1201
+ * mcpWaitNotification(server, method, { match?, timeoutMs? }) → params
1202
+ *
1203
+ * Wait for a notification of `method` and return its params. Notifications are kept from the moment the server started, each handed out once, so call first, then wait. `match` takes scalars at dot paths of the params (`{'data.status': 'done'}`). Default timeout 30 s.
1204
+ */
1205
+ declare function mcpWaitNotification(server: any, method: string, options?: { timeoutMs?: number; match?: any }): any;
1206
+
1207
+ /**
1208
+ * mcpStop(server)
1209
+ *
1210
+ * Stop the server. Optional: whatever the test leaves running is stopped when it ends.
1211
+ */
1212
+ declare function mcpStop(server: any): void;
1213
+
1214
+ /**
1215
+ * vmAvailable() → bool
1216
+ *
1217
+ * Whether VMs can run here: Tart is installed and answers. Guard a VM test with skip('no tart', !vmAvailable()).
1218
+ */
1219
+ declare function vmAvailable(): boolean;
1220
+
1221
+ /**
1222
+ * vmClone(image) → name
1223
+ *
1224
+ * A new VM from a ready image (a local Tart VM or an OCI reference); returns its name, unotest-<id>-<n>, unique to the test. Every VM the test cloned is stopped and deleted when it ends, red or green.
1225
+ */
1226
+ declare function vmClone(image: string): string;
1227
+
1228
+ /**
1229
+ * vmRun(name, { timeoutMs? }) → ip
1230
+ *
1231
+ * Boot the VM without a window and wait for its address; returns the IP. Default timeout 180 s. A boot that fails errors at once with Tart's output.
1232
+ */
1233
+ declare function vmRun(name: string, options?: { timeoutMs?: number }): string;
1234
+
1235
+ /**
1236
+ * vmIp(name, { timeoutMs? }) → ip
1237
+ *
1238
+ * The address of a running VM. Default timeout 60 s.
1239
+ */
1240
+ declare function vmIp(name: string, options?: { timeoutMs?: number }): string;
1241
+
1242
+ /**
1243
+ * vmStop(name)
1244
+ *
1245
+ * Stop the VM. Optional: the test's VMs are removed when it ends.
1246
+ */
1247
+ declare function vmStop(name: string): void;
1248
+
1249
+ /**
1250
+ * vmDelete(name)
1251
+ *
1252
+ * Delete the VM, stopping it first if it runs. Optional, as vmStop. The vm* steps take only a name vmClone returned in this test — other VMs on the machine are never touched.
1253
+ */
1254
+ declare function vmDelete(name: string): void;
1038
1255
 
1039
1256
  /**
1040
1257
  * waitForServiceWorker({ timeoutMs?, url? }) → string
1041
1258
  *
1042
1259
  * Wait for a browser extension's service worker and return its URL (`chrome-extension://<id>/sw.js`); a running one comes back at once. `url` — substring or /regex/ when several extensions run. Extensions load only with `launch.userDataDir`: without it the call fails at once.
1043
1260
  */
1044
- declare function waitForServiceWorker(options?: any): string;
1261
+ declare function waitForServiceWorker(options?: { timeoutMs?: number; url?: string | RegExp }): string;
1045
1262
 
1046
1263
  /**
1047
1264
  * extensionId() → string
@@ -1053,9 +1270,9 @@ declare function extensionId(): string;
1053
1270
  /**
1054
1271
  * evaluateInServiceWorker(js, ...args) → any
1055
1272
  *
1056
- * Like evaluate, in the extension's service worker — the way to `chrome.storage`, `chrome.tabs`, `chrome.runtime`. Same argument and JSON-return rules; waits for the worker if none runs. Each call finds the worker anew: MV3 stops an idle one.
1273
+ * Like evaluate, in the extension's service worker — the way to `chrome.storage`, `chrome.tabs`, `chrome.runtime`. `js` is a function or a string; same argument, page-code and JSON-return rules; waits for the worker if none runs. Each call finds the worker anew: MV3 stops an idle one.
1057
1274
  */
1058
- declare function evaluateInServiceWorker(jsBody: string, ...args: unknown[]): any;
1275
+ declare function evaluateInServiceWorker(jsBody: any, ...args: unknown[]): any;
1059
1276
 
1060
1277
  /** step(label, [options,] body)
1061
1278
  *
@@ -1072,3 +1289,30 @@ declare namespace step {
1072
1289
  function soft(label: string, body: () => void): void;
1073
1290
  function soft(label: string, options: { tag: unknown }, body: () => void): void;
1074
1291
  }
1292
+
1293
+ /** teardown(label, body)
1294
+ *
1295
+ * Registers a block that gives the stand back. Nothing runs where it
1296
+ * stands; the block plays after the test, passed or failed, newest
1297
+ * first, and sees the values as they are then. */
1298
+ declare function teardown(label: string, body: () => void): void;
1299
+
1300
+ /** waitUntil(() => condition, options?)
1301
+ *
1302
+ * Runs the body again and again until it gives a truthy value, and
1303
+ * gives that value back. Only a falsy value is retried: an error fails
1304
+ * at once. */
1305
+ declare function waitUntil<T>(
1306
+ condition: () => T,
1307
+ options?: { timeoutMs?: number; intervalMs?: number; label?: string },
1308
+ ): T;
1309
+
1310
+ /** assertNever(() => condition, options)
1311
+ *
1312
+ * Runs the body again and again for the whole window and fails the
1313
+ * moment it gives a truthy value, naming the value and the time. A
1314
+ * window that elapsed clean passes. An error fails at once. */
1315
+ declare function assertNever(
1316
+ condition: () => unknown,
1317
+ options: { withinMs: number; intervalMs?: number; label?: string },
1318
+ ): void;