@unframework.dev/testing 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/README.md +511 -2
  2. package/dist/browser/axe.js +34 -0
  3. package/dist/browser/behaviour.js +59 -0
  4. package/dist/browser/capabilities.js +58 -0
  5. package/dist/browser/clock.d.ts +17 -0
  6. package/dist/browser/clock.js +69 -0
  7. package/dist/browser/console.d.ts +27 -0
  8. package/dist/browser/console.js +142 -0
  9. package/dist/browser/determinism.js +108 -0
  10. package/dist/browser/element-timeout.js +28 -0
  11. package/dist/browser/events.js +68 -0
  12. package/dist/browser/geometry.js +135 -0
  13. package/dist/browser/keys.js +62 -0
  14. package/dist/browser/matchers.d.ts +39 -0
  15. package/dist/browser/matchers.js +78 -0
  16. package/dist/browser/navigation.js +38 -0
  17. package/dist/browser/parity.d.ts +10 -0
  18. package/dist/browser/parity.js +93 -0
  19. package/dist/browser/spec.d.ts +25 -0
  20. package/dist/browser/spec.js +38 -0
  21. package/dist/browser/target.d.ts +16 -0
  22. package/dist/browser/target.js +27 -0
  23. package/dist/browser/text-runs.js +68 -0
  24. package/dist/browser/thrown.js +71 -0
  25. package/dist/browser/trace.d.ts +21 -0
  26. package/dist/browser/trace.js +73 -0
  27. package/dist/browser/user.d.ts +45 -0
  28. package/dist/browser/user.js +184 -0
  29. package/dist/browser/view.d.ts +114 -0
  30. package/dist/browser/view.js +282 -0
  31. package/dist/browser/visual.d.ts +20 -0
  32. package/dist/browser/visual.js +36 -0
  33. package/dist/cli.d.ts +23 -0
  34. package/dist/cli.js +90 -0
  35. package/dist/commands.d.ts +107 -0
  36. package/dist/config/broadcast.js +29 -0
  37. package/dist/config/cases.d.ts +28 -0
  38. package/dist/config/cases.js +94 -0
  39. package/dist/config/index.d.ts +81 -0
  40. package/dist/config/index.js +275 -0
  41. package/dist/diff.d.ts +14 -0
  42. package/dist/diff.js +92 -0
  43. package/dist/dom/serialize.js +236 -0
  44. package/dist/errors.d.ts +13 -0
  45. package/dist/errors.js +38 -0
  46. package/dist/harness.d.ts +184 -0
  47. package/dist/harness.js +53 -0
  48. package/dist/index.d.ts +16 -0
  49. package/dist/index.js +12 -0
  50. package/dist/internal.d.ts +8 -0
  51. package/dist/internal.js +6 -0
  52. package/dist/layers.d.ts +183 -0
  53. package/dist/layers.js +241 -0
  54. package/dist/node/browser.d.ts +33 -0
  55. package/dist/node/browser.js +64 -0
  56. package/dist/node/commands.d.ts +137 -0
  57. package/dist/node/commands.js +139 -0
  58. package/dist/node/context.d.ts +28 -0
  59. package/dist/node/context.js +55 -0
  60. package/dist/node/events.d.ts +25 -0
  61. package/dist/node/events.js +50 -0
  62. package/dist/node/finished.d.ts +12 -0
  63. package/dist/node/finished.js +28 -0
  64. package/dist/node/index.d.ts +21 -0
  65. package/dist/node/index.js +20 -0
  66. package/dist/node/matrix.d.ts +219 -0
  67. package/dist/node/matrix.js +309 -0
  68. package/dist/node/mode.d.ts +101 -0
  69. package/dist/node/mode.js +201 -0
  70. package/dist/node/names.d.ts +4 -0
  71. package/dist/node/names.js +5 -0
  72. package/dist/node/policy.d.ts +44 -0
  73. package/dist/node/policy.js +140 -0
  74. package/dist/node/reporter.d.ts +101 -0
  75. package/dist/node/reporter.js +251 -0
  76. package/dist/node/summary.d.ts +99 -0
  77. package/dist/node/summary.js +352 -0
  78. package/dist/node/thrown.js +78 -0
  79. package/dist/node/viewport.d.ts +7 -0
  80. package/dist/node/viewport.js +8 -0
  81. package/dist/node/visual.d.ts +85 -0
  82. package/dist/node/visual.js +370 -0
  83. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/protocol.d.ts +23930 -0
  84. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/structs.d.ts +22 -0
  85. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/types.d.ts +22221 -0
  86. package/dist/normalize/display.js +309 -0
  87. package/dist/normalize/index.d.ts +34 -0
  88. package/dist/normalize/index.js +38 -0
  89. package/dist/normalize/pipeline.d.ts +19 -0
  90. package/dist/normalize/pipeline.js +45 -0
  91. package/dist/normalize/print.js +103 -0
  92. package/dist/normalize/rules/angular-hosts.js +53 -0
  93. package/dist/normalize/rules/aria-hosts.js +48 -0
  94. package/dist/normalize/rules/comments.js +16 -0
  95. package/dist/normalize/rules/control-values.js +65 -0
  96. package/dist/normalize/rules/engine-aliases.js +34 -0
  97. package/dist/normalize/rules/framework-attributes.js +85 -0
  98. package/dist/normalize/rules/generated-ids.js +64 -0
  99. package/dist/normalize/rules/ordering.js +39 -0
  100. package/dist/normalize/rules/qwik-styles.js +21 -0
  101. package/dist/normalize/rules/qwik-templates.js +20 -0
  102. package/dist/normalize/rules/values.js +125 -0
  103. package/dist/normalize/rules/whitespace.js +381 -0
  104. package/dist/normalize/style.js +121 -0
  105. package/dist/normalize/targets.d.ts +8 -0
  106. package/dist/normalize/targets.js +17 -0
  107. package/dist/normalize/tree.d.ts +1 -0
  108. package/dist/normalize/tree.js +151 -0
  109. package/dist/setup.d.ts +1 -0
  110. package/dist/setup.js +149 -0
  111. package/dist/ssr/index.d.ts +10 -0
  112. package/dist/ssr/index.js +103 -0
  113. package/dist/ssr/spec.d.ts +1 -0
  114. package/dist/ssr/spec.js +7 -0
  115. package/dist/targets/angular.d.ts +1 -0
  116. package/dist/targets/angular.js +5 -0
  117. package/dist/targets/astro.d.ts +1 -0
  118. package/dist/targets/astro.js +5 -0
  119. package/dist/targets/qwik.d.ts +1 -0
  120. package/dist/targets/qwik.js +5 -0
  121. package/dist/targets/react.d.ts +1 -0
  122. package/dist/targets/react.js +5 -0
  123. package/dist/targets/solid.d.ts +1 -0
  124. package/dist/targets/solid.js +5 -0
  125. package/dist/targets/svelte.d.ts +1 -0
  126. package/dist/targets/svelte.js +5 -0
  127. package/dist/targets/vue.d.ts +1 -0
  128. package/dist/targets/vue.js +5 -0
  129. package/dist/visual-types.d.ts +92 -0
  130. package/dist/visual-types.js +24 -0
  131. package/package.json +135 -3
