@unframework.dev/testing 0.0.0-stage → 0.0.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.
- package/README.md +511 -2
- package/dist/browser/axe.js +34 -0
- package/dist/browser/behaviour.js +59 -0
- package/dist/browser/capabilities.js +58 -0
- package/dist/browser/clock.d.ts +17 -0
- package/dist/browser/clock.js +69 -0
- package/dist/browser/console.d.ts +27 -0
- package/dist/browser/console.js +142 -0
- package/dist/browser/determinism.js +108 -0
- package/dist/browser/element-timeout.js +28 -0
- package/dist/browser/events.js +68 -0
- package/dist/browser/geometry.js +135 -0
- package/dist/browser/keys.js +62 -0
- package/dist/browser/matchers.d.ts +39 -0
- package/dist/browser/matchers.js +78 -0
- package/dist/browser/navigation.js +38 -0
- package/dist/browser/parity.d.ts +10 -0
- package/dist/browser/parity.js +93 -0
- package/dist/browser/spec.d.ts +25 -0
- package/dist/browser/spec.js +38 -0
- package/dist/browser/target.d.ts +16 -0
- package/dist/browser/target.js +27 -0
- package/dist/browser/text-runs.js +68 -0
- package/dist/browser/thrown.js +71 -0
- package/dist/browser/trace.d.ts +21 -0
- package/dist/browser/trace.js +73 -0
- package/dist/browser/user.d.ts +45 -0
- package/dist/browser/user.js +184 -0
- package/dist/browser/view.d.ts +114 -0
- package/dist/browser/view.js +282 -0
- package/dist/browser/visual.d.ts +20 -0
- package/dist/browser/visual.js +36 -0
- package/dist/cli.d.ts +23 -0
- package/dist/cli.js +90 -0
- package/dist/commands.d.ts +107 -0
- package/dist/config/broadcast.js +29 -0
- package/dist/config/cases.d.ts +28 -0
- package/dist/config/cases.js +94 -0
- package/dist/config/index.d.ts +81 -0
- package/dist/config/index.js +275 -0
- package/dist/diff.d.ts +14 -0
- package/dist/diff.js +92 -0
- package/dist/dom/serialize.js +236 -0
- package/dist/errors.d.ts +13 -0
- package/dist/errors.js +38 -0
- package/dist/harness.d.ts +184 -0
- package/dist/harness.js +53 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +12 -0
- package/dist/internal.d.ts +8 -0
- package/dist/internal.js +6 -0
- package/dist/layers.d.ts +183 -0
- package/dist/layers.js +241 -0
- package/dist/node/browser.d.ts +33 -0
- package/dist/node/browser.js +64 -0
- package/dist/node/commands.d.ts +137 -0
- package/dist/node/commands.js +139 -0
- package/dist/node/context.d.ts +28 -0
- package/dist/node/context.js +55 -0
- package/dist/node/events.d.ts +25 -0
- package/dist/node/events.js +50 -0
- package/dist/node/finished.d.ts +12 -0
- package/dist/node/finished.js +28 -0
- package/dist/node/index.d.ts +21 -0
- package/dist/node/index.js +20 -0
- package/dist/node/matrix.d.ts +219 -0
- package/dist/node/matrix.js +309 -0
- package/dist/node/mode.d.ts +101 -0
- package/dist/node/mode.js +201 -0
- package/dist/node/names.d.ts +4 -0
- package/dist/node/names.js +5 -0
- package/dist/node/policy.d.ts +44 -0
- package/dist/node/policy.js +140 -0
- package/dist/node/reporter.d.ts +101 -0
- package/dist/node/reporter.js +251 -0
- package/dist/node/summary.d.ts +99 -0
- package/dist/node/summary.js +352 -0
- package/dist/node/thrown.js +78 -0
- package/dist/node/viewport.d.ts +7 -0
- package/dist/node/viewport.js +8 -0
- package/dist/node/visual.d.ts +85 -0
- package/dist/node/visual.js +370 -0
- package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/protocol.d.ts +23930 -0
- package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/structs.d.ts +22 -0
- package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/types.d.ts +22221 -0
- package/dist/normalize/display.js +309 -0
- package/dist/normalize/index.d.ts +34 -0
- package/dist/normalize/index.js +38 -0
- package/dist/normalize/pipeline.d.ts +19 -0
- package/dist/normalize/pipeline.js +45 -0
- package/dist/normalize/print.js +103 -0
- package/dist/normalize/rules/angular-hosts.js +53 -0
- package/dist/normalize/rules/aria-hosts.js +48 -0
- package/dist/normalize/rules/comments.js +16 -0
- package/dist/normalize/rules/control-values.js +65 -0
- package/dist/normalize/rules/engine-aliases.js +34 -0
- package/dist/normalize/rules/framework-attributes.js +85 -0
- package/dist/normalize/rules/generated-ids.js +64 -0
- package/dist/normalize/rules/ordering.js +39 -0
- package/dist/normalize/rules/qwik-styles.js +21 -0
- package/dist/normalize/rules/qwik-templates.js +20 -0
- package/dist/normalize/rules/values.js +125 -0
- package/dist/normalize/rules/whitespace.js +381 -0
- package/dist/normalize/style.js +121 -0
- package/dist/normalize/targets.d.ts +8 -0
- package/dist/normalize/targets.js +17 -0
- package/dist/normalize/tree.d.ts +1 -0
- package/dist/normalize/tree.js +151 -0
- package/dist/setup.d.ts +1 -0
- package/dist/setup.js +149 -0
- package/dist/ssr/index.d.ts +10 -0
- package/dist/ssr/index.js +103 -0
- package/dist/ssr/spec.d.ts +1 -0
- package/dist/ssr/spec.js +7 -0
- package/dist/targets/angular.d.ts +1 -0
- package/dist/targets/angular.js +5 -0
- package/dist/targets/astro.d.ts +1 -0
- package/dist/targets/astro.js +5 -0
- package/dist/targets/qwik.d.ts +1 -0
- package/dist/targets/qwik.js +5 -0
- package/dist/targets/react.d.ts +1 -0
- package/dist/targets/react.js +5 -0
- package/dist/targets/solid.d.ts +1 -0
- package/dist/targets/solid.js +5 -0
- package/dist/targets/svelte.d.ts +1 -0
- package/dist/targets/svelte.js +5 -0
- package/dist/targets/vue.d.ts +1 -0
- package/dist/targets/vue.js +5 -0
- package/dist/visual-types.d.ts +92 -0
- package/dist/visual-types.js +24 -0
- package/package.json +135 -3
|
@@ -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 };
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import { caseOfFile } from "../harness.js";
|
|
2
|
+
import { currentTarget } from "./target.js";
|
|
3
|
+
import { consoleMark, excuseConsoleSince, watchConsoleErrors } from "./console.js";
|
|
4
|
+
import { recordLayer } from "../layers.js";
|
|
5
|
+
import { TestRunner, expect, inject } from "vitest";
|
|
6
|
+
import { commands } from "vitest/browser";
|
|
7
|
+
//#region src/browser/thrown.ts
|
|
8
|
+
/** Why the messages of the throwing step are excused from L13: the step throws on purpose. */
|
|
9
|
+
const EXCUSE = "the step throws on purpose, and each framework reports that in its own words";
|
|
10
|
+
/** The rounds of waiting for an error a framework rethrows in a task of its own. */
|
|
11
|
+
const SETTLE_ROUNDS = 3;
|
|
12
|
+
/**
|
|
13
|
+
* Runs `step`, which must make the component throw, and records L14 from the first `Error` it
|
|
14
|
+
* raised. Vitest treats a window `error` as a failure of the run only while no page listener is
|
|
15
|
+
* registered, so these listeners also keep the deliberate throw from failing it.
|
|
16
|
+
*/
|
|
17
|
+
async function expectThrown(host, step) {
|
|
18
|
+
const test = TestRunner.getCurrentTest();
|
|
19
|
+
if (!test) throw new Error("expectThrown must be called inside a test.");
|
|
20
|
+
const harness = inject("ufHarness");
|
|
21
|
+
const subject = {
|
|
22
|
+
case: caseOfFile(test.file.filepath, harness),
|
|
23
|
+
target: currentTarget(),
|
|
24
|
+
quarantine: harness.quarantine
|
|
25
|
+
};
|
|
26
|
+
let thrown;
|
|
27
|
+
let logged;
|
|
28
|
+
const take = (value) => {
|
|
29
|
+
if (value instanceof Error) thrown ??= value;
|
|
30
|
+
};
|
|
31
|
+
const onError = (event) => take(event.error);
|
|
32
|
+
const onRejection = (event) => take(event.reason);
|
|
33
|
+
const unwatch = watchConsoleErrors((value) => {
|
|
34
|
+
if (value instanceof Error) logged ??= value;
|
|
35
|
+
});
|
|
36
|
+
window.addEventListener("error", onError);
|
|
37
|
+
window.addEventListener("unhandledrejection", onRejection);
|
|
38
|
+
const console = consoleMark();
|
|
39
|
+
const steps = host.stepMark();
|
|
40
|
+
try {
|
|
41
|
+
await step().catch(take);
|
|
42
|
+
for (let round = 0; round < SETTLE_ROUNDS; round += 1) {
|
|
43
|
+
await host.settle().catch(take);
|
|
44
|
+
await new Promise((resolve) => setTimeout(resolve, 0));
|
|
45
|
+
}
|
|
46
|
+
} finally {
|
|
47
|
+
window.removeEventListener("error", onError);
|
|
48
|
+
window.removeEventListener("unhandledrejection", onRejection);
|
|
49
|
+
unwatch();
|
|
50
|
+
}
|
|
51
|
+
excuseConsoleSince(console, EXCUSE);
|
|
52
|
+
host.forgetSteps(steps);
|
|
53
|
+
const first = thrown ?? logged;
|
|
54
|
+
const failure = await problem(subject.case, first);
|
|
55
|
+
recordLayer(test, subject, "L14", failure ? {
|
|
56
|
+
status: "fail",
|
|
57
|
+
message: failure
|
|
58
|
+
} : { status: "pass" });
|
|
59
|
+
expect(first).toBeInstanceOf(Error);
|
|
60
|
+
}
|
|
61
|
+
/** What is wrong with the captured error's mapped stack, or nothing. */
|
|
62
|
+
async function problem(caseId, error) {
|
|
63
|
+
if (!error) return "The step threw no Error.";
|
|
64
|
+
const { message } = await commands.ufMapStack({
|
|
65
|
+
case: caseId,
|
|
66
|
+
stack: error.stack ?? ""
|
|
67
|
+
});
|
|
68
|
+
return message;
|
|
69
|
+
}
|
|
70
|
+
//#endregion
|
|
71
|
+
export { expectThrown };
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
//#region src/browser/trace.d.ts
|
|
2
|
+
/** One scripted step, after it settled. */
|
|
3
|
+
export interface TraceStep {
|
|
4
|
+
/**
|
|
5
|
+
* What happened, the same on every target: the action, the locator under the view's root,
|
|
6
|
+
* and the action's arguments as JSON (`click getByRole('button', { name: '+3' })`,
|
|
7
|
+
* `fill getByLabelText('Name') "Ada"`, `rerender {"label":"New"}`).
|
|
8
|
+
*/
|
|
9
|
+
action: string;
|
|
10
|
+
/** The normalised DOM, one line each, the focused element marked `uf:focused`. */
|
|
11
|
+
dom: string[];
|
|
12
|
+
/** Playwright's ARIA snapshot of the root, one line each. */
|
|
13
|
+
aria: string[];
|
|
14
|
+
/**
|
|
15
|
+
* The events emitted since the step before (or since the mount), grouped by name: names
|
|
16
|
+
* sorted, each name's argument lists in the order they came (the order of different effects
|
|
17
|
+
* one run triggers is not part of the contract, ADR-0050).
|
|
18
|
+
*/
|
|
19
|
+
events: Record<string, unknown[][]>;
|
|
20
|
+
}
|
|
21
|
+
//#endregion
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { renameGeneratedIds } from "../normalize/rules/generated-ids.js";
|
|
2
|
+
import { groupEvents, renumberIds } from "./events.js";
|
|
3
|
+
/** The steps of one view not yet compared, and the events they have seen. */
|
|
4
|
+
var Trace = class {
|
|
5
|
+
#source;
|
|
6
|
+
#steps = [];
|
|
7
|
+
/** How many of the view's events earlier steps took. */
|
|
8
|
+
#cursor = 0;
|
|
9
|
+
constructor(source) {
|
|
10
|
+
this.#source = source;
|
|
11
|
+
open.add(this);
|
|
12
|
+
}
|
|
13
|
+
/** Records a step, after the action settled. */
|
|
14
|
+
async record(action) {
|
|
15
|
+
const { html, ids } = this.#source.dom();
|
|
16
|
+
const names = new Map(ids);
|
|
17
|
+
const aria = renameGeneratedIds(await this.#source.aria(), names);
|
|
18
|
+
const events = this.#source.events.slice(this.#cursor);
|
|
19
|
+
this.#cursor += events.length;
|
|
20
|
+
this.#steps.push({
|
|
21
|
+
action,
|
|
22
|
+
dom: lines(html),
|
|
23
|
+
aria: lines(aria),
|
|
24
|
+
events: groupEvents(events.map((event) => ({
|
|
25
|
+
...event,
|
|
26
|
+
args: renumberIds(event.args, names)
|
|
27
|
+
})))
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
/** The steps since the previous call, which `expectParity` compares; the trace forgets them. */
|
|
31
|
+
take() {
|
|
32
|
+
return this.#steps.splice(0);
|
|
33
|
+
}
|
|
34
|
+
/** How many steps are waiting to be compared. */
|
|
35
|
+
get length() {
|
|
36
|
+
return this.#steps.length;
|
|
37
|
+
}
|
|
38
|
+
/** Forgets the steps since the trace held `length` of them: they are no scenario to compare. */
|
|
39
|
+
forget(length) {
|
|
40
|
+
this.#steps.length = length;
|
|
41
|
+
}
|
|
42
|
+
/** The steps not taken yet, as a message, or nothing. */
|
|
43
|
+
leftover() {
|
|
44
|
+
if (!this.#steps.length) return void 0;
|
|
45
|
+
const actions = this.#steps.map((step) => step.action).join("; ");
|
|
46
|
+
return `${this.#steps.length} step(s) of ${this.#source.root} were never compared (${actions}): every view.user action and rerender is followed by an expectParity, which compares its trace.`;
|
|
47
|
+
}
|
|
48
|
+
};
|
|
49
|
+
/** Every trace of the current test, which the setup file judges when it ends. */
|
|
50
|
+
const open = /* @__PURE__ */ new Set();
|
|
51
|
+
/**
|
|
52
|
+
* The steps of the current test's views that no `expectParity` compared, as L9's failures, and
|
|
53
|
+
* forgets every trace: the setup file calls it when a test ends.
|
|
54
|
+
*/
|
|
55
|
+
function closeTraces() {
|
|
56
|
+
const messages = [...open].flatMap((trace) => trace.leftover() ?? []);
|
|
57
|
+
open.clear();
|
|
58
|
+
return messages;
|
|
59
|
+
}
|
|
60
|
+
/** A trace file's contents: pretty JSON, so a diff names the line that changed. */
|
|
61
|
+
function traceFile(steps) {
|
|
62
|
+
return `${JSON.stringify({
|
|
63
|
+
version: 1,
|
|
64
|
+
steps
|
|
65
|
+
}, null, 2)}\n`;
|
|
66
|
+
}
|
|
67
|
+
/** Text as lines, without the final line break. */
|
|
68
|
+
function lines(text) {
|
|
69
|
+
const trimmed = text.replace(/\n+$/, "");
|
|
70
|
+
return trimmed ? trimmed.split("\n") : [];
|
|
71
|
+
}
|
|
72
|
+
//#endregion
|
|
73
|
+
export { Trace, closeTraces, traceFile };
|