@unframework.dev/testing 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/README.md +536 -2
  2. package/dist/browser/axe.js +34 -0
  3. package/dist/browser/behaviour.js +59 -0
  4. package/dist/browser/capabilities.js +58 -0
  5. package/dist/browser/clock.d.ts +17 -0
  6. package/dist/browser/clock.js +69 -0
  7. package/dist/browser/console.d.ts +27 -0
  8. package/dist/browser/console.js +142 -0
  9. package/dist/browser/determinism.js +108 -0
  10. package/dist/browser/element-timeout.js +28 -0
  11. package/dist/browser/events.js +68 -0
  12. package/dist/browser/geometry.js +135 -0
  13. package/dist/browser/keys.js +62 -0
  14. package/dist/browser/matchers.d.ts +39 -0
  15. package/dist/browser/matchers.js +78 -0
  16. package/dist/browser/navigation.js +38 -0
  17. package/dist/browser/parity.d.ts +10 -0
  18. package/dist/browser/parity.js +93 -0
  19. package/dist/browser/spec.d.ts +25 -0
  20. package/dist/browser/spec.js +38 -0
  21. package/dist/browser/target.d.ts +16 -0
  22. package/dist/browser/target.js +27 -0
  23. package/dist/browser/text-runs.js +68 -0
  24. package/dist/browser/thrown.js +71 -0
  25. package/dist/browser/trace.d.ts +21 -0
  26. package/dist/browser/trace.js +73 -0
  27. package/dist/browser/user.d.ts +45 -0
  28. package/dist/browser/user.js +184 -0
  29. package/dist/browser/view.d.ts +114 -0
  30. package/dist/browser/view.js +282 -0
  31. package/dist/browser/visual.d.ts +20 -0
  32. package/dist/browser/visual.js +36 -0
  33. package/dist/cli.d.ts +23 -0
  34. package/dist/cli.js +90 -0
  35. package/dist/commands.d.ts +107 -0
  36. package/dist/config/broadcast.js +29 -0
  37. package/dist/config/cases.d.ts +28 -0
  38. package/dist/config/cases.js +94 -0
  39. package/dist/config/index.d.ts +82 -0
  40. package/dist/config/index.js +295 -0
  41. package/dist/config/project-vite.d.ts +40 -0
  42. package/dist/config/project-vite.js +152 -0
  43. package/dist/diff.d.ts +14 -0
  44. package/dist/diff.js +92 -0
  45. package/dist/dom/serialize.js +236 -0
  46. package/dist/errors.d.ts +13 -0
  47. package/dist/errors.js +38 -0
  48. package/dist/harness.d.ts +189 -0
  49. package/dist/harness.js +53 -0
  50. package/dist/index.d.ts +16 -0
  51. package/dist/index.js +12 -0
  52. package/dist/internal.d.ts +8 -0
  53. package/dist/internal.js +6 -0
  54. package/dist/layers.d.ts +183 -0
  55. package/dist/layers.js +241 -0
  56. package/dist/node/browser.d.ts +33 -0
  57. package/dist/node/browser.js +64 -0
  58. package/dist/node/commands.d.ts +137 -0
  59. package/dist/node/commands.js +139 -0
  60. package/dist/node/context.d.ts +28 -0
  61. package/dist/node/context.js +55 -0
  62. package/dist/node/events.d.ts +25 -0
  63. package/dist/node/events.js +50 -0
  64. package/dist/node/finished.d.ts +12 -0
  65. package/dist/node/finished.js +28 -0
  66. package/dist/node/index.d.ts +21 -0
  67. package/dist/node/index.js +20 -0
  68. package/dist/node/matrix.d.ts +219 -0
  69. package/dist/node/matrix.js +309 -0
  70. package/dist/node/mode.d.ts +103 -0
  71. package/dist/node/mode.js +204 -0
  72. package/dist/node/names.d.ts +4 -0
  73. package/dist/node/names.js +5 -0
  74. package/dist/node/policy.d.ts +44 -0
  75. package/dist/node/policy.js +140 -0
  76. package/dist/node/reporter.d.ts +101 -0
  77. package/dist/node/reporter.js +251 -0
  78. package/dist/node/summary.d.ts +99 -0
  79. package/dist/node/summary.js +352 -0
  80. package/dist/node/thrown.js +78 -0
  81. package/dist/node/viewport.d.ts +7 -0
  82. package/dist/node/viewport.js +8 -0
  83. package/dist/node/visual.d.ts +85 -0
  84. package/dist/node/visual.js +373 -0
  85. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/protocol.d.ts +23930 -0
  86. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/structs.d.ts +22 -0
  87. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/types.d.ts +22221 -0
  88. package/dist/normalize/display.js +309 -0
  89. package/dist/normalize/index.d.ts +34 -0
  90. package/dist/normalize/index.js +38 -0
  91. package/dist/normalize/pipeline.d.ts +19 -0
  92. package/dist/normalize/pipeline.js +45 -0
  93. package/dist/normalize/print.js +103 -0
  94. package/dist/normalize/rules/angular-hosts.js +53 -0
  95. package/dist/normalize/rules/aria-hosts.js +48 -0
  96. package/dist/normalize/rules/comments.js +16 -0
  97. package/dist/normalize/rules/control-values.js +65 -0
  98. package/dist/normalize/rules/engine-aliases.js +34 -0
  99. package/dist/normalize/rules/framework-attributes.js +85 -0
  100. package/dist/normalize/rules/generated-ids.js +64 -0
  101. package/dist/normalize/rules/ordering.js +39 -0
  102. package/dist/normalize/rules/qwik-styles.js +21 -0
  103. package/dist/normalize/rules/qwik-templates.js +20 -0
  104. package/dist/normalize/rules/values.js +125 -0
  105. package/dist/normalize/rules/whitespace.js +381 -0
  106. package/dist/normalize/style.js +121 -0
  107. package/dist/normalize/targets.d.ts +8 -0
  108. package/dist/normalize/targets.js +17 -0
  109. package/dist/normalize/tree.d.ts +1 -0
  110. package/dist/normalize/tree.js +151 -0
  111. package/dist/setup.d.ts +1 -0
  112. package/dist/setup.js +149 -0
  113. package/dist/ssr/index.d.ts +10 -0
  114. package/dist/ssr/index.js +103 -0
  115. package/dist/ssr/spec.d.ts +1 -0
  116. package/dist/ssr/spec.js +7 -0
  117. package/dist/targets/angular.d.ts +1 -0
  118. package/dist/targets/angular.js +5 -0
  119. package/dist/targets/astro.d.ts +1 -0
  120. package/dist/targets/astro.js +5 -0
  121. package/dist/targets/qwik.d.ts +1 -0
  122. package/dist/targets/qwik.js +5 -0
  123. package/dist/targets/react.d.ts +1 -0
  124. package/dist/targets/react.js +5 -0
  125. package/dist/targets/solid.d.ts +1 -0
  126. package/dist/targets/solid.js +5 -0
  127. package/dist/targets/svelte.d.ts +1 -0
  128. package/dist/targets/svelte.js +5 -0
  129. package/dist/targets/vue.d.ts +1 -0
  130. package/dist/targets/vue.js +5 -0
  131. package/dist/visual-types.d.ts +92 -0
  132. package/dist/visual-types.js +24 -0
  133. package/package.json +146 -3
