@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.
Files changed (131) hide show
  1. package/README.md +511 -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 +81 -0
  40. package/dist/config/index.js +275 -0
  41. package/dist/diff.d.ts +14 -0
  42. package/dist/diff.js +92 -0
  43. package/dist/dom/serialize.js +236 -0
  44. package/dist/errors.d.ts +13 -0
  45. package/dist/errors.js +38 -0
  46. package/dist/harness.d.ts +184 -0
  47. package/dist/harness.js +53 -0
  48. package/dist/index.d.ts +16 -0
  49. package/dist/index.js +12 -0
  50. package/dist/internal.d.ts +8 -0
  51. package/dist/internal.js +6 -0
  52. package/dist/layers.d.ts +183 -0
  53. package/dist/layers.js +241 -0
  54. package/dist/node/browser.d.ts +33 -0
  55. package/dist/node/browser.js +64 -0
  56. package/dist/node/commands.d.ts +137 -0
  57. package/dist/node/commands.js +139 -0
  58. package/dist/node/context.d.ts +28 -0
  59. package/dist/node/context.js +55 -0
  60. package/dist/node/events.d.ts +25 -0
  61. package/dist/node/events.js +50 -0
  62. package/dist/node/finished.d.ts +12 -0
  63. package/dist/node/finished.js +28 -0
  64. package/dist/node/index.d.ts +21 -0
  65. package/dist/node/index.js +20 -0
  66. package/dist/node/matrix.d.ts +219 -0
  67. package/dist/node/matrix.js +309 -0
  68. package/dist/node/mode.d.ts +101 -0
  69. package/dist/node/mode.js +201 -0
  70. package/dist/node/names.d.ts +4 -0
  71. package/dist/node/names.js +5 -0
  72. package/dist/node/policy.d.ts +44 -0
  73. package/dist/node/policy.js +140 -0
  74. package/dist/node/reporter.d.ts +101 -0
  75. package/dist/node/reporter.js +251 -0
  76. package/dist/node/summary.d.ts +99 -0
  77. package/dist/node/summary.js +352 -0
  78. package/dist/node/thrown.js +78 -0
  79. package/dist/node/viewport.d.ts +7 -0
  80. package/dist/node/viewport.js +8 -0
  81. package/dist/node/visual.d.ts +85 -0
  82. package/dist/node/visual.js +370 -0
  83. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/protocol.d.ts +23930 -0
  84. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/structs.d.ts +22 -0
  85. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/types.d.ts +22221 -0
  86. package/dist/normalize/display.js +309 -0
  87. package/dist/normalize/index.d.ts +34 -0
  88. package/dist/normalize/index.js +38 -0
  89. package/dist/normalize/pipeline.d.ts +19 -0
  90. package/dist/normalize/pipeline.js +45 -0
  91. package/dist/normalize/print.js +103 -0
  92. package/dist/normalize/rules/angular-hosts.js +53 -0
  93. package/dist/normalize/rules/aria-hosts.js +48 -0
  94. package/dist/normalize/rules/comments.js +16 -0
  95. package/dist/normalize/rules/control-values.js +65 -0
  96. package/dist/normalize/rules/engine-aliases.js +34 -0
  97. package/dist/normalize/rules/framework-attributes.js +85 -0
  98. package/dist/normalize/rules/generated-ids.js +64 -0
  99. package/dist/normalize/rules/ordering.js +39 -0
  100. package/dist/normalize/rules/qwik-styles.js +21 -0
  101. package/dist/normalize/rules/qwik-templates.js +20 -0
  102. package/dist/normalize/rules/values.js +125 -0
  103. package/dist/normalize/rules/whitespace.js +381 -0
  104. package/dist/normalize/style.js +121 -0
  105. package/dist/normalize/targets.d.ts +8 -0
  106. package/dist/normalize/targets.js +17 -0
  107. package/dist/normalize/tree.d.ts +1 -0
  108. package/dist/normalize/tree.js +151 -0
  109. package/dist/setup.d.ts +1 -0
  110. package/dist/setup.js +149 -0
  111. package/dist/ssr/index.d.ts +10 -0
  112. package/dist/ssr/index.js +103 -0
  113. package/dist/ssr/spec.d.ts +1 -0
  114. package/dist/ssr/spec.js +7 -0
  115. package/dist/targets/angular.d.ts +1 -0
  116. package/dist/targets/angular.js +5 -0
  117. package/dist/targets/astro.d.ts +1 -0
  118. package/dist/targets/astro.js +5 -0
  119. package/dist/targets/qwik.d.ts +1 -0
  120. package/dist/targets/qwik.js +5 -0
  121. package/dist/targets/react.d.ts +1 -0
  122. package/dist/targets/react.js +5 -0
  123. package/dist/targets/solid.d.ts +1 -0
  124. package/dist/targets/solid.js +5 -0
  125. package/dist/targets/svelte.d.ts +1 -0
  126. package/dist/targets/svelte.js +5 -0
  127. package/dist/targets/vue.d.ts +1 -0
  128. package/dist/targets/vue.js +5 -0
  129. package/dist/visual-types.d.ts +92 -0
  130. package/dist/visual-types.js +24 -0
  131. package/package.json +135 -3
