@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,184 @@
1
+ import { QuarantineEntry } from "./layers.js";
2
+ import { Capabilities } from "@unframework.dev/codegen";
3
+ //#region src/harness.d.ts
4
+ /** An SSR scenario of a case: the props it renders with. */
5
+ export interface SsrScenario {
6
+ props?: Record<string, unknown>;
7
+ }
8
+ /** The `prefers-color-scheme` a browser project emulates for a case. */
9
+ export type ColorScheme = "light" | "dark";
10
+ /** Every {@link ColorScheme}, the first the default. */
11
+ export declare const COLOR_SCHEMES: readonly ColorScheme[];
12
+ /**
13
+ * The engines a browser project can run in (`UF_BROWSER`, ADR-0066). Chromium is the default
14
+ * and the only engine with committed artefacts: Firefox and WebKit compare live, with the
15
+ * reference in the same engine, and gate no pull request.
16
+ */
17
+ export declare const BROWSER_ENGINES: readonly ["chromium", "firefox", "webkit"];
18
+ /** One of {@link BROWSER_ENGINES}. */
19
+ export type BrowserEngine = (typeof BROWSER_ENGINES)[number];
20
+ /** A case's optional `case.json` (plan §7.1). */
21
+ export interface CaseConfig {
22
+ description?: string;
23
+ /**
24
+ * The input the spec and the SSR scenarios render, relative to the case's directory, when the
25
+ * case holds several or none: the others are its children or its harness parents (ADR-0057). A
26
+ * case with one input needs none. In the corpus it is one of the case's own file names
27
+ * (`"Form.uf.tsx"`); in a project's tests it may lie outside the case
28
+ * (`"../../src/Counter.uf.tsx"`, ADR-0086).
29
+ */
30
+ main?: string;
31
+ /** L6 scenarios by name; a case without any renders `default` with no props. */
32
+ ssr?: Record<string, SsrScenario>;
33
+ /**
34
+ * Props the server render throws with (L14, ADR-0078): the `ssr` project renders them once, and
35
+ * checks the error's stack. Not a scenario of `ssr`, which each must render cleanly (L6).
36
+ */
37
+ ssrThrows?: SsrScenario;
38
+ /** The axe rule ids L11 expects to fail on this case, exactly; none by default. */
39
+ axe?: string[];
40
+ /**
41
+ * Why every test of the case requires a capability (ADR-0050): its client code changes the
42
+ * mounted DOM (an `onMounted` that writes state, say), so no test of it can pass on a target
43
+ * without the capability, and the server render (L6) is what checks that target. The harness
44
+ * refuses the note on a case with a test that requires nothing, and requires it on a case
45
+ * whose every test requires something.
46
+ */
47
+ requires?: string;
48
+ /**
49
+ * The target that writes the case's shared expectations in place of the run's reference
50
+ * (ADR-0057), for a case that requires a capability Vue renders differently (`listbox`): the
51
+ * compile project checks that Vue declares the capability unsupported and this target native.
52
+ */
53
+ reference?: string;
54
+ /**
55
+ * The `prefers-color-scheme` the browser projects emulate before the case's spec mounts
56
+ * anything, `light` by default: a dark-theme case opts in (plan §7.6, ADR-0061). The server
57
+ * render (L6) has no colour scheme.
58
+ */
59
+ colorScheme?: ColorScheme;
60
+ }
61
+ /**
62
+ * What L10 compares with: the committed Linux baselines (geometry and pixels), or the reference
63
+ * target's capture from this run.
64
+ */
65
+ export type PixelMode = "baseline" | "live";
66
+ /** The run-wide harness context, provided to every project as `ufHarness`. */
67
+ export interface HarnessContext {
68
+ /** Identifies this run: the scratch files of different runs never mix. */
69
+ runId: string;
70
+ /** Absolute path of the cases directory; a case id is a path relative to it. */
71
+ casesDir: string;
72
+ /** The reference target (D10): in update mode it alone writes the shared artefacts. */
73
+ reference: string;
74
+ /** Update mode (`UF_UPDATE=1`): writes artefacts instead of only comparing. */
75
+ update: boolean;
76
+ /**
77
+ * The command that writes the artefacts, which a failure names: `pnpm test:update` when absent
78
+ * (the corpus), `unframework test --update` in a project's tests (ADR-0086).
79
+ */
80
+ updateCommand?: string;
81
+ pixels: PixelMode;
82
+ /** The canary installed in this run (`UF_CANARY`), or `null`. */
83
+ canary: string | null;
84
+ /**
85
+ * The image and platform the run is in (`UF_BASELINE_ENVIRONMENT`), or `null`. The visual
86
+ * command writes the committed baselines only when it is `BASELINE_ENVIRONMENT`.
87
+ */
88
+ baselineEnvironment: string | null;
89
+ /** The engine the browser projects run in (`UF_BROWSER`). */
90
+ browser: BrowserEngine;
91
+ /** Update mode: where the reference records what it wrote in this run, for its followers. */
92
+ ledgerDir: string;
93
+ /** Live pixels: where the reference publishes its captures for this run. */
94
+ liveDir: string;
95
+ /** Where this run's failed visual comparisons leave their reference, actual and diff images. */
96
+ diffsDir: string;
97
+ quarantine: QuarantineEntry[];
98
+ /** Every case's `case.json`, by case id (`{}` when a case has none). */
99
+ cases: Record<string, CaseConfig>;
100
+ }
101
+ declare module "vitest" {
102
+ interface ProvidedContext {
103
+ /** The target this project verifies, such as `"vue"`. */
104
+ target: string;
105
+ ufHarness: HarnessContext;
106
+ /**
107
+ * Browser projects: the target's capability matrix, as plain data. The browser reads it to
108
+ * skip a test that requires an unsupported capability (`it(name, { requires }, fn)`) and to
109
+ * refuse interactions where nothing runs; it never imports a target, whose compiler code
110
+ * does not run in a browser.
111
+ */
112
+ ufCapabilities: Capabilities;
113
+ /**
114
+ * Browser projects: the cases the target has no output for (their expected diagnostics hold
115
+ * an error for it, the one it declares for a capability it lacks), by case id, each with
116
+ * those errors. Their specs load against a stand-in for the component, and each test is
117
+ * skipped with `no output: <the errors>`. Absent outside the harness.
118
+ */
119
+ ufNoOutput: Record<string, string>;
120
+ /**
121
+ * Browser projects: the cases the target cannot compile yet (ADR-0068), by case id, each with
122
+ * the cause: the case's L3 is quarantined on the target, whose browser build type-checks its
123
+ * output. Their specs load against a stand-in for the component, and each test runs and
124
+ * records every browser layer as failed with the cause. Absent outside the harness.
125
+ */
126
+ ufStandIn?: Record<string, string>;
127
+ /**
128
+ * SSR projects of a target the run adds only as some case's reference (ADR-0057): the ids
129
+ * of those cases, which it renders alone. Absent everywhere else.
130
+ */
131
+ ufOnly?: string[];
132
+ /** SSR projects: the module specifier of the target's renderer (`toolchain.server`). */
133
+ ufServer?: string;
134
+ /**
135
+ * SSR projects: the cases the server render spec renders (`@unframework.dev/testing/ssr`,
136
+ * ADR-0086), in order, each with its main source by absolute path. The spec imports each
137
+ * from there, so it runs the same from the workspace and from `node_modules`.
138
+ */
139
+ ufSsrCases?: SsrCase[];
140
+ }
141
+ }
142
+ /** A case the server render spec renders (`ufSsrCases`). */
143
+ export interface SsrCase {
144
+ /** The case id, a key of `HarnessContext.cases`. */
145
+ id: string;
146
+ /** The case's directory (absolute): its `__expected__/` is here. */
147
+ dir: string;
148
+ /** The main `.uf.tsx` source (absolute): what the scenarios render. */
149
+ source: string;
150
+ /**
151
+ * Why every scenario of the case is skipped on this target, recorded on L6 and L13: the corpus
152
+ * skips a case whose every test requires a capability the target lacks (ADR-0050).
153
+ */
154
+ skip?: string;
155
+ /**
156
+ * Why the case cannot be judged, which fails each of its scenarios: the corpus fails a case
157
+ * whose expected diagnostics are missing.
158
+ */
159
+ failure?: string;
160
+ }
161
+ /** The SSR scenarios of a case: its declared ones, or `default` with no props. */
162
+ export declare function ssrScenarios(config: CaseConfig): Record<string, SsrScenario>;
163
+ /**
164
+ * The case a file belongs to: the path of its directory relative to the cases directory, with
165
+ * forward slashes, nested as deep as the project lays its cases out (ADR-0086). Throws for a file
166
+ * outside every case, because its results would have nowhere to go in the parity matrix.
167
+ */
168
+ export declare function caseOfFile(file: string, harness: Pick<HarnessContext, "casesDir" | "cases">): string;
169
+ /**
170
+ * The target that writes a case's shared artefacts: the one its `case.json` names (ADR-0057), or
171
+ * the run's reference.
172
+ */
173
+ export declare function caseReference(harness: Pick<HarnessContext, "reference" | "cases">, caseId: string): string;
174
+ /**
175
+ * Whether a target writes a case's shared artefacts in update mode: the case's reference
176
+ * (`caseReference`).
177
+ */
178
+ export declare function isReference(harness: Pick<HarnessContext, "reference" | "cases">, target: string, caseId: string): boolean;
179
+ /**
180
+ * The targets that write some case's shared artefacts in place of the run's reference
181
+ * (ADR-0057): they run after the reference and before every other target (`groupOrder`).
182
+ */
183
+ export declare function caseReferences(harness: Pick<HarnessContext, "reference" | "cases">): string[];
184
+ //#endregion
@@ -0,0 +1,53 @@
1
+ //#region src/harness.ts
2
+ /** Every {@link ColorScheme}, the first the default. */
3
+ const COLOR_SCHEMES = ["light", "dark"];
4
+ /**
5
+ * The engines a browser project can run in (`UF_BROWSER`, ADR-0066). Chromium is the default
6
+ * and the only engine with committed artefacts: Firefox and WebKit compare live, with the
7
+ * reference in the same engine, and gate no pull request.
8
+ */
9
+ const BROWSER_ENGINES = [
10
+ "chromium",
11
+ "firefox",
12
+ "webkit"
13
+ ];
14
+ /** The SSR scenarios of a case: its declared ones, or `default` with no props. */
15
+ function ssrScenarios(config) {
16
+ return config.ssr && Object.keys(config.ssr).length ? config.ssr : { default: {} };
17
+ }
18
+ /**
19
+ * The case a file belongs to: the path of its directory relative to the cases directory, with
20
+ * forward slashes, nested as deep as the project lays its cases out (ADR-0086). Throws for a file
21
+ * outside every case, because its results would have nowhere to go in the parity matrix.
22
+ */
23
+ function caseOfFile(file, harness) {
24
+ const normalized = file.replaceAll("\\", "/");
25
+ const casesDir = harness.casesDir.replaceAll("\\", "/").replace(/\/$/, "");
26
+ const directory = normalized.slice(0, normalized.lastIndexOf("/"));
27
+ const id = directory.startsWith(`${casesDir}/`) ? directory.slice(casesDir.length + 1) : "";
28
+ if (!id || !Object.hasOwn(harness.cases, id)) throw new Error(`${file} is not in a case directory under ${casesDir}: a spec lives next to its case's .uf.tsx.`);
29
+ return id;
30
+ }
31
+ /**
32
+ * The target that writes a case's shared artefacts: the one its `case.json` names (ADR-0057), or
33
+ * the run's reference.
34
+ */
35
+ function caseReference(harness, caseId) {
36
+ return harness.cases[caseId]?.reference ?? harness.reference;
37
+ }
38
+ /**
39
+ * Whether a target writes a case's shared artefacts in update mode: the case's reference
40
+ * (`caseReference`).
41
+ */
42
+ function isReference(harness, target, caseId) {
43
+ return caseReference(harness, caseId) === target;
44
+ }
45
+ /**
46
+ * The targets that write some case's shared artefacts in place of the run's reference
47
+ * (ADR-0057): they run after the reference and before every other target (`groupOrder`).
48
+ */
49
+ function caseReferences(harness) {
50
+ return [...new Set(Object.values(harness.cases).flatMap((config) => config.reference && config.reference !== harness.reference ? [config.reference] : []))].sort();
51
+ }
52
+ //#endregion
53
+ export { BROWSER_ENGINES, COLOR_SCHEMES, caseOfFile, caseReference, caseReferences, isReference, ssrScenarios };
@@ -0,0 +1,16 @@
1
+ import { CaseConfig, SsrScenario } from "./harness.js";
2
+ import { ConsoleEntry, allowConsole, capturedConsole } from "./browser/console.js";
3
+ import { PixelTolerance } from "./visual-types.js";
4
+ import { NoAxeViolationsOptions } from "./browser/matchers.js";
5
+ import { TraceStep } from "./browser/trace.js";
6
+ import { ParityOptions } from "./browser/parity.js";
7
+ import { SpecOptions, SpecTest, it, test } from "./browser/spec.js";
8
+ import { ViewClock } from "./browser/clock.js";
9
+ import { currentTarget } from "./browser/target.js";
10
+ import { ClickOptions, ViewUser } from "./browser/user.js";
11
+ import { ComponentMountOptions, NotAFunction, Props, View, ViewOptions, mount, mountScenario } from "./browser/view.js";
12
+ //#region src/index.d.ts
13
+ /** `describe()` with the project's target in the title, so reports tell the targets apart. */
14
+ export declare function describeTargets(name: string, fn: () => void): void;
15
+ //#endregion
16
+ export { type CaseConfig, type ClickOptions, type ComponentMountOptions, type ConsoleEntry, type NoAxeViolationsOptions, type NotAFunction, type ParityOptions, type PixelTolerance, type Props, type SpecOptions, type SpecTest, type SsrScenario, type TraceStep, type View, type ViewClock, type ViewOptions, type ViewUser, allowConsole, capturedConsole, currentTarget, it, mount, mountScenario, test };
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