@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
package/dist/index.js ADDED
@@ -0,0 +1,12 @@
1
+ import { currentTarget } from "./browser/target.js";
2
+ import { allowConsole, capturedConsole } from "./browser/console.js";
3
+ import { it, test } from "./browser/spec.js";
4
+ import { mount, mountScenario } from "./browser/view.js";
5
+ import { describe } from "vitest";
6
+ //#region src/index.ts
7
+ /** `describe()` with the project's target in the title, so reports tell the targets apart. */
8
+ function describeTargets(name, fn) {
9
+ describe(`${name} [${currentTarget()}]`, fn);
10
+ }
11
+ //#endregion
12
+ export { allowConsole, capturedConsole, currentTarget, describeTargets, it, mount, mountScenario, test };
@@ -0,0 +1,8 @@
1
+ import { LAYERS, LayerCheck, LayerFailure, LayerName, LayerOutcome, LayerSkip, LayerSubject, QuarantineEntry, UfLayerMeta, checkLayers, recordLayer } from "./layers.js";
2
+ import { HarnessContext } from "./harness.js";
3
+ import { installMatchers } from "./browser/matchers.js";
4
+ import { TargetOptions, registerTarget } from "./browser/target.js";
5
+ import { cleanup } from "./browser/view.js";
6
+ import { CaptureCommand, captureVisual } from "./browser/visual.js";
7
+ import { MountAdapter, MountEvent, MountListener, MountOptions, MountedComponent, RenderReport } from "@unframework.dev/codegen";
8
+ export { type CaptureCommand, type HarnessContext, LAYERS, type LayerCheck, LayerFailure, type LayerName, type LayerOutcome, type LayerSkip, type LayerSubject, type MountAdapter, type MountEvent, type MountListener, type MountOptions, type MountedComponent, type QuarantineEntry, type RenderReport, type TargetOptions, type UfLayerMeta, captureVisual, checkLayers, cleanup, installMatchers, recordLayer, registerTarget };
@@ -0,0 +1,6 @@
1
+ import { registerTarget } from "./browser/target.js";
2
+ import { LAYERS, LayerFailure, checkLayers, recordLayer } from "./layers.js";
3
+ import { captureVisual } from "./browser/visual.js";
4
+ import { cleanup } from "./browser/view.js";
5
+ import { installMatchers } from "./browser/matchers.js";
6
+ export { LAYERS, LayerFailure, captureVisual, checkLayers, cleanup, installMatchers, recordLayer, registerTarget };
@@ -0,0 +1,183 @@
1
+ import { PixelMode } from "./harness.js";
2
+ //#region src/layers.d.ts
3
+ /** The verification layers of plan §7.2. */
4
+ export type LayerName = "L1" | "L2" | "L3" | "L4" | "L5" | "L6" | "L7" | "L8" | "L9" | "L10" | "L11" | "L12" | "L13" | "L14" | "L15";
5
+ /** Every layer, in order. */
6
+ export declare const LAYERS: readonly LayerName[];
7
+ /** What one test found at one layer. */
8
+ export type LayerOutcome = {
9
+ status: "pass";
10
+ } | {
11
+ status: "fail";
12
+ message: string;
13
+ } | {
14
+ status: "skip";
15
+ reason: string;
16
+ } | {
17
+ status: "quarantined";
18
+ issue: string;
19
+ };
20
+ /** The per-layer record of one harness test (plan §7.2). */
21
+ export interface UfLayerMeta {
22
+ /** The case, relative to the cases directory: `"basics/hello"`. */
23
+ case: string;
24
+ target: string;
25
+ layers: Partial<Record<LayerName, LayerOutcome>>;
26
+ /**
27
+ * The parity scenarios the test checked (`expectParity` names), in the order it first checked
28
+ * them. A target that leaves out a scenario the reference checks would otherwise go unseen,
29
+ * as a cell merges every test of its case (see `summarise`).
30
+ */
31
+ scenarios?: string[];
32
+ /**
33
+ * The test, by its full name without the target `describeTargets` adds (`state/counter >
34
+ * increments`): the same on every target, so the summary compares each target's scenarios of
35
+ * a test with the reference's. The parity reporter sets it from the test's name.
36
+ */
37
+ test?: string;
38
+ /**
39
+ * Why the test was skipped on its target: a capability it requires is unsupported there
40
+ * (`requires interactivity: …`), or the target has no output for its case (`no output: …`).
41
+ * Every layer it would have recorded is recorded as skipped with the same reason, and the
42
+ * summary excuses its scenarios on that target alone.
43
+ */
44
+ skipped?: string;
45
+ /**
46
+ * Why the test ran against a stand-in for its case's component, which its target cannot compile
47
+ * yet (ADR-0068): the case's L3 is quarantined there, and the target's browser build
48
+ * type-checks its output, so the component's own module would fail the spec's import. Every
49
+ * browser layer is recorded as failed with this cause, and the summary excuses the test's
50
+ * scenarios on that target alone.
51
+ */
52
+ standIn?: string;
53
+ }
54
+ /** The layers a browser test records, which a test skipped by capability records as skipped. */
55
+ export declare const BROWSER_LAYERS: readonly LayerName[];
56
+ /** The skip of the layers that need output, on a target a case has compile errors for. */
57
+ export declare const NO_OUTPUT_SKIP = "compile errors: no output";
58
+ /**
59
+ * The skip of the browser layers of a case without a spec, a diagnostics case, on a target it has
60
+ * output for: one whose only diagnostic is a note, as a capability's info (UF4004). No browser
61
+ * project loads it, and its server render checks the output instead.
62
+ */
63
+ export declare const NO_SPEC_SKIP = "no spec: a diagnostics case renders in no browser";
64
+ /** L13's skip in the server render of a component that did not render: L6 failed instead. */
65
+ export declare const NOT_RENDERED_SKIP = "the component did not render (L6)";
66
+ /** A layer only a project outside this run records (L15, `bench`): the summary fills its cells. */
67
+ export declare const NOT_IN_THIS_RUN_SKIP = "not in this run";
68
+ /** L9's skip in a scenario that no interaction or rerender led to: there is no trace. */
69
+ export declare const NO_INTERACTION_SKIP = "no scripted interaction";
70
+ /** The prefix of a skip by capability: `requires interactivity: <the target's reason>`. */
71
+ export declare const REQUIRES_SKIP: RegExp;
72
+ /** The skip reason of a test that requires a capability its target does not support. */
73
+ export declare function requiresSkip(capability: string, reason: string): string;
74
+ /**
75
+ * The prefix of a browser test's skip on a target its case has no output for: `no output: <the
76
+ * errors the case expects for the target>`.
77
+ */
78
+ export declare const NO_OUTPUT_TEST_SKIP: RegExp;
79
+ /**
80
+ * The skip reason of a browser test of a case its target has no output for: the case expects
81
+ * an error for the target, the one it declares for a capability it lacks (ADR-0033).
82
+ */
83
+ export declare function noOutputSkip(errors: string): string;
84
+ /**
85
+ * A known failure that still runs (plan §7.7). The (case, target, layer) cell must still fail;
86
+ * once it passes, the entry is stale and fails the run until someone removes it. A cell is fed
87
+ * by every test that records the layer (L13 by the ssr and the browser test, L6 by each SSR
88
+ * scenario), so staleness is decided for the cell, once a run has every record (see
89
+ * `settleOutcome`), not for each test.
90
+ */
91
+ export interface QuarantineEntry {
92
+ case: string;
93
+ target: string;
94
+ layer: LayerName;
95
+ reason: string;
96
+ /** The tracking issue, such as a URL. */
97
+ issue: string;
98
+ /**
99
+ * L10 only: the pixel mode whose comparisons fail, for a failure the other mode does not show
100
+ * (the committed Linux baselines against the live reference capture). A run in the other mode
101
+ * does not apply the entry, so it neither quarantines the cell nor goes stale there.
102
+ */
103
+ pixels?: PixelMode;
104
+ }
105
+ /** Which case and target a test verifies, and the quarantine that applies to it. */
106
+ export interface LayerSubject {
107
+ case: string;
108
+ target: string;
109
+ quarantine?: readonly QuarantineEntry[];
110
+ }
111
+ /** A layer check returns this to skip the layer, with the reason the matrix shows. */
112
+ export interface LayerSkip {
113
+ skip: string;
114
+ }
115
+ /** Verifies one layer: throws on failure, returns nothing on success or a skip. */
116
+ export type LayerCheck = () => void | LayerSkip | Promise<void | LayerSkip>;
117
+ /** The task a layer is recorded on: a Vitest test (`TestContext.task`, `getCurrentTest()`). */
118
+ export interface LayerTask {
119
+ meta: {
120
+ uf?: UfLayerMeta;
121
+ };
122
+ }
123
+ declare module "vitest" {
124
+ interface TaskMeta {
125
+ /** The per-layer outcomes of a harness test. */
126
+ uf?: UfLayerMeta;
127
+ /**
128
+ * The capabilities the test requires (`it(name, { requires }, fn)`): the setup skips it on a
129
+ * target whose cell for one of them is unsupported.
130
+ */
131
+ ufRequires?: readonly string[];
132
+ }
133
+ }
134
+ /**
135
+ * Merges outcomes for the same case, target and layer: fail beats everything, and a failure
136
+ * keeps the message of every record that failed (each distinct one once, in order), so no
137
+ * sub-check's evidence is lost (the canaries require each of them).
138
+ */
139
+ export declare function mergeOutcomes(...outcomes: readonly LayerOutcome[]): LayerOutcome;
140
+ /** The quarantine entry for a case, target and layer, if any. */
141
+ export declare function quarantineFor(quarantine: readonly QuarantineEntry[] | undefined, subject: {
142
+ case: string;
143
+ target: string;
144
+ }, layer: LayerName): QuarantineEntry | undefined;
145
+ /**
146
+ * Applies a quarantine entry to a cell: the merged outcome of every record of one (case, target,
147
+ * layer) in a run that recorded them all. A cell that fails (or whose records were quarantined)
148
+ * is quarantined; one that passes, or is skipped, is a stale entry and fails.
149
+ */
150
+ export declare function settleOutcome(outcome: LayerOutcome, entry?: QuarantineEntry): LayerOutcome;
151
+ /**
152
+ * Records an outcome on a task and returns what was recorded. A failure the subject's quarantine
153
+ * covers is recorded as quarantined and does not fail the test. A pass or a skip is recorded as
154
+ * it is, even under an entry: one test cannot tell a stale entry from one another test of the
155
+ * cell still needs, so the run decides (see `settleOutcome`). Several records for the same layer
156
+ * merge (fail beats pass); a task records one case and target only.
157
+ */
158
+ export declare function recordLayer(task: LayerTask, subject: LayerSubject, layer: LayerName, outcome: LayerOutcome): LayerOutcome;
159
+ /**
160
+ * Records a test that runs against a stand-in for its case's component (ADR-0068): every browser
161
+ * layer fails with the stand-in's cause, and the test is marked so the summary excuses its
162
+ * scenarios. Not a skip: the test still runs, and a quarantine entry for each layer still needs
163
+ * it to fail, so the entries go stale once the target compiles the case.
164
+ */
165
+ export declare function recordStandIn(task: LayerTask, subject: LayerSubject, cause: string): void;
166
+ /** The messages of every failed layer a task recorded, in layer order. */
167
+ export declare function layerFailures(task: LayerTask): string[];
168
+ /**
169
+ * Runs layer checks in order, records each outcome on the task, and then throws one error with
170
+ * every failure, so a test reports all the layers it broke rather than the first (see
171
+ * `recordLayerChecks`). The Node projects check this way: their tests have nothing to run after.
172
+ */
173
+ export declare function checkLayers(task: LayerTask, subject: LayerSubject, checks: Partial<Record<LayerName, LayerCheck>>): Promise<void>;
174
+ /** The error a test fails with when one or more layers failed. */
175
+ export declare class LayerFailure extends Error {
176
+ override name: string;
177
+ readonly failures: readonly string[];
178
+ constructor(subject: {
179
+ case: string;
180
+ target: string;
181
+ }, failures: readonly string[]);
182
+ }
183
+ //#endregion
package/dist/layers.js ADDED
@@ -0,0 +1,241 @@
1
+ import { formatError } from "./errors.js";
2
+ import { REFERENCE_NOT_RUN_SKIP } from "./visual-types.js";
3
+ //#region src/layers.ts
4
+ /** Every layer, in order. */
5
+ const LAYERS = [
6
+ "L1",
7
+ "L2",
8
+ "L3",
9
+ "L4",
10
+ "L5",
11
+ "L6",
12
+ "L7",
13
+ "L8",
14
+ "L9",
15
+ "L10",
16
+ "L11",
17
+ "L12",
18
+ "L13",
19
+ "L14",
20
+ "L15"
21
+ ];
22
+ /** The layers a browser test records, which a test skipped by capability records as skipped. */
23
+ const BROWSER_LAYERS = [
24
+ "L7",
25
+ "L8",
26
+ "L9",
27
+ "L10",
28
+ "L11",
29
+ "L13",
30
+ "L14"
31
+ ];
32
+ /** The skip of the layers that need output, on a target a case has compile errors for. */
33
+ const NO_OUTPUT_SKIP = "compile errors: no output";
34
+ /**
35
+ * The skip of the browser layers of a case without a spec, a diagnostics case, on a target it has
36
+ * output for: one whose only diagnostic is a note, as a capability's info (UF4004). No browser
37
+ * project loads it, and its server render checks the output instead.
38
+ */
39
+ const NO_SPEC_SKIP = "no spec: a diagnostics case renders in no browser";
40
+ /** L13's skip in the server render of a component that did not render: L6 failed instead. */
41
+ const NOT_RENDERED_SKIP = "the component did not render (L6)";
42
+ /** A layer only a project outside this run records (L15, `bench`): the summary fills its cells. */
43
+ const NOT_IN_THIS_RUN_SKIP = "not in this run";
44
+ /** L9's skip in a scenario that no interaction or rerender led to: there is no trace. */
45
+ const NO_INTERACTION_SKIP = "no scripted interaction";
46
+ /** The prefix of a skip by capability: `requires interactivity: <the target's reason>`. */
47
+ const REQUIRES_SKIP = /^requires ([a-z][a-z0-9-]*): ./s;
48
+ /** The skip reason of a test that requires a capability its target does not support. */
49
+ function requiresSkip(capability, reason) {
50
+ return `requires ${capability}: ${reason}`;
51
+ }
52
+ /**
53
+ * The prefix of a browser test's skip on a target its case has no output for: `no output: <the
54
+ * errors the case expects for the target>`.
55
+ */
56
+ const NO_OUTPUT_TEST_SKIP = /^no output: ./s;
57
+ /**
58
+ * The skip reason of a browser test of a case its target has no output for: the case expects
59
+ * an error for the target, the one it declares for a capability it lacks (ADR-0033).
60
+ */
61
+ function noOutputSkip(errors) {
62
+ return `no output: ${errors}`;
63
+ }
64
+ /** Precedence when several records meet in one cell: a failure is never hidden by a pass. */
65
+ const PRECEDENCE = {
66
+ fail: 3,
67
+ quarantined: 2,
68
+ pass: 1,
69
+ skip: 0
70
+ };
71
+ /**
72
+ * Merges outcomes for the same case, target and layer: fail beats everything, and a failure
73
+ * keeps the message of every record that failed (each distinct one once, in order), so no
74
+ * sub-check's evidence is lost (the canaries require each of them).
75
+ */
76
+ function mergeOutcomes(...outcomes) {
77
+ const [first, ...rest] = outcomes;
78
+ if (!first) throw new Error("mergeOutcomes needs at least one outcome.");
79
+ const winner = rest.reduce((best, outcome) => rank(outcome) > rank(best) ? outcome : best, first);
80
+ if (winner.status !== "fail") return winner;
81
+ const messages = new Set(outcomes.flatMap((outcome) => outcome.status === "fail" ? [outcome.message] : []));
82
+ return messages.size === 1 ? winner : {
83
+ status: "fail",
84
+ message: [...messages].join("\n")
85
+ };
86
+ }
87
+ /**
88
+ * An outcome's precedence. A skip that stands for a check that could not run, which the summary
89
+ * never accepts (ADR-0091), ranks above a pass and every other skip: a cell where one scenario
90
+ * had nothing to compare with never reads as passed, and a skip by capability of another test of
91
+ * the case never hides it.
92
+ */
93
+ function rank(outcome) {
94
+ return outcome.status === "skip" && REFERENCE_NOT_RUN_SKIP.test(outcome.reason) ? PRECEDENCE.pass + .5 : PRECEDENCE[outcome.status];
95
+ }
96
+ /** The quarantine entry for a case, target and layer, if any. */
97
+ function quarantineFor(quarantine, subject, layer) {
98
+ return quarantine?.find((entry) => entry.case === subject.case && entry.target === subject.target && entry.layer === layer);
99
+ }
100
+ /**
101
+ * Applies a quarantine entry to a cell: the merged outcome of every record of one (case, target,
102
+ * layer) in a run that recorded them all. A cell that fails (or whose records were quarantined)
103
+ * is quarantined; one that passes, or is skipped, is a stale entry and fails.
104
+ */
105
+ function settleOutcome(outcome, entry) {
106
+ if (!entry) return outcome;
107
+ if (outcome.status === "fail") return {
108
+ status: "quarantined",
109
+ issue: entry.issue
110
+ };
111
+ if (outcome.status === "quarantined") return outcome;
112
+ const what = outcome.status === "pass" ? "passes" : `is skipped (${outcome.reason})`;
113
+ const pixels = entry.layer === "L10" && entry.pixels === void 0 ? ` If only one pixel mode fails it, name that mode in the entry (pixels: "baseline" or "live").` : "";
114
+ return {
115
+ status: "fail",
116
+ message: `stale quarantine entry: remove it. ${entry.case} › ${entry.target} › ${entry.layer} ${what} (quarantined for ${entry.issue}: ${entry.reason}).${pixels}`
117
+ };
118
+ }
119
+ /**
120
+ * Records an outcome on a task and returns what was recorded. A failure the subject's quarantine
121
+ * covers is recorded as quarantined and does not fail the test. A pass or a skip is recorded as
122
+ * it is, even under an entry: one test cannot tell a stale entry from one another test of the
123
+ * cell still needs, so the run decides (see `settleOutcome`). Several records for the same layer
124
+ * merge (fail beats pass); a task records one case and target only.
125
+ */
126
+ function recordLayer(task, subject, layer, outcome) {
127
+ if (outcome.status === "skip" && !isSkipReason(outcome.reason)) throw new TypeError(`${subject.case} › ${subject.target} › ${layer}: a skip needs a reason, not ${JSON.stringify(outcome.reason)}.`);
128
+ const entry = quarantineFor(subject.quarantine, subject, layer);
129
+ const settled = entry && outcome.status === "fail" ? {
130
+ status: "quarantined",
131
+ issue: entry.issue
132
+ } : outcome;
133
+ const meta = metaOf(task, subject);
134
+ const previous = meta.layers[layer];
135
+ meta.layers[layer] = previous ? mergeOutcomes(previous, settled) : settled;
136
+ return settled;
137
+ }
138
+ /**
139
+ * Records a test that runs against a stand-in for its case's component (ADR-0068): every browser
140
+ * layer fails with the stand-in's cause, and the test is marked so the summary excuses its
141
+ * scenarios. Not a skip: the test still runs, and a quarantine entry for each layer still needs
142
+ * it to fail, so the entries go stale once the target compiles the case.
143
+ */
144
+ function recordStandIn(task, subject, cause) {
145
+ for (const layer of BROWSER_LAYERS) recordLayer(task, subject, layer, {
146
+ status: "fail",
147
+ message: cause
148
+ });
149
+ metaOf(task, subject).standIn = cause;
150
+ }
151
+ /**
152
+ * Records that a test checked a parity scenario, once per name. The summary compares each
153
+ * target's scenarios of a case with the reference's.
154
+ */
155
+ function recordScenario(task, subject, name) {
156
+ const meta = metaOf(task, subject);
157
+ const scenarios = meta.scenarios ??= [];
158
+ if (!scenarios.includes(name)) scenarios.push(name);
159
+ }
160
+ /** The task's record, created for the subject on first use: a test records one case and target. */
161
+ function metaOf(task, subject) {
162
+ const meta = task.meta.uf ??= {
163
+ case: subject.case,
164
+ target: subject.target,
165
+ layers: {}
166
+ };
167
+ if (meta.case !== subject.case || meta.target !== subject.target) throw new Error(`A test records one case and target: it recorded ${meta.case} › ${meta.target}, then ${subject.case} › ${subject.target}.`);
168
+ return meta;
169
+ }
170
+ /** The messages of every failed layer a task recorded, in layer order. */
171
+ function layerFailures(task) {
172
+ const layers = task.meta.uf?.layers ?? {};
173
+ return LAYERS.flatMap((layer) => {
174
+ const outcome = layers[layer];
175
+ return outcome?.status === "fail" ? [`${layer}: ${outcome.message}`] : [];
176
+ });
177
+ }
178
+ /** A skip reason the matrix can show: a non-blank string. */
179
+ function isSkipReason(reason) {
180
+ return typeof reason === "string" && reason.trim() !== "";
181
+ }
182
+ /** A check's return value as an outcome: nothing passes, `{ skip: reason }` skips. */
183
+ function outcomeOfResult(result) {
184
+ if (result === void 0) return { status: "pass" };
185
+ if (typeof result === "object" && result !== null && "skip" in result) {
186
+ if (isSkipReason(result.skip)) return {
187
+ status: "skip",
188
+ reason: result.skip
189
+ };
190
+ }
191
+ return {
192
+ status: "fail",
193
+ message: `The check returned ${JSON.stringify(result)}: return nothing to pass, or { skip: reason } with a reason to skip.`
194
+ };
195
+ }
196
+ /**
197
+ * Runs layer checks in order and records each outcome on the task, without throwing: returns
198
+ * the failures (`"L7: …"`), quarantined ones excluded. A check fails by throwing, and skips by
199
+ * returning `{ skip: reason }` with a non-blank reason; any other return value is a failure,
200
+ * never a silent skip. The browser's `expectParity` records this way, so the spec's own
201
+ * assertions after it still run and are recorded as L8 (see `setup.ts`).
202
+ */
203
+ async function recordLayerChecks(task, subject, checks) {
204
+ const failures = [];
205
+ for (const layer of LAYERS) {
206
+ const check = checks[layer];
207
+ if (!check) continue;
208
+ let outcome;
209
+ try {
210
+ outcome = outcomeOfResult(await check());
211
+ } catch (error) {
212
+ outcome = {
213
+ status: "fail",
214
+ message: formatError(error)
215
+ };
216
+ }
217
+ const recorded = recordLayer(task, subject, layer, outcome);
218
+ if (recorded.status === "fail") failures.push(`${layer}: ${recorded.message}`);
219
+ }
220
+ return failures;
221
+ }
222
+ /**
223
+ * Runs layer checks in order, records each outcome on the task, and then throws one error with
224
+ * every failure, so a test reports all the layers it broke rather than the first (see
225
+ * `recordLayerChecks`). The Node projects check this way: their tests have nothing to run after.
226
+ */
227
+ async function checkLayers(task, subject, checks) {
228
+ const failures = await recordLayerChecks(task, subject, checks);
229
+ if (failures.length) throw new LayerFailure(subject, failures);
230
+ }
231
+ /** The error a test fails with when one or more layers failed. */
232
+ var LayerFailure = class extends Error {
233
+ name = "LayerFailure";
234
+ failures;
235
+ constructor(subject, failures) {
236
+ super(`${subject.case} › ${subject.target}: ${failures.length} layer(s) failed\n\n${failures.join("\n\n")}`);
237
+ this.failures = failures;
238
+ }
239
+ };
240
+ //#endregion
241
+ export { BROWSER_LAYERS, LAYERS, LayerFailure, NOT_IN_THIS_RUN_SKIP, NOT_RENDERED_SKIP, NO_INTERACTION_SKIP, NO_OUTPUT_SKIP, NO_OUTPUT_TEST_SKIP, NO_SPEC_SKIP, REQUIRES_SKIP, checkLayers, layerFailures, mergeOutcomes, noOutputSkip, quarantineFor, recordLayer, recordLayerChecks, recordScenario, recordStandIn, requiresSkip, settleOutcome };
@@ -0,0 +1,33 @@
1
+ import { BrowserEngine } from "../harness.js";
2
+ import { VIEWPORT } from "./viewport.js";
3
+ import { BrowserConfigOptions } from "vitest/node";
4
+ //#region src/node/browser.d.ts
5
+ /**
6
+ * How long a user's action (`view.user.click`, …) waits for its element, as `expect.element`
7
+ * waits the poll timeout (ADR-0043): without it the provider waits for the whole test's
8
+ * timeout, so a locator that matches nothing would hold a failing test, or a browser canary,
9
+ * for a minute.
10
+ */
11
+ export declare const ACTION_TIMEOUT = 5e3;
12
+ /**
13
+ * A browser command of any signature. Vitest calls it with its command context and the payload
14
+ * the browser sent, which only the command and its caller agree on.
15
+ */
16
+ export type AnyBrowserCommand = (context: never, ...payload: never[]) => unknown;
17
+ /** Options for {@link parityBrowser}. */
18
+ export interface ParityBrowserOptions {
19
+ /** The project's name, also the instance's (or Vitest appends " (chromium)"). */
20
+ name: string;
21
+ /** Commands besides the testing API's own, such as a target's server-side render. */
22
+ commands?: Readonly<Record<string, AnyBrowserCommand>>;
23
+ /** The engine (`UF_BROWSER`, through the harness's mode); Chromium by default. */
24
+ browser?: BrowserEngine;
25
+ }
26
+ /**
27
+ * The `test.browser` options of a project that runs the parity layers. A target's command may
28
+ * not take the name of one of the testing API's: it would replace the write policy or the
29
+ * visual comparison for that project without a word.
30
+ */
31
+ export declare function parityBrowser(options: ParityBrowserOptions): BrowserConfigOptions;
32
+ //#endregion
33
+ export { VIEWPORT };
@@ -0,0 +1,64 @@
1
+ import { VIEWPORT } from "./viewport.js";
2
+ import { browserCommands } from "./commands.js";
3
+ import { playwright } from "@vitest/browser-playwright";
4
+ //#region src/node/browser.ts
5
+ /**
6
+ * How long a user's action (`view.user.click`, …) waits for its element, as `expect.element`
7
+ * waits the poll timeout (ADR-0043): without it the provider waits for the whole test's
8
+ * timeout, so a locator that matches nothing would hold a failing test, or a browser canary,
9
+ * for a minute.
10
+ */
11
+ const ACTION_TIMEOUT = 5e3;
12
+ /**
13
+ * The switches Chromium launches with, for the captures (L10):
14
+ *
15
+ * - `--font-render-hinting=none`: Linux headless Chromium hints glyph advances to whole pixels;
16
+ * without hinting, text measures the same on macOS and Linux (form controls still differ, so
17
+ * committed geometry is a Linux baseline, like the pixels).
18
+ * - `--disable-partial-raster`: by default a repaint re-rasterises only the repainted rect,
19
+ * rounded out to whole pixels, over the tile's old pixels. Where a control starts mid-pixel,
20
+ * that edge cuts the anti-aliased corner of the box beside it, which then rasterises one level
21
+ * apart from a whole raster: the same DOM captured differently after a hover, a press or a
22
+ * keystroke repainted one control, depending on which repaints each frame grouped, which
23
+ * differs by target and by load. Each repainted tile is rasterised whole instead, so a capture
24
+ * depends on the DOM, never on what was repainted before it (test/parity/cases/stub/raster).
25
+ * Every reference capture of the corpus is byte-identical with and without it.
26
+ */
27
+ const CHROMIUM_ARGS = ["--font-render-hinting=none", "--disable-partial-raster"];
28
+ /**
29
+ * The `test.browser` options of a project that runs the parity layers. A target's command may
30
+ * not take the name of one of the testing API's: it would replace the write policy or the
31
+ * visual comparison for that project without a word.
32
+ */
33
+ function parityBrowser(options) {
34
+ const taken = Object.keys(options.commands ?? {}).filter((name) => Object.hasOwn(browserCommands, name));
35
+ if (taken.length) throw new Error(`[uf] parityBrowser(${options.name}): ${taken.join(", ")} would replace the testing API's own command(s). Give the target's command another name.`);
36
+ const browser = options.browser ?? "chromium";
37
+ return {
38
+ enabled: true,
39
+ headless: true,
40
+ viewport: VIEWPORT,
41
+ provider: playwright({
42
+ actionTimeout: ACTION_TIMEOUT,
43
+ launchOptions: { args: browser === "chromium" ? [...CHROMIUM_ARGS] : [] },
44
+ contextOptions: {
45
+ deviceScaleFactor: 1,
46
+ colorScheme: "light",
47
+ reducedMotion: "reduce",
48
+ forcedColors: "none",
49
+ locale: "en-US",
50
+ timezoneId: "UTC"
51
+ }
52
+ }),
53
+ instances: [{
54
+ browser,
55
+ name: options.name
56
+ }],
57
+ commands: {
58
+ ...browserCommands,
59
+ ...options.commands
60
+ }
61
+ };
62
+ }
63
+ //#endregion
64
+ export { ACTION_TIMEOUT, VIEWPORT, parityBrowser };