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