@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.mjs
CHANGED
|
@@ -9,6 +9,7 @@ import { compare } from "@blazediff/core-native";
|
|
|
9
9
|
import { interpret } from "@blazediff/interpret-native";
|
|
10
10
|
import { createHash, randomUUID } from "node:crypto";
|
|
11
11
|
import { chromium, firefox, webkit } from "playwright-core";
|
|
12
|
+
import { execFile, execFileSync, spawn } from "node:child_process";
|
|
12
13
|
//#region \0rolldown/runtime.js
|
|
13
14
|
var __defProp = Object.defineProperty;
|
|
14
15
|
var __exportAll = (all, no_symbols) => {
|
|
@@ -818,6 +819,17 @@ var ScreenshotFileSystem = class {
|
|
|
818
819
|
await fsp.writeFile(filepath, data);
|
|
819
820
|
}
|
|
820
821
|
/**
|
|
822
|
+
* Remove a screenshot's diff image and metadata sidecar, if any.
|
|
823
|
+
*
|
|
824
|
+
* A run that does not clear `diff/` — a filtered or single-screenshot
|
|
825
|
+
* re-capture — would otherwise leave the previous run's diff behind for a
|
|
826
|
+
* screenshot that now passes, and a screenshot with a diff is `changed`.
|
|
827
|
+
*/
|
|
828
|
+
async removeDiffFiles(filename) {
|
|
829
|
+
const filepath = this.getDiffFilePath(filename);
|
|
830
|
+
await Promise.all([fsp.rm(filepath, { force: true }), fsp.rm(toDiffMetaPath(filepath), { force: true })]);
|
|
831
|
+
}
|
|
832
|
+
/**
|
|
821
833
|
* Get the path to a diff metadata sidecar file (`<name>.json`)
|
|
822
834
|
*/
|
|
823
835
|
getDiffMetaFilePath(filename) {
|
|
@@ -964,6 +976,91 @@ const recordCaptureOrigins = async (outputDir, origins, knownNames) => {
|
|
|
964
976
|
}
|
|
965
977
|
};
|
|
966
978
|
//#endregion
|
|
979
|
+
//#region src/webServer/unreachable.ts
|
|
980
|
+
/** The advice for a refused connection when the config has no `webServer`. */
|
|
981
|
+
const NO_WEB_SERVER_HINT = "Start it before capturing, or add a `webServer` entry to cappa.config.ts so cappa starts it for you.";
|
|
982
|
+
/**
|
|
983
|
+
* How a refused connection reads, across the places one surfaces: Node's
|
|
984
|
+
* sockets and `fetch` (`ECONNREFUSED`), Chromium (`net::ERR_CONNECTION_REFUSED`),
|
|
985
|
+
* Firefox (`NS_ERROR_CONNECTION_REFUSED`) and WebKit.
|
|
986
|
+
*/
|
|
987
|
+
const REFUSED_PATTERN = /\bECONNREFUSED\b|\bERR_CONNECTION_REFUSED\b|\bNS_ERROR_CONNECTION_REFUSED\b|Could not connect to (?:the )?server|Connection refused/i;
|
|
988
|
+
const URL_PATTERN = /\bhttps?:\/\/[^\s"'`<>)\]]+/i;
|
|
989
|
+
const toOrigin = (url) => {
|
|
990
|
+
try {
|
|
991
|
+
return new URL(url.replace(/[.,;:!?]+$/, "")).origin;
|
|
992
|
+
} catch {
|
|
993
|
+
return;
|
|
994
|
+
}
|
|
995
|
+
};
|
|
996
|
+
/**
|
|
997
|
+
* Whether `error` — an `Error`, a plain object, or just a message string, as
|
|
998
|
+
* plugins report task failures — is a refused connection.
|
|
999
|
+
*
|
|
1000
|
+
* Walks `cause` and `AggregateError.errors`: Node's `fetch` says only
|
|
1001
|
+
* "fetch failed" and puts `ECONNREFUSED` on its cause, and a plugin that wraps
|
|
1002
|
+
* the error in a friendlier one keeps it there too.
|
|
1003
|
+
*
|
|
1004
|
+
* Works on any plugin's errors, third-party included, because it reads the
|
|
1005
|
+
* error rather than asking the plugin.
|
|
1006
|
+
*/
|
|
1007
|
+
function findRefusedConnection(error) {
|
|
1008
|
+
let refused = false;
|
|
1009
|
+
let origin;
|
|
1010
|
+
let socketOrigin;
|
|
1011
|
+
const seen = /* @__PURE__ */ new Set();
|
|
1012
|
+
const visit = (value, depth) => {
|
|
1013
|
+
if (value === null || value === void 0 || depth > 8 || seen.has(value)) return;
|
|
1014
|
+
seen.add(value);
|
|
1015
|
+
if (typeof value === "string") {
|
|
1016
|
+
if (REFUSED_PATTERN.test(value)) refused = true;
|
|
1017
|
+
const url = value.match(URL_PATTERN)?.[0];
|
|
1018
|
+
origin ??= url ? toOrigin(url) : void 0;
|
|
1019
|
+
return;
|
|
1020
|
+
}
|
|
1021
|
+
if (typeof value !== "object") return;
|
|
1022
|
+
const record = value;
|
|
1023
|
+
if (record.code === "ECONNREFUSED") {
|
|
1024
|
+
refused = true;
|
|
1025
|
+
if (typeof record.address === "string" && record.port !== void 0) {
|
|
1026
|
+
const host = record.address.includes(":") ? `[${record.address}]` : record.address;
|
|
1027
|
+
socketOrigin ??= `http://${host}:${record.port}`;
|
|
1028
|
+
}
|
|
1029
|
+
}
|
|
1030
|
+
visit(record.message, depth + 1);
|
|
1031
|
+
visit(record.cause, depth + 1);
|
|
1032
|
+
if (Array.isArray(record.errors)) for (const inner of record.errors) visit(inner, depth + 1);
|
|
1033
|
+
};
|
|
1034
|
+
visit(error, 0);
|
|
1035
|
+
if (!refused) return;
|
|
1036
|
+
const resolved = origin ?? socketOrigin;
|
|
1037
|
+
return resolved ? { origin: resolved } : {};
|
|
1038
|
+
}
|
|
1039
|
+
const LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
|
|
1040
|
+
"localhost",
|
|
1041
|
+
"127.0.0.1",
|
|
1042
|
+
"[::1]",
|
|
1043
|
+
"0.0.0.0"
|
|
1044
|
+
]);
|
|
1045
|
+
/**
|
|
1046
|
+
* Whether two origins name the same server.
|
|
1047
|
+
*
|
|
1048
|
+
* Loopback spellings are interchangeable: a plugin configured with
|
|
1049
|
+
* `localhost:6006` and a socket error reporting `127.0.0.1:6006` are the same
|
|
1050
|
+
* Storybook.
|
|
1051
|
+
*/
|
|
1052
|
+
function sameServer(a, b) {
|
|
1053
|
+
try {
|
|
1054
|
+
const left = new URL(a);
|
|
1055
|
+
const right = new URL(b);
|
|
1056
|
+
const port = (url) => url.port || (url.protocol === "https:" ? "443" : "80");
|
|
1057
|
+
if (port(left) !== port(right)) return false;
|
|
1058
|
+
return left.hostname === right.hostname || LOOPBACK_HOSTS.has(left.hostname) && LOOPBACK_HOSTS.has(right.hostname);
|
|
1059
|
+
} catch {
|
|
1060
|
+
return false;
|
|
1061
|
+
}
|
|
1062
|
+
}
|
|
1063
|
+
//#endregion
|
|
967
1064
|
//#region src/runner/tasks.ts
|
|
968
1065
|
const isObject = (value) => typeof value === "object" && value !== null;
|
|
969
1066
|
/**
|
|
@@ -1055,6 +1152,8 @@ var CaptureRunner = class {
|
|
|
1055
1152
|
outputDir;
|
|
1056
1153
|
fileSystem;
|
|
1057
1154
|
now;
|
|
1155
|
+
prepare;
|
|
1156
|
+
explainUnreachable;
|
|
1058
1157
|
listeners = /* @__PURE__ */ new Set();
|
|
1059
1158
|
controller = new AbortController();
|
|
1060
1159
|
seq = 0;
|
|
@@ -1084,6 +1183,8 @@ var CaptureRunner = class {
|
|
|
1084
1183
|
this.fileSystem = options.fileSystem ?? options.screenshotTool.filesystem ?? new ScreenshotFileSystem(this.outputDir);
|
|
1085
1184
|
this.id = options.id ?? randomUUID();
|
|
1086
1185
|
this.now = options.now ?? (() => Date.now());
|
|
1186
|
+
this.prepare = options.prepare;
|
|
1187
|
+
this.explainUnreachable = options.explainUnreachable ?? (() => "Start it before capturing, or add a `webServer` entry to cappa.config.ts so cappa starts it for you.");
|
|
1087
1188
|
}
|
|
1088
1189
|
/** Subscribe to run events. Returns an unsubscribe function. */
|
|
1089
1190
|
on(listener) {
|
|
@@ -1172,6 +1273,10 @@ var CaptureRunner = class {
|
|
|
1172
1273
|
this.attachToolCaptureSink();
|
|
1173
1274
|
try {
|
|
1174
1275
|
try {
|
|
1276
|
+
if (this.prepare) {
|
|
1277
|
+
this.state = "discovering";
|
|
1278
|
+
await this.prepare((level, message) => this.log(level, message));
|
|
1279
|
+
}
|
|
1175
1280
|
if (request.clearActual ?? true) {
|
|
1176
1281
|
this.log("debug", `Cleaning output directory: ${this.outputDir}`);
|
|
1177
1282
|
this.fileSystem.clearActual();
|
|
@@ -1179,7 +1284,8 @@ var CaptureRunner = class {
|
|
|
1179
1284
|
}
|
|
1180
1285
|
const pluginTasks = await this.discover(request);
|
|
1181
1286
|
if (!this.controller.signal.aborted) await this.execute(pluginTasks);
|
|
1182
|
-
} catch (
|
|
1287
|
+
} catch (thrown) {
|
|
1288
|
+
const error = this.toUnreachableError(thrown) ?? thrown;
|
|
1183
1289
|
this.error = error;
|
|
1184
1290
|
this.state = "failed";
|
|
1185
1291
|
this.finishedAt = this.now();
|
|
@@ -1357,6 +1463,7 @@ var CaptureRunner = class {
|
|
|
1357
1463
|
}
|
|
1358
1464
|
const durationMs = this.now() - taskStart;
|
|
1359
1465
|
completedTasks++;
|
|
1466
|
+
result = this.explainTaskError(result);
|
|
1360
1467
|
const failed = didScreenshotFail(result);
|
|
1361
1468
|
const status = toTaskStatus(result);
|
|
1362
1469
|
const typedResult = result;
|
|
@@ -1395,6 +1502,36 @@ var CaptureRunner = class {
|
|
|
1395
1502
|
});
|
|
1396
1503
|
}
|
|
1397
1504
|
}
|
|
1505
|
+
/**
|
|
1506
|
+
* The message for a refused connection: where, and what to do about it.
|
|
1507
|
+
*
|
|
1508
|
+
* Identical for every task that hit the same server — no task id, no path —
|
|
1509
|
+
* so a report can collapse 300 of them into one line.
|
|
1510
|
+
*/
|
|
1511
|
+
unreachableMessage(origin) {
|
|
1512
|
+
return `Cannot reach ${origin ?? "the app under test"}: connection refused. ${this.explainUnreachable(origin)}`;
|
|
1513
|
+
}
|
|
1514
|
+
toUnreachableError(error) {
|
|
1515
|
+
const refused = findRefusedConnection(error);
|
|
1516
|
+
if (!refused) return;
|
|
1517
|
+
return new Error(this.unreachableMessage(refused.origin), { cause: error });
|
|
1518
|
+
}
|
|
1519
|
+
/**
|
|
1520
|
+
* Replace a plugin's refused-connection error with the explained one.
|
|
1521
|
+
*
|
|
1522
|
+
* Reads the result rather than asking the plugin, so third-party plugins get
|
|
1523
|
+
* the same message without an API change.
|
|
1524
|
+
*/
|
|
1525
|
+
explainTaskError(result) {
|
|
1526
|
+
const error = result?.error;
|
|
1527
|
+
if (error === void 0 || error === null) return result;
|
|
1528
|
+
const refused = findRefusedConnection(error);
|
|
1529
|
+
if (!refused) return result;
|
|
1530
|
+
return {
|
|
1531
|
+
...result,
|
|
1532
|
+
error: this.unreachableMessage(refused.origin)
|
|
1533
|
+
};
|
|
1534
|
+
}
|
|
1398
1535
|
async collectDeleted() {
|
|
1399
1536
|
if (!this.anyTasksRan) return;
|
|
1400
1537
|
try {
|
|
@@ -1831,6 +1968,7 @@ var ScreenshotTool = class {
|
|
|
1831
1968
|
const saveDiff = extras.saveDiffImage ?? false;
|
|
1832
1969
|
const diffFilename = extras.diffImageFilename ?? filename;
|
|
1833
1970
|
const diffOverride = extras.diff;
|
|
1971
|
+
await this.filesystem.removeDiffFiles(diffFilename);
|
|
1834
1972
|
if (!await this.filesystem.hasExpectedFile(filename)) {
|
|
1835
1973
|
this.logger.debug(`Expected image not found for ${filename}, taking screenshot`);
|
|
1836
1974
|
result.filepath = await this.takeScreenshot(page, filename, options);
|
|
@@ -2030,6 +2168,204 @@ var ScreenshotTool = class {
|
|
|
2030
2168
|
}
|
|
2031
2169
|
};
|
|
2032
2170
|
//#endregion
|
|
2171
|
+
//#region src/agent/paths.ts
|
|
2172
|
+
/**
|
|
2173
|
+
* Where agent review keeps its state, inside `outputDir`.
|
|
2174
|
+
*
|
|
2175
|
+
* Its own module so screenshot collection can read the report without
|
|
2176
|
+
* importing the review pipeline, which itself collects screenshots.
|
|
2177
|
+
*/
|
|
2178
|
+
const AGENT_DIRNAME = ".cappa-agent";
|
|
2179
|
+
/** Bumped only if `request.json` or `report.json` change incompatibly. */
|
|
2180
|
+
const AGENT_REPORT_VERSION = 1;
|
|
2181
|
+
const agentDir = (outputDir) => path.resolve(outputDir, AGENT_DIRNAME);
|
|
2182
|
+
const judgmentsRoot = (outputDir) => path.join(agentDir(outputDir), "judgments");
|
|
2183
|
+
const agentReportPath = (outputDir) => path.join(agentDir(outputDir), "report.json");
|
|
2184
|
+
//#endregion
|
|
2185
|
+
//#region src/agent/verdict.ts
|
|
2186
|
+
/**
|
|
2187
|
+
* What a reviewer — heuristic or agent — believes a changed screenshot is.
|
|
2188
|
+
*
|
|
2189
|
+
* `ambiguous` is only ever produced by the heuristic: it is the signal that
|
|
2190
|
+
* the change has to be looked at, and an agent's verdict must resolve it into
|
|
2191
|
+
* one of the other three.
|
|
2192
|
+
*/
|
|
2193
|
+
const VERDICT_LABELS = [
|
|
2194
|
+
"regression-likely",
|
|
2195
|
+
"intentional-likely",
|
|
2196
|
+
"noise-likely",
|
|
2197
|
+
"ambiguous"
|
|
2198
|
+
];
|
|
2199
|
+
/** The labels a judge may hand back — everything but `ambiguous`. */
|
|
2200
|
+
const JUDGED_LABELS = [
|
|
2201
|
+
"regression-likely",
|
|
2202
|
+
"intentional-likely",
|
|
2203
|
+
"noise-likely"
|
|
2204
|
+
];
|
|
2205
|
+
const ACTION_BY_LABEL = {
|
|
2206
|
+
"regression-likely": "investigate",
|
|
2207
|
+
"intentional-likely": "approve-if-intended",
|
|
2208
|
+
"noise-likely": "mask-or-approve",
|
|
2209
|
+
ambiguous: "investigate"
|
|
2210
|
+
};
|
|
2211
|
+
const isVerdictLabel = (value) => typeof value === "string" && VERDICT_LABELS.includes(value);
|
|
2212
|
+
const isJudgedLabel = (value) => typeof value === "string" && JUDGED_LABELS.includes(value);
|
|
2213
|
+
/**
|
|
2214
|
+
* Change types are normalised to kebab-case before they are compared.
|
|
2215
|
+
*
|
|
2216
|
+
* `@blazediff/interpret-native` reports `color-change` today but earlier
|
|
2217
|
+
* releases reported `ColorChange`; normalising keeps the heuristic working
|
|
2218
|
+
* across a diff-engine upgrade instead of silently degrading every screenshot
|
|
2219
|
+
* to `ambiguous`.
|
|
2220
|
+
*/
|
|
2221
|
+
const normalizeChangeType = (changeType) => changeType.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
|
|
2222
|
+
const normalizeSeverity = (severity) => (severity ?? "").toLowerCase();
|
|
2223
|
+
/** Structural: something appeared, vanished or was replaced. */
|
|
2224
|
+
const REGRESSIVE_TYPES = /* @__PURE__ */ new Set([
|
|
2225
|
+
"content-change",
|
|
2226
|
+
"addition",
|
|
2227
|
+
"deletion"
|
|
2228
|
+
]);
|
|
2229
|
+
/** Restyled or moved, with structure intact. */
|
|
2230
|
+
const RESTYLE_TYPES = /* @__PURE__ */ new Set(["color-change", "shift"]);
|
|
2231
|
+
const NOISE_TYPES = /* @__PURE__ */ new Set(["rendering-noise"]);
|
|
2232
|
+
const ELEVATED_SEVERITY = /* @__PURE__ */ new Set(["medium", "high"]);
|
|
2233
|
+
/** Below this share of the image, a low-severity change is not perceptible. */
|
|
2234
|
+
const SUB_PERCEPTUAL_PERCENT = .01;
|
|
2235
|
+
/** Mean region confidence above which a pure recolour is trusted. */
|
|
2236
|
+
const RECOLOR_CONFIDENCE = .7;
|
|
2237
|
+
const formatPercent = (percent) => {
|
|
2238
|
+
if (percent === void 0) return "?%";
|
|
2239
|
+
return percent >= .01 ? `${percent.toFixed(2)}%` : `${percent.toFixed(3)}%`;
|
|
2240
|
+
};
|
|
2241
|
+
const countByType = (regions) => {
|
|
2242
|
+
const counts = /* @__PURE__ */ new Map();
|
|
2243
|
+
for (const region of regions) {
|
|
2244
|
+
const type = normalizeChangeType(region.changeType);
|
|
2245
|
+
counts.set(type, (counts.get(type) ?? 0) + 1);
|
|
2246
|
+
}
|
|
2247
|
+
return counts;
|
|
2248
|
+
};
|
|
2249
|
+
const formatBreakdown = (counts) => [...counts].sort((a, b) => b[1] - a[1]).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2250
|
+
const largestRegion = (regions) => regions.reduce((best, region) => !best || region.pixelCount > best.pixelCount ? region : best, void 0);
|
|
2251
|
+
const meanConfidence = (regions) => regions.length === 0 ? 0 : regions.reduce((sum, region) => sum + (region.confidence ?? 0), 0) / regions.length;
|
|
2252
|
+
/**
|
|
2253
|
+
* A one-line description of a change, shaped so that the same kind of change
|
|
2254
|
+
* on different screenshots produces the same headline — which is what lets an
|
|
2255
|
+
* agent spot one shared cause (a footer timestamp, a theme toggle) across
|
|
2256
|
+
* dozens of screenshots without opening any of them.
|
|
2257
|
+
*/
|
|
2258
|
+
const buildHeadline = (input) => {
|
|
2259
|
+
if (input.differentSizes) return "image dimensions changed";
|
|
2260
|
+
const interpretation = input.interpretation;
|
|
2261
|
+
const percent = input.percentDifference ?? interpretation?.diffPercentage;
|
|
2262
|
+
if (!interpretation || interpretation.regions.length === 0) return `${(input.numDiffPixels ?? interpretation?.diffCount)?.toLocaleString("en-US") ?? "?"} px (${formatPercent(percent)}) - no region analysis`;
|
|
2263
|
+
const regions = interpretation.regions;
|
|
2264
|
+
const counts = countByType(regions);
|
|
2265
|
+
const position = largestRegion(regions)?.position;
|
|
2266
|
+
const at = position ? ` @ ${position}` : "";
|
|
2267
|
+
const severity = normalizeSeverity(interpretation.severity) || "?";
|
|
2268
|
+
if (regions.length === 1) return `1 ${[...counts.keys()][0]}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2269
|
+
return `${regions.length} regions: ${formatBreakdown(counts)}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2270
|
+
};
|
|
2271
|
+
const verdict = (label, headline, rationale) => ({
|
|
2272
|
+
label,
|
|
2273
|
+
headline,
|
|
2274
|
+
rationale,
|
|
2275
|
+
action: ACTION_BY_LABEL[label]
|
|
2276
|
+
});
|
|
2277
|
+
/**
|
|
2278
|
+
* Classify a changed screenshot from its diff interpretation alone.
|
|
2279
|
+
*
|
|
2280
|
+
* Deliberately conservative: only the cases the signals settle are labelled,
|
|
2281
|
+
* and everything else is `ambiguous` so that it reaches a judge who can look
|
|
2282
|
+
* at the pixels. A wrong `noise-likely` hides a regression; a wrong
|
|
2283
|
+
* `ambiguous` costs one look.
|
|
2284
|
+
*/
|
|
2285
|
+
const deriveVerdict = (input) => {
|
|
2286
|
+
const headline = buildHeadline(input);
|
|
2287
|
+
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"]);
|
|
2288
|
+
const interpretation = input.interpretation;
|
|
2289
|
+
if (!interpretation || interpretation.regions.length === 0) return verdict("ambiguous", headline, ["pixels differ but no change regions were found"]);
|
|
2290
|
+
const regions = interpretation.regions;
|
|
2291
|
+
const types = regions.map((region) => normalizeChangeType(region.changeType));
|
|
2292
|
+
const severity = normalizeSeverity(interpretation.severity);
|
|
2293
|
+
const percent = input.percentDifference ?? interpretation.diffPercentage;
|
|
2294
|
+
const counts = countByType(regions);
|
|
2295
|
+
if (types.every((type) => NOISE_TYPES.has(type))) return verdict("noise-likely", headline, ["every region is classified as rendering noise"]);
|
|
2296
|
+
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"]);
|
|
2297
|
+
if (types.some((type) => REGRESSIVE_TYPES.has(type)) && ELEVATED_SEVERITY.has(severity)) {
|
|
2298
|
+
const structural = [...counts].filter(([type]) => REGRESSIVE_TYPES.has(type)).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2299
|
+
return verdict("regression-likely", headline, [`${severity} severity with structural changes (${structural})`, "content or layout changed, not just styling"]);
|
|
2300
|
+
}
|
|
2301
|
+
const allRecolor = types.every((type) => type === "color-change");
|
|
2302
|
+
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"]);
|
|
2303
|
+
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"]);
|
|
2304
|
+
return verdict("ambiguous", headline, [`mix of change types (${formatBreakdown(counts)}) at ${severity || "unknown"} severity`, `${formatPercent(percent)} of the image differs`]);
|
|
2305
|
+
};
|
|
2306
|
+
//#endregion
|
|
2307
|
+
//#region src/agent/reviewIndex.ts
|
|
2308
|
+
/**
|
|
2309
|
+
* Read the review index, or nothing.
|
|
2310
|
+
*
|
|
2311
|
+
* Never throws: like the capture manifest, the report is an extra, and a
|
|
2312
|
+
* missing or hand-edited file must not break the screenshot listing.
|
|
2313
|
+
*/
|
|
2314
|
+
const readAgentReviewIndex = async (outputDir) => {
|
|
2315
|
+
let raw;
|
|
2316
|
+
try {
|
|
2317
|
+
raw = JSON.parse(await fsp.readFile(agentReportPath(outputDir), "utf8"));
|
|
2318
|
+
} catch {
|
|
2319
|
+
return;
|
|
2320
|
+
}
|
|
2321
|
+
const createdAt = typeof raw?.createdAt === "string" ? Date.parse(raw.createdAt) : NaN;
|
|
2322
|
+
if (raw?.version !== 1 || Number.isNaN(createdAt) || !Array.isArray(raw.entries)) return;
|
|
2323
|
+
const reviews = /* @__PURE__ */ new Map();
|
|
2324
|
+
for (const entry of raw.entries) {
|
|
2325
|
+
if (typeof entry !== "object" || entry === null) continue;
|
|
2326
|
+
const { name, category, verdict, pending } = entry;
|
|
2327
|
+
if (typeof name !== "string" || category !== "changed") continue;
|
|
2328
|
+
if (typeof verdict !== "object" || verdict === null) continue;
|
|
2329
|
+
const v = verdict;
|
|
2330
|
+
if (!isVerdictLabel(v.label) || typeof v.headline !== "string") continue;
|
|
2331
|
+
reviews.set(name, {
|
|
2332
|
+
label: v.label,
|
|
2333
|
+
headline: v.headline,
|
|
2334
|
+
rationale: Array.isArray(v.rationale) ? v.rationale.filter((line) => typeof line === "string") : [],
|
|
2335
|
+
action: v.action,
|
|
2336
|
+
source: v.source === "agent" ? "agent" : "heuristic",
|
|
2337
|
+
...typeof v.confidence === "number" ? { confidence: v.confidence } : {},
|
|
2338
|
+
pending: pending === true,
|
|
2339
|
+
reviewedAt: new Date(createdAt).toISOString()
|
|
2340
|
+
});
|
|
2341
|
+
}
|
|
2342
|
+
return {
|
|
2343
|
+
createdAt,
|
|
2344
|
+
reviews
|
|
2345
|
+
};
|
|
2346
|
+
};
|
|
2347
|
+
const modifiedAt = async (file) => {
|
|
2348
|
+
try {
|
|
2349
|
+
return (await fsp.stat(file)).mtimeMs;
|
|
2350
|
+
} catch {
|
|
2351
|
+
return Number.POSITIVE_INFINITY;
|
|
2352
|
+
}
|
|
2353
|
+
};
|
|
2354
|
+
/**
|
|
2355
|
+
* The review for a changed screenshot, if it is still about these images.
|
|
2356
|
+
*
|
|
2357
|
+
* A capture after the check rewrites `actual/`, an approval rewrites
|
|
2358
|
+
* `expected/`; either makes the verdict describe pixels that are gone. File
|
|
2359
|
+
* times are compared rather than content hashed because this runs on every
|
|
2360
|
+
* listing the review UI makes.
|
|
2361
|
+
*/
|
|
2362
|
+
const freshAgentReview = async (index, outputDir, screenshot) => {
|
|
2363
|
+
const review = index?.reviews.get(screenshot.name);
|
|
2364
|
+
if (!index || !review) return void 0;
|
|
2365
|
+
const [actual, expected] = await Promise.all([modifiedAt(path.resolve(outputDir, screenshot.actualPath)), modifiedAt(path.resolve(outputDir, screenshot.expectedPath))]);
|
|
2366
|
+
return actual <= index.createdAt && expected <= index.createdAt ? review : void 0;
|
|
2367
|
+
};
|
|
2368
|
+
//#endregion
|
|
2033
2369
|
//#region src/screenshots/groupScreenshots.ts
|
|
2034
2370
|
const groupScreenshots = async (actualScreenshots, expectedScreenshots, diffScreenshots, outputDir) => {
|
|
2035
2371
|
const screenshotRepresentations = [];
|
|
@@ -2099,23 +2435,431 @@ const listPngs = async (dir) => Array.fromAsync(await glob(path.resolve(dir, "**
|
|
|
2099
2435
|
*
|
|
2100
2436
|
* The capture manifest is folded in here so every consumer — the CLI, the
|
|
2101
2437
|
* server, the review UI — sees the same `taskId`, and so a screenshot captured
|
|
2102
|
-
* before manifests existed simply has none rather than a wrong one.
|
|
2438
|
+
* before manifests existed simply has none rather than a wrong one. The last
|
|
2439
|
+
* `cappa agent check` verdict is folded in the same way, as `review`, while it
|
|
2440
|
+
* still describes the images on disk.
|
|
2103
2441
|
*/
|
|
2104
2442
|
const collectScreenshots = async (outputDir) => {
|
|
2105
|
-
const [actualScreenshots, expectedScreenshots, diffScreenshots, manifest] = await Promise.all([
|
|
2443
|
+
const [actualScreenshots, expectedScreenshots, diffScreenshots, manifest, reviewIndex] = await Promise.all([
|
|
2106
2444
|
listPngs(path.resolve(outputDir, "actual")),
|
|
2107
2445
|
listPngs(path.resolve(outputDir, "expected")),
|
|
2108
2446
|
listPngs(path.resolve(outputDir, "diff")),
|
|
2109
|
-
readCaptureManifest(outputDir)
|
|
2447
|
+
readCaptureManifest(outputDir),
|
|
2448
|
+
readAgentReviewIndex(outputDir)
|
|
2110
2449
|
]);
|
|
2111
|
-
|
|
2450
|
+
const screenshots = await groupScreenshots(actualScreenshots, expectedScreenshots, diffScreenshots, outputDir);
|
|
2451
|
+
return Promise.all(screenshots.map(async (screenshot) => {
|
|
2112
2452
|
const origin = manifest.screenshots[screenshot.name];
|
|
2113
|
-
|
|
2453
|
+
const withOrigin = origin ? {
|
|
2114
2454
|
...screenshot,
|
|
2115
2455
|
taskId: origin.taskId,
|
|
2116
2456
|
plugin: origin.plugin
|
|
2117
2457
|
} : screenshot;
|
|
2458
|
+
if (withOrigin.category !== "changed" || !reviewIndex) return withOrigin;
|
|
2459
|
+
const review = await freshAgentReview(reviewIndex, outputDir, withOrigin);
|
|
2460
|
+
return review ? {
|
|
2461
|
+
...withOrigin,
|
|
2462
|
+
review
|
|
2463
|
+
} : withOrigin;
|
|
2464
|
+
}));
|
|
2465
|
+
};
|
|
2466
|
+
//#endregion
|
|
2467
|
+
//#region src/webServer/process.ts
|
|
2468
|
+
/** Grace period between SIGTERM and SIGKILL. */
|
|
2469
|
+
const DEFAULT_KILL_GRACE_MS = 5e3;
|
|
2470
|
+
/** How long to wait for the kernel to reap a SIGKILLed group. */
|
|
2471
|
+
const SIGKILL_WAIT_MS = 2e3;
|
|
2472
|
+
const isWindows = process.platform === "win32";
|
|
2473
|
+
/**
|
|
2474
|
+
* The last part of a process's output, kept in memory.
|
|
2475
|
+
*
|
|
2476
|
+
* Bounded by bytes rather than lines: a dev server that prints one enormous
|
|
2477
|
+
* line is no reason to hold on to all of it, and the tail exists to explain a
|
|
2478
|
+
* failure, not to be a log.
|
|
2479
|
+
*/
|
|
2480
|
+
var OutputTail = class {
|
|
2481
|
+
maxBytes;
|
|
2482
|
+
chunks = [];
|
|
2483
|
+
size = 0;
|
|
2484
|
+
constructor(maxBytes = 65536) {
|
|
2485
|
+
this.maxBytes = maxBytes;
|
|
2486
|
+
}
|
|
2487
|
+
push(chunk) {
|
|
2488
|
+
this.chunks.push(chunk);
|
|
2489
|
+
this.size += chunk.length;
|
|
2490
|
+
while (this.size > this.maxBytes && this.chunks.length > 1) this.size -= this.chunks.shift()?.length ?? 0;
|
|
2491
|
+
}
|
|
2492
|
+
/** The last `maxLines` non-empty lines. */
|
|
2493
|
+
lines(maxLines = 30) {
|
|
2494
|
+
return this.chunks.join("").split(/\r?\n/).filter((line) => line.trim() !== "").slice(-maxLines);
|
|
2495
|
+
}
|
|
2496
|
+
};
|
|
2497
|
+
/**
|
|
2498
|
+
* Process groups this process started and has not stopped yet.
|
|
2499
|
+
*
|
|
2500
|
+
* Exists for the one exit no `close()` covers: the process leaving without
|
|
2501
|
+
* shutting down. A server left running holds its port, and the next run would
|
|
2502
|
+
* silently *reuse* it — a stale build answering for the current one.
|
|
2503
|
+
*/
|
|
2504
|
+
const liveProcesses = /* @__PURE__ */ new Set();
|
|
2505
|
+
let exitHookInstalled = false;
|
|
2506
|
+
const installExitHook = () => {
|
|
2507
|
+
if (exitHookInstalled) return;
|
|
2508
|
+
exitHookInstalled = true;
|
|
2509
|
+
process.on("exit", () => {
|
|
2510
|
+
for (const child of liveProcesses) killTreeNow(child);
|
|
2511
|
+
liveProcesses.clear();
|
|
2512
|
+
});
|
|
2513
|
+
};
|
|
2514
|
+
const killTreeNow = (child) => {
|
|
2515
|
+
if (child.pid === void 0) return;
|
|
2516
|
+
try {
|
|
2517
|
+
if (isWindows) execFileSync("taskkill", [
|
|
2518
|
+
"/pid",
|
|
2519
|
+
String(child.pid),
|
|
2520
|
+
"/T",
|
|
2521
|
+
"/F"
|
|
2522
|
+
], { stdio: "ignore" });
|
|
2523
|
+
else process.kill(-child.pid, "SIGKILL");
|
|
2524
|
+
} catch {}
|
|
2525
|
+
};
|
|
2526
|
+
/**
|
|
2527
|
+
* Start `command` through a shell, as the leader of its own process group.
|
|
2528
|
+
*
|
|
2529
|
+
* A group, because the command is rarely the server itself: `pnpm storybook`
|
|
2530
|
+
* is pnpm, running a shell, running storybook, running workers. Killing only
|
|
2531
|
+
* the direct child would leave the rest holding the port.
|
|
2532
|
+
*
|
|
2533
|
+
* Output is buffered, never written anywhere unless `onOutput` asks for it —
|
|
2534
|
+
* `cappa capture --json` must stay a single clean document on stdout.
|
|
2535
|
+
*/
|
|
2536
|
+
function spawnServerProcess(command, options) {
|
|
2537
|
+
const child = spawn(command, {
|
|
2538
|
+
cwd: options.cwd,
|
|
2539
|
+
env: {
|
|
2540
|
+
...process.env,
|
|
2541
|
+
...options.env
|
|
2542
|
+
},
|
|
2543
|
+
shell: true,
|
|
2544
|
+
detached: !isWindows,
|
|
2545
|
+
stdio: [
|
|
2546
|
+
"ignore",
|
|
2547
|
+
"pipe",
|
|
2548
|
+
"pipe"
|
|
2549
|
+
],
|
|
2550
|
+
windowsHide: true
|
|
2118
2551
|
});
|
|
2552
|
+
const output = new OutputTail();
|
|
2553
|
+
const onData = (data) => {
|
|
2554
|
+
const chunk = data.toString();
|
|
2555
|
+
output.push(chunk);
|
|
2556
|
+
options.onOutput?.(chunk);
|
|
2557
|
+
};
|
|
2558
|
+
child.stdout?.on("data", onData);
|
|
2559
|
+
child.stderr?.on("data", onData);
|
|
2560
|
+
liveProcesses.add(child);
|
|
2561
|
+
installExitHook();
|
|
2562
|
+
let exit;
|
|
2563
|
+
const exited = new Promise((resolve) => {
|
|
2564
|
+
const settle = (value) => {
|
|
2565
|
+
if (exit) return;
|
|
2566
|
+
exit = value;
|
|
2567
|
+
resolve(value);
|
|
2568
|
+
};
|
|
2569
|
+
child.once("exit", (code, signal) => settle({
|
|
2570
|
+
code,
|
|
2571
|
+
signal
|
|
2572
|
+
}));
|
|
2573
|
+
child.once("error", (error) => {
|
|
2574
|
+
output.push(`${error.message}\n`);
|
|
2575
|
+
settle({
|
|
2576
|
+
code: null,
|
|
2577
|
+
signal: null
|
|
2578
|
+
});
|
|
2579
|
+
});
|
|
2580
|
+
});
|
|
2581
|
+
let killing;
|
|
2582
|
+
return {
|
|
2583
|
+
get pid() {
|
|
2584
|
+
return child.pid;
|
|
2585
|
+
},
|
|
2586
|
+
exited,
|
|
2587
|
+
get exit() {
|
|
2588
|
+
return exit;
|
|
2589
|
+
},
|
|
2590
|
+
output,
|
|
2591
|
+
kill(graceMs = DEFAULT_KILL_GRACE_MS) {
|
|
2592
|
+
killing ??= killProcessTree(child, exited, graceMs).finally(() => {
|
|
2593
|
+
liveProcesses.delete(child);
|
|
2594
|
+
});
|
|
2595
|
+
return killing;
|
|
2596
|
+
}
|
|
2597
|
+
};
|
|
2598
|
+
}
|
|
2599
|
+
/** True while any process in the group led by `pid` is alive. */
|
|
2600
|
+
const groupAlive = (pid) => {
|
|
2601
|
+
try {
|
|
2602
|
+
process.kill(-pid, 0);
|
|
2603
|
+
return true;
|
|
2604
|
+
} catch (error) {
|
|
2605
|
+
return error.code === "EPERM";
|
|
2606
|
+
}
|
|
2607
|
+
};
|
|
2608
|
+
const delay = (ms) => new Promise((resolve) => {
|
|
2609
|
+
setTimeout(resolve, ms);
|
|
2610
|
+
});
|
|
2611
|
+
/**
|
|
2612
|
+
* SIGTERM the whole group, then SIGKILL whatever is left after `graceMs`.
|
|
2613
|
+
*
|
|
2614
|
+
* Waits on the group, not the child: the shell can exit at once while the
|
|
2615
|
+
* server it started is still shutting down — and still holding the port.
|
|
2616
|
+
*/
|
|
2617
|
+
async function killProcessTree(child, exited, graceMs) {
|
|
2618
|
+
const pid = child.pid;
|
|
2619
|
+
if (pid === void 0) return;
|
|
2620
|
+
if (isWindows) {
|
|
2621
|
+
await new Promise((resolve) => {
|
|
2622
|
+
execFile("taskkill", [
|
|
2623
|
+
"/pid",
|
|
2624
|
+
String(pid),
|
|
2625
|
+
"/T",
|
|
2626
|
+
"/F"
|
|
2627
|
+
], () => resolve());
|
|
2628
|
+
});
|
|
2629
|
+
await exited;
|
|
2630
|
+
return;
|
|
2631
|
+
}
|
|
2632
|
+
if (!groupAlive(pid)) return;
|
|
2633
|
+
try {
|
|
2634
|
+
process.kill(-pid, "SIGTERM");
|
|
2635
|
+
} catch {
|
|
2636
|
+
return;
|
|
2637
|
+
}
|
|
2638
|
+
const deadline = Date.now() + graceMs;
|
|
2639
|
+
while (groupAlive(pid) && Date.now() < deadline) await delay(50);
|
|
2640
|
+
if (groupAlive(pid)) {
|
|
2641
|
+
try {
|
|
2642
|
+
process.kill(-pid, "SIGKILL");
|
|
2643
|
+
} catch {}
|
|
2644
|
+
const killDeadline = Date.now() + SIGKILL_WAIT_MS;
|
|
2645
|
+
while (groupAlive(pid) && Date.now() < killDeadline) await delay(20);
|
|
2646
|
+
}
|
|
2647
|
+
await exited;
|
|
2648
|
+
}
|
|
2649
|
+
//#endregion
|
|
2650
|
+
//#region src/webServer/readiness.ts
|
|
2651
|
+
const PROBE_TIMEOUT_MS = 5e3;
|
|
2652
|
+
/** Delays between probes; the last one repeats. */
|
|
2653
|
+
const POLL_DELAYS_MS = [
|
|
2654
|
+
100,
|
|
2655
|
+
250,
|
|
2656
|
+
500,
|
|
2657
|
+
1e3
|
|
2658
|
+
];
|
|
2659
|
+
/**
|
|
2660
|
+
* Whether `url` answers with a 2xx or 3xx status.
|
|
2661
|
+
*
|
|
2662
|
+
* Redirects are not followed: a dev server that redirects `/` to `/login` is
|
|
2663
|
+
* up, and following it would make readiness depend on a page cappa never asked
|
|
2664
|
+
* about.
|
|
2665
|
+
*/
|
|
2666
|
+
async function isUrlReady(url, timeoutMs = PROBE_TIMEOUT_MS) {
|
|
2667
|
+
try {
|
|
2668
|
+
const response = await fetch(url, {
|
|
2669
|
+
redirect: "manual",
|
|
2670
|
+
signal: AbortSignal.timeout(Math.max(1, timeoutMs))
|
|
2671
|
+
});
|
|
2672
|
+
await response.body?.cancel().catch(() => {});
|
|
2673
|
+
return response.status >= 200 && response.status < 400;
|
|
2674
|
+
} catch {
|
|
2675
|
+
return false;
|
|
2676
|
+
}
|
|
2677
|
+
}
|
|
2678
|
+
/** Poll `url` until it is ready, the deadline passes, or `abort` settles. */
|
|
2679
|
+
async function waitForUrl(url, options) {
|
|
2680
|
+
const probe = options.probe ?? isUrlReady;
|
|
2681
|
+
const deadline = Date.now() + options.timeoutMs;
|
|
2682
|
+
let aborted = false;
|
|
2683
|
+
const abort = (options.abort ?? new Promise(() => {})).then(() => {
|
|
2684
|
+
aborted = true;
|
|
2685
|
+
}, () => {
|
|
2686
|
+
aborted = true;
|
|
2687
|
+
});
|
|
2688
|
+
for (let attempt = 0;; attempt++) {
|
|
2689
|
+
const remaining = deadline - Date.now();
|
|
2690
|
+
if (aborted) return "aborted";
|
|
2691
|
+
if (remaining <= 0) return "timeout";
|
|
2692
|
+
if (await probe(url, Math.min(remaining, PROBE_TIMEOUT_MS))) return "ready";
|
|
2693
|
+
const wait = Math.min(POLL_DELAYS_MS[Math.min(attempt, POLL_DELAYS_MS.length - 1)] ?? 1e3, Math.max(0, deadline - Date.now()));
|
|
2694
|
+
let timer;
|
|
2695
|
+
await Promise.race([new Promise((resolve) => {
|
|
2696
|
+
timer = setTimeout(resolve, wait);
|
|
2697
|
+
}), abort]);
|
|
2698
|
+
clearTimeout(timer);
|
|
2699
|
+
}
|
|
2700
|
+
}
|
|
2701
|
+
//#endregion
|
|
2702
|
+
//#region src/webServer/WebServerPool.ts
|
|
2703
|
+
/** A web server could not be started, or would not become ready. */
|
|
2704
|
+
var WebServerError = class extends Error {
|
|
2705
|
+
constructor(message) {
|
|
2706
|
+
super(message);
|
|
2707
|
+
this.name = "WebServerError";
|
|
2708
|
+
}
|
|
2709
|
+
};
|
|
2710
|
+
const describeExit = (exit) => exit.signal ? `signal ${exit.signal}` : exit.code === null ? "an error" : `code ${exit.code}`;
|
|
2711
|
+
const formatTail = (command, lines) => lines.length === 0 ? `\`${command}\` printed nothing.` : `Last output of \`${command}\`:\n${lines.map((line) => ` ${line}`).join("\n")}`;
|
|
2712
|
+
const seconds = (ms) => `${Math.round(ms / 100) / 10}s`;
|
|
2713
|
+
/**
|
|
2714
|
+
* The servers a config's `webServer` describes, started on demand.
|
|
2715
|
+
*
|
|
2716
|
+
* Lazy and restartable rather than started once: the owning engine calls
|
|
2717
|
+
* `ensure` before every run and `stop` when the browser goes idle, so a review
|
|
2718
|
+
* session that sits unused gives the port back, and the next capture starts —
|
|
2719
|
+
* and rebuilds — the app again, picking up whatever changed in between.
|
|
2720
|
+
*
|
|
2721
|
+
* Every `ensure` says which way it went, because "reusing a server" and
|
|
2722
|
+
* "started one" look identical in screenshots, and a stale build, another
|
|
2723
|
+
* branch or another project on the same port is otherwise very hard to spot.
|
|
2724
|
+
*/
|
|
2725
|
+
var WebServerPool = class {
|
|
2726
|
+
entries;
|
|
2727
|
+
options;
|
|
2728
|
+
probe;
|
|
2729
|
+
/** Bumped by `stop`, so a start in flight knows it was cancelled. */
|
|
2730
|
+
generation = 0;
|
|
2731
|
+
constructor(options) {
|
|
2732
|
+
this.options = options;
|
|
2733
|
+
this.probe = options.probe ?? isUrlReady;
|
|
2734
|
+
this.entries = options.servers.map((config) => ({
|
|
2735
|
+
config,
|
|
2736
|
+
state: { kind: "idle" },
|
|
2737
|
+
starting: null
|
|
2738
|
+
}));
|
|
2739
|
+
}
|
|
2740
|
+
/** Whether the config has any `webServer` entry at all. */
|
|
2741
|
+
get configured() {
|
|
2742
|
+
return this.entries.length > 0;
|
|
2743
|
+
}
|
|
2744
|
+
/** Number of processes cappa started that are still running. */
|
|
2745
|
+
get running() {
|
|
2746
|
+
return this.entries.filter((entry) => entry.state.kind === "running" && !entry.state.process.exit).length;
|
|
2747
|
+
}
|
|
2748
|
+
/**
|
|
2749
|
+
* Make every server ready, in parallel, starting the ones that are not.
|
|
2750
|
+
*
|
|
2751
|
+
* All of them, even for a run that only captures one plugin's tasks: nothing
|
|
2752
|
+
* maps a plugin to a server, and guessing would start the wrong one.
|
|
2753
|
+
*/
|
|
2754
|
+
async ensure(log = this.defaultLog) {
|
|
2755
|
+
if (this.entries.length === 0) return;
|
|
2756
|
+
const errors = (await Promise.allSettled(this.entries.map((entry) => this.ensureEntry(entry, log)))).flatMap((result) => result.status === "rejected" ? [result.reason] : []);
|
|
2757
|
+
if (errors.length === 1) throw errors[0];
|
|
2758
|
+
if (errors.length > 1) throw new WebServerError(errors.map((error) => error instanceof Error ? error.message : error).join("\n\n"));
|
|
2759
|
+
}
|
|
2760
|
+
/**
|
|
2761
|
+
* Stop every server cappa started. A reused server is left alone — cappa did
|
|
2762
|
+
* not start it, so it is not cappa's to stop.
|
|
2763
|
+
*/
|
|
2764
|
+
async stop() {
|
|
2765
|
+
this.generation += 1;
|
|
2766
|
+
await Promise.all(this.entries.map(async (entry) => {
|
|
2767
|
+
const state = entry.state;
|
|
2768
|
+
entry.state = { kind: "idle" };
|
|
2769
|
+
if (state.kind === "running") await state.process.kill(this.options.killGraceMs);
|
|
2770
|
+
}));
|
|
2771
|
+
}
|
|
2772
|
+
/**
|
|
2773
|
+
* What to tell the user about a connection refused at `origin`.
|
|
2774
|
+
*
|
|
2775
|
+
* Always an actionable sentence: the bare "ECONNREFUSED" it replaces is the
|
|
2776
|
+
* single most common capture failure, and says nothing about what to do.
|
|
2777
|
+
*/
|
|
2778
|
+
explainUnreachable(origin) {
|
|
2779
|
+
if (this.entries.length === 0) return NO_WEB_SERVER_HINT;
|
|
2780
|
+
const matching = origin ? this.entries.find((entry) => sameServer(entry.config.url, origin)) : void 0;
|
|
2781
|
+
const crashed = matching?.state.kind === "exited" ? matching : this.entries.find((entry) => entry.state.kind === "exited");
|
|
2782
|
+
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)}`;
|
|
2783
|
+
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\`.`;
|
|
2784
|
+
return "The configured `webServer` was ready, but stopped accepting connections.";
|
|
2785
|
+
}
|
|
2786
|
+
defaultLog = (level, message) => {
|
|
2787
|
+
this.options.log?.(level, message);
|
|
2788
|
+
};
|
|
2789
|
+
ensureEntry(entry, log) {
|
|
2790
|
+
entry.starting ??= this.startEntry(entry, log).finally(() => {
|
|
2791
|
+
entry.starting = null;
|
|
2792
|
+
});
|
|
2793
|
+
return entry.starting;
|
|
2794
|
+
}
|
|
2795
|
+
async startEntry(entry, log) {
|
|
2796
|
+
const { command, url, timeout, cwd, env, reuseExistingServer } = entry.config;
|
|
2797
|
+
const previous = entry.state;
|
|
2798
|
+
if (previous.kind === "running" && !previous.process.exit) {
|
|
2799
|
+
log("info", `Using \`${command}\` at ${url}, started earlier by cappa`);
|
|
2800
|
+
return;
|
|
2801
|
+
}
|
|
2802
|
+
if (previous.kind === "exited") log("warn", `\`${command}\` exited with ${describeExit(previous.exit)} after the last run; starting it again`);
|
|
2803
|
+
if (await this.probe(url, Math.min(timeout, 5e3))) {
|
|
2804
|
+
if (reuseExistingServer) {
|
|
2805
|
+
entry.state = { kind: "reused" };
|
|
2806
|
+
log("info", `Reusing server at ${url} — \`${command}\` was not run`);
|
|
2807
|
+
return;
|
|
2808
|
+
}
|
|
2809
|
+
throw new WebServerError(`${url} is already in use, and \`webServer.reuseExistingServer\` is false. Stop whatever is serving it, or allow reusing it.`);
|
|
2810
|
+
}
|
|
2811
|
+
const generation = this.generation;
|
|
2812
|
+
const startedAt = Date.now();
|
|
2813
|
+
log("info", `Starting \`${command}\` — waiting up to ${seconds(timeout)} for ${url}`);
|
|
2814
|
+
const child = (this.options.spawn ?? spawnServerProcess)(command, {
|
|
2815
|
+
cwd,
|
|
2816
|
+
env,
|
|
2817
|
+
onOutput: this.options.onOutput ? (chunk) => this.options.onOutput?.(entry.config, chunk) : void 0
|
|
2818
|
+
});
|
|
2819
|
+
entry.state = {
|
|
2820
|
+
kind: "running",
|
|
2821
|
+
process: child
|
|
2822
|
+
};
|
|
2823
|
+
const result = await waitForUrl(url, {
|
|
2824
|
+
timeoutMs: timeout,
|
|
2825
|
+
abort: child.exited,
|
|
2826
|
+
probe: this.probe
|
|
2827
|
+
});
|
|
2828
|
+
if (generation !== this.generation) {
|
|
2829
|
+
await child.kill(this.options.killGraceMs);
|
|
2830
|
+
throw new WebServerError(`\`${command}\` was stopped before ${url} was ready.`);
|
|
2831
|
+
}
|
|
2832
|
+
if (result === "ready") {
|
|
2833
|
+
this.watchForCrash(entry, child);
|
|
2834
|
+
log("success", `Started \`${command}\` — ${url} ready in ${seconds(Date.now() - startedAt)}`);
|
|
2835
|
+
return;
|
|
2836
|
+
}
|
|
2837
|
+
entry.state = { kind: "idle" };
|
|
2838
|
+
if (result === "aborted") {
|
|
2839
|
+
const exit = await child.exited;
|
|
2840
|
+
throw new WebServerError(`\`${command}\` exited with ${describeExit(exit)} before ${url} was ready.\n${formatTail(command, child.output.lines())}`);
|
|
2841
|
+
}
|
|
2842
|
+
await child.kill(this.options.killGraceMs);
|
|
2843
|
+
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())}`);
|
|
2844
|
+
}
|
|
2845
|
+
/**
|
|
2846
|
+
* Record a server that exits on its own, so the failures it causes can say
|
|
2847
|
+
* why and the next run starts it again. Deliberately no restart loop: a
|
|
2848
|
+
* server that keeps crashing should fail loudly, not flap.
|
|
2849
|
+
*/
|
|
2850
|
+
watchForCrash(entry, child) {
|
|
2851
|
+
child.exited.then((exit) => {
|
|
2852
|
+
const state = entry.state;
|
|
2853
|
+
if (state.kind !== "running" || state.process !== child) return;
|
|
2854
|
+
entry.state = {
|
|
2855
|
+
kind: "exited",
|
|
2856
|
+
exit,
|
|
2857
|
+
tail: child.output.lines()
|
|
2858
|
+
};
|
|
2859
|
+
child.kill(this.options.killGraceMs);
|
|
2860
|
+
this.defaultLog("error", `\`${entry.config.command}\` exited with ${describeExit(exit)} while cappa was using it.`);
|
|
2861
|
+
});
|
|
2862
|
+
}
|
|
2119
2863
|
};
|
|
2120
2864
|
//#endregion
|
|
2121
2865
|
//#region src/engine/RunStore.ts
|
|
@@ -2283,6 +3027,7 @@ const isWatchInProgressError = (error) => hasCode(error, ENGINE_ERROR_CODES.watc
|
|
|
2283
3027
|
var WarmBrowser = class {
|
|
2284
3028
|
createTool;
|
|
2285
3029
|
idleTimeoutMs;
|
|
3030
|
+
onShutdown;
|
|
2286
3031
|
tool = null;
|
|
2287
3032
|
idleTimer = null;
|
|
2288
3033
|
inUse = false;
|
|
@@ -2294,6 +3039,7 @@ var WarmBrowser = class {
|
|
|
2294
3039
|
constructor(options) {
|
|
2295
3040
|
this.createTool = options.create;
|
|
2296
3041
|
this.idleTimeoutMs = options.idleTimeoutMs ?? 3e5;
|
|
3042
|
+
this.onShutdown = options.onShutdown;
|
|
2297
3043
|
}
|
|
2298
3044
|
/** True while a browser process is alive. */
|
|
2299
3045
|
get isWarm() {
|
|
@@ -2365,7 +3111,11 @@ var WarmBrowser = class {
|
|
|
2365
3111
|
const tool = this.tool;
|
|
2366
3112
|
this.tool = null;
|
|
2367
3113
|
this.inUse = false;
|
|
2368
|
-
|
|
3114
|
+
try {
|
|
3115
|
+
if (tool) await tool.close();
|
|
3116
|
+
} finally {
|
|
3117
|
+
await this.onShutdown?.();
|
|
3118
|
+
}
|
|
2369
3119
|
});
|
|
2370
3120
|
}
|
|
2371
3121
|
startIdleTimer() {
|
|
@@ -2390,7 +3140,11 @@ var WarmBrowser = class {
|
|
|
2390
3140
|
if (this.inUse || this.closed || this.holds > 0) return;
|
|
2391
3141
|
const tool = this.tool;
|
|
2392
3142
|
this.tool = null;
|
|
2393
|
-
|
|
3143
|
+
try {
|
|
3144
|
+
if (tool) await tool.close();
|
|
3145
|
+
} finally {
|
|
3146
|
+
await this.onShutdown?.();
|
|
3147
|
+
}
|
|
2394
3148
|
});
|
|
2395
3149
|
}
|
|
2396
3150
|
serialize(work) {
|
|
@@ -2754,6 +3508,28 @@ const toRelative = (cwd, changedPath) => {
|
|
|
2754
3508
|
};
|
|
2755
3509
|
//#endregion
|
|
2756
3510
|
//#region src/engine/LocalEngine.ts
|
|
3511
|
+
const defaultLog = (level, message) => {
|
|
3512
|
+
try {
|
|
3513
|
+
getLogger()[level](message);
|
|
3514
|
+
} catch {}
|
|
3515
|
+
};
|
|
3516
|
+
/**
|
|
3517
|
+
* Stream a web server's output live at debug level. Buffered regardless: the
|
|
3518
|
+
* tail is what explains a server that failed to start.
|
|
3519
|
+
*
|
|
3520
|
+
* To stderr, never stdout — `capture --json` owns stdout.
|
|
3521
|
+
*/
|
|
3522
|
+
const streamOutputAtDebug = (server, chunk) => {
|
|
3523
|
+
let level = 0;
|
|
3524
|
+
try {
|
|
3525
|
+
level = getLogger().level;
|
|
3526
|
+
} catch {
|
|
3527
|
+
return;
|
|
3528
|
+
}
|
|
3529
|
+
if (level < 4) return;
|
|
3530
|
+
const prefix = `[webServer ${server.url}] `;
|
|
3531
|
+
process.stderr.write(chunk.split(/(?<=\n)/).map((line) => prefix + line).join(""));
|
|
3532
|
+
};
|
|
2757
3533
|
/**
|
|
2758
3534
|
* `CaptureEngine` backed by an in-process Playwright browser.
|
|
2759
3535
|
*
|
|
@@ -2771,6 +3547,7 @@ var LocalEngine = class {
|
|
|
2771
3547
|
fileSystem;
|
|
2772
3548
|
browser;
|
|
2773
3549
|
runs;
|
|
3550
|
+
webServers;
|
|
2774
3551
|
/**
|
|
2775
3552
|
* Set synchronously the moment a run is claimed, before any `await`, so two
|
|
2776
3553
|
* concurrent `startRun` calls cannot both pass the check and then fight over
|
|
@@ -2798,9 +3575,16 @@ var LocalEngine = class {
|
|
|
2798
3575
|
this.plugins = options.plugins;
|
|
2799
3576
|
this.fileSystem = new ScreenshotFileSystem(options.outputDir);
|
|
2800
3577
|
this.runs = new RunStore(options.runStore);
|
|
3578
|
+
this.webServers = new WebServerPool({
|
|
3579
|
+
servers: options.webServer ?? [],
|
|
3580
|
+
log: defaultLog,
|
|
3581
|
+
onOutput: streamOutputAtDebug,
|
|
3582
|
+
...options.webServerPool
|
|
3583
|
+
});
|
|
2801
3584
|
this.browser = new WarmBrowser({
|
|
2802
3585
|
create: options.createScreenshotTool ?? (() => this.buildTool()),
|
|
2803
|
-
idleTimeoutMs: options.browserIdleTimeoutMs
|
|
3586
|
+
idleTimeoutMs: options.browserIdleTimeoutMs,
|
|
3587
|
+
onShutdown: () => this.webServers.stop()
|
|
2804
3588
|
});
|
|
2805
3589
|
}
|
|
2806
3590
|
buildTool() {
|
|
@@ -2850,7 +3634,9 @@ var LocalEngine = class {
|
|
|
2850
3634
|
screenshotTool: await this.browser.acquire(),
|
|
2851
3635
|
plugins: this.plugins,
|
|
2852
3636
|
outputDir: this.options.outputDir,
|
|
2853
|
-
fileSystem: this.fileSystem
|
|
3637
|
+
fileSystem: this.fileSystem,
|
|
3638
|
+
prepare: (log) => this.webServers.ensure(log),
|
|
3639
|
+
explainUnreachable: (origin) => this.webServers.explainUnreachable(origin)
|
|
2854
3640
|
});
|
|
2855
3641
|
const finish = () => {
|
|
2856
3642
|
if (this.activeRunId !== runner.id) return;
|
|
@@ -2988,7 +3774,11 @@ var LocalEngine = class {
|
|
|
2988
3774
|
this.closed = true;
|
|
2989
3775
|
await this.endWatch("engine-closed");
|
|
2990
3776
|
(this.activeRunId ? this.runs.getRunner(this.activeRunId) : void 0)?.abort();
|
|
2991
|
-
|
|
3777
|
+
try {
|
|
3778
|
+
await this.browser.close();
|
|
3779
|
+
} finally {
|
|
3780
|
+
await this.webServers.stop();
|
|
3781
|
+
}
|
|
2992
3782
|
}
|
|
2993
3783
|
async endWatch(reason) {
|
|
2994
3784
|
const session = this.watchSession;
|
|
@@ -3061,6 +3851,7 @@ var LocalEngine = class {
|
|
|
3061
3851
|
async discoverTargets() {
|
|
3062
3852
|
const tool = await this.browser.acquire();
|
|
3063
3853
|
try {
|
|
3854
|
+
await this.webServers.ensure();
|
|
3064
3855
|
const discovered = await Promise.all(this.plugins.map(async (plugin) => {
|
|
3065
3856
|
const tasks = await plugin.discover(tool);
|
|
3066
3857
|
return {
|
|
@@ -3156,6 +3947,668 @@ var FsScreenshotStore = class {
|
|
|
3156
3947
|
}
|
|
3157
3948
|
};
|
|
3158
3949
|
//#endregion
|
|
3159
|
-
|
|
3950
|
+
//#region src/agent/tiles.ts
|
|
3951
|
+
const LOCATOR_MAX_WIDTH = 400;
|
|
3952
|
+
const LOCATOR_MAX_HEIGHT = 1200;
|
|
3953
|
+
const GUTTER = 12;
|
|
3954
|
+
const ROW_GUTTER = 16;
|
|
3955
|
+
const LABEL_HEIGHT = 18;
|
|
3956
|
+
const BACKGROUND = {
|
|
3957
|
+
r: 128,
|
|
3958
|
+
g: 128,
|
|
3959
|
+
b: 128
|
|
3960
|
+
};
|
|
3961
|
+
const escapeXml = (text) => text.replace(/[<>&"]/g, (c) => `&#${c.charCodeAt(0)};`);
|
|
3962
|
+
/** A caption strip, so a row reads as "#2 expected | #2 actual" at a glance. */
|
|
3963
|
+
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>`);
|
|
3964
|
+
const padAndClamp = (bbox, padding, width, height) => {
|
|
3965
|
+
const padX = typeof padding === "number" ? padding : padding.x;
|
|
3966
|
+
const padY = typeof padding === "number" ? padding : padding.y;
|
|
3967
|
+
const x = Math.max(0, Math.floor(bbox.x - padX));
|
|
3968
|
+
const y = Math.max(0, Math.floor(bbox.y - padY));
|
|
3969
|
+
const right = Math.min(width, Math.ceil(bbox.x + bbox.width + padX));
|
|
3970
|
+
const bottom = Math.min(height, Math.ceil(bbox.y + bbox.height + padY));
|
|
3971
|
+
return {
|
|
3972
|
+
x,
|
|
3973
|
+
y,
|
|
3974
|
+
width: Math.max(1, right - x),
|
|
3975
|
+
height: Math.max(1, bottom - y)
|
|
3976
|
+
};
|
|
3977
|
+
};
|
|
3978
|
+
const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
|
|
3979
|
+
/**
|
|
3980
|
+
* Context kept around a region: proportional to its size, within bounds.
|
|
3981
|
+
*
|
|
3982
|
+
* A fixed margin is too tight for small regions — a changed letter cropped
|
|
3983
|
+
* with 24px around it says nothing about whether a button label got
|
|
3984
|
+
* truncated — and wasteful for large ones.
|
|
3985
|
+
*/
|
|
3986
|
+
const contextPadding = (bbox, minimum) => ({
|
|
3987
|
+
x: clamp(bbox.width, minimum * 2, 160),
|
|
3988
|
+
y: clamp(bbox.height, minimum, 96)
|
|
3989
|
+
});
|
|
3990
|
+
/** Scale that fits `width`x`height` into the bounds without upscaling. */
|
|
3991
|
+
const fitScale = (width, height, maxWidth, maxHeight) => Math.min(1, maxWidth / width, maxHeight / height);
|
|
3992
|
+
const readSize$1 = async (file) => {
|
|
3993
|
+
const { width, height } = await sharp(file).metadata();
|
|
3994
|
+
if (!width || !height) throw new Error(`Unable to read image dimensions: ${file}`);
|
|
3995
|
+
return {
|
|
3996
|
+
width,
|
|
3997
|
+
height
|
|
3998
|
+
};
|
|
3999
|
+
};
|
|
4000
|
+
const renderCrop = async (file, box, scale) => {
|
|
4001
|
+
const crop = sharp(file).extract({
|
|
4002
|
+
left: box.x,
|
|
4003
|
+
top: box.y,
|
|
4004
|
+
width: box.width,
|
|
4005
|
+
height: box.height
|
|
4006
|
+
});
|
|
4007
|
+
if (scale < 1) crop.resize(Math.max(1, Math.round(box.width * scale)), Math.max(1, Math.round(box.height * scale)));
|
|
4008
|
+
return crop.png().toBuffer();
|
|
4009
|
+
};
|
|
4010
|
+
const renderRegions = async (options, width, height) => {
|
|
4011
|
+
const padding = options.padding ?? 24;
|
|
4012
|
+
const maxCropWidth = options.maxCropWidth ?? 640;
|
|
4013
|
+
const regions = options.regions.slice(0, options.maxRegions ?? 8);
|
|
4014
|
+
if (regions.length === 0) return void 0;
|
|
4015
|
+
const rows = await Promise.all(regions.map(async (region) => {
|
|
4016
|
+
const box = padAndClamp(region, contextPadding(region, padding), width, height);
|
|
4017
|
+
const scale = Math.min(1, maxCropWidth / box.width);
|
|
4018
|
+
const [expected, actual] = await Promise.all([renderCrop(options.expectedPath, box, scale), renderCrop(options.actualPath, box, scale)]);
|
|
4019
|
+
return {
|
|
4020
|
+
expected,
|
|
4021
|
+
actual,
|
|
4022
|
+
width: Math.max(1, Math.round(box.width * scale)),
|
|
4023
|
+
height: Math.max(1, Math.round(box.height * scale))
|
|
4024
|
+
};
|
|
4025
|
+
}));
|
|
4026
|
+
const columnWidth = (row) => Math.max(row.width, 96);
|
|
4027
|
+
const canvasWidth = Math.max(...rows.map((row) => columnWidth(row) * 2 + GUTTER));
|
|
4028
|
+
const canvasHeight = rows.reduce((sum, row) => sum + LABEL_HEIGHT + row.height, 0) + ROW_GUTTER * (rows.length - 1);
|
|
4029
|
+
const composites = [];
|
|
4030
|
+
let top = 0;
|
|
4031
|
+
rows.forEach((row, index) => {
|
|
4032
|
+
const column = columnWidth(row);
|
|
4033
|
+
const right = column + GUTTER;
|
|
4034
|
+
composites.push({
|
|
4035
|
+
input: label(`#${index + 1} expected`, column),
|
|
4036
|
+
left: 0,
|
|
4037
|
+
top
|
|
4038
|
+
}, {
|
|
4039
|
+
input: label(`#${index + 1} actual`, column),
|
|
4040
|
+
left: right,
|
|
4041
|
+
top
|
|
4042
|
+
}, {
|
|
4043
|
+
input: row.expected,
|
|
4044
|
+
left: 0,
|
|
4045
|
+
top: top + LABEL_HEIGHT
|
|
4046
|
+
}, {
|
|
4047
|
+
input: row.actual,
|
|
4048
|
+
left: right,
|
|
4049
|
+
top: top + LABEL_HEIGHT
|
|
4050
|
+
});
|
|
4051
|
+
top += LABEL_HEIGHT + row.height + ROW_GUTTER;
|
|
4052
|
+
});
|
|
4053
|
+
const file = path.join(options.outDir, "regions.png");
|
|
4054
|
+
await sharp({ create: {
|
|
4055
|
+
width: canvasWidth,
|
|
4056
|
+
height: canvasHeight,
|
|
4057
|
+
channels: 3,
|
|
4058
|
+
background: BACKGROUND
|
|
4059
|
+
} }).composite(composites).png().toFile(file);
|
|
4060
|
+
return {
|
|
4061
|
+
file,
|
|
4062
|
+
count: rows.length
|
|
4063
|
+
};
|
|
4064
|
+
};
|
|
4065
|
+
const renderLocator = async (options, width, height) => {
|
|
4066
|
+
const scale = fitScale(width, height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT);
|
|
4067
|
+
const locatorWidth = Math.max(1, Math.round(width * scale));
|
|
4068
|
+
const locatorHeight = Math.max(1, Math.round(height * scale));
|
|
4069
|
+
const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${locatorWidth}" height="${locatorHeight}">${options.regions.map((region, index) => {
|
|
4070
|
+
const x = Math.round(region.x * scale);
|
|
4071
|
+
const y = Math.round(region.y * scale);
|
|
4072
|
+
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>`;
|
|
4073
|
+
}).join("")}</svg>`;
|
|
4074
|
+
const file = path.join(options.outDir, "locator.png");
|
|
4075
|
+
await sharp(options.diffPath ?? options.actualPath).resize(locatorWidth, locatorHeight, { fit: "fill" }).composite([{
|
|
4076
|
+
input: Buffer.from(svg),
|
|
4077
|
+
left: 0,
|
|
4078
|
+
top: 0
|
|
4079
|
+
}]).png().toFile(file);
|
|
4080
|
+
return file;
|
|
4081
|
+
};
|
|
4082
|
+
/**
|
|
4083
|
+
* Write `locator.png` and `regions.png` into `outDir`.
|
|
4084
|
+
*
|
|
4085
|
+
* Expected and actual must have the same dimensions — region boxes are only
|
|
4086
|
+
* meaningful when both images share a coordinate space. Use
|
|
4087
|
+
* {@link renderOverview} when they do not.
|
|
4088
|
+
*/
|
|
4089
|
+
const renderJudgmentTiles = async (options) => {
|
|
4090
|
+
const { width, height } = await readSize$1(options.actualPath);
|
|
4091
|
+
const [regions, locator] = await Promise.all([renderRegions(options, width, height), renderLocator(options, width, height)]);
|
|
4092
|
+
return {
|
|
4093
|
+
locator,
|
|
4094
|
+
regions: regions?.file,
|
|
4095
|
+
renderedRegions: regions?.count ?? 0
|
|
4096
|
+
};
|
|
4097
|
+
};
|
|
4098
|
+
/**
|
|
4099
|
+
* Write `overview.png`: expected and actual, scaled down side by side.
|
|
4100
|
+
*
|
|
4101
|
+
* For screenshots whose dimensions changed, where no region can be located,
|
|
4102
|
+
* this is what the judge looks at instead of two full-size images.
|
|
4103
|
+
*/
|
|
4104
|
+
const renderOverview = async (options) => {
|
|
4105
|
+
const [expectedSize, actualSize] = await Promise.all([readSize$1(options.expectedPath), readSize$1(options.actualPath)]);
|
|
4106
|
+
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));
|
|
4107
|
+
const scaled = (size) => ({
|
|
4108
|
+
width: Math.max(1, Math.round(size.width * scale)),
|
|
4109
|
+
height: Math.max(1, Math.round(size.height * scale))
|
|
4110
|
+
});
|
|
4111
|
+
const expected = scaled(expectedSize);
|
|
4112
|
+
const actual = scaled(actualSize);
|
|
4113
|
+
const [expectedBuffer, actualBuffer] = await Promise.all([sharp(options.expectedPath).resize(expected.width, expected.height, { fit: "fill" }).png().toBuffer(), sharp(options.actualPath).resize(actual.width, actual.height, { fit: "fill" }).png().toBuffer()]);
|
|
4114
|
+
const file = path.join(options.outDir, "overview.png");
|
|
4115
|
+
await sharp({ create: {
|
|
4116
|
+
width: expected.width + GUTTER + actual.width,
|
|
4117
|
+
height: LABEL_HEIGHT + Math.max(expected.height, actual.height),
|
|
4118
|
+
channels: 3,
|
|
4119
|
+
background: BACKGROUND
|
|
4120
|
+
} }).composite([
|
|
4121
|
+
{
|
|
4122
|
+
input: label(`expected ${expectedSize.width}x${expectedSize.height}`, expected.width),
|
|
4123
|
+
left: 0,
|
|
4124
|
+
top: 0
|
|
4125
|
+
},
|
|
4126
|
+
{
|
|
4127
|
+
input: label(`actual ${actualSize.width}x${actualSize.height}`, actual.width),
|
|
4128
|
+
left: expected.width + GUTTER,
|
|
4129
|
+
top: 0
|
|
4130
|
+
},
|
|
4131
|
+
{
|
|
4132
|
+
input: expectedBuffer,
|
|
4133
|
+
left: 0,
|
|
4134
|
+
top: LABEL_HEIGHT
|
|
4135
|
+
},
|
|
4136
|
+
{
|
|
4137
|
+
input: actualBuffer,
|
|
4138
|
+
left: expected.width + GUTTER,
|
|
4139
|
+
top: LABEL_HEIGHT
|
|
4140
|
+
}
|
|
4141
|
+
]).png().toFile(file);
|
|
4142
|
+
return file;
|
|
4143
|
+
};
|
|
4144
|
+
//#endregion
|
|
4145
|
+
//#region src/agent/review.ts
|
|
4146
|
+
/**
|
|
4147
|
+
* Agent review: turn the screenshots on disk into something a coding agent
|
|
4148
|
+
* can judge cheaply, and fold its judgments back in.
|
|
4149
|
+
*
|
|
4150
|
+
* Nothing here captures. It reads `actual/`, `expected/` and `diff/` as the
|
|
4151
|
+
* last `cappa capture` left them, so it is safe to run repeatedly — a re-run
|
|
4152
|
+
* is how an agent's verdicts are applied, and a re-capture invalidates them
|
|
4153
|
+
* automatically because every judgment is tied to a fingerprint of the two
|
|
4154
|
+
* images it was made about.
|
|
4155
|
+
*
|
|
4156
|
+
* Layout, all inside `<outputDir>/.cappa-agent/` (dot-prefixed, so neither
|
|
4157
|
+
* screenshot collection nor the review server's static handler touch it):
|
|
4158
|
+
*
|
|
4159
|
+
* ```
|
|
4160
|
+
* report.json full report of the last check
|
|
4161
|
+
* judgments/<name>/request.json what to judge and where the evidence is
|
|
4162
|
+
* judgments/<name>/locator.png thumbnail with every region outlined
|
|
4163
|
+
* judgments/<name>/regions.png [expected | actual] crop per region
|
|
4164
|
+
* judgments/<name>/overview.png instead of the two above when sizes differ
|
|
4165
|
+
* judgments/<name>/verdict.json written by the judge
|
|
4166
|
+
* ```
|
|
4167
|
+
*/
|
|
4168
|
+
const REQUEST_FILE = "request.json";
|
|
4169
|
+
const VERDICT_FILE = "verdict.json";
|
|
4170
|
+
const JUDGMENT_FILES = [
|
|
4171
|
+
REQUEST_FILE,
|
|
4172
|
+
VERDICT_FILE,
|
|
4173
|
+
"locator.png",
|
|
4174
|
+
"regions.png",
|
|
4175
|
+
"overview.png"
|
|
4176
|
+
];
|
|
4177
|
+
const JUDGE_MODES = [
|
|
4178
|
+
"ambiguous",
|
|
4179
|
+
"all",
|
|
4180
|
+
"none"
|
|
4181
|
+
];
|
|
4182
|
+
/**
|
|
4183
|
+
* The directory holding a screenshot's judgment.
|
|
4184
|
+
*
|
|
4185
|
+
* Screenshot names are relative paths (`example/button/primary`), so they map
|
|
4186
|
+
* onto nested directories directly; anything that would resolve outside the
|
|
4187
|
+
* judgments root is refused rather than written.
|
|
4188
|
+
*/
|
|
4189
|
+
const judgmentDir = (outputDir, name) => {
|
|
4190
|
+
const root = judgmentsRoot(outputDir);
|
|
4191
|
+
const dir = path.resolve(root, name);
|
|
4192
|
+
const relative = path.relative(root, dir);
|
|
4193
|
+
if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Invalid screenshot name for a judgment: ${name}`);
|
|
4194
|
+
return dir;
|
|
4195
|
+
};
|
|
4196
|
+
const exists = async (file) => {
|
|
4197
|
+
try {
|
|
4198
|
+
await fsp.access(file);
|
|
4199
|
+
return true;
|
|
4200
|
+
} catch {
|
|
4201
|
+
return false;
|
|
4202
|
+
}
|
|
4203
|
+
};
|
|
4204
|
+
const readJson = async (file) => {
|
|
4205
|
+
try {
|
|
4206
|
+
return JSON.parse(await fsp.readFile(file, "utf8"));
|
|
4207
|
+
} catch {
|
|
4208
|
+
return;
|
|
4209
|
+
}
|
|
4210
|
+
};
|
|
4211
|
+
const writeJson = async (file, value) => {
|
|
4212
|
+
await fsp.mkdir(path.dirname(file), { recursive: true });
|
|
4213
|
+
await fsp.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
|
|
4214
|
+
};
|
|
4215
|
+
/** Ties a judgment to the exact pair of images it was made about. */
|
|
4216
|
+
const fingerprintImages = async (expectedPath, actualPath) => {
|
|
4217
|
+
const [expected, actual] = await Promise.all([fsp.readFile(expectedPath), fsp.readFile(actualPath)]);
|
|
4218
|
+
return createHash("sha256").update(expected).update("\0").update(actual).digest("hex");
|
|
4219
|
+
};
|
|
4220
|
+
/**
|
|
4221
|
+
* Read a judge's verdict, accepting both the nested shape blazediff uses
|
|
4222
|
+
* (`{ verdict: { label, headline, rationale }, confidence }`) and a flat one
|
|
4223
|
+
* (`{ label, headline, rationale, confidence }`) — a judge that writes either
|
|
4224
|
+
* should not have its work thrown away over nesting.
|
|
4225
|
+
*/
|
|
4226
|
+
const parseAgentVerdict = (raw) => {
|
|
4227
|
+
if (typeof raw !== "object" || raw === null) return {
|
|
4228
|
+
ok: false,
|
|
4229
|
+
error: "verdict.json is not a JSON object"
|
|
4230
|
+
};
|
|
4231
|
+
const outer = raw;
|
|
4232
|
+
const inner = typeof outer.verdict === "object" && outer.verdict !== null ? outer.verdict : outer;
|
|
4233
|
+
const label = inner.label;
|
|
4234
|
+
if (!isJudgedLabel(label)) return {
|
|
4235
|
+
ok: false,
|
|
4236
|
+
error: `label must be one of regression-likely, intentional-likely, noise-likely (got ${JSON.stringify(label)})`
|
|
4237
|
+
};
|
|
4238
|
+
const headline = typeof inner.headline === "string" && inner.headline.trim() ? inner.headline.trim() : void 0;
|
|
4239
|
+
if (!headline) return {
|
|
4240
|
+
ok: false,
|
|
4241
|
+
error: "headline must be a non-empty string"
|
|
4242
|
+
};
|
|
4243
|
+
const toLines = (value) => Array.isArray(value) ? value.filter((line) => typeof line === "string") : typeof value === "string" && value.trim() ? [value.trim()] : [];
|
|
4244
|
+
const rationale = [...toLines(inner.rationale)];
|
|
4245
|
+
if (inner !== outer) rationale.push(...toLines(outer.rationale));
|
|
4246
|
+
const rawConfidence = outer.confidence ?? inner.confidence;
|
|
4247
|
+
const confidence = typeof rawConfidence === "number" && Number.isFinite(rawConfidence) ? Math.min(1, Math.max(0, rawConfidence)) : void 0;
|
|
4248
|
+
return {
|
|
4249
|
+
ok: true,
|
|
4250
|
+
label,
|
|
4251
|
+
headline,
|
|
4252
|
+
rationale,
|
|
4253
|
+
...confidence !== void 0 ? { confidence } : {}
|
|
4254
|
+
};
|
|
4255
|
+
};
|
|
4256
|
+
const readSize = async (file) => {
|
|
4257
|
+
const { width = 0, height = 0 } = await sharp(file).metadata();
|
|
4258
|
+
return {
|
|
4259
|
+
width,
|
|
4260
|
+
height
|
|
4261
|
+
};
|
|
4262
|
+
};
|
|
4263
|
+
const toAgentRegions = (regions) => [...regions].sort((a, b) => b.pixelCount - a.pixelCount).map((region, index) => ({
|
|
4264
|
+
index: index + 1,
|
|
4265
|
+
bbox: {
|
|
4266
|
+
x: region.bbox.x,
|
|
4267
|
+
y: region.bbox.y,
|
|
4268
|
+
width: region.bbox.width,
|
|
4269
|
+
height: region.bbox.height
|
|
4270
|
+
},
|
|
4271
|
+
pixelCount: region.pixelCount,
|
|
4272
|
+
percentage: region.percentage,
|
|
4273
|
+
position: region.position,
|
|
4274
|
+
shape: region.shape,
|
|
4275
|
+
changeType: normalizeChangeType(region.changeType),
|
|
4276
|
+
confidence: region.confidence
|
|
4277
|
+
}));
|
|
4278
|
+
/**
|
|
4279
|
+
* The interpretation a capture already persisted, or a fresh one.
|
|
4280
|
+
*
|
|
4281
|
+
* `diff.interpret` is off by default, so most changed screenshots arrive
|
|
4282
|
+
* without one; computing it here means agent review works on any project
|
|
4283
|
+
* rather than only on those that opted into interpretation at capture time.
|
|
4284
|
+
*/
|
|
4285
|
+
const interpretationFor = async (screenshot, expectedPath, actualPath, diff) => {
|
|
4286
|
+
if (screenshot.diffMeta?.interpretation) return screenshot.diffMeta.interpretation;
|
|
4287
|
+
const pixel = diff && diff.type !== "gmsd" ? diff : void 0;
|
|
4288
|
+
try {
|
|
4289
|
+
return await interpret(expectedPath, actualPath, void 0, {
|
|
4290
|
+
source: "pixel",
|
|
4291
|
+
threshold: pixel?.threshold,
|
|
4292
|
+
antialiasing: pixel?.includeAA ?? false
|
|
4293
|
+
});
|
|
4294
|
+
} catch {
|
|
4295
|
+
return;
|
|
4296
|
+
}
|
|
4297
|
+
};
|
|
4298
|
+
const JUDGE_INSTRUCTIONS = [
|
|
4299
|
+
"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.",
|
|
4300
|
+
"Open overview.png when it exists instead — the image dimensions changed, so no regions could be located.",
|
|
4301
|
+
"Only open paths.expected / paths.actual / paths.diff (full size) when a change clearly continues outside its crop.",
|
|
4302
|
+
"Write verdict.json next to this file, or run `cappa agent judge <name> --label <label> --headline <text>`."
|
|
4303
|
+
];
|
|
4304
|
+
const VERDICT_SCHEMA = {
|
|
4305
|
+
label: "regression-likely | intentional-likely | noise-likely",
|
|
4306
|
+
headline: "one line describing what changed",
|
|
4307
|
+
rationale: ["short reasons"],
|
|
4308
|
+
confidence: "0..1"
|
|
4309
|
+
};
|
|
4310
|
+
const analyseChanged = async (screenshot, options, createdAt) => {
|
|
4311
|
+
const { outputDir } = options;
|
|
4312
|
+
const expectedPath = path.resolve(outputDir, screenshot.expectedPath);
|
|
4313
|
+
const actualPath = path.resolve(outputDir, screenshot.actualPath);
|
|
4314
|
+
const diffPath = path.resolve(outputDir, screenshot.diffPath);
|
|
4315
|
+
const [expectedSize, actualSize, diffExists] = await Promise.all([
|
|
4316
|
+
readSize(expectedPath),
|
|
4317
|
+
readSize(actualPath),
|
|
4318
|
+
exists(diffPath)
|
|
4319
|
+
]);
|
|
4320
|
+
const differentSizes = expectedSize.width !== actualSize.width || expectedSize.height !== actualSize.height;
|
|
4321
|
+
const interpretation = differentSizes ? void 0 : await interpretationFor(screenshot, expectedPath, actualPath, options.diff);
|
|
4322
|
+
const percentDifference = screenshot.diffMeta?.percentDifference ?? interpretation?.diffPercentage;
|
|
4323
|
+
const numDiffPixels = screenshot.diffMeta?.numDiffPixels ?? interpretation?.diffCount;
|
|
4324
|
+
const regions = toAgentRegions(interpretation?.regions ?? []);
|
|
4325
|
+
const heuristic = deriveVerdict({
|
|
4326
|
+
percentDifference,
|
|
4327
|
+
numDiffPixels,
|
|
4328
|
+
interpretation,
|
|
4329
|
+
differentSizes
|
|
4330
|
+
});
|
|
4331
|
+
const entry = {
|
|
4332
|
+
name: screenshot.name,
|
|
4333
|
+
category: "changed",
|
|
4334
|
+
...screenshot.taskId ? {
|
|
4335
|
+
taskId: screenshot.taskId,
|
|
4336
|
+
plugin: screenshot.plugin
|
|
4337
|
+
} : {},
|
|
4338
|
+
paths: {
|
|
4339
|
+
expected: expectedPath,
|
|
4340
|
+
actual: actualPath,
|
|
4341
|
+
...diffExists ? { diff: diffPath } : {}
|
|
4342
|
+
},
|
|
4343
|
+
percentDifference,
|
|
4344
|
+
numDiffPixels,
|
|
4345
|
+
dimensions: {
|
|
4346
|
+
expected: expectedSize,
|
|
4347
|
+
actual: actualSize
|
|
4348
|
+
},
|
|
4349
|
+
severity: interpretation?.severity?.toLowerCase(),
|
|
4350
|
+
summary: interpretation?.summary,
|
|
4351
|
+
regions,
|
|
4352
|
+
heuristic,
|
|
4353
|
+
verdict: {
|
|
4354
|
+
...heuristic,
|
|
4355
|
+
source: "heuristic"
|
|
4356
|
+
},
|
|
4357
|
+
pending: false
|
|
4358
|
+
};
|
|
4359
|
+
const dir = judgmentDir(outputDir, screenshot.name);
|
|
4360
|
+
const requestPath = path.join(dir, REQUEST_FILE);
|
|
4361
|
+
const verdictPath = path.join(dir, VERDICT_FILE);
|
|
4362
|
+
if (!(options.judge === "all" || options.judge === "ambiguous" && heuristic.label === "ambiguous" || await exists(requestPath))) return entry;
|
|
4363
|
+
const fingerprint = await fingerprintImages(expectedPath, actualPath);
|
|
4364
|
+
const previous = await readJson(requestPath);
|
|
4365
|
+
if (previous && previous.fingerprint !== fingerprint) await clearJudgmentFiles(dir);
|
|
4366
|
+
await fsp.mkdir(dir, { recursive: true });
|
|
4367
|
+
const judgment = {
|
|
4368
|
+
dir,
|
|
4369
|
+
request: requestPath,
|
|
4370
|
+
verdict: verdictPath
|
|
4371
|
+
};
|
|
4372
|
+
if (differentSizes) judgment.overview = await renderOverview({
|
|
4373
|
+
expectedPath,
|
|
4374
|
+
actualPath,
|
|
4375
|
+
outDir: dir
|
|
4376
|
+
});
|
|
4377
|
+
else {
|
|
4378
|
+
const tiles = await renderJudgmentTiles({
|
|
4379
|
+
expectedPath,
|
|
4380
|
+
actualPath,
|
|
4381
|
+
diffPath: diffExists ? diffPath : void 0,
|
|
4382
|
+
regions: regions.map((region) => region.bbox),
|
|
4383
|
+
outDir: dir,
|
|
4384
|
+
maxRegions: options.maxTileRegions
|
|
4385
|
+
});
|
|
4386
|
+
if (tiles.locator) judgment.locator = tiles.locator;
|
|
4387
|
+
if (tiles.regions) judgment.regions = tiles.regions;
|
|
4388
|
+
}
|
|
4389
|
+
entry.judgment = judgment;
|
|
4390
|
+
await writeJson(requestPath, {
|
|
4391
|
+
version: 1,
|
|
4392
|
+
name: entry.name,
|
|
4393
|
+
taskId: entry.taskId,
|
|
4394
|
+
plugin: entry.plugin,
|
|
4395
|
+
fingerprint,
|
|
4396
|
+
createdAt,
|
|
4397
|
+
instructions: JUDGE_INSTRUCTIONS,
|
|
4398
|
+
verdictSchema: VERDICT_SCHEMA,
|
|
4399
|
+
heuristic,
|
|
4400
|
+
percentDifference,
|
|
4401
|
+
numDiffPixels,
|
|
4402
|
+
dimensions: entry.dimensions,
|
|
4403
|
+
severity: entry.severity,
|
|
4404
|
+
summary: entry.summary,
|
|
4405
|
+
regions,
|
|
4406
|
+
paths: {
|
|
4407
|
+
locator: judgment.locator,
|
|
4408
|
+
regions: judgment.regions,
|
|
4409
|
+
overview: judgment.overview,
|
|
4410
|
+
expected: expectedPath,
|
|
4411
|
+
actual: actualPath,
|
|
4412
|
+
diff: entry.paths.diff,
|
|
4413
|
+
verdict: verdictPath
|
|
4414
|
+
}
|
|
4415
|
+
});
|
|
4416
|
+
if (!await exists(verdictPath)) {
|
|
4417
|
+
entry.pending = true;
|
|
4418
|
+
return entry;
|
|
4419
|
+
}
|
|
4420
|
+
const parsed = parseAgentVerdict(await readJson(verdictPath));
|
|
4421
|
+
if (!parsed.ok) {
|
|
4422
|
+
entry.pending = true;
|
|
4423
|
+
entry.verdictError = parsed.error;
|
|
4424
|
+
return entry;
|
|
4425
|
+
}
|
|
4426
|
+
entry.verdict = {
|
|
4427
|
+
label: parsed.label,
|
|
4428
|
+
headline: parsed.headline,
|
|
4429
|
+
rationale: parsed.rationale,
|
|
4430
|
+
action: ACTION_BY_LABEL[parsed.label],
|
|
4431
|
+
source: "agent",
|
|
4432
|
+
...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
|
|
4433
|
+
};
|
|
4434
|
+
return entry;
|
|
4435
|
+
};
|
|
4436
|
+
const clearJudgmentFiles = async (dir) => {
|
|
4437
|
+
await Promise.all(JUDGMENT_FILES.map((file) => fsp.rm(path.join(dir, file), { force: true })));
|
|
4438
|
+
};
|
|
4439
|
+
/**
|
|
4440
|
+
* Remove a screenshot's judgment — after it was approved, or because it is no
|
|
4441
|
+
* longer changed. Only the judgment's own files go: a directory can also be
|
|
4442
|
+
* the parent of another screenshot's judgment (`button` and `button/primary`).
|
|
4443
|
+
*/
|
|
4444
|
+
const clearJudgment = async (outputDir, name) => {
|
|
4445
|
+
const dir = judgmentDir(outputDir, name);
|
|
4446
|
+
await clearJudgmentFiles(dir);
|
|
4447
|
+
await removeEmptyDirs(dir, judgmentsRoot(outputDir));
|
|
4448
|
+
};
|
|
4449
|
+
/** Remove `dir` and its parents up to (excluding) `root` while empty. */
|
|
4450
|
+
const removeEmptyDirs = async (dir, root) => {
|
|
4451
|
+
let current = dir;
|
|
4452
|
+
while (current !== root && current.startsWith(root)) {
|
|
4453
|
+
try {
|
|
4454
|
+
await fsp.rmdir(current);
|
|
4455
|
+
} catch {
|
|
4456
|
+
return;
|
|
4457
|
+
}
|
|
4458
|
+
current = path.dirname(current);
|
|
4459
|
+
}
|
|
4460
|
+
};
|
|
4461
|
+
const listRequestDirs = async (root) => {
|
|
4462
|
+
if (!await exists(root)) return [];
|
|
4463
|
+
return (await Array.fromAsync(fsp.glob(`**/${REQUEST_FILE}`, { cwd: root }))).map((file) => path.resolve(root, path.dirname(file)));
|
|
4464
|
+
};
|
|
4465
|
+
/** Drop judgments for screenshots that no longer need one. */
|
|
4466
|
+
const pruneJudgments = async (outputDir, keep) => {
|
|
4467
|
+
const root = judgmentsRoot(outputDir);
|
|
4468
|
+
for (const dir of await listRequestDirs(root)) {
|
|
4469
|
+
if (keep.has(dir)) continue;
|
|
4470
|
+
await clearJudgmentFiles(dir);
|
|
4471
|
+
await removeEmptyDirs(dir, root);
|
|
4472
|
+
}
|
|
4473
|
+
};
|
|
4474
|
+
/**
|
|
4475
|
+
* Analyse every non-passing screenshot, write judgment requests for the ones
|
|
4476
|
+
* that need a judge, apply any verdicts already written, and persist the
|
|
4477
|
+
* full report to `<outputDir>/.cappa-agent/report.json`.
|
|
4478
|
+
*/
|
|
4479
|
+
const runAgentCheck = async (options) => {
|
|
4480
|
+
const outputDir = path.resolve(options.outputDir);
|
|
4481
|
+
const judge = options.judge ?? "ambiguous";
|
|
4482
|
+
const createdAt = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
|
|
4483
|
+
const screenshots = await collectScreenshots(outputDir);
|
|
4484
|
+
await fsp.mkdir(agentDir(outputDir), { recursive: true });
|
|
4485
|
+
await fsp.writeFile(path.join(agentDir(outputDir), ".gitignore"), "*\n");
|
|
4486
|
+
const changed = screenshots.filter((s) => s.category === "changed");
|
|
4487
|
+
const changedEntries = await mapWithConcurrency(options.concurrency ?? 4, changed, (screenshot) => analyseChanged(screenshot, {
|
|
4488
|
+
...options,
|
|
4489
|
+
outputDir,
|
|
4490
|
+
judge
|
|
4491
|
+
}, createdAt));
|
|
4492
|
+
await pruneJudgments(outputDir, new Set(changedEntries.flatMap((entry) => entry.judgment ? [entry.judgment.dir] : [])));
|
|
4493
|
+
const otherEntries = screenshots.flatMap((s) => {
|
|
4494
|
+
if (s.category === "new") return [{
|
|
4495
|
+
name: s.name,
|
|
4496
|
+
category: "new",
|
|
4497
|
+
...s.taskId ? {
|
|
4498
|
+
taskId: s.taskId,
|
|
4499
|
+
plugin: s.plugin
|
|
4500
|
+
} : {},
|
|
4501
|
+
paths: { actual: path.resolve(outputDir, s.actualPath) },
|
|
4502
|
+
pending: false
|
|
4503
|
+
}];
|
|
4504
|
+
if (s.category === "deleted") return [{
|
|
4505
|
+
name: s.name,
|
|
4506
|
+
category: "deleted",
|
|
4507
|
+
paths: { expected: path.resolve(outputDir, s.expectedPath) },
|
|
4508
|
+
pending: false
|
|
4509
|
+
}];
|
|
4510
|
+
return [];
|
|
4511
|
+
});
|
|
4512
|
+
const entries = [...changedEntries, ...otherEntries];
|
|
4513
|
+
const count = (category) => screenshots.filter((s) => s.category === category).length;
|
|
4514
|
+
const report = {
|
|
4515
|
+
version: 1,
|
|
4516
|
+
createdAt,
|
|
4517
|
+
outputDir,
|
|
4518
|
+
reportPath: agentReportPath(outputDir),
|
|
4519
|
+
judge,
|
|
4520
|
+
totals: {
|
|
4521
|
+
total: screenshots.length,
|
|
4522
|
+
passed: count("passed"),
|
|
4523
|
+
changed: count("changed"),
|
|
4524
|
+
new: count("new"),
|
|
4525
|
+
deleted: count("deleted"),
|
|
4526
|
+
pendingJudgments: entries.filter((entry) => entry.pending).length
|
|
4527
|
+
},
|
|
4528
|
+
entries
|
|
4529
|
+
};
|
|
4530
|
+
await writeJson(report.reportPath, report);
|
|
4531
|
+
return report;
|
|
4532
|
+
};
|
|
4533
|
+
/** Read the report the last {@link runAgentCheck} wrote, if any. */
|
|
4534
|
+
const readAgentReport = async (outputDir) => {
|
|
4535
|
+
const raw = await readJson(agentReportPath(outputDir));
|
|
4536
|
+
return raw?.version === 1 ? raw : void 0;
|
|
4537
|
+
};
|
|
4538
|
+
/**
|
|
4539
|
+
* The report as an agent should first see it: one line of state per
|
|
4540
|
+
* screenshot, with the detail left in `report.json` and the judgment
|
|
4541
|
+
* requests for when it is actually needed.
|
|
4542
|
+
*/
|
|
4543
|
+
const toSlimAgentReport = (report) => ({
|
|
4544
|
+
reportPath: report.reportPath,
|
|
4545
|
+
...report.totals,
|
|
4546
|
+
results: report.entries.map((entry) => ({
|
|
4547
|
+
name: entry.name,
|
|
4548
|
+
category: entry.category,
|
|
4549
|
+
...entry.verdict ? { verdict: {
|
|
4550
|
+
label: entry.verdict.label,
|
|
4551
|
+
headline: entry.verdict.headline,
|
|
4552
|
+
action: entry.verdict.action,
|
|
4553
|
+
source: entry.verdict.source
|
|
4554
|
+
} } : {},
|
|
4555
|
+
...entry.pending ? { pending: true } : {},
|
|
4556
|
+
...entry.pending && entry.judgment ? { judgment: entry.judgment.dir } : {},
|
|
4557
|
+
...entry.verdictError ? { verdictError: entry.verdictError } : {}
|
|
4558
|
+
}))
|
|
4559
|
+
});
|
|
4560
|
+
/**
|
|
4561
|
+
* Record a judge's verdict for a screenshot with a pending request — the
|
|
4562
|
+
* validated alternative to hand-writing `verdict.json`.
|
|
4563
|
+
*/
|
|
4564
|
+
const writeAgentVerdict = async (outputDir, name, input) => {
|
|
4565
|
+
const dir = judgmentDir(outputDir, name);
|
|
4566
|
+
if (!await exists(path.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).`);
|
|
4567
|
+
const parsed = parseAgentVerdict(input);
|
|
4568
|
+
if (!parsed.ok) throw new Error(parsed.error);
|
|
4569
|
+
const verdictPath = path.join(dir, VERDICT_FILE);
|
|
4570
|
+
await writeJson(verdictPath, {
|
|
4571
|
+
name,
|
|
4572
|
+
verdict: {
|
|
4573
|
+
label: parsed.label,
|
|
4574
|
+
headline: parsed.headline,
|
|
4575
|
+
rationale: parsed.rationale,
|
|
4576
|
+
action: ACTION_BY_LABEL[parsed.label]
|
|
4577
|
+
},
|
|
4578
|
+
...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
|
|
4579
|
+
});
|
|
4580
|
+
return verdictPath;
|
|
4581
|
+
};
|
|
4582
|
+
//#endregion
|
|
4583
|
+
//#region src/webServer/resolve.ts
|
|
4584
|
+
const DEFAULT_WEB_SERVER_TIMEOUT_MS = 6e4;
|
|
4585
|
+
const isHttpUrl = (value) => URL.canParse(value) && ["http:", "https:"].includes(new URL(value).protocol);
|
|
4586
|
+
/**
|
|
4587
|
+
* Normalise `webServer` to a list with every default applied.
|
|
4588
|
+
*
|
|
4589
|
+
* A relative `cwd` resolves against `configDir` — the directory of
|
|
4590
|
+
* `cappa.config.ts` — not the process's working directory, so the same config
|
|
4591
|
+
* works whether cappa runs from the repository root or from inside the package
|
|
4592
|
+
* (`pnpm -F visual-tests cappa capture`).
|
|
4593
|
+
*/
|
|
4594
|
+
function resolveWebServerConfig(webServer, configDir, env = process.env) {
|
|
4595
|
+
if (webServer === void 0) return [];
|
|
4596
|
+
return (Array.isArray(webServer) ? webServer : [webServer]).map((entry, index) => {
|
|
4597
|
+
const where = Array.isArray(webServer) ? `webServer[${index}]` : "webServer";
|
|
4598
|
+
if (typeof entry?.command !== "string" || entry.command.trim() === "") throw new Error(`Invalid configuration: ${where}.command is required.`);
|
|
4599
|
+
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".`);
|
|
4600
|
+
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.`);
|
|
4601
|
+
return {
|
|
4602
|
+
command: entry.command,
|
|
4603
|
+
url: entry.url,
|
|
4604
|
+
reuseExistingServer: entry.reuseExistingServer ?? !env.CI,
|
|
4605
|
+
timeout: entry.timeout ?? 6e4,
|
|
4606
|
+
cwd: path.resolve(configDir, entry.cwd ?? "."),
|
|
4607
|
+
env: entry.env ?? {}
|
|
4608
|
+
};
|
|
4609
|
+
});
|
|
4610
|
+
}
|
|
4611
|
+
//#endregion
|
|
4612
|
+
export { ACTION_BY_LABEL, AGENT_DIRNAME, AGENT_REPORT_VERSION, CONSOLE_LOG_LEVELS, CaptureRunner, DEFAULT_DEBOUNCE_MS, DEFAULT_IGNORED_DIRS, DEFAULT_KILL_GRACE_MS, DEFAULT_MAX_TASKS, DEFAULT_WEB_SERVER_TIMEOUT_MS, ENGINE_ERROR_CODES, FsScreenshotStore, JUDGED_LABELS, JUDGE_MODES, LocalEngine, MANIFEST_FILENAME, MANIFEST_VERSION, NO_WEB_SERVER_HINT, OutputTail, RunInProgressError, RunStore, SUB_PERCEPTUAL_PERCENT, ScreenshotFileSystem, ScreenshotTool, UnknownTargetsError, VERDICT_LABELS, WarmBrowser, WatchInProgressError, WatchSession, WebServerError, WebServerPool, agentDir, agentReportPath, attachConsoleLogging, buildHeadline, clearJudgment, collectScreenshots, compareImages, compareImagesGMSD, contextPadding, defineConfig, deriveVerdict, didScreenshotFail, filterTasks, findRefusedConnection, fingerprintImages, getDeletedScreenshots, groupScreenshots, imagesMatch, imagesMatchGMSD, isJudgedLabel, isRunInProgressError, isUnknownTargetsError, isUrlReady, isVerdictLabel, isWatchInProgressError, judgmentDir, mapWithConcurrency, mergeCaptureManifest, normalizeChangeType, padAndClamp, parseAgentVerdict, readAgentReport, readCaptureManifest, readDiffMeta, recordCaptureOrigins, renderJudgmentTiles, renderOverview, resolveWebServerConfig, runAgentCheck, sameServer, sanitizeScreenshotFilename, selectTasks, spawnServerProcess, toConsoleLogLevel, toDiffMetaPath, toManifestKey, toSerializedError, toSlimAgentReport, toTaskStatus, waitForUrl, writeAgentVerdict };
|
|
3160
4613
|
|
|
3161
4614
|
//# sourceMappingURL=index.mjs.map
|