@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 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 forced colours. */
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, and forced colours through the browser
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 `forced` value. A `print: false` stage is sent and followed by a frame wait without a
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
  *