@orkestrel/test 0.0.29 → 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.
@@ -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 AnimationReading {
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 CAPTURE_STAGINGS = 4;
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 CAPTURE_STAGINGS} restagings, when the provider wrote
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 file is read back through the runner's built-in `readFile` command and compared with
287
- * the shot itself, which is what separates a frame this run wrote from one an earlier run left
288
- * behind. The provider resolves `options.path` against the calling test file and returns an absolute
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 CAPTURE_STAGINGS} and the shot is refused with
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 CensusReading {
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. */
@@ -1346,9 +1354,12 @@ export declare function driveHold(resolve: () => HTMLElement, name: string): Pro
1346
1354
  * Reaches the control a resolver returns, only through natural forward Tab traversal from the
1347
1355
  * current focus.
1348
1356
  *
1349
- * @param resolve - The resolver that returns the target, called before the first step and again on
1350
- * every step, because a framework may replace the node between resolution and focus arrival.
1357
+ * @param resolve - The resolver called before traversal and at candidate arrivals, without retaining
1358
+ * its result between steps.
1351
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.
1352
1363
  * @returns The target after the browser moves focus to it.
1353
1364
  * @throws When the resolver refuses, or one complete traversal cannot reach the target.
1354
1365
  *
@@ -1365,7 +1376,7 @@ export declare function driveHold(resolve: () => HTMLElement, name: string): Pro
1365
1376
  * await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
1366
1377
  * ```
1367
1378
  */
1368
- 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>;
1369
1380
 
1370
1381
  /**
1371
1382
  * Configures one built element: its class list, its text, and its attributes.
@@ -1607,7 +1618,7 @@ export declare interface FrameOptions {
1607
1618
  * color in the `rgb(r, g, b)` form a computed style is written in, so a literal comparison,
1608
1619
  * `parseColor`, and `matchesColor` all take it.
1609
1620
  */
1610
- export declare interface FrameReading {
1621
+ export declare interface FrameResult {
1611
1622
  /** Holds the frame's width in device pixels. */
1612
1623
  readonly width: number;
1613
1624
  /** Holds the frame's height in device pixels. */
@@ -1616,6 +1627,14 @@ export declare interface FrameReading {
1616
1627
  readonly floor: string | undefined;
1617
1628
  }
1618
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
+
1619
1638
  /**
1620
1639
  * Holds a mounted statechart harness, the tally it publishes, and the run it drives.
1621
1640
  *
@@ -1985,6 +2004,30 @@ export declare interface JournalStep {
1985
2004
  */
1986
2005
  export declare function matchesColor(first: string | Color, second: string | Color): boolean;
1987
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
+
1988
2031
  /**
1989
2032
  * Measures the row the document's own content ends on, in document coordinates.
1990
2033
  *
@@ -2402,7 +2445,7 @@ export declare function readActiveElement(root?: Document | ShadowRoot): HTMLEle
2402
2445
  * readAnimations(document.documentElement).finite.length // 0 once every transition has settled
2403
2446
  * ```
2404
2447
  */
2405
- export declare function readAnimations(element: Element): AnimationReading;
2448
+ export declare function readAnimations(element: Element): AnimationResult;
2406
2449
 
2407
2450
  /**
2408
2451
  * Resolves the opaque color standing behind one element.
@@ -2433,6 +2476,22 @@ export declare function readAnimations(element: Element): AnimationReading;
2433
2476
  */
2434
2477
  export declare function readBackdrop(element: Element, floor: Color): Color;
2435
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
+
2436
2495
  /**
2437
2496
  * Collects every class token the stylesheets loaded into this document actually define.
2438
2497
  *
@@ -2494,7 +2553,7 @@ export declare function readCascade(): ReadonlySet<string>;
2494
2553
  * readCensus(container).undeclared // ['lead'] — no loaded stylesheet declares it
2495
2554
  * ```
2496
2555
  */
2497
- export declare function readCensus(root: ParentNode): CensusReading;
2556
+ export declare function readCensus(root: ParentNode): CensusResult;
2498
2557
 
2499
2558
  /**
2500
2559
  * Collects every class token the markup under one root carries.
@@ -2732,10 +2791,10 @@ export declare function readFocus(): string | undefined;
2732
2791
  *
2733
2792
  * @example
2734
2793
  * ```ts
2735
- * const reading = await readFrame(written)
2794
+ * const result = await readFrame(written)
2736
2795
  * ```
2737
2796
  */
2738
- export declare function readFrame(path: string): Promise<FrameReading>;
2797
+ export declare function readFrame(path: string): Promise<FrameResult>;
2739
2798
 
2740
2799
  /**
2741
2800
  * Reads the topmost element at one element's bounding-box centre.
@@ -3353,7 +3412,9 @@ export declare function releaseMedia(): Promise<void>;
3353
3412
  * otherwise read the last capture's variant. The size comes off the {@link CAPTURE_PANE} value
3354
3413
  * {@link stagePane} wrote onto the rule element, which is the reading taken before the first
3355
3414
  * staging. Calling this on an unstaged pane finds no such value, so it changes nothing and resizes
3356
- * 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.
3357
3418
  *
3358
3419
  * That hand-back is what makes {@link stagePane} and this pair a capture's staging rather than a
3359
3420
  * resize: the pair puts the tester back where it found it, so a suite that used it to reach a
@@ -3780,6 +3841,8 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
3780
3841
  * selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
3781
3842
  * `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
3782
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.
3783
3846
  *
3784
3847
  * Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
3785
3848
  * the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
@@ -3797,7 +3860,8 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
3797
3860
  * the shot replaces the node and takes any attribute of ours with it.
3798
3861
  *
3799
3862
  * The wait is two frames rather than a delay: the first carries the resize into layout and the
3800
- * 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.
3801
3865
  *
3802
3866
  * The viewport the tester had before this staging is written onto that rule element as the
3803
3867
  * {@link CAPTURE_PANE} value, in `<width>x<height>` form, and {@link releasePane} hands it back.
@@ -3921,7 +3985,8 @@ export declare function tapTouch(element: Element, options?: StabilityOptions):
3921
3985
  * @throws When one complete traversal cannot reach the target.
3922
3986
  *
3923
3987
  * @remarks
3924
- * The loop is {@link driveTraversal} over {@link resolveRendered}. Consecutive landings inside a
3988
+ * The loop is {@link driveTraversal} over {@link resolveRendered}, with a conservative name check
3989
+ * before each arrival resolution. Consecutive landings inside a
3925
3990
  * native segmented input continue through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings.
3926
3991
  * A longer run or any other revisit ends the traversal.
3927
3992
  *
@@ -3944,7 +4009,8 @@ export declare function traverseAccessible(name: string): Promise<HTMLElement>;
3944
4009
  *
3945
4010
  * @remarks
3946
4011
  * The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
3947
- * 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.
3948
4014
  *
3949
4015
  * @example
3950
4016
  * ```ts
@@ -3996,6 +4062,22 @@ export declare function typeAccessible(name: string, text: string): Promise<void
3996
4062
  */
3997
4063
  export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
3998
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
+
3999
4081
  /**
4000
4082
  * Waits until every finite animation on one element and its subtree has stopped moving.
4001
4083
  *