@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
|
@@ -0,0 +1,282 @@
|
|
|
1
|
+
import { caseOfFile } from "../harness.js";
|
|
2
|
+
import { registeredAdapter } from "./target.js";
|
|
3
|
+
import { captureExternalConsole } from "./console.js";
|
|
4
|
+
import { formatError } from "../errors.js";
|
|
5
|
+
import { recordLayer } from "../layers.js";
|
|
6
|
+
import { assertInteractive } from "./capabilities.js";
|
|
7
|
+
import { isNormalizeTarget } from "../normalize/targets.js";
|
|
8
|
+
import { normalizeDomWithIds } from "../dom/serialize.js";
|
|
9
|
+
import { inlineHosts } from "../normalize/rules/aria-hosts.js";
|
|
10
|
+
import { advanceClock, checkTick, installClock } from "./clock.js";
|
|
11
|
+
import { ROOT_ATTRIBUTE, installDeterminism, settleFrame } from "./determinism.js";
|
|
12
|
+
import { copyPayload, renumberIds } from "./events.js";
|
|
13
|
+
import { takePreventedNavigations } from "./navigation.js";
|
|
14
|
+
import { Trace } from "./trace.js";
|
|
15
|
+
import { expectParity } from "./parity.js";
|
|
16
|
+
import { expectThrown } from "./thrown.js";
|
|
17
|
+
import { createUser } from "./user.js";
|
|
18
|
+
import { TestRunner, inject } from "vitest";
|
|
19
|
+
import { commands, page } from "vitest/browser";
|
|
20
|
+
//#region src/browser/view.ts
|
|
21
|
+
/** The rounds of settling after an action before the page counts as never quiet. */
|
|
22
|
+
const SETTLE_ROUNDS = 10;
|
|
23
|
+
const mounted = /* @__PURE__ */ new Set();
|
|
24
|
+
let roots = 0;
|
|
25
|
+
function mount(component, options = {}) {
|
|
26
|
+
return mountWith(component, options.props, options);
|
|
27
|
+
}
|
|
28
|
+
async function mountScenario(component, name, options = {}) {
|
|
29
|
+
const caseId = currentCase("mountScenario");
|
|
30
|
+
const scenarios = inject("ufHarness").cases[caseId]?.ssr ?? {};
|
|
31
|
+
if (!Object.hasOwn(scenarios, name)) {
|
|
32
|
+
const declared = Object.keys(scenarios);
|
|
33
|
+
throw new Error(`mountScenario(…, "${name}"): ${caseId}'s case.json declares no SSR scenario "${name}" (${declared.length ? `it declares ${declared.join(", ")}` : "it declares none"}). Declare it under "ssr" with its props, or mount a browser-only scenario with mount(component, { props }).`);
|
|
34
|
+
}
|
|
35
|
+
const props = scenarios[name]?.props;
|
|
36
|
+
return mountWith(component, props === void 0 ? void 0 : structuredClone(props), options);
|
|
37
|
+
}
|
|
38
|
+
/** The current test's case. */
|
|
39
|
+
function currentCase(caller) {
|
|
40
|
+
const test = TestRunner.getCurrentTest();
|
|
41
|
+
if (!test) throw new Error(`${caller} must be called inside a test.`);
|
|
42
|
+
return caseOfFile(test.file.filepath, inject("ufHarness"));
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* The events a component declares: from the stub target's registration, or from the project's
|
|
46
|
+
* compile of the case's module (the `ufComponentEvents` command), never from a guess.
|
|
47
|
+
*/
|
|
48
|
+
async function declaredEvents(registration, component) {
|
|
49
|
+
if (registration.events) return registration.events(component);
|
|
50
|
+
const { events } = await commands.ufComponentEvents({ case: currentCase("mount") });
|
|
51
|
+
return events;
|
|
52
|
+
}
|
|
53
|
+
async function mountWith(component, props, { clock = false }) {
|
|
54
|
+
const registration = registeredAdapter();
|
|
55
|
+
const { target, mount: adapter } = registration;
|
|
56
|
+
const initial = checkProps("mount", props);
|
|
57
|
+
await installDeterminism();
|
|
58
|
+
const declared = await declaredEvents(registration, component);
|
|
59
|
+
const log = [];
|
|
60
|
+
const refused = [];
|
|
61
|
+
const on = Object.fromEntries(declared.map(({ name }) => [name, (...args) => {
|
|
62
|
+
try {
|
|
63
|
+
log.push({
|
|
64
|
+
name,
|
|
65
|
+
args: copyPayload(name, args)
|
|
66
|
+
});
|
|
67
|
+
} catch (error) {
|
|
68
|
+
refused.push(formatError(error));
|
|
69
|
+
}
|
|
70
|
+
}]));
|
|
71
|
+
if (clock) installClock();
|
|
72
|
+
const container = document.createElement("div");
|
|
73
|
+
const testId = `uf-root-${roots += 1}`;
|
|
74
|
+
container.setAttribute(ROOT_ATTRIBUTE, "");
|
|
75
|
+
container.setAttribute("data-testid", testId);
|
|
76
|
+
document.body.append(container);
|
|
77
|
+
let instance;
|
|
78
|
+
try {
|
|
79
|
+
instance = await adapter(component, container, {
|
|
80
|
+
...initial ? { props: initial } : {},
|
|
81
|
+
on,
|
|
82
|
+
events: declared
|
|
83
|
+
});
|
|
84
|
+
} catch (error) {
|
|
85
|
+
container.remove();
|
|
86
|
+
throw error;
|
|
87
|
+
}
|
|
88
|
+
report(instance);
|
|
89
|
+
const locator = page.getByTestId(testId);
|
|
90
|
+
const engine = inject("ufHarness")?.browser;
|
|
91
|
+
const normalizeOptions = {
|
|
92
|
+
...isNormalizeTarget(target) ? { target } : {},
|
|
93
|
+
...engine ? { engine } : {}
|
|
94
|
+
};
|
|
95
|
+
const dom = () => normalizeDomWithIds(container, normalizeOptions);
|
|
96
|
+
const html = () => dom().html;
|
|
97
|
+
const aria = async () => {
|
|
98
|
+
const restore = inlineHosts(container, isNormalizeTarget(target) ? target : void 0);
|
|
99
|
+
try {
|
|
100
|
+
return await commands.ufAriaSnapshot(locator.serialize());
|
|
101
|
+
} finally {
|
|
102
|
+
restore();
|
|
103
|
+
}
|
|
104
|
+
};
|
|
105
|
+
/** Fails with what the page or the payloads refused since the last settle. */
|
|
106
|
+
const raise = () => {
|
|
107
|
+
const problems = [...takePreventedNavigations(), ...refused.splice(0)];
|
|
108
|
+
if (problems.length) throw new Error(problems.join("\n"));
|
|
109
|
+
};
|
|
110
|
+
const settle = async () => {
|
|
111
|
+
await settleFrame(() => instance.settle());
|
|
112
|
+
raise();
|
|
113
|
+
};
|
|
114
|
+
/**
|
|
115
|
+
* Settles until the DOM and the emitted events stop changing: two rounds in a row read the
|
|
116
|
+
* same. A handler's work after an `await`, an effect a write scheduled, a lazily loaded
|
|
117
|
+
* handler: each lands in some round, and every target's step records all of it. Once the
|
|
118
|
+
* view is unmounted, a round waits for the page alone: the adapter has nothing left to settle.
|
|
119
|
+
*/
|
|
120
|
+
const settleUntilQuiet = async (settleOnce = settle) => {
|
|
121
|
+
let previous;
|
|
122
|
+
for (let round = 0; round < SETTLE_ROUNDS; round += 1) {
|
|
123
|
+
await settleOnce();
|
|
124
|
+
const snapshot = `${html()}\n${log.length}`;
|
|
125
|
+
if (snapshot === previous) return true;
|
|
126
|
+
previous = snapshot;
|
|
127
|
+
}
|
|
128
|
+
return false;
|
|
129
|
+
};
|
|
130
|
+
const trace = new Trace({
|
|
131
|
+
root: testId,
|
|
132
|
+
dom,
|
|
133
|
+
aria,
|
|
134
|
+
events: log
|
|
135
|
+
});
|
|
136
|
+
/** Settles after a step and records it; a page that never quiets fails L9, which it feeds. */
|
|
137
|
+
const step = async (action) => {
|
|
138
|
+
if (!await settleUntilQuiet()) failTrace(target, `did not settle after ${action}`);
|
|
139
|
+
await trace.record(action);
|
|
140
|
+
};
|
|
141
|
+
let unmounted = false;
|
|
142
|
+
/**
|
|
143
|
+
* Runs an action as a step of the view: each input through the adapter and settled before the
|
|
144
|
+
* next is taken (as the time between a person's two inputs lets a framework render), then the
|
|
145
|
+
* step is recorded.
|
|
146
|
+
*/
|
|
147
|
+
const perform = async (action, inputs) => {
|
|
148
|
+
if (unmounted) throw new Error(`${action}: the view is unmounted.`);
|
|
149
|
+
const pending = inputs[Symbol.iterator]();
|
|
150
|
+
for (let next = pending.next(); !next.done;) {
|
|
151
|
+
const input = next.value;
|
|
152
|
+
await (instance.interact ? instance.interact(input) : input());
|
|
153
|
+
next = pending.next();
|
|
154
|
+
if (!next.done && !await settleUntilQuiet()) failTrace(target, `did not settle after an input of ${action}`);
|
|
155
|
+
}
|
|
156
|
+
await step(action);
|
|
157
|
+
};
|
|
158
|
+
const declaredNames = declared.map(({ name }) => name);
|
|
159
|
+
const emittedArgs = (what) => {
|
|
160
|
+
assertInteractive(what);
|
|
161
|
+
raise();
|
|
162
|
+
const { ids } = dom();
|
|
163
|
+
return log.map((event) => ({
|
|
164
|
+
...event,
|
|
165
|
+
args: renumberIds(event.args, ids)
|
|
166
|
+
}));
|
|
167
|
+
};
|
|
168
|
+
const view = {
|
|
169
|
+
target,
|
|
170
|
+
container,
|
|
171
|
+
locator,
|
|
172
|
+
getByRole: (...args) => locator.getByRole(...args),
|
|
173
|
+
getByText: (...args) => locator.getByText(...args),
|
|
174
|
+
getByLabelText: (...args) => locator.getByLabelText(...args),
|
|
175
|
+
getByPlaceholder: (...args) => locator.getByPlaceholder(...args),
|
|
176
|
+
getByAltText: (...args) => locator.getByAltText(...args),
|
|
177
|
+
getByTitle: (...args) => locator.getByTitle(...args),
|
|
178
|
+
getByTestId: (...args) => locator.getByTestId(...args),
|
|
179
|
+
user: createUser({
|
|
180
|
+
testId,
|
|
181
|
+
perform
|
|
182
|
+
}),
|
|
183
|
+
clock: { async tick(ms) {
|
|
184
|
+
assertInteractive("view.clock.tick");
|
|
185
|
+
if (!clock) throw new Error("view.clock.tick: this view was mounted without a clock. Mount it with { clock: true }, which fakes setInterval before the component starts its intervals.");
|
|
186
|
+
checkTick(ms);
|
|
187
|
+
const action = `tick ${ms}ms`;
|
|
188
|
+
if (!unmounted) {
|
|
189
|
+
await advanceClock(ms, async (fire) => {
|
|
190
|
+
await (instance.interact ? instance.interact(fire) : fire());
|
|
191
|
+
if (!await settleUntilQuiet()) failTrace(target, `did not settle after an interval that ${action} ran`);
|
|
192
|
+
});
|
|
193
|
+
await step(action);
|
|
194
|
+
return;
|
|
195
|
+
}
|
|
196
|
+
const settlePage = async () => {
|
|
197
|
+
await settleFrame();
|
|
198
|
+
raise();
|
|
199
|
+
};
|
|
200
|
+
await advanceClock(ms, async (fire) => {
|
|
201
|
+
await fire();
|
|
202
|
+
if (!await settleUntilQuiet(settlePage)) throw new Error(`view.clock.tick: the page did not settle after an interval of ${action} once the view was unmounted: its emitted events still changed after ${SETTLE_ROUNDS} rounds.`);
|
|
203
|
+
});
|
|
204
|
+
} },
|
|
205
|
+
html,
|
|
206
|
+
settle,
|
|
207
|
+
async rerender(next) {
|
|
208
|
+
if (unmounted) throw new Error("rerender: the view is unmounted.");
|
|
209
|
+
const props = checkProps("rerender", next) ?? {};
|
|
210
|
+
report(await instance.rerender(props));
|
|
211
|
+
await step(`rerender ${JSON.stringify(props)}`);
|
|
212
|
+
},
|
|
213
|
+
emitted(name) {
|
|
214
|
+
if (!declaredNames.includes(name)) throw new Error(`view.emitted("${name}"): the component declares no event "${name}" (${declaredNames.length ? `it declares ${declaredNames.join(", ")}` : "it declares none"}).`);
|
|
215
|
+
return emittedArgs("view.emitted").filter((event) => event.name === name).map((event) => event.args);
|
|
216
|
+
},
|
|
217
|
+
events: () => emittedArgs("view.events").map((event) => [event.name, ...event.args]),
|
|
218
|
+
expectParity: (name, parityOptions) => expectParity({
|
|
219
|
+
...view,
|
|
220
|
+
trace,
|
|
221
|
+
dom,
|
|
222
|
+
aria
|
|
223
|
+
}, name, parityOptions),
|
|
224
|
+
expectThrown: (action) => expectThrown({
|
|
225
|
+
settle: () => settleFrame(() => instance.settle()),
|
|
226
|
+
stepMark: () => trace.length,
|
|
227
|
+
forgetSteps: (mark) => trace.forget(mark)
|
|
228
|
+
}, action),
|
|
229
|
+
async unmount() {
|
|
230
|
+
if (unmounted) return;
|
|
231
|
+
unmounted = true;
|
|
232
|
+
mounted.delete(view);
|
|
233
|
+
try {
|
|
234
|
+
await instance.unmount();
|
|
235
|
+
} finally {
|
|
236
|
+
container.remove();
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
};
|
|
240
|
+
mounted.add(view);
|
|
241
|
+
if (!await settleUntilQuiet()) throw new Error(`mount: the component did not settle: its DOM or its events still changed after ${SETTLE_ROUNDS} rounds. A component that keeps changing on its own (a timer) starts from an action, after the first expectParity (ADR-0050).`);
|
|
242
|
+
return view;
|
|
243
|
+
}
|
|
244
|
+
/** Records an L9 failure on the current test: a step that never settled cannot be compared. */
|
|
245
|
+
function failTrace(target, message) {
|
|
246
|
+
const test = TestRunner.getCurrentTest();
|
|
247
|
+
if (!test) throw new Error(message);
|
|
248
|
+
const harness = inject("ufHarness");
|
|
249
|
+
recordLayer(test, {
|
|
250
|
+
case: caseOfFile(test.file.filepath, harness),
|
|
251
|
+
target,
|
|
252
|
+
quarantine: harness.quarantine
|
|
253
|
+
}, "L9", {
|
|
254
|
+
status: "fail",
|
|
255
|
+
message: `${message}: the DOM or the emitted events still changed after ${SETTLE_ROUNDS} rounds of settling.`
|
|
256
|
+
});
|
|
257
|
+
}
|
|
258
|
+
/** Hands what a render logged outside the page (Astro's server render) to the L13 capture. */
|
|
259
|
+
function report(rendered) {
|
|
260
|
+
if (rendered && rendered.console?.length) captureExternalConsole(rendered.console);
|
|
261
|
+
}
|
|
262
|
+
/** The props an adapter gets: a plain object, or none. */
|
|
263
|
+
function checkProps(action, props) {
|
|
264
|
+
if (props === void 0 || isProps(props)) return props;
|
|
265
|
+
throw new TypeError(`${action}: props are an object of prop names and values, not ${props === null ? "null" : Array.isArray(props) ? "an array" : typeof props}.`);
|
|
266
|
+
}
|
|
267
|
+
function isProps(value) {
|
|
268
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
269
|
+
}
|
|
270
|
+
/** Unmounts every view the current test left mounted, newest first. */
|
|
271
|
+
async function cleanup() {
|
|
272
|
+
const errors = [];
|
|
273
|
+
for (const view of [...mounted].reverse()) try {
|
|
274
|
+
await view.unmount();
|
|
275
|
+
} catch (error) {
|
|
276
|
+
errors.push(error);
|
|
277
|
+
}
|
|
278
|
+
if (errors.length === 1) throw errors[0];
|
|
279
|
+
if (errors.length) throw new AggregateError(errors, `${errors.length} views failed to unmount.`);
|
|
280
|
+
}
|
|
281
|
+
//#endregion
|
|
282
|
+
export { cleanup, mount, mountScenario };
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { CaptureRequest, CaptureResult, PixelTolerance } from "../visual-types.js";
|
|
2
|
+
import "../commands.js";
|
|
3
|
+
import { RunnerTestCase } from "vitest";
|
|
4
|
+
import { Locator } from "vitest/browser";
|
|
5
|
+
//#region src/browser/visual.d.ts
|
|
6
|
+
/** Sends a capture to Node: `ufVisualCapture` for a case, or another package's own command. */
|
|
7
|
+
export type CaptureCommand = (request: CaptureRequest) => Promise<CaptureResult>;
|
|
8
|
+
/**
|
|
9
|
+
* Captures a settled container and compares it under the run's policy. `send` is the command
|
|
10
|
+
* that locates and compares it: the corpus's `ufVisualCapture` by default, or the visual
|
|
11
|
+
* runner's for an example (ADR-0087).
|
|
12
|
+
*/
|
|
13
|
+
export declare function captureVisual(test: RunnerTestCase, input: {
|
|
14
|
+
case: string;
|
|
15
|
+
name: string;
|
|
16
|
+
container: HTMLElement;
|
|
17
|
+
locator: Locator;
|
|
18
|
+
tolerance?: PixelTolerance;
|
|
19
|
+
}, send?: CaptureCommand): Promise<CaptureResult>;
|
|
20
|
+
//#endregion
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { captureGeometry } from "./geometry.js";
|
|
2
|
+
import { withMergedTextRuns } from "./text-runs.js";
|
|
3
|
+
import { recordArtifact } from "vitest";
|
|
4
|
+
import { commands } from "vitest/browser";
|
|
5
|
+
//#region src/browser/visual.ts
|
|
6
|
+
let markers = 0;
|
|
7
|
+
/**
|
|
8
|
+
* Captures a settled container and compares it under the run's policy. `send` is the command
|
|
9
|
+
* that locates and compares it: the corpus's `ufVisualCapture` by default, or the visual
|
|
10
|
+
* runner's for an example (ADR-0087).
|
|
11
|
+
*/
|
|
12
|
+
async function captureVisual(test, input, send = (request) => commands.ufVisualCapture(request)) {
|
|
13
|
+
const marker = `${Date.now().toString(36)}-${markers += 1}`;
|
|
14
|
+
input.container.setAttribute("data-uf-capture", marker);
|
|
15
|
+
try {
|
|
16
|
+
const result = await withMergedTextRuns(input.container, () => send({
|
|
17
|
+
element: input.locator.serialize(),
|
|
18
|
+
case: input.case,
|
|
19
|
+
name: input.name,
|
|
20
|
+
geometry: captureGeometry(input.container),
|
|
21
|
+
marker,
|
|
22
|
+
...input.tolerance ? { tolerance: input.tolerance } : {}
|
|
23
|
+
}));
|
|
24
|
+
if (!result.pass && result.attachments.length) await recordArtifact(test, {
|
|
25
|
+
type: "internal:toMatchScreenshot",
|
|
26
|
+
kind: "visual-regression",
|
|
27
|
+
message: result.message,
|
|
28
|
+
attachments: result.attachments
|
|
29
|
+
});
|
|
30
|
+
return result;
|
|
31
|
+
} finally {
|
|
32
|
+
input.container.removeAttribute("data-uf-capture");
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
//#endregion
|
|
36
|
+
export { captureVisual };
|
package/dist/cli.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
//#region src/cli.d.ts
|
|
2
|
+
/** Where the command runs and writes: the shape of `@unframework.dev/cli`'s `Io`. */
|
|
3
|
+
export interface TestIo {
|
|
4
|
+
cwd: string;
|
|
5
|
+
stdout(text: string): void;
|
|
6
|
+
stderr(text: string): void;
|
|
7
|
+
}
|
|
8
|
+
/** The command's arguments, read. */
|
|
9
|
+
export interface TestArguments {
|
|
10
|
+
targets: string[];
|
|
11
|
+
update: boolean;
|
|
12
|
+
/** What follows `--`, for Vitest. */
|
|
13
|
+
vitest: string[];
|
|
14
|
+
}
|
|
15
|
+
/** Reads the arguments, throwing on a usage error: the CLI exits 2 with the message. */
|
|
16
|
+
export declare function parseTestArguments(args: readonly string[]): TestArguments;
|
|
17
|
+
/**
|
|
18
|
+
* Runs the tests and gives the exit code: 0 when every test passes, 1 when one fails, and 2 on a
|
|
19
|
+
* usage or configuration error, which it reports, as the CLI's other commands do (ADR-0076).
|
|
20
|
+
* Vitest's own options (`--reporter`, a file filter) follow `--`.
|
|
21
|
+
*/
|
|
22
|
+
export declare function run(args: string[], io: TestIo): Promise<number>;
|
|
23
|
+
//#endregion
|
package/dist/cli.js
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { defineTestConfig } from "./config/index.js";
|
|
2
|
+
import { existsSync } from "node:fs";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import { TARGET_NAMES } from "@unframework.dev/compiler";
|
|
5
|
+
import { parseCLI, startVitest } from "vitest/node";
|
|
6
|
+
//#region src/cli.ts
|
|
7
|
+
/** The files a project's own Vitest configuration may have, the first one found winning. */
|
|
8
|
+
const VITEST_CONFIGS = [
|
|
9
|
+
"vitest.config.ts",
|
|
10
|
+
"vitest.config.mts",
|
|
11
|
+
"vitest.config.js",
|
|
12
|
+
"vitest.config.mjs"
|
|
13
|
+
];
|
|
14
|
+
/** Reads the arguments, throwing on a usage error: the CLI exits 2 with the message. */
|
|
15
|
+
function parseTestArguments(args) {
|
|
16
|
+
const parsed = {
|
|
17
|
+
targets: [],
|
|
18
|
+
update: false,
|
|
19
|
+
vitest: []
|
|
20
|
+
};
|
|
21
|
+
for (let index = 0; index < args.length; index += 1) {
|
|
22
|
+
const arg = args[index];
|
|
23
|
+
if (arg === "--") {
|
|
24
|
+
parsed.vitest = args.slice(index + 1);
|
|
25
|
+
break;
|
|
26
|
+
}
|
|
27
|
+
if (arg === "--update") {
|
|
28
|
+
parsed.update = true;
|
|
29
|
+
continue;
|
|
30
|
+
}
|
|
31
|
+
const target = /^--target(?:=(.*))?$/s.exec(arg);
|
|
32
|
+
if (target) {
|
|
33
|
+
const value = target[1] ?? args[index += 1];
|
|
34
|
+
if (value === void 0 || value === "" || value.startsWith("-")) throw new Error("--target needs a target's name, such as --target react.");
|
|
35
|
+
parsed.targets.push(value);
|
|
36
|
+
continue;
|
|
37
|
+
}
|
|
38
|
+
throw new Error(`unknown argument "${arg}". Pass Vitest's own options after --, such as unframework test -- --reporter=json.`);
|
|
39
|
+
}
|
|
40
|
+
const unknown = parsed.targets.filter((name) => !TARGET_NAMES.includes(name));
|
|
41
|
+
if (unknown.length) throw new Error(`unknown target${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}. The targets are ${TARGET_NAMES.join(", ")}.`);
|
|
42
|
+
return parsed;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Runs the tests and gives the exit code: 0 when every test passes, 1 when one fails, and 2 on a
|
|
46
|
+
* usage or configuration error, which it reports, as the CLI's other commands do (ADR-0076).
|
|
47
|
+
* Vitest's own options (`--reporter`, a file filter) follow `--`.
|
|
48
|
+
*/
|
|
49
|
+
async function run(args, io) {
|
|
50
|
+
const parsed = parseTestArguments(args);
|
|
51
|
+
const help = parsed.vitest.some((arg) => arg === "--help" || arg === "-h");
|
|
52
|
+
const { filter, options } = parseCLI(["vitest", ...parsed.vitest]);
|
|
53
|
+
if (help) return 0;
|
|
54
|
+
if (options.update !== void 0 && options.update !== false) throw new Error("Vitest's --update does not update the shared expectations: run unframework test --update.");
|
|
55
|
+
const config = VITEST_CONFIGS.map((name) => join(io.cwd, name)).find((file) => existsSync(file));
|
|
56
|
+
const saved = {
|
|
57
|
+
targets: process.env.UF_TARGETS,
|
|
58
|
+
update: process.env.UF_UPDATE,
|
|
59
|
+
cli: process.env.UF_TEST_CLI
|
|
60
|
+
};
|
|
61
|
+
const exitCode = process.exitCode;
|
|
62
|
+
if (parsed.targets.length) process.env.UF_TARGETS = parsed.targets.join(",");
|
|
63
|
+
else delete process.env.UF_TARGETS;
|
|
64
|
+
if (parsed.update) process.env.UF_UPDATE = "1";
|
|
65
|
+
else delete process.env.UF_UPDATE;
|
|
66
|
+
process.env.UF_TEST_CLI = "1";
|
|
67
|
+
try {
|
|
68
|
+
const inline = config === void 0 ? await defineTestConfig({ root: io.cwd }) : void 0;
|
|
69
|
+
process.exitCode = 0;
|
|
70
|
+
const vitest = await startVitest(filter, {
|
|
71
|
+
...options,
|
|
72
|
+
root: io.cwd,
|
|
73
|
+
run: true,
|
|
74
|
+
watch: false,
|
|
75
|
+
config: config ?? false
|
|
76
|
+
}, inline);
|
|
77
|
+
return process.exitCode !== 0 || vitest.state.getCountOfFailedTests() > 0 || vitest.state.getUnhandledErrors().length > 0 ? 1 : 0;
|
|
78
|
+
} finally {
|
|
79
|
+
process.exitCode = exitCode;
|
|
80
|
+
restore("UF_TARGETS", saved.targets);
|
|
81
|
+
restore("UF_UPDATE", saved.update);
|
|
82
|
+
restore("UF_TEST_CLI", saved.cli);
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
function restore(name, value) {
|
|
86
|
+
if (value === void 0) delete process.env[name];
|
|
87
|
+
else process.env[name] = value;
|
|
88
|
+
}
|
|
89
|
+
//#endregion
|
|
90
|
+
export { parseTestArguments, run };
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { ColorScheme } from "./harness.js";
|
|
2
|
+
import { CaptureRequest, CaptureResult } from "./visual-types.js";
|
|
3
|
+
import { MountEvent } from "@unframework.dev/codegen";
|
|
4
|
+
//#region src/commands.d.ts
|
|
5
|
+
/** A shared expectation the browser computed, to settle under the write policy (ADR-0029). */
|
|
6
|
+
export interface ArtefactRequest {
|
|
7
|
+
case: string;
|
|
8
|
+
/** The file name under `__expected__/`, such as `dom.initial.html` or `trace.after-click.json`. */
|
|
9
|
+
file: string;
|
|
10
|
+
/**
|
|
11
|
+
* The file's contents, or `null` where the scenario must have none (a trace without steps): the
|
|
12
|
+
* file must then not exist, and the reference deletes it in update mode.
|
|
13
|
+
*/
|
|
14
|
+
contents: string | null;
|
|
15
|
+
}
|
|
16
|
+
/** How an artefact was settled. */
|
|
17
|
+
export interface ArtefactResult {
|
|
18
|
+
pass: boolean;
|
|
19
|
+
/** `matched`, `written`, `missing`, `missing-reference` or `mismatch`. */
|
|
20
|
+
status: string;
|
|
21
|
+
/** Why it failed, with a diff; empty when it passed. */
|
|
22
|
+
message: string;
|
|
23
|
+
}
|
|
24
|
+
/** A Vitest locator as commands receive it. */
|
|
25
|
+
export interface SerializedLocatorLike {
|
|
26
|
+
selector: string;
|
|
27
|
+
locator: string;
|
|
28
|
+
}
|
|
29
|
+
/** Which case's component `ufComponentEvents` describes. */
|
|
30
|
+
export interface ComponentEventsRequest {
|
|
31
|
+
case: string;
|
|
32
|
+
}
|
|
33
|
+
/** The events the component a case's spec mounts declares, from the module the project compiled. */
|
|
34
|
+
export interface ComponentEventsResult {
|
|
35
|
+
events: MountEvent[];
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* One input of a person's action, which `ufInput` dispatches alone (ADR-0050): the pointer moved
|
|
39
|
+
* onto an element (as Playwright's hover moves it, after its checks), a mouse button's press or
|
|
40
|
+
* release (the `clickCount`-th of a multiple click), a step of the wheel, a key's press or
|
|
41
|
+
* release.
|
|
42
|
+
*/
|
|
43
|
+
export type InputRequest = {
|
|
44
|
+
kind: "move";
|
|
45
|
+
locator: SerializedLocatorLike;
|
|
46
|
+
/** The point to move to, from the element's top left corner; its centre by default. */
|
|
47
|
+
position?: {
|
|
48
|
+
x: number;
|
|
49
|
+
y: number;
|
|
50
|
+
};
|
|
51
|
+
/** Whether a click follows, which refuses a disabled element, or only the move. */
|
|
52
|
+
check: "click" | "hover";
|
|
53
|
+
} | {
|
|
54
|
+
kind: "press" | "release";
|
|
55
|
+
clickCount: number;
|
|
56
|
+
} | {
|
|
57
|
+
kind: "wheel";
|
|
58
|
+
deltaX: number;
|
|
59
|
+
deltaY: number;
|
|
60
|
+
} | {
|
|
61
|
+
kind: "keydown" | "keyup";
|
|
62
|
+
key: string;
|
|
63
|
+
text: boolean;
|
|
64
|
+
};
|
|
65
|
+
/** Which case's spec file the calling browser project finished (`ufSpecFinished`, ADR-0091). */
|
|
66
|
+
export interface SpecFinishedRequest {
|
|
67
|
+
case: string;
|
|
68
|
+
}
|
|
69
|
+
/** The stack of the error a case's scripted step threw, as the browser read it (ADR-0078). */
|
|
70
|
+
export interface MapStackRequest {
|
|
71
|
+
case: string;
|
|
72
|
+
stack: string;
|
|
73
|
+
}
|
|
74
|
+
/** What the mapped stack says. */
|
|
75
|
+
export interface MapStackResult {
|
|
76
|
+
/** Why the top frame in the case is not on the authored `throw`; absent when it is. */
|
|
77
|
+
message?: string;
|
|
78
|
+
}
|
|
79
|
+
/** What an input did: a character the keyboard layout lacks is inserted as text, with no key. */
|
|
80
|
+
export interface InputResult {
|
|
81
|
+
inserted: boolean;
|
|
82
|
+
}
|
|
83
|
+
declare module "vitest/browser" {
|
|
84
|
+
interface BrowserCommands {
|
|
85
|
+
/** Settles a shared `__expected__` artefact under the run's write policy. */
|
|
86
|
+
ufArtefact: (request: ArtefactRequest) => Promise<ArtefactResult>;
|
|
87
|
+
/** Playwright's ARIA snapshot of the element a locator points at. */
|
|
88
|
+
ufAriaSnapshot: (locator: SerializedLocatorLike) => Promise<string>;
|
|
89
|
+
/** L10: font audit, stable capture, geometry then pixels, under the write policy. */
|
|
90
|
+
ufVisualCapture: (request: CaptureRequest) => Promise<CaptureResult>;
|
|
91
|
+
/** Moves the focus to the element a locator points at, as Playwright's `focus` does. */
|
|
92
|
+
ufFocus: (locator: SerializedLocatorLike) => Promise<void>;
|
|
93
|
+
/** Dispatches one input of a `view.user` action through Playwright's mouse or keyboard. */
|
|
94
|
+
ufInput: (request: InputRequest) => Promise<InputResult>;
|
|
95
|
+
/** Moves the mouse to the corner of the viewport, off every mount root, between tests. */
|
|
96
|
+
ufResetInput: () => Promise<void>;
|
|
97
|
+
/** Emulates the `prefers-color-scheme` a case opts into, for the page its spec runs in. */
|
|
98
|
+
ufColorScheme: (scheme: ColorScheme) => Promise<void>;
|
|
99
|
+
/** The events a case's component declares, as the project's compile of it says (ADR-0050). */
|
|
100
|
+
ufComponentEvents: (request: ComponentEventsRequest) => Promise<ComponentEventsResult>;
|
|
101
|
+
/** Records that this project finished a case's spec file, which L10's followers read. */
|
|
102
|
+
ufSpecFinished: (request: SpecFinishedRequest) => Promise<void>;
|
|
103
|
+
/** Maps a thrown error's stack through the project's module graph and checks its top frame. */
|
|
104
|
+
ufMapStack: (request: MapStackRequest) => Promise<MapStackResult>;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
//#endregion
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
//#region src/config/broadcast.ts
|
|
2
|
+
/** The plugin's name, which a test finds it by. */
|
|
3
|
+
const NO_ERROR_BROADCAST = "uf-testing:no-error-broadcast";
|
|
4
|
+
/**
|
|
5
|
+
* Keeps a module that fails to compile from failing the specs after it. Its import fails its own
|
|
6
|
+
* spec, and Vite logs the error. Vite also sends it to every page the server serves, whose client
|
|
7
|
+
* puts an overlay over the page: every later spec of the run then clicks in it, and captures it in
|
|
8
|
+
* place of the component, so a case or an example that compiles would fail, or pass with the
|
|
9
|
+
* overlay in its screenshot. `server.hmr.overlay: false` cannot stop it: Vitest sets
|
|
10
|
+
* `server.hmr: false`, and Vite reads `overlay` only from an object.
|
|
11
|
+
*/
|
|
12
|
+
function noErrorBroadcast() {
|
|
13
|
+
return {
|
|
14
|
+
name: NO_ERROR_BROADCAST,
|
|
15
|
+
configureServer(server) {
|
|
16
|
+
const hot = server.environments.client.hot;
|
|
17
|
+
const send = hot.send.bind(hot);
|
|
18
|
+
hot.send = (...args) => {
|
|
19
|
+
const [payload] = args;
|
|
20
|
+
if (typeof payload === "object" && payload !== null && "type" in payload) {
|
|
21
|
+
if (payload.type === "error") return;
|
|
22
|
+
}
|
|
23
|
+
Reflect.apply(send, void 0, args);
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
//#endregion
|
|
29
|
+
export { NO_ERROR_BROADCAST, noErrorBroadcast };
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { CaseConfig } from "../harness.js";
|
|
2
|
+
//#region src/config/cases.d.ts
|
|
3
|
+
/** One case of a project. */
|
|
4
|
+
export interface ProjectCase {
|
|
5
|
+
/** The directory relative to the project's root, with forward slashes. */
|
|
6
|
+
id: string;
|
|
7
|
+
/** The case's directory (absolute). */
|
|
8
|
+
dir: string;
|
|
9
|
+
/** The test file (absolute). */
|
|
10
|
+
spec: string;
|
|
11
|
+
/** The main `.uf.tsx` source (absolute). */
|
|
12
|
+
source: string;
|
|
13
|
+
config: CaseConfig;
|
|
14
|
+
}
|
|
15
|
+
/** What {@link discoverCases} reads. */
|
|
16
|
+
export interface DiscoverOptions {
|
|
17
|
+
/** The project's root (absolute): case ids are relative to it. */
|
|
18
|
+
root: string;
|
|
19
|
+
/** Globs of test files, relative to the root. */
|
|
20
|
+
include: readonly string[];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Every case under the root, sorted by id. Throws, naming the fix, on a directory with two test
|
|
24
|
+
* files, a case with no main source, a test file at the root itself and a malformed `case.json`:
|
|
25
|
+
* a case that cannot be told apart would have nowhere to go in the run.
|
|
26
|
+
*/
|
|
27
|
+
export declare function discoverCases(options: DiscoverOptions): ProjectCase[];
|
|
28
|
+
//#endregion
|