@orkestrel/test 0.0.27 → 0.0.29
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 +9 -5
- package/dist/src/browser/index.d.ts +230 -25
- package/dist/src/browser/index.js +2818 -2517
- package/dist/src/browser/index.js.map +1 -1
- package/dist/src/core/index.d.cts +1 -1
- package/dist/src/core/index.d.ts +1 -1
- package/dist/src/server/index.cjs +12 -12
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +20 -20
- package/dist/src/server/index.d.ts +20 -20
- package/dist/src/server/index.js +12 -12
- package/dist/src/server/index.js.map +1 -1
- package/package.json +8 -8
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
|
|
@@ -33,6 +33,10 @@ npm install -D @orkestrel/test
|
|
|
33
33
|
Vitest provider. Core touches neither `node:*` nor the DOM, so a browser test project imports it
|
|
34
34
|
unchanged.
|
|
35
35
|
|
|
36
|
+
The browser face also supplies `sendTouch`, `tapTouch`, and `releaseTouch`, external file drags
|
|
37
|
+
through `sendFileDrag`, a `pointer` axis on `stageMedia`, and the stylesheet instruments
|
|
38
|
+
`adoptSheet`, `SheetAdoption`, and `readLayerNames`.
|
|
39
|
+
|
|
36
40
|
```ts
|
|
37
41
|
import {
|
|
38
42
|
captureError,
|
|
@@ -88,7 +92,7 @@ a browser workspace renders that table in.
|
|
|
88
92
|
The server face adds `readInventory`, which reads a checkout into a map of root-relative path to
|
|
89
93
|
file text that a parity suite can assert against, and `createLoopback`, which binds a server the
|
|
90
94
|
test built to an ephemeral loopback port. Behind them sit the pure leaves the server face also
|
|
91
|
-
exports on its own: `readInventory` refuses
|
|
95
|
+
exports on its own: `readInventory` refuses a path outside the root with `resolveContained` and prunes with
|
|
92
96
|
`isExcluded`, while `createScratch` refuses one with `requireContained`, the throwing form, and
|
|
93
97
|
reads and compares its allocation with `readIdentity` and `matchesIdentity` before `destroy()`
|
|
94
98
|
removes anything. `createLink` and `removeTree` do the writing under it, and both decide on the
|
|
@@ -142,7 +146,7 @@ back for every key that is not integer-like.
|
|
|
142
146
|
|
|
143
147
|
`createScratch` and `readInventory` promise different things, and each boundary is worth stating up
|
|
144
148
|
front. `createScratch` allocates its own directory at POSIX mode `0700` — under the host temporary
|
|
145
|
-
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
|
|
146
150
|
gates that assertion on `supportsMode`, the shipped probe that reads whether permission bits
|
|
147
151
|
round-trip on this host, so it runs only where they do and claims nothing about a host that emulates
|
|
148
152
|
them. The mode keeps another uid out, and neither a sibling test worker nor the code under test is
|
|
@@ -158,8 +162,8 @@ reports `ctime` in its place, the first write moves it, and `destroy()` then rem
|
|
|
158
162
|
returns as if it had. `readInventory` walks a checkout you supply, usually one the test did not
|
|
159
163
|
create, so it throws on a symlinked root or named target, throws on a named target whose real path
|
|
160
164
|
leaves the root through a link in the middle, and skips a symlink met while walking. Neither is a
|
|
161
|
-
sandbox against
|
|
162
|
-
|
|
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.
|
|
163
167
|
|
|
164
168
|
The browser face is the journey layer: an accessible-name resolver with exact failure voices,
|
|
165
169
|
region and disclosure targeting, input and traversal verbs, perception readers, a WCAG contrast
|
|
@@ -57,6 +57,20 @@ export declare interface AccessibilityNode {
|
|
|
57
57
|
*/
|
|
58
58
|
export declare const ACCESSIBLE_ROLES: readonly string[];
|
|
59
59
|
|
|
60
|
+
/**
|
|
61
|
+
* Adopts CSS text into the document with an idempotent release operation.
|
|
62
|
+
*
|
|
63
|
+
* @param text - The compiled sheet text.
|
|
64
|
+
* @returns The adopted sheet and its release operation.
|
|
65
|
+
*
|
|
66
|
+
* @example
|
|
67
|
+
* ```ts
|
|
68
|
+
* const adopted = adoptSheet('.sample { display: block }')
|
|
69
|
+
* adopted.release()
|
|
70
|
+
* ```
|
|
71
|
+
*/
|
|
72
|
+
export declare function adoptSheet(text: string): SheetAdoption;
|
|
73
|
+
|
|
60
74
|
/**
|
|
61
75
|
* Represents the animations running on one element and its subtree, split by whether each one ends.
|
|
62
76
|
*
|
|
@@ -597,7 +611,9 @@ export declare function collectScrollRegions(root: Element, axis?: 'inline' | 'b
|
|
|
597
611
|
* {@link containsNode}, so a control inside an open shadow root or a same-origin frame that `root`
|
|
598
612
|
* holds is in the region, and `start` may sit inside one. A `start` that sits outside the region,
|
|
599
613
|
* as the control immediately before it, is the walk's origin and never its end, so the first Tab into the
|
|
600
|
-
* region reaches its first stop.
|
|
614
|
+
* region reaches its first stop. A native segmented input contributes one stop while consecutive
|
|
615
|
+
* landings pass through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings. A longer run or
|
|
616
|
+
* any other revisit ends the walk.
|
|
601
617
|
*
|
|
602
618
|
* @example
|
|
603
619
|
* ```ts
|
|
@@ -1338,8 +1354,11 @@ export declare function driveHold(resolve: () => HTMLElement, name: string): Pro
|
|
|
1338
1354
|
*
|
|
1339
1355
|
* @remarks
|
|
1340
1356
|
* This is the one loop every traversal verb shares, over {@link stepFocus}. A step counts only when
|
|
1341
|
-
* focus lands on an element
|
|
1342
|
-
*
|
|
1357
|
+
* focus lands on an element. Consecutive landings on the same native segmented input continue
|
|
1358
|
+
* through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings and count that control once.
|
|
1359
|
+
* A longer run or any other revisit ends the traversal. Any different landing starts a separate run.
|
|
1360
|
+
* The press cap is {@link FOCUS_SEGMENT_LIMIT} times the {@link FOCUSABLE_SELECTOR} candidate count
|
|
1361
|
+
* plus ten, so a page of segmented inputs has a budget for their segments and picker indicators.
|
|
1343
1362
|
*
|
|
1344
1363
|
* @example
|
|
1345
1364
|
* ```ts
|
|
@@ -1529,6 +1548,16 @@ export declare function findKeyframes(name: string): CSSKeyframesRule | undefine
|
|
|
1529
1548
|
*/
|
|
1530
1549
|
export declare function findRule(selector: string): CSSStyleRule | undefined;
|
|
1531
1550
|
|
|
1551
|
+
/**
|
|
1552
|
+
* Bounds consecutive focus landings and the Tab presses budgeted per segmented input.
|
|
1553
|
+
*
|
|
1554
|
+
* @remarks
|
|
1555
|
+
* Chromium measured nine landings on a datetime-local input with step="0.001": year, month,
|
|
1556
|
+
* day, hour, minute, second, millisecond, and meridiem segments, plus the picker indicator.
|
|
1557
|
+
* The budget covers those landings with one spare press per input.
|
|
1558
|
+
*/
|
|
1559
|
+
export declare const FOCUS_SEGMENT_LIMIT = 10;
|
|
1560
|
+
|
|
1532
1561
|
/**
|
|
1533
1562
|
* Names what sequential keyboard navigation can reach, before disabled and unrendered elements go.
|
|
1534
1563
|
*
|
|
@@ -2035,11 +2064,13 @@ export declare function measureLuminance(color: Color): number;
|
|
|
2035
2064
|
*
|
|
2036
2065
|
* @remarks
|
|
2037
2066
|
* The value is a bit string in print, reduced motion, dark colour scheme, and forced colours order.
|
|
2038
|
-
* Each bit is `1` for a matching query and `0` otherwise, for example `0100`.
|
|
2067
|
+
* Each bit is `1` for a matching query and `0` otherwise, for example `0100`. The first pointer
|
|
2068
|
+
* stage appends a fifth bit for the pre-call `(pointer: coarse)` reading. Without a pointer stage,
|
|
2069
|
+
* the marker stays four bits and release leaves touch emulation alone.
|
|
2039
2070
|
*/
|
|
2040
2071
|
export declare const MEDIA_STAGE = "data-media-stage";
|
|
2041
2072
|
|
|
2042
|
-
/** Configures the tester's print medium, motion preference, and
|
|
2073
|
+
/** Configures the tester's print medium, motion preference, forced colours, and pointer precision. */
|
|
2043
2074
|
export declare interface MediaOptions {
|
|
2044
2075
|
/** Determines whether the tester lays out for print. Omit it to leave the medium alone. */
|
|
2045
2076
|
readonly print?: boolean;
|
|
@@ -2047,13 +2078,15 @@ export declare interface MediaOptions {
|
|
|
2047
2078
|
readonly motion?: boolean;
|
|
2048
2079
|
/** Determines whether the tester runs under forced colours. Omit it to leave the colours alone. */
|
|
2049
2080
|
readonly forced?: boolean;
|
|
2081
|
+
/** Selects touch emulation for coarse input or mouse input for fine precision. Omit it to leave touch emulation alone. */
|
|
2082
|
+
readonly pointer?: 'coarse' | 'fine';
|
|
2050
2083
|
}
|
|
2051
2084
|
|
|
2052
2085
|
/**
|
|
2053
2086
|
* Puts one element into the document and hands it straight back.
|
|
2054
2087
|
*
|
|
2055
2088
|
* @param element - The element to attach.
|
|
2056
|
-
* @returns The same element,
|
|
2089
|
+
* @returns The same element, appended to `document.body`.
|
|
2057
2090
|
*
|
|
2058
2091
|
* @remarks
|
|
2059
2092
|
* What this buys is the composition, not the attachment: the `append` method returns `void`, and
|
|
@@ -2183,7 +2216,7 @@ export declare function parseColor(value: string): Color | undefined;
|
|
|
2183
2216
|
* property is named by letters, digits, `_`, and `-` after its `--`. A name the scope leaves
|
|
2184
2217
|
* undeclared is not carried, so its `var()` fallback still applies.
|
|
2185
2218
|
*
|
|
2186
|
-
* The scope element is never written. The probe is
|
|
2219
|
+
* The scope element is never written. The probe is freshly created, so it has no earlier style to start a
|
|
2187
2220
|
* transition from, and a transition running on the scope keeps running: `currentColor` reads the
|
|
2188
2221
|
* color the scope shows at that moment, and the scope's geometry and scroll position stay as they
|
|
2189
2222
|
* were. No attribute, style, or child of the scope changes, so a `MutationObserver` on it records
|
|
@@ -2763,6 +2796,28 @@ export declare function readFrame(path: string): Promise<FrameReading>;
|
|
|
2763
2796
|
*/
|
|
2764
2797
|
export declare function readHit(element: Element): Element | undefined;
|
|
2765
2798
|
|
|
2799
|
+
/**
|
|
2800
|
+
* Reads layer statements and blocks in declaration order, including repeated names.
|
|
2801
|
+
*
|
|
2802
|
+
* @param source - The parsed sheet, or a grouping or style rule inside it.
|
|
2803
|
+
* @param layer - The qualified name of the layer enclosing the source, when one does.
|
|
2804
|
+
* @returns Qualified layer names, with an empty name for an anonymous top-level layer.
|
|
2805
|
+
*
|
|
2806
|
+
* @remarks
|
|
2807
|
+
* Descends through grouping and style rules at any depth, qualifying each name by its enclosing layer.
|
|
2808
|
+
* An anonymous layer inside a named layer contributes a trailing dot to that qualified name.
|
|
2809
|
+
* Conditions are read whether or not they match the document.
|
|
2810
|
+
* An `@import ... layer()` rule contributes nothing, and neither do its imported sheet's rules.
|
|
2811
|
+
* A dotted declaration such as `@layer a.b` contributes `a.b` as declared, without an implicit `a`.
|
|
2812
|
+
* Distinct anonymous layers produce the same names; the result does not distinguish their identities.
|
|
2813
|
+
*
|
|
2814
|
+
* @example
|
|
2815
|
+
* ```ts
|
|
2816
|
+
* readLayerNames(new CSSStyleSheet()) // []
|
|
2817
|
+
* ```
|
|
2818
|
+
*/
|
|
2819
|
+
export declare function readLayerNames(source: CSSStyleSheet | CSSGroupingRule | CSSStyleRule, layer?: string): readonly string[];
|
|
2820
|
+
|
|
2766
2821
|
/**
|
|
2767
2822
|
* Collects readable background color layers and refuses an unreadable painted layer.
|
|
2768
2823
|
*
|
|
@@ -2928,7 +2983,7 @@ export declare function readProtocolNode(element: Element): Promise<number>;
|
|
|
2928
2983
|
* Each frame on the way up adds its border and its padding, which is where its content starts,
|
|
2929
2984
|
* scales the point by the ratio of its painted width to its layout width, and adds its own position,
|
|
2930
2985
|
* so a tester iframe the runner scales or offsets is accounted for, and so is an iframe the page
|
|
2931
|
-
* itself nests, bordered, padded, or neither. The reading is of the layout
|
|
2986
|
+
* itself nests, bordered, padded, or neither. The reading is of the layout at the call: a box that moves
|
|
2932
2987
|
* afterwards moves the point it names. An element in a document no frame holds reads its own client
|
|
2933
2988
|
* point. A disconnected element has no layout, and its window still names the tester frame, so it is
|
|
2934
2989
|
* refused rather than read as that frame's corner.
|
|
@@ -2970,7 +3025,7 @@ export declare function readRefusal(name: string): string | undefined;
|
|
|
2970
3025
|
* sentence rather than a boolean. This fixes the resolver, translates the `unknown` a `catch` binds
|
|
2971
3026
|
* into `string | undefined`, and rethrows anything that is not an `Error` — a value no resolver
|
|
2972
3027
|
* raises, and one a caller reading a message would otherwise lose. `undefined` is rethrown with the
|
|
2973
|
-
* rest: a resolver that returned and
|
|
3028
|
+
* rest: a resolver that returned and an untrusted getter that threw `undefined` are different findings,
|
|
2974
3029
|
* which is why the `catch` is this function's own rather than a captured thrown value.
|
|
2975
3030
|
*
|
|
2976
3031
|
* It resolves rather than acts, so a target it reports `undefined` for is one an acting verb
|
|
@@ -2998,7 +3053,7 @@ export declare function readRefusal(role: string, name: string): string | undefi
|
|
|
2998
3053
|
* @remarks
|
|
2999
3054
|
* This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
|
|
3000
3055
|
* `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
|
|
3001
|
-
* painted
|
|
3056
|
+
* painted after it landed. A control that is not matching `:focus-visible` when the call is made
|
|
3002
3057
|
* reports nothing, because no measurement taken then would be about focus.
|
|
3003
3058
|
*
|
|
3004
3059
|
* Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
|
|
@@ -3041,7 +3096,7 @@ export declare function readRing(control: Element, worn?: Element): number | und
|
|
|
3041
3096
|
* A declared `role` wins outright, and its first token is the answer when several are listed.
|
|
3042
3097
|
* Otherwise the element's own anatomy decides: an anchor is a link only while it holds an `href`,
|
|
3043
3098
|
* an `input` takes the role {@link FIELD_ROLES} gives its type, a `select` is a combobox until it
|
|
3044
|
-
* offers several rows at once, a `section` is a region only
|
|
3099
|
+
* offers several rows at once, a `section` is a region only after something names it, and a `th`
|
|
3045
3100
|
* heads whichever axis its `scope` names. Every other tag answers from {@link IMPLICIT_ROLES},
|
|
3046
3101
|
* whose membership is the contract for what this can answer at all.
|
|
3047
3102
|
*
|
|
@@ -3267,6 +3322,14 @@ export declare function readValue(role: string, name: string): string;
|
|
|
3267
3322
|
* waits per axis for the recorded value, and removes the marker after every axis agrees. With no
|
|
3268
3323
|
* marker, sends the empty reset and compares readings taken strictly after that send. Each poll
|
|
3269
3324
|
* waits for a frame; the interval is 10 milliseconds. The provider must expose a DevTools session.
|
|
3325
|
+
* A fifth marker bit restores pointer precision through touch emulation. A four-bit marker or an
|
|
3326
|
+
* unstaged release leaves touch emulation alone. Restoring coarse precision uses one touch point;
|
|
3327
|
+
* the marker does not preserve a provider's earlier maximum touch-point count.
|
|
3328
|
+
* {@link releaseTouch} leaves this marker intact even when it disables a staged coarse pointer,
|
|
3329
|
+
* so media release still restores the reading recorded before the first pointer stage.
|
|
3330
|
+
* A first pointer stage while {@link tapTouch} emulation is live records coarse. In teardown,
|
|
3331
|
+
* call this release before {@link releaseTouch}; reversing the order restores coarse emulation
|
|
3332
|
+
* after touch cleanup.
|
|
3270
3333
|
*
|
|
3271
3334
|
* @example
|
|
3272
3335
|
* ```ts
|
|
@@ -3330,6 +3393,30 @@ export declare function releasePane(): Promise<void>;
|
|
|
3330
3393
|
*/
|
|
3331
3394
|
export declare function releasePointer(): Promise<void>;
|
|
3332
3395
|
|
|
3396
|
+
/**
|
|
3397
|
+
* Cancels emulated touch input, disables touch emulation, and parks the pointer.
|
|
3398
|
+
*
|
|
3399
|
+
* @returns A promise resolving after touch cleanup and the parked pointer's frame.
|
|
3400
|
+
* @throws Thrown when a protocol command fails, apart from Chromium's idle touch cancellation refusal.
|
|
3401
|
+
*
|
|
3402
|
+
* @remarks
|
|
3403
|
+
* Safe after a completed tap, a held touch, or an idle release. This sends no mouse button release.
|
|
3404
|
+
* A native drag that also holds the mouse requires its own `mouseReleased` protocol command before
|
|
3405
|
+
* parking. {@link releasePointer} releases only a press recorded by the package's hold verbs.
|
|
3406
|
+
* Parking after touch input does not prove that Chromium cleared sticky touch hover.
|
|
3407
|
+
* Disables even a coarse pointer staged by {@link stageMedia}, leaving its restoration marker
|
|
3408
|
+
* unchanged. Stage the coarse pointer again when later steps need it; {@link releaseMedia} still
|
|
3409
|
+
* restores the pointer reading recorded before the first pointer stage.
|
|
3410
|
+
* If that stage ran while {@link tapTouch} emulation was live, it recorded coarse. In teardown,
|
|
3411
|
+
* call {@link releaseMedia} before this cleanup; reversing the order ends with coarse emulation.
|
|
3412
|
+
*
|
|
3413
|
+
* @example
|
|
3414
|
+
* ```ts
|
|
3415
|
+
* await releaseTouch()
|
|
3416
|
+
* ```
|
|
3417
|
+
*/
|
|
3418
|
+
export declare function releaseTouch(): Promise<void>;
|
|
3419
|
+
|
|
3333
3420
|
/**
|
|
3334
3421
|
* Deletes one IndexedDB database and reports what the request actually did.
|
|
3335
3422
|
*
|
|
@@ -3497,12 +3584,40 @@ export declare function resolveFileInput(name: string): HTMLInputElement;
|
|
|
3497
3584
|
*/
|
|
3498
3585
|
export declare function resolveRendered(first: string, second?: string): HTMLElement;
|
|
3499
3586
|
|
|
3587
|
+
/** Names the native input types whose editable segments share one focused element. */
|
|
3588
|
+
export declare const SEGMENTED_INPUT_TYPES: readonly string[];
|
|
3589
|
+
|
|
3590
|
+
/**
|
|
3591
|
+
* Carries files from outside the page over a rendered target named by role and accessible name.
|
|
3592
|
+
*
|
|
3593
|
+
* @param type - The protocol drag event; cancellation leaves the target before ending the drag.
|
|
3594
|
+
* @param role - The target's accessible role.
|
|
3595
|
+
* @param name - The target's exact accessible name.
|
|
3596
|
+
* @param names - The file names to write under the provider root's `tmp/drag` directory.
|
|
3597
|
+
* @returns A promise resolving after the browser accepts the event.
|
|
3598
|
+
* @throws Thrown when the target is absent, ambiguous, or outside the viewport after scrolling,
|
|
3599
|
+
* a file name contains a path, or the provider refuses a file write or protocol command.
|
|
3600
|
+
*
|
|
3601
|
+
* @remarks
|
|
3602
|
+
* Resolves rendered elements through {@link isRendered}, without focus reachability. A status or
|
|
3603
|
+
* region can receive a drag without being a Tab stop. Events are trusted and carry the `Files`
|
|
3604
|
+
* type. No drop is sent. Chromium raises no `dragleave` for protocol cancellation alone, so
|
|
3605
|
+
* cancellation first moves the drag outside the page.
|
|
3606
|
+
*
|
|
3607
|
+
* @example
|
|
3608
|
+
* ```ts
|
|
3609
|
+
* await sendFileDrag('dragEnter', 'status', 'Drop status', ['note.txt'])
|
|
3610
|
+
* await sendFileDrag('dragCancel', 'status', 'Drop status', ['note.txt'])
|
|
3611
|
+
* ```
|
|
3612
|
+
*/
|
|
3613
|
+
export declare function sendFileDrag(type: 'dragEnter' | 'dragOver' | 'dragCancel', role: string, name: string, names: readonly string[]): Promise<void>;
|
|
3614
|
+
|
|
3500
3615
|
/**
|
|
3501
3616
|
* Sends one DevTools protocol command through the browser provider.
|
|
3502
3617
|
*
|
|
3503
3618
|
* @param method - The protocol method name.
|
|
3504
3619
|
* @param params - The protocol parameters. Omit them for a command that takes none.
|
|
3505
|
-
* @returns A promise resolving to the browser's reply
|
|
3620
|
+
* @returns A promise resolving to the browser's reply after the command completes.
|
|
3506
3621
|
* @throws Thrown when the provider exposes no DevTools session, or the command fails.
|
|
3507
3622
|
*
|
|
3508
3623
|
* @remarks
|
|
@@ -3516,6 +3631,24 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
|
|
|
3516
3631
|
*/
|
|
3517
3632
|
export declare function sendProtocol(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
|
|
3518
3633
|
|
|
3634
|
+
/**
|
|
3635
|
+
* Sends one emulated touch event through the browser protocol.
|
|
3636
|
+
*
|
|
3637
|
+
* @param type - The Chrome DevTools Protocol touch event type.
|
|
3638
|
+
* @param element - The connected element locating the touch; omit it to end or cancel every point.
|
|
3639
|
+
* @param point - The offset from the element's top-left corner. Default: `{ x: 20, y: 20 }`.
|
|
3640
|
+
* @returns A promise resolving after the browser accepts the event.
|
|
3641
|
+
* @throws Thrown when the element is disconnected, the provider exposes no DevTools session, or the
|
|
3642
|
+
* browser refuses the touch sequence.
|
|
3643
|
+
*
|
|
3644
|
+
* @example
|
|
3645
|
+
* ```ts
|
|
3646
|
+
* await sendTouch('touchStart', target)
|
|
3647
|
+
* await sendTouch('touchEnd')
|
|
3648
|
+
* ```
|
|
3649
|
+
*/
|
|
3650
|
+
export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd' | 'touchCancel', element?: Element, point?: ProtocolPoint): Promise<void>;
|
|
3651
|
+
|
|
3519
3652
|
/**
|
|
3520
3653
|
* Settles the page for one capture: parks the pointer, waits out every finite animation, and holds
|
|
3521
3654
|
* each endless animation at its first frame.
|
|
@@ -3531,7 +3664,7 @@ export declare function sendProtocol(method: string, params?: Readonly<Record<st
|
|
|
3531
3664
|
* A pointer left over a control paints that control's hover, and a transition still running paints
|
|
3532
3665
|
* a fill between two states, so neither is a state the interface rests in. An endless animation, a
|
|
3533
3666
|
* spinner or a placeholder shimmer, stands at a different phase in every frame unless it is held at
|
|
3534
|
-
* the same one, so each is paused at its first frame. Call the resume
|
|
3667
|
+
* the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
|
|
3535
3668
|
* capture that throws still owes it, so call it from a `finally` block.
|
|
3536
3669
|
*
|
|
3537
3670
|
* The subject is the whole document, its root element included. The pointer parks through
|
|
@@ -3565,6 +3698,20 @@ export declare interface SettleOptions extends WaitOptions {
|
|
|
3565
3698
|
readonly pointer?: boolean;
|
|
3566
3699
|
}
|
|
3567
3700
|
|
|
3701
|
+
/**
|
|
3702
|
+
* Describes an adopted stylesheet and its idempotent release operation.
|
|
3703
|
+
*/
|
|
3704
|
+
export declare interface SheetAdoption {
|
|
3705
|
+
/** Holds the stylesheet adopted into the document. */
|
|
3706
|
+
readonly sheet: CSSStyleSheet;
|
|
3707
|
+
/**
|
|
3708
|
+
* Removes this sheet from the document without removing another adoption.
|
|
3709
|
+
*
|
|
3710
|
+
* @returns Nothing.
|
|
3711
|
+
*/
|
|
3712
|
+
release(): void;
|
|
3713
|
+
}
|
|
3714
|
+
|
|
3568
3715
|
/**
|
|
3569
3716
|
* Configures how long a reading must hold still: the time bounds of {@link WaitOptions} and the
|
|
3570
3717
|
* count of reads it must agree across.
|
|
@@ -3578,13 +3725,13 @@ export declare interface StabilityOptions extends WaitOptions {
|
|
|
3578
3725
|
}
|
|
3579
3726
|
|
|
3580
3727
|
/**
|
|
3581
|
-
* Stages the tester's print medium, motion preference,
|
|
3582
|
-
* provider.
|
|
3728
|
+
* Stages the tester's print medium, motion preference, forced colours, and pointer precision through
|
|
3729
|
+
* the browser provider.
|
|
3583
3730
|
*
|
|
3584
3731
|
* @param options - The media axes to override.
|
|
3585
3732
|
* @returns A promise resolving after a bounded read-back for `print: true`, either `motion` value,
|
|
3586
|
-
* and either `
|
|
3587
|
-
* read-back.
|
|
3733
|
+
* either `forced` value, and either `pointer` value. A `print: false` stage is sent and followed by
|
|
3734
|
+
* a frame wait without a read-back.
|
|
3588
3735
|
* @throws Thrown when no axis is supplied or a staged query does not reach the tester.
|
|
3589
3736
|
*
|
|
3590
3737
|
* @remarks
|
|
@@ -3597,6 +3744,14 @@ export declare interface StabilityOptions extends WaitOptions {
|
|
|
3597
3744
|
* budgets. A restoration failure is attached as the refusal's cause. Register
|
|
3598
3745
|
* {@link releaseMedia} in teardown; it restores the readings observed before the first stage.
|
|
3599
3746
|
*
|
|
3747
|
+
* A coarse pointer enables single-point touch emulation; a fine pointer disables it. Chromium also
|
|
3748
|
+
* changes `any-pointer` and the hover queries. An omitted pointer never sends a touch-emulation
|
|
3749
|
+
* command. The first pointer stage appends its pre-call coarse reading to the media marker.
|
|
3750
|
+
* {@link releaseTouch} disables a staged coarse pointer without changing that marker. Stage the
|
|
3751
|
+
* pointer again after touch cleanup when later steps need coarse precision.
|
|
3752
|
+
* A first pointer stage while {@link tapTouch} emulation is live records coarse. In teardown,
|
|
3753
|
+
* call {@link releaseMedia} before {@link releaseTouch}; reversing the order ends coarse.
|
|
3754
|
+
*
|
|
3600
3755
|
* @example
|
|
3601
3756
|
* ```ts
|
|
3602
3757
|
* await stageMedia({ motion: false, print: true })
|
|
@@ -3616,7 +3771,7 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
|
|
|
3616
3771
|
*
|
|
3617
3772
|
* @remarks
|
|
3618
3773
|
* This depends on the runner's own tester layout, and that dependency is contract rather than an
|
|
3619
|
-
* accident: `vitest@4.1.
|
|
3774
|
+
* accident: `vitest@4.1.12` lays its tester out inside a smaller page, fits it by scaling the pane
|
|
3620
3775
|
* the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
|
|
3621
3776
|
* unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
|
|
3622
3777
|
* but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
|
|
@@ -3682,7 +3837,9 @@ export declare interface StateOptions extends WaitOptions {
|
|
|
3682
3837
|
* through the provider, reads the landing with {@link readActiveElement}, and leaves every decision
|
|
3683
3838
|
* to the caller: what counts as an end, a revisit, or a stop is the consumer's, because the two
|
|
3684
3839
|
* consumers disagree. The press is the next one only after the consumer asks for the next landing, so
|
|
3685
|
-
* a consumer that stops reading stops pressing.
|
|
3840
|
+
* a consumer that stops reading stops pressing. A native segmented input can yield the same element
|
|
3841
|
+
* for successive segment landings. This generator preserves each landing; its consumers count that
|
|
3842
|
+
* control once while continuing through its segments, and end a run beyond {@link FOCUS_SEGMENT_LIMIT}.
|
|
3686
3843
|
*
|
|
3687
3844
|
* @example
|
|
3688
3845
|
* ```ts
|
|
@@ -3716,6 +3873,46 @@ export declare interface StorageOptions {
|
|
|
3716
3873
|
readonly quota?: number;
|
|
3717
3874
|
}
|
|
3718
3875
|
|
|
3876
|
+
/**
|
|
3877
|
+
* Determines whether a native input exposes separately editable segments under one focused element.
|
|
3878
|
+
*
|
|
3879
|
+
* @param element - The element whose native input type is read in its own document's realm.
|
|
3880
|
+
* @returns True if the element is an input with a type in {@link SEGMENTED_INPUT_TYPES}, checked
|
|
3881
|
+
* against its own document's `HTMLInputElement`; false otherwise, including a document with no window.
|
|
3882
|
+
*
|
|
3883
|
+
* @example
|
|
3884
|
+
* ```ts
|
|
3885
|
+
* supportsSegmentedFocus(document.createElement('button')) // false
|
|
3886
|
+
* ```
|
|
3887
|
+
*/
|
|
3888
|
+
export declare function supportsSegmentedFocus(element: Element): boolean;
|
|
3889
|
+
|
|
3890
|
+
/**
|
|
3891
|
+
* Taps an element's centre with emulated touch after its box settles.
|
|
3892
|
+
*
|
|
3893
|
+
* @param element - The connected element locating the tap.
|
|
3894
|
+
* @param options - The stability frame count, time bounds, and abort signal.
|
|
3895
|
+
* @returns A promise resolving after the browser accepts the touch end.
|
|
3896
|
+
* @throws Thrown when stability fails, the element is disconnected, or a protocol command fails.
|
|
3897
|
+
*
|
|
3898
|
+
* @remarks
|
|
3899
|
+
* Uses one touch point and leaves touch emulation enabled until {@link releaseTouch}.
|
|
3900
|
+
* That cleanup disables even a coarse pointer staged by {@link stageMedia}; stage it again after
|
|
3901
|
+
* cleanup when later steps need coarse precision.
|
|
3902
|
+
* A first pointer stage while tap emulation is live records coarse as its pre-call reading.
|
|
3903
|
+
* In teardown, call {@link releaseMedia} before {@link releaseTouch}; reversing that order restores
|
|
3904
|
+
* coarse emulation after touch cleanup.
|
|
3905
|
+
* The wait uses {@link waitForStability}; an unsettled scroller can consume a tap to stop momentum
|
|
3906
|
+
* without producing a click. No scrolling or focus-reachability check is performed.
|
|
3907
|
+
*
|
|
3908
|
+
* @example
|
|
3909
|
+
* ```ts
|
|
3910
|
+
* await tapTouch(target, { budget: 2000 })
|
|
3911
|
+
* await releaseTouch()
|
|
3912
|
+
* ```
|
|
3913
|
+
*/
|
|
3914
|
+
export declare function tapTouch(element: Element, options?: StabilityOptions): Promise<void>;
|
|
3915
|
+
|
|
3719
3916
|
/**
|
|
3720
3917
|
* Reaches a named control only through natural forward Tab traversal from the current focus.
|
|
3721
3918
|
*
|
|
@@ -3724,7 +3921,9 @@ export declare interface StorageOptions {
|
|
|
3724
3921
|
* @throws When one complete traversal cannot reach the target.
|
|
3725
3922
|
*
|
|
3726
3923
|
* @remarks
|
|
3727
|
-
* The loop is {@link driveTraversal} over {@link resolveRendered}.
|
|
3924
|
+
* The loop is {@link driveTraversal} over {@link resolveRendered}. Consecutive landings inside a
|
|
3925
|
+
* native segmented input continue through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings.
|
|
3926
|
+
* A longer run or any other revisit ends the traversal.
|
|
3728
3927
|
*
|
|
3729
3928
|
* @example
|
|
3730
3929
|
* ```ts
|
|
@@ -3802,7 +4001,7 @@ export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElemen
|
|
|
3802
4001
|
*
|
|
3803
4002
|
* @param element - The element whose own animations and descendants' animations to wait on.
|
|
3804
4003
|
* @param options - The time bounds and the abort signal.
|
|
3805
|
-
* @returns A promise resolving
|
|
4004
|
+
* @returns A promise resolving after every finite animation has stopped running.
|
|
3806
4005
|
* @throws An `Error` when the element is not in a document, when a bound is invalid, or when an
|
|
3807
4006
|
* animation is still running at the budget; or the abort reason.
|
|
3808
4007
|
*
|
|
@@ -3937,8 +4136,8 @@ export declare function waitForState(role: string, name: string, state: string,
|
|
|
3937
4136
|
*
|
|
3938
4137
|
* @param stop - Accepts the destination. Omit it to census the remaining document.
|
|
3939
4138
|
* @returns Every element focus reached, in order and each once, the accepted stop last.
|
|
3940
|
-
* @throws Thrown when the walk
|
|
3941
|
-
*
|
|
4139
|
+
* @throws Thrown when the walk exceeds its press cap, a key press rejects, or focus lands in a
|
|
4140
|
+
* frame from another origin.
|
|
3942
4141
|
*
|
|
3943
4142
|
* @remarks
|
|
3944
4143
|
* The walk records the focused element and then presses Tab through {@link stepFocus}, so it reaches
|
|
@@ -3947,8 +4146,14 @@ export declare function waitForState(role: string, name: string, state: string,
|
|
|
3947
4146
|
* innermost focused element {@link readActiveElement} reads, so a control inside an open shadow root
|
|
3948
4147
|
* or a same-origin frame is a stop of its own, and its host or frame element is not. The walk ends
|
|
3949
4148
|
* with an empty list when only the body holds focus, and where focus revisits a stop or returns to
|
|
3950
|
-
* the body.
|
|
3951
|
-
*
|
|
4149
|
+
* the body. Consecutive landings on the same native segmented input continue through its segments
|
|
4150
|
+
* up to {@link FOCUS_SEGMENT_LIMIT} landings, including the initial focused element, and count that
|
|
4151
|
+
* control once. A longer run or any other revisit, including a repeated button in a focus trap,
|
|
4152
|
+
* ends the walk. Any different landing starts a separate run.
|
|
4153
|
+
* The press cap is {@link FOCUS_SEGMENT_LIMIT} times {@link countElements}, including
|
|
4154
|
+
* open shadow roots and same-origin frames. It applies no rule about which stop counts: the
|
|
4155
|
+
* predicate sees each one and decides, so a consumer that refuses a hidden stop throws from its own
|
|
4156
|
+
* predicate.
|
|
3952
4157
|
*
|
|
3953
4158
|
* A closed shadow root cannot be entered, so its host stands for everything inside it, and a frame
|
|
3954
4159
|
* from another origin is refused because its controls cannot be named.
|