@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.
- package/README.md +536 -2
- package/dist/browser/axe.js +34 -0
- package/dist/browser/behaviour.js +59 -0
- package/dist/browser/capabilities.js +58 -0
- package/dist/browser/clock.d.ts +17 -0
- package/dist/browser/clock.js +69 -0
- package/dist/browser/console.d.ts +27 -0
- package/dist/browser/console.js +142 -0
- package/dist/browser/determinism.js +108 -0
- package/dist/browser/element-timeout.js +28 -0
- package/dist/browser/events.js +68 -0
- package/dist/browser/geometry.js +135 -0
- package/dist/browser/keys.js +62 -0
- package/dist/browser/matchers.d.ts +39 -0
- package/dist/browser/matchers.js +78 -0
- package/dist/browser/navigation.js +38 -0
- package/dist/browser/parity.d.ts +10 -0
- package/dist/browser/parity.js +93 -0
- package/dist/browser/spec.d.ts +25 -0
- package/dist/browser/spec.js +38 -0
- package/dist/browser/target.d.ts +16 -0
- package/dist/browser/target.js +27 -0
- package/dist/browser/text-runs.js +68 -0
- package/dist/browser/thrown.js +71 -0
- package/dist/browser/trace.d.ts +21 -0
- package/dist/browser/trace.js +73 -0
- package/dist/browser/user.d.ts +45 -0
- package/dist/browser/user.js +184 -0
- package/dist/browser/view.d.ts +114 -0
- package/dist/browser/view.js +282 -0
- package/dist/browser/visual.d.ts +20 -0
- package/dist/browser/visual.js +36 -0
- package/dist/cli.d.ts +23 -0
- package/dist/cli.js +90 -0
- package/dist/commands.d.ts +107 -0
- package/dist/config/broadcast.js +29 -0
- package/dist/config/cases.d.ts +28 -0
- package/dist/config/cases.js +94 -0
- package/dist/config/index.d.ts +82 -0
- package/dist/config/index.js +295 -0
- package/dist/config/project-vite.d.ts +40 -0
- package/dist/config/project-vite.js +152 -0
- package/dist/diff.d.ts +14 -0
- package/dist/diff.js +92 -0
- package/dist/dom/serialize.js +236 -0
- package/dist/errors.d.ts +13 -0
- package/dist/errors.js +38 -0
- package/dist/harness.d.ts +189 -0
- package/dist/harness.js +53 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +12 -0
- package/dist/internal.d.ts +8 -0
- package/dist/internal.js +6 -0
- package/dist/layers.d.ts +183 -0
- package/dist/layers.js +241 -0
- package/dist/node/browser.d.ts +33 -0
- package/dist/node/browser.js +64 -0
- package/dist/node/commands.d.ts +137 -0
- package/dist/node/commands.js +139 -0
- package/dist/node/context.d.ts +28 -0
- package/dist/node/context.js +55 -0
- package/dist/node/events.d.ts +25 -0
- package/dist/node/events.js +50 -0
- package/dist/node/finished.d.ts +12 -0
- package/dist/node/finished.js +28 -0
- package/dist/node/index.d.ts +21 -0
- package/dist/node/index.js +20 -0
- package/dist/node/matrix.d.ts +219 -0
- package/dist/node/matrix.js +309 -0
- package/dist/node/mode.d.ts +103 -0
- package/dist/node/mode.js +204 -0
- package/dist/node/names.d.ts +4 -0
- package/dist/node/names.js +5 -0
- package/dist/node/policy.d.ts +44 -0
- package/dist/node/policy.js +140 -0
- package/dist/node/reporter.d.ts +101 -0
- package/dist/node/reporter.js +251 -0
- package/dist/node/summary.d.ts +99 -0
- package/dist/node/summary.js +352 -0
- package/dist/node/thrown.js +78 -0
- package/dist/node/viewport.d.ts +7 -0
- package/dist/node/viewport.js +8 -0
- package/dist/node/visual.d.ts +85 -0
- package/dist/node/visual.js +373 -0
- package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/protocol.d.ts +23930 -0
- package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/structs.d.ts +22 -0
- package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/types.d.ts +22221 -0
- package/dist/normalize/display.js +309 -0
- package/dist/normalize/index.d.ts +34 -0
- package/dist/normalize/index.js +38 -0
- package/dist/normalize/pipeline.d.ts +19 -0
- package/dist/normalize/pipeline.js +45 -0
- package/dist/normalize/print.js +103 -0
- package/dist/normalize/rules/angular-hosts.js +53 -0
- package/dist/normalize/rules/aria-hosts.js +48 -0
- package/dist/normalize/rules/comments.js +16 -0
- package/dist/normalize/rules/control-values.js +65 -0
- package/dist/normalize/rules/engine-aliases.js +34 -0
- package/dist/normalize/rules/framework-attributes.js +85 -0
- package/dist/normalize/rules/generated-ids.js +64 -0
- package/dist/normalize/rules/ordering.js +39 -0
- package/dist/normalize/rules/qwik-styles.js +21 -0
- package/dist/normalize/rules/qwik-templates.js +20 -0
- package/dist/normalize/rules/values.js +125 -0
- package/dist/normalize/rules/whitespace.js +381 -0
- package/dist/normalize/style.js +121 -0
- package/dist/normalize/targets.d.ts +8 -0
- package/dist/normalize/targets.js +17 -0
- package/dist/normalize/tree.d.ts +1 -0
- package/dist/normalize/tree.js +151 -0
- package/dist/setup.d.ts +1 -0
- package/dist/setup.js +149 -0
- package/dist/ssr/index.d.ts +10 -0
- package/dist/ssr/index.js +103 -0
- package/dist/ssr/spec.d.ts +1 -0
- package/dist/ssr/spec.js +7 -0
- package/dist/targets/angular.d.ts +1 -0
- package/dist/targets/angular.js +5 -0
- package/dist/targets/astro.d.ts +1 -0
- package/dist/targets/astro.js +5 -0
- package/dist/targets/qwik.d.ts +1 -0
- package/dist/targets/qwik.js +5 -0
- package/dist/targets/react.d.ts +1 -0
- package/dist/targets/react.js +5 -0
- package/dist/targets/solid.d.ts +1 -0
- package/dist/targets/solid.js +5 -0
- package/dist/targets/svelte.d.ts +1 -0
- package/dist/targets/svelte.js +5 -0
- package/dist/targets/vue.d.ts +1 -0
- package/dist/targets/vue.js +5 -0
- package/dist/visual-types.d.ts +92 -0
- package/dist/visual-types.js +24 -0
- package/package.json +146 -3
package/README.md
CHANGED
|
@@ -1,3 +1,537 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @unframework.dev/testing
|
|
2
2
|
|
|
3
|
-
|
|
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 };
|