@orkestrel/test 0.0.28 → 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.
- package/README.md +5 -5
- package/dist/src/browser/index.d.ts +162 -38
- package/dist/src/browser/index.js +227 -73
- package/dist/src/browser/index.js.map +1 -1
- package/dist/src/core/index.cjs +10 -10
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +1 -1
- package/dist/src/core/index.d.ts +1 -1
- package/dist/src/core/index.js +10 -10
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +31 -12
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +34 -20
- package/dist/src/server/index.d.ts +34 -20
- package/dist/src/server/index.js +31 -13
- package/dist/src/server/index.js.map +1 -1
- package/package.json +7 -7
|
@@ -7,7 +7,7 @@ import { isArray, isError, isNumber, isRecord, isString, resolveField } from "@o
|
|
|
7
7
|
*
|
|
8
8
|
* @param method - The protocol method name.
|
|
9
9
|
* @param params - The protocol parameters. Omit them for a command that takes none.
|
|
10
|
-
* @returns A promise resolving to the browser's reply
|
|
10
|
+
* @returns A promise resolving to the browser's reply after the command completes.
|
|
11
11
|
* @throws Thrown when the provider exposes no DevTools session, or the command fails.
|
|
12
12
|
*
|
|
13
13
|
* @remarks
|
|
@@ -75,7 +75,7 @@ function build(tag, options) {
|
|
|
75
75
|
* Puts one element into the document and hands it straight back.
|
|
76
76
|
*
|
|
77
77
|
* @param element - The element to attach.
|
|
78
|
-
* @returns The same element,
|
|
78
|
+
* @returns The same element, appended to `document.body`.
|
|
79
79
|
*
|
|
80
80
|
* @remarks
|
|
81
81
|
* What this buys is the composition, not the attachment: the `append` method returns `void`, and
|
|
@@ -209,6 +209,23 @@ var FIELD_ROLES = Object.freeze({
|
|
|
209
209
|
* the one list either one reads.
|
|
210
210
|
*/
|
|
211
211
|
var FOCUSABLE_SELECTOR = "a[href], area[href], button, input, select, summary, textarea, [tabindex]";
|
|
212
|
+
/** Names the native input types whose editable segments share one focused element. */
|
|
213
|
+
var SEGMENTED_INPUT_TYPES = Object.freeze([
|
|
214
|
+
"date",
|
|
215
|
+
"time",
|
|
216
|
+
"datetime-local",
|
|
217
|
+
"month",
|
|
218
|
+
"week"
|
|
219
|
+
]);
|
|
220
|
+
/**
|
|
221
|
+
* Bounds consecutive focus landings and the Tab presses budgeted per segmented input.
|
|
222
|
+
*
|
|
223
|
+
* @remarks
|
|
224
|
+
* Chromium measured nine landings on a datetime-local input with step="0.001": year, month,
|
|
225
|
+
* day, hour, minute, second, millisecond, and meridiem segments, plus the picker indicator.
|
|
226
|
+
* The budget covers those landings with one spare press per input.
|
|
227
|
+
*/
|
|
228
|
+
var FOCUS_SEGMENT_LIMIT = 10;
|
|
212
229
|
/**
|
|
213
230
|
* Names the role a `th` carries for the header axis its `scope` names.
|
|
214
231
|
*
|
|
@@ -315,7 +332,7 @@ var CAPTURE_PANE = "data-capture-pane";
|
|
|
315
332
|
* one restaging past the cap before it comes back down to the edge. Nothing measured needs a
|
|
316
333
|
* fourth, so a fourth is the headroom that keeps a settling document off the refusal.
|
|
317
334
|
*/
|
|
318
|
-
var
|
|
335
|
+
var CAPTURE_STAGE_LIMIT = 4;
|
|
319
336
|
/**
|
|
320
337
|
* Names the tester root's attribute holding the media readings observed before the first stage.
|
|
321
338
|
*
|
|
@@ -578,7 +595,7 @@ function measureContent() {
|
|
|
578
595
|
*
|
|
579
596
|
* @remarks
|
|
580
597
|
* This depends on the runner's own tester layout, and that dependency is contract rather than an
|
|
581
|
-
* accident: `vitest@4.1.
|
|
598
|
+
* accident: `vitest@4.1.12` lays its tester out inside a smaller page, fits it by scaling the pane
|
|
582
599
|
* the tester sits in, and clips whatever overflows that pane. Layout inside the tester is
|
|
583
600
|
* unaffected — the tester reports the viewport it was given and every breakpoint answers to it —
|
|
584
601
|
* but a screenshot is taken off the page the runner painted, so a frame shot through that scale is
|
|
@@ -587,6 +604,8 @@ function measureContent() {
|
|
|
587
604
|
* selector and the `--tester-transform`, `--tester-margin-left`, `--viewport-width`, and
|
|
588
605
|
* `--viewport-height` custom properties are the runner's, so a Vitest release that renames any of
|
|
589
606
|
* them reddens the size check that follows rather than writing a wrong frame.
|
|
607
|
+
* The custom-property overrides serve Vitest 4; `transform: none !important` on the pane and
|
|
608
|
+
* iframe also suppresses Vitest 5's direct CSS transform.
|
|
590
609
|
*
|
|
591
610
|
* Hand the pane straight back with {@link releasePane}. A tester pinned at a viewport taller than
|
|
592
611
|
* the window puts its lower half beyond what a pointer can reach, so an ordinary press then fails
|
|
@@ -604,7 +623,8 @@ function measureContent() {
|
|
|
604
623
|
* the shot replaces the node and takes any attribute of ours with it.
|
|
605
624
|
*
|
|
606
625
|
* The wait is two frames rather than a delay: the first carries the resize into layout and the
|
|
607
|
-
* second is the paint a screenshot reads.
|
|
626
|
+
* second is the paint a screenshot reads. An already matching viewport needs no resize command;
|
|
627
|
+
* the staging rule, paint waits, and rendered-size check still run.
|
|
608
628
|
*
|
|
609
629
|
* The viewport the tester had before this staging is written onto that rule element as the
|
|
610
630
|
* {@link CAPTURE_PANE} value, in `<width>x<height>` form, and {@link releasePane} hands it back.
|
|
@@ -618,7 +638,7 @@ function measureContent() {
|
|
|
618
638
|
*/
|
|
619
639
|
async function stagePane(width, height) {
|
|
620
640
|
const viewport = `${String(window.innerWidth)}x${String(window.innerHeight)}`;
|
|
621
|
-
await page.viewport(width, height);
|
|
641
|
+
if (window.innerWidth !== width || window.innerHeight !== height) await page.viewport(width, height);
|
|
622
642
|
const frame = window.frameElement;
|
|
623
643
|
const pane = frame?.parentElement;
|
|
624
644
|
const owner = pane?.ownerDocument;
|
|
@@ -629,9 +649,9 @@ async function stagePane(width, height) {
|
|
|
629
649
|
rule.setAttribute(CAPTURE_PANE, viewport);
|
|
630
650
|
rule.textContent = [
|
|
631
651
|
`[${CAPTURE_PANE}],:has(>iframe[data-vitest])`,
|
|
632
|
-
"{--tester-transform:none !important;--tester-margin-left:0px !important}",
|
|
652
|
+
"{--tester-transform:none !important;--tester-margin-left:0px !important;transform:none !important}",
|
|
633
653
|
"iframe[data-vitest]",
|
|
634
|
-
"{position:fixed !important;left:0 !important;top:0 !important;right:auto !important;",
|
|
654
|
+
"{transform:none !important;position:fixed !important;left:0 !important;top:0 !important;right:auto !important;",
|
|
635
655
|
"bottom:auto !important;width:var(--viewport-width) !important;",
|
|
636
656
|
"height:var(--viewport-height) !important;z-index:2147483647 !important}"
|
|
637
657
|
].join("");
|
|
@@ -657,7 +677,9 @@ async function stagePane(width, height) {
|
|
|
657
677
|
* otherwise read the last capture's variant. The size comes off the {@link CAPTURE_PANE} value
|
|
658
678
|
* {@link stagePane} wrote onto the rule element, which is the reading taken before the first
|
|
659
679
|
* staging. Calling this on an unstaged pane finds no such value, so it changes nothing and resizes
|
|
660
|
-
* nothing.
|
|
680
|
+
* nothing. A staged pane sends its saved size even when the tester already holds it, because the
|
|
681
|
+
* runner refits its frame scale only on a viewport request; a release that skipped it would leave
|
|
682
|
+
* the next case shooting through the staged scale.
|
|
661
683
|
*
|
|
662
684
|
* That hand-back is what makes {@link stagePane} and this pair a capture's staging rather than a
|
|
663
685
|
* resize: the pair puts the tester back where it found it, so a suite that used it to reach a
|
|
@@ -851,12 +873,12 @@ async function stageMedia(options) {
|
|
|
851
873
|
async function waitForStability(description, read, options) {
|
|
852
874
|
const frames = options?.frames ?? 4;
|
|
853
875
|
if (!Number.isInteger(frames) || frames < 1) throw new Error("Stability frames must be a positive integer");
|
|
854
|
-
const
|
|
876
|
+
const samples = [read()];
|
|
855
877
|
await waitForCondition(description, async () => {
|
|
856
878
|
await waitForFrame();
|
|
857
|
-
|
|
858
|
-
const tail =
|
|
859
|
-
return tail.length > frames && tail.every((
|
|
879
|
+
samples.push(read());
|
|
880
|
+
const tail = samples.slice(-(frames + 1));
|
|
881
|
+
return tail.length > frames && tail.every((sample) => sample === tail[0]);
|
|
860
882
|
}, options);
|
|
861
883
|
}
|
|
862
884
|
/**
|
|
@@ -895,33 +917,33 @@ async function releaseMedia() {
|
|
|
895
917
|
];
|
|
896
918
|
const staged = document.documentElement.getAttribute(MEDIA_STAGE);
|
|
897
919
|
if (staged !== null) {
|
|
898
|
-
const
|
|
920
|
+
const matches = staged.split("").map((value) => value === "1");
|
|
899
921
|
if (staged.length === 5) queries.push("(pointer: coarse)");
|
|
900
922
|
await sendProtocol("Emulation.setEmulatedMedia", {
|
|
901
|
-
media:
|
|
923
|
+
media: matches[0] ? "print" : "screen",
|
|
902
924
|
features: [
|
|
903
925
|
{
|
|
904
926
|
name: "prefers-reduced-motion",
|
|
905
|
-
value:
|
|
927
|
+
value: matches[1] ? "reduce" : "no-preference"
|
|
906
928
|
},
|
|
907
929
|
{
|
|
908
930
|
name: "prefers-color-scheme",
|
|
909
|
-
value:
|
|
931
|
+
value: matches[2] ? "dark" : "light"
|
|
910
932
|
},
|
|
911
933
|
{
|
|
912
934
|
name: "forced-colors",
|
|
913
|
-
value:
|
|
935
|
+
value: matches[3] ? "active" : "none"
|
|
914
936
|
}
|
|
915
937
|
]
|
|
916
938
|
});
|
|
917
939
|
if (staged.length === 5) await sendProtocol("Emulation.setTouchEmulationEnabled", {
|
|
918
|
-
enabled:
|
|
940
|
+
enabled: matches[4],
|
|
919
941
|
maxTouchPoints: 1
|
|
920
942
|
});
|
|
921
943
|
try {
|
|
922
944
|
await Promise.all(queries.map((query, index) => waitForCondition(query, async () => {
|
|
923
945
|
await waitForFrame();
|
|
924
|
-
return matchMedia(query).matches ===
|
|
946
|
+
return matchMedia(query).matches === matches[index];
|
|
925
947
|
})));
|
|
926
948
|
} catch (cause) {
|
|
927
949
|
throw new Error("Media emulation did not clear from the tester", { cause });
|
|
@@ -945,14 +967,17 @@ async function releaseMedia() {
|
|
|
945
967
|
* @param options - The path to write, the viewport to shoot at, and the element to shoot.
|
|
946
968
|
* @returns The absolute path of the written frame, after it has been read back and matched.
|
|
947
969
|
* @throws Thrown when the pane cannot be staged, when the document's height or an element frame's
|
|
948
|
-
* element height never settles under {@link
|
|
970
|
+
* element height never settles under {@link CAPTURE_STAGE_LIMIT} restagings, when the provider wrote
|
|
949
971
|
* the frame somewhere else, and when the bytes on disk are not the ones this shot produced.
|
|
950
972
|
*
|
|
951
973
|
* @remarks
|
|
952
974
|
* The path a screenshot call returns is the path it meant to write, so it is not evidence a file
|
|
953
|
-
* exists. The
|
|
954
|
-
*
|
|
955
|
-
*
|
|
975
|
+
* exists. The {@link verifyFrame} helper compares the file with the shot itself. When the page
|
|
976
|
+
* registered a `readCapture` command, {@link readCaptureReader} returns it and the comparison uses
|
|
977
|
+
* SHA-256 digests computed in Node for the file and in the browser for the returned bytes. Otherwise
|
|
978
|
+
* the runner's built-in `readFile` command supplies the base64 comparison. A command failure
|
|
979
|
+
* propagates without falling back. The provider resolves `options.path`
|
|
980
|
+
* against the calling test file and returns an absolute
|
|
956
981
|
* path, so the two are compared by the segments that survive resolving `.` and `..` lexically — the
|
|
957
982
|
* refusal is what a provider resolving that path against a different base would trip.
|
|
958
983
|
*
|
|
@@ -962,6 +987,8 @@ async function releaseMedia() {
|
|
|
962
987
|
* than the document — a frame that reads as the surface down to the fold and as bare canvas after
|
|
963
988
|
* it. The document is therefore laid out at the declared viewport first and, where it is taller
|
|
964
989
|
* than that, the pane is staged again at the height the document needs, for the shot alone.
|
|
990
|
+
* Where the tester already has the declared viewport, the reading precedes the initial staging,
|
|
991
|
+
* so fixed content stages at its final height directly. Every staged height is still read again.
|
|
965
992
|
*
|
|
966
993
|
* That height is {@link measureContent}, never less than `options.height`, because the declared
|
|
967
994
|
* viewport is the smallest frame a variant asks for. The reading is the content's own edge rather
|
|
@@ -984,7 +1011,7 @@ async function releaseMedia() {
|
|
|
984
1011
|
*
|
|
985
1012
|
* The re-reading stops when the pane and the edge agree, which is the pane the shot is taken at. A
|
|
986
1013
|
* rule that adds height with every pane never reaches that point, so the re-reading is bounded by
|
|
987
|
-
* {@link
|
|
1014
|
+
* {@link CAPTURE_STAGE_LIMIT} and the shot is refused with
|
|
988
1015
|
* `Capture frame at <path> never settled after <n> restagings: <h> over a <h> pane` rather than
|
|
989
1016
|
* written at a height that is already wrong.
|
|
990
1017
|
*
|
|
@@ -1037,12 +1064,13 @@ async function captureFrame(options) {
|
|
|
1037
1064
|
left: window.scrollX,
|
|
1038
1065
|
top: window.scrollY
|
|
1039
1066
|
};
|
|
1067
|
+
const prepared = window.innerWidth === options.width && window.innerHeight === options.height;
|
|
1040
1068
|
try {
|
|
1041
|
-
await stagePane(options.width, options.height);
|
|
1069
|
+
if (!prepared) await stagePane(options.width, options.height);
|
|
1042
1070
|
let pane = options.height;
|
|
1043
1071
|
let covered;
|
|
1044
1072
|
let growth = 0;
|
|
1045
|
-
for (let
|
|
1073
|
+
for (let stage = 0;; stage += 1) {
|
|
1046
1074
|
let height = element?.getBoundingClientRect().height;
|
|
1047
1075
|
if (element !== void 0 && height !== void 0 && height > options.height) {
|
|
1048
1076
|
element.scrollIntoView({
|
|
@@ -1100,11 +1128,17 @@ async function captureFrame(options) {
|
|
|
1100
1128
|
}
|
|
1101
1129
|
}
|
|
1102
1130
|
}
|
|
1103
|
-
const
|
|
1104
|
-
if (covered !== void 0) growth = Math.max(0,
|
|
1105
|
-
covered =
|
|
1106
|
-
if (pane === covered)
|
|
1107
|
-
|
|
1131
|
+
const extent = Math.max(height === void 0 ? measureContent() : Math.ceil(height), options.height);
|
|
1132
|
+
if (covered !== void 0) growth = Math.max(0, extent - covered);
|
|
1133
|
+
covered = extent;
|
|
1134
|
+
if (pane === covered) {
|
|
1135
|
+
if (prepared && stage === 0) {
|
|
1136
|
+
await stagePane(options.width, pane);
|
|
1137
|
+
continue;
|
|
1138
|
+
}
|
|
1139
|
+
break;
|
|
1140
|
+
}
|
|
1141
|
+
if (stage === 4) throw new Error(`Capture frame at ${options.path} never settled after ${String(4)} restagings: ${String(covered)} over a ${String(pane)} pane`);
|
|
1108
1142
|
pane = covered + growth;
|
|
1109
1143
|
await stagePane(options.width, pane);
|
|
1110
1144
|
}
|
|
@@ -1147,14 +1181,7 @@ async function captureFrame(options) {
|
|
|
1147
1181
|
else if (offset && style !== null) frame.setAttribute("style", style);
|
|
1148
1182
|
}
|
|
1149
1183
|
}
|
|
1150
|
-
|
|
1151
|
-
for (const segment of options.path.replaceAll("\\", "/").split("/")) {
|
|
1152
|
-
if (segment === "" || segment === ".") continue;
|
|
1153
|
-
if (segment === "..") segments.pop();
|
|
1154
|
-
else segments.push(segment);
|
|
1155
|
-
}
|
|
1156
|
-
if (!shot.path.replaceAll("\\", "/").endsWith(segments.join("/"))) throw new Error(`Capture frame was written to ${shot.path} where ${options.path} was asked for`);
|
|
1157
|
-
if (await commands.readFile(shot.path, "base64") !== shot.base64) throw new Error(`Capture frame at ${options.path} is not the one this run shot`);
|
|
1184
|
+
await verifyFrame(shot, options.path, readCaptureReader());
|
|
1158
1185
|
return shot.path;
|
|
1159
1186
|
} finally {
|
|
1160
1187
|
try {
|
|
@@ -1169,6 +1196,49 @@ async function captureFrame(options) {
|
|
|
1169
1196
|
}
|
|
1170
1197
|
}
|
|
1171
1198
|
/**
|
|
1199
|
+
* Reads the optional disk-digest command the tester page registered.
|
|
1200
|
+
*
|
|
1201
|
+
* @returns The registered `readCapture` command, or undefined where none is registered.
|
|
1202
|
+
*
|
|
1203
|
+
* @remarks Vitest publishes only registered commands, so an unregistered `readCapture` reads as
|
|
1204
|
+
* undefined and a capture falls back to the base64 read-back. Outside a Vitest browser page, where
|
|
1205
|
+
* `commands` is no object, the command reads as undefined too, so importing this module never
|
|
1206
|
+
* throws there.
|
|
1207
|
+
* @example
|
|
1208
|
+
* ```ts
|
|
1209
|
+
* await verifyFrame(shot, '../../tmp/frame.png', readCaptureReader())
|
|
1210
|
+
* ```
|
|
1211
|
+
*/
|
|
1212
|
+
function readCaptureReader() {
|
|
1213
|
+
if (typeof commands !== "object" || commands === null) return void 0;
|
|
1214
|
+
return readProperty(commands, "readCapture");
|
|
1215
|
+
}
|
|
1216
|
+
/**
|
|
1217
|
+
* Verifies a screenshot's destination and compares its returned bytes with the written file.
|
|
1218
|
+
*
|
|
1219
|
+
* @param shot - The provider's absolute path and base64 screenshot bytes.
|
|
1220
|
+
* @param path - The requested screenshot path, relative to the test file.
|
|
1221
|
+
* @param reader - The optional Node disk-digest command; omission uses Vitest's base64 read-back.
|
|
1222
|
+
* @throws Thrown when the destination differs, the bytes differ, or either reading fails.
|
|
1223
|
+
* @remarks Digest reads compare SHA-256 of the decoded shot with SHA-256 of the disk bytes.
|
|
1224
|
+
* Command failures propagate unchanged; they never select the base64 fallback.
|
|
1225
|
+
* @example
|
|
1226
|
+
* ```ts
|
|
1227
|
+
* await verifyFrame(shot, '../../tmp/frame.png', readCaptureReader())
|
|
1228
|
+
* ```
|
|
1229
|
+
*/
|
|
1230
|
+
async function verifyFrame(shot, path, reader) {
|
|
1231
|
+
const segments = [];
|
|
1232
|
+
for (const segment of path.replaceAll("\\", "/").split("/")) {
|
|
1233
|
+
if (segment === "" || segment === ".") continue;
|
|
1234
|
+
if (segment === "..") segments.pop();
|
|
1235
|
+
else segments.push(segment);
|
|
1236
|
+
}
|
|
1237
|
+
if (!shot.path.replaceAll("\\", "/").endsWith(segments.join("/"))) throw new Error(`Capture frame was written to ${shot.path} where ${path} was asked for`);
|
|
1238
|
+
const expected = reader === void 0 ? shot.base64 : [...new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(atob(shot.base64), (character) => character.charCodeAt(0))))].map((byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
1239
|
+
if ((reader === void 0 ? await commands.readFile(shot.path, "base64") : await reader(shot.path)) !== expected) throw new Error(`Capture frame at ${path} is not the one this run shot`);
|
|
1240
|
+
}
|
|
1241
|
+
/**
|
|
1172
1242
|
* Decodes a base64 PNG and paints it, unscaled, onto a fresh offscreen 2D canvas.
|
|
1173
1243
|
*
|
|
1174
1244
|
* @param encoded - The image's bytes as base64 text, without a data-URL prefix.
|
|
@@ -1223,7 +1293,7 @@ async function paintImage(encoded) {
|
|
|
1223
1293
|
*
|
|
1224
1294
|
* @example
|
|
1225
1295
|
* ```ts
|
|
1226
|
-
* const
|
|
1296
|
+
* const result = await readFrame(written)
|
|
1227
1297
|
* ```
|
|
1228
1298
|
*/
|
|
1229
1299
|
async function readFrame(path) {
|
|
@@ -1796,7 +1866,7 @@ function resolveFileInput(name) {
|
|
|
1796
1866
|
* ```
|
|
1797
1867
|
*/
|
|
1798
1868
|
async function chooseAccessible(name, files, options) {
|
|
1799
|
-
if (options?.keyboard) await driveTraversal(() => resolveFileInput(name), name);
|
|
1869
|
+
if (options?.keyboard) await driveTraversal(() => resolveFileInput(name), name, (focused) => focused instanceof HTMLInputElement && focused.type === "file");
|
|
1800
1870
|
const target = resolveFileInput(name);
|
|
1801
1871
|
const command = readProperty(commands, "chooseFiles");
|
|
1802
1872
|
if (typeof command !== "function") throw new Error("Register the chooseFiles browser command before choosing files");
|
|
@@ -2079,7 +2149,7 @@ async function releasePointer() {
|
|
|
2079
2149
|
* Each frame on the way up adds its border and its padding, which is where its content starts,
|
|
2080
2150
|
* scales the point by the ratio of its painted width to its layout width, and adds its own position,
|
|
2081
2151
|
* so a tester iframe the runner scales or offsets is accounted for, and so is an iframe the page
|
|
2082
|
-
* itself nests, bordered, padded, or neither. The reading is of the layout
|
|
2152
|
+
* itself nests, bordered, padded, or neither. The reading is of the layout at the call: a box that moves
|
|
2083
2153
|
* afterwards moves the point it names. An element in a document no frame holds reads its own client
|
|
2084
2154
|
* point. A disconnected element has no layout, and its window still names the tester frame, so it is
|
|
2085
2155
|
* refused rather than read as that frame's corner.
|
|
@@ -2286,7 +2356,10 @@ async function pressKeys(keys) {
|
|
|
2286
2356
|
* @throws When one complete traversal cannot reach the target.
|
|
2287
2357
|
*
|
|
2288
2358
|
* @remarks
|
|
2289
|
-
* The loop is {@link driveTraversal} over {@link resolveRendered}
|
|
2359
|
+
* The loop is {@link driveTraversal} over {@link resolveRendered}, with a conservative name check
|
|
2360
|
+
* before each arrival resolution. Consecutive landings inside a
|
|
2361
|
+
* native segmented input continue through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings.
|
|
2362
|
+
* A longer run or any other revisit ends the traversal.
|
|
2290
2363
|
*
|
|
2291
2364
|
* @example
|
|
2292
2365
|
* ```ts
|
|
@@ -2308,7 +2381,8 @@ async function traverseAccessible(name) {
|
|
|
2308
2381
|
*
|
|
2309
2382
|
* @remarks
|
|
2310
2383
|
* The resolution is {@link resolveAccessibleWithin} and the loop is {@link driveTraversal}, so a
|
|
2311
|
-
* twin of the same name earlier in the tab order is passed over rather than reached.
|
|
2384
|
+
* twin of the same name earlier in the tab order is passed over rather than reached. Candidates
|
|
2385
|
+
* retain the resolver's loose name match and must belong to a freshly resolved named region.
|
|
2312
2386
|
*
|
|
2313
2387
|
* @example
|
|
2314
2388
|
* ```ts
|
|
@@ -2316,7 +2390,10 @@ async function traverseAccessible(name) {
|
|
|
2316
2390
|
* ```
|
|
2317
2391
|
*/
|
|
2318
2392
|
async function traverseAccessibleWithin(region, role, name) {
|
|
2319
|
-
return driveTraversal(() => resolveAccessibleWithin(region, role, name), name)
|
|
2393
|
+
return driveTraversal(() => resolveAccessibleWithin(region, role, name), name, (focused) => matchesTraversalName(focused, name, false) && page.getByRole("region", {
|
|
2394
|
+
name: region,
|
|
2395
|
+
exact: true
|
|
2396
|
+
}).elements().some((container) => containsNode(container, focused)));
|
|
2320
2397
|
}
|
|
2321
2398
|
/**
|
|
2322
2399
|
* Reads the HTML element that holds focus, following it into open shadow roots and same-origin
|
|
@@ -2424,7 +2501,9 @@ function containsNode(root, node) {
|
|
|
2424
2501
|
* through the provider, reads the landing with {@link readActiveElement}, and leaves every decision
|
|
2425
2502
|
* to the caller: what counts as an end, a revisit, or a stop is the consumer's, because the two
|
|
2426
2503
|
* consumers disagree. The press is the next one only after the consumer asks for the next landing, so
|
|
2427
|
-
* a consumer that stops reading stops pressing.
|
|
2504
|
+
* a consumer that stops reading stops pressing. A native segmented input can yield the same element
|
|
2505
|
+
* for successive segment landings. This generator preserves each landing; its consumers count that
|
|
2506
|
+
* control once while continuing through its segments, and end a run beyond {@link FOCUS_SEGMENT_LIMIT}.
|
|
2428
2507
|
*
|
|
2429
2508
|
* @example
|
|
2430
2509
|
* ```ts
|
|
@@ -2440,42 +2519,104 @@ async function* stepFocus(limit) {
|
|
|
2440
2519
|
}
|
|
2441
2520
|
}
|
|
2442
2521
|
/**
|
|
2522
|
+
* Determines whether a native input exposes separately editable segments under one focused element.
|
|
2523
|
+
*
|
|
2524
|
+
* @param element - The element whose native input type is read in its own document's realm.
|
|
2525
|
+
* @returns True if the element is an input with a type in {@link SEGMENTED_INPUT_TYPES}, checked
|
|
2526
|
+
* against its own document's `HTMLInputElement`; false otherwise, including a document with no window.
|
|
2527
|
+
*
|
|
2528
|
+
* @example
|
|
2529
|
+
* ```ts
|
|
2530
|
+
* supportsSegmentedFocus(document.createElement('button')) // false
|
|
2531
|
+
* ```
|
|
2532
|
+
*/
|
|
2533
|
+
function supportsSegmentedFocus(element) {
|
|
2534
|
+
const realm = element.ownerDocument.defaultView;
|
|
2535
|
+
return realm !== null && element instanceof realm.HTMLInputElement && SEGMENTED_INPUT_TYPES.includes(element.type);
|
|
2536
|
+
}
|
|
2537
|
+
/**
|
|
2538
|
+
* Checks whether a landing can carry a requested accessible name without resolving the document.
|
|
2539
|
+
*
|
|
2540
|
+
* @param element - The element focus landed on.
|
|
2541
|
+
* @param name - The name the resolver matches.
|
|
2542
|
+
* @param exact - If `true`, compares exact names; if `false`, compares case-insensitive substrings.
|
|
2543
|
+
* Default: `true`.
|
|
2544
|
+
* @returns True if the name matches or its computation requires the resolver; false otherwise.
|
|
2545
|
+
*
|
|
2546
|
+
* @remarks
|
|
2547
|
+
* This is a conservative candidate check, not an accessible-name implementation. It compares a
|
|
2548
|
+
* nonempty `aria-label` without `aria-labelledby`, or the text of a plain native button or link.
|
|
2549
|
+
* Referenced labels, associated labels, descendants, shadow content, owned content, explicit roles,
|
|
2550
|
+
* generated content, and other naming rules fall through to the resolver. Empty requested names
|
|
2551
|
+
* also fall through because a role can prohibit naming. Whitespace, zero-width spaces, and soft
|
|
2552
|
+
* hyphens are normalized as in the provider's role query. Never use this check to accept a target.
|
|
2553
|
+
*
|
|
2554
|
+
* @example
|
|
2555
|
+
* ```ts
|
|
2556
|
+
* matchesTraversalName(document.createElement('input'), 'Attachments') // true
|
|
2557
|
+
* ```
|
|
2558
|
+
*/
|
|
2559
|
+
function matchesTraversalName(element, name, exact = true) {
|
|
2560
|
+
const wanted = name.replaceAll(/[\u200b\u00ad]/g, "").trim().replaceAll(/\s+/g, " ");
|
|
2561
|
+
if (wanted.length === 0 || element.hasAttribute("aria-labelledby")) return true;
|
|
2562
|
+
const label = element.getAttribute("aria-label") ?? "";
|
|
2563
|
+
const realm = element.ownerDocument.defaultView;
|
|
2564
|
+
if (label.trim().length === 0) {
|
|
2565
|
+
if (realm === null || !(element instanceof realm.HTMLButtonElement || element instanceof realm.HTMLAnchorElement) || element.hasAttribute("role") || element.hasAttribute("aria-owns") || element.childElementCount > 0 || element.shadowRoot !== null || element instanceof realm.HTMLButtonElement && (element.labels?.length ?? 0) > 0 || element instanceof realm.HTMLAnchorElement && !element.hasAttribute("href")) return true;
|
|
2566
|
+
if (![realm.getComputedStyle(element, "::before"), realm.getComputedStyle(element, "::after")].every((style) => style.content === "none" || style.content === "normal")) return true;
|
|
2567
|
+
if ((element.textContent ?? "").trim().length === 0) return true;
|
|
2568
|
+
}
|
|
2569
|
+
const actual = (label.trim().length > 0 ? label : element.textContent ?? "").replaceAll(/[\u200b\u00ad]/g, "").trim().replaceAll(/\s+/g, " ");
|
|
2570
|
+
return exact ? actual === wanted : actual.toUpperCase().includes(wanted.toUpperCase());
|
|
2571
|
+
}
|
|
2572
|
+
/**
|
|
2443
2573
|
* Reaches the control a resolver returns, only through natural forward Tab traversal from the
|
|
2444
2574
|
* current focus.
|
|
2445
2575
|
*
|
|
2446
|
-
* @param resolve - The resolver
|
|
2447
|
-
*
|
|
2576
|
+
* @param resolve - The resolver called before traversal and at candidate arrivals, without retaining
|
|
2577
|
+
* its result between steps.
|
|
2448
2578
|
* @param name - The target's name, as the refusal voices it.
|
|
2579
|
+
* @param candidate - The landing check; it must admit every element the resolver could return.
|
|
2580
|
+
* Default: the conservative exact-name check from {@link matchesTraversalName}. Supply a check
|
|
2581
|
+
* matching the resolver's semantics when it uses a label, region, or loose name.
|
|
2449
2582
|
* @returns The target after the browser moves focus to it.
|
|
2450
2583
|
* @throws When the resolver refuses, or one complete traversal cannot reach the target.
|
|
2451
2584
|
*
|
|
2452
2585
|
* @remarks
|
|
2453
2586
|
* This is the one loop every traversal verb shares, over {@link stepFocus}. A step counts only when
|
|
2454
|
-
* focus lands on an element
|
|
2455
|
-
*
|
|
2587
|
+
* focus lands on an element. Consecutive landings on the same native segmented input continue
|
|
2588
|
+
* through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings and count that control once.
|
|
2589
|
+
* A longer run or any other revisit ends the traversal. Any different landing starts a separate run.
|
|
2590
|
+
* The press cap is {@link FOCUS_SEGMENT_LIMIT} times the {@link FOCUSABLE_SELECTOR} candidate count
|
|
2591
|
+
* plus ten, so a page of segmented inputs has a budget for their segments and picker indicators.
|
|
2456
2592
|
*
|
|
2457
2593
|
* @example
|
|
2458
2594
|
* ```ts
|
|
2459
2595
|
* await driveTraversal(() => resolveRendered('Evaluate'), 'Evaluate')
|
|
2460
2596
|
* ```
|
|
2461
2597
|
*/
|
|
2462
|
-
async function driveTraversal(resolve, name) {
|
|
2598
|
+
async function driveTraversal(resolve, name, candidate) {
|
|
2463
2599
|
resolve();
|
|
2464
|
-
const cap = document.querySelectorAll(FOCUSABLE_SELECTOR).length *
|
|
2600
|
+
const cap = document.querySelectorAll(FOCUSABLE_SELECTOR).length * 10 + 10;
|
|
2465
2601
|
const visited = /* @__PURE__ */ new Set();
|
|
2466
|
-
const
|
|
2602
|
+
const stops = [];
|
|
2467
2603
|
for await (const focused of stepFocus(cap)) {
|
|
2604
|
+
const previous = stops.at(-1);
|
|
2605
|
+
stops.push(focused);
|
|
2468
2606
|
if (focused === void 0) continue;
|
|
2469
2607
|
try {
|
|
2470
|
-
|
|
2471
|
-
|
|
2608
|
+
if (candidate === void 0 ? matchesTraversalName(focused, name) : candidate(focused)) {
|
|
2609
|
+
const current = resolve();
|
|
2610
|
+
if (focused === current) return current;
|
|
2611
|
+
}
|
|
2472
2612
|
} catch {
|
|
2473
2613
|
continue;
|
|
2474
2614
|
}
|
|
2615
|
+
if (focused === previous && supportsSegmentedFocus(focused) && stops.length - stops.findLastIndex((entry) => entry !== focused) - 1 <= 10) continue;
|
|
2475
2616
|
if (visited.has(focused)) break;
|
|
2476
2617
|
visited.add(focused);
|
|
2477
|
-
trail.push(`${focused.tagName}:${focused.innerText.slice(0, 20)}`);
|
|
2478
2618
|
}
|
|
2619
|
+
const trail = [...new Set(stops)].filter((focused) => focused !== void 0).filter((focused) => visited.has(focused)).map((focused) => `${focused.tagName}:${focused.innerText.slice(0, 20)}`);
|
|
2479
2620
|
throw new Error(`Interactive target "${name}" is not reachable through forward Tab traversal: ${trail.join(" > ")}`);
|
|
2480
2621
|
}
|
|
2481
2622
|
/**
|
|
@@ -2484,8 +2625,8 @@ async function driveTraversal(resolve, name) {
|
|
|
2484
2625
|
*
|
|
2485
2626
|
* @param stop - Accepts the destination. Omit it to census the remaining document.
|
|
2486
2627
|
* @returns Every element focus reached, in order and each once, the accepted stop last.
|
|
2487
|
-
* @throws Thrown when the walk
|
|
2488
|
-
*
|
|
2628
|
+
* @throws Thrown when the walk exceeds its press cap, a key press rejects, or focus lands in a
|
|
2629
|
+
* frame from another origin.
|
|
2489
2630
|
*
|
|
2490
2631
|
* @remarks
|
|
2491
2632
|
* The walk records the focused element and then presses Tab through {@link stepFocus}, so it reaches
|
|
@@ -2494,8 +2635,14 @@ async function driveTraversal(resolve, name) {
|
|
|
2494
2635
|
* innermost focused element {@link readActiveElement} reads, so a control inside an open shadow root
|
|
2495
2636
|
* or a same-origin frame is a stop of its own, and its host or frame element is not. The walk ends
|
|
2496
2637
|
* with an empty list when only the body holds focus, and where focus revisits a stop or returns to
|
|
2497
|
-
* the body.
|
|
2498
|
-
*
|
|
2638
|
+
* the body. Consecutive landings on the same native segmented input continue through its segments
|
|
2639
|
+
* up to {@link FOCUS_SEGMENT_LIMIT} landings, including the initial focused element, and count that
|
|
2640
|
+
* control once. A longer run or any other revisit, including a repeated button in a focus trap,
|
|
2641
|
+
* ends the walk. Any different landing starts a separate run.
|
|
2642
|
+
* The press cap is {@link FOCUS_SEGMENT_LIMIT} times {@link countElements}, including
|
|
2643
|
+
* open shadow roots and same-origin frames. It applies no rule about which stop counts: the
|
|
2644
|
+
* predicate sees each one and decides, so a consumer that refuses a hidden stop throws from its own
|
|
2645
|
+
* predicate.
|
|
2499
2646
|
*
|
|
2500
2647
|
* A closed shadow root cannot be entered, so its host stands for everything inside it, and a frame
|
|
2501
2648
|
* from another origin is refused because its controls cannot be named.
|
|
@@ -2509,9 +2656,14 @@ async function walkFocus(stop) {
|
|
|
2509
2656
|
const first = readActiveElement();
|
|
2510
2657
|
if (first === void 0) return [];
|
|
2511
2658
|
const reached = [first];
|
|
2659
|
+
const stops = [first];
|
|
2512
2660
|
if (stop?.(first) === true) return reached;
|
|
2513
|
-
for await (const focused of stepFocus(countElements())) {
|
|
2514
|
-
if (focused === void 0
|
|
2661
|
+
for await (const focused of stepFocus(countElements() * 10)) {
|
|
2662
|
+
if (focused === void 0) return reached;
|
|
2663
|
+
const previous = stops.at(-1);
|
|
2664
|
+
stops.push(focused);
|
|
2665
|
+
if (focused === previous && supportsSegmentedFocus(focused) && stops.length - stops.findLastIndex((entry) => entry !== focused) - 1 <= 10) continue;
|
|
2666
|
+
if (reached.includes(focused)) return reached;
|
|
2515
2667
|
reached.push(focused);
|
|
2516
2668
|
if (stop?.(focused) === true) return reached;
|
|
2517
2669
|
}
|
|
@@ -2533,7 +2685,9 @@ async function walkFocus(stop) {
|
|
|
2533
2685
|
* {@link containsNode}, so a control inside an open shadow root or a same-origin frame that `root`
|
|
2534
2686
|
* holds is in the region, and `start` may sit inside one. A `start` that sits outside the region,
|
|
2535
2687
|
* as the control immediately before it, is the walk's origin and never its end, so the first Tab into the
|
|
2536
|
-
* region reaches its first stop.
|
|
2688
|
+
* region reaches its first stop. A native segmented input contributes one stop while consecutive
|
|
2689
|
+
* landings pass through its segments up to {@link FOCUS_SEGMENT_LIMIT} landings. A longer run or
|
|
2690
|
+
* any other revisit ends the walk.
|
|
2537
2691
|
*
|
|
2538
2692
|
* @example
|
|
2539
2693
|
* ```ts
|
|
@@ -2703,7 +2857,7 @@ function readText(element) {
|
|
|
2703
2857
|
* A declared `role` wins outright, and its first token is the answer when several are listed.
|
|
2704
2858
|
* Otherwise the element's own anatomy decides: an anchor is a link only while it holds an `href`,
|
|
2705
2859
|
* an `input` takes the role {@link FIELD_ROLES} gives its type, a `select` is a combobox until it
|
|
2706
|
-
* offers several rows at once, a `section` is a region only
|
|
2860
|
+
* offers several rows at once, a `section` is a region only after something names it, and a `th`
|
|
2707
2861
|
* heads whichever axis its `scope` names. Every other tag answers from {@link IMPLICIT_ROLES},
|
|
2708
2862
|
* whose membership is the contract for what this can answer at all.
|
|
2709
2863
|
*
|
|
@@ -2913,11 +3067,11 @@ async function waitForState(first, second, third, fourth) {
|
|
|
2913
3067
|
const absent = options?.absent ?? false;
|
|
2914
3068
|
const description = `"${name}" to ${absent ? "stop announcing" : "announce"} "${state}"`;
|
|
2915
3069
|
let observed = [];
|
|
2916
|
-
let
|
|
3070
|
+
let count = 0;
|
|
2917
3071
|
let refused;
|
|
2918
3072
|
try {
|
|
2919
3073
|
await waitForCondition(description, () => {
|
|
2920
|
-
|
|
3074
|
+
count += 1;
|
|
2921
3075
|
try {
|
|
2922
3076
|
observed = readStates(role === void 0 ? resolveRendered(name) : resolveRendered(role, name));
|
|
2923
3077
|
} catch (thrown) {
|
|
@@ -2929,7 +3083,7 @@ async function waitForState(first, second, third, fourth) {
|
|
|
2929
3083
|
} catch (cause) {
|
|
2930
3084
|
if (refused !== void 0 && cause === refused.thrown) throw cause;
|
|
2931
3085
|
if (cause === options?.signal?.reason) throw cause;
|
|
2932
|
-
if (
|
|
3086
|
+
if (count === 0) throw cause;
|
|
2933
3087
|
if (!isError(cause)) throw cause;
|
|
2934
3088
|
throw new Error(`${cause.message} (last states: ${JSON.stringify(observed)})`, { cause });
|
|
2935
3089
|
}
|
|
@@ -2940,7 +3094,7 @@ async function waitForState(first, second, third, fourth) {
|
|
|
2940
3094
|
*
|
|
2941
3095
|
* @param element - The element whose own animations and descendants' animations to wait on.
|
|
2942
3096
|
* @param options - The time bounds and the abort signal.
|
|
2943
|
-
* @returns A promise resolving
|
|
3097
|
+
* @returns A promise resolving after every finite animation has stopped running.
|
|
2944
3098
|
* @throws An `Error` when the element is not in a document, when a bound is invalid, or when an
|
|
2945
3099
|
* animation is still running at the budget; or the abort reason.
|
|
2946
3100
|
*
|
|
@@ -3053,7 +3207,7 @@ function readAnimations(element) {
|
|
|
3053
3207
|
* A pointer left over a control paints that control's hover, and a transition still running paints
|
|
3054
3208
|
* a fill between two states, so neither is a state the interface rests in. An endless animation, a
|
|
3055
3209
|
* spinner or a placeholder shimmer, stands at a different phase in every frame unless it is held at
|
|
3056
|
-
* the same one, so each is paused at its first frame. Call the resume
|
|
3210
|
+
* the same one, so each is paused at its first frame. Call the resume after the frame is shot; a
|
|
3057
3211
|
* capture that throws still owes it, so call it from a `finally` block.
|
|
3058
3212
|
*
|
|
3059
3213
|
* The subject is the whole document, its root element included. The pointer parks through
|
|
@@ -4183,7 +4337,7 @@ function parseColor(value) {
|
|
|
4183
4337
|
* property is named by letters, digits, `_`, and `-` after its `--`. A name the scope leaves
|
|
4184
4338
|
* undeclared is not carried, so its `var()` fallback still applies.
|
|
4185
4339
|
*
|
|
4186
|
-
* The scope element is never written. The probe is
|
|
4340
|
+
* The scope element is never written. The probe is freshly created, so it has no earlier style to start a
|
|
4187
4341
|
* transition from, and a transition running on the scope keeps running: `currentColor` reads the
|
|
4188
4342
|
* color the scope shows at that moment, and the scope's geometry and scroll position stay as they
|
|
4189
4343
|
* were. No attribute, style, or child of the scope changes, so a `MutationObserver` on it records
|
|
@@ -4519,7 +4673,7 @@ function readContrast(element, floor) {
|
|
|
4519
4673
|
* @remarks
|
|
4520
4674
|
* This reads and never acts. Focus arrives through the published verbs — `traverseAccessible`,
|
|
4521
4675
|
* `userEvent.keyboard` from `vitest/browser`, a real click — and this measures what the browser
|
|
4522
|
-
* painted
|
|
4676
|
+
* painted after it landed. A control that is not matching `:focus-visible` when the call is made
|
|
4523
4677
|
* reports nothing, because no measurement taken then would be about focus.
|
|
4524
4678
|
*
|
|
4525
4679
|
* Some controls are two elements: one that takes the focus and one a reader can see. A hidden radio
|
|
@@ -5066,6 +5220,6 @@ function buildCensus() {
|
|
|
5066
5220
|
});
|
|
5067
5221
|
}
|
|
5068
5222
|
//#endregion
|
|
5069
|
-
export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE,
|
|
5223
|
+
export { ACCESSIBLE_ROLES, CANVAS_COLOR, CAPTURE_PANE, CAPTURE_STAGE_LIMIT, CONTENT_ROLES, FIELD_ROLES, FOCUSABLE_SELECTOR, FOCUS_SEGMENT_LIMIT, HEADER_ROLES, IMPLICIT_ROLES, MEDIA_STAGE, POINTER_HOLD, SEGMENTED_INPUT_TYPES, adoptSheet, blendColor, build, buildCensus, buildContrast, buildDenial, buildEscapes, captureFrame, chooseAccessible, clearStorage, clickAccessible, clickAccessibleWithin, clickDisclosure, clipsOverflow, collectClippingAncestors, collectScrollRegions, collectTabStops, commitInput, computeNamePattern, computeOffset, containsNode, convertA98RGB, convertDisplayP3, convertLab, convertLinearSRGB, convertOKLab, convertProPhotoRGB, convertRec2020, convertSRGB, convertXYZD50, convertXYZD65, countElements, createChannel, createDragEvent, createHarness, createJournal, createKeyboardEvent, createPointerEvent, createPortfolio, createStorage, describeFocus, describeScrollRegions, describeTree, driveHold, driveTraversal, expandCaptures, extractOrphans, extractStyles, fillAccessible, findKeyframes, findRule, holdAccessible, holdAccessibleWithin, hoverAccessible, isOutsideViewport, isReachable, isRendered, matchesColor, matchesTraversalName, measureContent, measureContrast, measureLuminance, mount, paintImage, parkPointer, parseCSSColor, parseColor, pressKeys, readAccessibilityNode, readActiveElement, readAnimations, readBackdrop, readCaptureReader, readCascade, readCensus, readClasses, readClipEdge, readClipMargin, readClippedBlock, readColorContrast, readContrast, readFocus, readFrame, readHit, readLayerNames, readLayers, readName, readPage, readPerception, readPixels, readProtocolNode, readProtocolPoint, readRefusal, readRing, readRole, readRootToken, readRows, readRules, readShotPixel, readStates, readStyle, readText, readToken, readValue, releaseMedia, releasePane, releasePointer, releaseTouch, removeDatabase, render, resolveAccessible, resolveAccessibleWithin, resolveFileInput, resolveRendered, sendFileDrag, sendProtocol, sendTouch, settleCapture, stageMedia, stagePane, stepFocus, supportsSegmentedFocus, tapTouch, traverseAccessible, traverseAccessibleWithin, typeAccessible, typeInput, verifyFrame, waitForAnimations, waitForFrame, waitForStability, waitForState, walkFocus };
|
|
5070
5224
|
|
|
5071
5225
|
//# sourceMappingURL=index.js.map
|