@unframework.dev/testing 0.0.0-stage → 0.2.0

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.
Files changed (133) hide show
  1. package/README.md +536 -2
  2. package/dist/browser/axe.js +34 -0
  3. package/dist/browser/behaviour.js +59 -0
  4. package/dist/browser/capabilities.js +58 -0
  5. package/dist/browser/clock.d.ts +17 -0
  6. package/dist/browser/clock.js +69 -0
  7. package/dist/browser/console.d.ts +27 -0
  8. package/dist/browser/console.js +142 -0
  9. package/dist/browser/determinism.js +108 -0
  10. package/dist/browser/element-timeout.js +28 -0
  11. package/dist/browser/events.js +68 -0
  12. package/dist/browser/geometry.js +135 -0
  13. package/dist/browser/keys.js +62 -0
  14. package/dist/browser/matchers.d.ts +39 -0
  15. package/dist/browser/matchers.js +78 -0
  16. package/dist/browser/navigation.js +38 -0
  17. package/dist/browser/parity.d.ts +10 -0
  18. package/dist/browser/parity.js +93 -0
  19. package/dist/browser/spec.d.ts +25 -0
  20. package/dist/browser/spec.js +38 -0
  21. package/dist/browser/target.d.ts +16 -0
  22. package/dist/browser/target.js +27 -0
  23. package/dist/browser/text-runs.js +68 -0
  24. package/dist/browser/thrown.js +71 -0
  25. package/dist/browser/trace.d.ts +21 -0
  26. package/dist/browser/trace.js +73 -0
  27. package/dist/browser/user.d.ts +45 -0
  28. package/dist/browser/user.js +184 -0
  29. package/dist/browser/view.d.ts +114 -0
  30. package/dist/browser/view.js +282 -0
  31. package/dist/browser/visual.d.ts +20 -0
  32. package/dist/browser/visual.js +36 -0
  33. package/dist/cli.d.ts +23 -0
  34. package/dist/cli.js +90 -0
  35. package/dist/commands.d.ts +107 -0
  36. package/dist/config/broadcast.js +29 -0
  37. package/dist/config/cases.d.ts +28 -0
  38. package/dist/config/cases.js +94 -0
  39. package/dist/config/index.d.ts +82 -0
  40. package/dist/config/index.js +295 -0
  41. package/dist/config/project-vite.d.ts +40 -0
  42. package/dist/config/project-vite.js +152 -0
  43. package/dist/diff.d.ts +14 -0
  44. package/dist/diff.js +92 -0
  45. package/dist/dom/serialize.js +236 -0
  46. package/dist/errors.d.ts +13 -0
  47. package/dist/errors.js +38 -0
  48. package/dist/harness.d.ts +189 -0
  49. package/dist/harness.js +53 -0
  50. package/dist/index.d.ts +16 -0
  51. package/dist/index.js +12 -0
  52. package/dist/internal.d.ts +8 -0
  53. package/dist/internal.js +6 -0
  54. package/dist/layers.d.ts +183 -0
  55. package/dist/layers.js +241 -0
  56. package/dist/node/browser.d.ts +33 -0
  57. package/dist/node/browser.js +64 -0
  58. package/dist/node/commands.d.ts +137 -0
  59. package/dist/node/commands.js +139 -0
  60. package/dist/node/context.d.ts +28 -0
  61. package/dist/node/context.js +55 -0
  62. package/dist/node/events.d.ts +25 -0
  63. package/dist/node/events.js +50 -0
  64. package/dist/node/finished.d.ts +12 -0
  65. package/dist/node/finished.js +28 -0
  66. package/dist/node/index.d.ts +21 -0
  67. package/dist/node/index.js +20 -0
  68. package/dist/node/matrix.d.ts +219 -0
  69. package/dist/node/matrix.js +309 -0
  70. package/dist/node/mode.d.ts +103 -0
  71. package/dist/node/mode.js +204 -0
  72. package/dist/node/names.d.ts +4 -0
  73. package/dist/node/names.js +5 -0
  74. package/dist/node/policy.d.ts +44 -0
  75. package/dist/node/policy.js +140 -0
  76. package/dist/node/reporter.d.ts +101 -0
  77. package/dist/node/reporter.js +251 -0
  78. package/dist/node/summary.d.ts +99 -0
  79. package/dist/node/summary.js +352 -0
  80. package/dist/node/thrown.js +78 -0
  81. package/dist/node/viewport.d.ts +7 -0
  82. package/dist/node/viewport.js +8 -0
  83. package/dist/node/visual.d.ts +85 -0
  84. package/dist/node/visual.js +373 -0
  85. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/protocol.d.ts +23930 -0
  86. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/structs.d.ts +22 -0
  87. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/types.d.ts +22221 -0
  88. package/dist/normalize/display.js +309 -0
  89. package/dist/normalize/index.d.ts +34 -0
  90. package/dist/normalize/index.js +38 -0
  91. package/dist/normalize/pipeline.d.ts +19 -0
  92. package/dist/normalize/pipeline.js +45 -0
  93. package/dist/normalize/print.js +103 -0
  94. package/dist/normalize/rules/angular-hosts.js +53 -0
  95. package/dist/normalize/rules/aria-hosts.js +48 -0
  96. package/dist/normalize/rules/comments.js +16 -0
  97. package/dist/normalize/rules/control-values.js +65 -0
  98. package/dist/normalize/rules/engine-aliases.js +34 -0
  99. package/dist/normalize/rules/framework-attributes.js +85 -0
  100. package/dist/normalize/rules/generated-ids.js +64 -0
  101. package/dist/normalize/rules/ordering.js +39 -0
  102. package/dist/normalize/rules/qwik-styles.js +21 -0
  103. package/dist/normalize/rules/qwik-templates.js +20 -0
  104. package/dist/normalize/rules/values.js +125 -0
  105. package/dist/normalize/rules/whitespace.js +381 -0
  106. package/dist/normalize/style.js +121 -0
  107. package/dist/normalize/targets.d.ts +8 -0
  108. package/dist/normalize/targets.js +17 -0
  109. package/dist/normalize/tree.d.ts +1 -0
  110. package/dist/normalize/tree.js +151 -0
  111. package/dist/setup.d.ts +1 -0
  112. package/dist/setup.js +149 -0
  113. package/dist/ssr/index.d.ts +10 -0
  114. package/dist/ssr/index.js +103 -0
  115. package/dist/ssr/spec.d.ts +1 -0
  116. package/dist/ssr/spec.js +7 -0
  117. package/dist/targets/angular.d.ts +1 -0
  118. package/dist/targets/angular.js +5 -0
  119. package/dist/targets/astro.d.ts +1 -0
  120. package/dist/targets/astro.js +5 -0
  121. package/dist/targets/qwik.d.ts +1 -0
  122. package/dist/targets/qwik.js +5 -0
  123. package/dist/targets/react.d.ts +1 -0
  124. package/dist/targets/react.js +5 -0
  125. package/dist/targets/solid.d.ts +1 -0
  126. package/dist/targets/solid.js +5 -0
  127. package/dist/targets/svelte.d.ts +1 -0
  128. package/dist/targets/svelte.js +5 -0
  129. package/dist/targets/vue.d.ts +1 -0
  130. package/dist/targets/vue.js +5 -0
  131. package/dist/visual-types.d.ts +92 -0
  132. package/dist/visual-types.js +24 -0
  133. package/package.json +146 -3
