trykeyline-browser 0.0.0-stage → 0.3.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/LICENSE +21 -0
- package/README.md +14 -2
- package/audit/probe.mjs +390 -0
- package/audit.mjs +231 -0
- package/bin/trykeyline-browser.mjs +79 -0
- package/browse/args.mjs +44 -0
- package/browse/capture.mjs +181 -0
- package/browse/compare.mjs +263 -0
- package/browse/findings.mjs +129 -0
- package/browse/playwright.mjs +78 -0
- package/browse/report.mjs +301 -0
- package/browse/routes.mjs +252 -0
- package/browse/score.mjs +46 -0
- package/browse/serve.mjs +61 -0
- package/browse/walk.mjs +117 -0
- package/browse.mjs +175 -0
- package/package.json +53 -4
- package/probe.mjs +26 -0
- package/smoke/clicks.mjs +320 -0
- package/smoke/config.mjs +184 -0
- package/smoke/forms.mjs +329 -0
- package/smoke/keyboard.mjs +100 -0
- package/smoke/links.mjs +120 -0
- package/smoke/page.mjs +575 -0
- package/smoke/phone.mjs +126 -0
- package/smoke/shift.mjs +103 -0
- package/smoke/util.mjs +113 -0
- package/smoke.mjs +412 -0
package/smoke/clicks.mjs
ADDED
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Click everything a person could click, one at a time, from a freshly loaded
|
|
3
|
+
* page, and watch what changes: the URL, the DOM, the network, dialogs, new
|
|
4
|
+
* tabs, downloads, scroll and focus. A click that changes none of them within
|
|
5
|
+
* the quiet window (1.5 s) is a dead click.
|
|
6
|
+
*
|
|
7
|
+
* Every click starts from a fresh load of the route. A click that changed
|
|
8
|
+
* nothing leaves the page as it found it, so the next click reuses that page
|
|
9
|
+
* rather than loading it again; anything that changed the page gets a reload.
|
|
10
|
+
*
|
|
11
|
+
* Clicks that do something get follow-ups on the spot:
|
|
12
|
+
* - opened a menu or dialog → press Escape: it should close, and focus should come back
|
|
13
|
+
* - moved to another URL → press Back: the previous URL and content should return
|
|
14
|
+
* - moved without a reload → open that URL fresh: the same content should be there
|
|
15
|
+
*/
|
|
16
|
+
import { add } from "../browse/findings.mjs";
|
|
17
|
+
import { shotKey } from "../browse/capture.mjs";
|
|
18
|
+
import { isDestructive } from "./config.mjs";
|
|
19
|
+
import { PAGE, similarity } from "./page.mjs";
|
|
20
|
+
import { describe, normalUrl, open, openStep, pathOf, sleep } from "./util.mjs";
|
|
21
|
+
|
|
22
|
+
const IGNORED_TYPES = new Set(["image", "font", "media", "texttrack", "manifest", "other"]);
|
|
23
|
+
const stripQuery = (u) => u.replace(/[?#].*$/, "");
|
|
24
|
+
|
|
25
|
+
/** Which of a page's clickables to try, most likely to be broken first. */
|
|
26
|
+
export function plan(inventory, { base, settings, policy, skipped, route }) {
|
|
27
|
+
const out = [];
|
|
28
|
+
const hrefs = new Set();
|
|
29
|
+
const seen = new Set();
|
|
30
|
+
const rank = (c) => (c.kind === "link" ? (c.placeholder ? 1 : c.hashOnly ? 2 : 3) : 0);
|
|
31
|
+
const sorted = [...(inventory?.clickables ?? [])].sort((a, b) => rank(a) - rank(b) || a.i - b.i);
|
|
32
|
+
for (const c of sorted) {
|
|
33
|
+
if (c.isSubmit) continue; // the forms pass submits forms, under its own rules
|
|
34
|
+
if (c.current) continue; // the selected tab, the current page: doing nothing is right
|
|
35
|
+
const key = `${c.sel}|${c.text}`;
|
|
36
|
+
if (seen.has(key)) continue;
|
|
37
|
+
seen.add(key);
|
|
38
|
+
if (c.kind === "link" && !c.placeholder) {
|
|
39
|
+
if (!c.sameOrigin) continue; // never leave the product
|
|
40
|
+
if (c.download) continue;
|
|
41
|
+
if (settings.forbidUrl(c.href)) {
|
|
42
|
+
skipped.push({ what: `${describe(c)} on ${route}`, why: "the config forbids its URL" });
|
|
43
|
+
continue;
|
|
44
|
+
}
|
|
45
|
+
const target = normalUrl(c.href);
|
|
46
|
+
if (!c.hashOnly && hrefs.has(target)) continue; // one click per destination is enough
|
|
47
|
+
hrefs.add(target);
|
|
48
|
+
}
|
|
49
|
+
const destructive = isDestructive(c.text, c.context) || (c.href && isDestructive(pathOf(c.href, base).replace(/[/_-]/g, " ")));
|
|
50
|
+
const why = destructive ? policy.blocks({ write: true, destructive: true }) : null;
|
|
51
|
+
if (why) {
|
|
52
|
+
skipped.push({ what: `${describe(c)} on ${route}`, why });
|
|
53
|
+
continue;
|
|
54
|
+
}
|
|
55
|
+
out.push(c);
|
|
56
|
+
}
|
|
57
|
+
if (out.length > settings.maxClicks) {
|
|
58
|
+
skipped.push({ what: `${out.length - settings.maxClicks} more controls on ${route}`, why: `past --max-clicks ${settings.maxClicks}` });
|
|
59
|
+
}
|
|
60
|
+
return out.slice(0, settings.maxClicks);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
export async function checkClicks({ run, context, base, route, inventory, settings, policy, skipped, log, find }) {
|
|
64
|
+
const controls = plan(inventory, { base, settings, policy, skipped, route });
|
|
65
|
+
if (!controls.length) return;
|
|
66
|
+
log(` clicks ${route} ${controls.length} controls`);
|
|
67
|
+
const origin = new URL(base).origin;
|
|
68
|
+
const at = (c) => ({ page: route, viewport: "desktop", theme: "light", shot: shotKey("desktop", "light"), box: c.box, selector: c.sel, ...(find?.(c) ?? {}) });
|
|
69
|
+
const quiet = settings.quietMs;
|
|
70
|
+
const deadPlaceholders = [];
|
|
71
|
+
let backChecks = { soft: 0, hard: 0 };
|
|
72
|
+
let current = null;
|
|
73
|
+
let dirty = true;
|
|
74
|
+
|
|
75
|
+
const fresh = async () => {
|
|
76
|
+
await current?.page.close().catch(() => {});
|
|
77
|
+
const opened = await open(context, { base, route });
|
|
78
|
+
const flags = { armed: false, requests: [], baseline: new Set(), popup: false, download: false, dialog: null, errors: [], failed: [] };
|
|
79
|
+
const page = opened.page;
|
|
80
|
+
page.on("request", (req) => {
|
|
81
|
+
const url = req.url();
|
|
82
|
+
if (!flags.armed) {
|
|
83
|
+
flags.baseline.add(stripQuery(url));
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
if (IGNORED_TYPES.has(req.resourceType()) || flags.baseline.has(stripQuery(url))) return;
|
|
87
|
+
flags.requests.push(`${req.method()} ${pathOf(url, base)}`);
|
|
88
|
+
});
|
|
89
|
+
page.on("popup", (p) => {
|
|
90
|
+
if (flags.armed) flags.popup = true;
|
|
91
|
+
p.close().catch(() => {});
|
|
92
|
+
});
|
|
93
|
+
page.on("download", (d) => {
|
|
94
|
+
if (flags.armed) flags.download = true;
|
|
95
|
+
d.cancel().catch(() => {});
|
|
96
|
+
});
|
|
97
|
+
page.on("dialog", (d) => {
|
|
98
|
+
if (flags.armed) flags.dialog = `${d.type()}: ${d.message().slice(0, 120)}`;
|
|
99
|
+
});
|
|
100
|
+
page.on("pageerror", (err) => flags.armed && flags.errors.push(String(err?.message ?? err).slice(0, 300)));
|
|
101
|
+
page.on("response", (res) => {
|
|
102
|
+
if (flags.armed && res.status() >= 500 && res.url().startsWith(origin)) flags.failed.push(`${res.request().method()} ${pathOf(res.url(), base)} → ${res.status()}`);
|
|
103
|
+
});
|
|
104
|
+
page.on("requestfailed", (req) => {
|
|
105
|
+
const e = req.failure()?.errorText ?? "";
|
|
106
|
+
if (flags.armed && req.url().startsWith(origin) && !/ERR_ABORTED/.test(e)) flags.failed.push(`${req.method()} ${pathOf(req.url(), base)} → ${e}`);
|
|
107
|
+
});
|
|
108
|
+
current = { page, flags };
|
|
109
|
+
dirty = false;
|
|
110
|
+
return current;
|
|
111
|
+
};
|
|
112
|
+
|
|
113
|
+
for (const c of controls) {
|
|
114
|
+
if (dirty || !current) await fresh();
|
|
115
|
+
const { page, flags } = current;
|
|
116
|
+
const steps = [openStep(route), `Click ${describe(c)}`];
|
|
117
|
+
|
|
118
|
+
const marked = await page.evaluate(PAGE.mark, { match: { sel: c.sel, text: c.text, tag: c.tag } }).catch(() => null);
|
|
119
|
+
if (!marked) {
|
|
120
|
+
dirty = true;
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
if (settings.forbidSelectors.length) {
|
|
124
|
+
const forbidden = await page.$eval("[data-keyline-target]", (el, sels) => sels.some((s) => { try { return Boolean(el.closest(s)); } catch { return false; } }), settings.forbidSelectors).catch(() => false);
|
|
125
|
+
if (forbidden) {
|
|
126
|
+
skipped.push({ what: `${describe(c)} on ${route}`, why: "the config forbids its selector" });
|
|
127
|
+
continue;
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
const target = page.locator("[data-keyline-target]").first();
|
|
131
|
+
await target.scrollIntoViewIfNeeded({ timeout: 2000 }).catch(() => {});
|
|
132
|
+
await page.evaluate(PAGE.watch).catch(() => {});
|
|
133
|
+
await sleep(350); // baseline: whatever moves on its own now is noise later
|
|
134
|
+
const urlBefore = page.url();
|
|
135
|
+
const armed = await page.evaluate(PAGE.arm).catch(() => null);
|
|
136
|
+
Object.assign(flags, { armed: true, requests: [], popup: false, download: false, dialog: null, errors: [], failed: [] });
|
|
137
|
+
|
|
138
|
+
try {
|
|
139
|
+
await target.click({ timeout: 2500 });
|
|
140
|
+
} catch (err) {
|
|
141
|
+
flags.armed = false;
|
|
142
|
+
const msg = String(err?.message ?? err);
|
|
143
|
+
if (/intercepts pointer events/.test(msg)) {
|
|
144
|
+
const by = msg.match(/<[^>]+>/)?.[0]?.slice(0, 120) ?? "another element";
|
|
145
|
+
add(run, {
|
|
146
|
+
...at(c),
|
|
147
|
+
rule: "flow/click-blocked",
|
|
148
|
+
severity: "error",
|
|
149
|
+
title: `Something covers ${describe(c)}`,
|
|
150
|
+
evidence: `the click lands on ${by}`,
|
|
151
|
+
detail: "A pointer can't reach this control: another element sits on top of it. Usually an overlay, a sticky bar or a transparent box that should have `pointer-events: none`.",
|
|
152
|
+
steps: [...steps, `The click lands on ${by} instead`],
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
dirty = true;
|
|
156
|
+
continue;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
const t0 = Date.now();
|
|
160
|
+
let read = null;
|
|
161
|
+
let effect = null;
|
|
162
|
+
for (;;) {
|
|
163
|
+
await sleep(150);
|
|
164
|
+
effect = null;
|
|
165
|
+
if (flags.popup) effect = "opened a new tab";
|
|
166
|
+
else if (flags.download) effect = "started a download";
|
|
167
|
+
else if (flags.dialog) effect = `opened a browser ${flags.dialog}`;
|
|
168
|
+
else if (normalUrl(page.url()) !== normalUrl(urlBefore)) effect = `moved to ${pathOf(page.url(), base)}`;
|
|
169
|
+
if (!effect) {
|
|
170
|
+
read = await page.evaluate(PAGE.read).catch(() => ({ gone: true }));
|
|
171
|
+
if (read.gone) effect = "loaded a new document";
|
|
172
|
+
else if (read.opened) effect = "opened something";
|
|
173
|
+
else if (read.mutations > 0) effect = `changed the page (${read.samples[0] ?? "DOM"})`;
|
|
174
|
+
else if (read.focusMoved) effect = `moved focus to ${read.focusTo}`;
|
|
175
|
+
else if (read.scrolled) effect = "scrolled the page";
|
|
176
|
+
else if (flags.requests.length) effect = `sent ${flags.requests[0]}`;
|
|
177
|
+
}
|
|
178
|
+
if (effect || Date.now() - t0 >= quiet) break;
|
|
179
|
+
}
|
|
180
|
+
if (!effect) {
|
|
181
|
+
flags.armed = false;
|
|
182
|
+
if (c.placeholder) deadPlaceholders.push(c);
|
|
183
|
+
else {
|
|
184
|
+
add(run, {
|
|
185
|
+
...at(c),
|
|
186
|
+
rule: "flow/dead-click",
|
|
187
|
+
severity: "error",
|
|
188
|
+
title: `Clicking ${describe(c)} does nothing`,
|
|
189
|
+
evidence: `no URL change, DOM change, request, dialog or focus move within ${quiet / 1000} s`,
|
|
190
|
+
detail: "It looks clickable and isn't. Wire it to what it promises, or stop it looking like a control.",
|
|
191
|
+
steps: [...steps, `Wait ${quiet / 1000} s: nothing on the page, the URL or the network changes`],
|
|
192
|
+
});
|
|
193
|
+
}
|
|
194
|
+
continue;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// Something happened. Let it finish, then look closer.
|
|
198
|
+
await sleep(350);
|
|
199
|
+
flags.armed = false;
|
|
200
|
+
const urlAfter = page.url();
|
|
201
|
+
const moved = normalUrl(urlAfter) !== normalUrl(urlBefore);
|
|
202
|
+
const sameOrigin = urlAfter.startsWith(origin);
|
|
203
|
+
const final = moved ? null : await page.evaluate(PAGE.read).catch(() => ({ gone: true }));
|
|
204
|
+
const did = `${effect[0].toUpperCase()}${effect.slice(1)}`;
|
|
205
|
+
|
|
206
|
+
for (const e of flags.errors) {
|
|
207
|
+
add(run, { ...at(c), rule: "runtime/click-exception", severity: "error", title: `Clicking ${describe(c)} throws an error`, evidence: e, detail: "Script fails when this control is used; whatever it was meant to do may be half done.", steps: [...steps, `An uncaught exception: ${e.slice(0, 120)}`] });
|
|
208
|
+
}
|
|
209
|
+
for (const f of flags.failed.slice(0, 2)) {
|
|
210
|
+
add(run, { ...at(c), rule: "runtime/click-request-failed", severity: "error", title: `Clicking ${describe(c)} sends a request that fails`, evidence: f, steps: [...steps, `The request fails: ${f}`] });
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
// Escape should close what the click opened, and hand focus back.
|
|
214
|
+
if (final && !final.gone && final.opened) {
|
|
215
|
+
await page.keyboard.press("Escape");
|
|
216
|
+
await sleep(400);
|
|
217
|
+
const after = await page.evaluate(PAGE.afterEscape).catch(() => null);
|
|
218
|
+
if (after) {
|
|
219
|
+
const stillOpen = after.overlays.length > final.overlaysBefore || (final.expandedBefore === "false" && after.expanded === "true");
|
|
220
|
+
if (stillOpen) {
|
|
221
|
+
add(run, {
|
|
222
|
+
...at(c),
|
|
223
|
+
rule: "flow/escape-ignored",
|
|
224
|
+
severity: "warning",
|
|
225
|
+
title: `Escape doesn't close what ${describe(c)} opens`,
|
|
226
|
+
evidence: final.overlays.length ? `still open: ${after.overlays.slice(-1)[0] ?? final.overlays.slice(-1)[0]}` : 'aria-expanded stays "true"',
|
|
227
|
+
detail: "Keyboard and screen-reader users close menus and dialogs with Escape; without it they're stuck inside or must hunt for a close button.",
|
|
228
|
+
fix: "/keyline patterns",
|
|
229
|
+
steps: [...steps, did, "Press Escape", "It stays open"],
|
|
230
|
+
});
|
|
231
|
+
} else if (!after.focusOnTarget && final.targetConnected) {
|
|
232
|
+
add(run, {
|
|
233
|
+
...at(c),
|
|
234
|
+
rule: "flow/focus-not-returned",
|
|
235
|
+
severity: "warning",
|
|
236
|
+
title: `Closing what ${describe(c)} opens loses focus`,
|
|
237
|
+
evidence: `focus is on ${after.focus ?? "nothing"} after Escape`,
|
|
238
|
+
detail: "When a menu or dialog closes, focus should return to the control that opened it, so a keyboard user carries on from where they were.",
|
|
239
|
+
fix: "/keyline patterns",
|
|
240
|
+
steps: [...steps, did, "Press Escape", `Focus lands on ${after.focus ?? "the page"}, not the control`],
|
|
241
|
+
});
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
if (moved && sameOrigin) {
|
|
247
|
+
// The watcher survives only when the click moved without loading a new document.
|
|
248
|
+
const soft = await page.evaluate(() => Boolean(window.__klWatch)).catch(() => false);
|
|
249
|
+
// Moved without a new document: the URL must be enough to get this view back.
|
|
250
|
+
if (soft && settings.checks.has("stuck")) {
|
|
251
|
+
const wordsAfter = await page.evaluate(PAGE.words).catch(() => []);
|
|
252
|
+
const deep = await open(context, { base, route: urlAfter });
|
|
253
|
+
const wordsDeep = deep.error ? [] : await deep.page.evaluate(PAGE.words).catch(() => []);
|
|
254
|
+
await deep.page.close().catch(() => {});
|
|
255
|
+
const sim = similarity(wordsAfter, wordsDeep);
|
|
256
|
+
if (deep.error || (deep.status ?? 200) >= 400 || sim < 0.5) {
|
|
257
|
+
add(run, {
|
|
258
|
+
...at(c),
|
|
259
|
+
rule: "flow/state-lost",
|
|
260
|
+
severity: deep.status >= 400 || deep.error ? "error" : "warning",
|
|
261
|
+
title: `The view ${describe(c)} opens is lost on reload`,
|
|
262
|
+
evidence: deep.error ?? (deep.status >= 400 ? `${pathOf(urlAfter, base)} answers ${deep.status}` : `${Math.round(sim * 100)}% of the words match after opening ${pathOf(urlAfter, base)} directly`),
|
|
263
|
+
detail: "The click changed the URL without loading a page, but loading that URL fresh — a reload, a shared link, a bookmark — doesn't show the same thing.",
|
|
264
|
+
steps: [...steps, `The URL becomes ${pathOf(urlAfter, base)}`, "Reload, or open that URL in a new tab", deep.status >= 400 ? `It answers ${deep.status}` : "Different content shows"],
|
|
265
|
+
});
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
// Back should undo the move.
|
|
269
|
+
const budget = soft ? backChecks.soft < 6 : backChecks.hard < 2;
|
|
270
|
+
if (budget && settings.checks.has("back")) {
|
|
271
|
+
soft ? backChecks.soft++ : backChecks.hard++;
|
|
272
|
+
await page.waitForLoadState("load", { timeout: 10000 }).catch(() => {});
|
|
273
|
+
await page.goBack({ waitUntil: "load", timeout: 10000 }).catch(() => null);
|
|
274
|
+
await page.waitForLoadState("networkidle", { timeout: 2500 }).catch(() => {});
|
|
275
|
+
await sleep(300);
|
|
276
|
+
const urlBack = page.url();
|
|
277
|
+
const wordsBack = await page.evaluate(PAGE.words).catch(() => []);
|
|
278
|
+
const sim = similarity(armed?.words ?? [], wordsBack);
|
|
279
|
+
if (normalUrl(urlBack) !== normalUrl(urlBefore)) {
|
|
280
|
+
add(run, {
|
|
281
|
+
...at(c),
|
|
282
|
+
rule: "flow/back-broken",
|
|
283
|
+
severity: "error",
|
|
284
|
+
title: `Back doesn't return from where ${describe(c)} goes`,
|
|
285
|
+
evidence: `back lands on ${urlBack === "about:blank" ? "a blank page" : pathOf(urlBack, base)}, not ${pathOf(urlBefore, base)}`,
|
|
286
|
+
detail: "The browser's Back button should undo a move. Here it skips the page or leaves the product — usually `history.replaceState` where `pushState` was meant, or a redirect that adds a history entry.",
|
|
287
|
+
steps: [...steps, `The URL becomes ${pathOf(urlAfter, base)}`, "Press the browser's Back button", `It lands on ${pathOf(urlBack, base)}`],
|
|
288
|
+
});
|
|
289
|
+
} else if (sim < 0.5) {
|
|
290
|
+
add(run, {
|
|
291
|
+
...at(c),
|
|
292
|
+
rule: "flow/back-broken",
|
|
293
|
+
severity: "warning",
|
|
294
|
+
title: `Back returns to the URL but not the page ${describe(c)} left`,
|
|
295
|
+
evidence: `${Math.round(sim * 100)}% of the words match the page before the click`,
|
|
296
|
+
detail: "The address is right but the content isn't: the app doesn't render from the URL when history moves.",
|
|
297
|
+
steps: [...steps, `The URL becomes ${pathOf(urlAfter, base)}`, "Press the browser's Back button", "The URL is back but the content differs"],
|
|
298
|
+
});
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
dirty = true;
|
|
303
|
+
}
|
|
304
|
+
await current?.page.close().catch(() => {});
|
|
305
|
+
|
|
306
|
+
if (deadPlaceholders.length) {
|
|
307
|
+
const first = deadPlaceholders[0];
|
|
308
|
+
const names = deadPlaceholders.map((c) => `“${c.text || c.sel}”`);
|
|
309
|
+
add(run, {
|
|
310
|
+
...at(first),
|
|
311
|
+
rule: "flow/dead-click",
|
|
312
|
+
severity: "error",
|
|
313
|
+
title: deadPlaceholders.length === 1 ? `The link ${names[0]} goes nowhere` : `${deadPlaceholders.length} links go nowhere`,
|
|
314
|
+
evidence: `${names.slice(0, 8).join(", ")}${names.length > 8 ? ", …" : ""} — href="${first.hrefRaw}" and no handler`,
|
|
315
|
+
detail: "Placeholder links: they look like navigation and click to nothing. Give each its real URL, or make it a button that does something.",
|
|
316
|
+
steps: [openStep(route), `Click ${describe(first)}`, `Wait ${quiet / 1000} s: nothing changes`],
|
|
317
|
+
});
|
|
318
|
+
}
|
|
319
|
+
run.stats.clicks += controls.length;
|
|
320
|
+
}
|
package/smoke/config.mjs
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The smoke test's settings and its safety rules.
|
|
3
|
+
*
|
|
4
|
+
* `keyline.smoke.json`, at the project root (or `--config <file>`), is
|
|
5
|
+
* optional. Every key is:
|
|
6
|
+
*
|
|
7
|
+
* {
|
|
8
|
+
* "base": "http://localhost:3000",
|
|
9
|
+
* "routes": ["/", "/settings"], // only these, instead of discovery
|
|
10
|
+
* "examples": { "/projects/[id]": "/projects/42" }, // a URL for each dynamic route
|
|
11
|
+
* "testHosts": ["staging.example.com"], // hosts besides localhost where writes may run
|
|
12
|
+
* "auth": {
|
|
13
|
+
* "storageState": ".auth/state.json", // a saved Playwright session, or:
|
|
14
|
+
* "login": {
|
|
15
|
+
* "url": "/login",
|
|
16
|
+
* "steps": [
|
|
17
|
+
* { "fill": "#email", "env": "SMOKE_EMAIL" }, // credentials only from the environment
|
|
18
|
+
* { "fill": "#password", "env": "SMOKE_PASSWORD" },
|
|
19
|
+
* { "click": "button[type=submit]" },
|
|
20
|
+
* { "waitFor": "/dashboard" } // a URL path, or a selector
|
|
21
|
+
* ]
|
|
22
|
+
* }
|
|
23
|
+
* },
|
|
24
|
+
* "forbid": { "selectors": [".danger-zone"], "urls": ["/admin/*", "/billing"] },
|
|
25
|
+
* "maxClicks": 30,
|
|
26
|
+
* "quietMs": 1500,
|
|
27
|
+
* "stuckMs": 8000
|
|
28
|
+
* }
|
|
29
|
+
*
|
|
30
|
+
* The rules: anything that writes (a form submit, or a control whose words or
|
|
31
|
+
* URL say delete, remove, pay, buy, purchase, unsubscribe, sign out, log out)
|
|
32
|
+
* runs only on a test host: localhost, 127.0.0.1, ::1, *.localhost, *.test,
|
|
33
|
+
* or a host listed in `testHosts`. Of those, the destructive ones run only with
|
|
34
|
+
* `--allow-writes`. Elsewhere, the runner also blocks every request that isn't
|
|
35
|
+
* a GET, HEAD or OPTIONS, whatever started it.
|
|
36
|
+
*/
|
|
37
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
38
|
+
import { isAbsolute, join, resolve } from "node:path";
|
|
39
|
+
|
|
40
|
+
export const DEFAULTS = {
|
|
41
|
+
maxClicks: 30,
|
|
42
|
+
quietMs: 1500,
|
|
43
|
+
stuckMs: 8000,
|
|
44
|
+
limit: 20,
|
|
45
|
+
concurrency: 3,
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
export const CHECKS = ["links", "clicks", "stuck", "back", "forms", "keyboard", "phone", "shift"];
|
|
49
|
+
|
|
50
|
+
/** Words that mean an action can't be taken back, or costs money, or ends the session. */
|
|
51
|
+
export const DESTRUCTIVE = /\b(delete|remove|destroy|erase|wipe|discard|deactivate|close account|cancel (?:my )?(?:subscription|plan|account)|pay|buy|purchase|checkout|check out|place order|unsubscribe|sign ?out|log ?out|logout|signout|revoke)\b/i;
|
|
52
|
+
const DESTRUCTIVE_PATH = /(^|[/_-])(delete|remove|destroy|logout|log-out|signout|sign-out|unsubscribe|checkout|purchase|pay|revoke)([/_.-]|$)/i;
|
|
53
|
+
|
|
54
|
+
export function isDestructive(...texts) {
|
|
55
|
+
return texts.some((t) => t && DESTRUCTIVE.test(String(t)));
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export function isDestructivePath(url) {
|
|
59
|
+
try {
|
|
60
|
+
const u = new URL(url, "http://x");
|
|
61
|
+
return DESTRUCTIVE_PATH.test(u.pathname) || DESTRUCTIVE_PATH.test(u.search);
|
|
62
|
+
} catch {
|
|
63
|
+
return false;
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** A host where writes may run: local, *.localhost, *.test, or one the config names. */
|
|
68
|
+
export function isTestHost(base, testHosts = []) {
|
|
69
|
+
let host;
|
|
70
|
+
try {
|
|
71
|
+
host = new URL(base).hostname.toLowerCase().replace(/^\[|\]$/g, "");
|
|
72
|
+
} catch {
|
|
73
|
+
return false;
|
|
74
|
+
}
|
|
75
|
+
if (["localhost", "127.0.0.1", "::1", "0.0.0.0"].includes(host)) return true;
|
|
76
|
+
if (host.endsWith(".localhost") || host.endsWith(".test")) return true;
|
|
77
|
+
return testHosts.map((h) => String(h).toLowerCase()).includes(host);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** A glob (`/admin/*`), a regex (`/^\/admin/`), or a plain substring. */
|
|
81
|
+
export function urlMatcher(patterns = []) {
|
|
82
|
+
const tests = patterns.map((p) => {
|
|
83
|
+
const s = String(p);
|
|
84
|
+
if (s.length > 2 && s.startsWith("/") && s.endsWith("/") && /[\\^$()|[\]]/.test(s)) {
|
|
85
|
+
const re = new RegExp(s.slice(1, -1));
|
|
86
|
+
return (u) => {
|
|
87
|
+
try {
|
|
88
|
+
const url = new URL(u, "http://x");
|
|
89
|
+
return re.test(url.pathname + url.search) || re.test(u);
|
|
90
|
+
} catch {
|
|
91
|
+
return re.test(u);
|
|
92
|
+
}
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
if (s.includes("*")) {
|
|
96
|
+
const re = new RegExp("^" + s.split("*").map((x) => x.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$");
|
|
97
|
+
return (u) => {
|
|
98
|
+
try {
|
|
99
|
+
const url = new URL(u, "http://x");
|
|
100
|
+
return re.test(url.pathname) || re.test(url.href);
|
|
101
|
+
} catch {
|
|
102
|
+
return re.test(u);
|
|
103
|
+
}
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
return (u) => u.includes(s);
|
|
107
|
+
});
|
|
108
|
+
return (u) => tests.some((t) => t(u));
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
export function loadConfig({ root = ".", file = null } = {}) {
|
|
112
|
+
const path = file ? (isAbsolute(file) ? file : resolve(file)) : join(resolve(root), "keyline.smoke.json");
|
|
113
|
+
if (!existsSync(path)) {
|
|
114
|
+
if (file) throw new Error(`no config at ${file}`);
|
|
115
|
+
return { path: null };
|
|
116
|
+
}
|
|
117
|
+
let config;
|
|
118
|
+
try {
|
|
119
|
+
config = JSON.parse(readFileSync(path, "utf8"));
|
|
120
|
+
} catch (err) {
|
|
121
|
+
throw new Error(`${path} isn't valid JSON: ${err.message}`);
|
|
122
|
+
}
|
|
123
|
+
validate(config, path);
|
|
124
|
+
return { ...config, path };
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function validate(config, path) {
|
|
128
|
+
const login = config.auth?.login;
|
|
129
|
+
if (!login) return;
|
|
130
|
+
if (!Array.isArray(login.steps)) throw new Error(`${path}: auth.login.steps must be a list`);
|
|
131
|
+
for (const step of login.steps) {
|
|
132
|
+
if (step.fill && !step.env) {
|
|
133
|
+
throw new Error(`${path}: the login step filling ${step.fill} needs "env", the environment variable holding the value. Credentials never go in the config.`);
|
|
134
|
+
}
|
|
135
|
+
if ("value" in step || "password" in step) {
|
|
136
|
+
throw new Error(`${path}: a login step has an inline value. Put it in an environment variable and name it with "env".`);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** Settings from defaults, then the config, then the command line. */
|
|
142
|
+
export function settings(opts, config) {
|
|
143
|
+
const list = (v) => (v ? String(v).split(",").map((s) => s.trim()).filter(Boolean) : null);
|
|
144
|
+
const only = list(opts.only);
|
|
145
|
+
const skip = list(opts.skip) ?? [];
|
|
146
|
+
for (const c of [...(only ?? []), ...skip]) {
|
|
147
|
+
if (!CHECKS.includes(c)) throw new Error(`no check called '${c}' — use ${CHECKS.join(", ")}`);
|
|
148
|
+
}
|
|
149
|
+
const testHosts = [...(config.testHosts ?? []), ...(list(opts["test-host"]) ?? [])];
|
|
150
|
+
return {
|
|
151
|
+
checks: new Set((only ?? CHECKS).filter((c) => !skip.includes(c))),
|
|
152
|
+
maxClicks: Number(opts["max-clicks"] ?? config.maxClicks ?? DEFAULTS.maxClicks),
|
|
153
|
+
quietMs: Number(opts["quiet-ms"] ?? config.quietMs ?? DEFAULTS.quietMs),
|
|
154
|
+
stuckMs: Number(opts["stuck-ms"] ?? config.stuckMs ?? DEFAULTS.stuckMs),
|
|
155
|
+
limit: Number(opts.limit ?? DEFAULTS.limit),
|
|
156
|
+
concurrency: Math.max(1, Number(opts.concurrency ?? DEFAULTS.concurrency)),
|
|
157
|
+
allowWrites: Boolean(opts["allow-writes"]),
|
|
158
|
+
testHosts,
|
|
159
|
+
forbidSelectors: config.forbid?.selectors ?? [],
|
|
160
|
+
forbidUrl: urlMatcher(config.forbid?.urls ?? []),
|
|
161
|
+
examples: config.examples ?? {},
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* What the runner may do on this host. `write` is a form submit or anything
|
|
167
|
+
* that sends data; `destructive` is a write that can't be taken back.
|
|
168
|
+
*/
|
|
169
|
+
export function policy({ base, testHosts = [], allowWrites = false }) {
|
|
170
|
+
const test = isTestHost(base, testHosts);
|
|
171
|
+
return {
|
|
172
|
+
testHost: test,
|
|
173
|
+
allowWrites,
|
|
174
|
+
mayWrite: test,
|
|
175
|
+
mayDestroy: test && allowWrites,
|
|
176
|
+
/** Why an action is skipped, or null when it may run. */
|
|
177
|
+
blocks({ write = false, destructive = false } = {}) {
|
|
178
|
+
if (destructive && !test) return "it would change data, and this isn't a test host";
|
|
179
|
+
if (destructive && !allowWrites) return "it looks destructive; run with --allow-writes on a test host to include it";
|
|
180
|
+
if (write && !test) return "it submits data, and this isn't a test host";
|
|
181
|
+
return null;
|
|
182
|
+
},
|
|
183
|
+
};
|
|
184
|
+
}
|