@unframework.dev/testing 0.0.0-stage → 0.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +511 -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 +81 -0
- package/dist/config/index.js +275 -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 +184 -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 +101 -0
- package/dist/node/mode.js +201 -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 +370 -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 +135 -3
package/dist/layers.js
ADDED
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
import { formatError } from "./errors.js";
|
|
2
|
+
import { REFERENCE_NOT_RUN_SKIP } from "./visual-types.js";
|
|
3
|
+
//#region src/layers.ts
|
|
4
|
+
/** Every layer, in order. */
|
|
5
|
+
const LAYERS = [
|
|
6
|
+
"L1",
|
|
7
|
+
"L2",
|
|
8
|
+
"L3",
|
|
9
|
+
"L4",
|
|
10
|
+
"L5",
|
|
11
|
+
"L6",
|
|
12
|
+
"L7",
|
|
13
|
+
"L8",
|
|
14
|
+
"L9",
|
|
15
|
+
"L10",
|
|
16
|
+
"L11",
|
|
17
|
+
"L12",
|
|
18
|
+
"L13",
|
|
19
|
+
"L14",
|
|
20
|
+
"L15"
|
|
21
|
+
];
|
|
22
|
+
/** The layers a browser test records, which a test skipped by capability records as skipped. */
|
|
23
|
+
const BROWSER_LAYERS = [
|
|
24
|
+
"L7",
|
|
25
|
+
"L8",
|
|
26
|
+
"L9",
|
|
27
|
+
"L10",
|
|
28
|
+
"L11",
|
|
29
|
+
"L13",
|
|
30
|
+
"L14"
|
|
31
|
+
];
|
|
32
|
+
/** The skip of the layers that need output, on a target a case has compile errors for. */
|
|
33
|
+
const NO_OUTPUT_SKIP = "compile errors: no output";
|
|
34
|
+
/**
|
|
35
|
+
* The skip of the browser layers of a case without a spec, a diagnostics case, on a target it has
|
|
36
|
+
* output for: one whose only diagnostic is a note, as a capability's info (UF4004). No browser
|
|
37
|
+
* project loads it, and its server render checks the output instead.
|
|
38
|
+
*/
|
|
39
|
+
const NO_SPEC_SKIP = "no spec: a diagnostics case renders in no browser";
|
|
40
|
+
/** L13's skip in the server render of a component that did not render: L6 failed instead. */
|
|
41
|
+
const NOT_RENDERED_SKIP = "the component did not render (L6)";
|
|
42
|
+
/** A layer only a project outside this run records (L15, `bench`): the summary fills its cells. */
|
|
43
|
+
const NOT_IN_THIS_RUN_SKIP = "not in this run";
|
|
44
|
+
/** L9's skip in a scenario that no interaction or rerender led to: there is no trace. */
|
|
45
|
+
const NO_INTERACTION_SKIP = "no scripted interaction";
|
|
46
|
+
/** The prefix of a skip by capability: `requires interactivity: <the target's reason>`. */
|
|
47
|
+
const REQUIRES_SKIP = /^requires ([a-z][a-z0-9-]*): ./s;
|
|
48
|
+
/** The skip reason of a test that requires a capability its target does not support. */
|
|
49
|
+
function requiresSkip(capability, reason) {
|
|
50
|
+
return `requires ${capability}: ${reason}`;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The prefix of a browser test's skip on a target its case has no output for: `no output: <the
|
|
54
|
+
* errors the case expects for the target>`.
|
|
55
|
+
*/
|
|
56
|
+
const NO_OUTPUT_TEST_SKIP = /^no output: ./s;
|
|
57
|
+
/**
|
|
58
|
+
* The skip reason of a browser test of a case its target has no output for: the case expects
|
|
59
|
+
* an error for the target, the one it declares for a capability it lacks (ADR-0033).
|
|
60
|
+
*/
|
|
61
|
+
function noOutputSkip(errors) {
|
|
62
|
+
return `no output: ${errors}`;
|
|
63
|
+
}
|
|
64
|
+
/** Precedence when several records meet in one cell: a failure is never hidden by a pass. */
|
|
65
|
+
const PRECEDENCE = {
|
|
66
|
+
fail: 3,
|
|
67
|
+
quarantined: 2,
|
|
68
|
+
pass: 1,
|
|
69
|
+
skip: 0
|
|
70
|
+
};
|
|
71
|
+
/**
|
|
72
|
+
* Merges outcomes for the same case, target and layer: fail beats everything, and a failure
|
|
73
|
+
* keeps the message of every record that failed (each distinct one once, in order), so no
|
|
74
|
+
* sub-check's evidence is lost (the canaries require each of them).
|
|
75
|
+
*/
|
|
76
|
+
function mergeOutcomes(...outcomes) {
|
|
77
|
+
const [first, ...rest] = outcomes;
|
|
78
|
+
if (!first) throw new Error("mergeOutcomes needs at least one outcome.");
|
|
79
|
+
const winner = rest.reduce((best, outcome) => rank(outcome) > rank(best) ? outcome : best, first);
|
|
80
|
+
if (winner.status !== "fail") return winner;
|
|
81
|
+
const messages = new Set(outcomes.flatMap((outcome) => outcome.status === "fail" ? [outcome.message] : []));
|
|
82
|
+
return messages.size === 1 ? winner : {
|
|
83
|
+
status: "fail",
|
|
84
|
+
message: [...messages].join("\n")
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* An outcome's precedence. A skip that stands for a check that could not run, which the summary
|
|
89
|
+
* never accepts (ADR-0091), ranks above a pass and every other skip: a cell where one scenario
|
|
90
|
+
* had nothing to compare with never reads as passed, and a skip by capability of another test of
|
|
91
|
+
* the case never hides it.
|
|
92
|
+
*/
|
|
93
|
+
function rank(outcome) {
|
|
94
|
+
return outcome.status === "skip" && REFERENCE_NOT_RUN_SKIP.test(outcome.reason) ? PRECEDENCE.pass + .5 : PRECEDENCE[outcome.status];
|
|
95
|
+
}
|
|
96
|
+
/** The quarantine entry for a case, target and layer, if any. */
|
|
97
|
+
function quarantineFor(quarantine, subject, layer) {
|
|
98
|
+
return quarantine?.find((entry) => entry.case === subject.case && entry.target === subject.target && entry.layer === layer);
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* Applies a quarantine entry to a cell: the merged outcome of every record of one (case, target,
|
|
102
|
+
* layer) in a run that recorded them all. A cell that fails (or whose records were quarantined)
|
|
103
|
+
* is quarantined; one that passes, or is skipped, is a stale entry and fails.
|
|
104
|
+
*/
|
|
105
|
+
function settleOutcome(outcome, entry) {
|
|
106
|
+
if (!entry) return outcome;
|
|
107
|
+
if (outcome.status === "fail") return {
|
|
108
|
+
status: "quarantined",
|
|
109
|
+
issue: entry.issue
|
|
110
|
+
};
|
|
111
|
+
if (outcome.status === "quarantined") return outcome;
|
|
112
|
+
const what = outcome.status === "pass" ? "passes" : `is skipped (${outcome.reason})`;
|
|
113
|
+
const pixels = entry.layer === "L10" && entry.pixels === void 0 ? ` If only one pixel mode fails it, name that mode in the entry (pixels: "baseline" or "live").` : "";
|
|
114
|
+
return {
|
|
115
|
+
status: "fail",
|
|
116
|
+
message: `stale quarantine entry: remove it. ${entry.case} › ${entry.target} › ${entry.layer} ${what} (quarantined for ${entry.issue}: ${entry.reason}).${pixels}`
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Records an outcome on a task and returns what was recorded. A failure the subject's quarantine
|
|
121
|
+
* covers is recorded as quarantined and does not fail the test. A pass or a skip is recorded as
|
|
122
|
+
* it is, even under an entry: one test cannot tell a stale entry from one another test of the
|
|
123
|
+
* cell still needs, so the run decides (see `settleOutcome`). Several records for the same layer
|
|
124
|
+
* merge (fail beats pass); a task records one case and target only.
|
|
125
|
+
*/
|
|
126
|
+
function recordLayer(task, subject, layer, outcome) {
|
|
127
|
+
if (outcome.status === "skip" && !isSkipReason(outcome.reason)) throw new TypeError(`${subject.case} › ${subject.target} › ${layer}: a skip needs a reason, not ${JSON.stringify(outcome.reason)}.`);
|
|
128
|
+
const entry = quarantineFor(subject.quarantine, subject, layer);
|
|
129
|
+
const settled = entry && outcome.status === "fail" ? {
|
|
130
|
+
status: "quarantined",
|
|
131
|
+
issue: entry.issue
|
|
132
|
+
} : outcome;
|
|
133
|
+
const meta = metaOf(task, subject);
|
|
134
|
+
const previous = meta.layers[layer];
|
|
135
|
+
meta.layers[layer] = previous ? mergeOutcomes(previous, settled) : settled;
|
|
136
|
+
return settled;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Records a test that runs against a stand-in for its case's component (ADR-0068): every browser
|
|
140
|
+
* layer fails with the stand-in's cause, and the test is marked so the summary excuses its
|
|
141
|
+
* scenarios. Not a skip: the test still runs, and a quarantine entry for each layer still needs
|
|
142
|
+
* it to fail, so the entries go stale once the target compiles the case.
|
|
143
|
+
*/
|
|
144
|
+
function recordStandIn(task, subject, cause) {
|
|
145
|
+
for (const layer of BROWSER_LAYERS) recordLayer(task, subject, layer, {
|
|
146
|
+
status: "fail",
|
|
147
|
+
message: cause
|
|
148
|
+
});
|
|
149
|
+
metaOf(task, subject).standIn = cause;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Records that a test checked a parity scenario, once per name. The summary compares each
|
|
153
|
+
* target's scenarios of a case with the reference's.
|
|
154
|
+
*/
|
|
155
|
+
function recordScenario(task, subject, name) {
|
|
156
|
+
const meta = metaOf(task, subject);
|
|
157
|
+
const scenarios = meta.scenarios ??= [];
|
|
158
|
+
if (!scenarios.includes(name)) scenarios.push(name);
|
|
159
|
+
}
|
|
160
|
+
/** The task's record, created for the subject on first use: a test records one case and target. */
|
|
161
|
+
function metaOf(task, subject) {
|
|
162
|
+
const meta = task.meta.uf ??= {
|
|
163
|
+
case: subject.case,
|
|
164
|
+
target: subject.target,
|
|
165
|
+
layers: {}
|
|
166
|
+
};
|
|
167
|
+
if (meta.case !== subject.case || meta.target !== subject.target) throw new Error(`A test records one case and target: it recorded ${meta.case} › ${meta.target}, then ${subject.case} › ${subject.target}.`);
|
|
168
|
+
return meta;
|
|
169
|
+
}
|
|
170
|
+
/** The messages of every failed layer a task recorded, in layer order. */
|
|
171
|
+
function layerFailures(task) {
|
|
172
|
+
const layers = task.meta.uf?.layers ?? {};
|
|
173
|
+
return LAYERS.flatMap((layer) => {
|
|
174
|
+
const outcome = layers[layer];
|
|
175
|
+
return outcome?.status === "fail" ? [`${layer}: ${outcome.message}`] : [];
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
/** A skip reason the matrix can show: a non-blank string. */
|
|
179
|
+
function isSkipReason(reason) {
|
|
180
|
+
return typeof reason === "string" && reason.trim() !== "";
|
|
181
|
+
}
|
|
182
|
+
/** A check's return value as an outcome: nothing passes, `{ skip: reason }` skips. */
|
|
183
|
+
function outcomeOfResult(result) {
|
|
184
|
+
if (result === void 0) return { status: "pass" };
|
|
185
|
+
if (typeof result === "object" && result !== null && "skip" in result) {
|
|
186
|
+
if (isSkipReason(result.skip)) return {
|
|
187
|
+
status: "skip",
|
|
188
|
+
reason: result.skip
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
return {
|
|
192
|
+
status: "fail",
|
|
193
|
+
message: `The check returned ${JSON.stringify(result)}: return nothing to pass, or { skip: reason } with a reason to skip.`
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Runs layer checks in order and records each outcome on the task, without throwing: returns
|
|
198
|
+
* the failures (`"L7: …"`), quarantined ones excluded. A check fails by throwing, and skips by
|
|
199
|
+
* returning `{ skip: reason }` with a non-blank reason; any other return value is a failure,
|
|
200
|
+
* never a silent skip. The browser's `expectParity` records this way, so the spec's own
|
|
201
|
+
* assertions after it still run and are recorded as L8 (see `setup.ts`).
|
|
202
|
+
*/
|
|
203
|
+
async function recordLayerChecks(task, subject, checks) {
|
|
204
|
+
const failures = [];
|
|
205
|
+
for (const layer of LAYERS) {
|
|
206
|
+
const check = checks[layer];
|
|
207
|
+
if (!check) continue;
|
|
208
|
+
let outcome;
|
|
209
|
+
try {
|
|
210
|
+
outcome = outcomeOfResult(await check());
|
|
211
|
+
} catch (error) {
|
|
212
|
+
outcome = {
|
|
213
|
+
status: "fail",
|
|
214
|
+
message: formatError(error)
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
const recorded = recordLayer(task, subject, layer, outcome);
|
|
218
|
+
if (recorded.status === "fail") failures.push(`${layer}: ${recorded.message}`);
|
|
219
|
+
}
|
|
220
|
+
return failures;
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* Runs layer checks in order, records each outcome on the task, and then throws one error with
|
|
224
|
+
* every failure, so a test reports all the layers it broke rather than the first (see
|
|
225
|
+
* `recordLayerChecks`). The Node projects check this way: their tests have nothing to run after.
|
|
226
|
+
*/
|
|
227
|
+
async function checkLayers(task, subject, checks) {
|
|
228
|
+
const failures = await recordLayerChecks(task, subject, checks);
|
|
229
|
+
if (failures.length) throw new LayerFailure(subject, failures);
|
|
230
|
+
}
|
|
231
|
+
/** The error a test fails with when one or more layers failed. */
|
|
232
|
+
var LayerFailure = class extends Error {
|
|
233
|
+
name = "LayerFailure";
|
|
234
|
+
failures;
|
|
235
|
+
constructor(subject, failures) {
|
|
236
|
+
super(`${subject.case} › ${subject.target}: ${failures.length} layer(s) failed\n\n${failures.join("\n\n")}`);
|
|
237
|
+
this.failures = failures;
|
|
238
|
+
}
|
|
239
|
+
};
|
|
240
|
+
//#endregion
|
|
241
|
+
export { BROWSER_LAYERS, LAYERS, LayerFailure, NOT_IN_THIS_RUN_SKIP, NOT_RENDERED_SKIP, NO_INTERACTION_SKIP, NO_OUTPUT_SKIP, NO_OUTPUT_TEST_SKIP, NO_SPEC_SKIP, REQUIRES_SKIP, checkLayers, layerFailures, mergeOutcomes, noOutputSkip, quarantineFor, recordLayer, recordLayerChecks, recordScenario, recordStandIn, requiresSkip, settleOutcome };
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { BrowserEngine } from "../harness.js";
|
|
2
|
+
import { VIEWPORT } from "./viewport.js";
|
|
3
|
+
import { BrowserConfigOptions } from "vitest/node";
|
|
4
|
+
//#region src/node/browser.d.ts
|
|
5
|
+
/**
|
|
6
|
+
* How long a user's action (`view.user.click`, …) waits for its element, as `expect.element`
|
|
7
|
+
* waits the poll timeout (ADR-0043): without it the provider waits for the whole test's
|
|
8
|
+
* timeout, so a locator that matches nothing would hold a failing test, or a browser canary,
|
|
9
|
+
* for a minute.
|
|
10
|
+
*/
|
|
11
|
+
export declare const ACTION_TIMEOUT = 5e3;
|
|
12
|
+
/**
|
|
13
|
+
* A browser command of any signature. Vitest calls it with its command context and the payload
|
|
14
|
+
* the browser sent, which only the command and its caller agree on.
|
|
15
|
+
*/
|
|
16
|
+
export type AnyBrowserCommand = (context: never, ...payload: never[]) => unknown;
|
|
17
|
+
/** Options for {@link parityBrowser}. */
|
|
18
|
+
export interface ParityBrowserOptions {
|
|
19
|
+
/** The project's name, also the instance's (or Vitest appends " (chromium)"). */
|
|
20
|
+
name: string;
|
|
21
|
+
/** Commands besides the testing API's own, such as a target's server-side render. */
|
|
22
|
+
commands?: Readonly<Record<string, AnyBrowserCommand>>;
|
|
23
|
+
/** The engine (`UF_BROWSER`, through the harness's mode); Chromium by default. */
|
|
24
|
+
browser?: BrowserEngine;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* The `test.browser` options of a project that runs the parity layers. A target's command may
|
|
28
|
+
* not take the name of one of the testing API's: it would replace the write policy or the
|
|
29
|
+
* visual comparison for that project without a word.
|
|
30
|
+
*/
|
|
31
|
+
export declare function parityBrowser(options: ParityBrowserOptions): BrowserConfigOptions;
|
|
32
|
+
//#endregion
|
|
33
|
+
export { VIEWPORT };
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { VIEWPORT } from "./viewport.js";
|
|
2
|
+
import { browserCommands } from "./commands.js";
|
|
3
|
+
import { playwright } from "@vitest/browser-playwright";
|
|
4
|
+
//#region src/node/browser.ts
|
|
5
|
+
/**
|
|
6
|
+
* How long a user's action (`view.user.click`, …) waits for its element, as `expect.element`
|
|
7
|
+
* waits the poll timeout (ADR-0043): without it the provider waits for the whole test's
|
|
8
|
+
* timeout, so a locator that matches nothing would hold a failing test, or a browser canary,
|
|
9
|
+
* for a minute.
|
|
10
|
+
*/
|
|
11
|
+
const ACTION_TIMEOUT = 5e3;
|
|
12
|
+
/**
|
|
13
|
+
* The switches Chromium launches with, for the captures (L10):
|
|
14
|
+
*
|
|
15
|
+
* - `--font-render-hinting=none`: Linux headless Chromium hints glyph advances to whole pixels;
|
|
16
|
+
* without hinting, text measures the same on macOS and Linux (form controls still differ, so
|
|
17
|
+
* committed geometry is a Linux baseline, like the pixels).
|
|
18
|
+
* - `--disable-partial-raster`: by default a repaint re-rasterises only the repainted rect,
|
|
19
|
+
* rounded out to whole pixels, over the tile's old pixels. Where a control starts mid-pixel,
|
|
20
|
+
* that edge cuts the anti-aliased corner of the box beside it, which then rasterises one level
|
|
21
|
+
* apart from a whole raster: the same DOM captured differently after a hover, a press or a
|
|
22
|
+
* keystroke repainted one control, depending on which repaints each frame grouped, which
|
|
23
|
+
* differs by target and by load. Each repainted tile is rasterised whole instead, so a capture
|
|
24
|
+
* depends on the DOM, never on what was repainted before it (test/parity/cases/stub/raster).
|
|
25
|
+
* Every reference capture of the corpus is byte-identical with and without it.
|
|
26
|
+
*/
|
|
27
|
+
const CHROMIUM_ARGS = ["--font-render-hinting=none", "--disable-partial-raster"];
|
|
28
|
+
/**
|
|
29
|
+
* The `test.browser` options of a project that runs the parity layers. A target's command may
|
|
30
|
+
* not take the name of one of the testing API's: it would replace the write policy or the
|
|
31
|
+
* visual comparison for that project without a word.
|
|
32
|
+
*/
|
|
33
|
+
function parityBrowser(options) {
|
|
34
|
+
const taken = Object.keys(options.commands ?? {}).filter((name) => Object.hasOwn(browserCommands, name));
|
|
35
|
+
if (taken.length) throw new Error(`[uf] parityBrowser(${options.name}): ${taken.join(", ")} would replace the testing API's own command(s). Give the target's command another name.`);
|
|
36
|
+
const browser = options.browser ?? "chromium";
|
|
37
|
+
return {
|
|
38
|
+
enabled: true,
|
|
39
|
+
headless: true,
|
|
40
|
+
viewport: VIEWPORT,
|
|
41
|
+
provider: playwright({
|
|
42
|
+
actionTimeout: ACTION_TIMEOUT,
|
|
43
|
+
launchOptions: { args: browser === "chromium" ? [...CHROMIUM_ARGS] : [] },
|
|
44
|
+
contextOptions: {
|
|
45
|
+
deviceScaleFactor: 1,
|
|
46
|
+
colorScheme: "light",
|
|
47
|
+
reducedMotion: "reduce",
|
|
48
|
+
forcedColors: "none",
|
|
49
|
+
locale: "en-US",
|
|
50
|
+
timezoneId: "UTC"
|
|
51
|
+
}
|
|
52
|
+
}),
|
|
53
|
+
instances: [{
|
|
54
|
+
browser,
|
|
55
|
+
name: options.name
|
|
56
|
+
}],
|
|
57
|
+
commands: {
|
|
58
|
+
...browserCommands,
|
|
59
|
+
...options.commands
|
|
60
|
+
}
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
//#endregion
|
|
64
|
+
export { ACTION_TIMEOUT, VIEWPORT, parityBrowser };
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
import { ColorScheme } from "../harness.js";
|
|
2
|
+
import { ArtefactRequest, ArtefactResult, ComponentEventsRequest, ComponentEventsResult, InputRequest, InputResult, SerializedLocatorLike } from "../commands.js";
|
|
3
|
+
import { CommandProject } from "./context.js";
|
|
4
|
+
import { ufSpecFinished } from "./finished.js";
|
|
5
|
+
import { ufVisualCapture } from "./visual.js";
|
|
6
|
+
//#region src/node/commands.d.ts
|
|
7
|
+
/**
|
|
8
|
+
* `ufArtefact`: settles a shared expectation the browser computed (L7, L9). Contents of `null`
|
|
9
|
+
* say the scenario has no such file: only a trace may be absent, when no step led to it.
|
|
10
|
+
*/
|
|
11
|
+
export declare function ufArtefact(context: CommandProject, request: ArtefactRequest): ArtefactResult;
|
|
12
|
+
/** What the ARIA and focus commands need from Vitest's command context (Playwright provider). */
|
|
13
|
+
export interface AriaCommandContext {
|
|
14
|
+
iframe: {
|
|
15
|
+
locator(selector: string): {
|
|
16
|
+
ariaSnapshot(): Promise<string>;
|
|
17
|
+
};
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
/** `ufAriaSnapshot`: Playwright's ARIA snapshot of the element a locator points at (L7). */
|
|
21
|
+
export declare function ufAriaSnapshot(context: AriaCommandContext, locator: SerializedLocatorLike): Promise<string>;
|
|
22
|
+
/** What the focus command needs from Vitest's command context (Playwright provider). */
|
|
23
|
+
export interface FocusCommandContext {
|
|
24
|
+
iframe: {
|
|
25
|
+
locator(selector: string): {
|
|
26
|
+
focus(): Promise<void>;
|
|
27
|
+
};
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* `ufFocus`: focuses the element a locator points at, as Playwright's `locator.focus()` does
|
|
32
|
+
* (`view.user.focus`), waiting for it within the action timeout. Vitest's `userEvent` has no
|
|
33
|
+
* focus action.
|
|
34
|
+
*/
|
|
35
|
+
export declare function ufFocus(context: FocusCommandContext, locator: SerializedLocatorLike): Promise<void>;
|
|
36
|
+
/** What the input command needs from Vitest's command context (Playwright provider). */
|
|
37
|
+
export interface InputContext {
|
|
38
|
+
page: {
|
|
39
|
+
mouse: {
|
|
40
|
+
down(options: {
|
|
41
|
+
clickCount: number;
|
|
42
|
+
}): Promise<void>;
|
|
43
|
+
up(options: {
|
|
44
|
+
clickCount: number;
|
|
45
|
+
}): Promise<void>;
|
|
46
|
+
wheel(deltaX: number, deltaY: number): Promise<void>;
|
|
47
|
+
};
|
|
48
|
+
keyboard: {
|
|
49
|
+
down(key: string): Promise<void>;
|
|
50
|
+
up(key: string): Promise<void>;
|
|
51
|
+
insertText(text: string): Promise<void>;
|
|
52
|
+
};
|
|
53
|
+
};
|
|
54
|
+
iframe: {
|
|
55
|
+
locator(selector: string): {
|
|
56
|
+
isEnabled(): Promise<boolean>;
|
|
57
|
+
hover(options: {
|
|
58
|
+
position?: {
|
|
59
|
+
x: number;
|
|
60
|
+
y: number;
|
|
61
|
+
};
|
|
62
|
+
}): Promise<void>;
|
|
63
|
+
};
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* `ufInput`: dispatches one input of a `view.user` action, so the browser side can settle the
|
|
68
|
+
* page between two inputs, as the time between a person's would let it (ADR-0050). The move is
|
|
69
|
+
* Playwright's hover: it waits until the element is visible, stable and the one under the point,
|
|
70
|
+
* then moves the mouse to the point Playwright's click would press; a move before a click then
|
|
71
|
+
* refuses a disabled element, which that click would wait on until it timed out. The presses
|
|
72
|
+
* and releases happen where the mouse is, as in Playwright's click. A key is Playwright's
|
|
73
|
+
* keyboard's, and a character its US layout lacks is inserted as text with no key, as Vitest's
|
|
74
|
+
* `userEvent.keyboard` does: its release does nothing.
|
|
75
|
+
*/
|
|
76
|
+
export declare function ufInput(context: InputContext, request: InputRequest): Promise<InputResult>;
|
|
77
|
+
/** What the input reset needs from Vitest's command context (Playwright provider). */
|
|
78
|
+
export interface InputCommandContext {
|
|
79
|
+
page: {
|
|
80
|
+
mouse: {
|
|
81
|
+
move(x: number, y: number): Promise<void>;
|
|
82
|
+
};
|
|
83
|
+
};
|
|
84
|
+
frame(): Promise<{
|
|
85
|
+
frameElement(): Promise<{
|
|
86
|
+
boundingBox(): Promise<{
|
|
87
|
+
x: number;
|
|
88
|
+
y: number;
|
|
89
|
+
width: number;
|
|
90
|
+
height: number;
|
|
91
|
+
} | null>;
|
|
92
|
+
}>;
|
|
93
|
+
}>;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* `ufResetInput`: moves the mouse to the bottom right corner of the tester frame, off every mount
|
|
97
|
+
* root (they sit at the top left), so the next test starts with nothing hovered. Vitest's
|
|
98
|
+
* `unhover` hovers the body's centre instead, which is inside any wide root. The browser side
|
|
99
|
+
* releases the keys and the focus (see `resetInput`).
|
|
100
|
+
*/
|
|
101
|
+
export declare function ufResetInput(context: InputCommandContext): Promise<void>;
|
|
102
|
+
/** What the colour-scheme command needs from Vitest's command context (Playwright provider). */
|
|
103
|
+
export interface ColorSchemeContext {
|
|
104
|
+
page: {
|
|
105
|
+
emulateMedia(options: {
|
|
106
|
+
colorScheme: ColorScheme;
|
|
107
|
+
}): Promise<void>;
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* `ufColorScheme`: emulates the `prefers-color-scheme` a case opts into (`case.json`'s
|
|
112
|
+
* `colorScheme`, ADR-0061) for the page its spec file runs in, before anything mounts. The setup
|
|
113
|
+
* file sets it for every spec file, `light` by default, so no file runs in the scheme of the file
|
|
114
|
+
* before it.
|
|
115
|
+
*/
|
|
116
|
+
export declare function ufColorScheme(context: ColorSchemeContext, scheme: ColorScheme): Promise<void>;
|
|
117
|
+
/**
|
|
118
|
+
* `ufComponentEvents`: the events the component of a case declares, from the project's own
|
|
119
|
+
* compile of the case's main `.uf.tsx` (`recordCompiledModule`), so a mount listens to exactly
|
|
120
|
+
* those (an undeclared `onX` would fall through to Vue's root as a native listener). The main
|
|
121
|
+
* source is the case's only one, or the one its `case.json` names (ADR-0057): the spec mounts
|
|
122
|
+
* it, and its children's events reach only it.
|
|
123
|
+
*/
|
|
124
|
+
export declare function ufComponentEvents(context: CommandProject, request: ComponentEventsRequest): ComponentEventsResult;
|
|
125
|
+
/** Every command the testing API needs, keyed by the name the browser calls. */
|
|
126
|
+
export declare const browserCommands: {
|
|
127
|
+
ufArtefact: typeof ufArtefact;
|
|
128
|
+
ufAriaSnapshot: typeof ufAriaSnapshot;
|
|
129
|
+
ufVisualCapture: typeof ufVisualCapture;
|
|
130
|
+
ufFocus: typeof ufFocus;
|
|
131
|
+
ufInput: typeof ufInput;
|
|
132
|
+
ufResetInput: typeof ufResetInput;
|
|
133
|
+
ufColorScheme: typeof ufColorScheme;
|
|
134
|
+
ufComponentEvents: typeof ufComponentEvents;
|
|
135
|
+
ufSpecFinished: typeof ufSpecFinished;
|
|
136
|
+
};
|
|
137
|
+
//#endregion
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import { COLOR_SCHEMES } from "../harness.js";
|
|
2
|
+
import { caseDirectory, caseMainSource, projectHarness, sharedArtefactContext } from "./context.js";
|
|
3
|
+
import { compiledEvents } from "./events.js";
|
|
4
|
+
import { ufSpecFinished } from "./finished.js";
|
|
5
|
+
import { KEBAB_CASE } from "./names.js";
|
|
6
|
+
import { settleArtefact } from "./policy.js";
|
|
7
|
+
import { VIEWPORT } from "./viewport.js";
|
|
8
|
+
import { ufVisualCapture } from "./visual.js";
|
|
9
|
+
import { join } from "node:path";
|
|
10
|
+
//#region src/node/commands.ts
|
|
11
|
+
/**
|
|
12
|
+
* The shared expectations the browser may settle: `dom.<name>.html` and `aria.<name>.yaml` (L7)
|
|
13
|
+
* and `trace.<name>.json` (L9).
|
|
14
|
+
*/
|
|
15
|
+
const BROWSER_ARTEFACT = /^(?:dom\.(.*)\.html|aria\.(.*)\.yaml|trace\.(.*)\.json)$/;
|
|
16
|
+
/** Whether a file is a browser artefact of a scenario with a {@link KEBAB_CASE} name. */
|
|
17
|
+
function isBrowserArtefact(file) {
|
|
18
|
+
const match = BROWSER_ARTEFACT.exec(file);
|
|
19
|
+
const scenario = match?.[1] ?? match?.[2] ?? match?.[3];
|
|
20
|
+
return scenario !== void 0 && KEBAB_CASE.test(scenario);
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* `ufArtefact`: settles a shared expectation the browser computed (L7, L9). Contents of `null`
|
|
24
|
+
* say the scenario has no such file: only a trace may be absent, when no step led to it.
|
|
25
|
+
*/
|
|
26
|
+
function ufArtefact(context, request) {
|
|
27
|
+
const { target, harness } = projectHarness(context);
|
|
28
|
+
if (!isBrowserArtefact(request.file)) throw new Error(`[uf] "${request.file}" is not a browser artefact (dom.<name>.html, aria.<name>.yaml, trace.<name>.json).`);
|
|
29
|
+
if (request.contents === null && !request.file.startsWith("trace.")) throw new Error(`[uf] "${request.file}" always has contents: only a trace may be absent.`);
|
|
30
|
+
const path = join(caseDirectory(harness, request.case), "__expected__", request.file);
|
|
31
|
+
const outcome = settleArtefact(path, request.contents ?? void 0, sharedArtefactContext(harness, target, request.case));
|
|
32
|
+
return {
|
|
33
|
+
pass: outcome.pass,
|
|
34
|
+
status: outcome.status,
|
|
35
|
+
message: outcome.message
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
/** `ufAriaSnapshot`: Playwright's ARIA snapshot of the element a locator points at (L7). */
|
|
39
|
+
function ufAriaSnapshot(context, locator) {
|
|
40
|
+
return context.iframe.locator(locator.selector).ariaSnapshot();
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* `ufFocus`: focuses the element a locator points at, as Playwright's `locator.focus()` does
|
|
44
|
+
* (`view.user.focus`), waiting for it within the action timeout. Vitest's `userEvent` has no
|
|
45
|
+
* focus action.
|
|
46
|
+
*/
|
|
47
|
+
function ufFocus(context, locator) {
|
|
48
|
+
return context.iframe.locator(locator.selector).focus();
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* `ufInput`: dispatches one input of a `view.user` action, so the browser side can settle the
|
|
52
|
+
* page between two inputs, as the time between a person's would let it (ADR-0050). The move is
|
|
53
|
+
* Playwright's hover: it waits until the element is visible, stable and the one under the point,
|
|
54
|
+
* then moves the mouse to the point Playwright's click would press; a move before a click then
|
|
55
|
+
* refuses a disabled element, which that click would wait on until it timed out. The presses
|
|
56
|
+
* and releases happen where the mouse is, as in Playwright's click. A key is Playwright's
|
|
57
|
+
* keyboard's, and a character its US layout lacks is inserted as text with no key, as Vitest's
|
|
58
|
+
* `userEvent.keyboard` does: its release does nothing.
|
|
59
|
+
*/
|
|
60
|
+
async function ufInput(context, request) {
|
|
61
|
+
const { mouse, keyboard } = context.page;
|
|
62
|
+
switch (request.kind) {
|
|
63
|
+
case "move": {
|
|
64
|
+
const target = context.iframe.locator(request.locator.selector);
|
|
65
|
+
await target.hover(request.position ? { position: request.position } : {});
|
|
66
|
+
if (request.check === "click" && !await target.isEnabled()) throw new Error(`${request.locator.locator} is disabled: a click on it would do nothing. Click it once it is enabled.`);
|
|
67
|
+
return { inserted: false };
|
|
68
|
+
}
|
|
69
|
+
case "press":
|
|
70
|
+
await mouse.down({ clickCount: request.clickCount });
|
|
71
|
+
return { inserted: false };
|
|
72
|
+
case "release":
|
|
73
|
+
await mouse.up({ clickCount: request.clickCount });
|
|
74
|
+
return { inserted: false };
|
|
75
|
+
case "wheel":
|
|
76
|
+
await mouse.wheel(request.deltaX, request.deltaY);
|
|
77
|
+
return { inserted: false };
|
|
78
|
+
case "keydown": try {
|
|
79
|
+
await keyboard.down(request.key);
|
|
80
|
+
return { inserted: false };
|
|
81
|
+
} catch (error) {
|
|
82
|
+
if (!request.text || !UNKNOWN_KEY.test(String(error))) throw error;
|
|
83
|
+
await keyboard.insertText(request.key);
|
|
84
|
+
return { inserted: true };
|
|
85
|
+
}
|
|
86
|
+
case "keyup":
|
|
87
|
+
await keyboard.up(request.key);
|
|
88
|
+
return { inserted: false };
|
|
89
|
+
default: throw new TypeError(`ufInput: no input is ${JSON.stringify(request)}.`);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
/** Playwright's refusal of a key its keyboard layout does not have. */
|
|
93
|
+
const UNKNOWN_KEY = /Unknown key: /;
|
|
94
|
+
/**
|
|
95
|
+
* `ufResetInput`: moves the mouse to the bottom right corner of the tester frame, off every mount
|
|
96
|
+
* root (they sit at the top left), so the next test starts with nothing hovered. Vitest's
|
|
97
|
+
* `unhover` hovers the body's centre instead, which is inside any wide root. The browser side
|
|
98
|
+
* releases the keys and the focus (see `resetInput`).
|
|
99
|
+
*/
|
|
100
|
+
async function ufResetInput(context) {
|
|
101
|
+
const box = await (await (await context.frame()).frameElement()).boundingBox();
|
|
102
|
+
const { width, height } = box ?? VIEWPORT;
|
|
103
|
+
await context.page.mouse.move((box?.x ?? 0) + width - 1, (box?.y ?? 0) + height - 1);
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* `ufColorScheme`: emulates the `prefers-color-scheme` a case opts into (`case.json`'s
|
|
107
|
+
* `colorScheme`, ADR-0061) for the page its spec file runs in, before anything mounts. The setup
|
|
108
|
+
* file sets it for every spec file, `light` by default, so no file runs in the scheme of the file
|
|
109
|
+
* before it.
|
|
110
|
+
*/
|
|
111
|
+
async function ufColorScheme(context, scheme) {
|
|
112
|
+
if (!COLOR_SCHEMES.includes(scheme)) throw new TypeError(`ufColorScheme: ${JSON.stringify(scheme)} is not a colour scheme (${COLOR_SCHEMES.join(", ")}).`);
|
|
113
|
+
await context.page.emulateMedia({ colorScheme: scheme });
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* `ufComponentEvents`: the events the component of a case declares, from the project's own
|
|
117
|
+
* compile of the case's main `.uf.tsx` (`recordCompiledModule`), so a mount listens to exactly
|
|
118
|
+
* those (an undeclared `onX` would fall through to Vue's root as a native listener). The main
|
|
119
|
+
* source is the case's only one, or the one its `case.json` names (ADR-0057): the spec mounts
|
|
120
|
+
* it, and its children's events reach only it.
|
|
121
|
+
*/
|
|
122
|
+
function ufComponentEvents(context, request) {
|
|
123
|
+
const { target, harness } = projectHarness(context);
|
|
124
|
+
return { events: compiledEvents(caseMainSource(harness, request.case), target) };
|
|
125
|
+
}
|
|
126
|
+
/** Every command the testing API needs, keyed by the name the browser calls. */
|
|
127
|
+
const browserCommands = {
|
|
128
|
+
ufArtefact,
|
|
129
|
+
ufAriaSnapshot,
|
|
130
|
+
ufVisualCapture,
|
|
131
|
+
ufFocus,
|
|
132
|
+
ufInput,
|
|
133
|
+
ufResetInput,
|
|
134
|
+
ufColorScheme,
|
|
135
|
+
ufComponentEvents,
|
|
136
|
+
ufSpecFinished
|
|
137
|
+
};
|
|
138
|
+
//#endregion
|
|
139
|
+
export { browserCommands, ufAriaSnapshot, ufArtefact, ufColorScheme, ufComponentEvents, ufFocus, ufInput, ufResetInput };
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { HarnessContext } from "../harness.js";
|
|
2
|
+
import { ArtefactContext } from "./policy.js";
|
|
3
|
+
//#region src/node/context.d.ts
|
|
4
|
+
/** The part of Vitest's `BrowserCommandContext` the commands read. */
|
|
5
|
+
export interface CommandProject {
|
|
6
|
+
project: {
|
|
7
|
+
name: string;
|
|
8
|
+
getProvidedContext(): {
|
|
9
|
+
target?: string;
|
|
10
|
+
ufHarness?: HarnessContext;
|
|
11
|
+
};
|
|
12
|
+
};
|
|
13
|
+
}
|
|
14
|
+
/** The calling project's target and harness context; throws if the project does not provide them. */
|
|
15
|
+
export declare function projectHarness(context: CommandProject): {
|
|
16
|
+
target: string;
|
|
17
|
+
harness: HarnessContext;
|
|
18
|
+
};
|
|
19
|
+
/** The case directory of a case id, refusing ids that are not known cases. */
|
|
20
|
+
export declare function caseDirectory(harness: HarnessContext, id: string): string;
|
|
21
|
+
/** The directory artefact paths are shown relative to: the cases directory's parent. */
|
|
22
|
+
export declare function displayRoot(harness: HarnessContext): string;
|
|
23
|
+
/**
|
|
24
|
+
* How a target settles a case's artefacts every target shares (`__expected__/*`): the case's
|
|
25
|
+
* reference (ADR-0057) writes them in update mode, everyone else compares.
|
|
26
|
+
*/
|
|
27
|
+
export declare function sharedArtefactContext(harness: HarnessContext, target: string, caseId: string): ArtefactContext;
|
|
28
|
+
//#endregion
|