@unframework.dev/testing 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/README.md +511 -2
  2. package/dist/browser/axe.js +34 -0
  3. package/dist/browser/behaviour.js +59 -0
  4. package/dist/browser/capabilities.js +58 -0
  5. package/dist/browser/clock.d.ts +17 -0
  6. package/dist/browser/clock.js +69 -0
  7. package/dist/browser/console.d.ts +27 -0
  8. package/dist/browser/console.js +142 -0
  9. package/dist/browser/determinism.js +108 -0
  10. package/dist/browser/element-timeout.js +28 -0
  11. package/dist/browser/events.js +68 -0
  12. package/dist/browser/geometry.js +135 -0
  13. package/dist/browser/keys.js +62 -0
  14. package/dist/browser/matchers.d.ts +39 -0
  15. package/dist/browser/matchers.js +78 -0
  16. package/dist/browser/navigation.js +38 -0
  17. package/dist/browser/parity.d.ts +10 -0
  18. package/dist/browser/parity.js +93 -0
  19. package/dist/browser/spec.d.ts +25 -0
  20. package/dist/browser/spec.js +38 -0
  21. package/dist/browser/target.d.ts +16 -0
  22. package/dist/browser/target.js +27 -0
  23. package/dist/browser/text-runs.js +68 -0
  24. package/dist/browser/thrown.js +71 -0
  25. package/dist/browser/trace.d.ts +21 -0
  26. package/dist/browser/trace.js +73 -0
  27. package/dist/browser/user.d.ts +45 -0
  28. package/dist/browser/user.js +184 -0
  29. package/dist/browser/view.d.ts +114 -0
  30. package/dist/browser/view.js +282 -0
  31. package/dist/browser/visual.d.ts +20 -0
  32. package/dist/browser/visual.js +36 -0
  33. package/dist/cli.d.ts +23 -0
  34. package/dist/cli.js +90 -0
  35. package/dist/commands.d.ts +107 -0
  36. package/dist/config/broadcast.js +29 -0
  37. package/dist/config/cases.d.ts +28 -0
  38. package/dist/config/cases.js +94 -0
  39. package/dist/config/index.d.ts +81 -0
  40. package/dist/config/index.js +275 -0
  41. package/dist/diff.d.ts +14 -0
  42. package/dist/diff.js +92 -0
  43. package/dist/dom/serialize.js +236 -0
  44. package/dist/errors.d.ts +13 -0
  45. package/dist/errors.js +38 -0
  46. package/dist/harness.d.ts +184 -0
  47. package/dist/harness.js +53 -0
  48. package/dist/index.d.ts +16 -0
  49. package/dist/index.js +12 -0
  50. package/dist/internal.d.ts +8 -0
  51. package/dist/internal.js +6 -0
  52. package/dist/layers.d.ts +183 -0
  53. package/dist/layers.js +241 -0
  54. package/dist/node/browser.d.ts +33 -0
  55. package/dist/node/browser.js +64 -0
  56. package/dist/node/commands.d.ts +137 -0
  57. package/dist/node/commands.js +139 -0
  58. package/dist/node/context.d.ts +28 -0
  59. package/dist/node/context.js +55 -0
  60. package/dist/node/events.d.ts +25 -0
  61. package/dist/node/events.js +50 -0
  62. package/dist/node/finished.d.ts +12 -0
  63. package/dist/node/finished.js +28 -0
  64. package/dist/node/index.d.ts +21 -0
  65. package/dist/node/index.js +20 -0
  66. package/dist/node/matrix.d.ts +219 -0
  67. package/dist/node/matrix.js +309 -0
  68. package/dist/node/mode.d.ts +101 -0
  69. package/dist/node/mode.js +201 -0
  70. package/dist/node/names.d.ts +4 -0
  71. package/dist/node/names.js +5 -0
  72. package/dist/node/policy.d.ts +44 -0
  73. package/dist/node/policy.js +140 -0
  74. package/dist/node/reporter.d.ts +101 -0
  75. package/dist/node/reporter.js +251 -0
  76. package/dist/node/summary.d.ts +99 -0
  77. package/dist/node/summary.js +352 -0
  78. package/dist/node/thrown.js +78 -0
  79. package/dist/node/viewport.d.ts +7 -0
  80. package/dist/node/viewport.js +8 -0
  81. package/dist/node/visual.d.ts +85 -0
  82. package/dist/node/visual.js +370 -0
  83. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/protocol.d.ts +23930 -0
  84. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/structs.d.ts +22 -0
  85. package/dist/node_modules/.pnpm/playwright-core@1.63.0/node_modules/playwright-core/types/types.d.ts +22221 -0
  86. package/dist/normalize/display.js +309 -0
  87. package/dist/normalize/index.d.ts +34 -0
  88. package/dist/normalize/index.js +38 -0
  89. package/dist/normalize/pipeline.d.ts +19 -0
  90. package/dist/normalize/pipeline.js +45 -0
  91. package/dist/normalize/print.js +103 -0
  92. package/dist/normalize/rules/angular-hosts.js +53 -0
  93. package/dist/normalize/rules/aria-hosts.js +48 -0
  94. package/dist/normalize/rules/comments.js +16 -0
  95. package/dist/normalize/rules/control-values.js +65 -0
  96. package/dist/normalize/rules/engine-aliases.js +34 -0
  97. package/dist/normalize/rules/framework-attributes.js +85 -0
  98. package/dist/normalize/rules/generated-ids.js +64 -0
  99. package/dist/normalize/rules/ordering.js +39 -0
  100. package/dist/normalize/rules/qwik-styles.js +21 -0
  101. package/dist/normalize/rules/qwik-templates.js +20 -0
  102. package/dist/normalize/rules/values.js +125 -0
  103. package/dist/normalize/rules/whitespace.js +381 -0
  104. package/dist/normalize/style.js +121 -0
  105. package/dist/normalize/targets.d.ts +8 -0
  106. package/dist/normalize/targets.js +17 -0
  107. package/dist/normalize/tree.d.ts +1 -0
  108. package/dist/normalize/tree.js +151 -0
  109. package/dist/setup.d.ts +1 -0
  110. package/dist/setup.js +149 -0
  111. package/dist/ssr/index.d.ts +10 -0
  112. package/dist/ssr/index.js +103 -0
  113. package/dist/ssr/spec.d.ts +1 -0
  114. package/dist/ssr/spec.js +7 -0
  115. package/dist/targets/angular.d.ts +1 -0
  116. package/dist/targets/angular.js +5 -0
  117. package/dist/targets/astro.d.ts +1 -0
  118. package/dist/targets/astro.js +5 -0
  119. package/dist/targets/qwik.d.ts +1 -0
  120. package/dist/targets/qwik.js +5 -0
  121. package/dist/targets/react.d.ts +1 -0
  122. package/dist/targets/react.js +5 -0
  123. package/dist/targets/solid.d.ts +1 -0
  124. package/dist/targets/solid.js +5 -0
  125. package/dist/targets/svelte.d.ts +1 -0
  126. package/dist/targets/svelte.js +5 -0
  127. package/dist/targets/vue.d.ts +1 -0
  128. package/dist/targets/vue.js +5 -0
  129. package/dist/visual-types.d.ts +92 -0
  130. package/dist/visual-types.js +24 -0
  131. package/package.json +135 -3
package/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