@orkestrel/test 0.0.27 → 0.0.28
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 +4 -0
- package/dist/src/browser/index.d.ts +169 -6
- package/dist/src/browser/index.js +2739 -2494
- package/dist/src/browser/index.js.map +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -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,
|
|
@@ -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
|
*
|
|
@@ -2035,11 +2049,13 @@ export declare function measureLuminance(color: Color): number;
|
|
|
2035
2049
|
*
|
|
2036
2050
|
* @remarks
|
|
2037
2051
|
* 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`.
|
|
2052
|
+
* Each bit is `1` for a matching query and `0` otherwise, for example `0100`. The first pointer
|
|
2053
|
+
* stage appends a fifth bit for the pre-call `(pointer: coarse)` reading. Without a pointer stage,
|
|
2054
|
+
* the marker stays four bits and release leaves touch emulation alone.
|
|
2039
2055
|
*/
|
|
2040
2056
|
export declare const MEDIA_STAGE = "data-media-stage";
|
|
2041
2057
|
|
|
2042
|
-
/** Configures the tester's print medium, motion preference, and
|
|
2058
|
+
/** Configures the tester's print medium, motion preference, forced colours, and pointer precision. */
|
|
2043
2059
|
export declare interface MediaOptions {
|
|
2044
2060
|
/** Determines whether the tester lays out for print. Omit it to leave the medium alone. */
|
|
2045
2061
|
readonly print?: boolean;
|
|
@@ -2047,6 +2063,8 @@ export declare interface MediaOptions {
|
|
|
2047
2063
|
readonly motion?: boolean;
|
|
2048
2064
|
/** Determines whether the tester runs under forced colours. Omit it to leave the colours alone. */
|
|
2049
2065
|
readonly forced?: boolean;
|
|
2066
|
+
/** Selects touch emulation for coarse input or mouse input for fine precision. Omit it to leave touch emulation alone. */
|
|
2067
|
+
readonly pointer?: 'coarse' | 'fine';
|
|
2050
2068
|
}
|
|
2051
2069
|
|
|
2052
2070
|
/**
|
|
@@ -2763,6 +2781,28 @@ export declare function readFrame(path: string): Promise<FrameReading>;
|
|
|
2763
2781
|
*/
|
|
2764
2782
|
export declare function readHit(element: Element): Element | undefined;
|
|
2765
2783
|
|
|
2784
|
+
/**
|
|
2785
|
+
* Reads layer statements and blocks in declaration order, including repeated names.
|
|
2786
|
+
*
|
|
2787
|
+
* @param source - The parsed sheet, or a grouping or style rule inside it.
|
|
2788
|
+
* @param layer - The qualified name of the layer enclosing the source, when one does.
|
|
2789
|
+
* @returns Qualified layer names, with an empty name for an anonymous top-level layer.
|
|
2790
|
+
*
|
|
2791
|
+
* @remarks
|
|
2792
|
+
* Descends through grouping and style rules at any depth, qualifying each name by its enclosing layer.
|
|
2793
|
+
* An anonymous layer inside a named layer contributes a trailing dot to that qualified name.
|
|
2794
|
+
* Conditions are read whether or not they match the document.
|
|
2795
|
+
* An `@import ... layer()` rule contributes nothing, and neither do its imported sheet's rules.
|
|
2796
|
+
* A dotted declaration such as `@layer a.b` contributes `a.b` as declared, without an implicit `a`.
|
|
2797
|
+
* Distinct anonymous layers produce the same names; the result does not distinguish their identities.
|
|
2798
|
+
*
|
|
2799
|
+
* @example
|
|
2800
|
+
* ```ts
|
|
2801
|
+
* readLayerNames(new CSSStyleSheet()) // []
|
|
2802
|
+
* ```
|
|
2803
|
+
*/
|
|
2804
|
+
export declare function readLayerNames(source: CSSStyleSheet | CSSGroupingRule | CSSStyleRule, layer?: string): readonly string[];
|
|
2805
|
+
|
|
2766
2806
|
/**
|
|
2767
2807
|
* Collects readable background color layers and refuses an unreadable painted layer.
|
|
2768
2808
|
*
|
|
@@ -3267,6 +3307,14 @@ export declare function readValue(role: string, name: string): string;
|
|
|
3267
3307
|
* waits per axis for the recorded value, and removes the marker after every axis agrees. With no
|
|
3268
3308
|
* marker, sends the empty reset and compares readings taken strictly after that send. Each poll
|
|
3269
3309
|
* waits for a frame; the interval is 10 milliseconds. The provider must expose a DevTools session.
|
|
3310
|
+
* A fifth marker bit restores pointer precision through touch emulation. A four-bit marker or an
|
|
3311
|
+
* unstaged release leaves touch emulation alone. Restoring coarse precision uses one touch point;
|
|
3312
|
+
* the marker does not preserve a provider's earlier maximum touch-point count.
|
|
3313
|
+
* {@link releaseTouch} leaves this marker intact even when it disables a staged coarse pointer,
|
|
3314
|
+
* so media release still restores the reading recorded before the first pointer stage.
|
|
3315
|
+
* A first pointer stage while {@link tapTouch} emulation is live records coarse. In teardown,
|
|
3316
|
+
* call this release before {@link releaseTouch}; reversing the order restores coarse emulation
|
|
3317
|
+
* after touch cleanup.
|
|
3270
3318
|
*
|
|
3271
3319
|
* @example
|
|
3272
3320
|
* ```ts
|
|
@@ -3330,6 +3378,30 @@ export declare function releasePane(): Promise<void>;
|
|
|
3330
3378
|
*/
|
|
3331
3379
|
export declare function releasePointer(): Promise<void>;
|
|
3332
3380
|
|
|
3381
|
+
/**
|
|
3382
|
+
* Cancels emulated touch input, disables touch emulation, and parks the pointer.
|
|
3383
|
+
*
|
|
3384
|
+
* @returns A promise resolving after touch cleanup and the parked pointer's frame.
|
|
3385
|
+
* @throws Thrown when a protocol command fails, apart from Chromium's idle touch cancellation refusal.
|
|
3386
|
+
*
|
|
3387
|
+
* @remarks
|
|
3388
|
+
* Safe after a completed tap, a held touch, or an idle release. This sends no mouse button release.
|
|
3389
|
+
* A native drag that also holds the mouse requires its own `mouseReleased` protocol command before
|
|
3390
|
+
* parking. {@link releasePointer} releases only a press recorded by the package's hold verbs.
|
|
3391
|
+
* Parking after touch input does not prove that Chromium cleared sticky touch hover.
|
|
3392
|
+
* Disables even a coarse pointer staged by {@link stageMedia}, leaving its restoration marker
|
|
3393
|
+
* unchanged. Stage the coarse pointer again when later steps need it; {@link releaseMedia} still
|
|
3394
|
+
* restores the pointer reading recorded before the first pointer stage.
|
|
3395
|
+
* If that stage ran while {@link tapTouch} emulation was live, it recorded coarse. In teardown,
|
|
3396
|
+
* call {@link releaseMedia} before this cleanup; reversing the order ends with coarse emulation.
|
|
3397
|
+
*
|
|
3398
|
+
* @example
|
|
3399
|
+
* ```ts
|
|
3400
|
+
* await releaseTouch()
|
|
3401
|
+
* ```
|
|
3402
|
+
*/
|
|
3403
|
+
export declare function releaseTouch(): Promise<void>;
|
|
3404
|
+
|
|
3333
3405
|
/**
|
|
3334
3406
|
* Deletes one IndexedDB database and reports what the request actually did.
|
|
3335
3407
|
*
|
|
@@ -3497,6 +3569,31 @@ export declare function resolveFileInput(name: string): HTMLInputElement;
|
|
|
3497
3569
|
*/
|
|
3498
3570
|
export declare function resolveRendered(first: string, second?: string): HTMLElement;
|
|
3499
3571
|
|
|
3572
|
+
/**
|
|
3573
|
+
* Carries files from outside the page over a rendered target named by role and accessible name.
|
|
3574
|
+
*
|
|
3575
|
+
* @param type - The protocol drag event; cancellation leaves the target before ending the drag.
|
|
3576
|
+
* @param role - The target's accessible role.
|
|
3577
|
+
* @param name - The target's exact accessible name.
|
|
3578
|
+
* @param names - The file names to write under the provider root's `tmp/drag` directory.
|
|
3579
|
+
* @returns A promise resolving after the browser accepts the event.
|
|
3580
|
+
* @throws Thrown when the target is absent, ambiguous, or outside the viewport after scrolling,
|
|
3581
|
+
* a file name contains a path, or the provider refuses a file write or protocol command.
|
|
3582
|
+
*
|
|
3583
|
+
* @remarks
|
|
3584
|
+
* Resolves rendered elements through {@link isRendered}, without focus reachability. A status or
|
|
3585
|
+
* region can receive a drag without being a Tab stop. Events are trusted and carry the `Files`
|
|
3586
|
+
* type. No drop is sent. Chromium raises no `dragleave` for protocol cancellation alone, so
|
|
3587
|
+
* cancellation first moves the drag outside the page.
|
|
3588
|
+
*
|
|
3589
|
+
* @example
|
|
3590
|
+
* ```ts
|
|
3591
|
+
* await sendFileDrag('dragEnter', 'status', 'Drop status', ['note.txt'])
|
|
3592
|
+
* await sendFileDrag('dragCancel', 'status', 'Drop status', ['note.txt'])
|
|
3593
|
+
* ```
|
|
3594
|
+
*/
|
|
3595
|
+
export declare function sendFileDrag(type: 'dragEnter' | 'dragOver' | 'dragCancel', role: string, name: string, names: readonly string[]): Promise<void>;
|
|
3596
|
+
|
|
3500
3597
|
/**
|
|
3501
3598
|
* Sends one DevTools protocol command through the browser provider.
|
|
3502
3599
|
*
|
|
@@ -3516,6 +3613,24 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
|
|
|
3516
3613
|
*/
|
|
3517
3614
|
export declare function sendProtocol(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
|
|
3518
3615
|
|
|
3616
|
+
/**
|
|
3617
|
+
* Sends one emulated touch event through the browser protocol.
|
|
3618
|
+
*
|
|
3619
|
+
* @param type - The Chrome DevTools Protocol touch event type.
|
|
3620
|
+
* @param element - The connected element locating the touch; omit it to end or cancel every point.
|
|
3621
|
+
* @param point - The offset from the element's top-left corner. Default: `{ x: 20, y: 20 }`.
|
|
3622
|
+
* @returns A promise resolving after the browser accepts the event.
|
|
3623
|
+
* @throws Thrown when the element is disconnected, the provider exposes no DevTools session, or the
|
|
3624
|
+
* browser refuses the touch sequence.
|
|
3625
|
+
*
|
|
3626
|
+
* @example
|
|
3627
|
+
* ```ts
|
|
3628
|
+
* await sendTouch('touchStart', target)
|
|
3629
|
+
* await sendTouch('touchEnd')
|
|
3630
|
+
* ```
|
|
3631
|
+
*/
|
|
3632
|
+
export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd' | 'touchCancel', element?: Element, point?: ProtocolPoint): Promise<void>;
|
|
3633
|
+
|
|
3519
3634
|
/**
|
|
3520
3635
|
* Settles the page for one capture: parks the pointer, waits out every finite animation, and holds
|
|
3521
3636
|
* each endless animation at its first frame.
|
|
@@ -3565,6 +3680,20 @@ export declare interface SettleOptions extends WaitOptions {
|
|
|
3565
3680
|
readonly pointer?: boolean;
|
|
3566
3681
|
}
|
|
3567
3682
|
|
|
3683
|
+
/**
|
|
3684
|
+
* Describes an adopted stylesheet and its idempotent release operation.
|
|
3685
|
+
*/
|
|
3686
|
+
export declare interface SheetAdoption {
|
|
3687
|
+
/** Holds the stylesheet adopted into the document. */
|
|
3688
|
+
readonly sheet: CSSStyleSheet;
|
|
3689
|
+
/**
|
|
3690
|
+
* Removes this sheet from the document without removing another adoption.
|
|
3691
|
+
*
|
|
3692
|
+
* @returns Nothing.
|
|
3693
|
+
*/
|
|
3694
|
+
release(): void;
|
|
3695
|
+
}
|
|
3696
|
+
|
|
3568
3697
|
/**
|
|
3569
3698
|
* Configures how long a reading must hold still: the time bounds of {@link WaitOptions} and the
|
|
3570
3699
|
* count of reads it must agree across.
|
|
@@ -3578,13 +3707,13 @@ export declare interface StabilityOptions extends WaitOptions {
|
|
|
3578
3707
|
}
|
|
3579
3708
|
|
|
3580
3709
|
/**
|
|
3581
|
-
* Stages the tester's print medium, motion preference,
|
|
3582
|
-
* provider.
|
|
3710
|
+
* Stages the tester's print medium, motion preference, forced colours, and pointer precision through
|
|
3711
|
+
* the browser provider.
|
|
3583
3712
|
*
|
|
3584
3713
|
* @param options - The media axes to override.
|
|
3585
3714
|
* @returns A promise resolving after a bounded read-back for `print: true`, either `motion` value,
|
|
3586
|
-
* and either `
|
|
3587
|
-
* read-back.
|
|
3715
|
+
* either `forced` value, and either `pointer` value. A `print: false` stage is sent and followed by
|
|
3716
|
+
* a frame wait without a read-back.
|
|
3588
3717
|
* @throws Thrown when no axis is supplied or a staged query does not reach the tester.
|
|
3589
3718
|
*
|
|
3590
3719
|
* @remarks
|
|
@@ -3597,6 +3726,14 @@ export declare interface StabilityOptions extends WaitOptions {
|
|
|
3597
3726
|
* budgets. A restoration failure is attached as the refusal's cause. Register
|
|
3598
3727
|
* {@link releaseMedia} in teardown; it restores the readings observed before the first stage.
|
|
3599
3728
|
*
|
|
3729
|
+
* A coarse pointer enables single-point touch emulation; a fine pointer disables it. Chromium also
|
|
3730
|
+
* changes `any-pointer` and the hover queries. An omitted pointer never sends a touch-emulation
|
|
3731
|
+
* command. The first pointer stage appends its pre-call coarse reading to the media marker.
|
|
3732
|
+
* {@link releaseTouch} disables a staged coarse pointer without changing that marker. Stage the
|
|
3733
|
+
* pointer again after touch cleanup when later steps need coarse precision.
|
|
3734
|
+
* A first pointer stage while {@link tapTouch} emulation is live records coarse. In teardown,
|
|
3735
|
+
* call {@link releaseMedia} before {@link releaseTouch}; reversing the order ends coarse.
|
|
3736
|
+
*
|
|
3600
3737
|
* @example
|
|
3601
3738
|
* ```ts
|
|
3602
3739
|
* await stageMedia({ motion: false, print: true })
|
|
@@ -3716,6 +3853,32 @@ export declare interface StorageOptions {
|
|
|
3716
3853
|
readonly quota?: number;
|
|
3717
3854
|
}
|
|
3718
3855
|
|
|
3856
|
+
/**
|
|
3857
|
+
* Taps an element's centre with emulated touch after its box settles.
|
|
3858
|
+
*
|
|
3859
|
+
* @param element - The connected element locating the tap.
|
|
3860
|
+
* @param options - The stability frame count, time bounds, and abort signal.
|
|
3861
|
+
* @returns A promise resolving after the browser accepts the touch end.
|
|
3862
|
+
* @throws Thrown when stability fails, the element is disconnected, or a protocol command fails.
|
|
3863
|
+
*
|
|
3864
|
+
* @remarks
|
|
3865
|
+
* Uses one touch point and leaves touch emulation enabled until {@link releaseTouch}.
|
|
3866
|
+
* That cleanup disables even a coarse pointer staged by {@link stageMedia}; stage it again after
|
|
3867
|
+
* cleanup when later steps need coarse precision.
|
|
3868
|
+
* A first pointer stage while tap emulation is live records coarse as its pre-call reading.
|
|
3869
|
+
* In teardown, call {@link releaseMedia} before {@link releaseTouch}; reversing that order restores
|
|
3870
|
+
* coarse emulation after touch cleanup.
|
|
3871
|
+
* The wait uses {@link waitForStability}; an unsettled scroller can consume a tap to stop momentum
|
|
3872
|
+
* without producing a click. No scrolling or focus-reachability check is performed.
|
|
3873
|
+
*
|
|
3874
|
+
* @example
|
|
3875
|
+
* ```ts
|
|
3876
|
+
* await tapTouch(target, { budget: 2000 })
|
|
3877
|
+
* await releaseTouch()
|
|
3878
|
+
* ```
|
|
3879
|
+
*/
|
|
3880
|
+
export declare function tapTouch(element: Element, options?: StabilityOptions): Promise<void>;
|
|
3881
|
+
|
|
3719
3882
|
/**
|
|
3720
3883
|
* Reaches a named control only through natural forward Tab traversal from the current focus.
|
|
3721
3884
|
*
|