@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
@@ -0,0 +1,140 @@
1
+ import { diffLines } from "../diff.js";
2
+ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, rmdirSync, statSync, writeFileSync } from "node:fs";
3
+ import { dirname, isAbsolute, join, relative, sep } from "node:path";
4
+ //#region src/node/policy.ts
5
+ /** The corpus's command that writes the artefacts. */
6
+ const CORPUS_UPDATE = "pnpm test:update";
7
+ const updateHint = (command = CORPUS_UPDATE) => `Run \`${command}\` and review the diff if the change is intended.`;
8
+ /**
9
+ * Settles one artefact. `actual` is what this run produced; `undefined` means the artefact must
10
+ * not exist (an IR snapshot for a case with compile errors, a stale diagnostics.txt).
11
+ */
12
+ function settleArtefact(path, actual, context) {
13
+ const rel = display(path, context.root);
14
+ if (!isAbsolute(path)) throw new Error(`An artefact path must be absolute: ${path}`);
15
+ if (context.update && context.role !== "follower") {
16
+ if (actual === void 0) {
17
+ if (existsSync(path)) rmSync(path);
18
+ } else writeIfChanged(path, actual);
19
+ if (context.role === "reference") recordInLedger(path, context);
20
+ return {
21
+ pass: true,
22
+ status: "written",
23
+ message: ""
24
+ };
25
+ }
26
+ if (context.update && !ledgerHas(path, context)) return {
27
+ pass: false,
28
+ status: "missing-reference",
29
+ message: `The reference target (${context.reference ?? "unknown"}) did not write ${rel} earlier in this run. In update mode the reference runs first (sequence.groupOrder) and must not be filtered out with --project.`
30
+ };
31
+ const exists = existsSync(path);
32
+ if (actual === void 0) return exists ? {
33
+ pass: false,
34
+ status: "stale",
35
+ message: `Stale artefact ${rel}: this run no longer produces it. Run \`${context.updateCommand ?? CORPUS_UPDATE}\` to delete it.`
36
+ } : {
37
+ pass: true,
38
+ status: "matched",
39
+ message: ""
40
+ };
41
+ if (!exists) {
42
+ const writer = context.role === "follower" ? ` (the reference target, ${context.reference ?? "unknown"}, writes it)` : "";
43
+ return {
44
+ pass: false,
45
+ status: "missing",
46
+ message: `Missing artefact ${rel}. Run \`${context.updateCommand ?? CORPUS_UPDATE}\` to write it${writer}.`
47
+ };
48
+ }
49
+ const expected = readFileSync(path, "utf8");
50
+ if (expected === actual) return {
51
+ pass: true,
52
+ status: "matched",
53
+ message: ""
54
+ };
55
+ return {
56
+ pass: false,
57
+ status: "mismatch",
58
+ message: `${context.update ? `${rel}, as the reference wrote it in this run,` : rel} differs from this run's output:\n${diffLines(expected, actual)}\n${context.update ? "" : updateHint(context.updateCommand)}`.trimEnd()
59
+ };
60
+ }
61
+ /**
62
+ * Settles a directory that holds exactly a set of files (a target's golden outputs): no missing
63
+ * file, no stale file, every file equal. In update mode it writes the files and deletes the
64
+ * stale ones. Owners only: shared expectations are single files.
65
+ */
66
+ function settleArtefactDirectory(directory, files, context) {
67
+ const stale = (existsSync(directory) ? listFiles(directory) : []).filter((file) => !files.has(file));
68
+ if (context.update) {
69
+ for (const file of stale) rmSync(join(directory, file));
70
+ for (const [file, contents] of files) writeIfChanged(join(directory, file), contents);
71
+ removeEmptyDirectories(directory);
72
+ return {
73
+ pass: true,
74
+ status: "written",
75
+ message: ""
76
+ };
77
+ }
78
+ const problems = [];
79
+ for (const file of stale) problems.push(`Stale artefact ${display(join(directory, file), context.root)}: this run no longer produces it.`);
80
+ for (const [file, contents] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
81
+ const outcome = settleArtefact(join(directory, file), contents, {
82
+ role: "owner",
83
+ update: false,
84
+ root: context.root
85
+ });
86
+ if (!outcome.pass) problems.push(outcome.message);
87
+ }
88
+ if (!problems.length) return {
89
+ pass: true,
90
+ status: "matched",
91
+ message: ""
92
+ };
93
+ return {
94
+ pass: false,
95
+ status: problems.every((problem) => problem.startsWith("Missing")) ? "missing" : "mismatch",
96
+ message: `${problems.join("\n\n")}\n${updateHint()}`
97
+ };
98
+ }
99
+ /** Writes a file only when its contents change, so update runs leave mtimes alone. */
100
+ function writeIfChanged(path, contents) {
101
+ if (existsSync(path)) {
102
+ const current = readFileSync(path);
103
+ const next = typeof contents === "string" ? Buffer.from(contents) : Buffer.from(contents);
104
+ if (current.equals(next)) return false;
105
+ }
106
+ mkdirSync(dirname(path), { recursive: true });
107
+ writeFileSync(path, contents);
108
+ return true;
109
+ }
110
+ function ledgerEntry(path, context) {
111
+ if (!context.ledgerDir) throw new Error("Update mode needs the run's ledger directory to coordinate the reference and its followers.");
112
+ const rel = relative(context.root, path);
113
+ if (rel.startsWith("..") || isAbsolute(rel)) throw new Error(`The artefact ${path} is outside the harness root ${context.root}.`);
114
+ return join(context.ledgerDir, rel);
115
+ }
116
+ function recordInLedger(path, context) {
117
+ const entry = ledgerEntry(path, context);
118
+ mkdirSync(dirname(entry), { recursive: true });
119
+ writeFileSync(entry, "");
120
+ }
121
+ function ledgerHas(path, context) {
122
+ return existsSync(ledgerEntry(path, context));
123
+ }
124
+ /** Every file under a directory, as relative paths with forward slashes, sorted. */
125
+ function listFiles(directory) {
126
+ return readdirSync(directory, { recursive: true }).filter((entry) => statSync(join(directory, entry)).isFile()).map((entry) => entry.split(sep).join("/")).sort();
127
+ }
128
+ function removeEmptyDirectories(directory) {
129
+ if (!existsSync(directory)) return;
130
+ for (const entry of readdirSync(directory)) {
131
+ const path = join(directory, entry);
132
+ if (statSync(path).isDirectory()) removeEmptyDirectories(path);
133
+ }
134
+ if (!readdirSync(directory).length) rmdirSync(directory);
135
+ }
136
+ function display(path, root) {
137
+ return relative(root, path).split(sep).join("/");
138
+ }
139
+ //#endregion
140
+ export { settleArtefact, settleArtefactDirectory, writeIfChanged };
@@ -0,0 +1,101 @@
1
+ import { UfLayerMeta } from "../layers.js";
2
+ import { HarnessContext } from "../harness.js";
3
+ import { PartialMatrix } from "./matrix.js";
4
+ //#region src/node/reporter.d.ts
5
+ /** The part of a Vitest test case the reporter reads. */
6
+ interface ReportedTest {
7
+ project: {
8
+ name: string;
9
+ };
10
+ fullName: string;
11
+ meta(): {
12
+ uf?: UfLayerMeta;
13
+ };
14
+ result(): {
15
+ state: "passed" | "failed" | "skipped" | "pending";
16
+ };
17
+ }
18
+ /** The part of a Vitest test module the reporter reads. */
19
+ interface ReportedModule {
20
+ project: {
21
+ name: string;
22
+ };
23
+ meta(): {
24
+ uf?: UfLayerMeta;
25
+ };
26
+ children: {
27
+ allTests(): Iterable<ReportedTest>;
28
+ };
29
+ }
30
+ /** The part of a Vitest project the reporter reads. */
31
+ interface ReportedProject {
32
+ name: string;
33
+ config: {
34
+ root: string;
35
+ include: string[];
36
+ };
37
+ getProvidedContext(): {
38
+ ufHarness?: HarnessContext;
39
+ ufOnly?: string[];
40
+ };
41
+ }
42
+ /** The part of the Vitest instance the reporter reads. */
43
+ interface ReportedVitest {
44
+ projects: readonly ReportedProject[];
45
+ config: {
46
+ testNamePattern?: RegExp | undefined;
47
+ shard?: {
48
+ index: number;
49
+ count: number;
50
+ } | undefined;
51
+ watch?: boolean;
52
+ /** `--changed [since]`. */
53
+ changed?: boolean | string | undefined;
54
+ /** `vitest related <files>`, and the files `--changed` found. */
55
+ related?: readonly string[] | undefined;
56
+ /** `--tags-filter`. */
57
+ tagsFilter?: readonly string[] | undefined;
58
+ };
59
+ logger: {
60
+ log(...messages: unknown[]): void;
61
+ error(...messages: unknown[]): void;
62
+ };
63
+ /** Internal: the CLI's file filters. */
64
+ filenamePattern?: readonly string[] | undefined;
65
+ }
66
+ /** Options for {@link ParityReporter}. */
67
+ export interface ParityReporterOptions {
68
+ /** Where partial matrices go: `parity-matrix.<run>.json`. */
69
+ reportsDir: string;
70
+ /** Every project the config defines; a run of all of them is named `all`, and is complete. */
71
+ allProjects?: readonly string[];
72
+ /**
73
+ * A canary run's directory: its matrix goes to `<canaryDir>/parity-matrix.json`, where the
74
+ * canary runner reads it, and it supersedes no partial matrix.
75
+ */
76
+ canaryDir?: string;
77
+ }
78
+ /** The parity reporter. Add it to `test.reporters` next to Vitest's own. */
79
+ export declare class ParityReporter {
80
+ #private;
81
+ /** The matrix of the last finished run, for tooling and tests. */
82
+ matrix: PartialMatrix | undefined;
83
+ constructor(options: ParityReporterOptions);
84
+ onInit(vitest: ReportedVitest): void;
85
+ onTestRunEnd(testModules: readonly ReportedModule[], errors: readonly unknown[], reason: string): void;
86
+ }
87
+ /**
88
+ * A test's name without the target `describeTargets` puts in its suite's name (`state/counter
89
+ * [vue] > increments` → `state/counter > increments`): the same on every target.
90
+ */
91
+ export declare function testKey(fullName: string, target: string): string;
92
+ /** A file-name-safe name for the selected projects: `all`, or the project names. */
93
+ export declare function runName(projects: readonly string[], allProjects?: readonly string[]): string;
94
+ /**
95
+ * Whether a file name is a partial matrix's, `parity-matrix.<run>.json`. An engine's merged
96
+ * matrix, `parity-matrix.<engine>.json` (ADR-0066), is not: no run is named after an engine.
97
+ */
98
+ export declare function isPartialMatrixFile(name: string): boolean;
99
+ /** The partial matrices in a directory, by file. Throws on one that is not a current matrix. */
100
+ export declare function readPartialMatrices(reportsDir: string): Map<string, PartialMatrix>;
101
+ //#endregion
@@ -0,0 +1,251 @@
1
+ import { BROWSER_ENGINES, caseOfFile } from "../harness.js";
2
+ import { errorMessages } from "../errors.js";
3
+ import { buildPartialMatrix, narrowing, settleQuarantine, stringifyMatrix, withoutProjects } from "./matrix.js";
4
+ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
5
+ import { join, resolve } from "node:path";
6
+ //#region src/node/reporter.ts
7
+ /** The parity reporter. Add it to `test.reporters` next to Vitest's own. */
8
+ var ParityReporter = class {
9
+ #options;
10
+ #vitest;
11
+ /** The matrix of the last finished run, for tooling and tests. */
12
+ matrix;
13
+ constructor(options) {
14
+ this.#options = options;
15
+ }
16
+ onInit(vitest) {
17
+ this.#vitest = vitest;
18
+ }
19
+ onTestRunEnd(testModules, errors, reason) {
20
+ const vitest = this.#vitest;
21
+ if (!vitest) throw new Error("[uf:parity] onTestRunEnd ran before onInit.");
22
+ if (reason === "interrupted") {
23
+ vitest.logger.error("[uf:parity] The run was interrupted: no parity matrix written.");
24
+ return;
25
+ }
26
+ const projects = [...new Set(vitest.projects.map((project) => project.name))].sort();
27
+ const harness = vitest.projects.map((project) => project.getProvidedContext().ufHarness).find((context) => context !== void 0);
28
+ const filtered = filterOf(vitest);
29
+ const shard = vitest.config.shard ? {
30
+ index: vitest.config.shard.index,
31
+ count: vitest.config.shard.count
32
+ } : null;
33
+ const narrowed = narrowing({
34
+ filtered,
35
+ shard
36
+ });
37
+ const problems = [];
38
+ const counts = new Map(projects.map((name) => [name, 0]));
39
+ const records = [];
40
+ const named = /* @__PURE__ */ new Set();
41
+ for (const module of testModules) {
42
+ const fileRecord = module.meta().uf;
43
+ if (fileRecord) records.push({
44
+ project: module.project.name,
45
+ record: fileRecord
46
+ });
47
+ for (const test of module.children.allTests()) {
48
+ counts.set(test.project.name, (counts.get(test.project.name) ?? 0) + 1);
49
+ const meta = test.meta().uf;
50
+ const record = meta && {
51
+ ...meta,
52
+ test: testKey(test.fullName, meta.target)
53
+ };
54
+ if (record) {
55
+ records.push({
56
+ project: test.project.name,
57
+ record
58
+ });
59
+ const identity = JSON.stringify([
60
+ test.project.name,
61
+ record.case,
62
+ record.test
63
+ ]);
64
+ if (named.has(identity)) problems.push(`${test.project.name}: two tests of ${record.case} are named "${record.test}". Each test of a case has a name of its own: the summary compares each target's tests with the reference's by name.`);
65
+ named.add(identity);
66
+ }
67
+ if (!filtered && test.result().state === "skipped" && !skipsWithReasons(record)) problems.push(`${test.project.name}: "${test.fullName}" was skipped without recording why. A harness test never skips silently (plan §7.7): record each layer it skips, with the reason, before skipping.`);
68
+ }
69
+ }
70
+ const empty = projects.filter((name) => !counts.get(name));
71
+ if (empty.length) {
72
+ if (narrowed) vitest.logger.log(`[uf:parity] Not checking for empty projects: the run covers only ${narrowed}. Empty: ${empty.join(", ")}.`);
73
+ else problems.push(`${empty.length} selected project(s) collected zero tests: ${empty.join(", ")}. A project that runs nothing verifies nothing.`);
74
+ }
75
+ const all = runName(projects, this.#options.allProjects);
76
+ const complete = !narrowed && all === "all" && this.#options.allProjects !== void 0;
77
+ const matrix = buildPartialMatrix({
78
+ run: [
79
+ all,
80
+ ...shard ? [`shard-${shard.index}-of-${shard.count}`] : [],
81
+ ...filtered ? [`filtered-${hash(filtered)}`] : []
82
+ ].join("+"),
83
+ projects,
84
+ records,
85
+ finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
86
+ mode: harness ? {
87
+ update: harness.update,
88
+ pixels: harness.pixels,
89
+ canary: harness.canary
90
+ } : null,
91
+ filtered,
92
+ shard,
93
+ empty,
94
+ quarantine: harness?.quarantine ?? [],
95
+ reference: harness?.reference ?? null,
96
+ references: Object.fromEntries(Object.entries(harness?.cases ?? {}).flatMap(([id, config]) => config.reference ? [[id, config.reference]] : [])),
97
+ errors: [...new Set(errors.map((error) => errorMessages(error).join("; caused by: ")))]
98
+ });
99
+ if (complete) problems.push(...settleQuarantine(matrix.cases, matrix.quarantine, { stale: true }));
100
+ else if (matrix.quarantine.length) vitest.logger.log("[uf:parity] Quarantine entries are checked for staleness when every project runs (or in the merged summary).");
101
+ this.matrix = matrix;
102
+ if (this.#options.canaryDir) {
103
+ mkdirSync(this.#options.canaryDir, { recursive: true });
104
+ writeFileSync(join(this.#options.canaryDir, "parity-matrix.json"), stringifyMatrix(matrix));
105
+ } else {
106
+ mkdirSync(this.#options.reportsDir, { recursive: true });
107
+ const file = join(this.#options.reportsDir, `parity-matrix.${matrix.run}.json`);
108
+ writeFileSync(file, stringifyMatrix(matrix));
109
+ if (!narrowed) {
110
+ const scopes = scopesOf(vitest.projects, records, harness);
111
+ for (const line of supersede(this.#options.reportsDir, file, new Set(projects), scopes)) vitest.logger.log(`[uf:parity] ${line}`);
112
+ }
113
+ vitest.logger.log(`[uf:parity] ${records.length} record(s) from ${projects.length} project(s) → ${file}`);
114
+ }
115
+ if (problems.length) {
116
+ vitest.logger.error(`[uf:parity] ${problems.length} problem(s) beyond the failed tests:\n ${problems.join("\n ")}`);
117
+ process.exitCode = 1;
118
+ }
119
+ }
120
+ };
121
+ /**
122
+ * Why a run covers only part of its projects' tests besides its shard, or `null`. Such a run,
123
+ * like a shard, cannot tell an empty project or a stale entry from a filtered one, and
124
+ * supersedes nothing; unlike a shard's, its skipped tests may be ones it filtered out.
125
+ */
126
+ function filterOf(vitest) {
127
+ const reasons = [];
128
+ if (vitest.filenamePattern?.length) reasons.push(`files matching ${vitest.filenamePattern.join(", ")}`);
129
+ if (vitest.config.testNamePattern) reasons.push(`tests named ${vitest.config.testNamePattern}`);
130
+ const { changed, related, tagsFilter } = vitest.config;
131
+ if (changed) reasons.push(`files affected by ${changed === true ? "uncommitted changes" : `changes since ${changed}`}`);
132
+ else if (related?.length) reasons.push(`tests related to ${related.join(", ")}`);
133
+ if (tagsFilter?.length) reasons.push(`tests tagged ${tagsFilter.join(" ")}`);
134
+ if (vitest.config.watch) reasons.push("watch mode, which reruns only what changed");
135
+ return reasons.length ? reasons.join("; ") : null;
136
+ }
137
+ /**
138
+ * A test's name without the target `describeTargets` puts in its suite's name (`state/counter
139
+ * [vue] > increments` → `state/counter > increments`): the same on every target.
140
+ */
141
+ function testKey(fullName, target) {
142
+ const suffix = ` [${target}]`;
143
+ return fullName.split(" > ").map((part) => part.endsWith(suffix) ? part.slice(0, -suffix.length) : part).join(" > ");
144
+ }
145
+ /** Whether a skipped test recorded every layer it skipped, each with a reason. */
146
+ function skipsWithReasons(record) {
147
+ const outcomes = Object.values(record?.layers ?? {});
148
+ return outcomes.length > 0 && outcomes.every((outcome) => outcome.status === "skip");
149
+ }
150
+ /** A file-name-safe name for the selected projects: `all`, or the project names. */
151
+ function runName(projects, allProjects) {
152
+ const selected = [...new Set(projects)].sort();
153
+ if (allProjects && [...new Set(allProjects)].sort().join("\n") === selected.join("\n")) return "all";
154
+ const joined = selected.map((name) => name.replace(/[^a-zA-Z0-9-]+/g, "-")).join("+");
155
+ if (joined.length <= 80) return joined || "none";
156
+ return `${joined.slice(0, 60)}+${hash(joined)}`;
157
+ }
158
+ function hash(text) {
159
+ let value = 0;
160
+ for (const char of text) value = Math.imul(value, 31) + char.charCodeAt(0) >>> 0;
161
+ return value.toString(36);
162
+ }
163
+ /**
164
+ * Whether a file name is a partial matrix's, `parity-matrix.<run>.json`. An engine's merged
165
+ * matrix, `parity-matrix.<engine>.json` (ADR-0066), is not: no run is named after an engine.
166
+ */
167
+ function isPartialMatrixFile(name) {
168
+ const run = /^parity-matrix\.(.+)\.json$/.exec(name)?.[1];
169
+ return run !== void 0 && !BROWSER_ENGINES.includes(run);
170
+ }
171
+ /** The partial matrices in a directory, by file. Throws on one that is not a current matrix. */
172
+ function readPartialMatrices(reportsDir) {
173
+ const matrices = /* @__PURE__ */ new Map();
174
+ if (!existsSync(reportsDir)) return matrices;
175
+ for (const name of readdirSync(reportsDir).sort()) {
176
+ if (!isPartialMatrixFile(name)) continue;
177
+ const file = join(reportsDir, name);
178
+ const matrix = JSON.parse(readFileSync(file, "utf8"));
179
+ if (matrix.version !== 5 || !matrix.byProject) throw new Error(`[uf] ${file} is a parity matrix of version ${String(matrix.version)}, not 5: rerun the tests to replace it.`);
180
+ matrices.set(file, matrix);
181
+ }
182
+ return matrices;
183
+ }
184
+ /**
185
+ * What this run re-judged of each project it ran: the targets it recorded there, as a run of
186
+ * some targets (`UF_TARGETS`) records only theirs, and only some cases where the run added the
187
+ * project for the cases that name its target as their own reference (ADR-0057). The SSR
188
+ * project is told those cases (`ufOnly`), and the browser project includes their specs alone.
189
+ * Both come from the project itself, so they hold when a spec failed to load and the project
190
+ * recorded nothing, whichever other projects the run selected. A project that recorded nothing
191
+ * and names no cases re-judged all of it.
192
+ */
193
+ function scopesOf(projects, records, harness) {
194
+ const scopes = /* @__PURE__ */ new Map();
195
+ for (const project of projects) {
196
+ const targets = new Set(records.filter((entry) => entry.project === project.name).map((entry) => entry.record.target));
197
+ const cases = project.getProvidedContext().ufOnly ?? includedCases(project, harness);
198
+ scopes.set(project.name, {
199
+ ...targets.size ? { targets } : {},
200
+ ...cases ? { cases: new Set(cases) } : {}
201
+ });
202
+ }
203
+ return scopes;
204
+ }
205
+ /**
206
+ * The cases whose specs a project includes file by file, or none when it includes a pattern or a
207
+ * file outside every case: the harness lists the specs of a browser project it adds for some
208
+ * cases alone, and gives every other project a pattern or a harness file.
209
+ */
210
+ function includedCases(project, harness) {
211
+ const { root, include } = project.config;
212
+ if (!harness || !include.length || include.some((entry) => /[*?[\]{}!]/.test(entry))) return;
213
+ try {
214
+ return include.map((entry) => caseOfFile(resolve(root, entry), harness));
215
+ } catch {
216
+ return;
217
+ }
218
+ }
219
+ /**
220
+ * Removes the records this run re-judged from every other partial matrix: those of the projects
221
+ * it ran, within each one's scope (see `scopesOf`). They are stale, also the cells this run no
222
+ * longer records. A matrix left without projects is deleted; one of another version is deleted
223
+ * too, as nothing can merge it. Returns what it did.
224
+ */
225
+ function supersede(reportsDir, written, projects, scopes) {
226
+ const done = [];
227
+ for (const name of readdirSync(reportsDir).sort()) {
228
+ if (!isPartialMatrixFile(name)) continue;
229
+ const file = join(reportsDir, name);
230
+ if (file === written) continue;
231
+ const matrix = JSON.parse(readFileSync(file, "utf8"));
232
+ if (matrix.version !== 5 || !matrix.byProject) {
233
+ rmSync(file);
234
+ done.push(`Removed ${name}: a matrix of an older format.`);
235
+ continue;
236
+ }
237
+ const kept = withoutProjects(matrix, projects, scopes);
238
+ if (kept === matrix) continue;
239
+ if (kept) {
240
+ writeFileSync(file, stringifyMatrix(kept));
241
+ const superseded = matrix.projects.filter((project) => !kept.projects.includes(project) || kept.byProject[project] !== matrix.byProject[project] || kept.scenariosByProject[project] !== matrix.scenariosByProject[project] || kept.testsByProject[project] !== matrix.testsByProject[project]);
242
+ done.push(`Superseded ${superseded.length} project(s) of ${name}.`);
243
+ } else {
244
+ rmSync(file);
245
+ done.push(`Superseded ${name}.`);
246
+ }
247
+ }
248
+ return done;
249
+ }
250
+ //#endregion
251
+ export { ParityReporter, isPartialMatrixFile, readPartialMatrices, runName, testKey };
@@ -0,0 +1,99 @@
1
+ import { LayerName } from "../layers.js";
2
+ import { BrowserEngine } from "../harness.js";
3
+ import { MergedMatrix, PartialMatrix } from "./matrix.js";
4
+ //#region src/node/summary.d.ts
5
+ /** What a complete run covers. */
6
+ export interface SummaryExpectations {
7
+ /** Every project the config defines (for the selected targets). */
8
+ projects: readonly string[];
9
+ /** Every case id in the corpus. */
10
+ cases: readonly string[];
11
+ targets: readonly string[];
12
+ /** The layers live in this milestone: each needs a cell for every case and target. */
13
+ liveLayers: readonly LayerName[];
14
+ /** The skip reason recorded for the layers that are not live yet. */
15
+ notLiveReason: string;
16
+ /**
17
+ * A live layer only one project records, which the default run leaves out (L15, `bench`): a
18
+ * run without that project in full fills its cells as skipped, never missing. CI's parity job
19
+ * (`requireComplete`) requires them all the same.
20
+ */
21
+ recordedOnlyBy?: Partial<Record<LayerName, string>>;
22
+ /**
23
+ * Every capability name: a skip by capability on a live layer (`requires <name>: …`) must
24
+ * name one. Without it, any kebab-case name passes.
25
+ */
26
+ capabilities?: readonly string[];
27
+ }
28
+ /** Why a live layer's skip is not one the summary accepts, or nothing when it is. */
29
+ export declare function unacceptedSkip(reason: string, capabilities?: readonly string[]): string | undefined;
30
+ /** How to judge the merged matrix. */
31
+ export interface SummaryJudgement {
32
+ /**
33
+ * Every expected project must have run all its tests: a missing one, one that only a filtered
34
+ * run covered, and each missing cell, is a problem rather than a partial run. For CI, whose
35
+ * parity job merges one partial matrix per job: a job that never reported is a hole, not a
36
+ * subset someone chose. `writeSummary` defaults it to whether `CI` is set.
37
+ */
38
+ requireComplete?: boolean | undefined;
39
+ /** The engine the browser projects ran in; Chromium by default. The Markdown names another. */
40
+ browser?: BrowserEngine | undefined;
41
+ }
42
+ /** Options for {@link writeSummary}. */
43
+ export interface SummaryOptions extends SummaryJudgement {
44
+ reportsDir: string;
45
+ expected: SummaryExpectations;
46
+ /** `$GITHUB_STEP_SUMMARY`: the Markdown is appended there too. */
47
+ stepSummary?: string | undefined;
48
+ /**
49
+ * Only the partial matrices of runs that ended at or after this time: a local `pnpm test`
50
+ * summarises its own run, not an earlier one's leftovers. None is an error: the run wrote no
51
+ * matrix.
52
+ */
53
+ since?: Date | undefined;
54
+ }
55
+ /** What {@link writeSummary} produced. */
56
+ export interface SummaryResult {
57
+ matrix: MergedMatrix;
58
+ markdown: string;
59
+ /** Everything that makes the run not green; empty when it is. */
60
+ problems: string[];
61
+ /**
62
+ * Whether every expected project ran all its tests (in a run without a file, test-name or
63
+ * other filter, or in every shard of one), so completeness and stale quarantine entries were
64
+ * checked.
65
+ */
66
+ complete: boolean;
67
+ }
68
+ /** Which expected projects the merged runs do not cover in full. */
69
+ export interface Coverage {
70
+ /** No run has records of them. */
71
+ missingProjects: readonly string[];
72
+ /** Only filtered runs ran them: project → why each such run was filtered. */
73
+ partialProjects: ReadonlyMap<string, readonly string[]>;
74
+ /**
75
+ * Every shard ran them, and none collected a test of them. An unfiltered run fails on such a
76
+ * project itself; one shard cannot tell, as it may hold none of the project's files.
77
+ */
78
+ emptyProjects: readonly string[];
79
+ }
80
+ /** Merges the partial matrices in `reportsDir`, writes the merged matrix and its Markdown. */
81
+ export declare function writeSummary(options: SummaryOptions): SummaryResult;
82
+ /**
83
+ * The merged matrix's file name, without its extension: `parity-matrix` for Chromium, and
84
+ * `parity-matrix.<engine>` for another engine (ADR-0066), which `isPartialMatrixFile` never
85
+ * reads back as a partial matrix.
86
+ */
87
+ export declare function summaryName(browser: BrowserEngine): string;
88
+ /** Merges matrices, fills the layers that are not live, and lists the problems. Pure. */
89
+ export declare function summarise(partials: readonly PartialMatrix[], expected: SummaryExpectations, judgement?: SummaryJudgement): SummaryResult;
90
+ /** The matrix for people: where it came from, one table per case, then the problems. */
91
+ export declare function renderMarkdown(matrix: MergedMatrix, expected: SummaryExpectations, status: Coverage & {
92
+ problems: readonly string[];
93
+ requireComplete: boolean;
94
+ /** How many quarantine entries the newest run applied, which judged every record. */
95
+ quarantined: number;
96
+ /** The engine the browser projects ran in, when it is not Chromium. */
97
+ browser?: BrowserEngine | undefined;
98
+ }): string;
99
+ //#endregion