@spartan-native/host-conformance 0.0.0-stage → 0.2.1
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/AGENTS.md
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# AGENTS.md: @spartan-native/host-conformance
|
|
2
|
+
|
|
3
|
+
Instructions for AI coding agents writing or testing a `NativeHost` adapter.
|
|
4
|
+
|
|
5
|
+
## What this package is
|
|
6
|
+
|
|
7
|
+
The test suite every `@spartan-native/host-*` adapter must pass. It has no framework dependency: use it from Vitest, Jest or Jasmine, or call it as a plain function. An app doesn't need it at runtime. Use it in adapter tests, or in a custom host you write for your own runtime.
|
|
8
|
+
|
|
9
|
+
## Public API (`import … from '@spartan-native/host-conformance'`)
|
|
10
|
+
|
|
11
|
+
| Symbol | Use |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| `describeHostConformance(name, () => ({ host, driver? }))` | Registers one test per check in the current runner |
|
|
14
|
+
| `checkHostConformance(host, driver?)` | Runs every check and resolves `{ runtime, passed, results: [{ id, title, status, detail? }] }`. Never throws |
|
|
15
|
+
| `CHECKS`, `Check`, `SkipCheck` | The checks themselves, for custom runners |
|
|
16
|
+
| `HostDriver` | `{ setAppearance?(patch), setFocused?(focused) }`: lets the suite simulate the OS so the live checks run |
|
|
17
|
+
| `validatePlatform()`, `validateAppearance()` | Shape validators for an adapter's own tests |
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
describeHostConformance('myHost', () => {
|
|
21
|
+
const runtime = fakeRuntime();
|
|
22
|
+
return {
|
|
23
|
+
host: myHost({ runtime }),
|
|
24
|
+
driver: { setAppearance: (p) => runtime.emitTheme(p), setFocused: (f) => runtime.emitFocus(f) },
|
|
25
|
+
};
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## What a host must satisfy
|
|
30
|
+
|
|
31
|
+
- `runtime` is known. Every capability is `native`, `partial` or `none`. `platform()` and `appearance()` return valid shapes, and their skins agree.
|
|
32
|
+
- `menus` is present **exactly** when `nativeMenus !== 'none'`, with `onAction` plus `setApplicationMenu` or `showContextMenu`.
|
|
33
|
+
- `dialogs` is present **exactly** when `fileDialogs !== 'none'`, with `openFile`, `saveFile` and `pickFolder` (`message` is optional).
|
|
34
|
+
- Every subscribe returns an unsubscribe function that's safe to call twice. Nothing throws for capabilities reported as `none`.
|
|
35
|
+
- With a driver: appearance and focus changes are notified, and stop after unsubscribing.
|
|
36
|
+
|
|
37
|
+
## Rules for adapter authors
|
|
38
|
+
|
|
39
|
+
1. Report capabilities honestly. Use `partial` when it works only in some cases, and leave an optional service out entirely instead of shipping one that throws.
|
|
40
|
+
2. A cancelled dialog resolves `[]` or `null`. It must never reject.
|
|
41
|
+
3. Every new adapter's spec runs `describeHostConformance` with a fake runtime and a driver.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Roland Molnár
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,53 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @spartan-native/host-conformance
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**The test suite every `@spartan-native/host-*` adapter must pass.** It is framework-free. Use it from any test runner, or as a function that returns a report.
|
|
4
|
+
|
|
5
|
+
> Status: **implemented.** `webHost` and `staticHost` pass it. Spec: [`07-host-adapters.md`](https://github.com/Spartan-Native/spartan-native/blob/main/docs/07-host-adapters.md).
|
|
6
|
+
|
|
7
|
+
## In a test runner (Vitest, Jest, Jasmine)
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import { describeHostConformance } from '@spartan-native/host-conformance';
|
|
11
|
+
|
|
12
|
+
describeHostConformance('wailsHost', () => {
|
|
13
|
+
const runtime = fakeWailsRuntime();
|
|
14
|
+
return {
|
|
15
|
+
host: wailsHost({ runtime }),
|
|
16
|
+
// optional: lets the suite simulate the OS, so the live checks run too
|
|
17
|
+
driver: {
|
|
18
|
+
setAppearance: (patch) => runtime.emitThemeChange(patch),
|
|
19
|
+
setFocused: (focused) => runtime.emitFocus(focused),
|
|
20
|
+
},
|
|
21
|
+
};
|
|
22
|
+
});
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Each check becomes one test, so a failure names exactly what is wrong. Without a driver, the live checks are skipped (logged) rather than failed.
|
|
26
|
+
|
|
27
|
+
## As a function
|
|
28
|
+
|
|
29
|
+
```ts
|
|
30
|
+
const report = await checkHostConformance(host, driver);
|
|
31
|
+
report.passed; // false if any check failed
|
|
32
|
+
report.results; // [{ id, title, status: 'pass' | 'fail' | 'skip', detail? }]
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## The checks
|
|
36
|
+
|
|
37
|
+
| id | Checks |
|
|
38
|
+
| --- | --- |
|
|
39
|
+
| `runtime` | `runtime` is a known runtime |
|
|
40
|
+
| `capabilities` | every capability is present and is `native`, `partial` or `none` |
|
|
41
|
+
| `platform` | `platform()` resolves a valid `PlatformInfo` |
|
|
42
|
+
| `appearance` | `appearance()` resolves a valid `AppearanceState` (`#rrggbb` accent, enums, booleans, text scale) |
|
|
43
|
+
| `skin-agrees` | `appearance().skin` equals `platform().skin` |
|
|
44
|
+
| `focus` | `window.isFocused()` resolves a boolean |
|
|
45
|
+
| `menus-match-capability` | `menus` is present exactly when `nativeMenus` isn't `none`; it has `onAction` and at least one of `setApplicationMenu` / `showContextMenu` |
|
|
46
|
+
| `dialogs-match-capability` | `dialogs` is present exactly when `fileDialogs` isn't `none`; it has `openFile`, `saveFile` and `pickFolder` (`message` is optional) |
|
|
47
|
+
| `unsubscribe` | subscriptions return an unsubscribe function, safe to call twice |
|
|
48
|
+
| `graceful` | nothing throws for capabilities reported as `none` |
|
|
49
|
+
| `live-appearance` | _(driver)_ an OS change is notified, with the new values |
|
|
50
|
+
| `live-appearance-stops` | _(driver)_ no notifications after unsubscribe |
|
|
51
|
+
| `live-focus` | _(driver)_ focus changes are notified |
|
|
52
|
+
|
|
53
|
+
Validators `validatePlatform()` and `validateAppearance()` are exported for adapters' own tests.
|
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
import { CAPABILITIES } from "@spartan-native/theme";
|
|
2
|
+
const RUNTIMES = [
|
|
3
|
+
"web",
|
|
4
|
+
"wails",
|
|
5
|
+
"tauri",
|
|
6
|
+
"electron",
|
|
7
|
+
"dotnet",
|
|
8
|
+
"static"
|
|
9
|
+
];
|
|
10
|
+
const SKINS = [
|
|
11
|
+
"win",
|
|
12
|
+
"w10",
|
|
13
|
+
"mac",
|
|
14
|
+
"macc",
|
|
15
|
+
"gtk",
|
|
16
|
+
"qt",
|
|
17
|
+
"cros",
|
|
18
|
+
"web"
|
|
19
|
+
];
|
|
20
|
+
const OSES = [
|
|
21
|
+
"windows",
|
|
22
|
+
"macos",
|
|
23
|
+
"linux",
|
|
24
|
+
"chromeos",
|
|
25
|
+
"unknown"
|
|
26
|
+
];
|
|
27
|
+
const DESKTOPS = [
|
|
28
|
+
"gnome",
|
|
29
|
+
"kde",
|
|
30
|
+
"cinnamon",
|
|
31
|
+
"xfce",
|
|
32
|
+
"other",
|
|
33
|
+
null
|
|
34
|
+
];
|
|
35
|
+
const LEVELS = [
|
|
36
|
+
"native",
|
|
37
|
+
"partial",
|
|
38
|
+
"none"
|
|
39
|
+
];
|
|
40
|
+
var CheckFailed = class extends Error {};
|
|
41
|
+
var SkipCheck = class extends Error {};
|
|
42
|
+
const expect = (ok, message) => {
|
|
43
|
+
if (!ok) throw new CheckFailed(message);
|
|
44
|
+
};
|
|
45
|
+
const skip = (reason) => {
|
|
46
|
+
throw new SkipCheck(reason);
|
|
47
|
+
};
|
|
48
|
+
function capture(subscribe, timeoutMs = 500) {
|
|
49
|
+
const received = [];
|
|
50
|
+
const unsubscribe = subscribe((v) => received.push(v));
|
|
51
|
+
const next = (count = 1) => new Promise((resolve) => {
|
|
52
|
+
const started = Date.now();
|
|
53
|
+
const poll = () => received.length >= count || Date.now() - started > timeoutMs ? resolve(received) : setTimeout(poll, 5);
|
|
54
|
+
poll();
|
|
55
|
+
});
|
|
56
|
+
return {
|
|
57
|
+
received,
|
|
58
|
+
unsubscribe,
|
|
59
|
+
next
|
|
60
|
+
};
|
|
61
|
+
}
|
|
62
|
+
function validatePlatform(p) {
|
|
63
|
+
expect(OSES.includes(p.os), `platform().os is "${p.os}"; expected one of ${OSES.join(", ")}`);
|
|
64
|
+
expect(SKINS.includes(p.skin), `platform().skin is "${p.skin}"; expected one of ${SKINS.join(", ")}`);
|
|
65
|
+
expect([
|
|
66
|
+
"exact",
|
|
67
|
+
"hint",
|
|
68
|
+
"unknown"
|
|
69
|
+
].includes(p.confidence), `platform().confidence is "${p.confidence}"`);
|
|
70
|
+
expect(p.version === null || typeof p.version === "string", "platform().version must be a string or null");
|
|
71
|
+
expect(p.build === null || Number.isInteger(p.build), "platform().build must be an integer or null");
|
|
72
|
+
expect(DESKTOPS.includes(p.desktop), `platform().desktop is "${p.desktop}"`);
|
|
73
|
+
}
|
|
74
|
+
function validateAppearance(a) {
|
|
75
|
+
expect(SKINS.includes(a.skin), `appearance().skin is "${a.skin}"`);
|
|
76
|
+
expect(/^#[0-9a-f]{6}$/i.test(a.accent), `appearance().accent is "${a.accent}"; expected #rrggbb`);
|
|
77
|
+
expect(a.scheme === "light" || a.scheme === "dark", `appearance().scheme is "${a.scheme}"`);
|
|
78
|
+
expect([
|
|
79
|
+
"normal",
|
|
80
|
+
"more",
|
|
81
|
+
"forced"
|
|
82
|
+
].includes(a.contrast), `appearance().contrast is "${a.contrast}"`);
|
|
83
|
+
expect(typeof a.reduceTransparency === "boolean", "appearance().reduceTransparency must be a boolean");
|
|
84
|
+
expect(typeof a.reduceMotion === "boolean", "appearance().reduceMotion must be a boolean");
|
|
85
|
+
expect(typeof a.textScale === "number" && a.textScale >= .5 && a.textScale <= 4, `appearance().textScale is ${a.textScale}`);
|
|
86
|
+
}
|
|
87
|
+
const CHECKS = [
|
|
88
|
+
{
|
|
89
|
+
id: "runtime",
|
|
90
|
+
title: "declares a known runtime",
|
|
91
|
+
run: (h) => expect(RUNTIMES.includes(h.runtime), `runtime is "${h.runtime}"; expected one of ${RUNTIMES.join(", ")}`)
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
id: "capabilities",
|
|
95
|
+
title: "reports every capability as native, partial or none",
|
|
96
|
+
run: (h) => {
|
|
97
|
+
for (const c of CAPABILITIES) {
|
|
98
|
+
expect(c in h.capabilities, `capability "${c}" is missing`);
|
|
99
|
+
expect(LEVELS.includes(h.capabilities[c]), `capability "${c}" is "${h.capabilities[c]}"`);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
id: "platform",
|
|
105
|
+
title: "platform() resolves a valid PlatformInfo",
|
|
106
|
+
run: async (h) => validatePlatform(await h.platform())
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
id: "appearance",
|
|
110
|
+
title: "appearance() resolves a valid AppearanceState",
|
|
111
|
+
run: async (h) => validateAppearance(await h.appearance())
|
|
112
|
+
},
|
|
113
|
+
{
|
|
114
|
+
id: "skin-agrees",
|
|
115
|
+
title: "appearance().skin agrees with platform().skin",
|
|
116
|
+
run: async (h) => {
|
|
117
|
+
const [p, a] = await Promise.all([h.platform(), h.appearance()]);
|
|
118
|
+
expect(p.skin === a.skin, `platform().skin is "${p.skin}" but appearance().skin is "${a.skin}"`);
|
|
119
|
+
}
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
id: "focus",
|
|
123
|
+
title: "window.isFocused() resolves a boolean",
|
|
124
|
+
run: async (h) => expect(typeof await h.window.isFocused() === "boolean", "isFocused() must resolve a boolean")
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
id: "menus-match-capability",
|
|
128
|
+
title: "menus are present exactly when nativeMenus is not none",
|
|
129
|
+
run: (h) => {
|
|
130
|
+
const level = h.capabilities.nativeMenus;
|
|
131
|
+
const m = h.menus;
|
|
132
|
+
if (level === "none") {
|
|
133
|
+
expect(!m, "nativeMenus is \"none\" but the host has menus");
|
|
134
|
+
return;
|
|
135
|
+
}
|
|
136
|
+
expect(m, `nativeMenus is "${level}" but the host has no menus`);
|
|
137
|
+
expect(typeof m.onAction === "function", "menus.onAction must be a function");
|
|
138
|
+
expect(m.setApplicationMenu || m.showContextMenu, "menus must offer setApplicationMenu() or showContextMenu()");
|
|
139
|
+
const off = m.onAction(() => void 0);
|
|
140
|
+
expect(typeof off === "function", "menus.onAction must return an unsubscribe function");
|
|
141
|
+
off();
|
|
142
|
+
off();
|
|
143
|
+
}
|
|
144
|
+
},
|
|
145
|
+
{
|
|
146
|
+
id: "dialogs-match-capability",
|
|
147
|
+
title: "dialogs are present exactly when fileDialogs is not none",
|
|
148
|
+
run: (h) => {
|
|
149
|
+
const level = h.capabilities.fileDialogs;
|
|
150
|
+
const d = h.dialogs;
|
|
151
|
+
if (level === "none") {
|
|
152
|
+
expect(!d, "fileDialogs is \"none\" but the host has dialogs");
|
|
153
|
+
return;
|
|
154
|
+
}
|
|
155
|
+
expect(d, `fileDialogs is "${level}" but the host has no dialogs`);
|
|
156
|
+
for (const m of [
|
|
157
|
+
"openFile",
|
|
158
|
+
"saveFile",
|
|
159
|
+
"pickFolder"
|
|
160
|
+
]) expect(typeof d[m] === "function", `dialogs.${m} must be a function`);
|
|
161
|
+
expect(d.message === void 0 || typeof d.message === "function", "dialogs.message must be a function when present");
|
|
162
|
+
}
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
id: "unsubscribe",
|
|
166
|
+
title: "subscriptions return an unsubscribe function that can be called twice",
|
|
167
|
+
run: (h) => {
|
|
168
|
+
const offA = h.onAppearanceChange(() => void 0);
|
|
169
|
+
const offF = h.window.onFocusChange(() => void 0);
|
|
170
|
+
expect(typeof offA === "function" && typeof offF === "function", "subscribe must return a function");
|
|
171
|
+
offA();
|
|
172
|
+
offA();
|
|
173
|
+
offF();
|
|
174
|
+
offF();
|
|
175
|
+
}
|
|
176
|
+
},
|
|
177
|
+
{
|
|
178
|
+
id: "graceful",
|
|
179
|
+
title: "never throws for capabilities it reports as 'none'",
|
|
180
|
+
run: async (h) => {
|
|
181
|
+
if (h.capabilities.nativeMenus === "none") expect(h.menus === void 0 || typeof h.menus === "object", "menus must be undefined or an object");
|
|
182
|
+
if (h.capabilities.notifications === "none") expect(h.notifications === void 0 || typeof h.notifications === "object", "notifications must be undefined or an object");
|
|
183
|
+
await h.platform();
|
|
184
|
+
await h.appearance();
|
|
185
|
+
}
|
|
186
|
+
},
|
|
187
|
+
{
|
|
188
|
+
id: "live-appearance",
|
|
189
|
+
title: "notifies appearance changes, with the new values",
|
|
190
|
+
run: async (h, d) => {
|
|
191
|
+
if (!d.setAppearance) skip("no driver.setAppearance");
|
|
192
|
+
const before = await h.appearance();
|
|
193
|
+
const scheme = before.scheme === "dark" ? "light" : "dark";
|
|
194
|
+
const sub = capture((cb) => h.onAppearanceChange(cb));
|
|
195
|
+
await d.setAppearance({ scheme });
|
|
196
|
+
const got = await sub.next();
|
|
197
|
+
sub.unsubscribe();
|
|
198
|
+
expect(got.length > 0, "onAppearanceChange did not fire after the scheme changed");
|
|
199
|
+
validateAppearance(got[got.length - 1]);
|
|
200
|
+
expect(got[got.length - 1].scheme === scheme, `expected scheme "${scheme}", got "${got[got.length - 1].scheme}"`);
|
|
201
|
+
await d.setAppearance({ scheme: before.scheme });
|
|
202
|
+
}
|
|
203
|
+
},
|
|
204
|
+
{
|
|
205
|
+
id: "live-appearance-stops",
|
|
206
|
+
title: "stops notifying after unsubscribe",
|
|
207
|
+
run: async (h, d) => {
|
|
208
|
+
if (!d.setAppearance) skip("no driver.setAppearance");
|
|
209
|
+
const before = await h.appearance();
|
|
210
|
+
const sub = capture((cb) => h.onAppearanceChange(cb), 120);
|
|
211
|
+
sub.unsubscribe();
|
|
212
|
+
await d.setAppearance({ scheme: before.scheme === "dark" ? "light" : "dark" });
|
|
213
|
+
const got = await sub.next();
|
|
214
|
+
await d.setAppearance({ scheme: before.scheme });
|
|
215
|
+
expect(got.length === 0, "onAppearanceChange fired after unsubscribe");
|
|
216
|
+
}
|
|
217
|
+
},
|
|
218
|
+
{
|
|
219
|
+
id: "live-focus",
|
|
220
|
+
title: "notifies window focus changes",
|
|
221
|
+
run: async (h, d) => {
|
|
222
|
+
if (!d.setFocused) skip("no driver.setFocused");
|
|
223
|
+
const sub = capture((cb) => h.window.onFocusChange(cb));
|
|
224
|
+
await d.setFocused(false);
|
|
225
|
+
await d.setFocused(true);
|
|
226
|
+
const got = await sub.next(2);
|
|
227
|
+
sub.unsubscribe();
|
|
228
|
+
expect(got.includes(false) && got[got.length - 1] === true, `expected [false … true], got [${got.join(", ")}]`);
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
];
|
|
232
|
+
async function checkHostConformance(host, driver = {}) {
|
|
233
|
+
const results = [];
|
|
234
|
+
for (const check of CHECKS) try {
|
|
235
|
+
await check.run(host, driver);
|
|
236
|
+
results.push({
|
|
237
|
+
id: check.id,
|
|
238
|
+
title: check.title,
|
|
239
|
+
status: "pass"
|
|
240
|
+
});
|
|
241
|
+
} catch (e) {
|
|
242
|
+
const skipped = e instanceof SkipCheck;
|
|
243
|
+
results.push({
|
|
244
|
+
id: check.id,
|
|
245
|
+
title: check.title,
|
|
246
|
+
status: skipped ? "skip" : "fail",
|
|
247
|
+
detail: e instanceof Error ? e.message : String(e)
|
|
248
|
+
});
|
|
249
|
+
}
|
|
250
|
+
return {
|
|
251
|
+
runtime: host.runtime,
|
|
252
|
+
passed: results.every((r) => r.status !== "fail"),
|
|
253
|
+
results
|
|
254
|
+
};
|
|
255
|
+
}
|
|
256
|
+
function describeHostConformance(name, factory) {
|
|
257
|
+
const g = globalThis;
|
|
258
|
+
if (!g.describe || !g.it) throw new Error("describeHostConformance needs global describe/it (enable your runner's globals).");
|
|
259
|
+
const { describe, it } = g;
|
|
260
|
+
describe(`${name} · host conformance`, () => {
|
|
261
|
+
for (const check of CHECKS) it(check.title, async () => {
|
|
262
|
+
const { host, driver = {} } = await factory();
|
|
263
|
+
try {
|
|
264
|
+
await check.run(host, driver);
|
|
265
|
+
} catch (e) {
|
|
266
|
+
if (!(e instanceof SkipCheck)) throw e;
|
|
267
|
+
console.info(`[${name}] skipped "${check.title}": ${e.message}`);
|
|
268
|
+
}
|
|
269
|
+
});
|
|
270
|
+
});
|
|
271
|
+
}
|
|
272
|
+
export { CHECKS, SkipCheck, checkHostConformance, describeHostConformance, validateAppearance, validatePlatform };
|
|
273
|
+
|
|
274
|
+
//# sourceMappingURL=spartan-native-host-conformance.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"spartan-native-host-conformance.mjs","names":[],"sources":["../../../packages/hosts/host-conformance/src/lib/conformance.ts","../../../packages/hosts/host-conformance/src/lib/describe.ts"],"sourcesContent":["import {\n type AppearanceState,\n CAPABILITIES,\n type NativeHost,\n type PlatformInfo,\n type Skin,\n} from '@spartan-native/theme';\n\n/**\n * Lets the suite simulate the OS, so the live-event checks can run.\n * Adapters that can't be driven in a test omit it; those checks are then skipped.\n */\nexport interface HostDriver {\n /** Change what the OS reports (e.g. flip dark mode, change the accent). */\n setAppearance?(patch: Partial<AppearanceState>): void | Promise<void>;\n /** Focus or blur the window. */\n setFocused?(focused: boolean): void | Promise<void>;\n}\n\nexport type CheckStatus = 'pass' | 'fail' | 'skip';\n\nexport interface CheckResult {\n readonly id: string;\n readonly title: string;\n readonly status: CheckStatus;\n readonly detail?: string;\n}\n\nexport interface ConformanceReport {\n readonly runtime: string;\n readonly passed: boolean;\n readonly results: readonly CheckResult[];\n}\n\nconst RUNTIMES = ['web', 'wails', 'tauri', 'electron', 'dotnet', 'static'];\nconst SKINS: Skin[] = ['win', 'w10', 'mac', 'macc', 'gtk', 'qt', 'cros', 'web'];\nconst OSES = ['windows', 'macos', 'linux', 'chromeos', 'unknown'];\nconst DESKTOPS = ['gnome', 'kde', 'cinnamon', 'xfce', 'other', null];\nconst LEVELS = ['native', 'partial', 'none'];\n\n/** One check: throws to fail, throws SkipCheck to skip. */\nexport interface Check {\n readonly id: string;\n readonly title: string;\n run(host: NativeHost, driver: HostDriver): Promise<void> | void;\n}\n\nclass CheckFailed extends Error {}\n\n/** Thrown when a check can't run for this host (e.g. no driver to simulate the OS). */\nexport class SkipCheck extends Error {}\n\nconst expect = (ok: unknown, message: string) => {\n if (!ok) throw new CheckFailed(message);\n};\nconst skip = (reason: string): never => {\n throw new SkipCheck(reason);\n};\n\n/** Waits until `cb` has been called (or the timeout passes) and returns what it received. */\nfunction capture<T>(subscribe: (cb: (v: T) => void) => () => void, timeoutMs = 500) {\n const received: T[] = [];\n const unsubscribe = subscribe((v) => received.push(v));\n const next = (count = 1) =>\n new Promise<T[]>((resolve) => {\n const started = Date.now();\n const poll = () =>\n received.length >= count || Date.now() - started > timeoutMs ? resolve(received) : setTimeout(poll, 5);\n poll();\n });\n return { received, unsubscribe, next };\n}\n\nexport function validatePlatform(p: PlatformInfo): void {\n expect(OSES.includes(p.os), `platform().os is \"${p.os}\"; expected one of ${OSES.join(', ')}`);\n expect(SKINS.includes(p.skin), `platform().skin is \"${p.skin}\"; expected one of ${SKINS.join(', ')}`);\n expect(['exact', 'hint', 'unknown'].includes(p.confidence), `platform().confidence is \"${p.confidence}\"`);\n expect(p.version === null || typeof p.version === 'string', 'platform().version must be a string or null');\n expect(p.build === null || Number.isInteger(p.build), 'platform().build must be an integer or null');\n expect(DESKTOPS.includes(p.desktop), `platform().desktop is \"${p.desktop}\"`);\n}\n\nexport function validateAppearance(a: AppearanceState): void {\n expect(SKINS.includes(a.skin), `appearance().skin is \"${a.skin}\"`);\n expect(/^#[0-9a-f]{6}$/i.test(a.accent), `appearance().accent is \"${a.accent}\"; expected #rrggbb`);\n expect(a.scheme === 'light' || a.scheme === 'dark', `appearance().scheme is \"${a.scheme}\"`);\n expect(['normal', 'more', 'forced'].includes(a.contrast), `appearance().contrast is \"${a.contrast}\"`);\n expect(typeof a.reduceTransparency === 'boolean', 'appearance().reduceTransparency must be a boolean');\n expect(typeof a.reduceMotion === 'boolean', 'appearance().reduceMotion must be a boolean');\n expect(\n typeof a.textScale === 'number' && a.textScale >= 0.5 && a.textScale <= 4,\n `appearance().textScale is ${a.textScale}`,\n );\n}\n\n/** The checks, in order. Exported so runners can show them as separate tests. */\nexport const CHECKS: readonly Check[] = [\n {\n id: 'runtime',\n title: 'declares a known runtime',\n run: (h) =>\n expect(RUNTIMES.includes(h.runtime), `runtime is \"${h.runtime}\"; expected one of ${RUNTIMES.join(', ')}`),\n },\n {\n id: 'capabilities',\n title: 'reports every capability as native, partial or none',\n run: (h) => {\n for (const c of CAPABILITIES) {\n expect(c in h.capabilities, `capability \"${c}\" is missing`);\n expect(LEVELS.includes(h.capabilities[c]), `capability \"${c}\" is \"${h.capabilities[c]}\"`);\n }\n },\n },\n {\n id: 'platform',\n title: 'platform() resolves a valid PlatformInfo',\n run: async (h) => validatePlatform(await h.platform()),\n },\n {\n id: 'appearance',\n title: 'appearance() resolves a valid AppearanceState',\n run: async (h) => validateAppearance(await h.appearance()),\n },\n {\n id: 'skin-agrees',\n title: 'appearance().skin agrees with platform().skin',\n run: async (h) => {\n const [p, a] = await Promise.all([h.platform(), h.appearance()]);\n expect(p.skin === a.skin, `platform().skin is \"${p.skin}\" but appearance().skin is \"${a.skin}\"`);\n },\n },\n {\n id: 'focus',\n title: 'window.isFocused() resolves a boolean',\n run: async (h) => expect(typeof (await h.window.isFocused()) === 'boolean', 'isFocused() must resolve a boolean'),\n },\n {\n id: 'menus-match-capability',\n title: 'menus are present exactly when nativeMenus is not none',\n run: (h) => {\n const level = h.capabilities.nativeMenus;\n const m = h.menus;\n if (level === 'none') {\n expect(!m, 'nativeMenus is \"none\" but the host has menus');\n return;\n }\n expect(m, `nativeMenus is \"${level}\" but the host has no menus`);\n expect(typeof m!.onAction === 'function', 'menus.onAction must be a function');\n expect(m!.setApplicationMenu || m!.showContextMenu, 'menus must offer setApplicationMenu() or showContextMenu()');\n const off = m!.onAction(() => undefined);\n expect(typeof off === 'function', 'menus.onAction must return an unsubscribe function');\n off();\n off();\n },\n },\n {\n id: 'dialogs-match-capability',\n title: 'dialogs are present exactly when fileDialogs is not none',\n run: (h) => {\n const level = h.capabilities.fileDialogs;\n const d = h.dialogs;\n if (level === 'none') {\n expect(!d, 'fileDialogs is \"none\" but the host has dialogs');\n return;\n }\n expect(d, `fileDialogs is \"${level}\" but the host has no dialogs`);\n for (const m of ['openFile', 'saveFile', 'pickFolder'] as const)\n expect(typeof d![m] === 'function', `dialogs.${m} must be a function`);\n expect(\n d!.message === undefined || typeof d!.message === 'function',\n 'dialogs.message must be a function when present',\n );\n },\n },\n {\n id: 'unsubscribe',\n title: 'subscriptions return an unsubscribe function that can be called twice',\n run: (h) => {\n const offA = h.onAppearanceChange(() => undefined);\n const offF = h.window.onFocusChange(() => undefined);\n expect(typeof offA === 'function' && typeof offF === 'function', 'subscribe must return a function');\n offA();\n offA();\n offF();\n offF();\n },\n },\n {\n id: 'graceful',\n title: \"never throws for capabilities it reports as 'none'\",\n run: async (h) => {\n // Optional services must be absent rather than throwing when unsupported.\n if (h.capabilities.nativeMenus === 'none')\n expect(h.menus === undefined || typeof h.menus === 'object', 'menus must be undefined or an object');\n if (h.capabilities.notifications === 'none')\n expect(\n h.notifications === undefined || typeof h.notifications === 'object',\n 'notifications must be undefined or an object',\n );\n await h.platform();\n await h.appearance();\n },\n },\n {\n id: 'live-appearance',\n title: 'notifies appearance changes, with the new values',\n run: async (h, d) => {\n if (!d.setAppearance) skip('no driver.setAppearance');\n const before = await h.appearance();\n const scheme = before.scheme === 'dark' ? 'light' : 'dark';\n const sub = capture<AppearanceState>((cb) => h.onAppearanceChange(cb));\n await d.setAppearance!({ scheme });\n const got = await sub.next();\n sub.unsubscribe();\n expect(got.length > 0, 'onAppearanceChange did not fire after the scheme changed');\n validateAppearance(got[got.length - 1]);\n expect(got[got.length - 1].scheme === scheme, `expected scheme \"${scheme}\", got \"${got[got.length - 1].scheme}\"`);\n await d.setAppearance!({ scheme: before.scheme });\n },\n },\n {\n id: 'live-appearance-stops',\n title: 'stops notifying after unsubscribe',\n run: async (h, d) => {\n if (!d.setAppearance) skip('no driver.setAppearance');\n const before = await h.appearance();\n const sub = capture<AppearanceState>((cb) => h.onAppearanceChange(cb), 120);\n sub.unsubscribe();\n await d.setAppearance!({ scheme: before.scheme === 'dark' ? 'light' : 'dark' });\n const got = await sub.next();\n await d.setAppearance!({ scheme: before.scheme });\n expect(got.length === 0, 'onAppearanceChange fired after unsubscribe');\n },\n },\n {\n id: 'live-focus',\n title: 'notifies window focus changes',\n run: async (h, d) => {\n if (!d.setFocused) skip('no driver.setFocused');\n const sub = capture<boolean>((cb) => h.window.onFocusChange(cb));\n await d.setFocused!(false);\n await d.setFocused!(true);\n const got = await sub.next(2);\n sub.unsubscribe();\n expect(got.includes(false) && got[got.length - 1] === true, `expected [false … true], got [${got.join(', ')}]`);\n },\n },\n];\n\n/**\n * Runs every check against a host and returns a report. Never throws.\n *\n * ```ts\n * const report = await checkHostConformance(wailsHost(), driver);\n * if (!report.passed) console.table(report.results);\n * ```\n */\nexport async function checkHostConformance(host: NativeHost, driver: HostDriver = {}): Promise<ConformanceReport> {\n const results: CheckResult[] = [];\n for (const check of CHECKS) {\n try {\n await check.run(host, driver);\n results.push({ id: check.id, title: check.title, status: 'pass' });\n } catch (e) {\n const skipped = e instanceof SkipCheck;\n results.push({\n id: check.id,\n title: check.title,\n status: skipped ? 'skip' : 'fail',\n detail: e instanceof Error ? e.message : String(e),\n });\n }\n }\n return { runtime: host.runtime, passed: results.every((r) => r.status !== 'fail'), results };\n}\n","import type { NativeHost } from '@spartan-native/theme';\nimport { CHECKS, type HostDriver, SkipCheck } from './conformance';\n\ntype Describe = (name: string, body: () => void) => void;\ntype It = (name: string, body: () => Promise<void> | void) => void;\n\ninterface TestGlobals {\n describe?: Describe;\n it?: It;\n}\n\n/** What a factory returns: a fresh host, and optionally a driver that simulates the OS. */\nexport interface HostUnderTest {\n host: NativeHost;\n driver?: HostDriver;\n}\n\n/**\n * Registers the conformance suite with the test runner in use (Vitest, Jest, Jasmine:\n * anything with global `describe` / `it`). Each check becomes one test, so a\n * failure names exactly what is wrong. Skipped checks pass and say why.\n *\n * ```ts\n * // wails-host.spec.ts in the host-wails repository (npm/projects/host-wails/src/lib/)\n * describeHostConformance('wailsHost', () => ({ host: wailsHost({ runtime: fakeWailsRuntime() }), driver }));\n * ```\n */\nexport function describeHostConformance(name: string, factory: () => HostUnderTest | Promise<HostUnderTest>): void {\n const g = globalThis as TestGlobals;\n if (!g.describe || !g.it)\n throw new Error(\"describeHostConformance needs global describe/it (enable your runner's globals).\");\n const { describe, it } = g as Required<TestGlobals>;\n\n describe(`${name} · host conformance`, () => {\n for (const check of CHECKS) {\n it(check.title, async () => {\n const { host, driver = {} } = await factory();\n try {\n await check.run(host, driver);\n } catch (e) {\n if (!(e instanceof SkipCheck)) throw e;\n // Runners differ in how they skip at runtime; log it and pass.\n console.info(`[${name}] skipped \"${check.title}\": ${e.message}`);\n }\n });\n }\n });\n}\n"],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,44 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@spartan-native/host-conformance",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "The conformance suite every @spartan-native/host-* adapter must pass: contract shape, capability flags, live appearance and focus events, graceful fallbacks.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Roland Molnár",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/Spartan-Native/spartan-native.git",
|
|
10
|
+
"directory": "packages/hosts/host-conformance"
|
|
11
|
+
},
|
|
12
|
+
"homepage": "https://github.com/Spartan-Native/spartan-native/tree/main/packages/hosts/host-conformance#readme",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/Spartan-Native/spartan-native/issues"
|
|
15
|
+
},
|
|
16
|
+
"keywords": [
|
|
17
|
+
"spartan-native",
|
|
18
|
+
"native-host",
|
|
19
|
+
"conformance",
|
|
20
|
+
"testing"
|
|
21
|
+
],
|
|
22
|
+
"peerDependencies": {
|
|
23
|
+
"@spartan-native/theme": "0.2.1"
|
|
24
|
+
},
|
|
25
|
+
"dependencies": {
|
|
26
|
+
"tslib": "^2.3.0"
|
|
27
|
+
},
|
|
28
|
+
"sideEffects": false,
|
|
29
|
+
"publishConfig": {
|
|
30
|
+
"access": "public"
|
|
31
|
+
},
|
|
32
|
+
"module": "fesm2022/spartan-native-host-conformance.mjs",
|
|
33
|
+
"typings": "types/spartan-native-host-conformance.d.ts",
|
|
34
|
+
"exports": {
|
|
35
|
+
"./package.json": {
|
|
36
|
+
"default": "./package.json"
|
|
37
|
+
},
|
|
38
|
+
".": {
|
|
39
|
+
"types": "./types/spartan-native-host-conformance.d.ts",
|
|
40
|
+
"default": "./fesm2022/spartan-native-host-conformance.mjs"
|
|
41
|
+
}
|
|
42
|
+
},
|
|
43
|
+
"type": "module"
|
|
6
44
|
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import { AppearanceState, NativeHost, PlatformInfo } from "@spartan-native/theme";
|
|
2
|
+
/**
|
|
3
|
+
* Lets the suite simulate the OS, so the live-event checks can run.
|
|
4
|
+
* Adapters that can't be driven in a test omit it; those checks are then skipped.
|
|
5
|
+
*/
|
|
6
|
+
interface HostDriver {
|
|
7
|
+
/** Change what the OS reports (e.g. flip dark mode, change the accent). */
|
|
8
|
+
setAppearance?(patch: Partial<AppearanceState>): void | Promise<void>;
|
|
9
|
+
/** Focus or blur the window. */
|
|
10
|
+
setFocused?(focused: boolean): void | Promise<void>;
|
|
11
|
+
}
|
|
12
|
+
type CheckStatus = 'pass' | 'fail' | 'skip';
|
|
13
|
+
interface CheckResult {
|
|
14
|
+
readonly id: string;
|
|
15
|
+
readonly title: string;
|
|
16
|
+
readonly status: CheckStatus;
|
|
17
|
+
readonly detail?: string;
|
|
18
|
+
}
|
|
19
|
+
interface ConformanceReport {
|
|
20
|
+
readonly runtime: string;
|
|
21
|
+
readonly passed: boolean;
|
|
22
|
+
readonly results: readonly CheckResult[];
|
|
23
|
+
}
|
|
24
|
+
/** One check: throws to fail, throws SkipCheck to skip. */
|
|
25
|
+
interface Check {
|
|
26
|
+
readonly id: string;
|
|
27
|
+
readonly title: string;
|
|
28
|
+
run(host: NativeHost, driver: HostDriver): Promise<void> | void;
|
|
29
|
+
}
|
|
30
|
+
/** Thrown when a check can't run for this host (e.g. no driver to simulate the OS). */
|
|
31
|
+
export declare class SkipCheck extends Error {}
|
|
32
|
+
export declare function validatePlatform(p: PlatformInfo): void;
|
|
33
|
+
export declare function validateAppearance(a: AppearanceState): void;
|
|
34
|
+
/** The checks, in order. Exported so runners can show them as separate tests. */
|
|
35
|
+
export declare const CHECKS: readonly Check[];
|
|
36
|
+
/**
|
|
37
|
+
* Runs every check against a host and returns a report. Never throws.
|
|
38
|
+
*
|
|
39
|
+
* ```ts
|
|
40
|
+
* const report = await checkHostConformance(wailsHost(), driver);
|
|
41
|
+
* if (!report.passed) console.table(report.results);
|
|
42
|
+
* ```
|
|
43
|
+
*/
|
|
44
|
+
export declare function checkHostConformance(host: NativeHost, driver?: HostDriver): Promise<ConformanceReport>;
|
|
45
|
+
/** What a factory returns: a fresh host, and optionally a driver that simulates the OS. */
|
|
46
|
+
interface HostUnderTest {
|
|
47
|
+
host: NativeHost;
|
|
48
|
+
driver?: HostDriver;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Registers the conformance suite with the test runner in use (Vitest, Jest, Jasmine:
|
|
52
|
+
* anything with global `describe` / `it`). Each check becomes one test, so a
|
|
53
|
+
* failure names exactly what is wrong. Skipped checks pass and say why.
|
|
54
|
+
*
|
|
55
|
+
* ```ts
|
|
56
|
+
* // wails-host.spec.ts in the host-wails repository (npm/projects/host-wails/src/lib/)
|
|
57
|
+
* describeHostConformance('wailsHost', () => ({ host: wailsHost({ runtime: fakeWailsRuntime() }), driver }));
|
|
58
|
+
* ```
|
|
59
|
+
*/
|
|
60
|
+
export declare function describeHostConformance(name: string, factory: () => HostUnderTest | Promise<HostUnderTest>): void;
|
|
61
|
+
export type { Check, CheckResult, CheckStatus, ConformanceReport, HostDriver, HostUnderTest };
|