@orkestrel/test 0.0.39 → 0.0.41
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 +17 -10
- package/dist/src/browser/index.d.ts +238 -48
- package/dist/src/browser/index.js +356 -105
- package/dist/src/browser/index.js.map +1 -1
- package/dist/src/server/index.cjs +113 -20
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +107 -9
- package/dist/src/server/index.d.ts +107 -9
- package/dist/src/server/index.js +112 -22
- package/dist/src/server/index.js.map +1 -1
- package/package.json +11 -21
- package/dist/bin/reporter.d.ts +0 -5
- package/dist/bin/reporter.js +0 -6
- package/dist/bin/reporter.js.map +0 -1
package/README.md
CHANGED
|
@@ -111,7 +111,7 @@ const sources = readInventory(root, ['src/core', 'src/server'], { extensions: ['
|
|
|
111
111
|
Object.keys(sources)
|
|
112
112
|
// ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts', 'src/core/helpers.ts', 'src/core/index.ts',
|
|
113
113
|
// 'src/core/types.ts', 'src/core/validators.ts', 'src/server/Loopback.ts', 'src/server/constants.ts',
|
|
114
|
-
// 'src/server/factories.ts', 'src/server/helpers.ts', 'src/server/index.ts',
|
|
114
|
+
// 'src/server/factories.ts', 'src/server/helpers.ts', 'src/server/index.ts', 'src/server/plugins.ts',
|
|
115
115
|
// 'src/server/reporters/ProgressReporter.ts',
|
|
116
116
|
// 'src/server/types.ts', 'src/server/validators.ts']
|
|
117
117
|
|
|
@@ -136,7 +136,7 @@ Object.keys(
|
|
|
136
136
|
Object.keys(
|
|
137
137
|
readInventory(root, ['src'], { extensions: ['.ts'], exclude: ['src/server', 'src/browser'] }),
|
|
138
138
|
)
|
|
139
|
-
// ['src/
|
|
139
|
+
// ['src/core/Production.ts', 'src/core/Teardown.ts', 'src/core/constants.ts', 'src/core/factories.ts',
|
|
140
140
|
// 'src/core/helpers.ts', 'src/core/index.ts', 'src/core/types.ts', 'src/core/validators.ts']
|
|
141
141
|
```
|
|
142
142
|
|
|
@@ -217,17 +217,24 @@ rule deciding what ships and what stays in the package that owns it — see
|
|
|
217
217
|
## Package
|
|
218
218
|
|
|
219
219
|
Published as typed entry points per the `exports` field in `package.json`: `@orkestrel/test` for the
|
|
220
|
-
host-independent core, `@orkestrel/test/browser` for the journey layer,
|
|
221
|
-
for the Node helpers
|
|
222
|
-
|
|
223
|
-
`vitest/browser` is an ES-only module, and the reporter entry ships ESM only. The reporter entry
|
|
224
|
-
lives at `src/bin/reporter.ts` and builds to `dist/bin/reporter.js`; the specifier does not name
|
|
225
|
-
that path.
|
|
220
|
+
host-independent core, `@orkestrel/test/browser` for the journey layer, and
|
|
221
|
+
`@orkestrel/test/server` for the Node helpers. Core and server ship ESM and CommonJS. The browser
|
|
222
|
+
face ships ESM only, because `vitest/browser` is an ES-only module.
|
|
226
223
|
|
|
227
|
-
|
|
224
|
+
To run a suite with the progress reporter under command-line `--reporter` flags, mount the
|
|
225
|
+
progress plugin in the configuration:
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
import { defineConfig } from 'vitest/config'
|
|
229
|
+
import { createProgressPlugin } from '@orkestrel/test/server'
|
|
230
|
+
|
|
231
|
+
export default defineConfig({ plugins: [createProgressPlugin()] })
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Then name the file the reporter appends to:
|
|
228
235
|
|
|
229
236
|
```sh
|
|
230
|
-
npx vitest run --reporter
|
|
237
|
+
npx vitest run --reporter=dot --outputFile.progress=tmp/runs/progress.jsonl
|
|
231
238
|
```
|
|
232
239
|
|
|
233
240
|
## License
|
|
@@ -418,6 +418,9 @@ export declare const CAPTURE_STAGE_LIMIT = 4;
|
|
|
418
418
|
* transformed ancestor is counted as a row, though the top layer lays it out. A region inside a
|
|
419
419
|
* closed shadow root is unreachable, so its rows stay hidden without a refusal.
|
|
420
420
|
*
|
|
421
|
+
* To shoot the declared viewport at the scroll the page holds rather than the document, call
|
|
422
|
+
* {@link captureViewport}.
|
|
423
|
+
*
|
|
421
424
|
* @example
|
|
422
425
|
* ```ts
|
|
423
426
|
* await captureFrame({ path: '../../tmp/capture/start.png', width: 390, height: 844 })
|
|
@@ -445,6 +448,44 @@ export declare interface CaptureVariant extends JourneyVariant {
|
|
|
445
448
|
readonly apply?: () => void;
|
|
446
449
|
}
|
|
447
450
|
|
|
451
|
+
/**
|
|
452
|
+
* Shoots the declared viewport at the scroll the page holds and proves the file on disk holds this
|
|
453
|
+
* run's bytes.
|
|
454
|
+
*
|
|
455
|
+
* @param options - The path to write and the viewport to shoot at.
|
|
456
|
+
* @returns The absolute path of the written frame, after it has been read back and matched.
|
|
457
|
+
* @throws Thrown when the pane cannot be staged, when the cover cannot lay out over the viewport,
|
|
458
|
+
* when the provider wrote the frame somewhere else, and when the bytes on disk are not the ones this
|
|
459
|
+
* shot produced.
|
|
460
|
+
*
|
|
461
|
+
* @remarks
|
|
462
|
+
* The pane is staged at the declared viewport alone, no height is measured, and no taller pane is
|
|
463
|
+
* staged, so a mark the scroll drives keeps naming what the viewport shows. A tester that is not at
|
|
464
|
+
* the declared viewport is resized to it first, and the frame then holds the scroll the page keeps
|
|
465
|
+
* at that size. The shot is taken of a transparent fixed box, the cover, appended to the root
|
|
466
|
+
* element and removed on every path; the cover sends no pointer input and receives none. Its
|
|
467
|
+
* `position`, `inset`, `opacity`, and `pointer-events` declarations are set inline as important, so
|
|
468
|
+
* a page rule marked important does not paint it over the shot.
|
|
469
|
+
*
|
|
470
|
+
* The cover's box is read after it is appended, and a box that does not start at the viewport's
|
|
471
|
+
* origin at the viewport's size refuses the shot with
|
|
472
|
+
* `Capture frame at <path> cannot cover the viewport: a fixed box on the root element lays out at <w>x<h> from (<x>, <y>) in a <w>x<h> viewport`.
|
|
473
|
+
* The check reads the box, not its cause: a root element that becomes the cover's containing block,
|
|
474
|
+
* through a transform or a paint containment, lays the cover out over its own box, so the shot is
|
|
475
|
+
* refused wherever that box differs from the viewport, as a scrolled or a taller document's does,
|
|
476
|
+
* and taken where the two coincide.
|
|
477
|
+
*
|
|
478
|
+
* The pane is released and the scroll of the window and of every scroll container
|
|
479
|
+
* {@link collectScrollContainers} finds is restored before this returns, on every path, as
|
|
480
|
+
* {@link captureFrame} does. The file is verified as {@link verifyFrame} verifies it.
|
|
481
|
+
*
|
|
482
|
+
* @example
|
|
483
|
+
* ```ts
|
|
484
|
+
* await captureViewport({ path: '../../tmp/capture/contents.png', width: 390, height: 844 })
|
|
485
|
+
* ```
|
|
486
|
+
*/
|
|
487
|
+
export declare function captureViewport(options: ViewportOptions): Promise<string>;
|
|
488
|
+
|
|
448
489
|
/**
|
|
449
490
|
* Holds detached markup an authored-class census must report as undeclared.
|
|
450
491
|
*
|
|
@@ -1352,22 +1393,34 @@ export declare function createPointerEvent(name: string, options?: PointerEventI
|
|
|
1352
1393
|
/**
|
|
1353
1394
|
* Creates the capture portfolio one run places its screenshots through; a disabled run still refuses.
|
|
1354
1395
|
*
|
|
1355
|
-
* @param options - The state registry, the
|
|
1356
|
-
* directory it writes into, and whether it writes at all.
|
|
1357
|
-
* @returns The portfolio: its registry expansion, what it has placed,
|
|
1358
|
-
*
|
|
1396
|
+
* @param options - The state registry, the one state it projects, the variant matrix, the variant
|
|
1397
|
+
* this run renders, the directory and scopes it writes into, and whether it writes at all.
|
|
1398
|
+
* @returns The portfolio: its registry expansion, what it has accepted and placed, `place`, and
|
|
1399
|
+
* `view`.
|
|
1400
|
+
* @throws When no registered variant carries the name `variant` names, when the registry does not
|
|
1401
|
+
* carry the `state` option, and when `scope` names a scope that is not one path segment.
|
|
1359
1402
|
*
|
|
1360
1403
|
* @remarks
|
|
1361
|
-
* A disabled portfolio is the ordinary run. `place` then
|
|
1362
|
-
*
|
|
1363
|
-
* for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled
|
|
1364
|
-
* refuses an unregistered state name and a second placement of one state, so a wrong name
|
|
1365
|
-
* ordinary run
|
|
1366
|
-
*
|
|
1404
|
+
* A disabled portfolio is the ordinary run. `place` and `view` then resize nothing, write nothing,
|
|
1405
|
+
* and record no placement, so a journey calls them unconditionally and a suite with the flag unset
|
|
1406
|
+
* pays for none of it. The portfolio refuses an unregistered variant at creation. Every run, enabled
|
|
1407
|
+
* or not, refuses an unregistered state name and a second placement of one state, so a wrong name
|
|
1408
|
+
* fails the ordinary run, and an unrolled portfolio refuses every `view` in every run, with the text
|
|
1409
|
+
* {@link describeUnrolledView} renders. A placement holds its state from before its first await
|
|
1410
|
+
* until it settles, so a concurrent placement of that state is refused as already placed, and a
|
|
1411
|
+
* placement that throws leaves its state unplaced. `observed` lists every state `place` and `view`
|
|
1412
|
+
* accepted, written or not, and `placements` lists the ones they wrote, so a disabled run's
|
|
1413
|
+
* `placements` stays empty.
|
|
1367
1414
|
*
|
|
1368
|
-
*
|
|
1369
|
-
*
|
|
1370
|
-
*
|
|
1415
|
+
* A `state` option projects the run onto one state: `place` and `view` write that state and accept
|
|
1416
|
+
* every other registered state unwritten. A `scope` handler writes each state under
|
|
1417
|
+
* `<directory>/<scope>/`, and `files` carries the same scope, as {@link expandCaptures} expands it.
|
|
1418
|
+
*
|
|
1419
|
+
* An enabled `place` writes through `captureFrame`, and an enabled `view` through
|
|
1420
|
+
* `captureViewport`, so a placed state carries that helper's staged pane and its byte readback: a
|
|
1421
|
+
* path is recorded only after the file on disk has been proved to hold this run's own frame. The
|
|
1422
|
+
* portfolio's `unrolled` option reaches every frame `place` writes. `view` shoots the declared
|
|
1423
|
+
* viewport at the scroll the journey reached.
|
|
1371
1424
|
*
|
|
1372
1425
|
* @example
|
|
1373
1426
|
* ```ts
|
|
@@ -1497,6 +1550,24 @@ export declare function describeScrollRegions(regions: readonly HTMLElement[]):
|
|
|
1497
1550
|
*/
|
|
1498
1551
|
export declare function describeTree(element: Element): string;
|
|
1499
1552
|
|
|
1553
|
+
/**
|
|
1554
|
+
* Describes the refusal of a viewport placement in an unrolled portfolio.
|
|
1555
|
+
*
|
|
1556
|
+
* @param state - The state the placement named.
|
|
1557
|
+
* @returns The refusal, naming the state and the two placements that can shoot it.
|
|
1558
|
+
*
|
|
1559
|
+
* @remarks
|
|
1560
|
+
* An unrolled portfolio covers every row each scroll region hides, and a viewport frame covers the
|
|
1561
|
+
* rows the scroll shows, so a portfolio refuses the pairing in every run, written or not.
|
|
1562
|
+
*
|
|
1563
|
+
* @example
|
|
1564
|
+
* ```ts
|
|
1565
|
+
* describeUnrolledView('contents-scrolled')
|
|
1566
|
+
* // 'Capture state "contents-scrolled" cannot be viewed in an unrolled portfolio: place it to shoot every row, or view it from a portfolio created without unrolled'
|
|
1567
|
+
* ```
|
|
1568
|
+
*/
|
|
1569
|
+
export declare function describeUnrolledView(state: string): string;
|
|
1570
|
+
|
|
1500
1571
|
/**
|
|
1501
1572
|
* Holds the primary pointer button on the control a resolver returns, through the browser provider.
|
|
1502
1573
|
*
|
|
@@ -1594,12 +1665,16 @@ export declare interface EscapeFixture {
|
|
|
1594
1665
|
*
|
|
1595
1666
|
* @param states - The registered state names.
|
|
1596
1667
|
* @param variants - The variants the portfolio is rendered in.
|
|
1597
|
-
* @
|
|
1598
|
-
*
|
|
1668
|
+
* @param scope - The handler naming each state's scope directory. Omit it to name no directory.
|
|
1669
|
+
* @returns One `<state>--<variant>.png` name per pair, each under `<scope>/` where `scope` is given,
|
|
1670
|
+
* each state's variants together, in registry order.
|
|
1671
|
+
* @throws Thrown when `scope` names a scope that is empty, `.`, `..`, or carries a slash or a
|
|
1672
|
+
* backslash, because a scope is one path segment.
|
|
1599
1673
|
*
|
|
1600
1674
|
* @remarks
|
|
1601
1675
|
* The expansion is the portfolio's own definition of complete, so a duplicate in it is a registry
|
|
1602
|
-
* defect a proof reads directly rather than a collision discovered on disk.
|
|
1676
|
+
* defect a proof reads directly rather than a collision discovered on disk. The handler is called
|
|
1677
|
+
* once per state.
|
|
1603
1678
|
*
|
|
1604
1679
|
* @example
|
|
1605
1680
|
* ```ts
|
|
@@ -1607,7 +1682,7 @@ export declare interface EscapeFixture {
|
|
|
1607
1682
|
* // ['start--dark-390.png']
|
|
1608
1683
|
* ```
|
|
1609
1684
|
*/
|
|
1610
|
-
export declare function expandCaptures(states: readonly string[], variants: readonly CaptureVariant[]): readonly string[];
|
|
1685
|
+
export declare function expandCaptures(states: readonly string[], variants: readonly CaptureVariant[], scope?: ScopeHandler): readonly string[];
|
|
1611
1686
|
|
|
1612
1687
|
/**
|
|
1613
1688
|
* Collects every element carrying a component class rendered outside the container it belongs to.
|
|
@@ -1769,13 +1844,7 @@ export declare interface FrameOffset {
|
|
|
1769
1844
|
}
|
|
1770
1845
|
|
|
1771
1846
|
/** Configures one captured frame: where it is written, the viewport it is shot at, and what it shoots. */
|
|
1772
|
-
export declare interface FrameOptions {
|
|
1773
|
-
/** Holds the frame's path, relative to the calling test file. */
|
|
1774
|
-
readonly path: string;
|
|
1775
|
-
/** Holds the viewport width in CSS pixels the frame is shot at. */
|
|
1776
|
-
readonly width: number;
|
|
1777
|
-
/** Holds the viewport height in CSS pixels the frame is shot at. */
|
|
1778
|
-
readonly height: number;
|
|
1847
|
+
export declare interface FrameOptions extends ViewportOptions {
|
|
1779
1848
|
/** Holds the element to shoot. Omit it to shoot the whole page. */
|
|
1780
1849
|
readonly element?: Element | undefined;
|
|
1781
1850
|
/**
|
|
@@ -2224,7 +2293,7 @@ export declare function matchesTraversalName(element: HTMLElement, name: string,
|
|
|
2224
2293
|
*
|
|
2225
2294
|
* Each element contributes its client rectangle's bottom edge in document coordinates plus its own
|
|
2226
2295
|
* bottom margin, which sits outside that rectangle, and the largest contribution wins. An ancestor
|
|
2227
|
-
* that clips its overflow, which the {@link
|
|
2296
|
+
* that clips its overflow, which the {@link readClipBound} helper finds through the flat
|
|
2228
2297
|
* tree and so reaches a shadow wrapper around a slot, caps the contribution at that ancestor's clip
|
|
2229
2298
|
* edge, which the {@link readClipEdge} helper measures, because the rows a descendant lays out past a clipping
|
|
2230
2299
|
* frame are cut, scrolled, or discarded rather than added to the document: a viewport-height
|
|
@@ -2292,9 +2361,11 @@ export declare function measureLuminance(color: RGBA): number;
|
|
|
2292
2361
|
* The `scrollHeight` property never reads less than the `clientHeight` property, so a region whose
|
|
2293
2362
|
* rows fit reads its box rather than its rows, and the slack under its last row cannot be read
|
|
2294
2363
|
* there. This reading can, because it is taken over the elements inside the region rather than
|
|
2295
|
-
* over its box: each element contributes its bottom edge plus its own bottom margin,
|
|
2296
|
-
*
|
|
2297
|
-
*
|
|
2364
|
+
* over its box: each element contributes its bottom edge plus its own bottom margin, and the
|
|
2365
|
+
* largest contribution wins. Where the region itself clips its overflow, as the {@link clipsOverflow}
|
|
2366
|
+
* helper reports it, each contribution is capped at the clip edge, as the {@link readClipEdge}
|
|
2367
|
+
* helper measures it, of every clipping ancestor between the element and the region; where the
|
|
2368
|
+
* region clips nothing, no contribution is capped. The region's scroll offset is added back, so
|
|
2298
2369
|
* a scrolled region reads the same rows as an unscrolled one. The elements are the ones
|
|
2299
2370
|
* {@link collectRegionRows} reaches through the flat tree, so a host's shadow rows and a slot's
|
|
2300
2371
|
* assigned rows count, and a fixed or absolute box laid out against a block outside the region
|
|
@@ -2497,7 +2568,9 @@ export declare const POINTER_HOLD = "data-pointer-hold";
|
|
|
2497
2568
|
export declare interface PortfolioInterface {
|
|
2498
2569
|
/** Holds the name of the variant this run renders. */
|
|
2499
2570
|
readonly variant: string;
|
|
2500
|
-
/** Lists every state
|
|
2571
|
+
/** Lists every state `place` and `view` accepted so far, written or not, in placement order. */
|
|
2572
|
+
readonly observed: readonly string[];
|
|
2573
|
+
/** Lists every state written so far, in placement order. */
|
|
2501
2574
|
readonly placements: readonly string[];
|
|
2502
2575
|
/** Lists every path written so far, in write order. */
|
|
2503
2576
|
readonly paths: readonly string[];
|
|
@@ -2509,11 +2582,25 @@ export declare interface PortfolioInterface {
|
|
|
2509
2582
|
*
|
|
2510
2583
|
* @param state - The state name from the registry.
|
|
2511
2584
|
* @param element - The element to shoot. Omit it to shoot the whole page.
|
|
2512
|
-
* @returns The written path, or `undefined` when the portfolio is not enabled
|
|
2513
|
-
*
|
|
2514
|
-
* not
|
|
2585
|
+
* @returns The written path, or `undefined` when the portfolio is not enabled or the state is not
|
|
2586
|
+
* the one `state` projects.
|
|
2587
|
+
* @throws When the state is not registered, has already been placed or is being placed, or the
|
|
2588
|
+
* written frame does not read back as the bytes this shot produced.
|
|
2515
2589
|
*/
|
|
2516
2590
|
place(state: string, element?: Element): Promise<string | undefined>;
|
|
2591
|
+
/**
|
|
2592
|
+
* Places one registered state as the declared viewport at the scroll the journey reached:
|
|
2593
|
+
* applies the variant, stages the pane at the variant's size alone, and writes the verified
|
|
2594
|
+
* screenshot.
|
|
2595
|
+
*
|
|
2596
|
+
* @param state - The state name from the registry.
|
|
2597
|
+
* @returns The written path, or `undefined` when the portfolio is not enabled or the state is not
|
|
2598
|
+
* the one `state` projects.
|
|
2599
|
+
* @throws When the state is not registered, has already been placed or is being placed, or the
|
|
2600
|
+
* portfolio is unrolled, in every run; and when the written frame does not read back as the bytes
|
|
2601
|
+
* this shot produced.
|
|
2602
|
+
*/
|
|
2603
|
+
view(state: string): Promise<string | undefined>;
|
|
2517
2604
|
}
|
|
2518
2605
|
|
|
2519
2606
|
/**
|
|
@@ -2526,6 +2613,11 @@ export declare interface PortfolioOptions {
|
|
|
2526
2613
|
* this list, so the registry and the disk cannot drift apart.
|
|
2527
2614
|
*/
|
|
2528
2615
|
readonly states: readonly string[];
|
|
2616
|
+
/**
|
|
2617
|
+
* Holds the one state this run writes. Omit it to write every state. `place` accepts each other
|
|
2618
|
+
* registered state unwritten. Creation throws when the registry does not carry it.
|
|
2619
|
+
*/
|
|
2620
|
+
readonly state?: string;
|
|
2529
2621
|
/** Lists every variant the portfolio can be rendered in. One run renders exactly one of them. */
|
|
2530
2622
|
readonly variants: readonly CaptureVariant[];
|
|
2531
2623
|
/** Holds the name of the variant this run renders. Creation throws when no variant carries it. */
|
|
@@ -2533,13 +2625,20 @@ export declare interface PortfolioOptions {
|
|
|
2533
2625
|
/** Holds the directory each written file is placed in, relative to the calling test file. */
|
|
2534
2626
|
readonly directory: string;
|
|
2535
2627
|
/**
|
|
2536
|
-
*
|
|
2537
|
-
*
|
|
2628
|
+
* Names the scope directory each state is written under, inside `directory`. Omit it to write
|
|
2629
|
+
* every state into `directory` itself.
|
|
2630
|
+
*/
|
|
2631
|
+
readonly scope?: ScopeHandler;
|
|
2632
|
+
/**
|
|
2633
|
+
* Determines whether this run writes files. An ordinary run leaves it unset, so `place` and
|
|
2634
|
+
* `view` resize nothing and write nothing, and `placements` and `paths` stay empty while
|
|
2635
|
+
* `observed` still lists every state they accept.
|
|
2538
2636
|
*/
|
|
2539
2637
|
readonly enabled?: boolean;
|
|
2540
2638
|
/**
|
|
2541
|
-
* If `true`, every frame `place` writes also covers the rows every vertical scroll region hides
|
|
2542
|
-
* if `false` or omitted, each frame ends where the document's own
|
|
2639
|
+
* If `true`, every frame `place` writes also covers the rows every vertical scroll region hides,
|
|
2640
|
+
* and `view` refuses every state; if `false` or omitted, each frame ends where the document's own
|
|
2641
|
+
* content ends.
|
|
2543
2642
|
*/
|
|
2544
2643
|
readonly unrolled?: boolean;
|
|
2545
2644
|
}
|
|
@@ -2792,6 +2891,34 @@ export declare function readCensus(root: ParentNode): CensusResult;
|
|
|
2792
2891
|
*/
|
|
2793
2892
|
export declare function readClasses(root: ParentNode): ReadonlySet<string>;
|
|
2794
2893
|
|
|
2894
|
+
/**
|
|
2895
|
+
* Reads the lowest clip edge the clipping ancestors between an element and a region put on it.
|
|
2896
|
+
*
|
|
2897
|
+
* @param element - The element to read.
|
|
2898
|
+
* @param region - The flat-tree ancestor the climb stops at, itself not counted.
|
|
2899
|
+
* @param bounds - The memo one measurement shares across its elements, keyed by ancestor. Default:
|
|
2900
|
+
* a fresh memo.
|
|
2901
|
+
* @returns The lowest edge, in document coordinates, that the {@link readClipEdge} helper measures
|
|
2902
|
+
* on a clipping ancestor strictly between the element and the region; `Infinity` where none of them
|
|
2903
|
+
* clips; and `undefined` where the region is no flat-tree ancestor of the element.
|
|
2904
|
+
* @throws Thrown when the element is not connected to a document, as the
|
|
2905
|
+
* {@link collectClippingAncestors} helper throws.
|
|
2906
|
+
*
|
|
2907
|
+
* @remarks
|
|
2908
|
+
* The climb takes the steps the {@link readFlatParent} helper reads, as the
|
|
2909
|
+
* {@link collectClippingAncestors} helper does. Each ancestor's entry in `bounds` holds the bound it
|
|
2910
|
+
* hands down: its own clip edge and every bound above it, up to the region. A measurement that
|
|
2911
|
+
* reads every element of a subtree through one memo therefore reads each ancestor's style once,
|
|
2912
|
+
* rather than once for every element under it.
|
|
2913
|
+
*
|
|
2914
|
+
* @example
|
|
2915
|
+
* ```ts
|
|
2916
|
+
* const bounds = new Map<Element, number | undefined>()
|
|
2917
|
+
* readClipBound(row, document.body, bounds) // the edge of the nearest hidden frame around the row
|
|
2918
|
+
* ```
|
|
2919
|
+
*/
|
|
2920
|
+
export declare function readClipBound(element: Element, region: Element, bounds?: Map<Element, number | undefined>): number | undefined;
|
|
2921
|
+
|
|
2795
2922
|
/**
|
|
2796
2923
|
* Measures the row a clipping element cuts its content off at, in document coordinates.
|
|
2797
2924
|
*
|
|
@@ -2977,6 +3104,24 @@ export declare function readContrast(element: Element, floor?: RGBA): number;
|
|
|
2977
3104
|
*/
|
|
2978
3105
|
export declare function readControlValue(role: string, name: string): string;
|
|
2979
3106
|
|
|
3107
|
+
/**
|
|
3108
|
+
* Reads an element's parent in the flat tree, the tree a browser paints.
|
|
3109
|
+
*
|
|
3110
|
+
* @param element - The element to step up from.
|
|
3111
|
+
* @returns The slot the element is assigned to, else its parent element, else the host of the
|
|
3112
|
+
* shadow root it stands in, and `undefined` for an element with none of the three.
|
|
3113
|
+
*
|
|
3114
|
+
* @remarks
|
|
3115
|
+
* The `assignedSlot` property reports no slot of a closed shadow root, so a child assigned into one
|
|
3116
|
+
* steps to its light parent instead.
|
|
3117
|
+
*
|
|
3118
|
+
* @example
|
|
3119
|
+
* ```ts
|
|
3120
|
+
* readFlatParent(slotted) // the slot it is assigned to, inside its parent's open shadow root
|
|
3121
|
+
* ```
|
|
3122
|
+
*/
|
|
3123
|
+
export declare function readFlatParent(element: Element): Element | undefined;
|
|
3124
|
+
|
|
2980
3125
|
/**
|
|
2981
3126
|
* Reads the rendered text of the element that holds focus.
|
|
2982
3127
|
*
|
|
@@ -3628,6 +3773,27 @@ export declare function readToken(element: Element, name: string): string;
|
|
|
3628
3773
|
*/
|
|
3629
3774
|
export declare function recordConsole(name: string, output: string[], forward: (...data: unknown[]) => void): (...data: unknown[]) => void;
|
|
3630
3775
|
|
|
3776
|
+
/**
|
|
3777
|
+
* Records the scroll position of the tester's window and of every scroll container in its body, and
|
|
3778
|
+
* returns the callback that scrolls each of them back.
|
|
3779
|
+
*
|
|
3780
|
+
* @returns A callback that scrolls the window and each recorded container back to the position this
|
|
3781
|
+
* call read, instantly.
|
|
3782
|
+
*
|
|
3783
|
+
* @remarks
|
|
3784
|
+
* The containers are the ones {@link collectScrollContainers} finds when this is called. A capture
|
|
3785
|
+
* records them before its first staging, because growing a region clamps its scroll position and an
|
|
3786
|
+
* element frame's alignment scrolls a container too, and restores them after the pane is released.
|
|
3787
|
+
*
|
|
3788
|
+
* @example
|
|
3789
|
+
* ```ts
|
|
3790
|
+
* const restore = recordScroll()
|
|
3791
|
+
* window.scrollTo({ top: 600, behavior: 'instant' })
|
|
3792
|
+
* restore() // the window is back at the scroll it held
|
|
3793
|
+
* ```
|
|
3794
|
+
*/
|
|
3795
|
+
export declare function recordScroll(): () => void;
|
|
3796
|
+
|
|
3631
3797
|
/**
|
|
3632
3798
|
* Restores the media readings observed before the first stage as explicit emulation. With nothing
|
|
3633
3799
|
* staged, clears every override and waits for a stable reading, not a proved engine baseline. Checks
|
|
@@ -3954,6 +4120,15 @@ export declare function resolveRendered(first: string, second?: string): HTMLEle
|
|
|
3954
4120
|
*/
|
|
3955
4121
|
export declare type RGBA = readonly [red: number, green: number, blue: number, alpha: number];
|
|
3956
4122
|
|
|
4123
|
+
/**
|
|
4124
|
+
* Names the scope directory one capture state is written under, one path segment.
|
|
4125
|
+
*
|
|
4126
|
+
* @remarks
|
|
4127
|
+
* A portfolio calls it with each registered state, so it must return the same scope for a state on
|
|
4128
|
+
* every call.
|
|
4129
|
+
*/
|
|
4130
|
+
export declare type ScopeHandler = (state: string) => string;
|
|
4131
|
+
|
|
3957
4132
|
/** Names the native input types whose editable segments share one focused element. */
|
|
3958
4133
|
export declare const SEGMENTED_INPUT_TYPES: readonly string[];
|
|
3959
4134
|
|
|
@@ -4024,8 +4199,8 @@ export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd'
|
|
|
4024
4199
|
* each endless animation at its first frame.
|
|
4025
4200
|
*
|
|
4026
4201
|
* @param options - The time bounds of the wait, its abort signal, and whether the pointer parks.
|
|
4027
|
-
* @returns A promise resolving, after
|
|
4028
|
-
* sets every held animation running again.
|
|
4202
|
+
* @returns A promise resolving, after the listeners a finished animation's end event reaches have
|
|
4203
|
+
* run, to the resume: a function that sets every held animation running again.
|
|
4029
4204
|
* @throws Thrown when the pointer cannot park, as {@link parkPointer} raises it, and when a finite
|
|
4030
4205
|
* animation is still running at the budget, as {@link waitForAnimations} raises it. An aborted wait
|
|
4031
4206
|
* rejects with the signal's reason.
|
|
@@ -4037,6 +4212,12 @@ export declare function sendTouch(type: 'touchStart' | 'touchMove' | 'touchEnd'
|
|
|
4037
4212
|
* the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
|
|
4038
4213
|
* capture that throws still owes it, so call it from a `finally` block.
|
|
4039
4214
|
*
|
|
4215
|
+
* The settle waits one frame before it reads the animations, so a transition the page starts from
|
|
4216
|
+
* an animation-frame callback after the act is running when the wait reads it. The browser
|
|
4217
|
+
* dispatches an animation's end event, such as `transitionend`, after its `finished` promise
|
|
4218
|
+
* settles, so the settle yields one task after the wait: a page listener that finalizes its layout
|
|
4219
|
+
* on that event has run when the settle resolves.
|
|
4220
|
+
*
|
|
4040
4221
|
* The subject is the whole document, its root element included. The pointer parks through
|
|
4041
4222
|
* {@link parkPointer}, which sends no button release, so a held press stays held either way. Pass
|
|
4042
4223
|
* `pointer: false` only where the pointer is part of the state, such as a drag in flight: the
|
|
@@ -4164,17 +4345,15 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
|
|
|
4164
4345
|
*
|
|
4165
4346
|
* @remarks
|
|
4166
4347
|
* This depends on the runner's own tester layout, and that dependency is contract rather than an
|
|
4167
|
-
* accident: `vitest@
|
|
4168
|
-
*
|
|
4348
|
+
* accident: `vitest@5.1.0` lays its tester out inside a smaller page, fits it with a CSS scale, and
|
|
4349
|
+
* clips whatever overflows the pane the tester sits in. Layout inside the tester is
|
|
4169
4350
|
* unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
|
|
4170
4351
|
* but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
|
|
4171
4352
|
* a thumbnail of the surface and a frame shot after only unscaling it is a sliver. The tester is
|
|
4172
4353
|
* therefore unscaled and lifted to the window's own origin for the shot. The `iframe[data-vitest]`
|
|
4173
|
-
* selector and the `--
|
|
4174
|
-
*
|
|
4175
|
-
*
|
|
4176
|
-
* The custom-property overrides serve Vitest 4; `transform: none !important` on the pane and
|
|
4177
|
-
* iframe also suppresses Vitest 5's direct CSS transform.
|
|
4354
|
+
* selector and the `--viewport-width` and `--viewport-height` custom properties are the runner's, so
|
|
4355
|
+
* a Vitest release that renames any of them reddens the size check that follows rather than writing
|
|
4356
|
+
* a wrong frame. `transform: none !important` on the pane and iframe suppresses the fitting scale.
|
|
4178
4357
|
*
|
|
4179
4358
|
* Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
|
|
4180
4359
|
* the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
|
|
@@ -4185,9 +4364,10 @@ export declare function stageMedia(options: MediaOptions): Promise<void>;
|
|
|
4185
4364
|
* there. Staging and releasing as a pair resizes and then undoes the resize, so the journey step
|
|
4186
4365
|
* after it runs at the size the file started at.
|
|
4187
4366
|
*
|
|
4188
|
-
* The rule is declared rather than written inline, because the runner writes its
|
|
4189
|
-
*
|
|
4190
|
-
*
|
|
4367
|
+
* The rule is declared rather than written inline, because the runner writes its scale as an inline
|
|
4368
|
+
* `transform` on the tester's iframe and the viewport as inline custom properties on the body, and
|
|
4369
|
+
* rewrites them whenever the tester resizes. A declared rule marked important outranks an inline
|
|
4370
|
+
* value and survives every rewrite. It finds the pane by the
|
|
4191
4371
|
* tester it contains as well as by {@link CAPTURE_PANE}, because a re-render between the staging and
|
|
4192
4372
|
* the shot replaces the node and takes any attribute of ours with it.
|
|
4193
4373
|
*
|
|
@@ -4420,6 +4600,16 @@ export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElemen
|
|
|
4420
4600
|
*/
|
|
4421
4601
|
export declare function verifyFrame(shot: FrameShot, path: string, reader?: CaptureReader): Promise<void>;
|
|
4422
4602
|
|
|
4603
|
+
/** Configures one viewport shot: where it is written and the viewport it is shot at. */
|
|
4604
|
+
export declare interface ViewportOptions {
|
|
4605
|
+
/** Holds the frame's path, relative to the calling test file. */
|
|
4606
|
+
readonly path: string;
|
|
4607
|
+
/** Holds the viewport width in CSS pixels the frame is shot at. */
|
|
4608
|
+
readonly width: number;
|
|
4609
|
+
/** Holds the viewport height in CSS pixels the frame is shot at. */
|
|
4610
|
+
readonly height: number;
|
|
4611
|
+
}
|
|
4612
|
+
|
|
4423
4613
|
/**
|
|
4424
4614
|
* Waits until every finite animation on one element and its subtree has stopped moving.
|
|
4425
4615
|
*
|