@@ -0,0 +1,352 @@
1
+ import { isCI } from "./mode.js";
2
+ import { FONT_AUDIT_SKIP, LIVE_REFERENCE_SKIP, REFERENCE_NOT_RUN_SKIP } from "../visual-types.js";
3
+ import { BROWSER_LAYERS, LAYERS, NOT_IN_THIS_RUN_SKIP, NOT_RENDERED_SKIP, NO_INTERACTION_SKIP, NO_OUTPUT_SKIP, NO_OUTPUT_TEST_SKIP, NO_SPEC_SKIP, REQUIRES_SKIP } from "../layers.js";
4
+ import { cellHeadline, mergeMatrices, narrowing, outcomeOfCell, settleQuarantine, stringifyMatrix } from "./matrix.js";
5
+ import { readPartialMatrices } from "./reporter.js";
6
+ import { appendFileSync, writeFileSync } from "node:fs";
7
+ import { join } from "node:path";
8
+ //#region src/node/summary.ts
9
+ /**
10
+ * The skips a live layer may record besides one by capability (plan §7.7, ADR-0050): each has a
11
+ * mechanical cause. Anything else on a live layer would hide a check that never ran.
12
+ */
13
+ const MECHANICAL_SKIPS = [
14
+ NO_OUTPUT_SKIP,
15
+ NO_SPEC_SKIP,
16
+ LIVE_REFERENCE_SKIP,
17
+ NOT_RENDERED_SKIP,
18
+ NO_INTERACTION_SKIP
19
+ ];
20
+ /** Why a live layer's skip is not one the summary accepts, or nothing when it is. */
21
+ function unacceptedSkip(reason, capabilities) {
22
+ if (MECHANICAL_SKIPS.includes(reason) || NO_OUTPUT_TEST_SKIP.test(reason)) return void 0;
23
+ const capability = REQUIRES_SKIP.exec(reason)?.[1];
24
+ if (capability === void 0) return `skipped (${reason}), which names no capability its target lacks and none of the mechanical causes (${[...MECHANICAL_SKIPS, "no output: <the expected errors>"].join("; ")}): a live layer skips only for a reason the matrix can show.`;
25
+ if (capabilities && !capabilities.includes(capability)) return `skipped for "${capability}", which is not a capability.`;
26
+ }
27
+ /** Merges the partial matrices in `reportsDir`, writes the merged matrix and its Markdown. */
28
+ function writeSummary(options) {
29
+ const since = options.since;
30
+ const partials = [...readPartialMatrices(options.reportsDir).values()].filter((partial) => since === void 0 || Date.parse(partial.finishedAt) >= since.getTime());
31
+ if (!partials.length) throw new Error(since === void 0 ? `[uf:summary] No parity-matrix.*.json in ${options.reportsDir}: run the integration tests first.` : `[uf:summary] No run wrote a parity matrix to ${options.reportsDir} since ${since.toISOString()}: the run did not get as far as reporting.`);
32
+ const result = summarise(partials, options.expected, {
33
+ requireComplete: options.requireComplete ?? isCI(process.env),
34
+ browser: options.browser
35
+ });
36
+ const name = summaryName(options.browser ?? "chromium");
37
+ writeFileSync(join(options.reportsDir, `${name}.json`), stringifyMatrix(result.matrix));
38
+ writeFileSync(join(options.reportsDir, `${name}.md`), result.markdown);
39
+ if (options.stepSummary) appendFileSync(options.stepSummary, `${result.markdown}\n`);
40
+ return result;
41
+ }
42
+ /**
43
+ * The merged matrix's file name, without its extension: `parity-matrix` for Chromium, and
44
+ * `parity-matrix.<engine>` for another engine (ADR-0066), which `isPartialMatrixFile` never
45
+ * reads back as a partial matrix.
46
+ */
47
+ function summaryName(browser) {
48
+ return browser === "chromium" ? "parity-matrix" : `parity-matrix.${browser}`;
49
+ }
50
+ /** Merges matrices, fills the layers that are not live, and lists the problems. Pure. */
51
+ function summarise(partials, expected, judgement = {}) {
52
+ const { matrix: merged, quarantine, reference, references } = mergeMatrices(partials);
53
+ const coverage = coverageOf(merged, expected.projects);
54
+ const { missingProjects, partialProjects } = coverage;
55
+ const complete = missingProjects.length === 0 && partialProjects.size === 0;
56
+ const checkMissing = complete || Boolean(judgement.requireComplete);
57
+ const problems = [];
58
+ const live = new Set(expected.liveLayers);
59
+ const knownCases = new Set(expected.cases);
60
+ for (const project of coverage.emptyProjects) problems.push(`${project}: collected zero tests in every shard. A project that runs nothing verifies nothing.`);
61
+ if (judgement.requireComplete) {
62
+ for (const project of missingProjects) problems.push(`${project}: did not run (no parity matrix has its records).`);
63
+ for (const [project, filters] of partialProjects) problems.push(`${project}: only filtered runs ran it (${filters.join("; ")}), so not every cell is checked.`);
64
+ }
65
+ const drops = referenceDrops(merged.cases);
66
+ const blockedCases = new Set([...drops.values()].flatMap((drop) => [...drop.cases]));
67
+ const dropped = (caseId, target, layer) => blockedCases.has(caseId) && target === (references[caseId] ?? reference) && BROWSER_LAYERS.includes(layer);
68
+ settleQuarantine(merged.cases, quarantine, { stale: complete });
69
+ for (const caseId of Object.keys(merged.cases)) if (!knownCases.has(caseId)) problems.push(`${caseId}: recorded, but not a case in the corpus.`);
70
+ for (const caseId of [...expected.cases].sort()) {
71
+ const targets = merged.cases[caseId] ??= {};
72
+ for (const target of expected.targets) {
73
+ const cells = targets[target] ??= {};
74
+ for (const layer of LAYERS) {
75
+ const cell = cells[layer];
76
+ if (cell === void 0) {
77
+ const recordedBy = expected.recordedOnlyBy?.[layer];
78
+ if (!live.has(layer)) cells[layer] = `skip(${expected.notLiveReason})`;
79
+ else if (!judgement.requireComplete && recordedBy && !ranInFull(merged, recordedBy)) cells[layer] = `skip(${NOT_IN_THIS_RUN_SKIP})`;
80
+ else if ((checkMissing || recordedBy) && !dropped(caseId, target, layer)) problems.push(`${caseId} › ${target} › ${layer}: missing (no test recorded it).`);
81
+ continue;
82
+ }
83
+ if (layer === "L10" && drops.blocks(caseId, target)) continue;
84
+ const outcome = outcomeOfCell(cell);
85
+ if (outcome.status === "fail") problems.push(`${caseId} › ${target} › ${layer}: ${cellHeadline(cell)}`);
86
+ if (outcome.status === "skip" && live.has(layer)) {
87
+ const why = unacceptedSkip(outcome.reason, expected.capabilities);
88
+ if (why) problems.push(`${caseId} › ${target} › ${layer}: ${why}`);
89
+ }
90
+ }
91
+ targets[target] = Object.fromEntries(LAYERS.filter((layer) => cells[layer] !== void 0).map((layer) => [layer, cells[layer]]));
92
+ }
93
+ if (checkMissing && reference !== null && !blockedCases.has(caseId)) {
94
+ const judge = references[caseId] ?? reference;
95
+ problems.push(...scenarioProblems(merged, caseId, judge, expected.targets));
96
+ }
97
+ }
98
+ problems.unshift(...dropProblems(drops, partials));
99
+ const matrix = {
100
+ ...merged,
101
+ cases: Object.fromEntries(Object.entries(merged.cases).sort(([a], [b]) => a.localeCompare(b)))
102
+ };
103
+ return {
104
+ matrix,
105
+ markdown: renderMarkdown(matrix, expected, {
106
+ ...coverage,
107
+ problems,
108
+ requireComplete: Boolean(judgement.requireComplete),
109
+ quarantined: quarantine.length,
110
+ browser: judgement.browser
111
+ }),
112
+ problems,
113
+ complete
114
+ };
115
+ }
116
+ const cellKey = (caseId, target) => `${caseId}\u0000${target}`;
117
+ /** The project a blocked L10 cell names, or none for any other cell. */
118
+ function blockedBy(cell) {
119
+ if (cell === void 0 || !cell.startsWith("skip(")) return void 0;
120
+ const outcome = outcomeOfCell(cell);
121
+ return outcome.status === "skip" ? REFERENCE_NOT_RUN_SKIP.exec(outcome.reason)?.[1] : void 0;
122
+ }
123
+ /** Every L10 cell a reference's drop left without a comparison, grouped by that project. */
124
+ function referenceDrops(cells) {
125
+ const drops = /* @__PURE__ */ new Map();
126
+ const blocked = /* @__PURE__ */ new Set();
127
+ for (const [caseId, targets] of Object.entries(cells)) for (const [target, layers] of Object.entries(targets)) {
128
+ const project = blockedBy(layers.L10);
129
+ if (project === void 0) continue;
130
+ const drop = drops.get(project) ?? {
131
+ cases: /* @__PURE__ */ new Set(),
132
+ cells: /* @__PURE__ */ new Set()
133
+ };
134
+ drop.cases.add(caseId);
135
+ drop.cells.add(cellKey(caseId, target));
136
+ drops.set(project, drop);
137
+ blocked.add(cellKey(caseId, target));
138
+ }
139
+ return Object.assign(drops, { blocks: (caseId, target) => blocked.has(cellKey(caseId, target)) });
140
+ }
141
+ /** How many of a list to name in a problem before counting the rest. */
142
+ const NAMED = 3;
143
+ /**
144
+ * One problem per reference project that stopped early, with the errors Vitest reported in the
145
+ * runs that recorded its blocked cells: the closed connection is reported there, outside every
146
+ * test. A drop is never green, whatever else ran, and with no error the problem says so.
147
+ */
148
+ function dropProblems(drops, partials) {
149
+ return [...drops].sort(([a], [b]) => a.localeCompare(b)).map(([project, drop]) => {
150
+ const errors = [...new Set(partials.filter((partial) => Object.values(partial.byProject).some((cells) => Object.values(cells).some((targets) => Object.values(targets).some((layers) => blockedBy(layers.L10) === project)))).flatMap((partial) => partial.errors ?? []))];
151
+ const cases = [...drop.cases].sort();
152
+ return `${project} did not finish ${cases.length} of its spec files in this run (${named(cases)}); ${drop.cells.size} follower cell(s) could not be compared at L10. Vitest reported: ${errors.length ? named(errors) : "no error"}.`;
153
+ });
154
+ }
155
+ /** The first few items of a list, and how many more there are. */
156
+ function named(items) {
157
+ const more = items.length - NAMED;
158
+ return `${items.slice(0, NAMED).join(", ")}${more > 0 ? `, and ${more} more` : ""}`;
159
+ }
160
+ /** Whether the merged runs cover every test of a project. */
161
+ function ranInFull(merged, project) {
162
+ const { missingProjects, partialProjects } = coverageOf(merged, [project]);
163
+ return !missingProjects.length && !partialProjects.size;
164
+ }
165
+ /**
166
+ * The targets whose parity scenarios of a case differ from the reference's, test by test. Every
167
+ * target runs the same spec, and a cell merges every test of its case, so a scenario one target
168
+ * leaves out (a spec that branches on the target, a test that stops early) shows in no cell.
169
+ * A test a target skipped (by capability, or because the target has no output for the case), or
170
+ * ran against a stand-in for a component it cannot compile yet (ADR-0068), is excused on that
171
+ * target, and only that test: its scenarios are the ones it would have checked (ADR-0050). Judged like the missing cells, once every project ran all its tests: a filtered
172
+ * run checks only some scenarios.
173
+ */
174
+ function scenarioProblems(matrix, caseId, reference, targets) {
175
+ if (!targets.includes(reference)) return [];
176
+ const expected = matrix.tests[caseId]?.[reference] ?? {};
177
+ const problems = [];
178
+ for (const target of targets) {
179
+ if (target === reference) continue;
180
+ const actual = matrix.tests[caseId]?.[target] ?? {};
181
+ const differences = [];
182
+ for (const name of [.../* @__PURE__ */ new Set([...Object.keys(expected), ...Object.keys(actual)])].sort()) {
183
+ const theirs = expected[name];
184
+ const ours = actual[name];
185
+ if (ours?.skipped !== void 0 || ours?.standIn !== void 0) continue;
186
+ const wanted = theirs?.skipped === void 0 ? theirs?.scenarios ?? [] : [];
187
+ const checked = ours?.scenarios ?? [];
188
+ const missing = wanted.filter((scenario) => !checked.includes(scenario));
189
+ const extra = checked.filter((scenario) => !wanted.includes(scenario));
190
+ if (missing.length) differences.push(`"${name}" never checks ${missing.join(", ")}`);
191
+ if (extra.length) {
192
+ const why = theirs?.skipped === void 0 ? "" : ` (it skipped the test: ${theirs.skipped})`;
193
+ differences.push(`"${name}" checks ${extra.join(", ")}, which ${reference} never checks${why}`);
194
+ }
195
+ }
196
+ if (!differences.length) continue;
197
+ problems.push(`${caseId} › ${target}: its parity scenarios differ from ${reference}'s: ${differences.join("; ")}. Every target runs the same spec, so every target checks the same scenarios, unless it skips a test by capability, has no output for the case, or cannot compile it yet.`);
198
+ }
199
+ return problems;
200
+ }
201
+ /**
202
+ * Which expected projects the merged runs cover only in part. A filtered run (files, test
203
+ * names, a shard, `--changed`) lists every project it selected but records only the tests it
204
+ * ran: it covers no project in full, so its missing cells say nothing. Shards add up, though:
205
+ * shards 1 to n of one selection, with no other filter, ran every test of its projects.
206
+ */
207
+ function coverageOf(merged, projects) {
208
+ const ran = new Set(merged.projects);
209
+ const unfiltered = new Set(merged.runs.filter((run) => narrowing(run) === null).flatMap((run) => run.projects));
210
+ const sets = shardSets(merged.runs);
211
+ const partialProjects = /* @__PURE__ */ new Map();
212
+ const emptyProjects = [];
213
+ for (const project of projects) {
214
+ if (!ran.has(project) || unfiltered.has(project)) continue;
215
+ const ofProject = sets.filter((set) => set.projects.includes(project));
216
+ const complete = ofProject.filter((set) => !set.missing.length);
217
+ if (complete.length) {
218
+ if (complete.every((set) => set.runs.every((run) => run.empty.includes(project)))) emptyProjects.push(project);
219
+ continue;
220
+ }
221
+ const reasons = [...merged.runs.flatMap((run) => {
222
+ const why = narrowing(run);
223
+ return run.filtered !== null && why !== null && run.projects.includes(project) ? [why] : [];
224
+ }), ...ofProject.map((set) => `${shardList(set.ran, set.count)} without ${shardList(set.missing, set.count)}`)];
225
+ partialProjects.set(project, [...new Set(reasons)]);
226
+ }
227
+ return {
228
+ missingProjects: projects.filter((project) => !ran.has(project)),
229
+ partialProjects,
230
+ emptyProjects
231
+ };
232
+ }
233
+ /**
234
+ * The runs narrowed by nothing but a shard, grouped by selection and count. Vitest orders the
235
+ * test files of every selected project together and cuts them into `count` parts, so only the
236
+ * parts of one selection and one count make up a whole; any other shard says nothing about them.
237
+ */
238
+ function shardSets(runs) {
239
+ const groups = /* @__PURE__ */ new Map();
240
+ for (const run of runs) {
241
+ if (run.shard === null || run.filtered !== null) continue;
242
+ const key = JSON.stringify([run.shard.count, run.projects.toSorted()]);
243
+ const group = groups.get(key) ?? {
244
+ projects: run.projects,
245
+ count: run.shard.count,
246
+ runs: [],
247
+ indices: /* @__PURE__ */ new Set()
248
+ };
249
+ group.runs.push(run);
250
+ group.indices.add(run.shard.index);
251
+ groups.set(key, group);
252
+ }
253
+ return [...groups.values()].map(({ indices, ...group }) => {
254
+ const all = Array.from({ length: group.count }, (_, index) => index + 1);
255
+ return {
256
+ ...group,
257
+ ran: all.filter((index) => indices.has(index)),
258
+ missing: all.filter((index) => !indices.has(index))
259
+ };
260
+ });
261
+ }
262
+ /** Shards by index, such as `shard 1/3, shard 3/3`. */
263
+ function shardList(indices, count) {
264
+ return indices.map((index) => `shard ${index}/${count}`).join(", ");
265
+ }
266
+ /** The matrix for people: where it came from, one table per case, then the problems. */
267
+ function renderMarkdown(matrix, expected, status) {
268
+ const browser = status.browser ?? "chromium";
269
+ const layers = LAYERS.filter((layer) => expected.liveLayers.includes(layer));
270
+ const { missingProjects, partialProjects, problems } = status;
271
+ const narrowed = /* @__PURE__ */ new Map();
272
+ for (const [project, filters] of partialProjects) {
273
+ const filter = filters.join("; ");
274
+ narrowed.set(filter, [...narrowed.get(filter) ?? [], project]);
275
+ }
276
+ const gaps = [...missingProjects.length ? [`${missingProjects.length} project(s) did not run (${missingProjects.join(", ")})`] : [], ...[...narrowed].map(([filter, projects]) => projects.length === expected.projects.length ? `every project ran only in part (${filter})` : `${projects.length} project(s) ran only in part (${filter}: ${projects.join(", ")})`)];
277
+ const lines = [
278
+ browser === "chromium" ? "## Unframework parity matrix" : `## Unframework parity matrix in ${browser}`,
279
+ "",
280
+ ...browser === "chromium" ? [] : [`The browser projects ran in ${browser}: L10 compared each target with the reference's capture in this run, and the font audit was skipped (${FONT_AUDIT_SKIP}).`, ""],
281
+ `${Object.keys(matrix.cases).length} case(s) × ${expected.targets.length} target(s) × ${layers.length} live layer(s), from ${matrix.projects.length} project(s).`,
282
+ gaps.length ? status.requireComplete ? `Incomplete: ${gaps.join(", and ")}, and every project must run all its tests.` : `Partial run: ${gaps.join(", and ")}, so missing cells and stale quarantine entries are not checked.` : matrix.runs.length > 1 ? `Every project has records, from ${matrix.runs.length} runs: every cell is checked, each layer against the newest run that recorded it.` : "Every project ran: every cell is checked.",
283
+ `Layers that are not live (${LAYERS.filter((layer) => !layers.includes(layer)).join(", ")}) are recorded as skip(${expected.notLiveReason}).`,
284
+ ...Object.entries(expected.recordedOnlyBy ?? {}).filter(([, project]) => !status.requireComplete && !ranInFull(matrix, project)).map(([layer, project]) => `Only \`${project}\` records ${layer}, and it did not run in full, so those cells are skip(${NOT_IN_THIS_RUN_SKIP}).`),
285
+ "",
286
+ `Merged from ${matrix.runs.length} run(s), oldest first; a newer run's records replace the older ones it re-judged:`,
287
+ "",
288
+ ...matrix.runs.map((run) => `- ${describeRun(run)}`),
289
+ ""
290
+ ];
291
+ if (matrix.runs.some((run) => run.mode?.update)) lines.push("An update run wrote the shared artefacts: the reference target's cells from it pass because it wrote them, not because it compared them.", "");
292
+ if (status.quarantined) {
293
+ const one = status.quarantined === 1;
294
+ const entries = one ? "The quarantine entry" : `The ${status.quarantined} quarantine entries`;
295
+ const unchecked = `, but ${one ? "is" : "are"} not checked for staleness: not every project ran all its tests`;
296
+ lines.push(`${entries} of the newest run ${one ? "judges" : "judge"} every record${gaps.length ? unchecked : ""}.`, "");
297
+ }
298
+ for (const [caseId, targets] of Object.entries(matrix.cases)) {
299
+ lines.push(`### ${caseId}`, "", `| Target | ${layers.join(" | ")} |`, `| --- | ${layers.map(() => "---").join(" | ")} |`);
300
+ const notes = /* @__PURE__ */ new Map();
301
+ for (const target of expected.targets) {
302
+ const cells = targets[target] ?? {};
303
+ lines.push(`| ${target} | ${layers.map((layer) => short(cells[layer])).join(" | ")} |`);
304
+ for (const layer of layers) {
305
+ const cell = cells[layer];
306
+ const outcome = cell === void 0 ? void 0 : outcomeOfCell(cell);
307
+ if (outcome?.status !== "skip" && outcome?.status !== "quarantined") continue;
308
+ const note = outcome.status === "skip" ? `skipped: ${outcome.reason}` : `quarantined: ${outcome.issue}`;
309
+ const entry = notes.get(note) ?? {
310
+ layers: /* @__PURE__ */ new Set(),
311
+ targets: /* @__PURE__ */ new Set()
312
+ };
313
+ entry.layers.add(layer);
314
+ entry.targets.add(target);
315
+ notes.set(note, entry);
316
+ }
317
+ }
318
+ lines.push("");
319
+ for (const [note, where] of notes) {
320
+ const on = where.targets.size === expected.targets.length ? "every target" : [...where.targets].join(", ");
321
+ lines.push(`- ${escapeCell(note)}: ${[...where.layers].join(", ")} on ${on}.`);
322
+ }
323
+ const skipped = expected.targets.flatMap((target) => Object.entries(matrix.tests[caseId]?.[target] ?? {}).flatMap(([name, test]) => test.skipped !== void 0 ? [`- skipped on ${target} ${NO_OUTPUT_TEST_SKIP.test(test.skipped) ? "for want of output" : "by capability"}: "${escapeCell(name)}" (${escapeCell(test.skipped)}).`] : test.standIn !== void 0 ? [`- run against a stand-in on ${target}: "${escapeCell(name)}" (${escapeCell(test.standIn)}).`] : []));
324
+ lines.push(...skipped);
325
+ if (notes.size || skipped.length) lines.push("");
326
+ }
327
+ lines.push(problems.length ? `### Problems (${problems.length})` : "### No problems", "");
328
+ for (const problem of problems) lines.push(`- ${escapeCell(problem)}`);
329
+ return `${lines.join("\n").trimEnd()}\n`;
330
+ }
331
+ /** A run, for the provenance list: its name, mode, filter and when it ended. */
332
+ function describeRun(run) {
333
+ const how = run.mode ? [
334
+ run.mode.update ? "update" : "check",
335
+ `${run.mode.pixels} pixels`,
336
+ ...run.mode.canary ? [`canary ${run.mode.canary}`] : []
337
+ ].join(", ") : "outside the harness";
338
+ const narrowed = narrowing(run);
339
+ const only = narrowed === null ? "" : `; only ${narrowed}`;
340
+ return `\`${run.run}\` (${how}${only}), ended ${run.finishedAt}: ${run.projects.join(", ")}`;
341
+ }
342
+ /** A cell in a table: the status only; reasons are listed under the table. */
343
+ function short(cell) {
344
+ if (cell === void 0) return "**missing**";
345
+ const { status } = outcomeOfCell(cell);
346
+ return status === "fail" ? "**FAIL**" : status;
347
+ }
348
+ function escapeCell(text) {
349
+ return text.replaceAll("|", "\\|");
350
+ }
351
+ //#endregion
352
+ export { coverageOf, renderMarkdown, summarise, summaryName, unacceptedSkip, writeSummary };
@@ -0,0 +1,78 @@
1
+ import { caseDirectory, caseMainSource, projectHarness } from "./context.js";
2
+ import { existsSync, readFileSync, readdirSync } from "node:fs";
3
+ import { dirname, join, sep } from "node:path";
4
+ import { TraceMap, originalPositionFor } from "@jridgewell/trace-mapping";
5
+ //#region src/node/thrown.ts
6
+ /**
7
+ * The one line of a case's sources that holds `throw`: the `.uf.tsx` files of its directory and
8
+ * its main source, wherever that lies. Throws unless there is exactly one.
9
+ */
10
+ function throwSite(sources) {
11
+ const found = [...new Set(sources)].flatMap((file) => readFileSync(file, "utf8").split("\n").flatMap((text, index) => /\bthrow\b/.test(text) ? [{
12
+ file,
13
+ line: index + 1
14
+ }] : []));
15
+ if (found.length !== 1) throw new Error(`[uf] The case's sources hold ${found.length} throw statements: a case that throws on purpose holds one.`);
16
+ return found[0];
17
+ }
18
+ /** One line of a V8 stack: where it ran, with or without the function's name around it. */
19
+ const FRAME = /^\s*at (?:.*\()?(.+?):(\d+):(\d+)\)?\s*$/;
20
+ /** A stack's frames, top first, as written. */
21
+ function stackFrames(stack) {
22
+ return stack.split("\n").flatMap((text) => {
23
+ const match = FRAME.exec(text);
24
+ return match ? [{
25
+ url: match[1],
26
+ line: Number(match[2]),
27
+ column: Number(match[3])
28
+ }] : [];
29
+ });
30
+ }
31
+ /**
32
+ * The file a served module's URL stands for: Vite serves a file under the root at its path from
33
+ * the root, and any other at `/@fs/<absolute path>`.
34
+ */
35
+ function servedFile(url, root) {
36
+ let pathname;
37
+ try {
38
+ pathname = decodeURIComponent(new URL(url).pathname);
39
+ } catch {
40
+ return;
41
+ }
42
+ return pathname.startsWith("/@fs/") ? pathname.slice(4) : join(root, pathname);
43
+ }
44
+ /** A path's file name. */
45
+ function name(file) {
46
+ return file.split(sep).pop();
47
+ }
48
+ /**
49
+ * `ufMapStack`: maps the stack's top frame in the case's sources through the module graph's map
50
+ * of its module, and says why it is not on the case's one `throw`, if it is not.
51
+ */
52
+ async function ufMapStack(context, request) {
53
+ const vite = context.project.browser?.vite;
54
+ const graph = vite?.environments.client.moduleGraph;
55
+ if (!vite || !graph) return { message: "The browser project has no Vite server to map the stack on." };
56
+ const { harness } = projectHarness(context);
57
+ const directory = caseDirectory(harness, request.case);
58
+ const sources = [caseMainSource(harness, request.case), ...readdirSync(directory).filter((file) => file.endsWith(".uf.tsx")).map((file) => join(directory, file))].filter((file) => existsSync(file));
59
+ const site = throwSite(sources);
60
+ const expected = `${name(site.file)}:${site.line}`;
61
+ const directories = [...new Set(sources.map((file) => `${dirname(file)}${sep}`))];
62
+ const frame = stackFrames(request.stack).find(({ url }) => {
63
+ const file = servedFile(url, vite.config.root);
64
+ return file !== void 0 && directories.some((each) => file.startsWith(each));
65
+ });
66
+ if (!frame) return { message: `No frame of the stack is in the case. Expected ${expected}:\n${request.stack}` };
67
+ const { pathname, search } = new URL(frame.url);
68
+ const map = (await graph.getModuleByUrl(`${pathname}${search}`))?.transformResult?.map;
69
+ if (!map || !("version" in map) || map.mappings === "") return { message: `${frame.url} has no source map. Expected ${expected}.` };
70
+ const position = originalPositionFor(new TraceMap(JSON.stringify(map)), {
71
+ line: frame.line,
72
+ column: frame.column - 1
73
+ });
74
+ const actual = `${position.source?.split("/").pop()}:${position.line}`;
75
+ return actual === expected ? {} : { message: `The top frame in the case maps to ${actual}, not to ${expected}: ${frame.url}:${frame.line}:${frame.column}.` };
76
+ }
77
+ //#endregion
78
+ export { servedFile, stackFrames, throwSite, ufMapStack };
@@ -0,0 +1,7 @@
1
+ //#region src/node/viewport.d.ts
2
+ /** The tester iframe's size; layout depends on it, so it never changes. */
3
+ export declare const VIEWPORT: {
4
+ readonly width: number;
5
+ readonly height: number;
6
+ };
7
+ //#endregion
@@ -0,0 +1,8 @@
1
+ //#region src/node/viewport.ts
2
+ /** The tester iframe's size; layout depends on it, so it never changes. */
3
+ const VIEWPORT = {
4
+ width: 800,
5
+ height: 600
6
+ };
7
+ //#endregion
8
+ export { VIEWPORT };
@@ -0,0 +1,85 @@
1
+ import { HarnessContext } from "../harness.js";
2
+ import { CaptureRequest, CaptureResult, GeometryDelta, GeometrySnapshot } from "../visual-types.js";
3
+ import { CommandProject } from "./context.js";
4
+ import { Page } from "../node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/types.js";
5
+ //#region src/node/visual.d.ts
6
+ /** The font file's internal family name that CDP reports for the bundled "UF Test Sans". */
7
+ export declare const ALLOWED_FONTS: readonly string[];
8
+ /** A project of the run, as the visual command looks for the reference's browser project. */
9
+ interface RunProject {
10
+ name: string;
11
+ config: {
12
+ browser?: {
13
+ enabled?: boolean;
14
+ };
15
+ };
16
+ getProvidedContext(): {
17
+ target?: string;
18
+ };
19
+ }
20
+ /** What the visual command needs from Vitest's command context (Playwright provider). */
21
+ export interface VisualCommandContext extends CommandProject {
22
+ project: CommandProject["project"] & {
23
+ /** The run's projects, after `--project`: whether the reference's browser project is in it. */
24
+ vitest?: {
25
+ projects: readonly RunProject[];
26
+ };
27
+ };
28
+ page: Page;
29
+ iframe: {
30
+ locator(selector: string): PlaywrightLocatorLike;
31
+ };
32
+ }
33
+ interface PlaywrightLocatorLike {
34
+ screenshot(options: {
35
+ animations: "disabled";
36
+ caret: "hide";
37
+ scale: "css";
38
+ type: "png";
39
+ timeout: number;
40
+ }): Promise<Buffer>;
41
+ }
42
+ /**
43
+ * Where one capture's expectations and evidence live, and what its messages call it: a corpus
44
+ * case's scenario ({@link caseCaptureLocation}), or a project's example (`@unframework.dev/visual`,
45
+ * ADR-0087). L10's policy and comparison are the same for both.
46
+ */
47
+ export interface CaptureLocation {
48
+ /** Identifies the scenario among the run's captures: the reference's capture is kept under it. */
49
+ key: string;
50
+ /** What messages call the scenario, such as `basics/hello/initial`. */
51
+ label: string;
52
+ /** The case whose spec file captures it: whether the reference finished it (ADR-0091). */
53
+ case: string;
54
+ /** The target whose capture is the expectation: it publishes or writes, the others compare. */
55
+ reference: string;
56
+ /** The committed Linux screenshot. */
57
+ baselinePng: string;
58
+ /** The committed geometry and computed styles. */
59
+ geometry: string;
60
+ /** Where the reference publishes its capture with live pixels. */
61
+ livePng: string;
62
+ /** Where a failed comparison leaves its reference, actual and diff images and its geometry. */
63
+ diffs: string;
64
+ /** Where every capture of this target is written, a passing one too; none by default. */
65
+ capture?: string;
66
+ /** The command that writes the committed baselines, which a refusal or a missing one names. */
67
+ baselineCommand: string;
68
+ }
69
+ /** A case's scenario as L10 locates it: the case's `__screenshots__/` and `__expected__/`. */
70
+ export declare function caseCaptureLocation(harness: HarnessContext, caseId: string, name: string, target: string): CaptureLocation;
71
+ /** A baseline PNG's file name: the scenario, then the browser and platform that produced it. */
72
+ export declare function baselineFileName(name: string): string;
73
+ /** `ufVisualCapture`: the L10 command. */
74
+ export declare function ufVisualCapture(context: VisualCommandContext, request: CaptureRequest): Promise<CaptureResult>;
75
+ /**
76
+ * L10 at a location: audits the fonts, captures a stable PNG, then publishes, writes or compares
77
+ * it under the run's policy. The corpus's command and a project's examples both run it.
78
+ */
79
+ export declare function captureAt(context: VisualCommandContext, request: CaptureRequest, location: CaptureLocation): Promise<CaptureResult>;
80
+ /** Every box and computed-style difference, by element path. */
81
+ export declare function diffGeometry(expected: GeometrySnapshot, actual: GeometrySnapshot): GeometryDelta[];
82
+ /** Geometry deltas as message lines, the first `limit` of them. */
83
+ export declare function formatGeometryDiff(deltas: readonly GeometryDelta[], against?: string, limit?: number): string[];
84
+ //#endregion
85
+ export type { GeometryDelta };