@orkestrel/test 0.0.28 → 0.0.30
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/README.md +5 -5
- package/dist/src/browser/index.d.ts +162 -38
- package/dist/src/browser/index.js +227 -73
- package/dist/src/browser/index.js.map +1 -1
- package/dist/src/core/index.cjs +10 -10
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -1
- package/dist/src/core/index.d.ts +1 -1
- package/dist/src/core/index.js +10 -10
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +31 -12
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +34 -20
- package/dist/src/server/index.d.ts +34 -20
- package/dist/src/server/index.js +31 -13
- package/dist/src/server/index.js.map +1 -1
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -23,7 +23,7 @@ npm install -D @orkestrel/test
|
|
|
23
23
|
|
|
24
24
|
## Requirements
|
|
25
25
|
|
|
26
|
-
- Node.js >= 22.
|
|
26
|
+
- Node.js >= 22.18.0
|
|
27
27
|
- ESM and CommonJS
|
|
28
28
|
|
|
29
29
|
## Usage
|
|
@@ -92,7 +92,7 @@ a browser workspace renders that table in.
|
|
|
92
92
|
The server face adds `readInventory`, which reads a checkout into a map of root-relative path to
|
|
93
93
|
file text that a parity suite can assert against, and `createLoopback`, which binds a server the
|
|
94
94
|
test built to an ephemeral loopback port. Behind them sit the pure leaves the server face also
|
|
95
|
-
exports on its own: `readInventory` refuses
|
|
95
|
+
exports on its own: `readInventory` refuses a path outside the root with `resolveContained` and prunes with
|
|
96
96
|
`isExcluded`, while `createScratch` refuses one with `requireContained`, the throwing form, and
|
|
97
97
|
reads and compares its allocation with `readIdentity` and `matchesIdentity` before `destroy()`
|
|
98
98
|
removes anything. `createLink` and `removeTree` do the writing under it, and both decide on the
|
|
@@ -146,7 +146,7 @@ back for every key that is not integer-like.
|
|
|
146
146
|
|
|
147
147
|
`createScratch` and `readInventory` promise different things, and each boundary is worth stating up
|
|
148
148
|
front. `createScratch` allocates its own directory at POSIX mode `0700` — under the host temporary
|
|
149
|
-
directory, or under a `parent` you name — and refuses a path that lexically
|
|
149
|
+
directory, or under a `parent` you name — and refuses a path that lexically resolves outside it. The suite
|
|
150
150
|
gates that assertion on `supportsMode`, the shipped probe that reads whether permission bits
|
|
151
151
|
round-trip on this host, so it runs only where they do and claims nothing about a host that emulates
|
|
152
152
|
them. The mode keeps another uid out, and neither a sibling test worker nor the code under test is
|
|
@@ -162,8 +162,8 @@ reports `ctime` in its place, the first write moves it, and `destroy()` then rem
|
|
|
162
162
|
returns as if it had. `readInventory` walks a checkout you supply, usually one the test did not
|
|
163
163
|
create, so it throws on a symlinked root or named target, throws on a named target whose real path
|
|
164
164
|
leaves the root through a link in the middle, and skips a symlink met while walking. Neither is a
|
|
165
|
-
sandbox against
|
|
166
|
-
|
|
165
|
+
sandbox against untrusted filesystem content: those refusals stop accidental access outside the root, not a process
|
|
166
|
+
that can create hard links where the test process already writes.
|
|
167
167
|
|
|
168
168
|
The browser face is the journey layer: an accessible-name resolver with exact failure voices,
|
|
169
169
|
region and disclosure targeting, input and traversal verbs, perception readers, a WCAG contrast
|
|
@@ -78,7 +78,7 @@ export declare function adoptSheet(text: string): SheetAdoption;
|
|
|
78
78
|
* An animation counts as endless when its effect declares infinite iterations. A paused, an idle,
|
|
79
79
|
* and a finished animation are at rest, so neither list holds one.
|
|
80
80
|
*/
|
|
81
|
-
export declare interface
|
|
81
|
+
export declare interface AnimationResult {
|
|
82
82
|
/** Lists the running animations that end, the ones `waitForAnimations` waits on. */
|
|
83
83
|
readonly finite: readonly Animation[];
|
|
84
84
|
/** Lists the running animations whose effect declares infinite iterations. */
|
|
@@ -270,7 +270,7 @@ export declare const CAPTURE_PANE = "data-capture-pane";
|
|
|
270
270
|
* one restaging past the cap before it comes back down to the edge. Nothing measured needs a
|
|
271
271
|
* fourth, so a fourth is the headroom that keeps a settling document off the refusal.
|
|
272
272
|
*/
|
|
273
|
-
export declare const
|
|
273
|
+
export declare const CAPTURE_STAGE_LIMIT = 4;
|
|
274
274
|
|
|
275
275
|
/**
|
|
276
276
|
* Shoots one frame at one viewport size and proves the file on disk holds this run's bytes.
|
|
@@ -278,14 +278,17 @@ export declare const CAPTURE_STAGINGS = 4;
|
|
|
278
278
|
* @param options - The path to write, the viewport to shoot at, and the element to shoot.
|
|
279
279
|
* @returns The absolute path of the written frame, after it has been read back and matched.
|
|
280
280
|
* @throws Thrown when the pane cannot be staged, when the document's height or an element frame's
|
|
281
|
-
* element height never settles under {@link
|
|
281
|
+
* element height never settles under {@link CAPTURE_STAGE_LIMIT} restagings, when the provider wrote
|
|
282
282
|
* the frame somewhere else, and when the bytes on disk are not the ones this shot produced.
|
|
283
283
|
*
|
|
284
284
|
* @remarks
|
|
285
285
|
* The path a screenshot call returns is the path it meant to write, so it is not evidence a file
|
|
286
|
-
* exists. The
|
|
287
|
-
*
|
|
288
|
-
*
|
|
286
|
+
* exists. The {@link verifyFrame} helper compares the file with the shot itself. When the page
|
|
287
|
+
* registered a `readCapture` command, {@link readCaptureReader} returns it and the comparison uses
|
|
288
|
+
* SHA-256 digests computed in Node for the file and in the browser for the returned bytes. Otherwise
|
|
289
|
+
* the runner's built-in `readFile` command supplies the base64 comparison. A command failure
|
|
290
|
+
* propagates without falling back. The provider resolves `options.path`
|
|
291
|
+
* against the calling test file and returns an absolute
|
|
289
292
|
* path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
|
|
290
293
|
* refusal is what a provider resolving that path against a different base would trip.
|
|
291
294
|
*
|
|
@@ -295,6 +298,8 @@ export declare const CAPTURE_STAGINGS = 4;
|
|
|
295
298
|
* than the document — a frame that reads as the surface down to the fold and as bare canvas after
|
|
296
299
|
* it. The document is therefore laid out at the declared viewport first and, where it is taller
|
|
297
300
|
* than that, the pane is staged again at the height the document needs, for the shot alone.
|
|
301
|
+
* Where the tester already has the declared viewport, the reading precedes the initial staging,
|
|
302
|
+
* so fixed content stages at its final height directly. Every staged height is still read again.
|
|
298
303
|
*
|
|
299
304
|
* That height is {@link measureContent}, never less than `options.height`, because the declared
|
|
300
305
|
* viewport is the smallest frame a variant asks for. The reading is the content's own edge rather
|
|
@@ -317,7 +322,7 @@ export declare const CAPTURE_STAGINGS = 4;
|
|
|
317
322
|
*
|
|
318
323
|
* The re-reading stops when the pane and the edge agree, which is the pane the shot is taken at. A
|
|
319
324
|
* rule that adds height with every pane never reaches that point, so the re-reading is bounded by
|
|
320
|
-
* {@link
|
|
325
|
+
* {@link CAPTURE_STAGE_LIMIT} and the shot is refused with
|
|
321
326
|
* `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
|
|
322
327
|
* written at a height that is already wrong.
|
|
323
328
|
*
|
|
@@ -366,6 +371,9 @@ export declare const CAPTURE_STAGINGS = 4;
|
|
|
366
371
|
*/
|
|
367
372
|
export declare function captureFrame(options: FrameOptions): Promise<string>;
|
|
368
373
|
|
|
374
|
+
/** Reads the lowercase hexadecimal SHA-256 digest of a captured file through a browser command. */
|
|
375
|
+
export declare type CaptureReader = (path: string) => Promise<string>;
|
|
376
|
+
|
|
369
377
|
/**
|
|
370
378
|
* Adds to a journey variant the document change a capture run applies before resizing.
|
|
371
379
|
*
|
|
@@ -409,7 +417,7 @@ export declare interface CensusFixture {
|
|
|
409
417
|
* markup whose every class the cascade declares. Assert on `elements` as well as on `undeclared`
|
|
410
418
|
* and the two cannot be confused.
|
|
411
419
|
*/
|
|
412
|
-
export declare interface
|
|
420
|
+
export declare interface CensusResult {
|
|
413
421
|
/** Reports how many elements the walk read, the root included when it is an element. */
|
|
414
422
|
readonly elements: number;
|
|
415
423
|
/** Lists every class token the markup carries, sorted. */
|
|
@@ -611,7 +619,9 @@ export declare function collectScrollRegions(root: Element, axis?: 'inline' | 'b
|
|
|
611
619
|
* {@link containsNode}, so a control inside an open shadow root or a same-origin frame that `root`
|
|
612
620
|
* holds is in the region, and `start` may sit inside one. A `start` that sits outside the region,
|
|
613
621
|
* as the control immediately before it, is the walk's origin and never its end, so the first Tab into the
|
|
614
|
-
* region reaches its first stop.
|
|
622
|
+
* region reaches its first stop. A native segmented input contributes one stop while consecutive
|
|
623
|
+
* landings pass through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings. A longer run or
|
|
624
|
+
* any other revisit ends the walk.
|
|
615
625
|
*
|
|
616
626
|
* @example
|
|
617
627
|
* ```ts
|
|
@@ -1344,23 +1354,29 @@ export declare function driveHold(resolve: () => HTMLElement, name: string): Pro
|
|
|
1344
1354
|
* Reaches the control a resolver returns, only through natural forward Tab traversal from the
|
|
1345
1355
|
* current focus.
|
|
1346
1356
|
*
|
|
1347
|
-
* @param resolve - The resolver
|
|
1348
|
-
*
|
|
1357
|
+
* @param resolve - The resolver called before traversal and at candidate arrivals, without retaining
|
|
1358
|
+
* its result between steps.
|
|
1349
1359
|
* @param name - The target's name, as the refusal voices it.
|
|
1360
|
+
* @param candidate - The landing check; it must admit every element the resolver could return.
|
|
1361
|
+
* Default: the conservative exact-name check from {@link matchesTraversalName}. Supply a check
|
|
1362
|
+
* matching the resolver's semantics when it uses a label, region, or loose name.
|
|
1350
1363
|
* @returns The target after the browser moves focus to it.
|
|
1351
1364
|
* @throws When the resolver refuses, or one complete traversal cannot reach the target.
|
|
1352
1365
|
*
|
|
1353
1366
|
* @remarks
|
|
1354
1367
|
* This is the one loop every traversal verb shares, over {@link stepFocus}. A step counts only when
|
|
1355
|
-
* focus lands on an element
|
|
1356
|
-
*
|
|
1368
|
+
* focus lands on an element. Consecutive landings on the same native segmented input continue
|
|
1369
|
+
* through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings and count that control once.
|
|
1370
|
+
* A longer run or any other revisit ends the traversal. Any different landing starts a separate run.
|
|
1371
|
+
* The press cap is {@link FOCUS_SEGMENT_LIMIT} times the {@link FOCUSABLE_SELECTOR} candidate count
|
|
1372
|
+
* plus ten, so a page of segmented inputs has a budget for their segments and picker indicators.
|
|
1357
1373
|
*
|
|
1358
1374
|
* @example
|
|
1359
1375
|
* ```ts
|
|
1360
1376
|
* await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
|
|
1361
1377
|
* ```
|
|
1362
1378
|
*/
|
|
1363
|
-
export declare function driveTraversal(resolve: () => HTMLElement, name: string): Promise<HTMLElement>;
|
|
1379
|
+
export declare function driveTraversal(resolve: () => HTMLElement, name: string, candidate?: (element: HTMLElement) => boolean): Promise<HTMLElement>;
|
|
1364
1380
|
|
|
1365
1381
|
/**
|
|
1366
1382
|
* Configures one built element: its class list, its text, and its attributes.
|
|
@@ -1543,6 +1559,16 @@ export declare function findKeyframes(name: string): CSSKeyframesRule | undefine
|
|
|
1543
1559
|
*/
|
|
1544
1560
|
export declare function findRule(selector: string): CSSStyleRule | undefined;
|
|
1545
1561
|
|
|
1562
|
+
/**
|
|
1563
|
+
* Bounds consecutive focus landings and the Tab presses budgeted per segmented input.
|
|
1564
|
+
*
|
|
1565
|
+
* @remarks
|
|
1566
|
+
* Chromium measured nine landings on a datetime-local input with step="0.001": year, month,
|
|
1567
|
+
* day, hour, minute, second, millisecond, and meridiem segments, plus the picker indicator.
|
|
1568
|
+
* The budget covers those landings with one spare press per input.
|
|
1569
|
+
*/
|
|
1570
|
+
export declare const FOCUS_SEGMENT_LIMIT = 10;
|
|
1571
|
+
|
|
1546
1572
|
/**
|
|
1547
1573
|
* Names what sequential keyboard navigation can reach, before disabled and unrendered elements go.
|
|
1548
1574
|
*
|
|
@@ -1592,7 +1618,7 @@ export declare interface FrameOptions {
|
|
|
1592
1618
|
* color in the `rgb(r, g, b)` form a computed style is written in, so a literal comparison,
|
|
1593
1619
|
* `parseColor`, and `matchesColor` all take it.
|
|
1594
1620
|
*/
|
|
1595
|
-
export declare interface
|
|
1621
|
+
export declare interface FrameResult {
|
|
1596
1622
|
/** Holds the frame's width in device pixels. */
|
|
1597
1623
|
readonly width: number;
|
|
1598
1624
|
/** Holds the frame's height in device pixels. */
|
|
@@ -1601,6 +1627,14 @@ export declare interface FrameReading {
|
|
|
1601
1627
|
readonly floor: string | undefined;
|
|
1602
1628
|
}
|
|
1603
1629
|
|
|
1630
|
+
/** Represents the path and base64 bytes returned by Vitest's screenshot operation. */
|
|
1631
|
+
export declare interface FrameShot {
|
|
1632
|
+
/** Holds the absolute path the provider wrote. */
|
|
1633
|
+
readonly path: string;
|
|
1634
|
+
/** Holds the screenshot bytes encoded as base64. */
|
|
1635
|
+
readonly base64: string;
|
|
1636
|
+
}
|
|
1637
|
+
|
|
1604
1638
|
/**
|
|
1605
1639
|
* Holds a mounted statechart harness, the tally it publishes, and the run it drives.
|
|
1606
1640
|
*
|
|
@@ -1970,6 +2004,30 @@ export declare interface JournalStep {
|
|
|
1970
2004
|
*/
|
|
1971
2005
|
export declare function matchesColor(first: string | Color, second: string | Color): boolean;
|
|
1972
2006
|
|
|
2007
|
+
/**
|
|
2008
|
+
* Checks whether a landing can carry a requested accessible name without resolving the document.
|
|
2009
|
+
*
|
|
2010
|
+
* @param element - The element focus landed on.
|
|
2011
|
+
* @param name - The name the resolver matches.
|
|
2012
|
+
* @param exact - If `true`, compares exact names; if `false`, compares case-insensitive substrings.
|
|
2013
|
+
* Default: `true`.
|
|
2014
|
+
* @returns True if the name matches or its computation requires the resolver; false otherwise.
|
|
2015
|
+
*
|
|
2016
|
+
* @remarks
|
|
2017
|
+
* This is a conservative candidate check, not an accessible-name implementation. It compares a
|
|
2018
|
+
* nonempty `aria-label` without `aria-labelledby`, or the text of a plain native button or link.
|
|
2019
|
+
* Referenced labels, associated labels, descendants, shadow content, owned content, explicit roles,
|
|
2020
|
+
* generated content, and other naming rules fall through to the resolver. Empty requested names
|
|
2021
|
+
* also fall through because a role can prohibit naming. Whitespace, zero-width spaces, and soft
|
|
2022
|
+
* hyphens are normalized as in the provider's role query. Never use this check to accept a target.
|
|
2023
|
+
*
|
|
2024
|
+
* @example
|
|
2025
|
+
* ```ts
|
|
2026
|
+
* matchesTraversalName(document.createElement('input'), 'Attachments') // true
|
|
2027
|
+
* ```
|
|
2028
|
+
*/
|
|
2029
|
+
export declare function matchesTraversalName(element: HTMLElement, name: string, exact?: boolean): boolean;
|
|
2030
|
+
|
|
1973
2031
|
/**
|
|
1974
2032
|
* Measures the row the document's own content ends on, in document coordinates.
|
|
1975
2033
|
*
|
|
@@ -2071,7 +2129,7 @@ export declare interface MediaOptions {
|
|
|
2071
2129
|
* Puts one element into the document and hands it straight back.
|
|
2072
2130
|
*
|
|
2073
2131
|
* @param element - The element to attach.
|
|
2074
|
-
* @returns The same element,
|
|
2132
|
+
* @returns The same element, appended to `document.body`.
|
|
2075
2133
|
*
|
|
2076
2134
|
* @remarks
|
|
2077
2135
|
* What this buys is the composition, not the attachment: the `append` method returns `void`, and
|
|
@@ -2201,7 +2259,7 @@ export declare function parseColor(value: string): Color | undefined;
|
|
|
2201
2259
|
* property is named by letters, digits, `_`, and `-` after its `--`. A name the scope leaves
|
|
2202
2260
|
* undeclared is not carried, so its `var()` fallback still applies.
|
|
2203
2261
|
*
|
|
2204
|
-
* The scope element is never written. The probe is
|
|
2262
|
+
* The scope element is never written. The probe is freshly created, so it has no earlier style to start a
|
|
2205
2263
|
* transition from, and a transition running on the scope keeps running: `currentColor` reads the
|
|
2206
2264
|
* color the scope shows at that moment, and the scope's geometry and scroll position stay as they
|
|
2207
2265
|
* were. No attribute, style, or child of the scope changes, so a `MutationObserver` on it records
|
|
@@ -2387,7 +2445,7 @@ export declare function readActiveElement(root?: Document | ShadowRoot): HTMLEle
|
|
|
2387
2445
|
* readAnimations(document.documentElement).finite.length // 0 once every transition has settled
|
|
2388
2446
|
* ```
|
|
2389
2447
|
*/
|
|
2390
|
-
export declare function readAnimations(element: Element):
|
|
2448
|
+
export declare function readAnimations(element: Element): AnimationResult;
|
|
2391
2449
|
|
|
2392
2450
|
/**
|
|
2393
2451
|
* Resolves the opaque color standing behind one element.
|
|
@@ -2418,6 +2476,22 @@ export declare function readAnimations(element: Element): AnimationReading;
|
|
|
2418
2476
|
*/
|
|
2419
2477
|
export declare function readBackdrop(element: Element, floor: Color): Color;
|
|
2420
2478
|
|
|
2479
|
+
/**
|
|
2480
|
+
* Reads the optional disk-digest command the tester page registered.
|
|
2481
|
+
*
|
|
2482
|
+
* @returns The registered `readCapture` command, or undefined where none is registered.
|
|
2483
|
+
*
|
|
2484
|
+
* @remarks Vitest publishes only registered commands, so an unregistered `readCapture` reads as
|
|
2485
|
+
* undefined and a capture falls back to the base64 read-back. Outside a Vitest browser page, where
|
|
2486
|
+
* `commands` is no object, the command reads as undefined too, so importing this module never
|
|
2487
|
+
* throws there.
|
|
2488
|
+
* @example
|
|
2489
|
+
* ```ts
|
|
2490
|
+
* await verifyFrame(shot, '../../tmp/frame.png', readCaptureReader())
|
|
2491
|
+
* ```
|
|
2492
|
+
*/
|
|
2493
|
+
export declare function readCaptureReader(): CaptureReader | undefined;
|
|
2494
|
+
|
|
2421
2495
|
/**
|
|
2422
2496
|
* Collects every class token the stylesheets loaded into this document actually define.
|
|
2423
2497
|
*
|
|
@@ -2479,7 +2553,7 @@ export declare function readCascade(): ReadonlySet<string>;
|
|
|
2479
2553
|
* readCensus(container).undeclared // ['lead'] — no loaded stylesheet declares it
|
|
2480
2554
|
* ```
|
|
2481
2555
|
*/
|
|
2482
|
-
export declare function readCensus(root: ParentNode):
|
|
2556
|
+
export declare function readCensus(root: ParentNode): CensusResult;
|
|
2483
2557
|
|
|
2484
2558
|
/**
|
|
2485
2559
|
* Collects every class token the markup under one root carries.
|
|
@@ -2717,10 +2791,10 @@ export declare function readFocus(): string | undefined;
|
|
|
2717
2791
|
*
|
|
2718
2792
|
* @example
|
|
2719
2793
|
* ```ts
|
|
2720
|
-
* const
|
|
2794
|
+
* const result = await readFrame(written)
|
|
2721
2795
|
* ```
|
|
2722
2796
|
*/
|
|
2723
|
-
export declare function readFrame(path: string): Promise<
|
|
2797
|
+
export declare function readFrame(path: string): Promise<FrameResult>;
|
|
2724
2798
|
|
|
2725
2799
|
/**
|
|
2726
2800
|
* Reads the topmost element at one element's bounding-box centre.
|
|
@@ -2968,7 +3042,7 @@ export declare function readProtocolNode(element: Element): Promise<number>;
|
|
|
2968
3042
|
* Each frame on the way up adds its border and its padding, which is where its content starts,
|
|
2969
3043
|
* scales the point by the ratio of its painted width to its layout width, and adds its own position,
|
|
2970
3044
|
* so a tester iframe the runner scales or offsets is accounted for, and so is an iframe the page
|
|
2971
|
-
* itself nests, bordered, padded, or neither. The reading is of the layout
|
|
3045
|
+
* itself nests, bordered, padded, or neither. The reading is of the layout at the call: a box that moves
|
|
2972
3046
|
* afterwards moves the point it names. An element in a document no frame holds reads its own client
|
|
2973
3047
|
* point. A disconnected element has no layout, and its window still names the tester frame, so it is
|
|
2974
3048
|
* refused rather than read as that frame's corner.
|
|
@@ -3010,7 +3084,7 @@ export declare function readRefusal(name: string): string | undefined;
|
|
|
3010
3084
|
* sentence rather than a boolean. This fixes the resolver, translates the `unknown` a `catch` binds
|
|
3011
3085
|
* into `string | undefined`, and rethrows anything that is not an `Error` — a value no resolver
|
|
3012
3086
|
* raises, and one a caller reading a message would otherwise lose. `undefined` is rethrown with the
|
|
3013
|
-
* rest: a resolver that returned and
|
|
3087
|
+
* rest: a resolver that returned and an untrusted getter that threw `undefined` are different findings,
|
|
3014
3088
|
* which is why the `catch` is this function's own rather than a captured thrown value.
|
|
3015
3089
|
*
|
|
3016
3090
|
* It resolves rather than acts, so a target it reports `undefined` for is one an acting verb
|
|
@@ -3038,7 +3112,7 @@ export declare function readRefusal(role: string, name: string): string | undefi
|
|
|
3038
3112
|
* @remarks
|
|
3039
3113
|
* This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
|
|
3040
3114
|
* `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
|
|
3041
|
-
* painted
|
|
3115
|
+
* painted after it landed. A control that is not matching `:focus-visible` when the call is made
|
|
3042
3116
|
* reports nothing, because no measurement taken then would be about focus.
|
|
3043
3117
|
*
|
|
3044
3118
|
* Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
|
|
@@ -3081,7 +3155,7 @@ export declare function readRing(control: Element, worn?: Element): number | und
|
|
|
3081
3155
|
* A declared `role` wins outright, and its first token is the answer when several are listed.
|
|
3082
3156
|
* Otherwise the element's own anatomy decides: an anchor is a link only while it holds an `href`,
|
|
3083
3157
|
* an `input` takes the role {@link FIELD_ROLES} gives its type, a `select` is a combobox until it
|
|
3084
|
-
* offers several rows at once, a `section` is a region only
|
|
3158
|
+
* offers several rows at once, a `section` is a region only after something names it, and a `th`
|
|
3085
3159
|
* heads whichever axis its `scope` names. Every other tag answers from {@link IMPLICIT_ROLES},
|
|
3086
3160
|
* whose membership is the contract for what this can answer at all.
|
|
3087
3161
|
*
|
|
@@ -3338,7 +3412,9 @@ export declare function releaseMedia(): Promise<void>;
|
|
|
3338
3412
|
* otherwise read the last capture's variant. The size comes off the {@link CAPTURE_PANE} value
|
|
3339
3413
|
* {@link stagePane} wrote onto the rule element, which is the reading taken before the first
|
|
3340
3414
|
* staging. Calling this on an unstaged pane finds no such value, so it changes nothing and resizes
|
|
3341
|
-
* nothing.
|
|
3415
|
+
* nothing. A staged pane sends its saved size even when the tester already holds it, because the
|
|
3416
|
+
* runner refits its frame scale only on a viewport request; a release that skipped it would leave
|
|
3417
|
+
* the next case shooting through the staged scale.
|
|
3342
3418
|
*
|
|
3343
3419
|
* That hand-back is what makes {@link stagePane} and this pair a capture's staging rather than a
|
|
3344
3420
|
* resize: the pair puts the tester back where it found it, so a suite that used it to reach a
|
|
@@ -3569,6 +3645,9 @@ export declare function resolveFileInput(name: string): HTMLInputElement;
|
|
|
3569
3645
|
*/
|
|
3570
3646
|
export declare function resolveRendered(first: string, second?: string): HTMLElement;
|
|
3571
3647
|
|
|
3648
|
+
/** Names the native input types whose editable segments share one focused element. */
|
|
3649
|
+
export declare const SEGMENTED_INPUT_TYPES: readonly string[];
|
|
3650
|
+
|
|
3572
3651
|
/**
|
|
3573
3652
|
* Carries files from outside the page over a rendered target named by role and accessible name.
|
|
3574
3653
|
*
|
|
@@ -3599,7 +3678,7 @@ export declare function sendFileDrag(type: 'dragEnter' | 'dragOver' | 'dragCance
|
|
|
3599
3678
|
*
|
|
3600
3679
|
* @param method - The protocol method name.
|
|
3601
3680
|
* @param params - The protocol parameters. Omit them for a command that takes none.
|
|
3602
|
-
* @returns A promise resolving to the browser's reply
|
|
3681
|
+
* @returns A promise resolving to the browser's reply after the command completes.
|
|
3603
3682
|
* @throws Thrown when the provider exposes no DevTools session, or the command fails.
|
|
3604
3683
|
*
|
|
3605
3684
|
* @remarks
|
|
@@ -3646,7 +3725,7 @@ export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd'
|
|
|
3646
3725
|
* A pointer left over a control paints that control's hover, and a transition still running paints
|
|
3647
3726
|
* a fill between two states, so neither is a state the interface rests in. An endless animation, a
|
|
3648
3727
|
* spinner or a placeholder shimmer, stands at a different phase in every frame unless it is held at
|
|
3649
|
-
* the same one, so each is paused at its first frame. Call the resume
|
|
3728
|
+
* the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
|
|
3650
3729
|
* capture that throws still owes it, so call it from a `finally` block.
|
|
3651
3730
|
*
|
|
3652
3731
|
* The subject is the whole document, its root element included. The pointer parks through
|
|
@@ -3753,7 +3832,7 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
|
|
|
3753
3832
|
*
|
|
3754
3833
|
* @remarks
|
|
3755
3834
|
* This depends on the runner's own tester layout, and that dependency is contract rather than an
|
|
3756
|
-
* accident: `vitest@4.1.
|
|
3835
|
+
* accident: `vitest@4.1.12` lays its tester out inside a smaller page, fits it by scaling the pane
|
|
3757
3836
|
* the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
|
|
3758
3837
|
* unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
|
|
3759
3838
|
* but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
|
|
@@ -3762,6 +3841,8 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
|
|
|
3762
3841
|
* selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
|
|
3763
3842
|
* `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
|
|
3764
3843
|
* them reddens the size check that follows rather than writing a wrong frame.
|
|
3844
|
+
* The custom-property overrides serve Vitest 4; `transform: none !important` on the pane and
|
|
3845
|
+
* iframe also suppresses Vitest 5's direct CSS transform.
|
|
3765
3846
|
*
|
|
3766
3847
|
* Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
|
|
3767
3848
|
* the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
|
|
@@ -3779,7 +3860,8 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
|
|
|
3779
3860
|
* the shot replaces the node and takes any attribute of ours with it.
|
|
3780
3861
|
*
|
|
3781
3862
|
* The wait is two frames rather than a delay: the first carries the resize into layout and the
|
|
3782
|
-
* second is the paint a screenshot reads.
|
|
3863
|
+
* second is the paint a screenshot reads. An already matching viewport needs no resize command;
|
|
3864
|
+
* the staging rule, paint waits, and rendered-size check still run.
|
|
3783
3865
|
*
|
|
3784
3866
|
* The viewport the tester had before this staging is written onto that rule element as the
|
|
3785
3867
|
* {@link CAPTURE_PANE} value, in `<width>x<height>` form, and {@link releasePane} hands it back.
|
|
@@ -3819,7 +3901,9 @@ export declare interface StateOptions extends WaitOptions {
|
|
|
3819
3901
|
* through the provider, reads the landing with {@link readActiveElement}, and leaves every decision
|
|
3820
3902
|
* to the caller: what counts as an end, a revisit, or a stop is the consumer's, because the two
|
|
3821
3903
|
* consumers disagree. The press is the next one only after the consumer asks for the next landing, so
|
|
3822
|
-
* a consumer that stops reading stops pressing.
|
|
3904
|
+
* a consumer that stops reading stops pressing. A native segmented input can yield the same element
|
|
3905
|
+
* for successive segment landings. This generator preserves each landing; its consumers count that
|
|
3906
|
+
* control once while continuing through its segments, and end a run beyond {@link FOCUS_SEGMENT_LIMIT}.
|
|
3823
3907
|
*
|
|
3824
3908
|
* @example
|
|
3825
3909
|
* ```ts
|
|
@@ -3853,6 +3937,20 @@ export declare interface StorageOptions {
|
|
|
3853
3937
|
readonly quota?: number;
|
|
3854
3938
|
}
|
|
3855
3939
|
|
|
3940
|
+
/**
|
|
3941
|
+
* Determines whether a native input exposes separately editable segments under one focused element.
|
|
3942
|
+
*
|
|
3943
|
+
* @param element - The element whose native input type is read in its own document's realm.
|
|
3944
|
+
* @returns True if the element is an input with a type in {@link SEGMENTED_INPUT_TYPES}, checked
|
|
3945
|
+
* against its own document's `HTMLInputElement`; false otherwise, including a document with no window.
|
|
3946
|
+
*
|
|
3947
|
+
* @example
|
|
3948
|
+
* ```ts
|
|
3949
|
+
* supportsSegmentedFocus(document.createElement('button')) // false
|
|
3950
|
+
* ```
|
|
3951
|
+
*/
|
|
3952
|
+
export declare function supportsSegmentedFocus(element: Element): boolean;
|
|
3953
|
+
|
|
3856
3954
|
/**
|
|
3857
3955
|
* Taps an element's centre with emulated touch after its box settles.
|
|
3858
3956
|
*
|
|
@@ -3887,7 +3985,10 @@ export declare function tapTouch(element: Element, options?: StabilityOptions):
|
|
|
3887
3985
|
* @throws When one complete traversal cannot reach the target.
|
|
3888
3986
|
*
|
|
3889
3987
|
* @remarks
|
|
3890
|
-
* The loop is {@link driveTraversal} over {@link resolveRendered}
|
|
3988
|
+
* The loop is {@link driveTraversal} over {@link resolveRendered}, with a conservative name check
|
|
3989
|
+
* before each arrival resolution. Consecutive landings inside a
|
|
3990
|
+
* native segmented input continue through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings.
|
|
3991
|
+
* A longer run or any other revisit ends the traversal.
|
|
3891
3992
|
*
|
|
3892
3993
|
* @example
|
|
3893
3994
|
* ```ts
|
|
@@ -3908,7 +4009,8 @@ export declare function traverseAccessible(name: string): Promise<HTMLElement>;
|
|
|
3908
4009
|
*
|
|
3909
4010
|
* @remarks
|
|
3910
4011
|
* The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
|
|
3911
|
-
* twin of the same name earlier in the tab order is passed over rather than reached.
|
|
4012
|
+
* twin of the same name earlier in the tab order is passed over rather than reached. Candidates
|
|
4013
|
+
* retain the resolver's loose name match and must belong to a freshly resolved named region.
|
|
3912
4014
|
*
|
|
3913
4015
|
* @example
|
|
3914
4016
|
* ```ts
|
|
@@ -3960,12 +4062,28 @@ export declare function typeAccessible(name: string, text: string): Promise<void
|
|
|
3960
4062
|
*/
|
|
3961
4063
|
export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
|
|
3962
4064
|
|
|
4065
|
+
/**
|
|
4066
|
+
* Verifies a screenshot's destination and compares its returned bytes with the written file.
|
|
4067
|
+
*
|
|
4068
|
+
* @param shot - The provider's absolute path and base64 screenshot bytes.
|
|
4069
|
+
* @param path - The requested screenshot path, relative to the test file.
|
|
4070
|
+
* @param reader - The optional Node disk-digest command; omission uses Vitest's base64 read-back.
|
|
4071
|
+
* @throws Thrown when the destination differs, the bytes differ, or either reading fails.
|
|
4072
|
+
* @remarks Digest reads compare SHA-256 of the decoded shot with SHA-256 of the disk bytes.
|
|
4073
|
+
* Command failures propagate unchanged; they never select the base64 fallback.
|
|
4074
|
+
* @example
|
|
4075
|
+
* ```ts
|
|
4076
|
+
* await verifyFrame(shot, '../../tmp/frame.png', readCaptureReader())
|
|
4077
|
+
* ```
|
|
4078
|
+
*/
|
|
4079
|
+
export declare function verifyFrame(shot: FrameShot, path: string, reader?: CaptureReader): Promise<void>;
|
|
4080
|
+
|
|
3963
4081
|
/**
|
|
3964
4082
|
* Waits until every finite animation on one element and its subtree has stopped moving.
|
|
3965
4083
|
*
|
|
3966
4084
|
* @param element - The element whose own animations and descendants' animations to wait on.
|
|
3967
4085
|
* @param options - The time bounds and the abort signal.
|
|
3968
|
-
* @returns A promise resolving
|
|
4086
|
+
* @returns A promise resolving after every finite animation has stopped running.
|
|
3969
4087
|
* @throws An `Error` when the element is not in a document, when a bound is invalid, or when an
|
|
3970
4088
|
* animation is still running at the budget; or the abort reason.
|
|
3971
4089
|
*
|
|
@@ -4100,8 +4218,8 @@ export declare function waitForState(role: string, name: string, state: string,
|
|
|
4100
4218
|
*
|
|
4101
4219
|
* @param stop - Accepts the destination. Omit it to census the remaining document.
|
|
4102
4220
|
* @returns Every element focus reached, in order and each once, the accepted stop last.
|
|
4103
|
-
* @throws Thrown when the walk
|
|
4104
|
-
*
|
|
4221
|
+
* @throws Thrown when the walk exceeds its press cap, a key press rejects, or focus lands in a
|
|
4222
|
+
* frame from another origin.
|
|
4105
4223
|
*
|
|
4106
4224
|
* @remarks
|
|
4107
4225
|
* The walk records the focused element and then presses Tab through {@link stepFocus}, so it reaches
|
|
@@ -4110,8 +4228,14 @@ export declare function waitForState(role: string, name: string, state: string,
|
|
|
4110
4228
|
* innermost focused element {@link readActiveElement} reads, so a control inside an open shadow root
|
|
4111
4229
|
* or a same-origin frame is a stop of its own, and its host or frame element is not. The walk ends
|
|
4112
4230
|
* with an empty list when only the body holds focus, and where focus revisits a stop or returns to
|
|
4113
|
-
* the body.
|
|
4114
|
-
*
|
|
4231
|
+
* the body. Consecutive landings on the same native segmented input continue through its segments
|
|
4232
|
+
* up to {@link FOCUS_SEGMENT_LIMIT} landings, including the initial focused element, and count that
|
|
4233
|
+
* control once. A longer run or any other revisit, including a repeated button in a focus trap,
|
|
4234
|
+
* ends the walk. Any different landing starts a separate run.
|
|
4235
|
+
* The press cap is {@link FOCUS_SEGMENT_LIMIT} times {@link countElements}, including
|
|
4236
|
+
* open shadow roots and same-origin frames. It applies no rule about which stop counts: the
|
|
4237
|
+
* predicate sees each one and decides, so a consumer that refuses a hidden stop throws from its own
|
|
4238
|
+
* predicate.
|
|
4115
4239
|
*
|
|
4116
4240
|
* A closed shadow root cannot be entered, so its host stands for everything inside it, and a frame
|
|
4117
4241
|
* from another origin is refused because its controls cannot be named.
|