@cappa/core 0.17.0 → 0.19.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 +439 -181
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +146 -77
- package/dist/index.d.mts +146 -77
- package/dist/index.mjs +433 -177
- package/dist/index.mjs.map +1 -1
- package/dist/playwright.cjs +77 -0
- package/dist/playwright.cjs.map +1 -0
- package/dist/playwright.d.cts +117 -0
- package/dist/playwright.d.mts +117 -0
- package/dist/playwright.mjs +73 -0
- package/dist/playwright.mjs.map +1 -0
- package/package.json +6 -2
package/dist/index.mjs
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { DEFAULT_CONTAINER_IMAGE, playwright, resolveBrowserConfig, resolveContainerOptions } from "./playwright.mjs";
|
|
2
|
+
import { createRequire } from "node:module";
|
|
3
|
+
import fs, { realpathSync } from "node:fs";
|
|
2
4
|
import gmsd from "@blazediff/gmsd";
|
|
3
5
|
import { getLogger } from "@cappa/logger";
|
|
4
6
|
import fsp, { glob, open, readFile, writeFile } from "node:fs/promises";
|
|
@@ -7,9 +9,9 @@ import os from "node:os";
|
|
|
7
9
|
import path, { relative } from "node:path";
|
|
8
10
|
import { compare } from "@blazediff/core-native";
|
|
9
11
|
import { interpret } from "@blazediff/interpret-native";
|
|
12
|
+
import { execFile, execFileSync, spawn } from "node:child_process";
|
|
10
13
|
import { createHash, randomUUID } from "node:crypto";
|
|
11
14
|
import { chromium, firefox, webkit } from "playwright-core";
|
|
12
|
-
import { execFile, execFileSync, spawn } from "node:child_process";
|
|
13
15
|
//#region \0rolldown/runtime.js
|
|
14
16
|
var __defProp = Object.defineProperty;
|
|
15
17
|
var __exportAll = (all, no_symbols) => {
|
|
@@ -683,6 +685,242 @@ const attachConsoleLogging = (page, setting, logger) => {
|
|
|
683
685
|
});
|
|
684
686
|
};
|
|
685
687
|
//#endregion
|
|
688
|
+
//#region src/container.ts
|
|
689
|
+
/**
|
|
690
|
+
* Runs the official Playwright image for an exact `playwright-core` version
|
|
691
|
+
* through a container CLI (docker, podman, nerdctl, …) and hands back the
|
|
692
|
+
* `run-server` endpoint.
|
|
693
|
+
*
|
|
694
|
+
* Only subcommands all of those CLIs share are used: `version`, `image
|
|
695
|
+
* inspect`, `pull`, `inspect`, `run`, `port`, `logs`, `ps` and `rm`.
|
|
696
|
+
*/
|
|
697
|
+
/** Label on every container cappa starts; `removePlaywrightContainers` finds them by it. */
|
|
698
|
+
const CONTAINER_LABEL = "dev.cappa.playwright";
|
|
699
|
+
/** Port `run-server` listens on inside the container. */
|
|
700
|
+
const SERVER_PORT = 3e3;
|
|
701
|
+
/** Where the host's `playwright-core` is mounted inside the container. */
|
|
702
|
+
const PACKAGE_MOUNT = "/opt/playwright-core";
|
|
703
|
+
const defaultExec = (file, args) => new Promise((resolve, reject) => {
|
|
704
|
+
execFile(file, args, {
|
|
705
|
+
maxBuffer: 16777216,
|
|
706
|
+
windowsHide: true
|
|
707
|
+
}, (error, stdout, stderr) => {
|
|
708
|
+
if (error) reject(Object.assign(error, {
|
|
709
|
+
stdout,
|
|
710
|
+
stderr
|
|
711
|
+
}));
|
|
712
|
+
else resolve({
|
|
713
|
+
stdout: String(stdout),
|
|
714
|
+
stderr: String(stderr)
|
|
715
|
+
});
|
|
716
|
+
});
|
|
717
|
+
});
|
|
718
|
+
/** `true` once `run-server` answers plain HTTP with `Running`. */
|
|
719
|
+
const defaultProbe = async (url) => {
|
|
720
|
+
try {
|
|
721
|
+
const response = await fetch(url, { signal: AbortSignal.timeout(2e3) });
|
|
722
|
+
return response.ok && (await response.text()).includes("Running");
|
|
723
|
+
} catch {
|
|
724
|
+
return false;
|
|
725
|
+
}
|
|
726
|
+
};
|
|
727
|
+
const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
728
|
+
const errorText = (error) => {
|
|
729
|
+
const stderr = error?.stderr;
|
|
730
|
+
if (typeof stderr === "string" && stderr.trim()) return stderr.trim();
|
|
731
|
+
return error instanceof Error ? error.message : String(error);
|
|
732
|
+
};
|
|
733
|
+
const isNotFound = (error) => error?.code === "ENOENT";
|
|
734
|
+
/** `{version}` filled in. */
|
|
735
|
+
const containerImage = (image, version) => image.replaceAll("{version}", version);
|
|
736
|
+
/**
|
|
737
|
+
* Deterministic per version, image and run arguments: changing any of them
|
|
738
|
+
* starts a fresh container instead of reusing one with stale settings.
|
|
739
|
+
*/
|
|
740
|
+
const containerName = (version, image, runArgs, packageDir = "") => {
|
|
741
|
+
const hash = createHash("sha256").update(JSON.stringify([
|
|
742
|
+
image,
|
|
743
|
+
runArgs,
|
|
744
|
+
packageDir
|
|
745
|
+
])).digest("hex").slice(0, 8);
|
|
746
|
+
return `cappa-playwright-v${version.replace(/[^\w.-]/g, "_")}-${hash}`;
|
|
747
|
+
};
|
|
748
|
+
/** Host port from `<cli> port` output (`127.0.0.1:49153`, maybe several lines). */
|
|
749
|
+
const parsePort = (output) => {
|
|
750
|
+
for (const line of output.split("\n")) {
|
|
751
|
+
const match = line.trim().match(/:(\d+)$/);
|
|
752
|
+
if (match) return Number(match[1]);
|
|
753
|
+
}
|
|
754
|
+
return null;
|
|
755
|
+
};
|
|
756
|
+
/**
|
|
757
|
+
* Start — or reuse — the Playwright server container for `version` and wait
|
|
758
|
+
* until it accepts connections.
|
|
759
|
+
*/
|
|
760
|
+
async function ensurePlaywrightContainer(options) {
|
|
761
|
+
const { version, packageDir, cli, runArgs, readyTimeout, log = () => {}, exec = defaultExec, probe = defaultProbe, sleep = defaultSleep, now = Date.now } = options;
|
|
762
|
+
const image = containerImage(options.image, version);
|
|
763
|
+
const name = containerName(version, image, runArgs, packageDir);
|
|
764
|
+
const deadline = now() + readyTimeout;
|
|
765
|
+
const run = async (args) => {
|
|
766
|
+
try {
|
|
767
|
+
return await exec(cli, args);
|
|
768
|
+
} catch (error) {
|
|
769
|
+
if (isNotFound(error)) throw new Error(`Container CLI "${cli}" not found. Install it, or set playwright({ container: { cli } }) / CAPPA_CONTAINER_CLI to the one you use (docker, podman, nerdctl).`, { cause: error });
|
|
770
|
+
throw error;
|
|
771
|
+
}
|
|
772
|
+
};
|
|
773
|
+
try {
|
|
774
|
+
await run(["version"]);
|
|
775
|
+
} catch (error) {
|
|
776
|
+
if (error instanceof Error && error.message.startsWith("Container CLI")) throw error;
|
|
777
|
+
throw new Error(`"${cli} version" failed.${cli === "podman" ? " Is the podman machine running (`podman machine start`)?" : " Is the daemon running?"}\n\n${errorText(error)}`, { cause: error });
|
|
778
|
+
}
|
|
779
|
+
const state = async () => {
|
|
780
|
+
try {
|
|
781
|
+
const { stdout } = await run([
|
|
782
|
+
"inspect",
|
|
783
|
+
"--format",
|
|
784
|
+
"{{.State.Running}}",
|
|
785
|
+
name
|
|
786
|
+
]);
|
|
787
|
+
return stdout.trim() === "true" ? "running" : "stopped";
|
|
788
|
+
} catch {
|
|
789
|
+
return "absent";
|
|
790
|
+
}
|
|
791
|
+
};
|
|
792
|
+
const remove = async () => {
|
|
793
|
+
await run([
|
|
794
|
+
"rm",
|
|
795
|
+
"-f",
|
|
796
|
+
name
|
|
797
|
+
]).catch(() => {});
|
|
798
|
+
};
|
|
799
|
+
const stop = async () => {
|
|
800
|
+
await remove();
|
|
801
|
+
};
|
|
802
|
+
let reused = false;
|
|
803
|
+
const current = await state();
|
|
804
|
+
if (current === "running") {
|
|
805
|
+
reused = true;
|
|
806
|
+
log(`Reusing Playwright container ${name}`);
|
|
807
|
+
} else {
|
|
808
|
+
if (current === "stopped") await remove();
|
|
809
|
+
if (!await run([
|
|
810
|
+
"image",
|
|
811
|
+
"inspect",
|
|
812
|
+
image
|
|
813
|
+
]).then(() => true, () => false)) {
|
|
814
|
+
log(`Pulling ${image} (first run only; this can take a few minutes)`);
|
|
815
|
+
try {
|
|
816
|
+
await run(["pull", image]);
|
|
817
|
+
} catch (error) {
|
|
818
|
+
throw new Error(`Could not pull ${image}. Official images exist for every released Playwright version — check that playwright-core ${version} is a release (not a prerelease) and that the registry is reachable.\n\n${errorText(error)}`, { cause: error });
|
|
819
|
+
}
|
|
820
|
+
}
|
|
821
|
+
log(`Starting Playwright ${version} container ${name}`);
|
|
822
|
+
try {
|
|
823
|
+
await run([
|
|
824
|
+
"run",
|
|
825
|
+
"-d",
|
|
826
|
+
"--init",
|
|
827
|
+
"--ipc=host",
|
|
828
|
+
"--user",
|
|
829
|
+
"pwuser",
|
|
830
|
+
"--workdir",
|
|
831
|
+
"/home/pwuser",
|
|
832
|
+
"-p",
|
|
833
|
+
`127.0.0.1::${SERVER_PORT}`,
|
|
834
|
+
"--mount",
|
|
835
|
+
`type=bind,source=${packageDir},target=${PACKAGE_MOUNT},readonly`,
|
|
836
|
+
"--label",
|
|
837
|
+
`${CONTAINER_LABEL}=${version}`,
|
|
838
|
+
"--name",
|
|
839
|
+
name,
|
|
840
|
+
...runArgs,
|
|
841
|
+
image,
|
|
842
|
+
"node",
|
|
843
|
+
`${PACKAGE_MOUNT}/cli.js`,
|
|
844
|
+
"run-server",
|
|
845
|
+
"--port",
|
|
846
|
+
String(SERVER_PORT),
|
|
847
|
+
"--host",
|
|
848
|
+
"0.0.0.0"
|
|
849
|
+
]);
|
|
850
|
+
} catch (error) {
|
|
851
|
+
if (/already in use|conflict|already exists/i.test(errorText(error))) reused = true;
|
|
852
|
+
else throw new Error(`Could not start ${image}.\n\n${errorText(error)}`, { cause: error });
|
|
853
|
+
}
|
|
854
|
+
}
|
|
855
|
+
const containerLogs = async () => {
|
|
856
|
+
const result = await run([
|
|
857
|
+
"logs",
|
|
858
|
+
"--tail",
|
|
859
|
+
"30",
|
|
860
|
+
name
|
|
861
|
+
]).catch(() => null);
|
|
862
|
+
return result ? `${result.stdout}${result.stderr}`.trim() : "";
|
|
863
|
+
};
|
|
864
|
+
let port = null;
|
|
865
|
+
let attempt = 0;
|
|
866
|
+
while (true) {
|
|
867
|
+
if (port === null) {
|
|
868
|
+
const output = await run([
|
|
869
|
+
"port",
|
|
870
|
+
name,
|
|
871
|
+
`${SERVER_PORT}/tcp`
|
|
872
|
+
]).then((r) => r.stdout, () => "");
|
|
873
|
+
port = parsePort(output);
|
|
874
|
+
}
|
|
875
|
+
if (port !== null && await probe(`http://127.0.0.1:${port}/`)) return {
|
|
876
|
+
wsEndpoint: `ws://127.0.0.1:${port}/`,
|
|
877
|
+
name,
|
|
878
|
+
image,
|
|
879
|
+
reused,
|
|
880
|
+
stop
|
|
881
|
+
};
|
|
882
|
+
attempt++;
|
|
883
|
+
if (attempt % 8 === 0 && await state() !== "running") {
|
|
884
|
+
const logs = await containerLogs();
|
|
885
|
+
await remove();
|
|
886
|
+
throw new Error(`The Playwright container ${name} exited before its server came up.${logs ? `\n\n${logs}` : ""}`);
|
|
887
|
+
}
|
|
888
|
+
if (now() >= deadline) {
|
|
889
|
+
const logs = await containerLogs();
|
|
890
|
+
throw new Error(`Timed out after ${readyTimeout}ms waiting for the Playwright server in container ${name}. Raise playwright({ container: { readyTimeout } }) if the image is still downloading.${logs ? `\n\n${logs}` : ""}`);
|
|
891
|
+
}
|
|
892
|
+
await sleep(250);
|
|
893
|
+
}
|
|
894
|
+
}
|
|
895
|
+
/**
|
|
896
|
+
* Remove every container cappa started, whatever its version. Returns their
|
|
897
|
+
* names.
|
|
898
|
+
*/
|
|
899
|
+
async function removePlaywrightContainers(options) {
|
|
900
|
+
const { cli, exec = defaultExec } = options;
|
|
901
|
+
let stdout;
|
|
902
|
+
try {
|
|
903
|
+
({stdout} = await exec(cli, [
|
|
904
|
+
"ps",
|
|
905
|
+
"-a",
|
|
906
|
+
"--filter",
|
|
907
|
+
`label=${CONTAINER_LABEL}`,
|
|
908
|
+
"--format",
|
|
909
|
+
"{{.Names}}"
|
|
910
|
+
]));
|
|
911
|
+
} catch (error) {
|
|
912
|
+
if (isNotFound(error)) throw new Error(`Container CLI "${cli}" not found.`, { cause: error });
|
|
913
|
+
throw new Error(`"${cli} ps" failed.\n\n${errorText(error)}`, { cause: error });
|
|
914
|
+
}
|
|
915
|
+
const names = stdout.split("\n").map((line) => line.trim()).filter(Boolean);
|
|
916
|
+
if (names.length > 0) await exec(cli, [
|
|
917
|
+
"rm",
|
|
918
|
+
"-f",
|
|
919
|
+
...names
|
|
920
|
+
]);
|
|
921
|
+
return names;
|
|
922
|
+
}
|
|
923
|
+
//#endregion
|
|
686
924
|
//#region src/crop.ts
|
|
687
925
|
const DEFAULT_CROP_PADDING = 8;
|
|
688
926
|
/** The crop to apply, or `undefined` for none. */
|
|
@@ -1991,9 +2229,56 @@ const LOG_SINK_LEVELS = [
|
|
|
1991
2229
|
];
|
|
1992
2230
|
/** A logger-shaped object that forwards every call to `sink`. */
|
|
1993
2231
|
const toSinkLogger = (sink) => Object.fromEntries(LOG_SINK_LEVELS.map((level) => [level, (message, ...args) => sink(level, String(message), ...args)]));
|
|
2232
|
+
const browserMap = {
|
|
2233
|
+
chromium,
|
|
2234
|
+
firefox,
|
|
2235
|
+
webkit
|
|
2236
|
+
};
|
|
2237
|
+
/** Where the remote-browser recipe lives; linked from connection errors. */
|
|
2238
|
+
const REMOTE_BROWSER_DOCS = "https://tim-richter.github.io/cappa/configuration/#connecting-to-a-remote-browser";
|
|
2239
|
+
/** The installed `playwright-core` version, or `null` if it cannot be read. */
|
|
2240
|
+
const clientPlaywrightVersion = () => {
|
|
2241
|
+
try {
|
|
2242
|
+
return createRequire(import.meta.url)("playwright-core/package.json").version;
|
|
2243
|
+
} catch {
|
|
2244
|
+
return null;
|
|
2245
|
+
}
|
|
2246
|
+
};
|
|
2247
|
+
/** The installed `playwright-core` directory, symlinks resolved, or `null`. */
|
|
2248
|
+
const clientPlaywrightPackageDir = () => {
|
|
2249
|
+
try {
|
|
2250
|
+
const require = createRequire(import.meta.url);
|
|
2251
|
+
return realpathSync(path.dirname(require.resolve("playwright-core/package.json")));
|
|
2252
|
+
} catch {
|
|
2253
|
+
return null;
|
|
2254
|
+
}
|
|
2255
|
+
};
|
|
2256
|
+
/**
|
|
2257
|
+
* Turn a raw `browserType.connect()` failure into something actionable.
|
|
2258
|
+
*
|
|
2259
|
+
* Exported for tests.
|
|
2260
|
+
*/
|
|
2261
|
+
const describeConnectError = (error, wsEndpoint, clientVersion = clientPlaywrightVersion(), container) => {
|
|
2262
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
2263
|
+
if (container && (/version mismatch/i.test(message) || /\b428\b/.test(message))) return new Error(`The container image ${container.image} runs a different Playwright version than this client${clientVersion ? ` (playwright-core ${clientVersion})` : ""}. A custom playwright({ container: { image } }) must be built from the official image for the same version — use {version} in the tag.\n\n${message}`, { cause: error });
|
|
2264
|
+
if (/version mismatch/i.test(message) || /\b428\b/.test(message)) {
|
|
2265
|
+
const image = clientVersion ? `mcr.microsoft.com/playwright:v${clientVersion}-noble` : "the mcr.microsoft.com/playwright image matching your playwright-core";
|
|
2266
|
+
return new Error(`The Playwright server at ${wsEndpoint} runs a different Playwright version than this client${clientVersion ? ` (playwright-core ${clientVersion})` : ""}. Run the server from ${image}.\n\n${message}`, { cause: error });
|
|
2267
|
+
}
|
|
2268
|
+
if (/timeout/i.test(message) && /exceeded/i.test(message)) return new Error(`Timed out connecting to the Playwright server at ${wsEndpoint}. See ${REMOTE_BROWSER_DOCS}\n\n${message}`, { cause: error });
|
|
2269
|
+
return new Error(`No Playwright server at ${wsEndpoint}. Start one with \`playwright run-server\`, or unset connectOptions.wsEndpoint to launch a local browser. See ${REMOTE_BROWSER_DOCS}\n\n${message}`, { cause: error });
|
|
2270
|
+
};
|
|
1994
2271
|
var ScreenshotTool = class {
|
|
1995
2272
|
browserType;
|
|
1996
2273
|
headless;
|
|
2274
|
+
/** Browser provider, headless mode and instance — see `UserConfig.browser`. */
|
|
2275
|
+
browserConfig;
|
|
2276
|
+
/**
|
|
2277
|
+
* Set when the browser goes away underneath the tool — a remote browser
|
|
2278
|
+
* server restarting, or a local browser crashing. `WarmBrowser` checks it so
|
|
2279
|
+
* it starts a fresh browser instead of handing out a dead one.
|
|
2280
|
+
*/
|
|
2281
|
+
disconnected = false;
|
|
1997
2282
|
viewport;
|
|
1998
2283
|
fullPage;
|
|
1999
2284
|
/** Default content crop; a screenshot's own `crop` overrides it. */
|
|
@@ -2018,14 +2303,20 @@ var ScreenshotTool = class {
|
|
|
2018
2303
|
filesystem;
|
|
2019
2304
|
logConsoleEvents;
|
|
2020
2305
|
connectionTimeout;
|
|
2306
|
+
/** The container `init()` started or reused, when `container` is on. */
|
|
2307
|
+
container = null;
|
|
2021
2308
|
defaultUserAgent = "";
|
|
2022
2309
|
/** The real logger, kept so `setLogSink(null)` restores the same instance. */
|
|
2023
2310
|
baseLogger;
|
|
2024
2311
|
/** Set while a `CaptureRunner` owns this tool — see `setCaptureSink`. */
|
|
2025
2312
|
captureSink = null;
|
|
2026
2313
|
constructor(options) {
|
|
2027
|
-
this.
|
|
2028
|
-
|
|
2314
|
+
this.browserConfig = resolveBrowserConfig(options.browser ?? {
|
|
2315
|
+
headless: options.headless !== false,
|
|
2316
|
+
instances: [{ browser: options.browserType || "chromium" }]
|
|
2317
|
+
});
|
|
2318
|
+
this.browserType = this.browserConfig.instances[0].browser;
|
|
2319
|
+
this.headless = this.browserConfig.headless;
|
|
2029
2320
|
this.viewport = options.viewport || {
|
|
2030
2321
|
width: 1920,
|
|
2031
2322
|
height: 1080
|
|
@@ -2100,34 +2391,85 @@ var ScreenshotTool = class {
|
|
|
2100
2391
|
* Initialize playwright and page
|
|
2101
2392
|
*/
|
|
2102
2393
|
async init() {
|
|
2103
|
-
const
|
|
2104
|
-
|
|
2105
|
-
|
|
2106
|
-
|
|
2107
|
-
|
|
2108
|
-
|
|
2109
|
-
|
|
2394
|
+
const browserType = browserMap[this.browserType];
|
|
2395
|
+
if (!browserType) throw new Error(`Unsupported browser type: ${this.browserType}`);
|
|
2396
|
+
const { launchOptions, connectOptions, contextOptions } = this.browserConfig.provider.options;
|
|
2397
|
+
const launch = {
|
|
2398
|
+
...launchOptions,
|
|
2399
|
+
headless: this.headless
|
|
2400
|
+
};
|
|
2401
|
+
const container = resolveContainerOptions(this.browserConfig.provider.options.container);
|
|
2402
|
+
let connect = connectOptions?.wsEndpoint ? {
|
|
2403
|
+
...connectOptions,
|
|
2404
|
+
wsEndpoint: connectOptions.wsEndpoint
|
|
2405
|
+
} : null;
|
|
2406
|
+
if (connect && container) this.logger.debug(`connectOptions.wsEndpoint is set (${connect.wsEndpoint}); not starting a container.`);
|
|
2407
|
+
else if (container) {
|
|
2408
|
+
const version = clientPlaywrightVersion();
|
|
2409
|
+
const packageDir = clientPlaywrightPackageDir();
|
|
2410
|
+
if (!version || !packageDir) throw new Error("playwright({ container }) needs the installed playwright-core, but its package.json could not be read.");
|
|
2411
|
+
this.container = await ensurePlaywrightContainer({
|
|
2412
|
+
...container,
|
|
2413
|
+
version,
|
|
2414
|
+
packageDir,
|
|
2415
|
+
log: (message) => this.logger.info(message)
|
|
2416
|
+
});
|
|
2417
|
+
connect = {
|
|
2418
|
+
exposeNetwork: "<loopback>",
|
|
2419
|
+
...connectOptions,
|
|
2420
|
+
wsEndpoint: this.container.wsEndpoint
|
|
2421
|
+
};
|
|
2422
|
+
}
|
|
2423
|
+
let browser;
|
|
2424
|
+
if (connect) {
|
|
2425
|
+
const { wsEndpoint, ...options } = connect;
|
|
2426
|
+
try {
|
|
2427
|
+
browser = await browserType.connect(wsEndpoint, {
|
|
2428
|
+
...options,
|
|
2429
|
+
headers: {
|
|
2430
|
+
"x-playwright-launch-options": JSON.stringify(launch),
|
|
2431
|
+
...options.headers
|
|
2432
|
+
}
|
|
2433
|
+
});
|
|
2434
|
+
} catch (error) {
|
|
2435
|
+
throw describeConnectError(error, wsEndpoint, void 0, this.container ?? void 0);
|
|
2436
|
+
}
|
|
2437
|
+
} else browser = await browserType.launch(launch);
|
|
2110
2438
|
if (!browser) throw new Error("Something went wrong with starting the browser.");
|
|
2111
2439
|
this.browser = browser;
|
|
2112
|
-
|
|
2113
|
-
|
|
2114
|
-
|
|
2115
|
-
|
|
2440
|
+
this.disconnected = false;
|
|
2441
|
+
browser.on("disconnected", () => {
|
|
2442
|
+
if (this.browser === browser) this.disconnected = true;
|
|
2443
|
+
});
|
|
2444
|
+
if (!contextOptions?.userAgent) {
|
|
2445
|
+
const tempCtx = await browser.newContext();
|
|
2446
|
+
const tempPage = await tempCtx.newPage();
|
|
2447
|
+
this.defaultUserAgent = await tempPage.evaluate(() => navigator.userAgent);
|
|
2448
|
+
await tempCtx.close();
|
|
2449
|
+
}
|
|
2116
2450
|
await this.createContexts();
|
|
2117
2451
|
}
|
|
2118
2452
|
/**
|
|
2119
2453
|
* Create the pool of browser contexts and pages.
|
|
2454
|
+
*
|
|
2455
|
+
* `contextOptions` from the provider merge over cappa's defaults; the
|
|
2456
|
+
* viewport and the `CappaStorybook` user-agent suffix always win, because
|
|
2457
|
+
* plugins and `isCappa()` rely on them.
|
|
2120
2458
|
*/
|
|
2121
2459
|
async createContexts() {
|
|
2122
2460
|
const browser = this.browser;
|
|
2123
2461
|
if (!browser) throw new Error("Browser not initialized");
|
|
2462
|
+
const { contextOptions, actionTimeout } = this.browserConfig.provider.options;
|
|
2463
|
+
const { viewport: _ignored, ...extraContextOptions } = contextOptions ?? {};
|
|
2124
2464
|
const results = await Promise.all(Array.from({ length: this.concurrency }, async () => {
|
|
2125
2465
|
const context = await browser.newContext({
|
|
2126
2466
|
reducedMotion: "reduce",
|
|
2127
2467
|
deviceScaleFactor: 2,
|
|
2128
|
-
|
|
2468
|
+
...extraContextOptions,
|
|
2469
|
+
userAgent: `${contextOptions?.userAgent ?? this.defaultUserAgent} CappaStorybook`,
|
|
2129
2470
|
viewport: this.viewport
|
|
2130
2471
|
});
|
|
2472
|
+
if (actionTimeout) context.setDefaultTimeout(actionTimeout);
|
|
2131
2473
|
return {
|
|
2132
2474
|
context,
|
|
2133
2475
|
page: await context.newPage()
|
|
@@ -2182,13 +2524,23 @@ var ScreenshotTool = class {
|
|
|
2182
2524
|
this.context = null;
|
|
2183
2525
|
this.page = null;
|
|
2184
2526
|
}
|
|
2185
|
-
|
|
2527
|
+
const browser = this.browser;
|
|
2528
|
+
if (browser) {
|
|
2529
|
+
this.browser = null;
|
|
2186
2530
|
try {
|
|
2187
|
-
await
|
|
2531
|
+
await browser.close();
|
|
2188
2532
|
} catch (error) {
|
|
2189
2533
|
getLogger().debug("Error closing the browser:", error);
|
|
2190
2534
|
}
|
|
2191
|
-
|
|
2535
|
+
}
|
|
2536
|
+
this.disconnected = false;
|
|
2537
|
+
const container = this.container;
|
|
2538
|
+
this.container = null;
|
|
2539
|
+
const options = resolveContainerOptions(this.browserConfig.provider.options.container);
|
|
2540
|
+
if (container && options && !options.keepAlive && !container.reused) try {
|
|
2541
|
+
await container.stop();
|
|
2542
|
+
} catch (error) {
|
|
2543
|
+
getLogger().debug("Error removing the Playwright container:", error);
|
|
2192
2544
|
}
|
|
2193
2545
|
}
|
|
2194
2546
|
/**
|
|
@@ -2607,27 +2959,23 @@ var ScreenshotTool = class {
|
|
|
2607
2959
|
*/
|
|
2608
2960
|
const AGENT_DIRNAME = ".cappa-agent";
|
|
2609
2961
|
/** Bumped only if `request.json` or `report.json` change incompatibly. */
|
|
2610
|
-
const AGENT_REPORT_VERSION =
|
|
2962
|
+
const AGENT_REPORT_VERSION = 2;
|
|
2611
2963
|
const agentDir = (outputDir) => path.resolve(outputDir, AGENT_DIRNAME);
|
|
2612
2964
|
const judgmentsRoot = (outputDir) => path.join(agentDir(outputDir), "judgments");
|
|
2613
2965
|
const agentReportPath = (outputDir) => path.join(agentDir(outputDir), "report.json");
|
|
2614
2966
|
//#endregion
|
|
2615
2967
|
//#region src/agent/verdict.ts
|
|
2616
2968
|
/**
|
|
2617
|
-
* What a
|
|
2969
|
+
* What a judge believes a changed screenshot is, after looking at it.
|
|
2618
2970
|
*
|
|
2619
|
-
*
|
|
2620
|
-
*
|
|
2621
|
-
*
|
|
2971
|
+
* Only a judge labels a change. Cappa's diff threshold already absorbs
|
|
2972
|
+
* sub-pixel rendering differences, so a screenshot that reaches `changed`
|
|
2973
|
+
* differs beyond the tolerance the project configured — and classifying it
|
|
2974
|
+
* from diff signals alone (change types, severity, pixel counts) proved to
|
|
2975
|
+
* mislabel exactly the changes that matter: a font-size change reads as a
|
|
2976
|
+
* harmless shift plus recolour. Every changed screenshot is looked at instead.
|
|
2622
2977
|
*/
|
|
2623
2978
|
const VERDICT_LABELS = [
|
|
2624
|
-
"regression-likely",
|
|
2625
|
-
"intentional-likely",
|
|
2626
|
-
"noise-likely",
|
|
2627
|
-
"ambiguous"
|
|
2628
|
-
];
|
|
2629
|
-
/** The labels a judge may hand back — everything but `ambiguous`. */
|
|
2630
|
-
const JUDGED_LABELS = [
|
|
2631
2979
|
"regression-likely",
|
|
2632
2980
|
"intentional-likely",
|
|
2633
2981
|
"noise-likely"
|
|
@@ -2635,125 +2983,43 @@ const JUDGED_LABELS = [
|
|
|
2635
2983
|
const ACTION_BY_LABEL = {
|
|
2636
2984
|
"regression-likely": "investigate",
|
|
2637
2985
|
"intentional-likely": "approve-if-intended",
|
|
2638
|
-
"noise-likely": "mask-or-approve"
|
|
2639
|
-
ambiguous: "investigate"
|
|
2986
|
+
"noise-likely": "mask-or-approve"
|
|
2640
2987
|
};
|
|
2641
2988
|
const isVerdictLabel = (value) => typeof value === "string" && VERDICT_LABELS.includes(value);
|
|
2642
|
-
const isJudgedLabel = (value) => typeof value === "string" && JUDGED_LABELS.includes(value);
|
|
2643
2989
|
/**
|
|
2644
2990
|
* Change types are normalised to kebab-case before they are compared.
|
|
2645
2991
|
*
|
|
2646
2992
|
* `@blazediff/interpret-native` reports `color-change` today but earlier
|
|
2647
|
-
* releases reported `ColorChange`; normalising keeps the
|
|
2648
|
-
* across a diff-engine upgrade
|
|
2649
|
-
* to `ambiguous`.
|
|
2993
|
+
* releases reported `ColorChange`; normalising keeps the capture report's
|
|
2994
|
+
* labels working across a diff-engine upgrade.
|
|
2650
2995
|
*/
|
|
2651
2996
|
const normalizeChangeType = (changeType) => changeType.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
|
|
2652
|
-
const normalizeSeverity = (severity) => (severity ?? "").toLowerCase();
|
|
2653
|
-
/** Structural: something appeared, vanished or was replaced. */
|
|
2654
|
-
const REGRESSIVE_TYPES = /* @__PURE__ */ new Set([
|
|
2655
|
-
"content-change",
|
|
2656
|
-
"addition",
|
|
2657
|
-
"deletion"
|
|
2658
|
-
]);
|
|
2659
|
-
/** Restyled or moved, with structure intact. */
|
|
2660
|
-
const RESTYLE_TYPES = /* @__PURE__ */ new Set(["color-change", "shift"]);
|
|
2661
|
-
const NOISE_TYPES = /* @__PURE__ */ new Set(["rendering-noise"]);
|
|
2662
|
-
const ELEVATED_SEVERITY = /* @__PURE__ */ new Set(["medium", "high"]);
|
|
2663
|
-
/**
|
|
2664
|
-
* At or below this many differing pixels, a low-severity change is not
|
|
2665
|
-
* perceptible.
|
|
2666
|
-
*
|
|
2667
|
-
* An absolute count rather than a share of the image: a share depends on how
|
|
2668
|
-
* much empty canvas surrounds the content, so the same changed glyph would be
|
|
2669
|
-
* noise in a 1920x1080 capture and a regression in a tight crop of the
|
|
2670
|
-
* component. The pixels that changed are the same either way.
|
|
2671
|
-
*/
|
|
2672
|
-
const SUB_PERCEPTUAL_PIXELS = 25;
|
|
2673
|
-
/** Mean region confidence above which a pure recolour is trusted. */
|
|
2674
|
-
const RECOLOR_CONFIDENCE = .7;
|
|
2675
2997
|
const formatPercent = (percent) => {
|
|
2676
2998
|
if (percent === void 0) return "?%";
|
|
2677
2999
|
return percent >= .01 ? `${percent.toFixed(2)}%` : `${percent.toFixed(3)}%`;
|
|
2678
3000
|
};
|
|
2679
|
-
const countByType = (regions) => {
|
|
2680
|
-
const counts = /* @__PURE__ */ new Map();
|
|
2681
|
-
for (const region of regions) {
|
|
2682
|
-
const type = normalizeChangeType(region.changeType);
|
|
2683
|
-
counts.set(type, (counts.get(type) ?? 0) + 1);
|
|
2684
|
-
}
|
|
2685
|
-
return counts;
|
|
2686
|
-
};
|
|
2687
|
-
const formatBreakdown = (counts) => [...counts].sort((a, b) => b[1] - a[1]).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2688
3001
|
const largestRegion = (regions) => regions.reduce((best, region) => !best || region.pixelCount > best.pixelCount ? region : best, void 0);
|
|
2689
|
-
const meanConfidence = (regions) => regions.length === 0 ? 0 : regions.reduce((sum, region) => sum + (region.confidence ?? 0), 0) / regions.length;
|
|
2690
3002
|
/**
|
|
2691
|
-
* A one-line description of
|
|
2692
|
-
* on different screenshots produces the same
|
|
2693
|
-
*
|
|
2694
|
-
* dozens of screenshots
|
|
3003
|
+
* A one-line description of where and how much a screenshot changed, shaped
|
|
3004
|
+
* so that the same change on different screenshots produces the same text —
|
|
3005
|
+
* which is what lets a judge spot one shared cause (a footer timestamp, a
|
|
3006
|
+
* theme toggle) across dozens of screenshots and judge them together.
|
|
3007
|
+
*
|
|
3008
|
+
* Deliberately geometry only: no change types, no severity. Those are guesses
|
|
3009
|
+
* from pixel signals, and a judge primed with "noise" or "shift" looks less
|
|
3010
|
+
* carefully at what is in fact a regression.
|
|
2695
3011
|
*/
|
|
2696
|
-
const
|
|
2697
|
-
const
|
|
2698
|
-
|
|
2699
|
-
if (input.differentSizes) return hasRegions ? `dimensions changed; ${buildHeadline({
|
|
3012
|
+
const describeChange = (input) => {
|
|
3013
|
+
const regions = input.interpretation?.regions ?? [];
|
|
3014
|
+
if (input.differentSizes) return regions.length > 0 ? `dimensions changed; ${describeChange({
|
|
2700
3015
|
...input,
|
|
2701
3016
|
differentSizes: false
|
|
2702
3017
|
})}` : "image dimensions changed";
|
|
2703
|
-
const percent = input.percentDifference ?? interpretation?.diffPercentage;
|
|
2704
|
-
if (
|
|
2705
|
-
const regions = interpretation.regions;
|
|
2706
|
-
const counts = countByType(regions);
|
|
3018
|
+
const percent = input.percentDifference ?? input.interpretation?.diffPercentage;
|
|
3019
|
+
if (regions.length === 0) return `${(input.numDiffPixels ?? input.interpretation?.diffCount)?.toLocaleString("en-US") ?? "?"} px (${formatPercent(percent)}) - no regions located`;
|
|
2707
3020
|
const position = largestRegion(regions)?.position;
|
|
2708
3021
|
const at = position ? ` @ ${position}` : "";
|
|
2709
|
-
|
|
2710
|
-
if (regions.length === 1) return `1 ${[...counts.keys()][0]}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2711
|
-
return `${regions.length} regions: ${formatBreakdown(counts)}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2712
|
-
};
|
|
2713
|
-
const verdict = (label, headline, rationale) => ({
|
|
2714
|
-
label,
|
|
2715
|
-
headline,
|
|
2716
|
-
rationale,
|
|
2717
|
-
action: ACTION_BY_LABEL[label]
|
|
2718
|
-
});
|
|
2719
|
-
/**
|
|
2720
|
-
* Classify a changed screenshot from its diff interpretation alone.
|
|
2721
|
-
*
|
|
2722
|
-
* Deliberately conservative: only the cases the signals settle are labelled,
|
|
2723
|
-
* and everything else is `ambiguous` so that it reaches a judge who can look
|
|
2724
|
-
* at the pixels. A wrong `noise-likely` hides a regression; a wrong
|
|
2725
|
-
* `ambiguous` costs one look.
|
|
2726
|
-
*/
|
|
2727
|
-
const deriveVerdict = (input) => {
|
|
2728
|
-
const headline = buildHeadline(input);
|
|
2729
|
-
const interpretation = input.interpretation;
|
|
2730
|
-
const hasRegions = (interpretation?.regions.length ?? 0) > 0;
|
|
2731
|
-
if (input.differentSizes && (!interpretation || !hasRegions)) 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"]);
|
|
2732
|
-
if (!interpretation || !hasRegions) return verdict("ambiguous", headline, ["pixels differ but no change regions were found"]);
|
|
2733
|
-
const classified = classifyRegions(input, interpretation, headline, !input.differentSizes);
|
|
2734
|
-
if (!input.differentSizes) return classified;
|
|
2735
|
-
return {
|
|
2736
|
-
...classified,
|
|
2737
|
-
rationale: ["expected and actual have different dimensions — compared on a canvas padded to the larger size", ...classified.rationale]
|
|
2738
|
-
};
|
|
2739
|
-
};
|
|
2740
|
-
const classifyRegions = (input, interpretation, headline, allowNoise) => {
|
|
2741
|
-
const regions = interpretation.regions;
|
|
2742
|
-
const types = regions.map((region) => normalizeChangeType(region.changeType));
|
|
2743
|
-
const severity = normalizeSeverity(interpretation.severity);
|
|
2744
|
-
const percent = input.percentDifference ?? interpretation.diffPercentage;
|
|
2745
|
-
const pixels = input.numDiffPixels ?? interpretation.diffCount;
|
|
2746
|
-
const counts = countByType(regions);
|
|
2747
|
-
if (allowNoise && types.every((type) => NOISE_TYPES.has(type))) return verdict("noise-likely", headline, ["every region is classified as rendering noise"]);
|
|
2748
|
-
if (allowNoise && pixels <= 25 && severity === "low") return verdict("noise-likely", headline, [`${pixels.toLocaleString("en-US")} ${pixels === 1 ? "pixel differs" : "pixels differ"} (at most 25) at low severity`, "sub-perceptual change"]);
|
|
2749
|
-
if (types.some((type) => REGRESSIVE_TYPES.has(type)) && ELEVATED_SEVERITY.has(severity)) {
|
|
2750
|
-
const structural = [...counts].filter(([type]) => REGRESSIVE_TYPES.has(type)).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2751
|
-
return verdict("regression-likely", headline, [`${severity} severity with structural changes (${structural})`, "content or layout changed, not just styling"]);
|
|
2752
|
-
}
|
|
2753
|
-
const allRecolor = types.every((type) => type === "color-change");
|
|
2754
|
-
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"]);
|
|
2755
|
-
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"]);
|
|
2756
|
-
return verdict("ambiguous", headline, [`mix of change types (${formatBreakdown(counts)}) at ${severity || "unknown"} severity`, `${formatPercent(percent)} of the image differs`]);
|
|
3022
|
+
return `${`${regions.length} ${regions.length === 1 ? "region" : "regions"}`}${at} (${formatPercent(percent)})`;
|
|
2757
3023
|
};
|
|
2758
3024
|
//#endregion
|
|
2759
3025
|
//#region src/agent/reviewIndex.ts
|
|
@@ -2771,11 +3037,11 @@ const readAgentReviewIndex = async (outputDir) => {
|
|
|
2771
3037
|
return;
|
|
2772
3038
|
}
|
|
2773
3039
|
const createdAt = typeof raw?.createdAt === "string" ? Date.parse(raw.createdAt) : NaN;
|
|
2774
|
-
if (raw?.version !==
|
|
3040
|
+
if (raw?.version !== 2 || Number.isNaN(createdAt) || !Array.isArray(raw.entries)) return;
|
|
2775
3041
|
const reviews = /* @__PURE__ */ new Map();
|
|
2776
3042
|
for (const entry of raw.entries) {
|
|
2777
3043
|
if (typeof entry !== "object" || entry === null) continue;
|
|
2778
|
-
const { name, category, verdict
|
|
3044
|
+
const { name, category, verdict } = entry;
|
|
2779
3045
|
if (typeof name !== "string" || category !== "changed") continue;
|
|
2780
3046
|
if (typeof verdict !== "object" || verdict === null) continue;
|
|
2781
3047
|
const v = verdict;
|
|
@@ -2785,9 +3051,9 @@ const readAgentReviewIndex = async (outputDir) => {
|
|
|
2785
3051
|
headline: v.headline,
|
|
2786
3052
|
rationale: Array.isArray(v.rationale) ? v.rationale.filter((line) => typeof line === "string") : [],
|
|
2787
3053
|
action: v.action,
|
|
2788
|
-
source:
|
|
3054
|
+
source: "agent",
|
|
2789
3055
|
...typeof v.confidence === "number" ? { confidence: v.confidence } : {},
|
|
2790
|
-
pending:
|
|
3056
|
+
pending: false,
|
|
2791
3057
|
reviewedAt: new Date(createdAt).toISOString()
|
|
2792
3058
|
});
|
|
2793
3059
|
}
|
|
@@ -3512,6 +3778,13 @@ var WarmBrowser = class {
|
|
|
3512
3778
|
if (this.closed) throw new Error("WarmBrowser has been closed");
|
|
3513
3779
|
this.cancelIdleTimer();
|
|
3514
3780
|
this.inUse = true;
|
|
3781
|
+
if (this.tool?.disconnected === true) {
|
|
3782
|
+
const dead = this.tool;
|
|
3783
|
+
this.tool = null;
|
|
3784
|
+
try {
|
|
3785
|
+
await dead.close();
|
|
3786
|
+
} catch {}
|
|
3787
|
+
}
|
|
3515
3788
|
if (this.tool) {
|
|
3516
3789
|
await this.tool.recycleContexts();
|
|
3517
3790
|
return this.tool;
|
|
@@ -4058,7 +4331,8 @@ var LocalEngine = class {
|
|
|
4058
4331
|
width: 1920,
|
|
4059
4332
|
height: 1080
|
|
4060
4333
|
},
|
|
4061
|
-
connectionTimeout: this.options.connectionTimeout
|
|
4334
|
+
connectionTimeout: this.options.connectionTimeout,
|
|
4335
|
+
browser: this.options.browser
|
|
4062
4336
|
});
|
|
4063
4337
|
}
|
|
4064
4338
|
async listPlugins() {
|
|
@@ -4606,6 +4880,9 @@ const renderOverview = async (options) => {
|
|
|
4606
4880
|
* Agent review: turn the screenshots on disk into something a coding agent
|
|
4607
4881
|
* can judge cheaply, and fold its judgments back in.
|
|
4608
4882
|
*
|
|
4883
|
+
* Every changed screenshot gets a judgment request. Nothing is labelled from
|
|
4884
|
+
* diff signals alone — see `VERDICT_LABELS` for why.
|
|
4885
|
+
*
|
|
4609
4886
|
* Nothing here captures. It reads `actual/`, `expected/` and `diff/` as the
|
|
4610
4887
|
* last `cappa capture` left them, so it is safe to run repeatedly — a re-run
|
|
4611
4888
|
* is how an agent's verdicts are applied, and a re-capture invalidates them
|
|
@@ -4633,11 +4910,6 @@ const JUDGMENT_FILES = [
|
|
|
4633
4910
|
"regions.png",
|
|
4634
4911
|
"overview.png"
|
|
4635
4912
|
];
|
|
4636
|
-
const JUDGE_MODES = [
|
|
4637
|
-
"ambiguous",
|
|
4638
|
-
"all",
|
|
4639
|
-
"none"
|
|
4640
|
-
];
|
|
4641
4913
|
/**
|
|
4642
4914
|
* The directory holding a screenshot's judgment.
|
|
4643
4915
|
*
|
|
@@ -4690,7 +4962,7 @@ const parseAgentVerdict = (raw) => {
|
|
|
4690
4962
|
const outer = raw;
|
|
4691
4963
|
const inner = typeof outer.verdict === "object" && outer.verdict !== null ? outer.verdict : outer;
|
|
4692
4964
|
const label = inner.label;
|
|
4693
|
-
if (!
|
|
4965
|
+
if (!isVerdictLabel(label)) return {
|
|
4694
4966
|
ok: false,
|
|
4695
4967
|
error: `label must be one of regression-likely, intentional-likely, noise-likely (got ${JSON.stringify(label)})`
|
|
4696
4968
|
};
|
|
@@ -4742,9 +5014,7 @@ const toAgentRegions = (regions) => [...regions].sort((a, b) => b.pixelCount - a
|
|
|
4742
5014
|
pixelCount: region.pixelCount,
|
|
4743
5015
|
percentage: region.percentage,
|
|
4744
5016
|
position: region.position,
|
|
4745
|
-
shape: region.shape
|
|
4746
|
-
changeType: normalizeChangeType(region.changeType),
|
|
4747
|
-
confidence: region.confidence
|
|
5017
|
+
shape: region.shape
|
|
4748
5018
|
}));
|
|
4749
5019
|
/**
|
|
4750
5020
|
* The interpretation a capture already persisted, or a fresh one.
|
|
@@ -4767,8 +5037,10 @@ const interpretationFor = async (screenshot, expectedPath, actualPath, diff) =>
|
|
|
4767
5037
|
}
|
|
4768
5038
|
};
|
|
4769
5039
|
const JUDGE_INSTRUCTIONS = [
|
|
5040
|
+
"Every changed screenshot differs beyond the project's diff threshold, so sub-pixel rendering is already filtered out: look at each change before labelling it.",
|
|
4770
5041
|
"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.",
|
|
4771
5042
|
"overview.png exists only when the image dimensions changed: it shows both images whole, side by side. Regions are then located on a canvas padded to the larger size, anchored top-left — in a crop, area that only one image covers is empty.",
|
|
5043
|
+
"Compare sizes, not just content: text that is larger, smaller, bolder or reflowed, and spacing, alignment or wrapping that moved, are regressions unless a code change explains them.",
|
|
4772
5044
|
"Only open paths.expected / paths.actual / paths.diff (full size) when a change clearly continues outside its crop.",
|
|
4773
5045
|
"Write verdict.json next to this file, or run `cappa agent judge <name> --label <label> --headline <text>`."
|
|
4774
5046
|
];
|
|
@@ -4826,7 +5098,7 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4826
5098
|
const percentDifference = screenshot.diffMeta?.percentDifference ?? interpretation?.diffPercentage;
|
|
4827
5099
|
const numDiffPixels = screenshot.diffMeta?.numDiffPixels ?? interpretation?.diffCount;
|
|
4828
5100
|
const regions = toAgentRegions(interpretation?.regions ?? []);
|
|
4829
|
-
const
|
|
5101
|
+
const change = describeChange({
|
|
4830
5102
|
percentDifference,
|
|
4831
5103
|
numDiffPixels,
|
|
4832
5104
|
interpretation,
|
|
@@ -4850,20 +5122,13 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4850
5122
|
expected: expectedSize,
|
|
4851
5123
|
actual: actualSize
|
|
4852
5124
|
},
|
|
4853
|
-
|
|
4854
|
-
summary: interpretation?.summary,
|
|
5125
|
+
change,
|
|
4855
5126
|
regions,
|
|
4856
|
-
|
|
4857
|
-
verdict: {
|
|
4858
|
-
...heuristic,
|
|
4859
|
-
source: "heuristic"
|
|
4860
|
-
},
|
|
4861
|
-
pending: false
|
|
5127
|
+
pending: true
|
|
4862
5128
|
};
|
|
4863
5129
|
const dir = judgmentDir(outputDir, screenshot.name);
|
|
4864
5130
|
const requestPath = path.join(dir, REQUEST_FILE);
|
|
4865
5131
|
const verdictPath = path.join(dir, VERDICT_FILE);
|
|
4866
|
-
if (!(options.judge === "all" || options.judge === "ambiguous" && heuristic.label === "ambiguous" || await exists(requestPath))) return entry;
|
|
4867
5132
|
const fingerprint = await fingerprintImages(expectedPath, actualPath);
|
|
4868
5133
|
const previous = await readJson(requestPath);
|
|
4869
5134
|
if (previous && previous.fingerprint !== fingerprint) await clearJudgmentFiles(dir);
|
|
@@ -4892,7 +5157,7 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4892
5157
|
}
|
|
4893
5158
|
entry.judgment = judgment;
|
|
4894
5159
|
await writeJson(requestPath, {
|
|
4895
|
-
version:
|
|
5160
|
+
version: 2,
|
|
4896
5161
|
name: entry.name,
|
|
4897
5162
|
taskId: entry.taskId,
|
|
4898
5163
|
plugin: entry.plugin,
|
|
@@ -4900,12 +5165,10 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4900
5165
|
createdAt,
|
|
4901
5166
|
instructions: JUDGE_INSTRUCTIONS,
|
|
4902
5167
|
verdictSchema: VERDICT_SCHEMA,
|
|
4903
|
-
|
|
5168
|
+
change,
|
|
4904
5169
|
percentDifference,
|
|
4905
5170
|
numDiffPixels,
|
|
4906
5171
|
dimensions: entry.dimensions,
|
|
4907
|
-
severity: entry.severity,
|
|
4908
|
-
summary: entry.summary,
|
|
4909
5172
|
regions,
|
|
4910
5173
|
paths: {
|
|
4911
5174
|
locator: judgment.locator,
|
|
@@ -4917,22 +5180,18 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4917
5180
|
verdict: verdictPath
|
|
4918
5181
|
}
|
|
4919
5182
|
});
|
|
4920
|
-
if (!await exists(verdictPath))
|
|
4921
|
-
entry.pending = true;
|
|
4922
|
-
return entry;
|
|
4923
|
-
}
|
|
5183
|
+
if (!await exists(verdictPath)) return entry;
|
|
4924
5184
|
const parsed = parseAgentVerdict(await readJson(verdictPath));
|
|
4925
5185
|
if (!parsed.ok) {
|
|
4926
|
-
entry.pending = true;
|
|
4927
5186
|
entry.verdictError = parsed.error;
|
|
4928
5187
|
return entry;
|
|
4929
5188
|
}
|
|
5189
|
+
entry.pending = false;
|
|
4930
5190
|
entry.verdict = {
|
|
4931
5191
|
label: parsed.label,
|
|
4932
5192
|
headline: parsed.headline,
|
|
4933
5193
|
rationale: parsed.rationale,
|
|
4934
5194
|
action: ACTION_BY_LABEL[parsed.label],
|
|
4935
|
-
source: "agent",
|
|
4936
5195
|
...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
|
|
4937
5196
|
};
|
|
4938
5197
|
return entry;
|
|
@@ -4976,13 +5235,12 @@ const pruneJudgments = async (outputDir, keep) => {
|
|
|
4976
5235
|
}
|
|
4977
5236
|
};
|
|
4978
5237
|
/**
|
|
4979
|
-
* Analyse every non-passing screenshot, write judgment
|
|
4980
|
-
*
|
|
4981
|
-
*
|
|
5238
|
+
* Analyse every non-passing screenshot, write a judgment request for every
|
|
5239
|
+
* changed one, apply any verdicts already written, and persist the full
|
|
5240
|
+
* report to `<outputDir>/.cappa-agent/report.json`.
|
|
4982
5241
|
*/
|
|
4983
5242
|
const runAgentCheck = async (options) => {
|
|
4984
5243
|
const outputDir = path.resolve(options.outputDir);
|
|
4985
|
-
const judge = options.judge ?? "ambiguous";
|
|
4986
5244
|
const createdAt = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
|
|
4987
5245
|
const screenshots = await collectScreenshots(outputDir);
|
|
4988
5246
|
await fsp.mkdir(agentDir(outputDir), { recursive: true });
|
|
@@ -4990,8 +5248,7 @@ const runAgentCheck = async (options) => {
|
|
|
4990
5248
|
const changed = screenshots.filter((s) => s.category === "changed");
|
|
4991
5249
|
const changedEntries = await mapWithConcurrency(options.concurrency ?? 4, changed, (screenshot) => analyseChanged(screenshot, {
|
|
4992
5250
|
...options,
|
|
4993
|
-
outputDir
|
|
4994
|
-
judge
|
|
5251
|
+
outputDir
|
|
4995
5252
|
}, createdAt));
|
|
4996
5253
|
await pruneJudgments(outputDir, new Set(changedEntries.flatMap((entry) => entry.judgment ? [entry.judgment.dir] : [])));
|
|
4997
5254
|
const otherEntries = screenshots.flatMap((s) => {
|
|
@@ -5016,11 +5273,10 @@ const runAgentCheck = async (options) => {
|
|
|
5016
5273
|
const entries = [...changedEntries, ...otherEntries];
|
|
5017
5274
|
const count = (category) => screenshots.filter((s) => s.category === category).length;
|
|
5018
5275
|
const report = {
|
|
5019
|
-
version:
|
|
5276
|
+
version: 2,
|
|
5020
5277
|
createdAt,
|
|
5021
5278
|
outputDir,
|
|
5022
5279
|
reportPath: agentReportPath(outputDir),
|
|
5023
|
-
judge,
|
|
5024
5280
|
totals: {
|
|
5025
5281
|
total: screenshots.length,
|
|
5026
5282
|
passed: count("passed"),
|
|
@@ -5037,7 +5293,7 @@ const runAgentCheck = async (options) => {
|
|
|
5037
5293
|
/** Read the report the last {@link runAgentCheck} wrote, if any. */
|
|
5038
5294
|
const readAgentReport = async (outputDir) => {
|
|
5039
5295
|
const raw = await readJson(agentReportPath(outputDir));
|
|
5040
|
-
return raw?.version ===
|
|
5296
|
+
return raw?.version === 2 ? raw : void 0;
|
|
5041
5297
|
};
|
|
5042
5298
|
/**
|
|
5043
5299
|
* The report as an agent should first see it: one line of state per
|
|
@@ -5050,11 +5306,11 @@ const toSlimAgentReport = (report) => ({
|
|
|
5050
5306
|
results: report.entries.map((entry) => ({
|
|
5051
5307
|
name: entry.name,
|
|
5052
5308
|
category: entry.category,
|
|
5309
|
+
...entry.change ? { change: entry.change } : {},
|
|
5053
5310
|
...entry.verdict ? { verdict: {
|
|
5054
5311
|
label: entry.verdict.label,
|
|
5055
5312
|
headline: entry.verdict.headline,
|
|
5056
|
-
action: entry.verdict.action
|
|
5057
|
-
source: entry.verdict.source
|
|
5313
|
+
action: entry.verdict.action
|
|
5058
5314
|
} } : {},
|
|
5059
5315
|
...entry.pending ? { pending: true } : {},
|
|
5060
5316
|
...entry.pending && entry.judgment ? { judgment: entry.judgment.dir } : {},
|
|
@@ -5067,7 +5323,7 @@ const toSlimAgentReport = (report) => ({
|
|
|
5067
5323
|
*/
|
|
5068
5324
|
const writeAgentVerdict = async (outputDir, name, input) => {
|
|
5069
5325
|
const dir = judgmentDir(outputDir, name);
|
|
5070
|
-
if (!await exists(path.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first
|
|
5326
|
+
if (!await exists(path.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first; only changed screenshots get one.`);
|
|
5071
5327
|
const parsed = parseAgentVerdict(input);
|
|
5072
5328
|
if (!parsed.ok) throw new Error(parsed.error);
|
|
5073
5329
|
const verdictPath = path.join(dir, VERDICT_FILE);
|
|
@@ -5113,6 +5369,6 @@ function resolveWebServerConfig(webServer, configDir, env = process.env) {
|
|
|
5113
5369
|
});
|
|
5114
5370
|
}
|
|
5115
5371
|
//#endregion
|
|
5116
|
-
export { ACTION_BY_LABEL, AGENT_DIRNAME, AGENT_REPORT_VERSION, CONSOLE_LOG_LEVELS, CaptureRunner, DEFAULT_CROP_PADDING, DEFAULT_DEBOUNCE_MS, DEFAULT_IGNORED_DIRS, DEFAULT_KILL_GRACE_MS, DEFAULT_MAX_TASKS, DEFAULT_WEB_SERVER_TIMEOUT_MS, ENGINE_ERROR_CODES, FsScreenshotStore,
|
|
5372
|
+
export { ACTION_BY_LABEL, AGENT_DIRNAME, AGENT_REPORT_VERSION, CONSOLE_LOG_LEVELS, CONTAINER_LABEL, CaptureRunner, DEFAULT_CONTAINER_IMAGE, DEFAULT_CROP_PADDING, DEFAULT_DEBOUNCE_MS, DEFAULT_IGNORED_DIRS, DEFAULT_KILL_GRACE_MS, DEFAULT_MAX_TASKS, DEFAULT_WEB_SERVER_TIMEOUT_MS, ENGINE_ERROR_CODES, FsScreenshotStore, LocalEngine, MANIFEST_FILENAME, MANIFEST_VERSION, NO_WEB_SERVER_HINT, OutputTail, RunInProgressError, RunStore, ScreenshotFileSystem, ScreenshotTool, UnknownTargetsError, VERDICT_LABELS, WarmBrowser, WatchInProgressError, WatchSession, WebServerError, WebServerPool, agentDir, agentReportPath, attachConsoleLogging, clearJudgment, collectScreenshots, compareImages, compareImagesGMSD, contextPadding, defineConfig, describeChange, didScreenshotFail, ensurePlaywrightContainer, filterTasks, findRefusedConnection, fingerprintImages, getDeletedScreenshots, groupScreenshots, imagesMatch, imagesMatchGMSD, isRunInProgressError, isUnknownTargetsError, isUrlReady, isVerdictLabel, isWatchInProgressError, judgmentDir, mapWithConcurrency, measureContentClip, mergeCaptureManifest, normalizeChangeType, padAndClamp, parseAgentVerdict, playwright, readAgentReport, readCaptureManifest, readDiffMeta, recordCaptureOrigins, removePlaywrightContainers, renderJudgmentTiles, renderOverview, resolveBrowserConfig, resolveContainerOptions, resolveCrop, resolveWebServerConfig, runAgentCheck, sameServer, sanitizeScreenshotFilename, selectTasks, spawnServerProcess, toConsoleLogLevel, toDiffMetaPath, toManifestKey, toSerializedError, toSlimAgentReport, toTaskStatus, waitForUrl, writeAgentVerdict };
|
|
5117
5373
|
|
|
5118
5374
|
//# sourceMappingURL=index.mjs.map
|