package/dist/cli.d.ts ADDED
@@ -0,0 +1,23 @@
1
+ //#region src/cli.d.ts
2
+ /** Where the command runs and writes: the shape of `@unframework.dev/cli`'s `Io`. */
3
+ export interface TestIo {
4
+ cwd: string;
5
+ stdout(text: string): void;
6
+ stderr(text: string): void;
7
+ }
8
+ /** The command's arguments, read. */
9
+ export interface TestArguments {
10
+ targets: string[];
11
+ update: boolean;
12
+ /** What follows `--`, for Vitest. */
13
+ vitest: string[];
14
+ }
15
+ /** Reads the arguments, throwing on a usage error: the CLI exits 2 with the message. */
16
+ export declare function parseTestArguments(args: readonly string[]): TestArguments;
17
+ /**
18
+ * Runs the tests and gives the exit code: 0 when every test passes, 1 when one fails, and 2 on a
19
+ * usage or configuration error, which it reports, as the CLI's other commands do (ADR-0076).
20
+ * Vitest's own options (`--reporter`, a file filter) follow `--`.
21
+ */
22
+ export declare function run(args: string[], io: TestIo): Promise<number>;
23
+ //#endregion
package/dist/cli.js ADDED
@@ -0,0 +1,90 @@
1
+ import { defineTestConfig } from "./config/index.js";
2
+ import { existsSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { TARGET_NAMES } from "@unframework.dev/compiler";
5
+ import { parseCLI, startVitest } from "vitest/node";
6
+ //#region src/cli.ts
7
+ /** The files a project's own Vitest configuration may have, the first one found winning. */
8
+ const VITEST_CONFIGS = [
9
+ "vitest.config.ts",
10
+ "vitest.config.mts",
11
+ "vitest.config.js",
12
+ "vitest.config.mjs"
13
+ ];
14
+ /** Reads the arguments, throwing on a usage error: the CLI exits 2 with the message. */
15
+ function parseTestArguments(args) {
16
+ const parsed = {
17
+ targets: [],
18
+ update: false,
19
+ vitest: []
20
+ };
21
+ for (let index = 0; index < args.length; index += 1) {
22
+ const arg = args[index];
23
+ if (arg === "--") {
24
+ parsed.vitest = args.slice(index + 1);
25
+ break;
26
+ }
27
+ if (arg === "--update") {
28
+ parsed.update = true;
29
+ continue;
30
+ }
31
+ const target = /^--target(?:=(.*))?$/s.exec(arg);
32
+ if (target) {
33
+ const value = target[1] ?? args[index += 1];
34
+ if (value === void 0 || value === "" || value.startsWith("-")) throw new Error("--target needs a target's name, such as --target react.");
35
+ parsed.targets.push(value);
36
+ continue;
37
+ }
38
+ throw new Error(`unknown argument "${arg}". Pass Vitest's own options after --, such as unframework test -- --reporter=json.`);
39
+ }
40
+ const unknown = parsed.targets.filter((name) => !TARGET_NAMES.includes(name));
41
+ if (unknown.length) throw new Error(`unknown target${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}. The targets are ${TARGET_NAMES.join(", ")}.`);
42
+ return parsed;
43
+ }
44
+ /**
45
+ * Runs the tests and gives the exit code: 0 when every test passes, 1 when one fails, and 2 on a
46
+ * usage or configuration error, which it reports, as the CLI's other commands do (ADR-0076).
47
+ * Vitest's own options (`--reporter`, a file filter) follow `--`.
48
+ */
49
+ async function run(args, io) {
50
+ const parsed = parseTestArguments(args);
51
+ const help = parsed.vitest.some((arg) => arg === "--help" || arg === "-h");
52
+ const { filter, options } = parseCLI(["vitest", ...parsed.vitest]);
53
+ if (help) return 0;
54
+ if (options.update !== void 0 && options.update !== false) throw new Error("Vitest's --update does not update the shared expectations: run unframework test --update.");
55
+ const config = VITEST_CONFIGS.map((name) => join(io.cwd, name)).find((file) => existsSync(file));
56
+ const saved = {
57
+ targets: process.env.UF_TARGETS,
58
+ update: process.env.UF_UPDATE,
59
+ cli: process.env.UF_TEST_CLI
60
+ };
61
+ const exitCode = process.exitCode;
62
+ if (parsed.targets.length) process.env.UF_TARGETS = parsed.targets.join(",");
63
+ else delete process.env.UF_TARGETS;
64
+ if (parsed.update) process.env.UF_UPDATE = "1";
65
+ else delete process.env.UF_UPDATE;
66
+ process.env.UF_TEST_CLI = "1";
67
+ try {
68
+ const inline = config === void 0 ? await defineTestConfig({ root: io.cwd }) : void 0;
69
+ process.exitCode = 0;
70
+ const vitest = await startVitest(filter, {
71
+ ...options,
72
+ root: io.cwd,
73
+ run: true,
74
+ watch: false,
75
+ config: config ?? false
76
+ }, inline);
77
+ return process.exitCode !== 0 || vitest.state.getCountOfFailedTests() > 0 || vitest.state.getUnhandledErrors().length > 0 ? 1 : 0;
78
+ } finally {
79
+ process.exitCode = exitCode;
80
+ restore("UF_TARGETS", saved.targets);
81
+ restore("UF_UPDATE", saved.update);
82
+ restore("UF_TEST_CLI", saved.cli);
83
+ }
84
+ }
85
+ function restore(name, value) {
86
+ if (value === void 0) delete process.env[name];
87
+ else process.env[name] = value;
88
+ }
89
+ //#endregion
90
+ export { parseTestArguments, run };
@@ -0,0 +1,107 @@
1
+ import { ColorScheme } from "./harness.js";
2
+ import { CaptureRequest, CaptureResult } from "./visual-types.js";
3
+ import { MountEvent } from "@unframework.dev/codegen";
4
+ //#region src/commands.d.ts
5
+ /** A shared expectation the browser computed, to settle under the write policy (ADR-0029). */
6
+ export interface ArtefactRequest {
7
+ case: string;
8
+ /** The file name under `__expected__/`, such as `dom.initial.html` or `trace.after-click.json`. */
9
+ file: string;
10
+ /**
11
+ * The file's contents, or `null` where the scenario must have none (a trace without steps): the
12
+ * file must then not exist, and the reference deletes it in update mode.
13
+ */
14
+ contents: string | null;
15
+ }
16
+ /** How an artefact was settled. */
17
+ export interface ArtefactResult {
18
+ pass: boolean;
19
+ /** `matched`, `written`, `missing`, `missing-reference` or `mismatch`. */
20
+ status: string;
21
+ /** Why it failed, with a diff; empty when it passed. */
22
+ message: string;
23
+ }
24
+ /** A Vitest locator as commands receive it. */
25
+ export interface SerializedLocatorLike {
26
+ selector: string;
27
+ locator: string;
28
+ }
29
+ /** Which case's component `ufComponentEvents` describes. */
30
+ export interface ComponentEventsRequest {
31
+ case: string;
32
+ }
33
+ /** The events the component a case's spec mounts declares, from the module the project compiled. */
34
+ export interface ComponentEventsResult {
35
+ events: MountEvent[];
36
+ }
37
+ /**
38
+ * One input of a person's action, which `ufInput` dispatches alone (ADR-0050): the pointer moved
39
+ * onto an element (as Playwright's hover moves it, after its checks), a mouse button's press or
40
+ * release (the `clickCount`-th of a multiple click), a step of the wheel, a key's press or
41
+ * release.
42
+ */
43
+ export type InputRequest = {
44
+ kind: "move";
45
+ locator: SerializedLocatorLike;
46
+ /** The point to move to, from the element's top left corner; its centre by default. */
47
+ position?: {
48
+ x: number;
49
+ y: number;
50
+ };
51
+ /** Whether a click follows, which refuses a disabled element, or only the move. */
52
+ check: "click" | "hover";
53
+ } | {
54
+ kind: "press" | "release";
55
+ clickCount: number;
56
+ } | {
57
+ kind: "wheel";
58
+ deltaX: number;
59
+ deltaY: number;
60
+ } | {
61
+ kind: "keydown" | "keyup";
62
+ key: string;
63
+ text: boolean;
64
+ };
65
+ /** Which case's spec file the calling browser project finished (`ufSpecFinished`, ADR-0091). */
66
+ export interface SpecFinishedRequest {
67
+ case: string;
68
+ }
69
+ /** The stack of the error a case's scripted step threw, as the browser read it (ADR-0078). */
70
+ export interface MapStackRequest {
71
+ case: string;
72
+ stack: string;
73
+ }
74
+ /** What the mapped stack says. */
75
+ export interface MapStackResult {
76
+ /** Why the top frame in the case is not on the authored `throw`; absent when it is. */
77
+ message?: string;
78
+ }
79
+ /** What an input did: a character the keyboard layout lacks is inserted as text, with no key. */
80
+ export interface InputResult {
81
+ inserted: boolean;
82
+ }
83
+ declare module "vitest/browser" {
84
+ interface BrowserCommands {
85
+ /** Settles a shared `__expected__` artefact under the run's write policy. */
86
+ ufArtefact: (request: ArtefactRequest) => Promise<ArtefactResult>;
87
+ /** Playwright's ARIA snapshot of the element a locator points at. */
88
+ ufAriaSnapshot: (locator: SerializedLocatorLike) => Promise<string>;
89
+ /** L10: font audit, stable capture, geometry then pixels, under the write policy. */
90
+ ufVisualCapture: (request: CaptureRequest) => Promise<CaptureResult>;
91
+ /** Moves the focus to the element a locator points at, as Playwright's `focus` does. */
92
+ ufFocus: (locator: SerializedLocatorLike) => Promise<void>;
93
+ /** Dispatches one input of a `view.user` action through Playwright's mouse or keyboard. */
94
+ ufInput: (request: InputRequest) => Promise<InputResult>;
95
+ /** Moves the mouse to the corner of the viewport, off every mount root, between tests. */
96
+ ufResetInput: () => Promise<void>;
97
+ /** Emulates the `prefers-color-scheme` a case opts into, for the page its spec runs in. */
98
+ ufColorScheme: (scheme: ColorScheme) => Promise<void>;
99
+ /** The events a case's component declares, as the project's compile of it says (ADR-0050). */
100
+ ufComponentEvents: (request: ComponentEventsRequest) => Promise<ComponentEventsResult>;
101
+ /** Records that this project finished a case's spec file, which L10's followers read. */
102
+ ufSpecFinished: (request: SpecFinishedRequest) => Promise<void>;
103
+ /** Maps a thrown error's stack through the project's module graph and checks its top frame. */
104
+ ufMapStack: (request: MapStackRequest) => Promise<MapStackResult>;
105
+ }
106
+ }
107
+ //#endregion
@@ -0,0 +1,29 @@
1
+ //#region src/config/broadcast.ts
2
+ /** The plugin's name, which a test finds it by. */
3
+ const NO_ERROR_BROADCAST = "uf-testing:no-error-broadcast";
4
+ /**
5
+ * Keeps a module that fails to compile from failing the specs after it. Its import fails its own
6
+ * spec, and Vite logs the error. Vite also sends it to every page the server serves, whose client
7
+ * puts an overlay over the page: every later spec of the run then clicks in it, and captures it in
8
+ * place of the component, so a case or an example that compiles would fail, or pass with the
9
+ * overlay in its screenshot. `server.hmr.overlay: false` cannot stop it: Vitest sets
10
+ * `server.hmr: false`, and Vite reads `overlay` only from an object.
11
+ */
12
+ function noErrorBroadcast() {
13
+ return {
14
+ name: NO_ERROR_BROADCAST,
15
+ configureServer(server) {
16
+ const hot = server.environments.client.hot;
17
+ const send = hot.send.bind(hot);
18
+ hot.send = (...args) => {
19
+ const [payload] = args;
20
+ if (typeof payload === "object" && payload !== null && "type" in payload) {
21
+ if (payload.type === "error") return;
22
+ }
23
+ Reflect.apply(send, void 0, args);
24
+ };
25
+ }
26
+ };
27
+ }
28
+ //#endregion
29
+ export { NO_ERROR_BROADCAST, noErrorBroadcast };
@@ -0,0 +1,28 @@
1
+ import { CaseConfig } from "../harness.js";
2
+ //#region src/config/cases.d.ts
3
+ /** One case of a project. */
4
+ export interface ProjectCase {
5
+ /** The directory relative to the project's root, with forward slashes. */
6
+ id: string;
7
+ /** The case's directory (absolute). */
8
+ dir: string;
9
+ /** The test file (absolute). */
10
+ spec: string;
11
+ /** The main `.uf.tsx` source (absolute). */
12
+ source: string;
13
+ config: CaseConfig;
14
+ }
15
+ /** What {@link discoverCases} reads. */
16
+ export interface DiscoverOptions {
17
+ /** The project's root (absolute): case ids are relative to it. */
18
+ root: string;
19
+ /** Globs of test files, relative to the root. */
20
+ include: readonly string[];
21
+ }
22
+ /**
23
+ * Every case under the root, sorted by id. Throws, naming the fix, on a directory with two test
24
+ * files, a case with no main source, a test file at the root itself and a malformed `case.json`:
25
+ * a case that cannot be told apart would have nowhere to go in the run.
26
+ */
27
+ export declare function discoverCases(options: DiscoverOptions): ProjectCase[];
28
+ //#endregion
@@ -0,0 +1,94 @@
1
+ import { COLOR_SCHEMES } from "../harness.js";
2
+ import { KEBAB_CASE } from "../node/names.js";
3
+ import { existsSync, globSync, readFileSync, readdirSync } from "node:fs";
4
+ import { dirname, join, relative, resolve, sep } from "node:path";
5
+ import { TARGET_NAMES } from "@unframework.dev/compiler";
6
+ //#region src/config/cases.ts
7
+ /** What a test file never lies in: installed packages and build output. */
8
+ const EXCLUDED = ["**/node_modules/**", "**/dist/**"];
9
+ /** The keys of a project's `case.json`: the public ones (ADR-0085). */
10
+ const CASE_KEYS = /* @__PURE__ */ new Set([
11
+ "description",
12
+ "main",
13
+ "ssr",
14
+ "axe",
15
+ "colorScheme",
16
+ "reference"
17
+ ]);
18
+ /**
19
+ * Every case under the root, sorted by id. Throws, naming the fix, on a directory with two test
20
+ * files, a case with no main source, a test file at the root itself and a malformed `case.json`:
21
+ * a case that cannot be told apart would have nowhere to go in the run.
22
+ */
23
+ function discoverCases(options) {
24
+ const files = globSync([...options.include], {
25
+ cwd: options.root,
26
+ exclude: [...EXCLUDED]
27
+ }).toSorted();
28
+ const byDirectory = /* @__PURE__ */ new Map();
29
+ for (const file of files) {
30
+ const absolute = resolve(options.root, file);
31
+ const directory = dirname(absolute);
32
+ byDirectory.set(directory, [...byDirectory.get(directory) ?? [], absolute]);
33
+ }
34
+ const cases = [];
35
+ for (const [dir, specs] of byDirectory) {
36
+ const id = relative(options.root, dir).split(sep).join("/");
37
+ if (!id) throw new Error(`[uf] ${relative(options.root, specs[0])} is at the project's root: a case is a directory, so move the test file into a directory of its own, such as test/<name>/.`);
38
+ if (specs.length > 1) throw new Error(`[uf] Case ${id} holds ${specs.length} test files (${specs.map((spec) => relative(dir, spec)).join(", ")}): a case is a directory with one test file, so give each its own directory.`);
39
+ const config = readCaseConfig(id, join(dir, "case.json"));
40
+ cases.push({
41
+ id,
42
+ dir,
43
+ spec: specs[0],
44
+ source: mainSource(id, dir, config.main),
45
+ config
46
+ });
47
+ }
48
+ return cases.toSorted((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
49
+ }
50
+ /**
51
+ * A case's main source: `main`, relative to the case's directory, or the directory's only
52
+ * `.uf.tsx`.
53
+ */
54
+ function mainSource(id, dir, main) {
55
+ if (main !== void 0) {
56
+ const source = resolve(dir, main);
57
+ if (!main.endsWith(".uf.tsx") || !existsSync(source)) throw new Error(`[uf] Case ${id}: case.json's "main" names ${JSON.stringify(main)}, which is no .uf.tsx file relative to the case's directory. Point it at the component the test mounts, such as "../../src/Button.uf.tsx".`);
58
+ return source;
59
+ }
60
+ const inputs = readdirSync(dir).filter((file) => file.endsWith(".uf.tsx"));
61
+ if (inputs.length === 1) return join(dir, inputs[0]);
62
+ throw new Error(inputs.length ? `[uf] Case ${id} holds ${inputs.join(", ")}: name the one the test mounts in case.json, "main": "${inputs[0]}".` : `[uf] Case ${id} has no main source: add a .uf.tsx beside its test, or name the component in case.json, "main": "../../src/Button.uf.tsx".`);
63
+ }
64
+ /** A case's `case.json`, checked: `{}` when it has none. */
65
+ function readCaseConfig(id, file) {
66
+ if (!existsSync(file)) return {};
67
+ let config;
68
+ try {
69
+ config = JSON.parse(readFileSync(file, "utf8"));
70
+ } catch (error) {
71
+ throw new Error(`[uf] Case ${id}: case.json is not JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
72
+ }
73
+ if (typeof config !== "object" || config === null || Array.isArray(config)) throw new Error(`[uf] Case ${id}: case.json must hold an object.`);
74
+ const record = config;
75
+ const problems = [];
76
+ for (const key of Object.keys(record)) if (!CASE_KEYS.has(key)) problems.push(`unknown key "${key}" (it takes ${[...CASE_KEYS].join(", ")})`);
77
+ if (record.description !== void 0 && typeof record.description !== "string") problems.push(`"description" must be a string`);
78
+ if (record.main !== void 0 && typeof record.main !== "string") problems.push(`"main" must be the path of a .uf.tsx file, relative to the case`);
79
+ if (record.reference !== void 0 && !TARGET_NAMES.includes(record.reference)) problems.push(`"reference" must name a target: ${TARGET_NAMES.join(", ")}`);
80
+ if (record.colorScheme !== void 0 && !COLOR_SCHEMES.includes(record.colorScheme)) problems.push(`"colorScheme" must be one of ${COLOR_SCHEMES.map((s) => `"${s}"`).join(", ")}`);
81
+ if (record.axe !== void 0 && (!Array.isArray(record.axe) || record.axe.some((rule) => typeof rule !== "string"))) problems.push(`"axe" must be a list of axe rule ids`);
82
+ if (record.ssr !== void 0) {
83
+ if (typeof record.ssr !== "object" || record.ssr === null || Array.isArray(record.ssr)) problems.push(`"ssr" must map scenario names to { "props": {…} }`);
84
+ else for (const [scenario, value] of Object.entries(record.ssr)) {
85
+ if (!KEBAB_CASE.test(scenario)) problems.push(`SSR scenario "${scenario}", which is not kebab-case`);
86
+ const props = value?.props;
87
+ if (typeof value !== "object" || value === null || Array.isArray(value) || props !== void 0 && (typeof props !== "object" || props === null || Array.isArray(props))) problems.push(`SSR scenario "${scenario}" must be { "props": {…} }`);
88
+ }
89
+ }
90
+ if (problems.length) throw new Error(`[uf] Case ${id}: case.json has ${problems.join("; ")}.`);
91
+ return record;
92
+ }
93
+ //#endregion
94
+ export { EXCLUDED, discoverCases, readCaseConfig };
@@ -0,0 +1,81 @@
1
+ import { PixelMode } from "../harness.js";
2
+ import { DiscoverOptions, ProjectCase, discoverCases } from "./cases.js";
3
+ import { TargetName } from "@unframework.dev/compiler";
4
+ import { ViteUserConfig } from "vitest/config";
5
+ import { Toolchain } from "@unframework.dev/codegen";
6
+ //#region src/config/index.d.ts
7
+ /** The options of {@link defineTestConfig}. */
8
+ export interface TestConfigOptions {
9
+ /** The targets to test: `unframework.config.ts`'s `targets` by default. */
10
+ targets?: readonly TargetName[];
11
+ /** Globs of test files, relative to the root: `["**\/*.test.ts"]` by default. */
12
+ include?: readonly string[];
13
+ /**
14
+ * The target that writes the shared expectations, which every other target must match: `vue`
15
+ * when the project tests it, the first target otherwise. It always joins the run.
16
+ */
17
+ reference?: TargetName;
18
+ /**
19
+ * What pixels compare with: `live`, every target against the reference's capture in the same
20
+ * run, by default, in CI too; or `baseline`, committed baselines, which only the baseline image
21
+ * writes.
22
+ */
23
+ pixels?: PixelMode;
24
+ /**
25
+ * Where a target's compiler stack resolves from, such as Angular's: `package.resolveFrom` in
26
+ * `unframework.config.ts` by default, then the root.
27
+ */
28
+ toolchainDirs?: Partial<Record<TargetName, string>>;
29
+ /** The project's root, where `unframework.config.ts` lies: the working directory by default. */
30
+ root?: string;
31
+ }
32
+ /** The test files a project's run finds by default. */
33
+ export declare const DEFAULT_INCLUDE: readonly string[];
34
+ /**
35
+ * This package's modules, wherever a project installs it: the server render comparison imports
36
+ * each case's main source, which must go through the project's Vite pipeline.
37
+ */
38
+ export declare const TESTING_PACKAGE: RegExp;
39
+ /**
40
+ * The target packages' modules, wherever a project installs them: a server renderer imports its
41
+ * framework, which must be the copy the component the project's Vite pipeline compiles imports.
42
+ */
43
+ export declare const TARGET_PACKAGES: RegExp;
44
+ /**
45
+ * The Vitest configuration of a project's tests: one `browser:<target>` project in Chromium and
46
+ * one `ssr:<target>` project per target, with the reference ordered first. `UF_TARGETS` narrows
47
+ * the targets (`unframework test --target`), and `UF_UPDATE=1` writes the expectations
48
+ * (`--update`). Throws, naming the fix, on an invalid configuration, an unknown target, a case it
49
+ * cannot tell apart and a toolchain that cannot load: a check that cannot start fails.
50
+ */
51
+ export declare function defineTestConfig(options?: TestConfigOptions): Promise<ViteUserConfig>;
52
+ /**
53
+ * The targets `UF_TARGETS` selects (`unframework test --target`), every one of the project's when
54
+ * it is unset. A name outside the project's targets throws, so a typo never tests nothing.
55
+ */
56
+ export declare function selectedTargets(value: string | undefined, targets: readonly TargetName[]): TargetName[];
57
+ /**
58
+ * The targets a run tests, in the project's order: the selected ones, and the reference and every
59
+ * target a case names as its own, which write the expectations and the live captures the others
60
+ * compare with (ADR-0057), so they always join.
61
+ */
62
+ export declare function runTargets(targets: readonly TargetName[], selected: readonly TargetName[], writers: readonly TargetName[]): TargetName[];
63
+ /**
64
+ * Where a target's compiler stack resolves from: `toolchainDirs`, relative to the root, then
65
+ * `package.resolveFrom`, which `resolveConfig` has made absolute, then the root (A9).
66
+ */
67
+ export declare function toolchainDirOf(target: TargetName, root: string, toolchainDirs: TestConfigOptions["toolchainDirs"], resolveFrom: string | Partial<Record<TargetName, string>> | undefined): string;
68
+ /**
69
+ * Loads a target's toolchain, refusing one of another name. It loads from this package, which
70
+ * depends on every target, so a project need not install the target packages itself: the
71
+ * preview (`@unframework.dev/visual`) builds its servers from it too.
72
+ */
73
+ export declare function loadToolchain(target: TargetName): Promise<Toolchain>;
74
+ /**
75
+ * The file of a toolchain's browser mount adapter (`toolchain.client`), resolved from this
76
+ * package, which depends on the target: a Vite server outside the test projects imports it by
77
+ * path, since the project need not install the target package (pnpm keeps it out of reach).
78
+ */
79
+ export declare function toolchainClientFile(toolchain: Toolchain): string;
80
+ //#endregion
81
+ export { type DiscoverOptions, type ProjectCase, discoverCases };