@cappa/core 0.14.0 → 0.16.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/dist/index.cjs +1502 -11
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +651 -3
- package/dist/index.d.mts +651 -3
- package/dist/index.mjs +1465 -12
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.cjs
CHANGED
|
@@ -47,6 +47,7 @@ let _blazediff_core_native = require("@blazediff/core-native");
|
|
|
47
47
|
let _blazediff_interpret_native = require("@blazediff/interpret-native");
|
|
48
48
|
let node_crypto = require("node:crypto");
|
|
49
49
|
let playwright_core = require("playwright-core");
|
|
50
|
+
let node_child_process = require("node:child_process");
|
|
50
51
|
//#region src/features/png/util.ts
|
|
51
52
|
const pngSignature = Buffer.from([
|
|
52
53
|
137,
|
|
@@ -844,6 +845,17 @@ var ScreenshotFileSystem = class {
|
|
|
844
845
|
await node_fs_promises.default.writeFile(filepath, data);
|
|
845
846
|
}
|
|
846
847
|
/**
|
|
848
|
+
* Remove a screenshot's diff image and metadata sidecar, if any.
|
|
849
|
+
*
|
|
850
|
+
* A run that does not clear `diff/` — a filtered or single-screenshot
|
|
851
|
+
* re-capture — would otherwise leave the previous run's diff behind for a
|
|
852
|
+
* screenshot that now passes, and a screenshot with a diff is `changed`.
|
|
853
|
+
*/
|
|
854
|
+
async removeDiffFiles(filename) {
|
|
855
|
+
const filepath = this.getDiffFilePath(filename);
|
|
856
|
+
await Promise.all([node_fs_promises.default.rm(filepath, { force: true }), node_fs_promises.default.rm(toDiffMetaPath(filepath), { force: true })]);
|
|
857
|
+
}
|
|
858
|
+
/**
|
|
847
859
|
* Get the path to a diff metadata sidecar file (`<name>.json`)
|
|
848
860
|
*/
|
|
849
861
|
getDiffMetaFilePath(filename) {
|
|
@@ -990,6 +1002,91 @@ const recordCaptureOrigins = async (outputDir, origins, knownNames) => {
|
|
|
990
1002
|
}
|
|
991
1003
|
};
|
|
992
1004
|
//#endregion
|
|
1005
|
+
//#region src/webServer/unreachable.ts
|
|
1006
|
+
/** The advice for a refused connection when the config has no `webServer`. */
|
|
1007
|
+
const NO_WEB_SERVER_HINT = "Start it before capturing, or add a `webServer` entry to cappa.config.ts so cappa starts it for you.";
|
|
1008
|
+
/**
|
|
1009
|
+
* How a refused connection reads, across the places one surfaces: Node's
|
|
1010
|
+
* sockets and `fetch` (`ECONNREFUSED`), Chromium (`net::ERR_CONNECTION_REFUSED`),
|
|
1011
|
+
* Firefox (`NS_ERROR_CONNECTION_REFUSED`) and WebKit.
|
|
1012
|
+
*/
|
|
1013
|
+
const REFUSED_PATTERN = /\bECONNREFUSED\b|\bERR_CONNECTION_REFUSED\b|\bNS_ERROR_CONNECTION_REFUSED\b|Could not connect to (?:the )?server|Connection refused/i;
|
|
1014
|
+
const URL_PATTERN = /\bhttps?:\/\/[^\s"'`<>)\]]+/i;
|
|
1015
|
+
const toOrigin = (url) => {
|
|
1016
|
+
try {
|
|
1017
|
+
return new URL(url.replace(/[.,;:!?]+$/, "")).origin;
|
|
1018
|
+
} catch {
|
|
1019
|
+
return;
|
|
1020
|
+
}
|
|
1021
|
+
};
|
|
1022
|
+
/**
|
|
1023
|
+
* Whether `error` — an `Error`, a plain object, or just a message string, as
|
|
1024
|
+
* plugins report task failures — is a refused connection.
|
|
1025
|
+
*
|
|
1026
|
+
* Walks `cause` and `AggregateError.errors`: Node's `fetch` says only
|
|
1027
|
+
* "fetch failed" and puts `ECONNREFUSED` on its cause, and a plugin that wraps
|
|
1028
|
+
* the error in a friendlier one keeps it there too.
|
|
1029
|
+
*
|
|
1030
|
+
* Works on any plugin's errors, third-party included, because it reads the
|
|
1031
|
+
* error rather than asking the plugin.
|
|
1032
|
+
*/
|
|
1033
|
+
function findRefusedConnection(error) {
|
|
1034
|
+
let refused = false;
|
|
1035
|
+
let origin;
|
|
1036
|
+
let socketOrigin;
|
|
1037
|
+
const seen = /* @__PURE__ */ new Set();
|
|
1038
|
+
const visit = (value, depth) => {
|
|
1039
|
+
if (value === null || value === void 0 || depth > 8 || seen.has(value)) return;
|
|
1040
|
+
seen.add(value);
|
|
1041
|
+
if (typeof value === "string") {
|
|
1042
|
+
if (REFUSED_PATTERN.test(value)) refused = true;
|
|
1043
|
+
const url = value.match(URL_PATTERN)?.[0];
|
|
1044
|
+
origin ??= url ? toOrigin(url) : void 0;
|
|
1045
|
+
return;
|
|
1046
|
+
}
|
|
1047
|
+
if (typeof value !== "object") return;
|
|
1048
|
+
const record = value;
|
|
1049
|
+
if (record.code === "ECONNREFUSED") {
|
|
1050
|
+
refused = true;
|
|
1051
|
+
if (typeof record.address === "string" && record.port !== void 0) {
|
|
1052
|
+
const host = record.address.includes(":") ? `[${record.address}]` : record.address;
|
|
1053
|
+
socketOrigin ??= `http://${host}:${record.port}`;
|
|
1054
|
+
}
|
|
1055
|
+
}
|
|
1056
|
+
visit(record.message, depth + 1);
|
|
1057
|
+
visit(record.cause, depth + 1);
|
|
1058
|
+
if (Array.isArray(record.errors)) for (const inner of record.errors) visit(inner, depth + 1);
|
|
1059
|
+
};
|
|
1060
|
+
visit(error, 0);
|
|
1061
|
+
if (!refused) return;
|
|
1062
|
+
const resolved = origin ?? socketOrigin;
|
|
1063
|
+
return resolved ? { origin: resolved } : {};
|
|
1064
|
+
}
|
|
1065
|
+
const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
|
|
1066
|
+
"localhost",
|
|
1067
|
+
"127.0.0.1",
|
|
1068
|
+
"[::1]",
|
|
1069
|
+
"0.0.0.0"
|
|
1070
|
+
]);
|
|
1071
|
+
/**
|
|
1072
|
+
* Whether two origins name the same server.
|
|
1073
|
+
*
|
|
1074
|
+
* Loopback spellings are interchangeable: a plugin configured with
|
|
1075
|
+
* `localhost:6006` and a socket error reporting `127.0.0.1:6006` are the same
|
|
1076
|
+
* Storybook.
|
|
1077
|
+
*/
|
|
1078
|
+
function sameServer(a, b) {
|
|
1079
|
+
try {
|
|
1080
|
+
const left = new URL(a);
|
|
1081
|
+
const right = new URL(b);
|
|
1082
|
+
const port = (url) => url.port || (url.protocol === "https:" ? "443" : "80");
|
|
1083
|
+
if (port(left) !== port(right)) return false;
|
|
1084
|
+
return left.hostname === right.hostname || LOOPBACK_HOSTS.has(left.hostname) && LOOPBACK_HOSTS.has(right.hostname);
|
|
1085
|
+
} catch {
|
|
1086
|
+
return false;
|
|
1087
|
+
}
|
|
1088
|
+
}
|
|
1089
|
+
//#endregion
|
|
993
1090
|
//#region src/runner/tasks.ts
|
|
994
1091
|
const isObject = (value) => typeof value === "object" && value !== null;
|
|
995
1092
|
/**
|
|
@@ -1081,6 +1178,8 @@ var CaptureRunner = class {
|
|
|
1081
1178
|
outputDir;
|
|
1082
1179
|
fileSystem;
|
|
1083
1180
|
now;
|
|
1181
|
+
prepare;
|
|
1182
|
+
explainUnreachable;
|
|
1084
1183
|
listeners = /* @__PURE__ */ new Set();
|
|
1085
1184
|
controller = new AbortController();
|
|
1086
1185
|
seq = 0;
|
|
@@ -1110,6 +1209,8 @@ var CaptureRunner = class {
|
|
|
1110
1209
|
this.fileSystem = options.fileSystem ?? options.screenshotTool.filesystem ?? new ScreenshotFileSystem(this.outputDir);
|
|
1111
1210
|
this.id = options.id ?? (0, node_crypto.randomUUID)();
|
|
1112
1211
|
this.now = options.now ?? (() => Date.now());
|
|
1212
|
+
this.prepare = options.prepare;
|
|
1213
|
+
this.explainUnreachable = options.explainUnreachable ?? (() => "Start it before capturing, or add a `webServer` entry to cappa.config.ts so cappa starts it for you.");
|
|
1113
1214
|
}
|
|
1114
1215
|
/** Subscribe to run events. Returns an unsubscribe function. */
|
|
1115
1216
|
on(listener) {
|
|
@@ -1198,6 +1299,10 @@ var CaptureRunner = class {
|
|
|
1198
1299
|
this.attachToolCaptureSink();
|
|
1199
1300
|
try {
|
|
1200
1301
|
try {
|
|
1302
|
+
if (this.prepare) {
|
|
1303
|
+
this.state = "discovering";
|
|
1304
|
+
await this.prepare((level, message) => this.log(level, message));
|
|
1305
|
+
}
|
|
1201
1306
|
if (request.clearActual ?? true) {
|
|
1202
1307
|
this.log("debug", `Cleaning output directory: ${this.outputDir}`);
|
|
1203
1308
|
this.fileSystem.clearActual();
|
|
@@ -1205,7 +1310,8 @@ var CaptureRunner = class {
|
|
|
1205
1310
|
}
|
|
1206
1311
|
const pluginTasks = await this.discover(request);
|
|
1207
1312
|
if (!this.controller.signal.aborted) await this.execute(pluginTasks);
|
|
1208
|
-
} catch (
|
|
1313
|
+
} catch (thrown) {
|
|
1314
|
+
const error = this.toUnreachableError(thrown) ?? thrown;
|
|
1209
1315
|
this.error = error;
|
|
1210
1316
|
this.state = "failed";
|
|
1211
1317
|
this.finishedAt = this.now();
|
|
@@ -1383,6 +1489,7 @@ var CaptureRunner = class {
|
|
|
1383
1489
|
}
|
|
1384
1490
|
const durationMs = this.now() - taskStart;
|
|
1385
1491
|
completedTasks++;
|
|
1492
|
+
result = this.explainTaskError(result);
|
|
1386
1493
|
const failed = didScreenshotFail(result);
|
|
1387
1494
|
const status = toTaskStatus(result);
|
|
1388
1495
|
const typedResult = result;
|
|
@@ -1421,6 +1528,36 @@ var CaptureRunner = class {
|
|
|
1421
1528
|
});
|
|
1422
1529
|
}
|
|
1423
1530
|
}
|
|
1531
|
+
/**
|
|
1532
|
+
* The message for a refused connection: where, and what to do about it.
|
|
1533
|
+
*
|
|
1534
|
+
* Identical for every task that hit the same server — no task id, no path —
|
|
1535
|
+
* so a report can collapse 300 of them into one line.
|
|
1536
|
+
*/
|
|
1537
|
+
unreachableMessage(origin) {
|
|
1538
|
+
return `Cannot reach ${origin ?? "the app under test"}: connection refused. ${this.explainUnreachable(origin)}`;
|
|
1539
|
+
}
|
|
1540
|
+
toUnreachableError(error) {
|
|
1541
|
+
const refused = findRefusedConnection(error);
|
|
1542
|
+
if (!refused) return;
|
|
1543
|
+
return new Error(this.unreachableMessage(refused.origin), { cause: error });
|
|
1544
|
+
}
|
|
1545
|
+
/**
|
|
1546
|
+
* Replace a plugin's refused-connection error with the explained one.
|
|
1547
|
+
*
|
|
1548
|
+
* Reads the result rather than asking the plugin, so third-party plugins get
|
|
1549
|
+
* the same message without an API change.
|
|
1550
|
+
*/
|
|
1551
|
+
explainTaskError(result) {
|
|
1552
|
+
const error = result?.error;
|
|
1553
|
+
if (error === void 0 || error === null) return result;
|
|
1554
|
+
const refused = findRefusedConnection(error);
|
|
1555
|
+
if (!refused) return result;
|
|
1556
|
+
return {
|
|
1557
|
+
...result,
|
|
1558
|
+
error: this.unreachableMessage(refused.origin)
|
|
1559
|
+
};
|
|
1560
|
+
}
|
|
1424
1561
|
async collectDeleted() {
|
|
1425
1562
|
if (!this.anyTasksRan) return;
|
|
1426
1563
|
try {
|
|
@@ -1857,6 +1994,7 @@ var ScreenshotTool = class {
|
|
|
1857
1994
|
const saveDiff = extras.saveDiffImage ?? false;
|
|
1858
1995
|
const diffFilename = extras.diffImageFilename ?? filename;
|
|
1859
1996
|
const diffOverride = extras.diff;
|
|
1997
|
+
await this.filesystem.removeDiffFiles(diffFilename);
|
|
1860
1998
|
if (!await this.filesystem.hasExpectedFile(filename)) {
|
|
1861
1999
|
this.logger.debug(`Expected image not found for ${filename}, taking screenshot`);
|
|
1862
2000
|
result.filepath = await this.takeScreenshot(page, filename, options);
|
|
@@ -2056,6 +2194,204 @@ var ScreenshotTool = class {
|
|
|
2056
2194
|
}
|
|
2057
2195
|
};
|
|
2058
2196
|
//#endregion
|
|
2197
|
+
//#region src/agent/paths.ts
|
|
2198
|
+
/**
|
|
2199
|
+
* Where agent review keeps its state, inside `outputDir`.
|
|
2200
|
+
*
|
|
2201
|
+
* Its own module so screenshot collection can read the report without
|
|
2202
|
+
* importing the review pipeline, which itself collects screenshots.
|
|
2203
|
+
*/
|
|
2204
|
+
const AGENT_DIRNAME = ".cappa-agent";
|
|
2205
|
+
/** Bumped only if `request.json` or `report.json` change incompatibly. */
|
|
2206
|
+
const AGENT_REPORT_VERSION = 1;
|
|
2207
|
+
const agentDir = (outputDir) => node_path.default.resolve(outputDir, AGENT_DIRNAME);
|
|
2208
|
+
const judgmentsRoot = (outputDir) => node_path.default.join(agentDir(outputDir), "judgments");
|
|
2209
|
+
const agentReportPath = (outputDir) => node_path.default.join(agentDir(outputDir), "report.json");
|
|
2210
|
+
//#endregion
|
|
2211
|
+
//#region src/agent/verdict.ts
|
|
2212
|
+
/**
|
|
2213
|
+
* What a reviewer — heuristic or agent — believes a changed screenshot is.
|
|
2214
|
+
*
|
|
2215
|
+
* `ambiguous` is only ever produced by the heuristic: it is the signal that
|
|
2216
|
+
* the change has to be looked at, and an agent's verdict must resolve it into
|
|
2217
|
+
* one of the other three.
|
|
2218
|
+
*/
|
|
2219
|
+
const VERDICT_LABELS = [
|
|
2220
|
+
"regression-likely",
|
|
2221
|
+
"intentional-likely",
|
|
2222
|
+
"noise-likely",
|
|
2223
|
+
"ambiguous"
|
|
2224
|
+
];
|
|
2225
|
+
/** The labels a judge may hand back — everything but `ambiguous`. */
|
|
2226
|
+
const JUDGED_LABELS = [
|
|
2227
|
+
"regression-likely",
|
|
2228
|
+
"intentional-likely",
|
|
2229
|
+
"noise-likely"
|
|
2230
|
+
];
|
|
2231
|
+
const ACTION_BY_LABEL = {
|
|
2232
|
+
"regression-likely": "investigate",
|
|
2233
|
+
"intentional-likely": "approve-if-intended",
|
|
2234
|
+
"noise-likely": "mask-or-approve",
|
|
2235
|
+
ambiguous: "investigate"
|
|
2236
|
+
};
|
|
2237
|
+
const isVerdictLabel = (value) => typeof value === "string" && VERDICT_LABELS.includes(value);
|
|
2238
|
+
const isJudgedLabel = (value) => typeof value === "string" && JUDGED_LABELS.includes(value);
|
|
2239
|
+
/**
|
|
2240
|
+
* Change types are normalised to kebab-case before they are compared.
|
|
2241
|
+
*
|
|
2242
|
+
* `@blazediff/interpret-native` reports `color-change` today but earlier
|
|
2243
|
+
* releases reported `ColorChange`; normalising keeps the heuristic working
|
|
2244
|
+
* across a diff-engine upgrade instead of silently degrading every screenshot
|
|
2245
|
+
* to `ambiguous`.
|
|
2246
|
+
*/
|
|
2247
|
+
const normalizeChangeType = (changeType) => changeType.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
|
|
2248
|
+
const normalizeSeverity = (severity) => (severity ?? "").toLowerCase();
|
|
2249
|
+
/** Structural: something appeared, vanished or was replaced. */
|
|
2250
|
+
const REGRESSIVE_TYPES = /* @__PURE__ */ new Set([
|
|
2251
|
+
"content-change",
|
|
2252
|
+
"addition",
|
|
2253
|
+
"deletion"
|
|
2254
|
+
]);
|
|
2255
|
+
/** Restyled or moved, with structure intact. */
|
|
2256
|
+
const RESTYLE_TYPES = /* @__PURE__ */ new Set(["color-change", "shift"]);
|
|
2257
|
+
const NOISE_TYPES = /* @__PURE__ */ new Set(["rendering-noise"]);
|
|
2258
|
+
const ELEVATED_SEVERITY = /* @__PURE__ */ new Set(["medium", "high"]);
|
|
2259
|
+
/** Below this share of the image, a low-severity change is not perceptible. */
|
|
2260
|
+
const SUB_PERCEPTUAL_PERCENT = .01;
|
|
2261
|
+
/** Mean region confidence above which a pure recolour is trusted. */
|
|
2262
|
+
const RECOLOR_CONFIDENCE = .7;
|
|
2263
|
+
const formatPercent = (percent) => {
|
|
2264
|
+
if (percent === void 0) return "?%";
|
|
2265
|
+
return percent >= .01 ? `${percent.toFixed(2)}%` : `${percent.toFixed(3)}%`;
|
|
2266
|
+
};
|
|
2267
|
+
const countByType = (regions) => {
|
|
2268
|
+
const counts = /* @__PURE__ */ new Map();
|
|
2269
|
+
for (const region of regions) {
|
|
2270
|
+
const type = normalizeChangeType(region.changeType);
|
|
2271
|
+
counts.set(type, (counts.get(type) ?? 0) + 1);
|
|
2272
|
+
}
|
|
2273
|
+
return counts;
|
|
2274
|
+
};
|
|
2275
|
+
const formatBreakdown = (counts) => [...counts].sort((a, b) => b[1] - a[1]).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2276
|
+
const largestRegion = (regions) => regions.reduce((best, region) => !best || region.pixelCount > best.pixelCount ? region : best, void 0);
|
|
2277
|
+
const meanConfidence = (regions) => regions.length === 0 ? 0 : regions.reduce((sum, region) => sum + (region.confidence ?? 0), 0) / regions.length;
|
|
2278
|
+
/**
|
|
2279
|
+
* A one-line description of a change, shaped so that the same kind of change
|
|
2280
|
+
* on different screenshots produces the same headline — which is what lets an
|
|
2281
|
+
* agent spot one shared cause (a footer timestamp, a theme toggle) across
|
|
2282
|
+
* dozens of screenshots without opening any of them.
|
|
2283
|
+
*/
|
|
2284
|
+
const buildHeadline = (input) => {
|
|
2285
|
+
if (input.differentSizes) return "image dimensions changed";
|
|
2286
|
+
const interpretation = input.interpretation;
|
|
2287
|
+
const percent = input.percentDifference ?? interpretation?.diffPercentage;
|
|
2288
|
+
if (!interpretation || interpretation.regions.length === 0) return `${(input.numDiffPixels ?? interpretation?.diffCount)?.toLocaleString("en-US") ?? "?"} px (${formatPercent(percent)}) - no region analysis`;
|
|
2289
|
+
const regions = interpretation.regions;
|
|
2290
|
+
const counts = countByType(regions);
|
|
2291
|
+
const position = largestRegion(regions)?.position;
|
|
2292
|
+
const at = position ? ` @ ${position}` : "";
|
|
2293
|
+
const severity = normalizeSeverity(interpretation.severity) || "?";
|
|
2294
|
+
if (regions.length === 1) return `1 ${[...counts.keys()][0]}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2295
|
+
return `${regions.length} regions: ${formatBreakdown(counts)}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2296
|
+
};
|
|
2297
|
+
const verdict = (label, headline, rationale) => ({
|
|
2298
|
+
label,
|
|
2299
|
+
headline,
|
|
2300
|
+
rationale,
|
|
2301
|
+
action: ACTION_BY_LABEL[label]
|
|
2302
|
+
});
|
|
2303
|
+
/**
|
|
2304
|
+
* Classify a changed screenshot from its diff interpretation alone.
|
|
2305
|
+
*
|
|
2306
|
+
* Deliberately conservative: only the cases the signals settle are labelled,
|
|
2307
|
+
* and everything else is `ambiguous` so that it reaches a judge who can look
|
|
2308
|
+
* at the pixels. A wrong `noise-likely` hides a regression; a wrong
|
|
2309
|
+
* `ambiguous` costs one look.
|
|
2310
|
+
*/
|
|
2311
|
+
const deriveVerdict = (input) => {
|
|
2312
|
+
const headline = buildHeadline(input);
|
|
2313
|
+
if (input.differentSizes) return verdict("ambiguous", headline, ["expected and actual have different dimensions — content likely grew or shrank", "could be an intended content change or a broken layout"]);
|
|
2314
|
+
const interpretation = input.interpretation;
|
|
2315
|
+
if (!interpretation || interpretation.regions.length === 0) return verdict("ambiguous", headline, ["pixels differ but no change regions were found"]);
|
|
2316
|
+
const regions = interpretation.regions;
|
|
2317
|
+
const types = regions.map((region) => normalizeChangeType(region.changeType));
|
|
2318
|
+
const severity = normalizeSeverity(interpretation.severity);
|
|
2319
|
+
const percent = input.percentDifference ?? interpretation.diffPercentage;
|
|
2320
|
+
const counts = countByType(regions);
|
|
2321
|
+
if (types.every((type) => NOISE_TYPES.has(type))) return verdict("noise-likely", headline, ["every region is classified as rendering noise"]);
|
|
2322
|
+
if (percent < .01 && severity === "low") return verdict("noise-likely", headline, [`less than ${SUB_PERCEPTUAL_PERCENT}% of the image differs (${formatPercent(percent)}) at low severity`, "sub-perceptual change"]);
|
|
2323
|
+
if (types.some((type) => REGRESSIVE_TYPES.has(type)) && ELEVATED_SEVERITY.has(severity)) {
|
|
2324
|
+
const structural = [...counts].filter(([type]) => REGRESSIVE_TYPES.has(type)).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2325
|
+
return verdict("regression-likely", headline, [`${severity} severity with structural changes (${structural})`, "content or layout changed, not just styling"]);
|
|
2326
|
+
}
|
|
2327
|
+
const allRecolor = types.every((type) => type === "color-change");
|
|
2328
|
+
if (allRecolor && meanConfidence(regions) > RECOLOR_CONFIDENCE) return verdict("intentional-likely", headline, [`${regions.length} confident color-change ${regions.length === 1 ? "region" : "regions"}`, "edge structure preserved — looks like a theming or palette change"]);
|
|
2329
|
+
if (!allRecolor && types.every((type) => RESTYLE_TYPES.has(type))) return verdict("intentional-likely", headline, ["every region is a shift or color change — content moved or was restyled, structure preserved"]);
|
|
2330
|
+
return verdict("ambiguous", headline, [`mix of change types (${formatBreakdown(counts)}) at ${severity || "unknown"} severity`, `${formatPercent(percent)} of the image differs`]);
|
|
2331
|
+
};
|
|
2332
|
+
//#endregion
|
|
2333
|
+
//#region src/agent/reviewIndex.ts
|
|
2334
|
+
/**
|
|
2335
|
+
* Read the review index, or nothing.
|
|
2336
|
+
*
|
|
2337
|
+
* Never throws: like the capture manifest, the report is an extra, and a
|
|
2338
|
+
* missing or hand-edited file must not break the screenshot listing.
|
|
2339
|
+
*/
|
|
2340
|
+
const readAgentReviewIndex = async (outputDir) => {
|
|
2341
|
+
let raw;
|
|
2342
|
+
try {
|
|
2343
|
+
raw = JSON.parse(await node_fs_promises.default.readFile(agentReportPath(outputDir), "utf8"));
|
|
2344
|
+
} catch {
|
|
2345
|
+
return;
|
|
2346
|
+
}
|
|
2347
|
+
const createdAt = typeof raw?.createdAt === "string" ? Date.parse(raw.createdAt) : NaN;
|
|
2348
|
+
if (raw?.version !== 1 || Number.isNaN(createdAt) || !Array.isArray(raw.entries)) return;
|
|
2349
|
+
const reviews = /* @__PURE__ */ new Map();
|
|
2350
|
+
for (const entry of raw.entries) {
|
|
2351
|
+
if (typeof entry !== "object" || entry === null) continue;
|
|
2352
|
+
const { name, category, verdict, pending } = entry;
|
|
2353
|
+
if (typeof name !== "string" || category !== "changed") continue;
|
|
2354
|
+
if (typeof verdict !== "object" || verdict === null) continue;
|
|
2355
|
+
const v = verdict;
|
|
2356
|
+
if (!isVerdictLabel(v.label) || typeof v.headline !== "string") continue;
|
|
2357
|
+
reviews.set(name, {
|
|
2358
|
+
label: v.label,
|
|
2359
|
+
headline: v.headline,
|
|
2360
|
+
rationale: Array.isArray(v.rationale) ? v.rationale.filter((line) => typeof line === "string") : [],
|
|
2361
|
+
action: v.action,
|
|
2362
|
+
source: v.source === "agent" ? "agent" : "heuristic",
|
|
2363
|
+
...typeof v.confidence === "number" ? { confidence: v.confidence } : {},
|
|
2364
|
+
pending: pending === true,
|
|
2365
|
+
reviewedAt: new Date(createdAt).toISOString()
|
|
2366
|
+
});
|
|
2367
|
+
}
|
|
2368
|
+
return {
|
|
2369
|
+
createdAt,
|
|
2370
|
+
reviews
|
|
2371
|
+
};
|
|
2372
|
+
};
|
|
2373
|
+
const modifiedAt = async (file) => {
|
|
2374
|
+
try {
|
|
2375
|
+
return (await node_fs_promises.default.stat(file)).mtimeMs;
|
|
2376
|
+
} catch {
|
|
2377
|
+
return Number.POSITIVE_INFINITY;
|
|
2378
|
+
}
|
|
2379
|
+
};
|
|
2380
|
+
/**
|
|
2381
|
+
* The review for a changed screenshot, if it is still about these images.
|
|
2382
|
+
*
|
|
2383
|
+
* A capture after the check rewrites `actual/`, an approval rewrites
|
|
2384
|
+
* `expected/`; either makes the verdict describe pixels that are gone. File
|
|
2385
|
+
* times are compared rather than content hashed because this runs on every
|
|
2386
|
+
* listing the review UI makes.
|
|
2387
|
+
*/
|
|
2388
|
+
const freshAgentReview = async (index, outputDir, screenshot) => {
|
|
2389
|
+
const review = index?.reviews.get(screenshot.name);
|
|
2390
|
+
if (!index || !review) return void 0;
|
|
2391
|
+
const [actual, expected] = await Promise.all([modifiedAt(node_path.default.resolve(outputDir, screenshot.actualPath)), modifiedAt(node_path.default.resolve(outputDir, screenshot.expectedPath))]);
|
|
2392
|
+
return actual <= index.createdAt && expected <= index.createdAt ? review : void 0;
|
|
2393
|
+
};
|
|
2394
|
+
//#endregion
|
|
2059
2395
|
//#region src/screenshots/groupScreenshots.ts
|
|
2060
2396
|
const groupScreenshots = async (actualScreenshots, expectedScreenshots, diffScreenshots, outputDir) => {
|
|
2061
2397
|
const screenshotRepresentations = [];
|
|
@@ -2125,23 +2461,431 @@ const listPngs = async (dir) => Array.fromAsync(await (0, node_fs_promises.glob)
|
|
|
2125
2461
|
*
|
|
2126
2462
|
* The capture manifest is folded in here so every consumer — the CLI, the
|
|
2127
2463
|
* server, the review UI — sees the same `taskId`, and so a screenshot captured
|
|
2128
|
-
* before manifests existed simply has none rather than a wrong one.
|
|
2464
|
+
* before manifests existed simply has none rather than a wrong one. The last
|
|
2465
|
+
* `cappa agent check` verdict is folded in the same way, as `review`, while it
|
|
2466
|
+
* still describes the images on disk.
|
|
2129
2467
|
*/
|
|
2130
2468
|
const collectScreenshots = async (outputDir) => {
|
|
2131
|
-
const [actualScreenshots, expectedScreenshots, diffScreenshots, manifest] = await Promise.all([
|
|
2469
|
+
const [actualScreenshots, expectedScreenshots, diffScreenshots, manifest, reviewIndex] = await Promise.all([
|
|
2132
2470
|
listPngs(node_path.default.resolve(outputDir, "actual")),
|
|
2133
2471
|
listPngs(node_path.default.resolve(outputDir, "expected")),
|
|
2134
2472
|
listPngs(node_path.default.resolve(outputDir, "diff")),
|
|
2135
|
-
readCaptureManifest(outputDir)
|
|
2473
|
+
readCaptureManifest(outputDir),
|
|
2474
|
+
readAgentReviewIndex(outputDir)
|
|
2136
2475
|
]);
|
|
2137
|
-
|
|
2476
|
+
const screenshots = await groupScreenshots(actualScreenshots, expectedScreenshots, diffScreenshots, outputDir);
|
|
2477
|
+
return Promise.all(screenshots.map(async (screenshot) => {
|
|
2138
2478
|
const origin = manifest.screenshots[screenshot.name];
|
|
2139
|
-
|
|
2479
|
+
const withOrigin = origin ? {
|
|
2140
2480
|
...screenshot,
|
|
2141
2481
|
taskId: origin.taskId,
|
|
2142
2482
|
plugin: origin.plugin
|
|
2143
2483
|
} : screenshot;
|
|
2484
|
+
if (withOrigin.category !== "changed" || !reviewIndex) return withOrigin;
|
|
2485
|
+
const review = await freshAgentReview(reviewIndex, outputDir, withOrigin);
|
|
2486
|
+
return review ? {
|
|
2487
|
+
...withOrigin,
|
|
2488
|
+
review
|
|
2489
|
+
} : withOrigin;
|
|
2490
|
+
}));
|
|
2491
|
+
};
|
|
2492
|
+
//#endregion
|
|
2493
|
+
//#region src/webServer/process.ts
|
|
2494
|
+
/** Grace period between SIGTERM and SIGKILL. */
|
|
2495
|
+
const DEFAULT_KILL_GRACE_MS = 5e3;
|
|
2496
|
+
/** How long to wait for the kernel to reap a SIGKILLed group. */
|
|
2497
|
+
const SIGKILL_WAIT_MS = 2e3;
|
|
2498
|
+
const isWindows = process.platform === "win32";
|
|
2499
|
+
/**
|
|
2500
|
+
* The last part of a process's output, kept in memory.
|
|
2501
|
+
*
|
|
2502
|
+
* Bounded by bytes rather than lines: a dev server that prints one enormous
|
|
2503
|
+
* line is no reason to hold on to all of it, and the tail exists to explain a
|
|
2504
|
+
* failure, not to be a log.
|
|
2505
|
+
*/
|
|
2506
|
+
var OutputTail = class {
|
|
2507
|
+
maxBytes;
|
|
2508
|
+
chunks = [];
|
|
2509
|
+
size = 0;
|
|
2510
|
+
constructor(maxBytes = 65536) {
|
|
2511
|
+
this.maxBytes = maxBytes;
|
|
2512
|
+
}
|
|
2513
|
+
push(chunk) {
|
|
2514
|
+
this.chunks.push(chunk);
|
|
2515
|
+
this.size += chunk.length;
|
|
2516
|
+
while (this.size > this.maxBytes && this.chunks.length > 1) this.size -= this.chunks.shift()?.length ?? 0;
|
|
2517
|
+
}
|
|
2518
|
+
/** The last `maxLines` non-empty lines. */
|
|
2519
|
+
lines(maxLines = 30) {
|
|
2520
|
+
return this.chunks.join("").split(/\r?\n/).filter((line) => line.trim() !== "").slice(-maxLines);
|
|
2521
|
+
}
|
|
2522
|
+
};
|
|
2523
|
+
/**
|
|
2524
|
+
* Process groups this process started and has not stopped yet.
|
|
2525
|
+
*
|
|
2526
|
+
* Exists for the one exit no `close()` covers: the process leaving without
|
|
2527
|
+
* shutting down. A server left running holds its port, and the next run would
|
|
2528
|
+
* silently *reuse* it — a stale build answering for the current one.
|
|
2529
|
+
*/
|
|
2530
|
+
const liveProcesses = /* @__PURE__ */ new Set();
|
|
2531
|
+
let exitHookInstalled = false;
|
|
2532
|
+
const installExitHook = () => {
|
|
2533
|
+
if (exitHookInstalled) return;
|
|
2534
|
+
exitHookInstalled = true;
|
|
2535
|
+
process.on("exit", () => {
|
|
2536
|
+
for (const child of liveProcesses) killTreeNow(child);
|
|
2537
|
+
liveProcesses.clear();
|
|
2538
|
+
});
|
|
2539
|
+
};
|
|
2540
|
+
const killTreeNow = (child) => {
|
|
2541
|
+
if (child.pid === void 0) return;
|
|
2542
|
+
try {
|
|
2543
|
+
if (isWindows) (0, node_child_process.execFileSync)("taskkill", [
|
|
2544
|
+
"/pid",
|
|
2545
|
+
String(child.pid),
|
|
2546
|
+
"/T",
|
|
2547
|
+
"/F"
|
|
2548
|
+
], { stdio: "ignore" });
|
|
2549
|
+
else process.kill(-child.pid, "SIGKILL");
|
|
2550
|
+
} catch {}
|
|
2551
|
+
};
|
|
2552
|
+
/**
|
|
2553
|
+
* Start `command` through a shell, as the leader of its own process group.
|
|
2554
|
+
*
|
|
2555
|
+
* A group, because the command is rarely the server itself: `pnpm storybook`
|
|
2556
|
+
* is pnpm, running a shell, running storybook, running workers. Killing only
|
|
2557
|
+
* the direct child would leave the rest holding the port.
|
|
2558
|
+
*
|
|
2559
|
+
* Output is buffered, never written anywhere unless `onOutput` asks for it —
|
|
2560
|
+
* `cappa capture --json` must stay a single clean document on stdout.
|
|
2561
|
+
*/
|
|
2562
|
+
function spawnServerProcess(command, options) {
|
|
2563
|
+
const child = (0, node_child_process.spawn)(command, {
|
|
2564
|
+
cwd: options.cwd,
|
|
2565
|
+
env: {
|
|
2566
|
+
...process.env,
|
|
2567
|
+
...options.env
|
|
2568
|
+
},
|
|
2569
|
+
shell: true,
|
|
2570
|
+
detached: !isWindows,
|
|
2571
|
+
stdio: [
|
|
2572
|
+
"ignore",
|
|
2573
|
+
"pipe",
|
|
2574
|
+
"pipe"
|
|
2575
|
+
],
|
|
2576
|
+
windowsHide: true
|
|
2144
2577
|
});
|
|
2578
|
+
const output = new OutputTail();
|
|
2579
|
+
const onData = (data) => {
|
|
2580
|
+
const chunk = data.toString();
|
|
2581
|
+
output.push(chunk);
|
|
2582
|
+
options.onOutput?.(chunk);
|
|
2583
|
+
};
|
|
2584
|
+
child.stdout?.on("data", onData);
|
|
2585
|
+
child.stderr?.on("data", onData);
|
|
2586
|
+
liveProcesses.add(child);
|
|
2587
|
+
installExitHook();
|
|
2588
|
+
let exit;
|
|
2589
|
+
const exited = new Promise((resolve) => {
|
|
2590
|
+
const settle = (value) => {
|
|
2591
|
+
if (exit) return;
|
|
2592
|
+
exit = value;
|
|
2593
|
+
resolve(value);
|
|
2594
|
+
};
|
|
2595
|
+
child.once("exit", (code, signal) => settle({
|
|
2596
|
+
code,
|
|
2597
|
+
signal
|
|
2598
|
+
}));
|
|
2599
|
+
child.once("error", (error) => {
|
|
2600
|
+
output.push(`${error.message}\n`);
|
|
2601
|
+
settle({
|
|
2602
|
+
code: null,
|
|
2603
|
+
signal: null
|
|
2604
|
+
});
|
|
2605
|
+
});
|
|
2606
|
+
});
|
|
2607
|
+
let killing;
|
|
2608
|
+
return {
|
|
2609
|
+
get pid() {
|
|
2610
|
+
return child.pid;
|
|
2611
|
+
},
|
|
2612
|
+
exited,
|
|
2613
|
+
get exit() {
|
|
2614
|
+
return exit;
|
|
2615
|
+
},
|
|
2616
|
+
output,
|
|
2617
|
+
kill(graceMs = DEFAULT_KILL_GRACE_MS) {
|
|
2618
|
+
killing ??= killProcessTree(child, exited, graceMs).finally(() => {
|
|
2619
|
+
liveProcesses.delete(child);
|
|
2620
|
+
});
|
|
2621
|
+
return killing;
|
|
2622
|
+
}
|
|
2623
|
+
};
|
|
2624
|
+
}
|
|
2625
|
+
/** True while any process in the group led by `pid` is alive. */
|
|
2626
|
+
const groupAlive = (pid) => {
|
|
2627
|
+
try {
|
|
2628
|
+
process.kill(-pid, 0);
|
|
2629
|
+
return true;
|
|
2630
|
+
} catch (error) {
|
|
2631
|
+
return error.code === "EPERM";
|
|
2632
|
+
}
|
|
2633
|
+
};
|
|
2634
|
+
const delay = (ms) => new Promise((resolve) => {
|
|
2635
|
+
setTimeout(resolve, ms);
|
|
2636
|
+
});
|
|
2637
|
+
/**
|
|
2638
|
+
* SIGTERM the whole group, then SIGKILL whatever is left after `graceMs`.
|
|
2639
|
+
*
|
|
2640
|
+
* Waits on the group, not the child: the shell can exit at once while the
|
|
2641
|
+
* server it started is still shutting down — and still holding the port.
|
|
2642
|
+
*/
|
|
2643
|
+
async function killProcessTree(child, exited, graceMs) {
|
|
2644
|
+
const pid = child.pid;
|
|
2645
|
+
if (pid === void 0) return;
|
|
2646
|
+
if (isWindows) {
|
|
2647
|
+
await new Promise((resolve) => {
|
|
2648
|
+
(0, node_child_process.execFile)("taskkill", [
|
|
2649
|
+
"/pid",
|
|
2650
|
+
String(pid),
|
|
2651
|
+
"/T",
|
|
2652
|
+
"/F"
|
|
2653
|
+
], () => resolve());
|
|
2654
|
+
});
|
|
2655
|
+
await exited;
|
|
2656
|
+
return;
|
|
2657
|
+
}
|
|
2658
|
+
if (!groupAlive(pid)) return;
|
|
2659
|
+
try {
|
|
2660
|
+
process.kill(-pid, "SIGTERM");
|
|
2661
|
+
} catch {
|
|
2662
|
+
return;
|
|
2663
|
+
}
|
|
2664
|
+
const deadline = Date.now() + graceMs;
|
|
2665
|
+
while (groupAlive(pid) && Date.now() < deadline) await delay(50);
|
|
2666
|
+
if (groupAlive(pid)) {
|
|
2667
|
+
try {
|
|
2668
|
+
process.kill(-pid, "SIGKILL");
|
|
2669
|
+
} catch {}
|
|
2670
|
+
const killDeadline = Date.now() + SIGKILL_WAIT_MS;
|
|
2671
|
+
while (groupAlive(pid) && Date.now() < killDeadline) await delay(20);
|
|
2672
|
+
}
|
|
2673
|
+
await exited;
|
|
2674
|
+
}
|
|
2675
|
+
//#endregion
|
|
2676
|
+
//#region src/webServer/readiness.ts
|
|
2677
|
+
const PROBE_TIMEOUT_MS = 5e3;
|
|
2678
|
+
/** Delays between probes; the last one repeats. */
|
|
2679
|
+
const POLL_DELAYS_MS = [
|
|
2680
|
+
100,
|
|
2681
|
+
250,
|
|
2682
|
+
500,
|
|
2683
|
+
1e3
|
|
2684
|
+
];
|
|
2685
|
+
/**
|
|
2686
|
+
* Whether `url` answers with a 2xx or 3xx status.
|
|
2687
|
+
*
|
|
2688
|
+
* Redirects are not followed: a dev server that redirects `/` to `/login` is
|
|
2689
|
+
* up, and following it would make readiness depend on a page cappa never asked
|
|
2690
|
+
* about.
|
|
2691
|
+
*/
|
|
2692
|
+
async function isUrlReady(url, timeoutMs = PROBE_TIMEOUT_MS) {
|
|
2693
|
+
try {
|
|
2694
|
+
const response = await fetch(url, {
|
|
2695
|
+
redirect: "manual",
|
|
2696
|
+
signal: AbortSignal.timeout(Math.max(1, timeoutMs))
|
|
2697
|
+
});
|
|
2698
|
+
await response.body?.cancel().catch(() => {});
|
|
2699
|
+
return response.status >= 200 && response.status < 400;
|
|
2700
|
+
} catch {
|
|
2701
|
+
return false;
|
|
2702
|
+
}
|
|
2703
|
+
}
|
|
2704
|
+
/** Poll `url` until it is ready, the deadline passes, or `abort` settles. */
|
|
2705
|
+
async function waitForUrl(url, options) {
|
|
2706
|
+
const probe = options.probe ?? isUrlReady;
|
|
2707
|
+
const deadline = Date.now() + options.timeoutMs;
|
|
2708
|
+
let aborted = false;
|
|
2709
|
+
const abort = (options.abort ?? new Promise(() => {})).then(() => {
|
|
2710
|
+
aborted = true;
|
|
2711
|
+
}, () => {
|
|
2712
|
+
aborted = true;
|
|
2713
|
+
});
|
|
2714
|
+
for (let attempt = 0;; attempt++) {
|
|
2715
|
+
const remaining = deadline - Date.now();
|
|
2716
|
+
if (aborted) return "aborted";
|
|
2717
|
+
if (remaining <= 0) return "timeout";
|
|
2718
|
+
if (await probe(url, Math.min(remaining, PROBE_TIMEOUT_MS))) return "ready";
|
|
2719
|
+
const wait = Math.min(POLL_DELAYS_MS[Math.min(attempt, POLL_DELAYS_MS.length - 1)] ?? 1e3, Math.max(0, deadline - Date.now()));
|
|
2720
|
+
let timer;
|
|
2721
|
+
await Promise.race([new Promise((resolve) => {
|
|
2722
|
+
timer = setTimeout(resolve, wait);
|
|
2723
|
+
}), abort]);
|
|
2724
|
+
clearTimeout(timer);
|
|
2725
|
+
}
|
|
2726
|
+
}
|
|
2727
|
+
//#endregion
|
|
2728
|
+
//#region src/webServer/WebServerPool.ts
|
|
2729
|
+
/** A web server could not be started, or would not become ready. */
|
|
2730
|
+
var WebServerError = class extends Error {
|
|
2731
|
+
constructor(message) {
|
|
2732
|
+
super(message);
|
|
2733
|
+
this.name = "WebServerError";
|
|
2734
|
+
}
|
|
2735
|
+
};
|
|
2736
|
+
const describeExit = (exit) => exit.signal ? `signal ${exit.signal}` : exit.code === null ? "an error" : `code ${exit.code}`;
|
|
2737
|
+
const formatTail = (command, lines) => lines.length === 0 ? `\`${command}\` printed nothing.` : `Last output of \`${command}\`:\n${lines.map((line) => ` ${line}`).join("\n")}`;
|
|
2738
|
+
const seconds = (ms) => `${Math.round(ms / 100) / 10}s`;
|
|
2739
|
+
/**
|
|
2740
|
+
* The servers a config's `webServer` describes, started on demand.
|
|
2741
|
+
*
|
|
2742
|
+
* Lazy and restartable rather than started once: the owning engine calls
|
|
2743
|
+
* `ensure` before every run and `stop` when the browser goes idle, so a review
|
|
2744
|
+
* session that sits unused gives the port back, and the next capture starts —
|
|
2745
|
+
* and rebuilds — the app again, picking up whatever changed in between.
|
|
2746
|
+
*
|
|
2747
|
+
* Every `ensure` says which way it went, because "reusing a server" and
|
|
2748
|
+
* "started one" look identical in screenshots, and a stale build, another
|
|
2749
|
+
* branch or another project on the same port is otherwise very hard to spot.
|
|
2750
|
+
*/
|
|
2751
|
+
var WebServerPool = class {
|
|
2752
|
+
entries;
|
|
2753
|
+
options;
|
|
2754
|
+
probe;
|
|
2755
|
+
/** Bumped by `stop`, so a start in flight knows it was cancelled. */
|
|
2756
|
+
generation = 0;
|
|
2757
|
+
constructor(options) {
|
|
2758
|
+
this.options = options;
|
|
2759
|
+
this.probe = options.probe ?? isUrlReady;
|
|
2760
|
+
this.entries = options.servers.map((config) => ({
|
|
2761
|
+
config,
|
|
2762
|
+
state: { kind: "idle" },
|
|
2763
|
+
starting: null
|
|
2764
|
+
}));
|
|
2765
|
+
}
|
|
2766
|
+
/** Whether the config has any `webServer` entry at all. */
|
|
2767
|
+
get configured() {
|
|
2768
|
+
return this.entries.length > 0;
|
|
2769
|
+
}
|
|
2770
|
+
/** Number of processes cappa started that are still running. */
|
|
2771
|
+
get running() {
|
|
2772
|
+
return this.entries.filter((entry) => entry.state.kind === "running" && !entry.state.process.exit).length;
|
|
2773
|
+
}
|
|
2774
|
+
/**
|
|
2775
|
+
* Make every server ready, in parallel, starting the ones that are not.
|
|
2776
|
+
*
|
|
2777
|
+
* All of them, even for a run that only captures one plugin's tasks: nothing
|
|
2778
|
+
* maps a plugin to a server, and guessing would start the wrong one.
|
|
2779
|
+
*/
|
|
2780
|
+
async ensure(log = this.defaultLog) {
|
|
2781
|
+
if (this.entries.length === 0) return;
|
|
2782
|
+
const errors = (await Promise.allSettled(this.entries.map((entry) => this.ensureEntry(entry, log)))).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
|
|
2783
|
+
if (errors.length === 1) throw errors[0];
|
|
2784
|
+
if (errors.length > 1) throw new WebServerError(errors.map((error) => error instanceof Error ? error.message : error).join("\n\n"));
|
|
2785
|
+
}
|
|
2786
|
+
/**
|
|
2787
|
+
* Stop every server cappa started. A reused server is left alone — cappa did
|
|
2788
|
+
* not start it, so it is not cappa's to stop.
|
|
2789
|
+
*/
|
|
2790
|
+
async stop() {
|
|
2791
|
+
this.generation += 1;
|
|
2792
|
+
await Promise.all(this.entries.map(async (entry) => {
|
|
2793
|
+
const state = entry.state;
|
|
2794
|
+
entry.state = { kind: "idle" };
|
|
2795
|
+
if (state.kind === "running") await state.process.kill(this.options.killGraceMs);
|
|
2796
|
+
}));
|
|
2797
|
+
}
|
|
2798
|
+
/**
|
|
2799
|
+
* What to tell the user about a connection refused at `origin`.
|
|
2800
|
+
*
|
|
2801
|
+
* Always an actionable sentence: the bare "ECONNREFUSED" it replaces is the
|
|
2802
|
+
* single most common capture failure, and says nothing about what to do.
|
|
2803
|
+
*/
|
|
2804
|
+
explainUnreachable(origin) {
|
|
2805
|
+
if (this.entries.length === 0) return NO_WEB_SERVER_HINT;
|
|
2806
|
+
const matching = origin ? this.entries.find((entry) => sameServer(entry.config.url, origin)) : void 0;
|
|
2807
|
+
const crashed = matching?.state.kind === "exited" ? matching : this.entries.find((entry) => entry.state.kind === "exited");
|
|
2808
|
+
if (crashed && crashed.state.kind === "exited") return `The web server \`${crashed.config.command}\` exited with ${describeExit(crashed.state.exit)} during the run; it is started again on the next run.\n${formatTail(crashed.config.command, crashed.state.tail)}`;
|
|
2809
|
+
if (origin && !matching) return `No \`webServer\` entry serves ${origin} (configured: ${this.entries.map((entry) => entry.config.url).join(", ")}). Check that the plugin's URL matches \`webServer.url\`.`;
|
|
2810
|
+
return "The configured `webServer` was ready, but stopped accepting connections.";
|
|
2811
|
+
}
|
|
2812
|
+
defaultLog = (level, message) => {
|
|
2813
|
+
this.options.log?.(level, message);
|
|
2814
|
+
};
|
|
2815
|
+
ensureEntry(entry, log) {
|
|
2816
|
+
entry.starting ??= this.startEntry(entry, log).finally(() => {
|
|
2817
|
+
entry.starting = null;
|
|
2818
|
+
});
|
|
2819
|
+
return entry.starting;
|
|
2820
|
+
}
|
|
2821
|
+
async startEntry(entry, log) {
|
|
2822
|
+
const { command, url, timeout, cwd, env, reuseExistingServer } = entry.config;
|
|
2823
|
+
const previous = entry.state;
|
|
2824
|
+
if (previous.kind === "running" && !previous.process.exit) {
|
|
2825
|
+
log("info", `Using \`${command}\` at ${url}, started earlier by cappa`);
|
|
2826
|
+
return;
|
|
2827
|
+
}
|
|
2828
|
+
if (previous.kind === "exited") log("warn", `\`${command}\` exited with ${describeExit(previous.exit)} after the last run; starting it again`);
|
|
2829
|
+
if (await this.probe(url, Math.min(timeout, 5e3))) {
|
|
2830
|
+
if (reuseExistingServer) {
|
|
2831
|
+
entry.state = { kind: "reused" };
|
|
2832
|
+
log("info", `Reusing server at ${url} — \`${command}\` was not run`);
|
|
2833
|
+
return;
|
|
2834
|
+
}
|
|
2835
|
+
throw new WebServerError(`${url} is already in use, and \`webServer.reuseExistingServer\` is false. Stop whatever is serving it, or allow reusing it.`);
|
|
2836
|
+
}
|
|
2837
|
+
const generation = this.generation;
|
|
2838
|
+
const startedAt = Date.now();
|
|
2839
|
+
log("info", `Starting \`${command}\` — waiting up to ${seconds(timeout)} for ${url}`);
|
|
2840
|
+
const child = (this.options.spawn ?? spawnServerProcess)(command, {
|
|
2841
|
+
cwd,
|
|
2842
|
+
env,
|
|
2843
|
+
onOutput: this.options.onOutput ? (chunk) => this.options.onOutput?.(entry.config, chunk) : void 0
|
|
2844
|
+
});
|
|
2845
|
+
entry.state = {
|
|
2846
|
+
kind: "running",
|
|
2847
|
+
process: child
|
|
2848
|
+
};
|
|
2849
|
+
const result = await waitForUrl(url, {
|
|
2850
|
+
timeoutMs: timeout,
|
|
2851
|
+
abort: child.exited,
|
|
2852
|
+
probe: this.probe
|
|
2853
|
+
});
|
|
2854
|
+
if (generation !== this.generation) {
|
|
2855
|
+
await child.kill(this.options.killGraceMs);
|
|
2856
|
+
throw new WebServerError(`\`${command}\` was stopped before ${url} was ready.`);
|
|
2857
|
+
}
|
|
2858
|
+
if (result === "ready") {
|
|
2859
|
+
this.watchForCrash(entry, child);
|
|
2860
|
+
log("success", `Started \`${command}\` — ${url} ready in ${seconds(Date.now() - startedAt)}`);
|
|
2861
|
+
return;
|
|
2862
|
+
}
|
|
2863
|
+
entry.state = { kind: "idle" };
|
|
2864
|
+
if (result === "aborted") {
|
|
2865
|
+
const exit = await child.exited;
|
|
2866
|
+
throw new WebServerError(`\`${command}\` exited with ${describeExit(exit)} before ${url} was ready.\n${formatTail(command, child.output.lines())}`);
|
|
2867
|
+
}
|
|
2868
|
+
await child.kill(this.options.killGraceMs);
|
|
2869
|
+
throw new WebServerError(`Timed out after ${seconds(timeout)} waiting for \`${command}\` to serve ${url}. If it needs longer — a build step, say — raise \`webServer.timeout\`.\n${formatTail(command, child.output.lines())}`);
|
|
2870
|
+
}
|
|
2871
|
+
/**
|
|
2872
|
+
* Record a server that exits on its own, so the failures it causes can say
|
|
2873
|
+
* why and the next run starts it again. Deliberately no restart loop: a
|
|
2874
|
+
* server that keeps crashing should fail loudly, not flap.
|
|
2875
|
+
*/
|
|
2876
|
+
watchForCrash(entry, child) {
|
|
2877
|
+
child.exited.then((exit) => {
|
|
2878
|
+
const state = entry.state;
|
|
2879
|
+
if (state.kind !== "running" || state.process !== child) return;
|
|
2880
|
+
entry.state = {
|
|
2881
|
+
kind: "exited",
|
|
2882
|
+
exit,
|
|
2883
|
+
tail: child.output.lines()
|
|
2884
|
+
};
|
|
2885
|
+
child.kill(this.options.killGraceMs);
|
|
2886
|
+
this.defaultLog("error", `\`${entry.config.command}\` exited with ${describeExit(exit)} while cappa was using it.`);
|
|
2887
|
+
});
|
|
2888
|
+
}
|
|
2145
2889
|
};
|
|
2146
2890
|
//#endregion
|
|
2147
2891
|
//#region src/engine/RunStore.ts
|
|
@@ -2309,6 +3053,7 @@ const isWatchInProgressError = (error) => hasCode(error, ENGINE_ERROR_CODES.watc
|
|
|
2309
3053
|
var WarmBrowser = class {
|
|
2310
3054
|
createTool;
|
|
2311
3055
|
idleTimeoutMs;
|
|
3056
|
+
onShutdown;
|
|
2312
3057
|
tool = null;
|
|
2313
3058
|
idleTimer = null;
|
|
2314
3059
|
inUse = false;
|
|
@@ -2320,6 +3065,7 @@ var WarmBrowser = class {
|
|
|
2320
3065
|
constructor(options) {
|
|
2321
3066
|
this.createTool = options.create;
|
|
2322
3067
|
this.idleTimeoutMs = options.idleTimeoutMs ?? 3e5;
|
|
3068
|
+
this.onShutdown = options.onShutdown;
|
|
2323
3069
|
}
|
|
2324
3070
|
/** True while a browser process is alive. */
|
|
2325
3071
|
get isWarm() {
|
|
@@ -2391,7 +3137,11 @@ var WarmBrowser = class {
|
|
|
2391
3137
|
const tool = this.tool;
|
|
2392
3138
|
this.tool = null;
|
|
2393
3139
|
this.inUse = false;
|
|
2394
|
-
|
|
3140
|
+
try {
|
|
3141
|
+
if (tool) await tool.close();
|
|
3142
|
+
} finally {
|
|
3143
|
+
await this.onShutdown?.();
|
|
3144
|
+
}
|
|
2395
3145
|
});
|
|
2396
3146
|
}
|
|
2397
3147
|
startIdleTimer() {
|
|
@@ -2416,7 +3166,11 @@ var WarmBrowser = class {
|
|
|
2416
3166
|
if (this.inUse || this.closed || this.holds > 0) return;
|
|
2417
3167
|
const tool = this.tool;
|
|
2418
3168
|
this.tool = null;
|
|
2419
|
-
|
|
3169
|
+
try {
|
|
3170
|
+
if (tool) await tool.close();
|
|
3171
|
+
} finally {
|
|
3172
|
+
await this.onShutdown?.();
|
|
3173
|
+
}
|
|
2420
3174
|
});
|
|
2421
3175
|
}
|
|
2422
3176
|
serialize(work) {
|
|
@@ -2780,6 +3534,28 @@ const toRelative = (cwd, changedPath) => {
|
|
|
2780
3534
|
};
|
|
2781
3535
|
//#endregion
|
|
2782
3536
|
//#region src/engine/LocalEngine.ts
|
|
3537
|
+
const defaultLog = (level, message) => {
|
|
3538
|
+
try {
|
|
3539
|
+
(0, _cappa_logger.getLogger)()[level](message);
|
|
3540
|
+
} catch {}
|
|
3541
|
+
};
|
|
3542
|
+
/**
|
|
3543
|
+
* Stream a web server's output live at debug level. Buffered regardless: the
|
|
3544
|
+
* tail is what explains a server that failed to start.
|
|
3545
|
+
*
|
|
3546
|
+
* To stderr, never stdout — `capture --json` owns stdout.
|
|
3547
|
+
*/
|
|
3548
|
+
const streamOutputAtDebug = (server, chunk) => {
|
|
3549
|
+
let level = 0;
|
|
3550
|
+
try {
|
|
3551
|
+
level = (0, _cappa_logger.getLogger)().level;
|
|
3552
|
+
} catch {
|
|
3553
|
+
return;
|
|
3554
|
+
}
|
|
3555
|
+
if (level < 4) return;
|
|
3556
|
+
const prefix = `[webServer ${server.url}] `;
|
|
3557
|
+
process.stderr.write(chunk.split(/(?<=\n)/).map((line) => prefix + line).join(""));
|
|
3558
|
+
};
|
|
2783
3559
|
/**
|
|
2784
3560
|
* `CaptureEngine` backed by an in-process Playwright browser.
|
|
2785
3561
|
*
|
|
@@ -2797,6 +3573,7 @@ var LocalEngine = class {
|
|
|
2797
3573
|
fileSystem;
|
|
2798
3574
|
browser;
|
|
2799
3575
|
runs;
|
|
3576
|
+
webServers;
|
|
2800
3577
|
/**
|
|
2801
3578
|
* Set synchronously the moment a run is claimed, before any `await`, so two
|
|
2802
3579
|
* concurrent `startRun` calls cannot both pass the check and then fight over
|
|
@@ -2824,9 +3601,16 @@ var LocalEngine = class {
|
|
|
2824
3601
|
this.plugins = options.plugins;
|
|
2825
3602
|
this.fileSystem = new ScreenshotFileSystem(options.outputDir);
|
|
2826
3603
|
this.runs = new RunStore(options.runStore);
|
|
3604
|
+
this.webServers = new WebServerPool({
|
|
3605
|
+
servers: options.webServer ?? [],
|
|
3606
|
+
log: defaultLog,
|
|
3607
|
+
onOutput: streamOutputAtDebug,
|
|
3608
|
+
...options.webServerPool
|
|
3609
|
+
});
|
|
2827
3610
|
this.browser = new WarmBrowser({
|
|
2828
3611
|
create: options.createScreenshotTool ?? (() => this.buildTool()),
|
|
2829
|
-
idleTimeoutMs: options.browserIdleTimeoutMs
|
|
3612
|
+
idleTimeoutMs: options.browserIdleTimeoutMs,
|
|
3613
|
+
onShutdown: () => this.webServers.stop()
|
|
2830
3614
|
});
|
|
2831
3615
|
}
|
|
2832
3616
|
buildTool() {
|
|
@@ -2876,7 +3660,9 @@ var LocalEngine = class {
|
|
|
2876
3660
|
screenshotTool: await this.browser.acquire(),
|
|
2877
3661
|
plugins: this.plugins,
|
|
2878
3662
|
outputDir: this.options.outputDir,
|
|
2879
|
-
fileSystem: this.fileSystem
|
|
3663
|
+
fileSystem: this.fileSystem,
|
|
3664
|
+
prepare: (log) => this.webServers.ensure(log),
|
|
3665
|
+
explainUnreachable: (origin) => this.webServers.explainUnreachable(origin)
|
|
2880
3666
|
});
|
|
2881
3667
|
const finish = () => {
|
|
2882
3668
|
if (this.activeRunId !== runner.id) return;
|
|
@@ -3014,7 +3800,11 @@ var LocalEngine = class {
|
|
|
3014
3800
|
this.closed = true;
|
|
3015
3801
|
await this.endWatch("engine-closed");
|
|
3016
3802
|
(this.activeRunId ? this.runs.getRunner(this.activeRunId) : void 0)?.abort();
|
|
3017
|
-
|
|
3803
|
+
try {
|
|
3804
|
+
await this.browser.close();
|
|
3805
|
+
} finally {
|
|
3806
|
+
await this.webServers.stop();
|
|
3807
|
+
}
|
|
3018
3808
|
}
|
|
3019
3809
|
async endWatch(reason) {
|
|
3020
3810
|
const session = this.watchSession;
|
|
@@ -3087,6 +3877,7 @@ var LocalEngine = class {
|
|
|
3087
3877
|
async discoverTargets() {
|
|
3088
3878
|
const tool = await this.browser.acquire();
|
|
3089
3879
|
try {
|
|
3880
|
+
await this.webServers.ensure();
|
|
3090
3881
|
const discovered = await Promise.all(this.plugins.map(async (plugin) => {
|
|
3091
3882
|
const tasks = await plugin.discover(tool);
|
|
3092
3883
|
return {
|
|
@@ -3182,49 +3973,749 @@ var FsScreenshotStore = class {
|
|
|
3182
3973
|
}
|
|
3183
3974
|
};
|
|
3184
3975
|
//#endregion
|
|
3976
|
+
//#region src/agent/tiles.ts
|
|
3977
|
+
const LOCATOR_MAX_WIDTH = 400;
|
|
3978
|
+
const LOCATOR_MAX_HEIGHT = 1200;
|
|
3979
|
+
const GUTTER = 12;
|
|
3980
|
+
const ROW_GUTTER = 16;
|
|
3981
|
+
const LABEL_HEIGHT = 18;
|
|
3982
|
+
const BACKGROUND = {
|
|
3983
|
+
r: 128,
|
|
3984
|
+
g: 128,
|
|
3985
|
+
b: 128
|
|
3986
|
+
};
|
|
3987
|
+
const escapeXml = (text) => text.replace(/[<>&"]/g, (c) => `&#${c.charCodeAt(0)};`);
|
|
3988
|
+
/** A caption strip, so a row reads as "#2 expected | #2 actual" at a glance. */
|
|
3989
|
+
const label = (text, width) => Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${LABEL_HEIGHT}"><rect width="100%" height="100%" fill="#222"/><text x="4" y="13" font-family="sans-serif" font-size="12" fill="#fff">${escapeXml(text)}</text></svg>`);
|
|
3990
|
+
const padAndClamp = (bbox, padding, width, height) => {
|
|
3991
|
+
const padX = typeof padding === "number" ? padding : padding.x;
|
|
3992
|
+
const padY = typeof padding === "number" ? padding : padding.y;
|
|
3993
|
+
const x = Math.max(0, Math.floor(bbox.x - padX));
|
|
3994
|
+
const y = Math.max(0, Math.floor(bbox.y - padY));
|
|
3995
|
+
const right = Math.min(width, Math.ceil(bbox.x + bbox.width + padX));
|
|
3996
|
+
const bottom = Math.min(height, Math.ceil(bbox.y + bbox.height + padY));
|
|
3997
|
+
return {
|
|
3998
|
+
x,
|
|
3999
|
+
y,
|
|
4000
|
+
width: Math.max(1, right - x),
|
|
4001
|
+
height: Math.max(1, bottom - y)
|
|
4002
|
+
};
|
|
4003
|
+
};
|
|
4004
|
+
const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
|
|
4005
|
+
/**
|
|
4006
|
+
* Context kept around a region: proportional to its size, within bounds.
|
|
4007
|
+
*
|
|
4008
|
+
* A fixed margin is too tight for small regions — a changed letter cropped
|
|
4009
|
+
* with 24px around it says nothing about whether a button label got
|
|
4010
|
+
* truncated — and wasteful for large ones.
|
|
4011
|
+
*/
|
|
4012
|
+
const contextPadding = (bbox, minimum) => ({
|
|
4013
|
+
x: clamp(bbox.width, minimum * 2, 160),
|
|
4014
|
+
y: clamp(bbox.height, minimum, 96)
|
|
4015
|
+
});
|
|
4016
|
+
/** Scale that fits `width`x`height` into the bounds without upscaling. */
|
|
4017
|
+
const fitScale = (width, height, maxWidth, maxHeight) => Math.min(1, maxWidth / width, maxHeight / height);
|
|
4018
|
+
const readSize$1 = async (file) => {
|
|
4019
|
+
const { width, height } = await (0, sharp.default)(file).metadata();
|
|
4020
|
+
if (!width || !height) throw new Error(`Unable to read image dimensions: ${file}`);
|
|
4021
|
+
return {
|
|
4022
|
+
width,
|
|
4023
|
+
height
|
|
4024
|
+
};
|
|
4025
|
+
};
|
|
4026
|
+
const renderCrop = async (file, box, scale) => {
|
|
4027
|
+
const crop = (0, sharp.default)(file).extract({
|
|
4028
|
+
left: box.x,
|
|
4029
|
+
top: box.y,
|
|
4030
|
+
width: box.width,
|
|
4031
|
+
height: box.height
|
|
4032
|
+
});
|
|
4033
|
+
if (scale < 1) crop.resize(Math.max(1, Math.round(box.width * scale)), Math.max(1, Math.round(box.height * scale)));
|
|
4034
|
+
return crop.png().toBuffer();
|
|
4035
|
+
};
|
|
4036
|
+
const renderRegions = async (options, width, height) => {
|
|
4037
|
+
const padding = options.padding ?? 24;
|
|
4038
|
+
const maxCropWidth = options.maxCropWidth ?? 640;
|
|
4039
|
+
const regions = options.regions.slice(0, options.maxRegions ?? 8);
|
|
4040
|
+
if (regions.length === 0) return void 0;
|
|
4041
|
+
const rows = await Promise.all(regions.map(async (region) => {
|
|
4042
|
+
const box = padAndClamp(region, contextPadding(region, padding), width, height);
|
|
4043
|
+
const scale = Math.min(1, maxCropWidth / box.width);
|
|
4044
|
+
const [expected, actual] = await Promise.all([renderCrop(options.expectedPath, box, scale), renderCrop(options.actualPath, box, scale)]);
|
|
4045
|
+
return {
|
|
4046
|
+
expected,
|
|
4047
|
+
actual,
|
|
4048
|
+
width: Math.max(1, Math.round(box.width * scale)),
|
|
4049
|
+
height: Math.max(1, Math.round(box.height * scale))
|
|
4050
|
+
};
|
|
4051
|
+
}));
|
|
4052
|
+
const columnWidth = (row) => Math.max(row.width, 96);
|
|
4053
|
+
const canvasWidth = Math.max(...rows.map((row) => columnWidth(row) * 2 + GUTTER));
|
|
4054
|
+
const canvasHeight = rows.reduce((sum, row) => sum + LABEL_HEIGHT + row.height, 0) + ROW_GUTTER * (rows.length - 1);
|
|
4055
|
+
const composites = [];
|
|
4056
|
+
let top = 0;
|
|
4057
|
+
rows.forEach((row, index) => {
|
|
4058
|
+
const column = columnWidth(row);
|
|
4059
|
+
const right = column + GUTTER;
|
|
4060
|
+
composites.push({
|
|
4061
|
+
input: label(`#${index + 1} expected`, column),
|
|
4062
|
+
left: 0,
|
|
4063
|
+
top
|
|
4064
|
+
}, {
|
|
4065
|
+
input: label(`#${index + 1} actual`, column),
|
|
4066
|
+
left: right,
|
|
4067
|
+
top
|
|
4068
|
+
}, {
|
|
4069
|
+
input: row.expected,
|
|
4070
|
+
left: 0,
|
|
4071
|
+
top: top + LABEL_HEIGHT
|
|
4072
|
+
}, {
|
|
4073
|
+
input: row.actual,
|
|
4074
|
+
left: right,
|
|
4075
|
+
top: top + LABEL_HEIGHT
|
|
4076
|
+
});
|
|
4077
|
+
top += LABEL_HEIGHT + row.height + ROW_GUTTER;
|
|
4078
|
+
});
|
|
4079
|
+
const file = node_path.default.join(options.outDir, "regions.png");
|
|
4080
|
+
await (0, sharp.default)({ create: {
|
|
4081
|
+
width: canvasWidth,
|
|
4082
|
+
height: canvasHeight,
|
|
4083
|
+
channels: 3,
|
|
4084
|
+
background: BACKGROUND
|
|
4085
|
+
} }).composite(composites).png().toFile(file);
|
|
4086
|
+
return {
|
|
4087
|
+
file,
|
|
4088
|
+
count: rows.length
|
|
4089
|
+
};
|
|
4090
|
+
};
|
|
4091
|
+
const renderLocator = async (options, width, height) => {
|
|
4092
|
+
const scale = fitScale(width, height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT);
|
|
4093
|
+
const locatorWidth = Math.max(1, Math.round(width * scale));
|
|
4094
|
+
const locatorHeight = Math.max(1, Math.round(height * scale));
|
|
4095
|
+
const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${locatorWidth}" height="${locatorHeight}">${options.regions.map((region, index) => {
|
|
4096
|
+
const x = Math.round(region.x * scale);
|
|
4097
|
+
const y = Math.round(region.y * scale);
|
|
4098
|
+
return `<rect x="${x}" y="${y}" width="${Math.max(2, Math.round(region.width * scale))}" height="${Math.max(2, Math.round(region.height * scale))}" fill="none" stroke="red" stroke-width="2"/><text x="${x + 2}" y="${Math.max(12, y - 3)}" font-family="sans-serif" font-size="12" font-weight="bold" fill="red" stroke="#fff" stroke-width="3" paint-order="stroke">${index + 1}</text>`;
|
|
4099
|
+
}).join("")}</svg>`;
|
|
4100
|
+
const file = node_path.default.join(options.outDir, "locator.png");
|
|
4101
|
+
await (0, sharp.default)(options.diffPath ?? options.actualPath).resize(locatorWidth, locatorHeight, { fit: "fill" }).composite([{
|
|
4102
|
+
input: Buffer.from(svg),
|
|
4103
|
+
left: 0,
|
|
4104
|
+
top: 0
|
|
4105
|
+
}]).png().toFile(file);
|
|
4106
|
+
return file;
|
|
4107
|
+
};
|
|
4108
|
+
/**
|
|
4109
|
+
* Write `locator.png` and `regions.png` into `outDir`.
|
|
4110
|
+
*
|
|
4111
|
+
* Expected and actual must have the same dimensions — region boxes are only
|
|
4112
|
+
* meaningful when both images share a coordinate space. Use
|
|
4113
|
+
* {@link renderOverview} when they do not.
|
|
4114
|
+
*/
|
|
4115
|
+
const renderJudgmentTiles = async (options) => {
|
|
4116
|
+
const { width, height } = await readSize$1(options.actualPath);
|
|
4117
|
+
const [regions, locator] = await Promise.all([renderRegions(options, width, height), renderLocator(options, width, height)]);
|
|
4118
|
+
return {
|
|
4119
|
+
locator,
|
|
4120
|
+
regions: regions?.file,
|
|
4121
|
+
renderedRegions: regions?.count ?? 0
|
|
4122
|
+
};
|
|
4123
|
+
};
|
|
4124
|
+
/**
|
|
4125
|
+
* Write `overview.png`: expected and actual, scaled down side by side.
|
|
4126
|
+
*
|
|
4127
|
+
* For screenshots whose dimensions changed, where no region can be located,
|
|
4128
|
+
* this is what the judge looks at instead of two full-size images.
|
|
4129
|
+
*/
|
|
4130
|
+
const renderOverview = async (options) => {
|
|
4131
|
+
const [expectedSize, actualSize] = await Promise.all([readSize$1(options.expectedPath), readSize$1(options.actualPath)]);
|
|
4132
|
+
const scale = Math.min(fitScale(expectedSize.width, expectedSize.height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT), fitScale(actualSize.width, actualSize.height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT));
|
|
4133
|
+
const scaled = (size) => ({
|
|
4134
|
+
width: Math.max(1, Math.round(size.width * scale)),
|
|
4135
|
+
height: Math.max(1, Math.round(size.height * scale))
|
|
4136
|
+
});
|
|
4137
|
+
const expected = scaled(expectedSize);
|
|
4138
|
+
const actual = scaled(actualSize);
|
|
4139
|
+
const [expectedBuffer, actualBuffer] = await Promise.all([(0, sharp.default)(options.expectedPath).resize(expected.width, expected.height, { fit: "fill" }).png().toBuffer(), (0, sharp.default)(options.actualPath).resize(actual.width, actual.height, { fit: "fill" }).png().toBuffer()]);
|
|
4140
|
+
const file = node_path.default.join(options.outDir, "overview.png");
|
|
4141
|
+
await (0, sharp.default)({ create: {
|
|
4142
|
+
width: expected.width + GUTTER + actual.width,
|
|
4143
|
+
height: LABEL_HEIGHT + Math.max(expected.height, actual.height),
|
|
4144
|
+
channels: 3,
|
|
4145
|
+
background: BACKGROUND
|
|
4146
|
+
} }).composite([
|
|
4147
|
+
{
|
|
4148
|
+
input: label(`expected ${expectedSize.width}x${expectedSize.height}`, expected.width),
|
|
4149
|
+
left: 0,
|
|
4150
|
+
top: 0
|
|
4151
|
+
},
|
|
4152
|
+
{
|
|
4153
|
+
input: label(`actual ${actualSize.width}x${actualSize.height}`, actual.width),
|
|
4154
|
+
left: expected.width + GUTTER,
|
|
4155
|
+
top: 0
|
|
4156
|
+
},
|
|
4157
|
+
{
|
|
4158
|
+
input: expectedBuffer,
|
|
4159
|
+
left: 0,
|
|
4160
|
+
top: LABEL_HEIGHT
|
|
4161
|
+
},
|
|
4162
|
+
{
|
|
4163
|
+
input: actualBuffer,
|
|
4164
|
+
left: expected.width + GUTTER,
|
|
4165
|
+
top: LABEL_HEIGHT
|
|
4166
|
+
}
|
|
4167
|
+
]).png().toFile(file);
|
|
4168
|
+
return file;
|
|
4169
|
+
};
|
|
4170
|
+
//#endregion
|
|
4171
|
+
//#region src/agent/review.ts
|
|
4172
|
+
/**
|
|
4173
|
+
* Agent review: turn the screenshots on disk into something a coding agent
|
|
4174
|
+
* can judge cheaply, and fold its judgments back in.
|
|
4175
|
+
*
|
|
4176
|
+
* Nothing here captures. It reads `actual/`, `expected/` and `diff/` as the
|
|
4177
|
+
* last `cappa capture` left them, so it is safe to run repeatedly — a re-run
|
|
4178
|
+
* is how an agent's verdicts are applied, and a re-capture invalidates them
|
|
4179
|
+
* automatically because every judgment is tied to a fingerprint of the two
|
|
4180
|
+
* images it was made about.
|
|
4181
|
+
*
|
|
4182
|
+
* Layout, all inside `<outputDir>/.cappa-agent/` (dot-prefixed, so neither
|
|
4183
|
+
* screenshot collection nor the review server's static handler touch it):
|
|
4184
|
+
*
|
|
4185
|
+
* ```
|
|
4186
|
+
* report.json full report of the last check
|
|
4187
|
+
* judgments/<name>/request.json what to judge and where the evidence is
|
|
4188
|
+
* judgments/<name>/locator.png thumbnail with every region outlined
|
|
4189
|
+
* judgments/<name>/regions.png [expected | actual] crop per region
|
|
4190
|
+
* judgments/<name>/overview.png instead of the two above when sizes differ
|
|
4191
|
+
* judgments/<name>/verdict.json written by the judge
|
|
4192
|
+
* ```
|
|
4193
|
+
*/
|
|
4194
|
+
const REQUEST_FILE = "request.json";
|
|
4195
|
+
const VERDICT_FILE = "verdict.json";
|
|
4196
|
+
const JUDGMENT_FILES = [
|
|
4197
|
+
REQUEST_FILE,
|
|
4198
|
+
VERDICT_FILE,
|
|
4199
|
+
"locator.png",
|
|
4200
|
+
"regions.png",
|
|
4201
|
+
"overview.png"
|
|
4202
|
+
];
|
|
4203
|
+
const JUDGE_MODES = [
|
|
4204
|
+
"ambiguous",
|
|
4205
|
+
"all",
|
|
4206
|
+
"none"
|
|
4207
|
+
];
|
|
4208
|
+
/**
|
|
4209
|
+
* The directory holding a screenshot's judgment.
|
|
4210
|
+
*
|
|
4211
|
+
* Screenshot names are relative paths (`example/button/primary`), so they map
|
|
4212
|
+
* onto nested directories directly; anything that would resolve outside the
|
|
4213
|
+
* judgments root is refused rather than written.
|
|
4214
|
+
*/
|
|
4215
|
+
const judgmentDir = (outputDir, name) => {
|
|
4216
|
+
const root = judgmentsRoot(outputDir);
|
|
4217
|
+
const dir = node_path.default.resolve(root, name);
|
|
4218
|
+
const relative = node_path.default.relative(root, dir);
|
|
4219
|
+
if (!relative || relative.startsWith("..") || node_path.default.isAbsolute(relative)) throw new Error(`Invalid screenshot name for a judgment: ${name}`);
|
|
4220
|
+
return dir;
|
|
4221
|
+
};
|
|
4222
|
+
const exists = async (file) => {
|
|
4223
|
+
try {
|
|
4224
|
+
await node_fs_promises.default.access(file);
|
|
4225
|
+
return true;
|
|
4226
|
+
} catch {
|
|
4227
|
+
return false;
|
|
4228
|
+
}
|
|
4229
|
+
};
|
|
4230
|
+
const readJson = async (file) => {
|
|
4231
|
+
try {
|
|
4232
|
+
return JSON.parse(await node_fs_promises.default.readFile(file, "utf8"));
|
|
4233
|
+
} catch {
|
|
4234
|
+
return;
|
|
4235
|
+
}
|
|
4236
|
+
};
|
|
4237
|
+
const writeJson = async (file, value) => {
|
|
4238
|
+
await node_fs_promises.default.mkdir(node_path.default.dirname(file), { recursive: true });
|
|
4239
|
+
await node_fs_promises.default.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
|
|
4240
|
+
};
|
|
4241
|
+
/** Ties a judgment to the exact pair of images it was made about. */
|
|
4242
|
+
const fingerprintImages = async (expectedPath, actualPath) => {
|
|
4243
|
+
const [expected, actual] = await Promise.all([node_fs_promises.default.readFile(expectedPath), node_fs_promises.default.readFile(actualPath)]);
|
|
4244
|
+
return (0, node_crypto.createHash)("sha256").update(expected).update("\0").update(actual).digest("hex");
|
|
4245
|
+
};
|
|
4246
|
+
/**
|
|
4247
|
+
* Read a judge's verdict, accepting both the nested shape blazediff uses
|
|
4248
|
+
* (`{ verdict: { label, headline, rationale }, confidence }`) and a flat one
|
|
4249
|
+
* (`{ label, headline, rationale, confidence }`) — a judge that writes either
|
|
4250
|
+
* should not have its work thrown away over nesting.
|
|
4251
|
+
*/
|
|
4252
|
+
const parseAgentVerdict = (raw) => {
|
|
4253
|
+
if (typeof raw !== "object" || raw === null) return {
|
|
4254
|
+
ok: false,
|
|
4255
|
+
error: "verdict.json is not a JSON object"
|
|
4256
|
+
};
|
|
4257
|
+
const outer = raw;
|
|
4258
|
+
const inner = typeof outer.verdict === "object" && outer.verdict !== null ? outer.verdict : outer;
|
|
4259
|
+
const label = inner.label;
|
|
4260
|
+
if (!isJudgedLabel(label)) return {
|
|
4261
|
+
ok: false,
|
|
4262
|
+
error: `label must be one of regression-likely, intentional-likely, noise-likely (got ${JSON.stringify(label)})`
|
|
4263
|
+
};
|
|
4264
|
+
const headline = typeof inner.headline === "string" && inner.headline.trim() ? inner.headline.trim() : void 0;
|
|
4265
|
+
if (!headline) return {
|
|
4266
|
+
ok: false,
|
|
4267
|
+
error: "headline must be a non-empty string"
|
|
4268
|
+
};
|
|
4269
|
+
const toLines = (value) => Array.isArray(value) ? value.filter((line) => typeof line === "string") : typeof value === "string" && value.trim() ? [value.trim()] : [];
|
|
4270
|
+
const rationale = [...toLines(inner.rationale)];
|
|
4271
|
+
if (inner !== outer) rationale.push(...toLines(outer.rationale));
|
|
4272
|
+
const rawConfidence = outer.confidence ?? inner.confidence;
|
|
4273
|
+
const confidence = typeof rawConfidence === "number" && Number.isFinite(rawConfidence) ? Math.min(1, Math.max(0, rawConfidence)) : void 0;
|
|
4274
|
+
return {
|
|
4275
|
+
ok: true,
|
|
4276
|
+
label,
|
|
4277
|
+
headline,
|
|
4278
|
+
rationale,
|
|
4279
|
+
...confidence !== void 0 ? { confidence } : {}
|
|
4280
|
+
};
|
|
4281
|
+
};
|
|
4282
|
+
const readSize = async (file) => {
|
|
4283
|
+
const { width = 0, height = 0 } = await (0, sharp.default)(file).metadata();
|
|
4284
|
+
return {
|
|
4285
|
+
width,
|
|
4286
|
+
height
|
|
4287
|
+
};
|
|
4288
|
+
};
|
|
4289
|
+
const toAgentRegions = (regions) => [...regions].sort((a, b) => b.pixelCount - a.pixelCount).map((region, index) => ({
|
|
4290
|
+
index: index + 1,
|
|
4291
|
+
bbox: {
|
|
4292
|
+
x: region.bbox.x,
|
|
4293
|
+
y: region.bbox.y,
|
|
4294
|
+
width: region.bbox.width,
|
|
4295
|
+
height: region.bbox.height
|
|
4296
|
+
},
|
|
4297
|
+
pixelCount: region.pixelCount,
|
|
4298
|
+
percentage: region.percentage,
|
|
4299
|
+
position: region.position,
|
|
4300
|
+
shape: region.shape,
|
|
4301
|
+
changeType: normalizeChangeType(region.changeType),
|
|
4302
|
+
confidence: region.confidence
|
|
4303
|
+
}));
|
|
4304
|
+
/**
|
|
4305
|
+
* The interpretation a capture already persisted, or a fresh one.
|
|
4306
|
+
*
|
|
4307
|
+
* `diff.interpret` is off by default, so most changed screenshots arrive
|
|
4308
|
+
* without one; computing it here means agent review works on any project
|
|
4309
|
+
* rather than only on those that opted into interpretation at capture time.
|
|
4310
|
+
*/
|
|
4311
|
+
const interpretationFor = async (screenshot, expectedPath, actualPath, diff) => {
|
|
4312
|
+
if (screenshot.diffMeta?.interpretation) return screenshot.diffMeta.interpretation;
|
|
4313
|
+
const pixel = diff && diff.type !== "gmsd" ? diff : void 0;
|
|
4314
|
+
try {
|
|
4315
|
+
return await (0, _blazediff_interpret_native.interpret)(expectedPath, actualPath, void 0, {
|
|
4316
|
+
source: "pixel",
|
|
4317
|
+
threshold: pixel?.threshold,
|
|
4318
|
+
antialiasing: pixel?.includeAA ?? false
|
|
4319
|
+
});
|
|
4320
|
+
} catch {
|
|
4321
|
+
return;
|
|
4322
|
+
}
|
|
4323
|
+
};
|
|
4324
|
+
const JUDGE_INSTRUCTIONS = [
|
|
4325
|
+
"Read locator.png and regions.png together. locator.png outlines every region (numbered) on a thumbnail; regions.png stacks one [expected | actual] row per region, in `regions` order.",
|
|
4326
|
+
"Open overview.png when it exists instead — the image dimensions changed, so no regions could be located.",
|
|
4327
|
+
"Only open paths.expected / paths.actual / paths.diff (full size) when a change clearly continues outside its crop.",
|
|
4328
|
+
"Write verdict.json next to this file, or run `cappa agent judge <name> --label <label> --headline <text>`."
|
|
4329
|
+
];
|
|
4330
|
+
const VERDICT_SCHEMA = {
|
|
4331
|
+
label: "regression-likely | intentional-likely | noise-likely",
|
|
4332
|
+
headline: "one line describing what changed",
|
|
4333
|
+
rationale: ["short reasons"],
|
|
4334
|
+
confidence: "0..1"
|
|
4335
|
+
};
|
|
4336
|
+
const analyseChanged = async (screenshot, options, createdAt) => {
|
|
4337
|
+
const { outputDir } = options;
|
|
4338
|
+
const expectedPath = node_path.default.resolve(outputDir, screenshot.expectedPath);
|
|
4339
|
+
const actualPath = node_path.default.resolve(outputDir, screenshot.actualPath);
|
|
4340
|
+
const diffPath = node_path.default.resolve(outputDir, screenshot.diffPath);
|
|
4341
|
+
const [expectedSize, actualSize, diffExists] = await Promise.all([
|
|
4342
|
+
readSize(expectedPath),
|
|
4343
|
+
readSize(actualPath),
|
|
4344
|
+
exists(diffPath)
|
|
4345
|
+
]);
|
|
4346
|
+
const differentSizes = expectedSize.width !== actualSize.width || expectedSize.height !== actualSize.height;
|
|
4347
|
+
const interpretation = differentSizes ? void 0 : await interpretationFor(screenshot, expectedPath, actualPath, options.diff);
|
|
4348
|
+
const percentDifference = screenshot.diffMeta?.percentDifference ?? interpretation?.diffPercentage;
|
|
4349
|
+
const numDiffPixels = screenshot.diffMeta?.numDiffPixels ?? interpretation?.diffCount;
|
|
4350
|
+
const regions = toAgentRegions(interpretation?.regions ?? []);
|
|
4351
|
+
const heuristic = deriveVerdict({
|
|
4352
|
+
percentDifference,
|
|
4353
|
+
numDiffPixels,
|
|
4354
|
+
interpretation,
|
|
4355
|
+
differentSizes
|
|
4356
|
+
});
|
|
4357
|
+
const entry = {
|
|
4358
|
+
name: screenshot.name,
|
|
4359
|
+
category: "changed",
|
|
4360
|
+
...screenshot.taskId ? {
|
|
4361
|
+
taskId: screenshot.taskId,
|
|
4362
|
+
plugin: screenshot.plugin
|
|
4363
|
+
} : {},
|
|
4364
|
+
paths: {
|
|
4365
|
+
expected: expectedPath,
|
|
4366
|
+
actual: actualPath,
|
|
4367
|
+
...diffExists ? { diff: diffPath } : {}
|
|
4368
|
+
},
|
|
4369
|
+
percentDifference,
|
|
4370
|
+
numDiffPixels,
|
|
4371
|
+
dimensions: {
|
|
4372
|
+
expected: expectedSize,
|
|
4373
|
+
actual: actualSize
|
|
4374
|
+
},
|
|
4375
|
+
severity: interpretation?.severity?.toLowerCase(),
|
|
4376
|
+
summary: interpretation?.summary,
|
|
4377
|
+
regions,
|
|
4378
|
+
heuristic,
|
|
4379
|
+
verdict: {
|
|
4380
|
+
...heuristic,
|
|
4381
|
+
source: "heuristic"
|
|
4382
|
+
},
|
|
4383
|
+
pending: false
|
|
4384
|
+
};
|
|
4385
|
+
const dir = judgmentDir(outputDir, screenshot.name);
|
|
4386
|
+
const requestPath = node_path.default.join(dir, REQUEST_FILE);
|
|
4387
|
+
const verdictPath = node_path.default.join(dir, VERDICT_FILE);
|
|
4388
|
+
if (!(options.judge === "all" || options.judge === "ambiguous" && heuristic.label === "ambiguous" || await exists(requestPath))) return entry;
|
|
4389
|
+
const fingerprint = await fingerprintImages(expectedPath, actualPath);
|
|
4390
|
+
const previous = await readJson(requestPath);
|
|
4391
|
+
if (previous && previous.fingerprint !== fingerprint) await clearJudgmentFiles(dir);
|
|
4392
|
+
await node_fs_promises.default.mkdir(dir, { recursive: true });
|
|
4393
|
+
const judgment = {
|
|
4394
|
+
dir,
|
|
4395
|
+
request: requestPath,
|
|
4396
|
+
verdict: verdictPath
|
|
4397
|
+
};
|
|
4398
|
+
if (differentSizes) judgment.overview = await renderOverview({
|
|
4399
|
+
expectedPath,
|
|
4400
|
+
actualPath,
|
|
4401
|
+
outDir: dir
|
|
4402
|
+
});
|
|
4403
|
+
else {
|
|
4404
|
+
const tiles = await renderJudgmentTiles({
|
|
4405
|
+
expectedPath,
|
|
4406
|
+
actualPath,
|
|
4407
|
+
diffPath: diffExists ? diffPath : void 0,
|
|
4408
|
+
regions: regions.map((region) => region.bbox),
|
|
4409
|
+
outDir: dir,
|
|
4410
|
+
maxRegions: options.maxTileRegions
|
|
4411
|
+
});
|
|
4412
|
+
if (tiles.locator) judgment.locator = tiles.locator;
|
|
4413
|
+
if (tiles.regions) judgment.regions = tiles.regions;
|
|
4414
|
+
}
|
|
4415
|
+
entry.judgment = judgment;
|
|
4416
|
+
await writeJson(requestPath, {
|
|
4417
|
+
version: 1,
|
|
4418
|
+
name: entry.name,
|
|
4419
|
+
taskId: entry.taskId,
|
|
4420
|
+
plugin: entry.plugin,
|
|
4421
|
+
fingerprint,
|
|
4422
|
+
createdAt,
|
|
4423
|
+
instructions: JUDGE_INSTRUCTIONS,
|
|
4424
|
+
verdictSchema: VERDICT_SCHEMA,
|
|
4425
|
+
heuristic,
|
|
4426
|
+
percentDifference,
|
|
4427
|
+
numDiffPixels,
|
|
4428
|
+
dimensions: entry.dimensions,
|
|
4429
|
+
severity: entry.severity,
|
|
4430
|
+
summary: entry.summary,
|
|
4431
|
+
regions,
|
|
4432
|
+
paths: {
|
|
4433
|
+
locator: judgment.locator,
|
|
4434
|
+
regions: judgment.regions,
|
|
4435
|
+
overview: judgment.overview,
|
|
4436
|
+
expected: expectedPath,
|
|
4437
|
+
actual: actualPath,
|
|
4438
|
+
diff: entry.paths.diff,
|
|
4439
|
+
verdict: verdictPath
|
|
4440
|
+
}
|
|
4441
|
+
});
|
|
4442
|
+
if (!await exists(verdictPath)) {
|
|
4443
|
+
entry.pending = true;
|
|
4444
|
+
return entry;
|
|
4445
|
+
}
|
|
4446
|
+
const parsed = parseAgentVerdict(await readJson(verdictPath));
|
|
4447
|
+
if (!parsed.ok) {
|
|
4448
|
+
entry.pending = true;
|
|
4449
|
+
entry.verdictError = parsed.error;
|
|
4450
|
+
return entry;
|
|
4451
|
+
}
|
|
4452
|
+
entry.verdict = {
|
|
4453
|
+
label: parsed.label,
|
|
4454
|
+
headline: parsed.headline,
|
|
4455
|
+
rationale: parsed.rationale,
|
|
4456
|
+
action: ACTION_BY_LABEL[parsed.label],
|
|
4457
|
+
source: "agent",
|
|
4458
|
+
...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
|
|
4459
|
+
};
|
|
4460
|
+
return entry;
|
|
4461
|
+
};
|
|
4462
|
+
const clearJudgmentFiles = async (dir) => {
|
|
4463
|
+
await Promise.all(JUDGMENT_FILES.map((file) => node_fs_promises.default.rm(node_path.default.join(dir, file), { force: true })));
|
|
4464
|
+
};
|
|
4465
|
+
/**
|
|
4466
|
+
* Remove a screenshot's judgment — after it was approved, or because it is no
|
|
4467
|
+
* longer changed. Only the judgment's own files go: a directory can also be
|
|
4468
|
+
* the parent of another screenshot's judgment (`button` and `button/primary`).
|
|
4469
|
+
*/
|
|
4470
|
+
const clearJudgment = async (outputDir, name) => {
|
|
4471
|
+
const dir = judgmentDir(outputDir, name);
|
|
4472
|
+
await clearJudgmentFiles(dir);
|
|
4473
|
+
await removeEmptyDirs(dir, judgmentsRoot(outputDir));
|
|
4474
|
+
};
|
|
4475
|
+
/** Remove `dir` and its parents up to (excluding) `root` while empty. */
|
|
4476
|
+
const removeEmptyDirs = async (dir, root) => {
|
|
4477
|
+
let current = dir;
|
|
4478
|
+
while (current !== root && current.startsWith(root)) {
|
|
4479
|
+
try {
|
|
4480
|
+
await node_fs_promises.default.rmdir(current);
|
|
4481
|
+
} catch {
|
|
4482
|
+
return;
|
|
4483
|
+
}
|
|
4484
|
+
current = node_path.default.dirname(current);
|
|
4485
|
+
}
|
|
4486
|
+
};
|
|
4487
|
+
const listRequestDirs = async (root) => {
|
|
4488
|
+
if (!await exists(root)) return [];
|
|
4489
|
+
return (await Array.fromAsync(node_fs_promises.default.glob(`**/${REQUEST_FILE}`, { cwd: root }))).map((file) => node_path.default.resolve(root, node_path.default.dirname(file)));
|
|
4490
|
+
};
|
|
4491
|
+
/** Drop judgments for screenshots that no longer need one. */
|
|
4492
|
+
const pruneJudgments = async (outputDir, keep) => {
|
|
4493
|
+
const root = judgmentsRoot(outputDir);
|
|
4494
|
+
for (const dir of await listRequestDirs(root)) {
|
|
4495
|
+
if (keep.has(dir)) continue;
|
|
4496
|
+
await clearJudgmentFiles(dir);
|
|
4497
|
+
await removeEmptyDirs(dir, root);
|
|
4498
|
+
}
|
|
4499
|
+
};
|
|
4500
|
+
/**
|
|
4501
|
+
* Analyse every non-passing screenshot, write judgment requests for the ones
|
|
4502
|
+
* that need a judge, apply any verdicts already written, and persist the
|
|
4503
|
+
* full report to `<outputDir>/.cappa-agent/report.json`.
|
|
4504
|
+
*/
|
|
4505
|
+
const runAgentCheck = async (options) => {
|
|
4506
|
+
const outputDir = node_path.default.resolve(options.outputDir);
|
|
4507
|
+
const judge = options.judge ?? "ambiguous";
|
|
4508
|
+
const createdAt = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
|
|
4509
|
+
const screenshots = await collectScreenshots(outputDir);
|
|
4510
|
+
await node_fs_promises.default.mkdir(agentDir(outputDir), { recursive: true });
|
|
4511
|
+
await node_fs_promises.default.writeFile(node_path.default.join(agentDir(outputDir), ".gitignore"), "*\n");
|
|
4512
|
+
const changed = screenshots.filter((s) => s.category === "changed");
|
|
4513
|
+
const changedEntries = await mapWithConcurrency(options.concurrency ?? 4, changed, (screenshot) => analyseChanged(screenshot, {
|
|
4514
|
+
...options,
|
|
4515
|
+
outputDir,
|
|
4516
|
+
judge
|
|
4517
|
+
}, createdAt));
|
|
4518
|
+
await pruneJudgments(outputDir, new Set(changedEntries.flatMap((entry) => entry.judgment ? [entry.judgment.dir] : [])));
|
|
4519
|
+
const otherEntries = screenshots.flatMap((s) => {
|
|
4520
|
+
if (s.category === "new") return [{
|
|
4521
|
+
name: s.name,
|
|
4522
|
+
category: "new",
|
|
4523
|
+
...s.taskId ? {
|
|
4524
|
+
taskId: s.taskId,
|
|
4525
|
+
plugin: s.plugin
|
|
4526
|
+
} : {},
|
|
4527
|
+
paths: { actual: node_path.default.resolve(outputDir, s.actualPath) },
|
|
4528
|
+
pending: false
|
|
4529
|
+
}];
|
|
4530
|
+
if (s.category === "deleted") return [{
|
|
4531
|
+
name: s.name,
|
|
4532
|
+
category: "deleted",
|
|
4533
|
+
paths: { expected: node_path.default.resolve(outputDir, s.expectedPath) },
|
|
4534
|
+
pending: false
|
|
4535
|
+
}];
|
|
4536
|
+
return [];
|
|
4537
|
+
});
|
|
4538
|
+
const entries = [...changedEntries, ...otherEntries];
|
|
4539
|
+
const count = (category) => screenshots.filter((s) => s.category === category).length;
|
|
4540
|
+
const report = {
|
|
4541
|
+
version: 1,
|
|
4542
|
+
createdAt,
|
|
4543
|
+
outputDir,
|
|
4544
|
+
reportPath: agentReportPath(outputDir),
|
|
4545
|
+
judge,
|
|
4546
|
+
totals: {
|
|
4547
|
+
total: screenshots.length,
|
|
4548
|
+
passed: count("passed"),
|
|
4549
|
+
changed: count("changed"),
|
|
4550
|
+
new: count("new"),
|
|
4551
|
+
deleted: count("deleted"),
|
|
4552
|
+
pendingJudgments: entries.filter((entry) => entry.pending).length
|
|
4553
|
+
},
|
|
4554
|
+
entries
|
|
4555
|
+
};
|
|
4556
|
+
await writeJson(report.reportPath, report);
|
|
4557
|
+
return report;
|
|
4558
|
+
};
|
|
4559
|
+
/** Read the report the last {@link runAgentCheck} wrote, if any. */
|
|
4560
|
+
const readAgentReport = async (outputDir) => {
|
|
4561
|
+
const raw = await readJson(agentReportPath(outputDir));
|
|
4562
|
+
return raw?.version === 1 ? raw : void 0;
|
|
4563
|
+
};
|
|
4564
|
+
/**
|
|
4565
|
+
* The report as an agent should first see it: one line of state per
|
|
4566
|
+
* screenshot, with the detail left in `report.json` and the judgment
|
|
4567
|
+
* requests for when it is actually needed.
|
|
4568
|
+
*/
|
|
4569
|
+
const toSlimAgentReport = (report) => ({
|
|
4570
|
+
reportPath: report.reportPath,
|
|
4571
|
+
...report.totals,
|
|
4572
|
+
results: report.entries.map((entry) => ({
|
|
4573
|
+
name: entry.name,
|
|
4574
|
+
category: entry.category,
|
|
4575
|
+
...entry.verdict ? { verdict: {
|
|
4576
|
+
label: entry.verdict.label,
|
|
4577
|
+
headline: entry.verdict.headline,
|
|
4578
|
+
action: entry.verdict.action,
|
|
4579
|
+
source: entry.verdict.source
|
|
4580
|
+
} } : {},
|
|
4581
|
+
...entry.pending ? { pending: true } : {},
|
|
4582
|
+
...entry.pending && entry.judgment ? { judgment: entry.judgment.dir } : {},
|
|
4583
|
+
...entry.verdictError ? { verdictError: entry.verdictError } : {}
|
|
4584
|
+
}))
|
|
4585
|
+
});
|
|
4586
|
+
/**
|
|
4587
|
+
* Record a judge's verdict for a screenshot with a pending request — the
|
|
4588
|
+
* validated alternative to hand-writing `verdict.json`.
|
|
4589
|
+
*/
|
|
4590
|
+
const writeAgentVerdict = async (outputDir, name, input) => {
|
|
4591
|
+
const dir = judgmentDir(outputDir, name);
|
|
4592
|
+
if (!await exists(node_path.default.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first (use --judge all to request one for any changed screenshot).`);
|
|
4593
|
+
const parsed = parseAgentVerdict(input);
|
|
4594
|
+
if (!parsed.ok) throw new Error(parsed.error);
|
|
4595
|
+
const verdictPath = node_path.default.join(dir, VERDICT_FILE);
|
|
4596
|
+
await writeJson(verdictPath, {
|
|
4597
|
+
name,
|
|
4598
|
+
verdict: {
|
|
4599
|
+
label: parsed.label,
|
|
4600
|
+
headline: parsed.headline,
|
|
4601
|
+
rationale: parsed.rationale,
|
|
4602
|
+
action: ACTION_BY_LABEL[parsed.label]
|
|
4603
|
+
},
|
|
4604
|
+
...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
|
|
4605
|
+
});
|
|
4606
|
+
return verdictPath;
|
|
4607
|
+
};
|
|
4608
|
+
//#endregion
|
|
4609
|
+
//#region src/webServer/resolve.ts
|
|
4610
|
+
const DEFAULT_WEB_SERVER_TIMEOUT_MS = 6e4;
|
|
4611
|
+
const isHttpUrl = (value) => URL.canParse(value) && ["http:", "https:"].includes(new URL(value).protocol);
|
|
4612
|
+
/**
|
|
4613
|
+
* Normalise `webServer` to a list with every default applied.
|
|
4614
|
+
*
|
|
4615
|
+
* A relative `cwd` resolves against `configDir` — the directory of
|
|
4616
|
+
* `cappa.config.ts` — not the process's working directory, so the same config
|
|
4617
|
+
* works whether cappa runs from the repository root or from inside the package
|
|
4618
|
+
* (`pnpm -F visual-tests cappa capture`).
|
|
4619
|
+
*/
|
|
4620
|
+
function resolveWebServerConfig(webServer, configDir, env = process.env) {
|
|
4621
|
+
if (webServer === void 0) return [];
|
|
4622
|
+
return (Array.isArray(webServer) ? webServer : [webServer]).map((entry, index) => {
|
|
4623
|
+
const where = Array.isArray(webServer) ? `webServer[${index}]` : "webServer";
|
|
4624
|
+
if (typeof entry?.command !== "string" || entry.command.trim() === "") throw new Error(`Invalid configuration: ${where}.command is required.`);
|
|
4625
|
+
if (typeof entry.url !== "string" || !isHttpUrl(entry.url)) throw new Error(`Invalid configuration: ${where}.url must be an absolute URL, e.g. "http://localhost:6006".`);
|
|
4626
|
+
if (entry.timeout !== void 0 && !(Number.isFinite(entry.timeout) && entry.timeout > 0)) throw new Error(`Invalid configuration: ${where}.timeout must be a positive number of milliseconds.`);
|
|
4627
|
+
return {
|
|
4628
|
+
command: entry.command,
|
|
4629
|
+
url: entry.url,
|
|
4630
|
+
reuseExistingServer: entry.reuseExistingServer ?? !env.CI,
|
|
4631
|
+
timeout: entry.timeout ?? 6e4,
|
|
4632
|
+
cwd: node_path.default.resolve(configDir, entry.cwd ?? "."),
|
|
4633
|
+
env: entry.env ?? {}
|
|
4634
|
+
};
|
|
4635
|
+
});
|
|
4636
|
+
}
|
|
4637
|
+
//#endregion
|
|
4638
|
+
exports.ACTION_BY_LABEL = ACTION_BY_LABEL;
|
|
4639
|
+
exports.AGENT_DIRNAME = AGENT_DIRNAME;
|
|
4640
|
+
exports.AGENT_REPORT_VERSION = AGENT_REPORT_VERSION;
|
|
3185
4641
|
exports.CONSOLE_LOG_LEVELS = CONSOLE_LOG_LEVELS;
|
|
3186
4642
|
exports.CaptureRunner = CaptureRunner;
|
|
3187
4643
|
exports.DEFAULT_DEBOUNCE_MS = DEFAULT_DEBOUNCE_MS;
|
|
3188
4644
|
exports.DEFAULT_IGNORED_DIRS = DEFAULT_IGNORED_DIRS;
|
|
4645
|
+
exports.DEFAULT_KILL_GRACE_MS = DEFAULT_KILL_GRACE_MS;
|
|
3189
4646
|
exports.DEFAULT_MAX_TASKS = DEFAULT_MAX_TASKS;
|
|
4647
|
+
exports.DEFAULT_WEB_SERVER_TIMEOUT_MS = DEFAULT_WEB_SERVER_TIMEOUT_MS;
|
|
3190
4648
|
exports.ENGINE_ERROR_CODES = ENGINE_ERROR_CODES;
|
|
3191
4649
|
exports.FsScreenshotStore = FsScreenshotStore;
|
|
4650
|
+
exports.JUDGED_LABELS = JUDGED_LABELS;
|
|
4651
|
+
exports.JUDGE_MODES = JUDGE_MODES;
|
|
3192
4652
|
exports.LocalEngine = LocalEngine;
|
|
3193
4653
|
exports.MANIFEST_FILENAME = MANIFEST_FILENAME;
|
|
3194
4654
|
exports.MANIFEST_VERSION = MANIFEST_VERSION;
|
|
4655
|
+
exports.NO_WEB_SERVER_HINT = NO_WEB_SERVER_HINT;
|
|
4656
|
+
exports.OutputTail = OutputTail;
|
|
3195
4657
|
exports.RunInProgressError = RunInProgressError;
|
|
3196
4658
|
exports.RunStore = RunStore;
|
|
4659
|
+
exports.SUB_PERCEPTUAL_PERCENT = SUB_PERCEPTUAL_PERCENT;
|
|
3197
4660
|
exports.ScreenshotFileSystem = ScreenshotFileSystem;
|
|
3198
4661
|
exports.ScreenshotTool = ScreenshotTool;
|
|
3199
4662
|
exports.UnknownTargetsError = UnknownTargetsError;
|
|
4663
|
+
exports.VERDICT_LABELS = VERDICT_LABELS;
|
|
3200
4664
|
exports.WarmBrowser = WarmBrowser;
|
|
3201
4665
|
exports.WatchInProgressError = WatchInProgressError;
|
|
3202
4666
|
exports.WatchSession = WatchSession;
|
|
4667
|
+
exports.WebServerError = WebServerError;
|
|
4668
|
+
exports.WebServerPool = WebServerPool;
|
|
4669
|
+
exports.agentDir = agentDir;
|
|
4670
|
+
exports.agentReportPath = agentReportPath;
|
|
3203
4671
|
exports.attachConsoleLogging = attachConsoleLogging;
|
|
4672
|
+
exports.buildHeadline = buildHeadline;
|
|
4673
|
+
exports.clearJudgment = clearJudgment;
|
|
3204
4674
|
exports.collectScreenshots = collectScreenshots;
|
|
3205
4675
|
exports.compareImages = compareImages;
|
|
3206
4676
|
exports.compareImagesGMSD = compareImagesGMSD;
|
|
4677
|
+
exports.contextPadding = contextPadding;
|
|
3207
4678
|
exports.defineConfig = defineConfig;
|
|
4679
|
+
exports.deriveVerdict = deriveVerdict;
|
|
3208
4680
|
exports.didScreenshotFail = didScreenshotFail;
|
|
3209
4681
|
exports.filterTasks = filterTasks;
|
|
4682
|
+
exports.findRefusedConnection = findRefusedConnection;
|
|
4683
|
+
exports.fingerprintImages = fingerprintImages;
|
|
3210
4684
|
exports.getDeletedScreenshots = getDeletedScreenshots;
|
|
3211
4685
|
exports.groupScreenshots = groupScreenshots;
|
|
3212
4686
|
exports.imagesMatch = imagesMatch;
|
|
3213
4687
|
exports.imagesMatchGMSD = imagesMatchGMSD;
|
|
4688
|
+
exports.isJudgedLabel = isJudgedLabel;
|
|
3214
4689
|
exports.isRunInProgressError = isRunInProgressError;
|
|
3215
4690
|
exports.isUnknownTargetsError = isUnknownTargetsError;
|
|
4691
|
+
exports.isUrlReady = isUrlReady;
|
|
4692
|
+
exports.isVerdictLabel = isVerdictLabel;
|
|
3216
4693
|
exports.isWatchInProgressError = isWatchInProgressError;
|
|
4694
|
+
exports.judgmentDir = judgmentDir;
|
|
3217
4695
|
exports.mapWithConcurrency = mapWithConcurrency;
|
|
3218
4696
|
exports.mergeCaptureManifest = mergeCaptureManifest;
|
|
4697
|
+
exports.normalizeChangeType = normalizeChangeType;
|
|
4698
|
+
exports.padAndClamp = padAndClamp;
|
|
4699
|
+
exports.parseAgentVerdict = parseAgentVerdict;
|
|
4700
|
+
exports.readAgentReport = readAgentReport;
|
|
3219
4701
|
exports.readCaptureManifest = readCaptureManifest;
|
|
3220
4702
|
exports.readDiffMeta = readDiffMeta;
|
|
3221
4703
|
exports.recordCaptureOrigins = recordCaptureOrigins;
|
|
4704
|
+
exports.renderJudgmentTiles = renderJudgmentTiles;
|
|
4705
|
+
exports.renderOverview = renderOverview;
|
|
4706
|
+
exports.resolveWebServerConfig = resolveWebServerConfig;
|
|
4707
|
+
exports.runAgentCheck = runAgentCheck;
|
|
4708
|
+
exports.sameServer = sameServer;
|
|
3222
4709
|
exports.sanitizeScreenshotFilename = sanitizeScreenshotFilename;
|
|
3223
4710
|
exports.selectTasks = selectTasks;
|
|
4711
|
+
exports.spawnServerProcess = spawnServerProcess;
|
|
3224
4712
|
exports.toConsoleLogLevel = toConsoleLogLevel;
|
|
3225
4713
|
exports.toDiffMetaPath = toDiffMetaPath;
|
|
3226
4714
|
exports.toManifestKey = toManifestKey;
|
|
3227
4715
|
exports.toSerializedError = toSerializedError;
|
|
4716
|
+
exports.toSlimAgentReport = toSlimAgentReport;
|
|
3228
4717
|
exports.toTaskStatus = toTaskStatus;
|
|
4718
|
+
exports.waitForUrl = waitForUrl;
|
|
4719
|
+
exports.writeAgentVerdict = writeAgentVerdict;
|
|
3229
4720
|
|
|
3230
4721
|
//# sourceMappingURL=index.cjs.map
|