package/README.md CHANGED
@@ -1,3 +1,512 @@
1
- # Temporary Holding Version
1
+ # @unframework.dev/testing
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The cross-target test API (plan §7.3, §8.5): one spec, written once, runs in every
4
+ `browser:<target>` project and verifies the shared expectations layer by layer. It stays
5
+ `private` until its first release (ADR-0085). Now published, unframework.dev documents it for users
6
+ (`apps/web/content/docs/4.tooling/5.testing.md`).
7
+
8
+ ```ts
9
+ // cases/state/counter/counter.test.ts
10
+ import { describeTargets, it, mountScenario } from "@unframework.dev/testing";
11
+ import { expect } from "vitest";
12
+
13
+ import Counter from "./Counter.uf.tsx";
14
+
15
+ describeTargets("state/counter", () => {
16
+ it("renders the initial count", async () => {
17
+ const view = await mountScenario(Counter, "initial");
18
+ await view.expectParity("initial"); // L7 DOM + ARIA, L9 (no steps), L10 pixels, L11 axe
19
+ await expect.element(view.getByRole("status")).toHaveTextContent("2"); // L8
20
+ });
21
+
22
+ it("increments and emits the new value", { requires: ["interactivity"] }, async () => {
23
+ const view = await mountScenario(Counter, "initial");
24
+ await view.user.click(view.getByRole("button", { name: "+3" })); // a step of the trace
25
+ await view.expectParity("after-increment"); // L9 compares the step with the trace
26
+ await expect.element(view.getByRole("status")).toHaveTextContent("5");
27
+ expect(view.emitted("change")).toEqual([[5]]);
28
+ });
29
+ });
30
+ ```
31
+
32
+ ## Public API
33
+
34
+ The root entry is the public API, exactly (ADR-0085). `tests/repo/test/testing-api.test.ts` pins
35
+ these names, and the corpus's lint rule (`oxlint.config.ts`, tested by
36
+ `tests/repo/test/corpus-imports.test.ts`) refuses any other import from a spec:
37
+
38
+ - **Runtime:** `describeTargets`, `it`, `test`, `mount`, `mountScenario`, `allowConsole`,
39
+ `capturedConsole` and `currentTarget`.
40
+ - **Types:** `View`, `ViewOptions`, `ComponentMountOptions`, `Props`, `NotAFunction`, `ViewUser`,
41
+ `ClickOptions`, `ViewClock`, `TraceStep`, `SpecOptions`, `SpecTest`, `ParityOptions`,
42
+ `PixelTolerance`, `ConsoleEntry`, `CaseConfig`, `SsrScenario` and `NoAxeViolationsOptions`.
43
+ - **Matchers,** which `./setup` registers: `toHaveNoAxeViolations(options?)` and
44
+ `toHaveAriaTree(expected)` (below).
45
+ - **The case:** its directory, its spec, its main `.uf.tsx`, the generated `__expected__/`, and
46
+ `case.json`'s `ssr`, `axe`, `colorScheme`, `reference` and `main`.
47
+
48
+ The subpaths are internal, for the harness and the test configuration, never for a spec:
49
+
50
+ | Subpath | Holds |
51
+ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
52
+ | `./harness` | The browser machinery: `registerTarget`, `cleanup`, `captureVisual`, `checkLayers`, `LAYERS`, `LayerFailure`, `recordLayer`, `installMatchers`, the layer and adapter types, `HarnessContext` |
53
+ | `./setup` | The setup file every browser project loads first (below) |
54
+ | `./<target>` | The setup file that registers a target's mount adapter |
55
+ | `./node` | The Node side: the browser commands, the write policy, the mode, the reporter and the summary |
56
+ | `./normalize` | The normaliser |
57
+ | `./ssr` | `describeServerRender(cases)`, the one server render comparison (L6, L13), which the corpus's ssr spec calls with its own skips |
58
+ | `./ssr/spec` | The ssr spec `defineTestConfig`'s `ssr:<target>` projects run, by its resolved path |
59
+ | `./cli` | `run(args, io)`, the `unframework test` command, which the umbrella registers |
60
+
61
+ `./config` is public, for a project's `vitest.config.ts`: `defineTestConfig` (below).
62
+
63
+ ## A project's tests (`@unframework.dev/testing/config`)
64
+
65
+ `defineTestConfig(options?)` resolves to the Vitest configuration of a project's tests (ADR-0086):
66
+ one `browser:<target>` project in Chromium and one `ssr:<target>` project for each target of its
67
+ `unframework.config.ts`, built from the pieces the corpus's harness uses. `unframework test`
68
+ (`./cli`) runs it, or the project's own `vitest.config.ts` when it has one.
69
+
70
+ | Option | Default | What it does |
71
+ | --------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
72
+ | `targets` | `unframework.config.ts`'s `targets` | The targets to test |
73
+ | `include` | `["**/*.test.ts"]`, never in `node_modules` or `dist` | The test files, relative to the root |
74
+ | `reference` | `vue` when tested, else the first target | The target that writes `__expected__/`. It always joins the run |
75
+ | `pixels` | `live` | `live` compares with the reference's capture, in CI too, and `baseline` with baselines |
76
+ | `toolchainDirs` | `package.resolveFrom`, then the root | Where each target's compiler stack resolves from (Angular's) |
77
+ | `root` | the working directory | Where `unframework.config.ts` is: case ids are relative to it |
78
+
79
+ - **A case** is a directory with one test file. Its id is its path from the root, and its main
80
+ source is `case.json`'s `main`, relative to the case and maybe outside it, or else its only
81
+ `.uf.tsx` (`discoverCases`, `src/config/cases.ts`). Two test files in one directory, no main
82
+ source, a test file at the root and an unknown `case.json` key throw at startup, naming the fix.
83
+ - **The run** narrows to `UF_TARGETS` (`--target`), always with the reference and any target a
84
+ case names as its own (`runTargets`), and writes with `UF_UPDATE=1` (`--update`). Its scratch
85
+ goes in the root's `.reports/` and `.live/`. Installed under `node_modules`, the package is
86
+ inlined in the ssr projects (`TESTING_PACKAGE`) and left out of the browser projects' dep
87
+ optimizer, so its imports go through the project's Vite pipeline and share one Vitest runner.
88
+ The target packages are inlined in the ssr projects too (`TARGET_PACKAGES`), so a server
89
+ renderer loads the framework copy the component loads, and Qwik's target is left out of the
90
+ dep optimizer, since its mount adapter needs Qwik's plugin. The mode is a project's
91
+ (`resolveHarnessMode({ project })`): pixels compare live unless the project chose `baseline`,
92
+ and CI may compare live. It runs in Chromium alone.
93
+ - **A module that fails to compile fails its own spec alone.** The browser projects keep Vite from
94
+ sending the error to every page they serve (`noErrorBroadcast`, a copy of the harness's), whose
95
+ overlay would cover every later spec's page and capture.
96
+ - **The toolchains, for a host outside the test projects:** `loadToolchain(target)` loads a
97
+ target's toolchain from this package, which depends on every target, and
98
+ `toolchainClientFile(toolchain)` gives its mount adapter's file, so a Vite server can import it
99
+ by path where the project doesn't install the target package. The preview builds its servers
100
+ from them (ADR-0088).
101
+ - **`unframework test [--target <t>]… [--update] [-- <vitest args>]`** passes what follows `--`
102
+ to Vitest, refuses Vitest's `--update`, and exits 0, 1 on a failed test, or 2 on a usage or
103
+ configuration error.
104
+
105
+ ## Browser (`@unframework.dev/testing`)
106
+
107
+ - **`mount(component, { props, clock? })`** mounts with the project's registered adapter into a
108
+ `<div data-uf-root>` in the page's `<body>`, and returns a **`View`**: `container`, a `locator`
109
+ (`page.getByTestId("uf-root-N")`, stable as the DOM changes), `getBy*` queries scoped to the
110
+ container, `html()` (the normalised DOM), `settle()`, `rerender(props)`, `user`, `clock`,
111
+ `emitted(name)`, `events()` and `unmount()`. A component imported from a `.uf.tsx` is typed as its
112
+ authored function, so `props` (and `rerender`'s) are checked against its props type; the untyped
113
+ overload takes what is not a function only (the test stubs).
114
+ - **`mountScenario(component, name, { clock? })`** mounts with `case.json`'s `ssr[name].props`, so a
115
+ browser scenario and its server twin render the same props; the test then checks it with
116
+ `expectParity(name)`. A scenario `case.json` cannot hold (an explicit `undefined`, a rerender) is
117
+ browser-only: mount it with `mount` and say so in a comment.
118
+ - **`view.rerender(props)`** renders the component again with new props, as a parent would,
119
+ and waits until it has settled, as `mount` does. The props are replaced whole: a prop the new
120
+ props lack takes its default again (each adapter's `rerender`, ADR-0043). It records a step
121
+ of the view's trace, `rerender {…props as JSON}`, as an action does.
122
+ - **`toHaveNoAxeViolations(options?)`** runs axe-core on an element with L11's options
123
+ (`src/browser/axe.ts`), and passes on no violation, or on exactly the rules
124
+ `options.expected` lists. **`toHaveAriaTree(expected)`** compares an element's ARIA snapshot,
125
+ taken and normalised as L7 takes a view's (Angular's hosts inline, generated ids renamed), with
126
+ one tree that holds on every target. It ignores the indentation and the blank lines around
127
+ `expected`. Both take `expect.element(locator)` or an element, fail with the target's name (and
128
+ `toHaveAriaTree` with a line diff), and are typed on Vitest's `Matchers`. Vitest's own
129
+ `toMatchAriaSnapshot()` and `toMatchAriaInlineSnapshot()` read the raw tree of one target, and
130
+ stay as they are.
131
+ - **`it(name, { requires }, fn)`** and **`test`** (ADR-0050): Vitest's, plus `requires`, the
132
+ capabilities a test needs (`["interactivity"]`, typed by `CapabilityName`). On a target whose
133
+ cell for one of them is unsupported (Astro's `interactivity`), the setup file skips the test
134
+ before it runs and records `skip(requires <capability>: <the target's reason>)` on L7, L8, L9,
135
+ L10, L11, L13 and L14, and `skipped` on the test's record, so the matrix shows it and the summary
136
+ excuses that test's scenarios on that target alone. The cells come from Node
137
+ (`test.provide.ufCapabilities`), never from importing a target. It refuses `skip`, `only`,
138
+ `todo`, `fails`, `retry`, `repeats`, `concurrent` and `tags`, `requires: []` and an unknown
139
+ capability. Every test of a case the target has no output for (`test.provide.ufNoOutput`, by
140
+ case id, with the errors it expects for the target; the harness gives its spec a stand-in for
141
+ the component) is skipped there the same way, whatever it requires, with `no output: <the
142
+ errors>` on every layer, and the summary excuses it on that target alone. A case the target
143
+ cannot compile yet gets a stand-in too (`test.provide.ufStandIn`, by case id, with the cause,
144
+ ADR-0068). Its tests are not skipped: the setup first records L7, L8, L9, L10, L11, L13 and L14 as
145
+ failed with the cause (`recordStandIn`), and `standIn` on the test's record. The summary
146
+ excuses its scenarios on that target alone, and its cells still fail.
147
+ - **`view.user`** acts as a person does, through Playwright's real input (ADR-0050). An action
148
+ is the inputs a person gives apart in time, each dispatched alone (the `ufInput` command):
149
+ `click(target, { position? })` moves the mouse onto the element (Playwright's hover, which
150
+ waits until it is visible, stable and the element under the point; then a disabled element
151
+ is refused, where Playwright's click would wait until its timeout), then presses and releases
152
+ its main button; `dblClick` and `tripleClick` press and release it two and three times (the
153
+ second release fires `dblclick`); `hover` and `unhover` move the mouse; `type(target, text)`
154
+ focuses the element (Playwright's `locator.focus()`), presses and releases each key of `text`
155
+ in turn, then releases every key still held; `keyboard(text)` presses the keys where the focus
156
+ is (the frame, when nothing has it); `tab` presses and releases Tab, with Shift held for
157
+ `{ shift: true }`, after focusing the frame; `fill` and `clear` focus the field, then fill or
158
+ clear it as Playwright does, in one input; `focus` (the `ufFocus` command) and
159
+ `selectOptions` are one input each; `wheel` moves the mouse onto the element, then turns the
160
+ wheel `times` steps (a `direction` is 100 pixels a step, as Vitest's). In a key text, a
161
+ character types itself, `{Enter}` presses and releases a key as Playwright names it,
162
+ `{Shift>}` holds it (until `{/Shift}`, in this action or a later one) and `{/Shift}` releases
163
+ it, and `{{` and `[[` type a brace and a bracket; a character Playwright's US layout lacks is
164
+ inserted as text, with no key events, as Vitest's keyboard does. The rest of Vitest's keyboard
165
+ syntax (`[KeyA]`, `{a>3}`), a key pressed while held or released while not held, and an empty
166
+ text are refused before any input. Each input runs through the adapter's `interact` (React's
167
+ `act`, Qwik's lazily loaded handlers) and settles until two rounds in a row read the same DOM
168
+ and the same number of emits (at most ten, or L9 fails "did not settle after an input of
169
+ …") before the next is dispatched, as the time between a person's two inputs lets a
170
+ framework that renders in a task of its own render (Angular): dispatched back to back, two
171
+ inputs could land before one such render, and a watcher would be called back once for both,
172
+ or not at all, by chance. So a watcher of a field's text is called back once for each key
173
+ typed, on every target. After the last input the action settles the same way and records one
174
+ step: `{ action, dom, aria, events }`. Each action takes a locator under this view's root
175
+ only (an element, the page's locator, another view's or the root itself is refused: a step
176
+ names its target the same way on every target). An input waits the provider's action timeout
177
+ (5 s), as an assertion waits the poll's. A key a test leaves held is released when it ends.
178
+ On a target that runs no client code an action throws: the test should declare
179
+ `requires: ["interactivity"]`.
180
+ - **`view.clock`**, for a view mounted with `{ clock: true }` (ADR-0050): the page's
181
+ `setInterval` and `clearInterval` are Vitest's fakes, installed before the component mounts,
182
+ so its intervals fire only when the spec advances the clock. `view.clock.tick(ms)`, a positive
183
+ whole number of milliseconds, runs every interval due on the way one at a time, as real time
184
+ would: each fires alone, in a task of its own, through the adapter's `interact`, and the view
185
+ then settles as after an action (until two rounds read the same DOM and emits) before the
186
+ next is due. So a framework that renders in a task of its own (React, Angular, Qwik) renders
187
+ between two intervals, and a watcher calls back once for each; intervals due at the same
188
+ moment run one after another, settled between them. Writes in two tasks with no render
189
+ between them are outside the contract, and the clock never makes them. The tick records one
190
+ step, `tick <ms>ms`, holding what every interval did. After an unmount it advances the clock
191
+ the same way, settling the page after each interval, but records no step: `view.emitted` then
192
+ shows what an interval the component failed to stop emitted. The tick reads the due times
193
+ from Vitest's fake clock (`setInterval.clock`), and fails if it no longer can. More than 1000
194
+ intervals in one tick (an interval of no time) fail it, as Vitest's own advance does.
195
+ `Date`, `performance`, `setTimeout` and the frames stay real: no framework's
196
+ scheduler calls `setInterval`, and Vitest's own waits keep the timers it saved at startup. The
197
+ clock is the page's, so one view of a test may have one (a second throws before it mounts); a
198
+ tick throws for a view mounted without one, and on a target that runs no client code. The
199
+ setup gives the page its real intervals back when the test ends, after the unmount, so a
200
+ teardown clears its interval on the clock that set it.
201
+ - **`view.emitted(name)`** gives the arguments of each emit of a declared event, in order
202
+ (`[[5]]`); **`view.events()`** every emit as `[name, ...args]`. The adapter listens to exactly
203
+ the events the component declares, which the project's own compile of the case's main source
204
+ reports (`ufComponentEvents`; a stub registers its own). Each emit's arguments are copied as plain
205
+ data when they arrive, after trailing `undefined` arguments are dropped (a listener cannot
206
+ tell them from absent ones): a function, any other `undefined`, a non-finite number, a `Map`
207
+ or `Set`, a DOM event or node, or a class instance fails the test at the next settle, naming
208
+ the event and where in its payload. Generated ids (`uf-id-…`) are renamed as `html()` renames them,
209
+ wherever they stand in a string. Both
210
+ throw for an event the component does not declare, and on a target that runs no client code.
211
+ - **L9, interaction traces.** `expectParity(name)` compares the steps since the mount or the
212
+ previous `expectParity` with `__expected__/trace.<name>.json` (the reference writes it, every
213
+ other target must match), then forgets them. With no step, the file must not exist and L9
214
+ records `skip(no scripted interaction)`. A step no `expectParity` compares fails L9 when the
215
+ test ends. The file is pretty JSON, `{ "version": 1, "steps": [...] }`, each step's `dom` and
216
+ `aria` a list of lines and its `events` grouped by name (names sorted, each name's emits in
217
+ order: the order of different effects one run triggers is not part of the contract).
218
+ - **`view.expectThrown(step)`** runs a `view.user` step that makes the component throw, and records
219
+ L14: the first `Error`'s top frame in the case must map to the line of the case's source that
220
+ holds `throw` (ADR-0078). What the step logs is excused from L13, and it leaves no step for L9.
221
+ - **`view.expectParity(name, { tolerance? })`** settles, then verifies the scenario against the
222
+ case's shared expectations: L7 (`__expected__/dom.<name>.html` and Playwright's
223
+ `aria.<name>.yaml`), L9 (`trace.<name>.json`, below), L10 (geometry and computed styles, then pixels, through
224
+ `ufVisualCapture`) and L11 (axe-core on the container: no violations, or exactly
225
+ `case.json`'s `axe` list). Each layer and the scenario are recorded in `task.meta.uf`, and it
226
+ resolves even when a layer fails, so the test's own assertions after it run too (L8); the
227
+ setup file then fails the test with every failed layer. Only a misuse rejects (a name that is
228
+ not kebab-case or that the spec checked already, a tolerance without a reason). No landmark wraps the mount root, so a
229
+ component may render its own `<main>`; axe's `region` rule (all content inside landmarks) is
230
+ off, because placing a component in the page's landmarks is the page's job.
231
+ - **L10 captures what styles change.** Each element records its border box and 68 computed
232
+ properties (`GEOMETRY_STYLE_PROPERTIES`), offsets, `text-shadow` and `outline-offset` among
233
+ them, and each text run its line boxes. A `::before` or `::after` whose `content` is not
234
+ `none` is keyed `<path>::before` or `<path>::after`, with the same properties and `content`,
235
+ and no box: the DOM gives it none. `filter` is left out, so the `L10-root-inverted` canary
236
+ proves the pixel comparison alone (ADR-0061).
237
+ - **L10 sees each run of text as one node.** Frameworks split one run of text into DOM text
238
+ nodes differently (`Price: {price} EUR` is three nodes on React, Solid and Qwik, one on Vue,
239
+ and Vue splits a text branch from the text beside it), and Chromium starts each node at a
240
+ 1/64 px edge, which moves later glyphs by a fraction of a pixel. So for the capture (geometry
241
+ and pixels) every run of adjacent text nodes in the mount root, comments between them
242
+ included, is merged into its first node, never across an element, then restored: the same
243
+ nodes, with their data, so a framework's references stay valid (ADR-0044). L7 already reads a
244
+ run as one text.
245
+ - **L10 never depends on what was repainted before it.** By default Chromium re-rasterises only
246
+ a repainted rect, rounded out to whole pixels, over the tile's old pixels, so a control that
247
+ starts mid-pixel takes in the anti-aliased corner of the box beside it, which then rasterises
248
+ one level apart: the same DOM captured differently after a hover, a press or a keystroke
249
+ repainted one control. The parity projects launch Chromium with `--disable-partial-raster`,
250
+ which rasterises every repainted tile whole, so a capture is a function of the DOM. Firefox and
251
+ WebKit have no such switch, and compare live within their engine (ADR-0066).
252
+ - **L10 follows the environment.** In Chromium, in CI and in the baseline environment (the Playwright image
253
+ `pnpm test:baselines` runs, `BASELINE_ENVIRONMENT`) it compares with the committed
254
+ `__expected__/geometry.<name>.json` and `__screenshots__/<name>-chromium-linux.png`, and only
255
+ that environment writes them. Elsewhere, any Linux host and any run in Firefox or WebKit
256
+ included (CI too, `UF_BROWSER`), it compares each target with
257
+ the reference's capture from the same run, and records the reference's own L10 as a skip:
258
+ nothing was compared. Pixels differ between hosts, and so does geometry once a case has form
259
+ controls (a text input is 160px wide on macOS and 200px on Linux). The font audit walks the
260
+ user-agent shadow roots and generated content, so a `<textarea>`'s text is checked too.
261
+ - **L10 names a reference that didn't finish.** A follower with no capture to compare with fails
262
+ `missing-reference-capture`, unless the case's reference has a browser project in the run that
263
+ didn't finish the case's spec file (the setup file reports each finished file through
264
+ `ufSpecFinished`). Then its L10 is `skip(reference not run: <project> …)`, and the summary
265
+ reports one problem for that project, with the errors Vitest reported outside every test, in
266
+ place of one per cell (ADR-0091).
267
+ - **L10 is one code path for cases and examples (ADR-0087).** `captureAt(context, request,
268
+ location)` in `./node` runs the font audit, the capture, the policy and the comparison at a
269
+ `CaptureLocation`: the baselines, where the reference publishes its live capture, where a
270
+ failure's images go, where every capture goes (none for a case) and the command that writes the
271
+ baselines. `ufVisualCapture` builds a case's location (`caseCaptureLocation`), and
272
+ `@unframework.dev/visual`'s `ufExampleCapture` an example's. In the browser, `captureVisual`
273
+ (`./harness`) takes the command it sends to, `ufVisualCapture` by default. A failed comparison's
274
+ result carries its geometry `deltas`, and a location that keeps every capture its `capture` path.
275
+ - **`describeTargets`**, **`currentTarget`**, **`allowConsole(pattern, reason)`** (for the
276
+ current test, every matching message, whatever the pattern's flags), and
277
+ **`registerTarget(target, mount, { events? })`** for the per-target setup files (`events`
278
+ reads a stub component's declared events, which no compile reports).
279
+ - **The mount contract** (`@unframework.dev/codegen`'s toolchain types): `MountOptions.on` holds a
280
+ listener per declared event, by the source's name, and `MountOptions.events` the events'
281
+ payload shapes; each adapter passes the listeners as its framework's consumer would (React's
282
+ and Solid's `onChange`, Vue's `onChange` beside the props, Svelte's `onchange`, Angular's
283
+ `outputBinding("change")` with the payload spread back by its shape, Qwik's `onChange$` QRL,
284
+ none on Astro) and keeps them across `rerender`. `MountedComponent.interact(action)` runs a
285
+ user's action the framework's way. `MountOptions.renderCommand` is how a host outside Vitest
286
+ reaches a server render (Astro's, ADR-0088). The test projects leave it out, so Astro's
287
+ adapter calls its Vitest command.
288
+
289
+ ## Writing a spec
290
+
291
+ Every spec of the corpus follows these rules, which L8, L9 and their canaries rely on
292
+ (ADR-0043, ADR-0050); `harness/cases.ts` checks the ones a spec's text shows:
293
+
294
+ - Every test calls `expectParity` (after its interactions, if it has any), then asserts at
295
+ least one positive fact about what it rendered, through the view's queries
296
+ (`await expect.element(view.getByText("…")).toBeVisible()`, `view.getByRole(…)`); emits are
297
+ checked with `view.emitted`/`view.events`. A test without assertions fails L8
298
+ (`expect.requireAssertions` in the browser projects); a test that only asserts absence
299
+ (`not.toBeInTheDocument()`) passes even when the component renders nothing, so it proves
300
+ nothing. A test that requires nothing asserts first through a locator (`expect.element`,
301
+ `expect.poll`), so a render of nothing fails it as a query that finds nothing.
302
+ - A test asserts after `expectParity`: between a step (a `view.user` action, a `rerender` or a
303
+ `clock.tick` of a mounted view) and the `expectParity` that compares it, it asserts nothing,
304
+ and it ends with no step uncompared. A step that acts on what an earlier step's handler alone
305
+ renders, or follows a submission or a link a handler must prevent, comes after an
306
+ `expectParity` of the earlier step. So a step whose handler is missing fails L9 before a later
307
+ action or assertion can abort the test.
308
+ - A test declares `requires: ["interactivity"]` (and any option capability it relies on) when
309
+ an expectation depends on client code: an action, an emit, a mounted state that a lifecycle
310
+ hook, a watcher or `watchEffect` changed, or state or consts surviving a rerender.
311
+ - At least one test of a case checks a scenario before it acts, and requires nothing, unless the
312
+ case's mount-time client code changes the DOM: then every test requires `interactivity`, the
313
+ server render (L6) checks a static target, and `case.json` says why in its `requires` note.
314
+ - A spec acts only through `view.user`: never `userEvent`, `page` or a locator's own actions,
315
+ which bypass the adapter, the settling and the trace.
316
+ - A test whose component starts an interval mounts with `{ clock: true }` and moves time only
317
+ with `view.clock.tick(ms)`, so each tick's work is a step of its own on every target, however
318
+ loaded the machine. Any other timer runs in real time: a spec that waits for it asserts with
319
+ `expect.poll`, a fixed wait only proves that nothing more happens (after an unmount), and no
320
+ `expectParity`, step or action comes while such a timer that changes the DOM or emits can
321
+ fire: it starts from an action after the first `expectParity`, and stops (or the view
322
+ unmounts) before the next.
323
+ - A DOM read that feeds state or an emit reads what layout does not decide (`textContent`,
324
+ attributes, `value`, `document.activeElement`), never geometry.
325
+ - No spec reorders a list, or replaces a row's item, while the focus is inside the list: keyed
326
+ identity on reorder is not guaranteed yet.
327
+ - Specs never branch on the target (`currentTarget()`): every target runs the same checks.
328
+ - Test names and scenario names are unique in the case; scenario names are kebab-case string
329
+ literals; a scenario with an SSR twin mounts with `mountScenario`. The summary fails a target
330
+ whose tests check other scenarios than the reference's, test by test.
331
+ - Assertions go in the test body. A spec needs no hooks; one of its `afterEach` hooks that throws
332
+ is recorded as L8.
333
+
334
+ ## Setup files
335
+
336
+ - **`@unframework.dev/testing/setup`**, loaded first by every browser project: the bundled Inter font
337
+ as "UF Test Sans", the motion and caret reset, the startup assertions (DPR 1, reduced motion,
338
+ and the case's colour scheme: `case.json`'s `colorScheme`, `light` by default, which the file
339
+ emulates through `ufColorScheme` before anything mounts, ADR-0061, and which the check reads
340
+ again for at most 5 s, since Firefox can apply it late, ADR-0081), console capture recorded
341
+ as **L13** for every test of a case (plus the adapter's server-side console, at mount and at
342
+ each rerender), and cleanup (the unmount, then the real intervals back if a view had a clock).
343
+ The capture starts
344
+ when the file loads and discards nothing: a message logged while the modules evaluate or in a
345
+ `beforeAll` hook fails the next test, marked as logged before it; the console is judged after
346
+ the unmount's scheduled work has run; and a message after a file's last test fails the file.
347
+ It gives every `expect.element` without a timeout the project's `expect.poll.timeout`, which
348
+ the project must set: Vitest 5 would otherwise wait for the whole test's timeout.
349
+ After L13 it records **L8**, the spec's own behaviour: failed with the test's own errors (its
350
+ assertions, its hooks, Vitest's "no assertion" error, a failed unmount), but not a
351
+ `LayerFailure`, and then fails the test with one error holding every other failed layer (L8's
352
+ errors Vitest reports already). When L8 is quarantined, the test's own errors are removed from
353
+ its result, which passes unless another layer failed. An `aroundEach` judges a test whose
354
+ afterEach hooks a throwing spec hook stopped.
355
+ Before each test it skips one whose `requires` names a capability the target lacks, recording
356
+ why on every browser layer (above). It installs a navigation guard: a form submission or a
357
+ link the component does not prevent is prevented by a bubbling listener on `window`, which runs
358
+ after every framework's, and fails L8 at the next settle, rather than taking the spec file's
359
+ frame away. After each test it fails L9 with the steps no `expectParity` compared, and resets
360
+ the input for the next test (`ufResetInput`: the mouse to the frame's corner, the keys
361
+ released, the focus blurred and the frame focused again). It registers the matchers above.
362
+ - **`@unframework.dev/testing/<target>`** (`react`, `vue`, `svelte`, `solid`, `angular`, `qwik`,
363
+ `astro`): registers `@unframework.dev/target-<target>/toolchain/client`'s mount adapter.
364
+
365
+ ## Node (`@unframework.dev/testing/node`)
366
+
367
+ - **The write policy** (DESIGN §4.4), as plain functions every driver shares:
368
+ `settleArtefact(path, actual, context)` and `settleArtefactDirectory(dir, files, context)`.
369
+ Check mode compares and never writes; in update mode owners and the reference target write,
370
+ and followers compare against what the reference wrote in the same run (a per-run ledger).
371
+ A case's `case.json` may name its own reference (`reference`, ADR-0057): that target writes
372
+ the case's shared artefacts and its pixels, publishes its live capture, and its scenarios are
373
+ the ones every target's must check (`caseReference`, `sharedArtefactContext(harness, target,
374
+ case)`); its projects run after the run's reference and before every other target
375
+ (`groupOrder`'s `caseReferences`).
376
+ - **The run:** `resolveHarnessMode` (`UF_UPDATE`, `UF_PIXELS`, `UF_CANARY`,
377
+ `UF_BASELINE_ENVIRONMENT`, `UF_BROWSER`; it refuses writing in CI, and writing the visual
378
+ baselines outside `BASELINE_ENVIRONMENT`; with `UF_BROWSER=firefox` or `webkit` it compares
379
+ pixels live, in CI too, and refuses writing anything, because every committed artefact is
380
+ Chromium's, ADR-0066), `createHarnessRun` (the context provided to every project as
381
+ `ufHarness`; each run's scratch output is its own directory, so concurrent runs never clear
382
+ each other's; an L10 quarantine entry that names `pixels` applies only in runs of that pixel
383
+ mode) and `groupOrder`, which in Firefox and WebKit, with live pixels, gives each browser project
384
+ a group of its own: the reference at 1, then `caseReferences`, then each other target in the
385
+ order of the target list it takes (ADR-0081).
386
+ - **Browser commands:** `browserCommands` (`ufArtefact`, which settles `dom.`, `aria.` and
387
+ `trace.<name>.*`, a trace with no contents being one that must not exist; `ufAriaSnapshot`,
388
+ `ufVisualCapture`, `ufFocus`, `ufInput` (one input of a `view.user` action: a hover, a mouse
389
+ button's press or release, a wheel step, a key's press or release), `ufResetInput`,
390
+ `ufColorScheme` (Playwright's `emulateMedia` with the case's `prefers-color-scheme`), and
391
+ `ufComponentEvents`, which answers from the
392
+ compiles a project's unplugin reported to `recordCompiledModule`, for the case's only source or
393
+ the one its `case.json` names as `main`, ADR-0057), and
394
+ `parityBrowser({ name, commands, browser })`, the deterministic Chromium every parity project
395
+ runs (800×600 at DPR 1, `--font-render-hinting=none`, `--disable-partial-raster`, light scheme
396
+ until a case opts into dark, reduced motion, a 5 s action timeout). `browser: "firefox"` or
397
+ `"webkit"` runs that engine in the same context, without Chromium's switches, and L10 skips
398
+ its font audit there (`FONT_AUDIT_SKIP`: the audit reads CDP). A target's command may not
399
+ take one of the testing API's names.
400
+ - **Layers:** `checkLayers(task, subject, { L1: () => …, L2: … })` runs checks, records each
401
+ outcome and throws one error with every failure (`expectParity` records the same way without
402
+ throwing). A check skips only by returning
403
+ `{ skip: reason }` with a reason. A failure the quarantine covers is recorded as quarantined;
404
+ a pass under an entry is recorded as a pass, because a quarantine entry is judged per
405
+ (case, target, layer) cell, over every test that records it.
406
+ - **The parity matrix:** `ParityReporter` writes `parity-matrix.<run>.json` (version 5), with
407
+ each project's cells and parity scenarios, and each test's, by its name without the target
408
+ (`testKey`): the scenarios it checked, or why it was skipped by capability or ran against a
409
+ stand-in (`tests`); and what
410
+ a test file recorded after its last test, the run's mode, its reference target and when it
411
+ ended. It fails the run when a selected project collected no tests, when a test was skipped
412
+ without recording why, when two tests of a case share a name, and, once a run has every record
413
+ of a cell, on a stale quarantine entry. A run of some projects replaces exactly those projects' records in earlier
414
+ matrices; a filtered run (files, test names, tags, `--changed`, `related`, watch mode) or a
415
+ shard replaces nothing. A shard covers its projects in full only together with shards 1 to n
416
+ of the same selection and count, with no other filter; the summary then also fails a project
417
+ no shard collected a test of. `writeSummary` merges the partial
418
+ matrices into `parity-matrix.json` and `parity-matrix.md`, or `parity-matrix.<engine>.*` for
419
+ `browser: "firefox"` or `"webkit"` (`summaryName`), which `isPartialMatrixFile` never reads
420
+ back (each project's cells from its last
421
+ run, the runs listed, every record judged by the newest run's quarantine) and appends the
422
+ Markdown to `$GITHUB_STEP_SUMMARY`; in CI (or with `requireComplete`) a project that did not
423
+ run, or that only filtered runs or an incomplete set of shards ran, is a problem, not a partial
424
+ run, and `since` restricts it to the runs that ended since a time. Judged like the missing
425
+ cells, a target whose tests check other parity scenarios than the reference's, test by test,
426
+ is a problem (every target runs the same spec), except for a test it skipped by capability or
427
+ for want of output, or ran against a stand-in. A skip on a live layer must name a capability
428
+ the target lacks (`requires <name>: …`, the name one of `SummaryExpectations.capabilities`) or
429
+ a mechanical cause: no output (`compile errors: no output` for the layers of a compile with
430
+ errors, and `no output: <the expected errors>` for a browser test of such a case), no spec (the
431
+ browser layers of a diagnostics case its target has output for), the live reference, a
432
+ component that did not render (L6), no scripted interaction. A live layer only one project
433
+ records (`SummaryExpectations.recordedOnlyBy`) reads `skip(not in this run)` in a run without
434
+ that project in full, unless every project must have reported. The Markdown lists each test a
435
+ target skipped, by capability or for want of output, or ran against a stand-in, under its
436
+ case's table.
437
+
438
+ ## Normalisation (`@unframework.dev/testing/normalize`)
439
+
440
+ `normalizeHtml(html, { target })` turns any target's HTML into one canonical text (plan §7.5).
441
+ A `class` with no token and a `style` with no declaration go, and so does a declaration with an
442
+ empty value; declarations are sorted by property unless the order of two of them decides what
443
+ renders (`@unframework.dev/ir`'s `cssPropertiesOverlap`: the same property, a shorthand and its
444
+ longhand, a flow-relative longhand and a physical one), as frameworks disagree on these
445
+ even with themselves (ADR-0044). Class tokens keep their duplicates: a doubled class means a
446
+ broken merge. A boolean attribute's `="true"` is written empty on Qwik only, whose client writes
447
+ an attribute that is on that way. With `engine: "firefox"`, a `-moz-box-orient` declaration takes
448
+ the name Chromium serialises, `-webkit-box-orient` (rule 3b): Firefox writes the property it
449
+ parsed under its own alias, and its value still compares. No other engine, `-moz-*` property or
450
+ value is touched (ADR-0081). The browser API passes the run's engine. Without one, nothing is
451
+ renamed.
452
+ Only the named target's framework noise is removed (Angular's hosts only from Angular's
453
+ output, Qwik's `preventdefault:`, `stoppropagation:` and `capture:` dispatch attributes and its
454
+ `q:template` elements, where its server render keeps a slot's unclaimed fallback, and its
455
+ `<style q:style>` elements, where its server render writes a `useStyles$` sheet that its client
456
+ writes in `<head>`, only from Qwik's, React's stale `checked` and `selected` attributes only from
457
+ React's, and the space Playwright's ARIA snapshot puts at an Angular host only from Angular's
458
+ snapshot); without a
459
+ target nothing is noise. On every target, the markup of a control's initial state is left out
460
+ where its live state, a `uf:*` pseudo-attribute, says the same (rule 4d): an `<input>`'s `value`
461
+ that equals its `uf:value`, an `<input>`'s `checked` where `uf:checked` is `"true"`, an
462
+ `<option>`'s `selected` where `uf:selected` is `"true"`, and a `<textarea>`'s text that equals its
463
+ `uf:value`, since each repeats the state (react-dom writes a controlled control's state as markup,
464
+ Vue's `v-model` does not); markup that differs stays (ADR-0058). On React only, a `checked` or
465
+ `selected` goes wherever its `uf:*` state is there, whatever it says (rule 4e): react-dom writes a
466
+ box's first state as its attribute and never updates it, and the state still compares. On Angular
467
+ only, the view takes the ARIA snapshot with each host set to `display: inline`, so the host adds no
468
+ space, and then puts the hosts' `style` back; a host among flex or grid items stays as it is
469
+ (`inlineHosts`, ADR-0060). Generated ids are the compiler's `uf-id-…` ids, by
470
+ provenance (the analyzer rejects an authored id or reference with the prefix): each one, a
471
+ `uf-id-` and the characters the frameworks' ids use, is renamed `uf-id-1`, `uf-id-2`… by first
472
+ appearance wherever it appears, in every attribute value (a radio group's `name`, a `data-*`
473
+ value, an idref, a `#id` URL) and every text node, and the ARIA snapshots and payloads of the
474
+ same step take the DOM's renaming (ADR-0049). An author's suffix (`${id}-1`) makes another id,
475
+ so two ids that collide on one target still differ from the reference; authored ids are never
476
+ renamed. Whitespace collapses as Chromium lays it out, rubies
477
+ and bidi isolates included; a whitespace text that collapses away beside a ruby stays, printed
478
+ as `""`, because Chromium's ruby layout still sees it. Where a table-internal box (a bound
479
+ `display: table-cell`, say) sits in an inline box, Chromium wraps it in an anonymous inline
480
+ table, which the model does not build: that line keeps its whitespace as written, so outputs
481
+ that write it differently differ. The static reading takes `display`, `position`, `float`,
482
+ `unicode-bidi` and `white-space` from the inline style and the user-agent defaults; on a live
483
+ subtree `normalizeDom` takes them from Chromium's computed styles instead, so a stylesheet
484
+ counts, except where Chromium computes a value the element does not lay out by (a replaced
485
+ element or `<br>` computing `inline`, `<wbr>`, SVG children, raw text, a `<textarea>`'s value, a
486
+ `<select>`'s `white-space`), ADR-0061. `serializeDom` and `normalizeDom` read a
487
+ live subtree, form-control state included, and mark the element that has the focus
488
+ `uf:focused` (Playwright's default ARIA snapshot never shows it), so L7 and L9 see where the
489
+ focus is; `normalizeDom` throws on a live element, attribute
490
+ or text that the HTML parser would rebuild differently (an SVG child created in the HTML
491
+ namespace, `viewbox`, a table row without its `<tbody>`, a carriage return).
492
+
493
+ ## Tests
494
+
495
+ `pnpm test` runs the unit tests in Node, the DOM tests in Chromium, and then the parity suite
496
+ (`test/parity/`): the browser API end to end against a framework-free stub target, with its
497
+ own committed artefacts and the corpus's `requireAssertions`. Its self-tests that expect a
498
+ layer to fail consume the failure with `expectLayerFailure(layer, pattern)`
499
+ (`src/browser/behaviour.ts`, not exported: a corpus spec quarantines a known failure instead);
500
+ the `stub/behaviour*` cases prove L8's pass, failure, quarantine, staleness and assertion rule,
501
+ and `test/behaviour.test.ts` reads the matrix they make. A stub with `setup` has behaviour
502
+ (listeners that change its DOM and emit its declared `emits`): `stub/interactions` proves
503
+ `view.user`, the settling (after each input too, against a stub whose render comes in a later
504
+ task, as Angular's: a stub's `settle` waits for its scheduled work), `emitted`/`events`,
505
+ payload copies, focus, the navigation guard, L9's
506
+ pass and skip and a step left at the end of a test; `stub/trace-mismatch` an L9 diff and a stale
507
+ trace; `stub/requires` a capability skip (the stub lacks a list box), which
508
+ `test/interactions.test.ts` reads in the matrix. The DOM tests also run Astro's mount
509
+ adapter, whose rerender needs the toolchain's render command (`vitest.config.ts`).
510
+ `UF_UPDATE=1 pnpm exec vitest run --config test/parity/vitest.config.ts` rewrites the artefacts.
511
+
512
+ The `stub/matchers` case proves each matcher passes and fails with its message, and that Vitest's own `toMatchAriaInlineSnapshot` still behaves as Vitest's once the setup has run.
@@ -0,0 +1,34 @@
1
+ import axe from "axe-core";
2
+ //#region src/browser/axe.ts
3
+ /**
4
+ * axe runs on the mount container, so its page-level rules (one `<main>`, a level-one heading,
5
+ * a bypass block) do not apply: they need the whole page as their context. `region` (all
6
+ * content inside landmarks) is the page's structure too: the page that renders a component
7
+ * places it in its landmarks, which the component cannot do for itself, so it is off. Every
8
+ * rule about the component's own markup, its own landmarks included, stays on.
9
+ */
10
+ const AXE_OPTIONS = {
11
+ resultTypes: ["violations"],
12
+ rules: { region: { enabled: false } }
13
+ };
14
+ /**
15
+ * Runs axe-core on `element` with L11's options, and compares the rules it reports with
16
+ * `expected`, the rule ids the element is known to break (case.json's `axe` for L11).
17
+ */
18
+ async function compareAxe(element, expected) {
19
+ const results = await axe.run(element, AXE_OPTIONS);
20
+ const actual = [...new Set(results.violations.map((violation) => violation.id))].toSorted();
21
+ const wanted = [...new Set(expected)].toSorted();
22
+ if (actual.join("\n") === wanted.join("\n")) return {
23
+ pass: true,
24
+ unexpected: [],
25
+ missing: []
26
+ };
27
+ return {
28
+ pass: false,
29
+ unexpected: results.violations.filter((violation) => !wanted.includes(violation.id)).map((violation) => ` ${violation.id} (${violation.impact ?? "no impact"}): ${violation.help} at ${violation.nodes.map((node) => node.target.join(" ")).join(", ")}`),
30
+ missing: wanted.filter((id) => !actual.includes(id))
31
+ };
32
+ }
33
+ //#endregion
34
+ export { compareAxe };
@@ -0,0 +1,59 @@
1
+ import { formatError } from "../errors.js";
2
+ import { LAYERS, LayerFailure, recordLayer } from "../layers.js";
3
+ import "vitest";
4
+ //#region src/browser/behaviour.ts
5
+ /** The error Vitest records for a test without assertions under `expect.requireAssertions`. */
6
+ const NO_ASSERTIONS = "expected any number of assertion, but got none";
7
+ /** The layer failures each test consumed with `expectLayerFailure`. */
8
+ const consumed = /* @__PURE__ */ new WeakMap();
9
+ /**
10
+ * Records L8 and decides how the test ends; the setup file's afterEach calls it last, after
11
+ * L13. L8 fails with the test's own errors: what its body, its hooks and Vitest's assertion
12
+ * count threw, but not a `LayerFailure` (a layer's own record), plus a failed unmount.
13
+ *
14
+ * - When L8 is quarantined, the test's own errors are removed from its result, which passes if
15
+ * no other layer failed (Vitest recorded them before the afterEach hooks ran).
16
+ * - Then it throws one `LayerFailure` with every failed layer but L8, whose errors Vitest
17
+ * reports already (a failed unmount, which it never saw, is added).
18
+ *
19
+ * `late` are the test's own failures that Vitest never saw either: what the page refused after
20
+ * the test's last settle (a navigation the component did not prevent).
21
+ */
22
+ function judgeTest(task, subject, unmountError, late = []) {
23
+ const errors = task.result?.errors ?? [];
24
+ const own = errors.filter((error) => error.name !== "LayerFailure");
25
+ const messages = own.map(describeTestError);
26
+ const unseen = [...unmountError === void 0 ? [] : [`Unmounting failed: ${formatError(unmountError)}`], ...late];
27
+ const recorded = recordLayer(task, subject, "L8", messages.length || unseen.length ? {
28
+ status: "fail",
29
+ message: [...messages, ...unseen].join("\n")
30
+ } : { status: "pass" });
31
+ const skipped = consumed.get(task) ?? /* @__PURE__ */ new Set();
32
+ const layers = task.meta.uf?.layers ?? {};
33
+ const failures = LAYERS.flatMap((layer) => {
34
+ const outcome = layers[layer];
35
+ return layer !== "L8" && !skipped.has(layer) && outcome?.status === "fail" ? [`${layer}: ${outcome.message}`] : [];
36
+ });
37
+ if (recorded.status === "quarantined" && task.result) {
38
+ const kept = errors.filter((error) => !own.includes(error));
39
+ task.result.errors = kept.length ? kept : void 0;
40
+ if (!kept.length && !failures.length) task.result.state = "pass";
41
+ } else if (recorded.status === "fail" && unseen.length) failures.push(...unseen.map((message) => `L8: ${message}`));
42
+ if (failures.length) throw new LayerFailure(subject, failures);
43
+ }
44
+ /** Terminal colours, which Vitest's element errors carry. */
45
+ const ANSI_COLOUR = /\u001b\[[0-9;]*m/g;
46
+ /** The page's HTML that Vitest prints after an element error: L7 records the DOM already. */
47
+ const PAGE_HTML = /\n+HTML:\n[\s\S]*$/;
48
+ /**
49
+ * One error of the test, for the L8 record: its name and message, as plain text, without the
50
+ * page's HTML that an element error appends (its ARIA tree stays, which says what was there).
51
+ */
52
+ function describeTestError(error) {
53
+ const message = error.message.replace(ANSI_COLOUR, "");
54
+ if (message === NO_ASSERTIONS) return "The test asserted nothing: every test asserts at least one fact about what it rendered (expect.requireAssertions).";
55
+ const name = error.name ?? "Error";
56
+ return `${name}: ${name === "VitestBrowserElementError" ? message.replace(PAGE_HTML, "") : message}`;
57
+ }
58
+ //#endregion
59
+ export { judgeTest };