@@ -0,0 +1,135 @@
1
+ //#region src/browser/geometry.ts
2
+ /** The computed properties that explain how a box looks. Width and height come from the box. */
3
+ const GEOMETRY_STYLE_PROPERTIES = [
4
+ "display",
5
+ "position",
6
+ "top",
7
+ "right",
8
+ "bottom",
9
+ "left",
10
+ "float",
11
+ "box-sizing",
12
+ "margin-top",
13
+ "margin-right",
14
+ "margin-bottom",
15
+ "margin-left",
16
+ "padding-top",
17
+ "padding-right",
18
+ "padding-bottom",
19
+ "padding-left",
20
+ "border-top-width",
21
+ "border-right-width",
22
+ "border-bottom-width",
23
+ "border-left-width",
24
+ "border-top-style",
25
+ "border-right-style",
26
+ "border-bottom-style",
27
+ "border-left-style",
28
+ "border-top-color",
29
+ "border-right-color",
30
+ "border-bottom-color",
31
+ "border-left-color",
32
+ "border-top-left-radius",
33
+ "border-top-right-radius",
34
+ "border-bottom-right-radius",
35
+ "border-bottom-left-radius",
36
+ "color",
37
+ "background-color",
38
+ "background-image",
39
+ "opacity",
40
+ "visibility",
41
+ "font-family",
42
+ "font-size",
43
+ "font-weight",
44
+ "font-style",
45
+ "line-height",
46
+ "letter-spacing",
47
+ "word-spacing",
48
+ "text-align",
49
+ "text-decoration-line",
50
+ "text-transform",
51
+ "text-shadow",
52
+ "white-space",
53
+ "vertical-align",
54
+ "overflow-x",
55
+ "overflow-y",
56
+ "z-index",
57
+ "transform",
58
+ "box-shadow",
59
+ "outline-style",
60
+ "outline-width",
61
+ "outline-color",
62
+ "outline-offset",
63
+ "list-style-type",
64
+ "flex-direction",
65
+ "flex-wrap",
66
+ "justify-content",
67
+ "align-items",
68
+ "row-gap",
69
+ "column-gap",
70
+ "grid-template-columns",
71
+ "grid-template-rows"
72
+ ];
73
+ /** The pseudo-elements captured where their computed `content` is not `none`. */
74
+ const PSEUDO_ELEMENTS = ["::before", "::after"];
75
+ /** The captured properties of a computed style. */
76
+ function styleOf(computed) {
77
+ const style = {};
78
+ for (const property of GEOMETRY_STYLE_PROPERTIES) style[property] = computed.getPropertyValue(property);
79
+ return style;
80
+ }
81
+ const toBox = (rect, origin) => [
82
+ rect.x - origin.x,
83
+ rect.y - origin.y,
84
+ rect.width,
85
+ rect.height
86
+ ];
87
+ /** Snapshots the boxes and computed styles of every element and text node under a container. */
88
+ function captureGeometry(container) {
89
+ const origin = container.getBoundingClientRect();
90
+ const nodes = {};
91
+ const visit = (parent, prefix) => {
92
+ const counters = /* @__PURE__ */ new Map();
93
+ const next = (key) => {
94
+ const index = counters.get(key) ?? 0;
95
+ counters.set(key, index + 1);
96
+ return `${prefix}${key}[${index}]`;
97
+ };
98
+ for (const child of flatten(parent)) if (child.nodeType === Node.TEXT_NODE) {
99
+ if (!child.textContent?.trim()) continue;
100
+ const range = document.createRange();
101
+ range.selectNodeContents(child);
102
+ nodes[next("#text")] = { box: [...range.getClientRects()].map((r) => toBox(r, origin)) };
103
+ } else if (child instanceof Element) {
104
+ const path = next(child.localName);
105
+ const style = styleOf(getComputedStyle(child));
106
+ nodes[path] = {
107
+ box: toBox(child.getBoundingClientRect(), origin),
108
+ style
109
+ };
110
+ for (const pseudo of PSEUDO_ELEMENTS) {
111
+ const computed = getComputedStyle(child, pseudo);
112
+ if (computed.content === "none") continue;
113
+ nodes[`${path}${pseudo}`] = { style: {
114
+ ...styleOf(computed),
115
+ content: computed.content
116
+ } };
117
+ }
118
+ if (child.localName !== "textarea") visit(child, `${path}/`);
119
+ }
120
+ };
121
+ visit(container, "");
122
+ return {
123
+ version: 1,
124
+ nodes
125
+ };
126
+ }
127
+ /** The element and text children of a node, looking through `display: contents` wrappers. */
128
+ function flatten(parent) {
129
+ const out = [];
130
+ for (const child of parent.childNodes) if (child instanceof Element && getComputedStyle(child).display === "contents") out.push(...flatten(child));
131
+ else if (child.nodeType === Node.TEXT_NODE || child instanceof Element) out.push(child);
132
+ return out;
133
+ }
134
+ //#endregion
135
+ export { GEOMETRY_STYLE_PROPERTIES, captureGeometry };
@@ -0,0 +1,62 @@
1
+ //#region src/browser/keys.ts
2
+ /** The syntax, for the refusals. */
3
+ const SYNTAX = "a character types itself, {Enter} presses and releases a key as Playwright names it ({Escape}, {ArrowDown}, {Backspace}), {Shift>} holds it and {/Shift} releases it, and {{ and [[ type a brace and a bracket";
4
+ /**
5
+ * The keys of a text, in order, checked against the keys already held (and those the text holds
6
+ * on the way): a key is pressed only when it is not held, and released alone only when it is.
7
+ * Throws for an empty text and for anything outside the syntax, naming the action.
8
+ */
9
+ function parseKeys(text, action, held = /* @__PURE__ */ new Set()) {
10
+ const refuse = (problem) => {
11
+ throw new TypeError(`${action}: ${problem} in ${JSON.stringify(text)}: ${SYNTAX}.`);
12
+ };
13
+ if (text === "") refuse("no key to press");
14
+ const keys = [];
15
+ const holding = new Set(held);
16
+ const add = (written, key, press, release) => {
17
+ if (press && holding.has(key)) refuse(`${written} presses ${key}, which is held already`);
18
+ if (!press && !holding.has(key)) refuse(`${written} releases ${key}, which is not held`);
19
+ if (!release) holding.add(key);
20
+ if (!press) holding.delete(key);
21
+ keys.push({
22
+ key,
23
+ text: isCharacter(key),
24
+ press,
25
+ release
26
+ });
27
+ };
28
+ const chars = characters(text);
29
+ for (let index = 0; index < chars.length; index += 1) {
30
+ const char = chars[index];
31
+ if ((char === "{" || char === "[") && chars[index + 1] === char) {
32
+ add(char + char, char, true, true);
33
+ index += 1;
34
+ } else if (char === "[") refuse("a key code in brackets ([KeyA]) is not supported");
35
+ else if (char !== "{") add(char, char, true, true);
36
+ else {
37
+ const end = chars.indexOf("}", index + 1);
38
+ if (end === -1) refuse(`the "{" at ${index} is never closed`);
39
+ const tag = chars.slice(index + 1, end).join("");
40
+ const match = /^(\/)?([^{}/>[\]\\]+)(>)?$/u.exec(tag);
41
+ if (!match || match[1] && match[3]) refuse(`{${tag}} is not a key`);
42
+ const [, release, key = "", hold] = match;
43
+ add(`{${tag}}`, key, !release, !hold);
44
+ index = end;
45
+ }
46
+ }
47
+ return keys;
48
+ }
49
+ /** Whether a key is one character, which a keyboard layout without it inserts as text. */
50
+ function isCharacter(key) {
51
+ return characters(key).length === 1;
52
+ }
53
+ /**
54
+ * The characters of a text as Playwright's keyboard types them, a code point at a time (its
55
+ * `keyboard.type` loops with `for … of`): an emoji of several code points is several keys there
56
+ * too, so a grapheme is not one character here.
57
+ */
58
+ function characters(text) {
59
+ return Array.from(text);
60
+ }
61
+ //#endregion
62
+ export { isCharacter, parseKeys };
@@ -0,0 +1,39 @@
1
+ import "../commands.js";
2
+ //#region src/browser/matchers.d.ts
3
+ /** Options for `toHaveNoAxeViolations`. */
4
+ export interface NoAxeViolationsOptions {
5
+ /**
6
+ * The axe rule ids the element is known to break, exactly, as case.json's `axe` list is for
7
+ * L11: a rule axe reports that is not listed fails, and so does a listed rule it doesn't
8
+ * report. None by default.
9
+ */
10
+ expected?: readonly string[];
11
+ }
12
+ declare module "vitest" {
13
+ interface Matchers<R, T> {
14
+ /**
15
+ * Runs axe-core on the element with L11's options, and passes when it reports no violation,
16
+ * or exactly the rules `options.expected` names.
17
+ *
18
+ * @example
19
+ * await expect.element(view.getByRole("button")).toHaveNoAxeViolations();
20
+ */
21
+ toHaveNoAxeViolations(options?: NoAxeViolationsOptions): Promise<void>;
22
+ /**
23
+ * Compares the element's ARIA tree with `expected`, one tree that holds on every target:
24
+ * Playwright's ARIA snapshot, normalised as L7 normalises `aria.<name>.yaml`. Common
25
+ * indentation and the blank lines around `expected` are ignored, so a template literal can
26
+ * hold it.
27
+ *
28
+ * @example
29
+ * await expect.element(view.getByRole("group")).toHaveAriaTree(`
30
+ * - group:
31
+ * - button "Save"
32
+ * `);
33
+ */
34
+ toHaveAriaTree(expected: string): Promise<void>;
35
+ }
36
+ }
37
+ /** Registers the matchers. The setup file calls it once, before any spec runs. */
38
+ export declare function installMatchers(): void;
39
+ //#endregion
@@ -0,0 +1,78 @@
1
+ import { diffLines } from "../diff.js";
2
+ import { currentTarget } from "./target.js";
3
+ import { renameGeneratedIds } from "../normalize/rules/generated-ids.js";
4
+ import { isNormalizeTarget } from "../normalize/targets.js";
5
+ import { normalizeDomWithIds } from "../dom/serialize.js";
6
+ import { inlineHosts } from "../normalize/rules/aria-hosts.js";
7
+ import { compareAxe } from "./axe.js";
8
+ import { expect } from "vitest";
9
+ import { commands, page } from "vitest/browser";
10
+ //#region src/browser/matchers.ts
11
+ /** Registers the matchers. The setup file calls it once, before any spec runs. */
12
+ function installMatchers() {
13
+ expect.extend({
14
+ async toHaveNoAxeViolations(received, options = {}) {
15
+ const element = elementOf(received, "toHaveNoAxeViolations");
16
+ const expected = options.expected ?? [];
17
+ const { pass, unexpected, missing } = await compareAxe(element, expected);
18
+ const lines = [...unexpected];
19
+ if (missing.length) lines.push(` expected but not reported: ${missing.join(", ")}`);
20
+ return {
21
+ pass,
22
+ message: () => pass ? `expected axe-core to report a violation other than ${expected.length ? expected.join(", ") : "none"}, but it reported exactly ${expected.length ? "those" : "none"}` : `axe-core reported violations on ${currentTarget()}:\n${lines.join("\n")}`
23
+ };
24
+ },
25
+ async toHaveAriaTree(received, expected) {
26
+ const element = elementOf(received, "toHaveAriaTree");
27
+ if (typeof expected !== "string") throw new TypeError("toHaveAriaTree: the expected tree is a string, in YAML.");
28
+ const target = currentTarget();
29
+ const actual = asTree(await ariaTree(element, target));
30
+ const wanted = asTree(expected);
31
+ const pass = actual === wanted;
32
+ return {
33
+ pass,
34
+ message: () => pass ? `expected the ARIA tree on ${target} to differ from:\n${wanted}` : `the ARIA tree on ${target} differs:\n${diffLines(wanted, actual)}`,
35
+ actual,
36
+ expected: wanted
37
+ };
38
+ }
39
+ });
40
+ }
41
+ /**
42
+ * The matchers take an element: `expect.element(locator)` resolves one, and `expect(element)`
43
+ * passes it as it is.
44
+ */
45
+ function elementOf(received, matcher) {
46
+ if (received instanceof Element) return received;
47
+ throw new TypeError(`${matcher}: expected an element, as \`expect.element(locator)\` resolves one, but received ${received === null ? "null" : typeof received}.`);
48
+ }
49
+ /**
50
+ * Playwright's ARIA snapshot of `element`, as L7 takes a view's (`aria` in view.ts): with
51
+ * Angular's hosts inline while it is taken (ADR-0060), and the generated ids in its text renamed
52
+ * as the normalised DOM renames them.
53
+ */
54
+ async function ariaTree(element, target) {
55
+ const normalizeTarget = isNormalizeTarget(target) ? target : void 0;
56
+ const { ids } = normalizeDomWithIds(element, normalizeTarget ? { target: normalizeTarget } : {});
57
+ const restore = inlineHosts(element, normalizeTarget);
58
+ try {
59
+ const snapshot = await commands.ufAriaSnapshot(page.elementLocator(element).serialize());
60
+ return renameGeneratedIds(snapshot, ids);
61
+ } finally {
62
+ restore();
63
+ }
64
+ }
65
+ /**
66
+ * A tree as the matcher compares it: no blank lines around it, no trailing spaces, and the
67
+ * indentation its lines share removed, so a tree written in an indented template literal reads
68
+ * as the snapshot does.
69
+ */
70
+ function asTree(text) {
71
+ const lines = text.split("\n").map((line) => line.trimEnd());
72
+ while (lines.length && !lines[0]) lines.shift();
73
+ while (lines.length && !lines.at(-1)) lines.pop();
74
+ const indent = Math.min(...lines.filter(Boolean).map((line) => line.length - line.trimStart().length));
75
+ return lines.map((line) => line.slice(Number.isFinite(indent) ? indent : 0)).join("\n");
76
+ }
77
+ //#endregion
78
+ export { installMatchers };
@@ -0,0 +1,38 @@
1
+ //#region src/browser/navigation.ts
2
+ /** What the guard prevented since a test last took the list. */
3
+ const prevented = [];
4
+ let installed = false;
5
+ /**
6
+ * Installs the guard once per page: bubbling listeners on `window`, which run after every
7
+ * framework's own (Solid's and Qwik's delegation listen on the document, React's on its root,
8
+ * the others on the element), so a component that prevents the default has done so by then.
9
+ */
10
+ function installNavigationGuard() {
11
+ if (installed) return;
12
+ installed = true;
13
+ window.addEventListener("submit", (event) => {
14
+ if (event.defaultPrevented) return;
15
+ event.preventDefault();
16
+ prevented.push(`a form submission was not prevented: the component's submit listener must call event.preventDefault() (${describe(event.target)}).`);
17
+ });
18
+ window.addEventListener("click", (event) => {
19
+ if (event.defaultPrevented) return;
20
+ const target = event.target;
21
+ const link = target instanceof Element ? target.closest("a[href]") : null;
22
+ if (!link) return;
23
+ event.preventDefault();
24
+ prevented.push(`a link's navigation was not prevented: a click on a link leaves the page unless the component prevents it (${describe(link)}).`);
25
+ });
26
+ }
27
+ /** What the guard prevented since this was last called, and forgets it. */
28
+ function takePreventedNavigations() {
29
+ return prevented.splice(0);
30
+ }
31
+ /** An element for a message: its tag, and its id or name if it has one. */
32
+ function describe(target) {
33
+ if (!(target instanceof Element)) return "outside an element";
34
+ const name = target.getAttribute("id") ?? target.getAttribute("name");
35
+ return `<${target.localName}${name ? ` "${name}"` : ""}>`;
36
+ }
37
+ //#endregion
38
+ export { installNavigationGuard, takePreventedNavigations };
@@ -0,0 +1,10 @@
1
+ import { PixelTolerance } from "../visual-types.js";
2
+ import "../commands.js";
3
+ import { Locator } from "vitest/browser";
4
+ //#region src/browser/parity.d.ts
5
+ /** Options for `expectParity`. */
6
+ export interface ParityOptions {
7
+ /** A pixel tolerance for this scenario. Zero by default; any tolerance needs a reason. */
8
+ tolerance?: PixelTolerance;
9
+ }
10
+ //#endregion
@@ -0,0 +1,93 @@
1
+ import { caseOfFile } from "../harness.js";
2
+ import { KEBAB_CASE } from "../node/names.js";
3
+ import { LIVE_REFERENCE_SKIP, referenceNotRunSkip } from "../visual-types.js";
4
+ import { NO_INTERACTION_SKIP, recordLayerChecks, recordScenario } from "../layers.js";
5
+ import { renameGeneratedIds } from "../normalize/rules/generated-ids.js";
6
+ import { compareAxe } from "./axe.js";
7
+ import { traceFile } from "./trace.js";
8
+ import { captureVisual } from "./visual.js";
9
+ import { TestRunner, inject } from "vitest";
10
+ import { commands } from "vitest/browser";
11
+ //#region src/browser/parity.ts
12
+ /** The scenarios each spec file has checked, by file: a name names one scenario of a case. */
13
+ const checked = /* @__PURE__ */ new Map();
14
+ /**
15
+ * Runs L7, L9, L10 and L11 for one scenario of the current test's case and records them. Only
16
+ * a misuse rejects (a name that is not kebab-case or already checked, a tolerance without a
17
+ * reason, a call outside a test): that is the spec's own error, recorded as L8.
18
+ */
19
+ async function expectParity(view, name, options = {}) {
20
+ if (!KEBAB_CASE.test(name)) throw new Error(`expectParity("${name}"): a scenario name is kebab-case (words of a-z and 0-9 joined by single hyphens), such as "after-click".`);
21
+ if (options.tolerance && !options.tolerance.reason.trim()) throw new Error(`expectParity("${name}"): a pixel tolerance needs a reason.`);
22
+ const test = TestRunner.getCurrentTest();
23
+ if (!test) throw new Error("expectParity must be called inside a test.");
24
+ const names = checked.get(test.file.filepath) ?? /* @__PURE__ */ new Set();
25
+ checked.set(test.file.filepath, names);
26
+ if (names.has(name)) throw new Error(`expectParity("${name}"): this spec checked a scenario of that name already. Each scenario is unique in its case: name this one apart.`);
27
+ names.add(name);
28
+ const harness = inject("ufHarness");
29
+ const caseId = caseOfFile(test.file.filepath, harness);
30
+ const declaredAxe = harness.cases[caseId]?.axe ?? [];
31
+ const subject = {
32
+ case: caseId,
33
+ target: view.target,
34
+ quarantine: harness.quarantine
35
+ };
36
+ recordScenario(test, subject, name);
37
+ await view.settle();
38
+ const steps = view.trace.take();
39
+ await recordLayerChecks(test, subject, {
40
+ async L7() {
41
+ const failures = [];
42
+ const { html, ids } = view.dom();
43
+ const dom = await commands.ufArtefact({
44
+ case: caseId,
45
+ file: `dom.${name}.html`,
46
+ contents: asFile(html)
47
+ });
48
+ if (!dom.pass) failures.push(dom.message);
49
+ const snapshot = renameGeneratedIds(await view.aria(), new Map(ids));
50
+ const aria = await commands.ufArtefact({
51
+ case: caseId,
52
+ file: `aria.${name}.yaml`,
53
+ contents: asFile(snapshot)
54
+ });
55
+ if (!aria.pass) failures.push(aria.message);
56
+ if (failures.length) throw new Error(failures.join("\n\n"));
57
+ },
58
+ async L9() {
59
+ const trace = await commands.ufArtefact({
60
+ case: caseId,
61
+ file: `trace.${name}.json`,
62
+ contents: steps.length ? traceFile(steps) : null
63
+ });
64
+ if (!trace.pass) throw new Error(trace.message);
65
+ return steps.length ? void 0 : { skip: NO_INTERACTION_SKIP };
66
+ },
67
+ async L10() {
68
+ const result = await captureVisual(test, {
69
+ case: caseId,
70
+ name,
71
+ container: view.container,
72
+ locator: view.locator,
73
+ ...options.tolerance ? { tolerance: options.tolerance } : {}
74
+ });
75
+ if (result.outcome === "reference-not-run" && result.referenceProject !== void 0) return { skip: referenceNotRunSkip(result.referenceProject) };
76
+ if (!result.pass) throw new Error(`${result.outcome} (${result.mode}, ${result.role}): ${result.message}`);
77
+ return result.outcome === "published-reference" ? { skip: LIVE_REFERENCE_SKIP } : void 0;
78
+ },
79
+ async L11() {
80
+ const { pass, unexpected, missing } = await compareAxe(view.container, declaredAxe);
81
+ if (pass) return;
82
+ const lines = [...unexpected];
83
+ if (missing.length) lines.push(` declared in case.json but not reported: ${missing.join(", ")}`);
84
+ throw new Error(`axe-core violations differ from case.json's "axe" list:\n${lines.join("\n")}`);
85
+ }
86
+ });
87
+ }
88
+ /** Artefacts are text files with exactly one trailing newline. */
89
+ function asFile(text) {
90
+ return `${text.replace(/\n+$/, "")}\n`;
91
+ }
92
+ //#endregion
93
+ export { expectParity };
@@ -0,0 +1,25 @@
1
+ import { TestFunction, TestOptions } from "vitest";
2
+ import { CapabilityName } from "@unframework.dev/codegen";
3
+ //#region src/browser/spec.d.ts
4
+ /** The options of Vitest's that a corpus test may not set. */
5
+ declare const REFUSED: readonly ["skip", "only", "todo", "fails", "retry", "repeats", "concurrent", "tags"];
6
+ /** A corpus test's options: Vitest's (a timeout, metadata), and the capabilities it requires. */
7
+ export interface SpecOptions extends Omit<TestOptions, (typeof REFUSED)[number]> {
8
+ /**
9
+ * The capabilities the test needs: on a target whose cell for one of them is unsupported, the
10
+ * test is skipped and every browser layer records `requires <capability>: <the reason>`. A
11
+ * test whose expectations depend on client code requires `"interactivity"`.
12
+ */
13
+ requires?: readonly CapabilityName[];
14
+ }
15
+ /** `it(name, fn)` or `it(name, { requires }, fn)`. */
16
+ export interface SpecTest {
17
+ (name: string, fn: TestFunction): void;
18
+ (name: string, options: SpecOptions, fn: TestFunction): void;
19
+ }
20
+ /** Declares a corpus test, with the capabilities it requires (see {@link SpecOptions}). */
21
+ declare const it$1: SpecTest;
22
+ /** {@link it}, by its other name. */
23
+ export declare const test: SpecTest;
24
+ //#endregion
25
+ export { it$1 as it };
@@ -0,0 +1,38 @@
1
+ import { capabilityCell } from "./capabilities.js";
2
+ import { it } from "vitest";
3
+ //#region src/browser/spec.ts
4
+ /** The options of Vitest's that a corpus test may not set. */
5
+ const REFUSED = [
6
+ "skip",
7
+ "only",
8
+ "todo",
9
+ "fails",
10
+ "retry",
11
+ "repeats",
12
+ "concurrent",
13
+ "tags"
14
+ ];
15
+ /** Declares a corpus test, with the capabilities it requires (see {@link SpecOptions}). */
16
+ const it$1 = (name, optionsOrFn, maybeFn) => {
17
+ const options = typeof optionsOrFn === "function" ? {} : optionsOrFn;
18
+ const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
19
+ if (!fn) throw new TypeError(`it("${name}"): a test needs a function.`);
20
+ const refused = REFUSED.filter((key) => Object.hasOwn(options, key));
21
+ if (refused.length) throw new TypeError(`it("${name}"): a corpus test does not set ${refused.join(", ")}. A known failure is a quarantine entry, a flaky test is a bug, and a test runs on every target unless a capability it requires is unsupported.`);
22
+ const { requires, meta, ...rest } = options;
23
+ if (requires !== void 0) {
24
+ if (!Array.isArray(requires) || !requires.length) throw new TypeError(`it("${name}"): requires names one or more capabilities.`);
25
+ for (const capability of requires) capabilityCell(capability);
26
+ }
27
+ it(name, {
28
+ ...rest,
29
+ meta: {
30
+ ...meta,
31
+ ...requires ? { ufRequires: [...requires] } : {}
32
+ }
33
+ }, fn);
34
+ };
35
+ /** {@link it}, by its other name. */
36
+ const test = it$1;
37
+ //#endregion
38
+ export { it$1 as it, test };
@@ -0,0 +1,16 @@
1
+ import { MountAdapter, MountEvent } from "@unframework.dev/codegen";
2
+ //#region src/browser/target.d.ts
3
+ /** What a registration may add to its adapter. */
4
+ export interface TargetOptions {
5
+ /**
6
+ * The events a component declares, read from the component itself: for a stub target, whose
7
+ * components are not compiled. Without it, `mount` asks the project which events the case's
8
+ * compiled component declares (the `ufComponentEvents` command).
9
+ */
10
+ events?(component: unknown): readonly MountEvent[];
11
+ }
12
+ /** Registers the project's mount adapter. One adapter per project: a second target is a bug. */
13
+ export declare function registerTarget(target: string, mount: MountAdapter, options?: TargetOptions): void;
14
+ /** The target this project verifies (`test.provide.target`). */
15
+ export declare function currentTarget(): string;
16
+ //#endregion
@@ -0,0 +1,27 @@
1
+ import { inject } from "vitest";
2
+ //#region src/browser/target.ts
3
+ let registration;
4
+ /** Registers the project's mount adapter. One adapter per project: a second target is a bug. */
5
+ function registerTarget(target, mount, options = {}) {
6
+ if (registration && registration.target !== target) throw new Error(`registerTarget("${target}"): this project already registered "${registration.target}". A browser project verifies one target.`);
7
+ registration = {
8
+ ...options,
9
+ target,
10
+ mount
11
+ };
12
+ }
13
+ /** The target this project verifies (`test.provide.target`). */
14
+ function currentTarget() {
15
+ const target = inject("target");
16
+ if (!target) throw new Error("No target is provided: the project must set test.provide.target.");
17
+ return target;
18
+ }
19
+ /** The registered adapter, checked against the project's target. */
20
+ function registeredAdapter() {
21
+ if (!registration) throw new Error("No mount adapter is registered: the project's setupFiles must include @unframework.dev/testing/<target>.");
22
+ const target = currentTarget();
23
+ if (registration.target !== target) throw new Error(`The registered adapter is for "${registration.target}", but this project verifies "${target}".`);
24
+ return registration;
25
+ }
26
+ //#endregion
27
+ export { currentTarget, registerTarget, registeredAdapter };
@@ -0,0 +1,68 @@
1
+ //#region src/browser/text-runs.ts
2
+ /** Elements whose text is not laid out as text: raw text, and a form control's value. */
3
+ const SKIPPED = /* @__PURE__ */ new Set([
4
+ "script",
5
+ "style",
6
+ "textarea"
7
+ ]);
8
+ /**
9
+ * Merges every run of adjacent text nodes under `root` into the run's first text node: text
10
+ * nodes count as adjacent when only comment nodes (framework anchors) separate them. The first
11
+ * node's data becomes the run's text; the other text nodes and the comments between them are
12
+ * detached, and kept. Runs never cross an element, so white-space processing, which works on an
13
+ * element's text whatever its nodes, is unchanged. Returns what restores the tree exactly: the
14
+ * original data, and the same node objects back in their places, so a framework's references to
15
+ * its nodes stay valid.
16
+ */
17
+ function mergeTextRuns(root) {
18
+ const runs = [];
19
+ const visit = (parent) => {
20
+ let child = parent.firstChild;
21
+ while (child) {
22
+ if (child instanceof Text) {
23
+ const run = runFrom(child);
24
+ if (run.detached.length) {
25
+ runs.push(run);
26
+ child.data = [run.data, ...run.detached.map(textOf)].join("");
27
+ for (const node of run.detached) node.remove();
28
+ }
29
+ } else if (child instanceof Element && !SKIPPED.has(child.localName)) visit(child);
30
+ child = child.nextSibling;
31
+ }
32
+ };
33
+ visit(root);
34
+ return () => {
35
+ for (const { first, data, detached } of runs.toReversed()) {
36
+ first.data = data;
37
+ first.after(...detached);
38
+ }
39
+ };
40
+ }
41
+ /** Runs `capture` with the text runs under `root` merged, and restores them afterwards. */
42
+ async function withMergedTextRuns(root, capture) {
43
+ const restore = mergeTextRuns(root);
44
+ try {
45
+ return await capture();
46
+ } finally {
47
+ restore();
48
+ }
49
+ }
50
+ /** The run starting at `first`: the nodes after it up to its last adjacent text node. */
51
+ function runFrom(first) {
52
+ const detached = [];
53
+ const pending = [];
54
+ for (let node = first.nextSibling; node; node = node.nextSibling) if (node instanceof Comment) pending.push(node);
55
+ else if (node instanceof Text) detached.push(...pending.splice(0), node);
56
+ else break;
57
+ return {
58
+ first,
59
+ data: first.data,
60
+ detached
61
+ };
62
+ }
63
+ /** The text a detached node adds to its run: a text node's data, nothing for a comment. */
64
+ function textOf(node) {
65
+ return node instanceof Text ? node.data : "";
66
+ }
67
+ //#endregion
68
+ export { mergeTextRuns, withMergedTextRuns };