trykeyline-browser 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +14 -2
- package/audit/probe.mjs +390 -0
- package/audit.mjs +209 -0
- package/bin/trykeyline-browser.mjs +79 -0
- package/browse/args.mjs +44 -0
- package/browse/capture.mjs +181 -0
- package/browse/compare.mjs +260 -0
- package/browse/findings.mjs +125 -0
- package/browse/playwright.mjs +78 -0
- package/browse/report.mjs +265 -0
- package/browse/routes.mjs +252 -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
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Keyline's browser tools, a separate package so the core (`trykeyline`) and
|
|
4
|
+
* its skill stay free of Playwright. `npx trykeyline audit …` runs this.
|
|
5
|
+
*
|
|
6
|
+
* trykeyline-browser audit (--base URL | --serve DIR) [options]
|
|
7
|
+
* trykeyline-browser smoke (--base URL | --serve DIR) [options]
|
|
8
|
+
* trykeyline-browser pages | capture | report [options]
|
|
9
|
+
* trykeyline-browser probe <name> [--arg JSON]
|
|
10
|
+
*
|
|
11
|
+
* Exit codes: 0 done, 1 errors found, 2 a usage error.
|
|
12
|
+
*/
|
|
13
|
+
import { readFileSync, realpathSync } from "node:fs";
|
|
14
|
+
import { fileURLToPath } from "node:url";
|
|
15
|
+
import { parseOrExplain } from "../browse/args.mjs";
|
|
16
|
+
|
|
17
|
+
const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
|
|
18
|
+
|
|
19
|
+
const USAGE = `trykeyline-browser ${version} — Keyline's browser tools (also: npx trykeyline <command>).
|
|
20
|
+
|
|
21
|
+
audit (--base URL | --serve DIR) every page measured, with the detector's findings, in one report
|
|
22
|
+
smoke (--base URL | --serve DIR) click through the product and report broken flows
|
|
23
|
+
pages the pages it would visit
|
|
24
|
+
capture (--base URL | --serve DIR) visit, screenshot and report load errors
|
|
25
|
+
report [DIR] [--compare DIR] re-render a report, or mark what changed since another
|
|
26
|
+
probe <name> [--arg JSON] print a page check to run in your own browser
|
|
27
|
+
|
|
28
|
+
Each takes --help. Playwright loads from the project, or installs once into
|
|
29
|
+
~/.cache/keyline, when a command first needs a browser.`;
|
|
30
|
+
|
|
31
|
+
export async function main(argv) {
|
|
32
|
+
const [cmd, ...rest] = argv;
|
|
33
|
+
if (cmd === "audit") return (await import("../audit.mjs")).run(rest);
|
|
34
|
+
if (cmd === "smoke") return (await import("../smoke.mjs")).run(rest);
|
|
35
|
+
if (cmd === "pages" || cmd === "capture" || cmd === "report") return (await import("../browse.mjs")).run(argv);
|
|
36
|
+
if (cmd === "probe") {
|
|
37
|
+
const opts = parseOrExplain("probe", rest, { values: ["arg"] });
|
|
38
|
+
if (!opts) return 2;
|
|
39
|
+
const { PROBES, probeExpression } = await import("../probe.mjs");
|
|
40
|
+
if (opts.help || !opts._[0]) {
|
|
41
|
+
console.log(`keyline probe <name> [--arg JSON] — one expression for your browser's JavaScript tool.\n\nProbes: ${PROBES.join(", ")}`);
|
|
42
|
+
return opts.help ? 0 : 2;
|
|
43
|
+
}
|
|
44
|
+
try {
|
|
45
|
+
console.log(probeExpression(opts._[0], opts.arg ? JSON.parse(opts.arg) : undefined));
|
|
46
|
+
return 0;
|
|
47
|
+
} catch (err) {
|
|
48
|
+
console.error(`keyline probe: ${err.message}`);
|
|
49
|
+
return 2;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
if (cmd === "-v" || cmd === "--version") {
|
|
53
|
+
console.log(version);
|
|
54
|
+
return 0;
|
|
55
|
+
}
|
|
56
|
+
if (!cmd || cmd === "-h" || cmd === "--help") {
|
|
57
|
+
console.log(USAGE);
|
|
58
|
+
return cmd ? 0 : 2;
|
|
59
|
+
}
|
|
60
|
+
console.error(`trykeyline-browser: no command '${cmd}'\n\n${USAGE}`);
|
|
61
|
+
return 2;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const isMain = () => {
|
|
65
|
+
try {
|
|
66
|
+
return process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
|
|
67
|
+
} catch {
|
|
68
|
+
return false;
|
|
69
|
+
}
|
|
70
|
+
};
|
|
71
|
+
if (isMain()) {
|
|
72
|
+
main(process.argv.slice(2)).then(
|
|
73
|
+
(code) => process.exit(code),
|
|
74
|
+
(err) => {
|
|
75
|
+
console.error(err?.stack ?? err);
|
|
76
|
+
process.exit(2);
|
|
77
|
+
},
|
|
78
|
+
);
|
|
79
|
+
}
|
package/browse/args.mjs
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Arguments for the browser tools. Each command names the options it takes:
|
|
3
|
+
* `values` take one (`--base URL` or `--base=URL`, split at the first `=`
|
|
4
|
+
* only, so a URL keeps its query), `switches` take none. Anything else that
|
|
5
|
+
* starts with a dash is an error, so a typo (`--bsae`) is never dropped in
|
|
6
|
+
* silence. `-h` and `--help` are always known.
|
|
7
|
+
*
|
|
8
|
+
* @returns {{ _: string[], [option: string]: string | boolean | string[] } | { error: string }}
|
|
9
|
+
*/
|
|
10
|
+
export function parseArgs(argv, { values = [], switches = [] } = {}) {
|
|
11
|
+
const opts = { _: [] };
|
|
12
|
+
for (let i = 0; i < argv.length; i++) {
|
|
13
|
+
const a = argv[i];
|
|
14
|
+
if (a === "-h" || a === "--help") {
|
|
15
|
+
opts.help = true;
|
|
16
|
+
continue;
|
|
17
|
+
}
|
|
18
|
+
if (!a.startsWith("-") || a === "-") {
|
|
19
|
+
opts._.push(a);
|
|
20
|
+
continue;
|
|
21
|
+
}
|
|
22
|
+
const eq = a.indexOf("=");
|
|
23
|
+
const name = a.startsWith("--") ? (eq > 0 ? a.slice(2, eq) : a.slice(2)) : a;
|
|
24
|
+
if (switches.includes(name)) {
|
|
25
|
+
if (eq > 0) return { error: `--${name} takes no value` };
|
|
26
|
+
opts[name] = true;
|
|
27
|
+
} else if (values.includes(name)) {
|
|
28
|
+
const value = eq > 0 ? a.slice(eq + 1) : argv[++i];
|
|
29
|
+
if (value === undefined || value === "" || (eq < 0 && value.startsWith("--"))) return { error: `--${name} needs a value` };
|
|
30
|
+
opts[name] = value;
|
|
31
|
+
} else {
|
|
32
|
+
return { error: `unknown option ${a.startsWith("--") ? `--${name}` : a}` };
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
return opts;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Parse, or print why not and a pointer to --help. Returns null on a usage error (the caller exits 2). */
|
|
39
|
+
export function parseOrExplain(command, argv, spec) {
|
|
40
|
+
const opts = parseArgs(argv, spec);
|
|
41
|
+
if (!opts.error) return opts;
|
|
42
|
+
console.error(`keyline ${command}: ${opts.error} (try --help)`);
|
|
43
|
+
return null;
|
|
44
|
+
}
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Visit a page the way a reader would, and keep what the run needs: the HTTP
|
|
3
|
+
* status, console errors, uncaught exceptions, failed requests, the links the
|
|
4
|
+
* page actually rendered, a full-page screenshot, and whatever the caller's
|
|
5
|
+
* probes measure inside the page.
|
|
6
|
+
*
|
|
7
|
+
* A probe is `{ name, fn }`: `fn` runs in the page (Playwright's
|
|
8
|
+
* `page.evaluate`) after the page has settled and been scrolled through, and
|
|
9
|
+
* returns plain data. The audit's checks and the smoke test's element
|
|
10
|
+
* inventory are probes; the core knows nothing about either.
|
|
11
|
+
*/
|
|
12
|
+
import { mkdirSync } from "node:fs";
|
|
13
|
+
import { dirname, join } from "node:path";
|
|
14
|
+
import { linkPath } from "./routes.mjs";
|
|
15
|
+
|
|
16
|
+
export const VIEWPORTS = {
|
|
17
|
+
desktop: { name: "desktop", width: 1440, height: 900, isMobile: false, hasTouch: false },
|
|
18
|
+
phone: { name: "phone", width: 390, height: 844, isMobile: true, hasTouch: true },
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
export const THEMES = ["light", "dark"];
|
|
22
|
+
|
|
23
|
+
/** A screenshot taller than this is clipped: a 40,000px page is a bug, not a picture. */
|
|
24
|
+
const MAX_SHOT_HEIGHT = 9000;
|
|
25
|
+
|
|
26
|
+
export function shotKey(viewport, theme) {
|
|
27
|
+
return `${viewport}-${theme}`;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export function shotFile(route, viewport, theme) {
|
|
31
|
+
const slug = route === "/" ? "home" : route.replace(/^\//, "").replace(/[^a-z0-9]+/gi, "-").replace(/-+$/, "").toLowerCase();
|
|
32
|
+
return join("shots", `${slug}--${viewport}-${theme}.png`);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* One browser context per viewport × theme: colour scheme and touch are
|
|
37
|
+
* context-wide, and a fresh context means no state leaks between passes.
|
|
38
|
+
*/
|
|
39
|
+
export async function openContext(browser, { viewport = "desktop", theme = "light", reducedMotion = false, storageState } = {}) {
|
|
40
|
+
const vp = VIEWPORTS[viewport] ?? viewport;
|
|
41
|
+
return browser.newContext({
|
|
42
|
+
viewport: { width: vp.width, height: vp.height },
|
|
43
|
+
isMobile: vp.isMobile,
|
|
44
|
+
hasTouch: vp.hasTouch,
|
|
45
|
+
colorScheme: theme,
|
|
46
|
+
reducedMotion: reducedMotion ? "reduce" : "no-preference",
|
|
47
|
+
deviceScaleFactor: 1,
|
|
48
|
+
storageState,
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Scroll to the bottom in steps and back, so lazy images and reveal-on-scroll content are present. */
|
|
53
|
+
async function settle(page) {
|
|
54
|
+
await page.evaluate(async () => {
|
|
55
|
+
const step = Math.max(400, Math.floor(window.innerHeight * 0.8));
|
|
56
|
+
const wait = (ms) => new Promise((r) => setTimeout(r, ms));
|
|
57
|
+
for (let y = 0; y < document.documentElement.scrollHeight && y < 40000; y += step) {
|
|
58
|
+
window.scrollTo(0, y);
|
|
59
|
+
await wait(60);
|
|
60
|
+
}
|
|
61
|
+
window.scrollTo(0, 0);
|
|
62
|
+
await wait(120);
|
|
63
|
+
await document.fonts?.ready;
|
|
64
|
+
// Let finite animations land (an opening sequence, a reveal), up to 4s, so the page is shot as it settles.
|
|
65
|
+
const finite = document.getAnimations().filter((a) => a.effect?.getComputedTiming().endTime !== Infinity);
|
|
66
|
+
await Promise.race([Promise.all(finite.map((a) => a.finished.catch(() => {}))), wait(4000)]);
|
|
67
|
+
});
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Wire a page's listeners. Returned arrays fill as the page runs, so a smoke
|
|
72
|
+
* step can read them before and after a click.
|
|
73
|
+
*/
|
|
74
|
+
export function listen(page, origin) {
|
|
75
|
+
const log = { console: [], pageErrors: [], failedRequests: [] };
|
|
76
|
+
page.on("console", (msg) => {
|
|
77
|
+
if (msg.type() === "error" || msg.type() === "warning") log.console.push({ type: msg.type(), text: msg.text().slice(0, 500), at: msg.location()?.url ?? null });
|
|
78
|
+
});
|
|
79
|
+
page.on("pageerror", (err) => log.pageErrors.push({ text: String(err?.message ?? err).slice(0, 500) }));
|
|
80
|
+
page.on("requestfailed", (req) => {
|
|
81
|
+
const failure = req.failure()?.errorText ?? "failed";
|
|
82
|
+
if (/ERR_ABORTED/.test(failure)) return; // navigations and cancelled prefetches
|
|
83
|
+
log.failedRequests.push({ url: req.url(), method: req.method(), status: null, error: failure, sameOrigin: req.url().startsWith(origin) });
|
|
84
|
+
});
|
|
85
|
+
page.on("response", (res) => {
|
|
86
|
+
if (res.status() >= 400) log.failedRequests.push({ url: res.url(), method: res.request().method(), status: res.status(), error: null, sameOrigin: res.url().startsWith(origin) });
|
|
87
|
+
});
|
|
88
|
+
return log;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* Visit one route in an open context. Returns the page record for
|
|
93
|
+
* findings.json plus the raw logs and probe results for the caller to judge.
|
|
94
|
+
*/
|
|
95
|
+
export async function visit(context, { base, route, out, viewport = "desktop", theme = "light", probes = [], shoot = true, timeout = 30000 }) {
|
|
96
|
+
const page = await context.newPage();
|
|
97
|
+
const origin = new URL(base).origin;
|
|
98
|
+
const log = listen(page, origin);
|
|
99
|
+
const url = new URL(route, base).href;
|
|
100
|
+
let status = null;
|
|
101
|
+
let navError = null;
|
|
102
|
+
try {
|
|
103
|
+
const res = await page.goto(url, { waitUntil: "load", timeout });
|
|
104
|
+
status = res?.status() ?? null;
|
|
105
|
+
await page.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
|
|
106
|
+
await settle(page);
|
|
107
|
+
} catch (err) {
|
|
108
|
+
navError = String(err?.message ?? err).split("\n")[0];
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const title = await page.title().catch(() => "");
|
|
112
|
+
const finalUrl = page.url();
|
|
113
|
+
const links = navError
|
|
114
|
+
? []
|
|
115
|
+
: [
|
|
116
|
+
...new Set(
|
|
117
|
+
(await page.$$eval("a[href]", (as) => as.map((a) => a.getAttribute("href"))).catch(() => []))
|
|
118
|
+
.map((h) => linkPath(h, finalUrl, origin))
|
|
119
|
+
.filter(Boolean),
|
|
120
|
+
),
|
|
121
|
+
];
|
|
122
|
+
|
|
123
|
+
const results = {};
|
|
124
|
+
if (!navError) {
|
|
125
|
+
for (const probe of probes) {
|
|
126
|
+
try {
|
|
127
|
+
results[probe.name] = await page.evaluate(probe.fn, probe.arg);
|
|
128
|
+
} catch (err) {
|
|
129
|
+
results[probe.name] = { error: String(err?.message ?? err).split("\n")[0] };
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
let shot = null;
|
|
135
|
+
if (shoot && !navError) {
|
|
136
|
+
const file = shotFile(route, viewport, theme);
|
|
137
|
+
mkdirSync(dirname(join(out, file)), { recursive: true });
|
|
138
|
+
const size = await page.evaluate(() => ({ w: document.documentElement.clientWidth, h: document.documentElement.scrollHeight }));
|
|
139
|
+
const height = Math.min(size.h, MAX_SHOT_HEIGHT);
|
|
140
|
+
await page.screenshot({ path: join(out, file), fullPage: true, animations: "disabled", clip: { x: 0, y: 0, width: size.w, height } });
|
|
141
|
+
shot = { path: file, width: size.w, height, clipped: size.h > MAX_SHOT_HEIGHT };
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
await page.close();
|
|
145
|
+
return { route, url, finalUrl, title, status, navError, links, log, results, shot, viewport, theme };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** Selector for an element, short enough to read and stable enough to find again. Runs in the page. */
|
|
149
|
+
export const SELECTOR_HELPER = `
|
|
150
|
+
window.__keylineSelector = function (el) {
|
|
151
|
+
if (!(el instanceof Element)) return null;
|
|
152
|
+
if (el.id && /^[A-Za-z][\\w-]*$/.test(el.id)) return '#' + el.id;
|
|
153
|
+
const parts = [];
|
|
154
|
+
while (el && el.nodeType === 1 && parts.length < 5) {
|
|
155
|
+
let part = el.localName;
|
|
156
|
+
const testId = el.getAttribute('data-testid');
|
|
157
|
+
if (testId) { parts.unshift(part + '[data-testid="' + testId + '"]'); break; }
|
|
158
|
+
const cls = [...el.classList].filter((c) => /^[A-Za-z][\\w-]*$/.test(c) && c.length < 30).slice(0, 2);
|
|
159
|
+
if (cls.length) part += '.' + cls.join('.');
|
|
160
|
+
const parent = el.parentElement;
|
|
161
|
+
if (parent) {
|
|
162
|
+
const same = [...parent.children].filter((c) => c.localName === el.localName);
|
|
163
|
+
if (same.length > 1) part += ':nth-of-type(' + (same.indexOf(el) + 1) + ')';
|
|
164
|
+
}
|
|
165
|
+
parts.unshift(part);
|
|
166
|
+
if (el.id) break;
|
|
167
|
+
el = parent;
|
|
168
|
+
}
|
|
169
|
+
return parts.join(' > ');
|
|
170
|
+
};
|
|
171
|
+
window.__keylineBox = function (el) {
|
|
172
|
+
const r = el.getBoundingClientRect();
|
|
173
|
+
return { x: Math.round(r.left + window.scrollX), y: Math.round(r.top + window.scrollY), w: Math.round(r.width), h: Math.round(r.height) };
|
|
174
|
+
};
|
|
175
|
+
`;
|
|
176
|
+
|
|
177
|
+
/** Install the helpers on every page of a context, before any probe runs. */
|
|
178
|
+
export async function withHelpers(context) {
|
|
179
|
+
await context.addInitScript(SELECTOR_HELPER);
|
|
180
|
+
return context;
|
|
181
|
+
}
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What changed since the last run: which findings are new, which are still
|
|
3
|
+
* there, which came back, which were fixed, and which pages look different.
|
|
4
|
+
*
|
|
5
|
+
* keyline report keyline-report --compare keyline-report-before
|
|
6
|
+
*
|
|
7
|
+
* Findings are matched on rule + page + viewport + theme + selector (the title
|
|
8
|
+
* when there's no selector) — the same key a run is de-duplicated on. Each
|
|
9
|
+
* finding in the current run gets `change`:
|
|
10
|
+
*
|
|
11
|
+
* "new" not in the previous run
|
|
12
|
+
* "still" in it too (a status a person set there — accepted, dismissed — carries over)
|
|
13
|
+
* "returned" not in the previous run, but in that run's own `fixed` list: fixed once, back now
|
|
14
|
+
*
|
|
15
|
+
* The previous run's findings with no match go under `fixed`, if the current
|
|
16
|
+
* run could have seen them again: their page was visited, at their viewport and
|
|
17
|
+
* theme. Pages left out of this run say nothing about what was fixed on them.
|
|
18
|
+
*
|
|
19
|
+
* Screenshots present in both runs are diffed pixel by pixel in the browser
|
|
20
|
+
* Playwright already drives (canvas, no image library), each diff written to
|
|
21
|
+
* `diffs/`. A page × viewport × theme whose changed share is above the
|
|
22
|
+
* threshold gets an info finding, `visual/changed`, boxed round what changed.
|
|
23
|
+
*/
|
|
24
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
25
|
+
import { dirname, join, relative } from "node:path";
|
|
26
|
+
import { split } from "trykeyline/check/findings";
|
|
27
|
+
import { readRun, writeRun } from "./findings.mjs";
|
|
28
|
+
import { shotKey } from "./capture.mjs";
|
|
29
|
+
|
|
30
|
+
/** The identity of a finding across runs. */
|
|
31
|
+
export function matchKey(f) {
|
|
32
|
+
return [f.rule, f.page ?? "", f.viewport ?? "", f.theme ?? "", f.selector ?? f.title].join("|");
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Findings that describe a comparison, not the product, never take part in one. */
|
|
36
|
+
const isVisual = (f) => f.rule?.startsWith("visual/");
|
|
37
|
+
|
|
38
|
+
/** Remove what an earlier compare wrote, so comparing twice gives the same answer. */
|
|
39
|
+
export function clearCompare(run) {
|
|
40
|
+
delete run.compare;
|
|
41
|
+
delete run.fixed;
|
|
42
|
+
run.findings = run.findings.filter((f) => !isVisual(f)).map(({ change, previous, diff, ...f }) => f);
|
|
43
|
+
for (const p of run.pages ?? []) delete p.diffs;
|
|
44
|
+
return run;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Mark `run`'s findings against `prev`. Mutates and returns `run`. */
|
|
48
|
+
export function compareRuns(run, prev, { against = null } = {}) {
|
|
49
|
+
const fixedBefore = new Set((prev.fixed ?? []).map(matchKey));
|
|
50
|
+
const { matched, left } = split(run.findings.filter((f) => !isVisual(f)), prev.findings.filter((f) => !isVisual(f)), matchKey);
|
|
51
|
+
for (const [f, was] of matched) {
|
|
52
|
+
if (was) {
|
|
53
|
+
f.change = "still";
|
|
54
|
+
f.previous = was.id;
|
|
55
|
+
if ((!f.status || f.status === "open") && was.status && was.status !== "open") f.status = was.status;
|
|
56
|
+
} else {
|
|
57
|
+
f.change = fixedBefore.has(matchKey(f)) ? "returned" : "new";
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// Only what this run could have seen again counts as fixed.
|
|
62
|
+
const routes = new Set(run.pages.map((p) => p.route));
|
|
63
|
+
const passes = new Set(run.pages.flatMap((p) => Object.keys(p.shots ?? {})));
|
|
64
|
+
const seen = (f) => {
|
|
65
|
+
if (f.page && !routes.has(f.page)) return false;
|
|
66
|
+
if (f.viewport && f.theme && passes.size && !passes.has(shotKey(f.viewport, f.theme))) return false;
|
|
67
|
+
return true;
|
|
68
|
+
};
|
|
69
|
+
run.fixed = left.filter(seen).map(({ change, previous, ...f }, i) => ({ ...f, previous: f.id, id: `x${i + 1}`, change: "fixed" }));
|
|
70
|
+
|
|
71
|
+
const count = (c) => run.findings.filter((f) => f.change === c).length;
|
|
72
|
+
run.compare = {
|
|
73
|
+
against,
|
|
74
|
+
previous: { kind: prev.kind, started: prev.started, finished: prev.finished },
|
|
75
|
+
new: count("new"),
|
|
76
|
+
still: count("still"),
|
|
77
|
+
returned: count("returned"),
|
|
78
|
+
fixed: run.fixed.length,
|
|
79
|
+
};
|
|
80
|
+
return run;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Diff two PNGs in a browser page. `before` and `after` are PNG buffers.
|
|
85
|
+
* Returns the share of pixels that changed, a box round them, and a diff
|
|
86
|
+
* image: the new shot washed out, changed pixels in red. Where the sizes
|
|
87
|
+
* differ, the area only one shot covers counts as changed.
|
|
88
|
+
*/
|
|
89
|
+
export async function diffPngs(page, before, after, { tolerance = 24 } = {}) {
|
|
90
|
+
const r = await page.evaluate(
|
|
91
|
+
async ({ a, b, tolerance }) => {
|
|
92
|
+
const load = (src) =>
|
|
93
|
+
new Promise((res, rej) => {
|
|
94
|
+
const img = new Image();
|
|
95
|
+
img.onload = () => res(img);
|
|
96
|
+
img.onerror = () => rej(new Error("a screenshot couldn't be decoded"));
|
|
97
|
+
img.src = src;
|
|
98
|
+
});
|
|
99
|
+
const [ia, ib] = await Promise.all([load(a), load(b)]);
|
|
100
|
+
const w = Math.max(ia.naturalWidth, ib.naturalWidth);
|
|
101
|
+
const h = Math.max(ia.naturalHeight, ib.naturalHeight);
|
|
102
|
+
const pixels = (img) => {
|
|
103
|
+
const c = new OffscreenCanvas(w, h);
|
|
104
|
+
const ctx = c.getContext("2d", { willReadFrequently: true });
|
|
105
|
+
ctx.drawImage(img, 0, 0);
|
|
106
|
+
return ctx.getImageData(0, 0, w, h).data;
|
|
107
|
+
};
|
|
108
|
+
const pa = pixels(ia);
|
|
109
|
+
const pb = pixels(ib);
|
|
110
|
+
const out = new ImageData(w, h);
|
|
111
|
+
const d = out.data;
|
|
112
|
+
let changed = 0;
|
|
113
|
+
let x0 = w, y0 = h, x1 = -1, y1 = -1;
|
|
114
|
+
for (let y = 0; y < h; y++) {
|
|
115
|
+
const inA = y < ia.naturalHeight;
|
|
116
|
+
const inB = y < ib.naturalHeight;
|
|
117
|
+
for (let x = 0; x < w; x++) {
|
|
118
|
+
const i = (y * w + x) * 4;
|
|
119
|
+
const a1 = inA && x < ia.naturalWidth;
|
|
120
|
+
const b1 = inB && x < ib.naturalWidth;
|
|
121
|
+
const diff = !(a1 && b1) || Math.abs(pa[i] - pb[i]) > tolerance || Math.abs(pa[i + 1] - pb[i + 1]) > tolerance || Math.abs(pa[i + 2] - pb[i + 2]) > tolerance || Math.abs(pa[i + 3] - pb[i + 3]) > tolerance;
|
|
122
|
+
if (diff) {
|
|
123
|
+
changed++;
|
|
124
|
+
if (x < x0) x0 = x;
|
|
125
|
+
if (y < y0) y0 = y;
|
|
126
|
+
if (x > x1) x1 = x;
|
|
127
|
+
if (y > y1) y1 = y;
|
|
128
|
+
d[i] = 230; d[i + 1] = 30; d[i + 2] = 30; d[i + 3] = 255;
|
|
129
|
+
} else {
|
|
130
|
+
const src = b1 ? pb : pa;
|
|
131
|
+
const lum = 0.299 * src[i] + 0.587 * src[i + 1] + 0.114 * src[i + 2];
|
|
132
|
+
const v = 255 - (255 - lum) * 0.22;
|
|
133
|
+
d[i] = v; d[i + 1] = v; d[i + 2] = v; d[i + 3] = 255;
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
const c = new OffscreenCanvas(w, h);
|
|
138
|
+
c.getContext("2d").putImageData(out, 0, 0);
|
|
139
|
+
const blob = await c.convertToBlob({ type: "image/png" });
|
|
140
|
+
const png = await new Promise((res) => {
|
|
141
|
+
const fr = new FileReader();
|
|
142
|
+
fr.onload = () => res(String(fr.result).split(",")[1]);
|
|
143
|
+
fr.readAsDataURL(blob);
|
|
144
|
+
});
|
|
145
|
+
return {
|
|
146
|
+
width: w,
|
|
147
|
+
height: h,
|
|
148
|
+
before: { width: ia.naturalWidth, height: ia.naturalHeight },
|
|
149
|
+
after: { width: ib.naturalWidth, height: ib.naturalHeight },
|
|
150
|
+
changed,
|
|
151
|
+
total: w * h,
|
|
152
|
+
box: changed ? { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 } : null,
|
|
153
|
+
png,
|
|
154
|
+
};
|
|
155
|
+
},
|
|
156
|
+
{ a: `data:image/png;base64,${before.toString("base64")}`, b: `data:image/png;base64,${after.toString("base64")}`, tolerance },
|
|
157
|
+
);
|
|
158
|
+
return { ...r, percent: r.total ? Math.round((r.changed / r.total) * 100000) / 1000 : 0, png: Buffer.from(r.png, "base64") };
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** Every shot present in both runs, as pairs of files. */
|
|
162
|
+
export function shotPairs(run, dir, prev, prevDir) {
|
|
163
|
+
const prevPages = new Map(prev.pages.map((p) => [p.route, p]));
|
|
164
|
+
const pairs = [];
|
|
165
|
+
for (const page of run.pages) {
|
|
166
|
+
const was = prevPages.get(page.route);
|
|
167
|
+
if (!was) continue;
|
|
168
|
+
for (const [key, shot] of Object.entries(page.shots ?? {})) {
|
|
169
|
+
const old = was.shots?.[key];
|
|
170
|
+
if (!old) continue;
|
|
171
|
+
const after = join(dir, shot.path);
|
|
172
|
+
const before = join(prevDir, old.path);
|
|
173
|
+
if (existsSync(after) && existsSync(before)) pairs.push({ page, key, shot, before, after });
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
return pairs;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Diff every shared shot and record it: `pages[].diffs[key]`, a PNG in
|
|
181
|
+
* `diffs/`, and a `visual/changed` finding above `threshold` percent.
|
|
182
|
+
*/
|
|
183
|
+
export async function diffRuns(run, dir, prev, prevDir, { browser, threshold = 0.01, tolerance = 24, log = () => {} }) {
|
|
184
|
+
const pairs = shotPairs(run, dir, prev, prevDir);
|
|
185
|
+
if (!pairs.length) return { compared: 0, changed: 0 };
|
|
186
|
+
const page = await browser.newPage();
|
|
187
|
+
let changedPages = 0;
|
|
188
|
+
try {
|
|
189
|
+
for (const p of pairs) {
|
|
190
|
+
const r = await diffPngs(page, readFileSync(p.before), readFileSync(p.after), { tolerance });
|
|
191
|
+
const file = join("diffs", p.shot.path.split("/").pop());
|
|
192
|
+
mkdirSync(dirname(join(dir, file)), { recursive: true });
|
|
193
|
+
writeFileSync(join(dir, file), r.png);
|
|
194
|
+
const [viewport, theme] = p.key.split("-");
|
|
195
|
+
p.page.diffs ??= {};
|
|
196
|
+
p.page.diffs[p.key] = { path: file, percent: r.percent, width: r.width, height: r.height, box: r.box, sizeChanged: r.before.width !== r.after.width || r.before.height !== r.after.height };
|
|
197
|
+
log(` ${viewport} ${theme} ${p.page.route} ${r.percent}% changed`);
|
|
198
|
+
if (r.percent > threshold) {
|
|
199
|
+
changedPages++;
|
|
200
|
+
run.findings.push({
|
|
201
|
+
id: `v${changedPages}`,
|
|
202
|
+
kind: run.kind,
|
|
203
|
+
domain: "visual",
|
|
204
|
+
rule: "visual/changed",
|
|
205
|
+
severity: "info",
|
|
206
|
+
status: "open",
|
|
207
|
+
title: "This page looks different since the last run",
|
|
208
|
+
detail: "Red in the diff marks every pixel that changed. If the change wasn't meant, it's a regression; if it was, nothing to do.",
|
|
209
|
+
evidence: `${r.percent}% of the page changed${p.page.diffs[p.key].sizeChanged ? ` · ${r.before.width}×${r.before.height} → ${r.after.width}×${r.after.height}` : ""}`,
|
|
210
|
+
page: p.page.route,
|
|
211
|
+
viewport,
|
|
212
|
+
theme,
|
|
213
|
+
shot: p.key,
|
|
214
|
+
box: r.box ? clampBox(r.box, p.shot) : undefined,
|
|
215
|
+
diff: { path: file, width: r.width, height: r.height, box: r.box },
|
|
216
|
+
});
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
} finally {
|
|
220
|
+
await page.close();
|
|
221
|
+
}
|
|
222
|
+
return { compared: pairs.length, changed: changedPages };
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
function clampBox(box, shot) {
|
|
226
|
+
const x = Math.min(box.x, shot.width - 1);
|
|
227
|
+
const y = Math.min(box.y, shot.height - 1);
|
|
228
|
+
return { x, y, w: Math.max(1, Math.min(box.w, shot.width - x)), h: Math.max(1, Math.min(box.h, shot.height - y)) };
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/**
|
|
232
|
+
* Compare the run in `dir` with the one in `prevDir`, write the marks into
|
|
233
|
+
* `dir/findings.json`, and diff the screenshots unless `diff: false`. A browser
|
|
234
|
+
* is launched only when there are shots to diff; if none can launch, the
|
|
235
|
+
* findings are still compared and the diff is skipped with a note.
|
|
236
|
+
*/
|
|
237
|
+
export async function compareDirs(dir, prevDir, { diff = true, threshold = 0.01, tolerance = 24, browser = null, launch = null, log = (m) => process.stderr.write(m + "\n") } = {}) {
|
|
238
|
+
const run = clearCompare(readRun(dir));
|
|
239
|
+
const prev = readRun(prevDir);
|
|
240
|
+
if (prev.kind !== run.kind) log(`Comparing a ${run.kind} with a ${prev.kind}: findings only one of them looks for will show as new or fixed.`);
|
|
241
|
+
compareRuns(run, prev, { against: relative(dir, prevDir) || "." });
|
|
242
|
+
|
|
243
|
+
if (diff && shotPairs(run, dir, prev, prevDir).length) {
|
|
244
|
+
let own = null;
|
|
245
|
+
try {
|
|
246
|
+
if (!browser) {
|
|
247
|
+
const start = launch ?? (await import("./playwright.mjs")).launch;
|
|
248
|
+
own = await start({ root: run.root ?? process.cwd(), log });
|
|
249
|
+
}
|
|
250
|
+
log("Diffing screenshots …");
|
|
251
|
+
run.compare.visual = { threshold, ...(await diffRuns(run, dir, prev, prevDir, { browser: browser ?? own, threshold, tolerance, log })) };
|
|
252
|
+
} catch (err) {
|
|
253
|
+
log(`Screenshots not diffed: ${String(err?.message ?? err).split("\n")[0]}`);
|
|
254
|
+
run.compare.visual = { threshold, compared: 0, changed: 0, skipped: String(err?.message ?? err).split("\n")[0] };
|
|
255
|
+
} finally {
|
|
256
|
+
await own?.close();
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
return writeRun(dir, run);
|
|
260
|
+
}
|