@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.cjs
CHANGED
|
@@ -30,6 +30,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
|
|
|
30
30
|
enumerable: true
|
|
31
31
|
}) : target, mod));
|
|
32
32
|
//#endregion
|
|
33
|
+
const require_playwright = require("./playwright.cjs");
|
|
33
34
|
let node_fs = require("node:fs");
|
|
34
35
|
node_fs = __toESM(node_fs);
|
|
35
36
|
let _blazediff_gmsd = require("@blazediff/gmsd");
|
|
@@ -45,9 +46,10 @@ let node_path = require("node:path");
|
|
|
45
46
|
node_path = __toESM(node_path);
|
|
46
47
|
let _blazediff_core_native = require("@blazediff/core-native");
|
|
47
48
|
let _blazediff_interpret_native = require("@blazediff/interpret-native");
|
|
49
|
+
let node_child_process = require("node:child_process");
|
|
48
50
|
let node_crypto = require("node:crypto");
|
|
51
|
+
let node_module = require("node:module");
|
|
49
52
|
let playwright_core = require("playwright-core");
|
|
50
|
-
let node_child_process = require("node:child_process");
|
|
51
53
|
//#region src/features/png/util.ts
|
|
52
54
|
const pngSignature = Buffer.from([
|
|
53
55
|
137,
|
|
@@ -709,6 +711,242 @@ const attachConsoleLogging = (page, setting, logger) => {
|
|
|
709
711
|
});
|
|
710
712
|
};
|
|
711
713
|
//#endregion
|
|
714
|
+
//#region src/container.ts
|
|
715
|
+
/**
|
|
716
|
+
* Runs the official Playwright image for an exact `playwright-core` version
|
|
717
|
+
* through a container CLI (docker, podman, nerdctl, …) and hands back the
|
|
718
|
+
* `run-server` endpoint.
|
|
719
|
+
*
|
|
720
|
+
* Only subcommands all of those CLIs share are used: `version`, `image
|
|
721
|
+
* inspect`, `pull`, `inspect`, `run`, `port`, `logs`, `ps` and `rm`.
|
|
722
|
+
*/
|
|
723
|
+
/** Label on every container cappa starts; `removePlaywrightContainers` finds them by it. */
|
|
724
|
+
const CONTAINER_LABEL = "dev.cappa.playwright";
|
|
725
|
+
/** Port `run-server` listens on inside the container. */
|
|
726
|
+
const SERVER_PORT = 3e3;
|
|
727
|
+
/** Where the host's `playwright-core` is mounted inside the container. */
|
|
728
|
+
const PACKAGE_MOUNT = "/opt/playwright-core";
|
|
729
|
+
const defaultExec = (file, args) => new Promise((resolve, reject) => {
|
|
730
|
+
(0, node_child_process.execFile)(file, args, {
|
|
731
|
+
maxBuffer: 16777216,
|
|
732
|
+
windowsHide: true
|
|
733
|
+
}, (error, stdout, stderr) => {
|
|
734
|
+
if (error) reject(Object.assign(error, {
|
|
735
|
+
stdout,
|
|
736
|
+
stderr
|
|
737
|
+
}));
|
|
738
|
+
else resolve({
|
|
739
|
+
stdout: String(stdout),
|
|
740
|
+
stderr: String(stderr)
|
|
741
|
+
});
|
|
742
|
+
});
|
|
743
|
+
});
|
|
744
|
+
/** `true` once `run-server` answers plain HTTP with `Running`. */
|
|
745
|
+
const defaultProbe = async (url) => {
|
|
746
|
+
try {
|
|
747
|
+
const response = await fetch(url, { signal: AbortSignal.timeout(2e3) });
|
|
748
|
+
return response.ok && (await response.text()).includes("Running");
|
|
749
|
+
} catch {
|
|
750
|
+
return false;
|
|
751
|
+
}
|
|
752
|
+
};
|
|
753
|
+
const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
754
|
+
const errorText = (error) => {
|
|
755
|
+
const stderr = error?.stderr;
|
|
756
|
+
if (typeof stderr === "string" && stderr.trim()) return stderr.trim();
|
|
757
|
+
return error instanceof Error ? error.message : String(error);
|
|
758
|
+
};
|
|
759
|
+
const isNotFound = (error) => error?.code === "ENOENT";
|
|
760
|
+
/** `{version}` filled in. */
|
|
761
|
+
const containerImage = (image, version) => image.replaceAll("{version}", version);
|
|
762
|
+
/**
|
|
763
|
+
* Deterministic per version, image and run arguments: changing any of them
|
|
764
|
+
* starts a fresh container instead of reusing one with stale settings.
|
|
765
|
+
*/
|
|
766
|
+
const containerName = (version, image, runArgs, packageDir = "") => {
|
|
767
|
+
const hash = (0, node_crypto.createHash)("sha256").update(JSON.stringify([
|
|
768
|
+
image,
|
|
769
|
+
runArgs,
|
|
770
|
+
packageDir
|
|
771
|
+
])).digest("hex").slice(0, 8);
|
|
772
|
+
return `cappa-playwright-v${version.replace(/[^\w.-]/g, "_")}-${hash}`;
|
|
773
|
+
};
|
|
774
|
+
/** Host port from `<cli> port` output (`127.0.0.1:49153`, maybe several lines). */
|
|
775
|
+
const parsePort = (output) => {
|
|
776
|
+
for (const line of output.split("\n")) {
|
|
777
|
+
const match = line.trim().match(/:(\d+)$/);
|
|
778
|
+
if (match) return Number(match[1]);
|
|
779
|
+
}
|
|
780
|
+
return null;
|
|
781
|
+
};
|
|
782
|
+
/**
|
|
783
|
+
* Start — or reuse — the Playwright server container for `version` and wait
|
|
784
|
+
* until it accepts connections.
|
|
785
|
+
*/
|
|
786
|
+
async function ensurePlaywrightContainer(options) {
|
|
787
|
+
const { version, packageDir, cli, runArgs, readyTimeout, log = () => {}, exec = defaultExec, probe = defaultProbe, sleep = defaultSleep, now = Date.now } = options;
|
|
788
|
+
const image = containerImage(options.image, version);
|
|
789
|
+
const name = containerName(version, image, runArgs, packageDir);
|
|
790
|
+
const deadline = now() + readyTimeout;
|
|
791
|
+
const run = async (args) => {
|
|
792
|
+
try {
|
|
793
|
+
return await exec(cli, args);
|
|
794
|
+
} catch (error) {
|
|
795
|
+
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 });
|
|
796
|
+
throw error;
|
|
797
|
+
}
|
|
798
|
+
};
|
|
799
|
+
try {
|
|
800
|
+
await run(["version"]);
|
|
801
|
+
} catch (error) {
|
|
802
|
+
if (error instanceof Error && error.message.startsWith("Container CLI")) throw error;
|
|
803
|
+
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 });
|
|
804
|
+
}
|
|
805
|
+
const state = async () => {
|
|
806
|
+
try {
|
|
807
|
+
const { stdout } = await run([
|
|
808
|
+
"inspect",
|
|
809
|
+
"--format",
|
|
810
|
+
"{{.State.Running}}",
|
|
811
|
+
name
|
|
812
|
+
]);
|
|
813
|
+
return stdout.trim() === "true" ? "running" : "stopped";
|
|
814
|
+
} catch {
|
|
815
|
+
return "absent";
|
|
816
|
+
}
|
|
817
|
+
};
|
|
818
|
+
const remove = async () => {
|
|
819
|
+
await run([
|
|
820
|
+
"rm",
|
|
821
|
+
"-f",
|
|
822
|
+
name
|
|
823
|
+
]).catch(() => {});
|
|
824
|
+
};
|
|
825
|
+
const stop = async () => {
|
|
826
|
+
await remove();
|
|
827
|
+
};
|
|
828
|
+
let reused = false;
|
|
829
|
+
const current = await state();
|
|
830
|
+
if (current === "running") {
|
|
831
|
+
reused = true;
|
|
832
|
+
log(`Reusing Playwright container ${name}`);
|
|
833
|
+
} else {
|
|
834
|
+
if (current === "stopped") await remove();
|
|
835
|
+
if (!await run([
|
|
836
|
+
"image",
|
|
837
|
+
"inspect",
|
|
838
|
+
image
|
|
839
|
+
]).then(() => true, () => false)) {
|
|
840
|
+
log(`Pulling ${image} (first run only; this can take a few minutes)`);
|
|
841
|
+
try {
|
|
842
|
+
await run(["pull", image]);
|
|
843
|
+
} catch (error) {
|
|
844
|
+
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 });
|
|
845
|
+
}
|
|
846
|
+
}
|
|
847
|
+
log(`Starting Playwright ${version} container ${name}`);
|
|
848
|
+
try {
|
|
849
|
+
await run([
|
|
850
|
+
"run",
|
|
851
|
+
"-d",
|
|
852
|
+
"--init",
|
|
853
|
+
"--ipc=host",
|
|
854
|
+
"--user",
|
|
855
|
+
"pwuser",
|
|
856
|
+
"--workdir",
|
|
857
|
+
"/home/pwuser",
|
|
858
|
+
"-p",
|
|
859
|
+
`127.0.0.1::${SERVER_PORT}`,
|
|
860
|
+
"--mount",
|
|
861
|
+
`type=bind,source=${packageDir},target=${PACKAGE_MOUNT},readonly`,
|
|
862
|
+
"--label",
|
|
863
|
+
`${CONTAINER_LABEL}=${version}`,
|
|
864
|
+
"--name",
|
|
865
|
+
name,
|
|
866
|
+
...runArgs,
|
|
867
|
+
image,
|
|
868
|
+
"node",
|
|
869
|
+
`${PACKAGE_MOUNT}/cli.js`,
|
|
870
|
+
"run-server",
|
|
871
|
+
"--port",
|
|
872
|
+
String(SERVER_PORT),
|
|
873
|
+
"--host",
|
|
874
|
+
"0.0.0.0"
|
|
875
|
+
]);
|
|
876
|
+
} catch (error) {
|
|
877
|
+
if (/already in use|conflict|already exists/i.test(errorText(error))) reused = true;
|
|
878
|
+
else throw new Error(`Could not start ${image}.\n\n${errorText(error)}`, { cause: error });
|
|
879
|
+
}
|
|
880
|
+
}
|
|
881
|
+
const containerLogs = async () => {
|
|
882
|
+
const result = await run([
|
|
883
|
+
"logs",
|
|
884
|
+
"--tail",
|
|
885
|
+
"30",
|
|
886
|
+
name
|
|
887
|
+
]).catch(() => null);
|
|
888
|
+
return result ? `${result.stdout}${result.stderr}`.trim() : "";
|
|
889
|
+
};
|
|
890
|
+
let port = null;
|
|
891
|
+
let attempt = 0;
|
|
892
|
+
while (true) {
|
|
893
|
+
if (port === null) {
|
|
894
|
+
const output = await run([
|
|
895
|
+
"port",
|
|
896
|
+
name,
|
|
897
|
+
`${SERVER_PORT}/tcp`
|
|
898
|
+
]).then((r) => r.stdout, () => "");
|
|
899
|
+
port = parsePort(output);
|
|
900
|
+
}
|
|
901
|
+
if (port !== null && await probe(`http://127.0.0.1:${port}/`)) return {
|
|
902
|
+
wsEndpoint: `ws://127.0.0.1:${port}/`,
|
|
903
|
+
name,
|
|
904
|
+
image,
|
|
905
|
+
reused,
|
|
906
|
+
stop
|
|
907
|
+
};
|
|
908
|
+
attempt++;
|
|
909
|
+
if (attempt % 8 === 0 && await state() !== "running") {
|
|
910
|
+
const logs = await containerLogs();
|
|
911
|
+
await remove();
|
|
912
|
+
throw new Error(`The Playwright container ${name} exited before its server came up.${logs ? `\n\n${logs}` : ""}`);
|
|
913
|
+
}
|
|
914
|
+
if (now() >= deadline) {
|
|
915
|
+
const logs = await containerLogs();
|
|
916
|
+
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}` : ""}`);
|
|
917
|
+
}
|
|
918
|
+
await sleep(250);
|
|
919
|
+
}
|
|
920
|
+
}
|
|
921
|
+
/**
|
|
922
|
+
* Remove every container cappa started, whatever its version. Returns their
|
|
923
|
+
* names.
|
|
924
|
+
*/
|
|
925
|
+
async function removePlaywrightContainers(options) {
|
|
926
|
+
const { cli, exec = defaultExec } = options;
|
|
927
|
+
let stdout;
|
|
928
|
+
try {
|
|
929
|
+
({stdout} = await exec(cli, [
|
|
930
|
+
"ps",
|
|
931
|
+
"-a",
|
|
932
|
+
"--filter",
|
|
933
|
+
`label=${CONTAINER_LABEL}`,
|
|
934
|
+
"--format",
|
|
935
|
+
"{{.Names}}"
|
|
936
|
+
]));
|
|
937
|
+
} catch (error) {
|
|
938
|
+
if (isNotFound(error)) throw new Error(`Container CLI "${cli}" not found.`, { cause: error });
|
|
939
|
+
throw new Error(`"${cli} ps" failed.\n\n${errorText(error)}`, { cause: error });
|
|
940
|
+
}
|
|
941
|
+
const names = stdout.split("\n").map((line) => line.trim()).filter(Boolean);
|
|
942
|
+
if (names.length > 0) await exec(cli, [
|
|
943
|
+
"rm",
|
|
944
|
+
"-f",
|
|
945
|
+
...names
|
|
946
|
+
]);
|
|
947
|
+
return names;
|
|
948
|
+
}
|
|
949
|
+
//#endregion
|
|
712
950
|
//#region src/crop.ts
|
|
713
951
|
const DEFAULT_CROP_PADDING = 8;
|
|
714
952
|
/** The crop to apply, or `undefined` for none. */
|
|
@@ -2017,9 +2255,56 @@ const LOG_SINK_LEVELS = [
|
|
|
2017
2255
|
];
|
|
2018
2256
|
/** A logger-shaped object that forwards every call to `sink`. */
|
|
2019
2257
|
const toSinkLogger = (sink) => Object.fromEntries(LOG_SINK_LEVELS.map((level) => [level, (message, ...args) => sink(level, String(message), ...args)]));
|
|
2258
|
+
const browserMap = {
|
|
2259
|
+
chromium: playwright_core.chromium,
|
|
2260
|
+
firefox: playwright_core.firefox,
|
|
2261
|
+
webkit: playwright_core.webkit
|
|
2262
|
+
};
|
|
2263
|
+
/** Where the remote-browser recipe lives; linked from connection errors. */
|
|
2264
|
+
const REMOTE_BROWSER_DOCS = "https://tim-richter.github.io/cappa/configuration/#connecting-to-a-remote-browser";
|
|
2265
|
+
/** The installed `playwright-core` version, or `null` if it cannot be read. */
|
|
2266
|
+
const clientPlaywrightVersion = () => {
|
|
2267
|
+
try {
|
|
2268
|
+
return (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("playwright-core/package.json").version;
|
|
2269
|
+
} catch {
|
|
2270
|
+
return null;
|
|
2271
|
+
}
|
|
2272
|
+
};
|
|
2273
|
+
/** The installed `playwright-core` directory, symlinks resolved, or `null`. */
|
|
2274
|
+
const clientPlaywrightPackageDir = () => {
|
|
2275
|
+
try {
|
|
2276
|
+
const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
|
|
2277
|
+
return (0, node_fs.realpathSync)(node_path.default.dirname(require$1.resolve("playwright-core/package.json")));
|
|
2278
|
+
} catch {
|
|
2279
|
+
return null;
|
|
2280
|
+
}
|
|
2281
|
+
};
|
|
2282
|
+
/**
|
|
2283
|
+
* Turn a raw `browserType.connect()` failure into something actionable.
|
|
2284
|
+
*
|
|
2285
|
+
* Exported for tests.
|
|
2286
|
+
*/
|
|
2287
|
+
const describeConnectError = (error, wsEndpoint, clientVersion = clientPlaywrightVersion(), container) => {
|
|
2288
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
2289
|
+
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 });
|
|
2290
|
+
if (/version mismatch/i.test(message) || /\b428\b/.test(message)) {
|
|
2291
|
+
const image = clientVersion ? `mcr.microsoft.com/playwright:v${clientVersion}-noble` : "the mcr.microsoft.com/playwright image matching your playwright-core";
|
|
2292
|
+
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 });
|
|
2293
|
+
}
|
|
2294
|
+
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 });
|
|
2295
|
+
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 });
|
|
2296
|
+
};
|
|
2020
2297
|
var ScreenshotTool = class {
|
|
2021
2298
|
browserType;
|
|
2022
2299
|
headless;
|
|
2300
|
+
/** Browser provider, headless mode and instance — see `UserConfig.browser`. */
|
|
2301
|
+
browserConfig;
|
|
2302
|
+
/**
|
|
2303
|
+
* Set when the browser goes away underneath the tool — a remote browser
|
|
2304
|
+
* server restarting, or a local browser crashing. `WarmBrowser` checks it so
|
|
2305
|
+
* it starts a fresh browser instead of handing out a dead one.
|
|
2306
|
+
*/
|
|
2307
|
+
disconnected = false;
|
|
2023
2308
|
viewport;
|
|
2024
2309
|
fullPage;
|
|
2025
2310
|
/** Default content crop; a screenshot's own `crop` overrides it. */
|
|
@@ -2044,14 +2329,20 @@ var ScreenshotTool = class {
|
|
|
2044
2329
|
filesystem;
|
|
2045
2330
|
logConsoleEvents;
|
|
2046
2331
|
connectionTimeout;
|
|
2332
|
+
/** The container `init()` started or reused, when `container` is on. */
|
|
2333
|
+
container = null;
|
|
2047
2334
|
defaultUserAgent = "";
|
|
2048
2335
|
/** The real logger, kept so `setLogSink(null)` restores the same instance. */
|
|
2049
2336
|
baseLogger;
|
|
2050
2337
|
/** Set while a `CaptureRunner` owns this tool — see `setCaptureSink`. */
|
|
2051
2338
|
captureSink = null;
|
|
2052
2339
|
constructor(options) {
|
|
2053
|
-
this.
|
|
2054
|
-
|
|
2340
|
+
this.browserConfig = require_playwright.resolveBrowserConfig(options.browser ?? {
|
|
2341
|
+
headless: options.headless !== false,
|
|
2342
|
+
instances: [{ browser: options.browserType || "chromium" }]
|
|
2343
|
+
});
|
|
2344
|
+
this.browserType = this.browserConfig.instances[0].browser;
|
|
2345
|
+
this.headless = this.browserConfig.headless;
|
|
2055
2346
|
this.viewport = options.viewport || {
|
|
2056
2347
|
width: 1920,
|
|
2057
2348
|
height: 1080
|
|
@@ -2126,34 +2417,85 @@ var ScreenshotTool = class {
|
|
|
2126
2417
|
* Initialize playwright and page
|
|
2127
2418
|
*/
|
|
2128
2419
|
async init() {
|
|
2129
|
-
const
|
|
2130
|
-
|
|
2131
|
-
|
|
2132
|
-
|
|
2133
|
-
|
|
2134
|
-
|
|
2135
|
-
|
|
2420
|
+
const browserType = browserMap[this.browserType];
|
|
2421
|
+
if (!browserType) throw new Error(`Unsupported browser type: ${this.browserType}`);
|
|
2422
|
+
const { launchOptions, connectOptions, contextOptions } = this.browserConfig.provider.options;
|
|
2423
|
+
const launch = {
|
|
2424
|
+
...launchOptions,
|
|
2425
|
+
headless: this.headless
|
|
2426
|
+
};
|
|
2427
|
+
const container = require_playwright.resolveContainerOptions(this.browserConfig.provider.options.container);
|
|
2428
|
+
let connect = connectOptions?.wsEndpoint ? {
|
|
2429
|
+
...connectOptions,
|
|
2430
|
+
wsEndpoint: connectOptions.wsEndpoint
|
|
2431
|
+
} : null;
|
|
2432
|
+
if (connect && container) this.logger.debug(`connectOptions.wsEndpoint is set (${connect.wsEndpoint}); not starting a container.`);
|
|
2433
|
+
else if (container) {
|
|
2434
|
+
const version = clientPlaywrightVersion();
|
|
2435
|
+
const packageDir = clientPlaywrightPackageDir();
|
|
2436
|
+
if (!version || !packageDir) throw new Error("playwright({ container }) needs the installed playwright-core, but its package.json could not be read.");
|
|
2437
|
+
this.container = await ensurePlaywrightContainer({
|
|
2438
|
+
...container,
|
|
2439
|
+
version,
|
|
2440
|
+
packageDir,
|
|
2441
|
+
log: (message) => this.logger.info(message)
|
|
2442
|
+
});
|
|
2443
|
+
connect = {
|
|
2444
|
+
exposeNetwork: "<loopback>",
|
|
2445
|
+
...connectOptions,
|
|
2446
|
+
wsEndpoint: this.container.wsEndpoint
|
|
2447
|
+
};
|
|
2448
|
+
}
|
|
2449
|
+
let browser;
|
|
2450
|
+
if (connect) {
|
|
2451
|
+
const { wsEndpoint, ...options } = connect;
|
|
2452
|
+
try {
|
|
2453
|
+
browser = await browserType.connect(wsEndpoint, {
|
|
2454
|
+
...options,
|
|
2455
|
+
headers: {
|
|
2456
|
+
"x-playwright-launch-options": JSON.stringify(launch),
|
|
2457
|
+
...options.headers
|
|
2458
|
+
}
|
|
2459
|
+
});
|
|
2460
|
+
} catch (error) {
|
|
2461
|
+
throw describeConnectError(error, wsEndpoint, void 0, this.container ?? void 0);
|
|
2462
|
+
}
|
|
2463
|
+
} else browser = await browserType.launch(launch);
|
|
2136
2464
|
if (!browser) throw new Error("Something went wrong with starting the browser.");
|
|
2137
2465
|
this.browser = browser;
|
|
2138
|
-
|
|
2139
|
-
|
|
2140
|
-
|
|
2141
|
-
|
|
2466
|
+
this.disconnected = false;
|
|
2467
|
+
browser.on("disconnected", () => {
|
|
2468
|
+
if (this.browser === browser) this.disconnected = true;
|
|
2469
|
+
});
|
|
2470
|
+
if (!contextOptions?.userAgent) {
|
|
2471
|
+
const tempCtx = await browser.newContext();
|
|
2472
|
+
const tempPage = await tempCtx.newPage();
|
|
2473
|
+
this.defaultUserAgent = await tempPage.evaluate(() => navigator.userAgent);
|
|
2474
|
+
await tempCtx.close();
|
|
2475
|
+
}
|
|
2142
2476
|
await this.createContexts();
|
|
2143
2477
|
}
|
|
2144
2478
|
/**
|
|
2145
2479
|
* Create the pool of browser contexts and pages.
|
|
2480
|
+
*
|
|
2481
|
+
* `contextOptions` from the provider merge over cappa's defaults; the
|
|
2482
|
+
* viewport and the `CappaStorybook` user-agent suffix always win, because
|
|
2483
|
+
* plugins and `isCappa()` rely on them.
|
|
2146
2484
|
*/
|
|
2147
2485
|
async createContexts() {
|
|
2148
2486
|
const browser = this.browser;
|
|
2149
2487
|
if (!browser) throw new Error("Browser not initialized");
|
|
2488
|
+
const { contextOptions, actionTimeout } = this.browserConfig.provider.options;
|
|
2489
|
+
const { viewport: _ignored, ...extraContextOptions } = contextOptions ?? {};
|
|
2150
2490
|
const results = await Promise.all(Array.from({ length: this.concurrency }, async () => {
|
|
2151
2491
|
const context = await browser.newContext({
|
|
2152
2492
|
reducedMotion: "reduce",
|
|
2153
2493
|
deviceScaleFactor: 2,
|
|
2154
|
-
|
|
2494
|
+
...extraContextOptions,
|
|
2495
|
+
userAgent: `${contextOptions?.userAgent ?? this.defaultUserAgent} CappaStorybook`,
|
|
2155
2496
|
viewport: this.viewport
|
|
2156
2497
|
});
|
|
2498
|
+
if (actionTimeout) context.setDefaultTimeout(actionTimeout);
|
|
2157
2499
|
return {
|
|
2158
2500
|
context,
|
|
2159
2501
|
page: await context.newPage()
|
|
@@ -2208,13 +2550,23 @@ var ScreenshotTool = class {
|
|
|
2208
2550
|
this.context = null;
|
|
2209
2551
|
this.page = null;
|
|
2210
2552
|
}
|
|
2211
|
-
|
|
2553
|
+
const browser = this.browser;
|
|
2554
|
+
if (browser) {
|
|
2555
|
+
this.browser = null;
|
|
2212
2556
|
try {
|
|
2213
|
-
await
|
|
2557
|
+
await browser.close();
|
|
2214
2558
|
} catch (error) {
|
|
2215
2559
|
(0, _cappa_logger.getLogger)().debug("Error closing the browser:", error);
|
|
2216
2560
|
}
|
|
2217
|
-
|
|
2561
|
+
}
|
|
2562
|
+
this.disconnected = false;
|
|
2563
|
+
const container = this.container;
|
|
2564
|
+
this.container = null;
|
|
2565
|
+
const options = require_playwright.resolveContainerOptions(this.browserConfig.provider.options.container);
|
|
2566
|
+
if (container && options && !options.keepAlive && !container.reused) try {
|
|
2567
|
+
await container.stop();
|
|
2568
|
+
} catch (error) {
|
|
2569
|
+
(0, _cappa_logger.getLogger)().debug("Error removing the Playwright container:", error);
|
|
2218
2570
|
}
|
|
2219
2571
|
}
|
|
2220
2572
|
/**
|
|
@@ -2633,27 +2985,23 @@ var ScreenshotTool = class {
|
|
|
2633
2985
|
*/
|
|
2634
2986
|
const AGENT_DIRNAME = ".cappa-agent";
|
|
2635
2987
|
/** Bumped only if `request.json` or `report.json` change incompatibly. */
|
|
2636
|
-
const AGENT_REPORT_VERSION =
|
|
2988
|
+
const AGENT_REPORT_VERSION = 2;
|
|
2637
2989
|
const agentDir = (outputDir) => node_path.default.resolve(outputDir, AGENT_DIRNAME);
|
|
2638
2990
|
const judgmentsRoot = (outputDir) => node_path.default.join(agentDir(outputDir), "judgments");
|
|
2639
2991
|
const agentReportPath = (outputDir) => node_path.default.join(agentDir(outputDir), "report.json");
|
|
2640
2992
|
//#endregion
|
|
2641
2993
|
//#region src/agent/verdict.ts
|
|
2642
2994
|
/**
|
|
2643
|
-
* What a
|
|
2995
|
+
* What a judge believes a changed screenshot is, after looking at it.
|
|
2644
2996
|
*
|
|
2645
|
-
*
|
|
2646
|
-
*
|
|
2647
|
-
*
|
|
2997
|
+
* Only a judge labels a change. Cappa's diff threshold already absorbs
|
|
2998
|
+
* sub-pixel rendering differences, so a screenshot that reaches `changed`
|
|
2999
|
+
* differs beyond the tolerance the project configured — and classifying it
|
|
3000
|
+
* from diff signals alone (change types, severity, pixel counts) proved to
|
|
3001
|
+
* mislabel exactly the changes that matter: a font-size change reads as a
|
|
3002
|
+
* harmless shift plus recolour. Every changed screenshot is looked at instead.
|
|
2648
3003
|
*/
|
|
2649
3004
|
const VERDICT_LABELS = [
|
|
2650
|
-
"regression-likely",
|
|
2651
|
-
"intentional-likely",
|
|
2652
|
-
"noise-likely",
|
|
2653
|
-
"ambiguous"
|
|
2654
|
-
];
|
|
2655
|
-
/** The labels a judge may hand back — everything but `ambiguous`. */
|
|
2656
|
-
const JUDGED_LABELS = [
|
|
2657
3005
|
"regression-likely",
|
|
2658
3006
|
"intentional-likely",
|
|
2659
3007
|
"noise-likely"
|
|
@@ -2661,125 +3009,43 @@ const JUDGED_LABELS = [
|
|
|
2661
3009
|
const ACTION_BY_LABEL = {
|
|
2662
3010
|
"regression-likely": "investigate",
|
|
2663
3011
|
"intentional-likely": "approve-if-intended",
|
|
2664
|
-
"noise-likely": "mask-or-approve"
|
|
2665
|
-
ambiguous: "investigate"
|
|
3012
|
+
"noise-likely": "mask-or-approve"
|
|
2666
3013
|
};
|
|
2667
3014
|
const isVerdictLabel = (value) => typeof value === "string" && VERDICT_LABELS.includes(value);
|
|
2668
|
-
const isJudgedLabel = (value) => typeof value === "string" && JUDGED_LABELS.includes(value);
|
|
2669
3015
|
/**
|
|
2670
3016
|
* Change types are normalised to kebab-case before they are compared.
|
|
2671
3017
|
*
|
|
2672
3018
|
* `@blazediff/interpret-native` reports `color-change` today but earlier
|
|
2673
|
-
* releases reported `ColorChange`; normalising keeps the
|
|
2674
|
-
* across a diff-engine upgrade
|
|
2675
|
-
* to `ambiguous`.
|
|
3019
|
+
* releases reported `ColorChange`; normalising keeps the capture report's
|
|
3020
|
+
* labels working across a diff-engine upgrade.
|
|
2676
3021
|
*/
|
|
2677
3022
|
const normalizeChangeType = (changeType) => changeType.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
|
|
2678
|
-
const normalizeSeverity = (severity) => (severity ?? "").toLowerCase();
|
|
2679
|
-
/** Structural: something appeared, vanished or was replaced. */
|
|
2680
|
-
const REGRESSIVE_TYPES = /* @__PURE__ */ new Set([
|
|
2681
|
-
"content-change",
|
|
2682
|
-
"addition",
|
|
2683
|
-
"deletion"
|
|
2684
|
-
]);
|
|
2685
|
-
/** Restyled or moved, with structure intact. */
|
|
2686
|
-
const RESTYLE_TYPES = /* @__PURE__ */ new Set(["color-change", "shift"]);
|
|
2687
|
-
const NOISE_TYPES = /* @__PURE__ */ new Set(["rendering-noise"]);
|
|
2688
|
-
const ELEVATED_SEVERITY = /* @__PURE__ */ new Set(["medium", "high"]);
|
|
2689
|
-
/**
|
|
2690
|
-
* At or below this many differing pixels, a low-severity change is not
|
|
2691
|
-
* perceptible.
|
|
2692
|
-
*
|
|
2693
|
-
* An absolute count rather than a share of the image: a share depends on how
|
|
2694
|
-
* much empty canvas surrounds the content, so the same changed glyph would be
|
|
2695
|
-
* noise in a 1920x1080 capture and a regression in a tight crop of the
|
|
2696
|
-
* component. The pixels that changed are the same either way.
|
|
2697
|
-
*/
|
|
2698
|
-
const SUB_PERCEPTUAL_PIXELS = 25;
|
|
2699
|
-
/** Mean region confidence above which a pure recolour is trusted. */
|
|
2700
|
-
const RECOLOR_CONFIDENCE = .7;
|
|
2701
3023
|
const formatPercent = (percent) => {
|
|
2702
3024
|
if (percent === void 0) return "?%";
|
|
2703
3025
|
return percent >= .01 ? `${percent.toFixed(2)}%` : `${percent.toFixed(3)}%`;
|
|
2704
3026
|
};
|
|
2705
|
-
const countByType = (regions) => {
|
|
2706
|
-
const counts = /* @__PURE__ */ new Map();
|
|
2707
|
-
for (const region of regions) {
|
|
2708
|
-
const type = normalizeChangeType(region.changeType);
|
|
2709
|
-
counts.set(type, (counts.get(type) ?? 0) + 1);
|
|
2710
|
-
}
|
|
2711
|
-
return counts;
|
|
2712
|
-
};
|
|
2713
|
-
const formatBreakdown = (counts) => [...counts].sort((a, b) => b[1] - a[1]).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2714
3027
|
const largestRegion = (regions) => regions.reduce((best, region) => !best || region.pixelCount > best.pixelCount ? region : best, void 0);
|
|
2715
|
-
const meanConfidence = (regions) => regions.length === 0 ? 0 : regions.reduce((sum, region) => sum + (region.confidence ?? 0), 0) / regions.length;
|
|
2716
3028
|
/**
|
|
2717
|
-
* A one-line description of
|
|
2718
|
-
* on different screenshots produces the same
|
|
2719
|
-
*
|
|
2720
|
-
* dozens of screenshots
|
|
3029
|
+
* A one-line description of where and how much a screenshot changed, shaped
|
|
3030
|
+
* so that the same change on different screenshots produces the same text —
|
|
3031
|
+
* which is what lets a judge spot one shared cause (a footer timestamp, a
|
|
3032
|
+
* theme toggle) across dozens of screenshots and judge them together.
|
|
3033
|
+
*
|
|
3034
|
+
* Deliberately geometry only: no change types, no severity. Those are guesses
|
|
3035
|
+
* from pixel signals, and a judge primed with "noise" or "shift" looks less
|
|
3036
|
+
* carefully at what is in fact a regression.
|
|
2721
3037
|
*/
|
|
2722
|
-
const
|
|
2723
|
-
const
|
|
2724
|
-
|
|
2725
|
-
if (input.differentSizes) return hasRegions ? `dimensions changed; ${buildHeadline({
|
|
3038
|
+
const describeChange = (input) => {
|
|
3039
|
+
const regions = input.interpretation?.regions ?? [];
|
|
3040
|
+
if (input.differentSizes) return regions.length > 0 ? `dimensions changed; ${describeChange({
|
|
2726
3041
|
...input,
|
|
2727
3042
|
differentSizes: false
|
|
2728
3043
|
})}` : "image dimensions changed";
|
|
2729
|
-
const percent = input.percentDifference ?? interpretation?.diffPercentage;
|
|
2730
|
-
if (
|
|
2731
|
-
const regions = interpretation.regions;
|
|
2732
|
-
const counts = countByType(regions);
|
|
3044
|
+
const percent = input.percentDifference ?? input.interpretation?.diffPercentage;
|
|
3045
|
+
if (regions.length === 0) return `${(input.numDiffPixels ?? input.interpretation?.diffCount)?.toLocaleString("en-US") ?? "?"} px (${formatPercent(percent)}) - no regions located`;
|
|
2733
3046
|
const position = largestRegion(regions)?.position;
|
|
2734
3047
|
const at = position ? ` @ ${position}` : "";
|
|
2735
|
-
|
|
2736
|
-
if (regions.length === 1) return `1 ${[...counts.keys()][0]}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2737
|
-
return `${regions.length} regions: ${formatBreakdown(counts)}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2738
|
-
};
|
|
2739
|
-
const verdict = (label, headline, rationale) => ({
|
|
2740
|
-
label,
|
|
2741
|
-
headline,
|
|
2742
|
-
rationale,
|
|
2743
|
-
action: ACTION_BY_LABEL[label]
|
|
2744
|
-
});
|
|
2745
|
-
/**
|
|
2746
|
-
* Classify a changed screenshot from its diff interpretation alone.
|
|
2747
|
-
*
|
|
2748
|
-
* Deliberately conservative: only the cases the signals settle are labelled,
|
|
2749
|
-
* and everything else is `ambiguous` so that it reaches a judge who can look
|
|
2750
|
-
* at the pixels. A wrong `noise-likely` hides a regression; a wrong
|
|
2751
|
-
* `ambiguous` costs one look.
|
|
2752
|
-
*/
|
|
2753
|
-
const deriveVerdict = (input) => {
|
|
2754
|
-
const headline = buildHeadline(input);
|
|
2755
|
-
const interpretation = input.interpretation;
|
|
2756
|
-
const hasRegions = (interpretation?.regions.length ?? 0) > 0;
|
|
2757
|
-
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"]);
|
|
2758
|
-
if (!interpretation || !hasRegions) return verdict("ambiguous", headline, ["pixels differ but no change regions were found"]);
|
|
2759
|
-
const classified = classifyRegions(input, interpretation, headline, !input.differentSizes);
|
|
2760
|
-
if (!input.differentSizes) return classified;
|
|
2761
|
-
return {
|
|
2762
|
-
...classified,
|
|
2763
|
-
rationale: ["expected and actual have different dimensions — compared on a canvas padded to the larger size", ...classified.rationale]
|
|
2764
|
-
};
|
|
2765
|
-
};
|
|
2766
|
-
const classifyRegions = (input, interpretation, headline, allowNoise) => {
|
|
2767
|
-
const regions = interpretation.regions;
|
|
2768
|
-
const types = regions.map((region) => normalizeChangeType(region.changeType));
|
|
2769
|
-
const severity = normalizeSeverity(interpretation.severity);
|
|
2770
|
-
const percent = input.percentDifference ?? interpretation.diffPercentage;
|
|
2771
|
-
const pixels = input.numDiffPixels ?? interpretation.diffCount;
|
|
2772
|
-
const counts = countByType(regions);
|
|
2773
|
-
if (allowNoise && types.every((type) => NOISE_TYPES.has(type))) return verdict("noise-likely", headline, ["every region is classified as rendering noise"]);
|
|
2774
|
-
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"]);
|
|
2775
|
-
if (types.some((type) => REGRESSIVE_TYPES.has(type)) && ELEVATED_SEVERITY.has(severity)) {
|
|
2776
|
-
const structural = [...counts].filter(([type]) => REGRESSIVE_TYPES.has(type)).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2777
|
-
return verdict("regression-likely", headline, [`${severity} severity with structural changes (${structural})`, "content or layout changed, not just styling"]);
|
|
2778
|
-
}
|
|
2779
|
-
const allRecolor = types.every((type) => type === "color-change");
|
|
2780
|
-
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"]);
|
|
2781
|
-
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"]);
|
|
2782
|
-
return verdict("ambiguous", headline, [`mix of change types (${formatBreakdown(counts)}) at ${severity || "unknown"} severity`, `${formatPercent(percent)} of the image differs`]);
|
|
3048
|
+
return `${`${regions.length} ${regions.length === 1 ? "region" : "regions"}`}${at} (${formatPercent(percent)})`;
|
|
2783
3049
|
};
|
|
2784
3050
|
//#endregion
|
|
2785
3051
|
//#region src/agent/reviewIndex.ts
|
|
@@ -2797,11 +3063,11 @@ const readAgentReviewIndex = async (outputDir) => {
|
|
|
2797
3063
|
return;
|
|
2798
3064
|
}
|
|
2799
3065
|
const createdAt = typeof raw?.createdAt === "string" ? Date.parse(raw.createdAt) : NaN;
|
|
2800
|
-
if (raw?.version !==
|
|
3066
|
+
if (raw?.version !== 2 || Number.isNaN(createdAt) || !Array.isArray(raw.entries)) return;
|
|
2801
3067
|
const reviews = /* @__PURE__ */ new Map();
|
|
2802
3068
|
for (const entry of raw.entries) {
|
|
2803
3069
|
if (typeof entry !== "object" || entry === null) continue;
|
|
2804
|
-
const { name, category, verdict
|
|
3070
|
+
const { name, category, verdict } = entry;
|
|
2805
3071
|
if (typeof name !== "string" || category !== "changed") continue;
|
|
2806
3072
|
if (typeof verdict !== "object" || verdict === null) continue;
|
|
2807
3073
|
const v = verdict;
|
|
@@ -2811,9 +3077,9 @@ const readAgentReviewIndex = async (outputDir) => {
|
|
|
2811
3077
|
headline: v.headline,
|
|
2812
3078
|
rationale: Array.isArray(v.rationale) ? v.rationale.filter((line) => typeof line === "string") : [],
|
|
2813
3079
|
action: v.action,
|
|
2814
|
-
source:
|
|
3080
|
+
source: "agent",
|
|
2815
3081
|
...typeof v.confidence === "number" ? { confidence: v.confidence } : {},
|
|
2816
|
-
pending:
|
|
3082
|
+
pending: false,
|
|
2817
3083
|
reviewedAt: new Date(createdAt).toISOString()
|
|
2818
3084
|
});
|
|
2819
3085
|
}
|
|
@@ -3538,6 +3804,13 @@ var WarmBrowser = class {
|
|
|
3538
3804
|
if (this.closed) throw new Error("WarmBrowser has been closed");
|
|
3539
3805
|
this.cancelIdleTimer();
|
|
3540
3806
|
this.inUse = true;
|
|
3807
|
+
if (this.tool?.disconnected === true) {
|
|
3808
|
+
const dead = this.tool;
|
|
3809
|
+
this.tool = null;
|
|
3810
|
+
try {
|
|
3811
|
+
await dead.close();
|
|
3812
|
+
} catch {}
|
|
3813
|
+
}
|
|
3541
3814
|
if (this.tool) {
|
|
3542
3815
|
await this.tool.recycleContexts();
|
|
3543
3816
|
return this.tool;
|
|
@@ -4084,7 +4357,8 @@ var LocalEngine = class {
|
|
|
4084
4357
|
width: 1920,
|
|
4085
4358
|
height: 1080
|
|
4086
4359
|
},
|
|
4087
|
-
connectionTimeout: this.options.connectionTimeout
|
|
4360
|
+
connectionTimeout: this.options.connectionTimeout,
|
|
4361
|
+
browser: this.options.browser
|
|
4088
4362
|
});
|
|
4089
4363
|
}
|
|
4090
4364
|
async listPlugins() {
|
|
@@ -4632,6 +4906,9 @@ const renderOverview = async (options) => {
|
|
|
4632
4906
|
* Agent review: turn the screenshots on disk into something a coding agent
|
|
4633
4907
|
* can judge cheaply, and fold its judgments back in.
|
|
4634
4908
|
*
|
|
4909
|
+
* Every changed screenshot gets a judgment request. Nothing is labelled from
|
|
4910
|
+
* diff signals alone — see `VERDICT_LABELS` for why.
|
|
4911
|
+
*
|
|
4635
4912
|
* Nothing here captures. It reads `actual/`, `expected/` and `diff/` as the
|
|
4636
4913
|
* last `cappa capture` left them, so it is safe to run repeatedly — a re-run
|
|
4637
4914
|
* is how an agent's verdicts are applied, and a re-capture invalidates them
|
|
@@ -4659,11 +4936,6 @@ const JUDGMENT_FILES = [
|
|
|
4659
4936
|
"regions.png",
|
|
4660
4937
|
"overview.png"
|
|
4661
4938
|
];
|
|
4662
|
-
const JUDGE_MODES = [
|
|
4663
|
-
"ambiguous",
|
|
4664
|
-
"all",
|
|
4665
|
-
"none"
|
|
4666
|
-
];
|
|
4667
4939
|
/**
|
|
4668
4940
|
* The directory holding a screenshot's judgment.
|
|
4669
4941
|
*
|
|
@@ -4716,7 +4988,7 @@ const parseAgentVerdict = (raw) => {
|
|
|
4716
4988
|
const outer = raw;
|
|
4717
4989
|
const inner = typeof outer.verdict === "object" && outer.verdict !== null ? outer.verdict : outer;
|
|
4718
4990
|
const label = inner.label;
|
|
4719
|
-
if (!
|
|
4991
|
+
if (!isVerdictLabel(label)) return {
|
|
4720
4992
|
ok: false,
|
|
4721
4993
|
error: `label must be one of regression-likely, intentional-likely, noise-likely (got ${JSON.stringify(label)})`
|
|
4722
4994
|
};
|
|
@@ -4768,9 +5040,7 @@ const toAgentRegions = (regions) => [...regions].sort((a, b) => b.pixelCount - a
|
|
|
4768
5040
|
pixelCount: region.pixelCount,
|
|
4769
5041
|
percentage: region.percentage,
|
|
4770
5042
|
position: region.position,
|
|
4771
|
-
shape: region.shape
|
|
4772
|
-
changeType: normalizeChangeType(region.changeType),
|
|
4773
|
-
confidence: region.confidence
|
|
5043
|
+
shape: region.shape
|
|
4774
5044
|
}));
|
|
4775
5045
|
/**
|
|
4776
5046
|
* The interpretation a capture already persisted, or a fresh one.
|
|
@@ -4793,8 +5063,10 @@ const interpretationFor = async (screenshot, expectedPath, actualPath, diff) =>
|
|
|
4793
5063
|
}
|
|
4794
5064
|
};
|
|
4795
5065
|
const JUDGE_INSTRUCTIONS = [
|
|
5066
|
+
"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.",
|
|
4796
5067
|
"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.",
|
|
4797
5068
|
"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.",
|
|
5069
|
+
"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.",
|
|
4798
5070
|
"Only open paths.expected / paths.actual / paths.diff (full size) when a change clearly continues outside its crop.",
|
|
4799
5071
|
"Write verdict.json next to this file, or run `cappa agent judge <name> --label <label> --headline <text>`."
|
|
4800
5072
|
];
|
|
@@ -4852,7 +5124,7 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4852
5124
|
const percentDifference = screenshot.diffMeta?.percentDifference ?? interpretation?.diffPercentage;
|
|
4853
5125
|
const numDiffPixels = screenshot.diffMeta?.numDiffPixels ?? interpretation?.diffCount;
|
|
4854
5126
|
const regions = toAgentRegions(interpretation?.regions ?? []);
|
|
4855
|
-
const
|
|
5127
|
+
const change = describeChange({
|
|
4856
5128
|
percentDifference,
|
|
4857
5129
|
numDiffPixels,
|
|
4858
5130
|
interpretation,
|
|
@@ -4876,20 +5148,13 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4876
5148
|
expected: expectedSize,
|
|
4877
5149
|
actual: actualSize
|
|
4878
5150
|
},
|
|
4879
|
-
|
|
4880
|
-
summary: interpretation?.summary,
|
|
5151
|
+
change,
|
|
4881
5152
|
regions,
|
|
4882
|
-
|
|
4883
|
-
verdict: {
|
|
4884
|
-
...heuristic,
|
|
4885
|
-
source: "heuristic"
|
|
4886
|
-
},
|
|
4887
|
-
pending: false
|
|
5153
|
+
pending: true
|
|
4888
5154
|
};
|
|
4889
5155
|
const dir = judgmentDir(outputDir, screenshot.name);
|
|
4890
5156
|
const requestPath = node_path.default.join(dir, REQUEST_FILE);
|
|
4891
5157
|
const verdictPath = node_path.default.join(dir, VERDICT_FILE);
|
|
4892
|
-
if (!(options.judge === "all" || options.judge === "ambiguous" && heuristic.label === "ambiguous" || await exists(requestPath))) return entry;
|
|
4893
5158
|
const fingerprint = await fingerprintImages(expectedPath, actualPath);
|
|
4894
5159
|
const previous = await readJson(requestPath);
|
|
4895
5160
|
if (previous && previous.fingerprint !== fingerprint) await clearJudgmentFiles(dir);
|
|
@@ -4918,7 +5183,7 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4918
5183
|
}
|
|
4919
5184
|
entry.judgment = judgment;
|
|
4920
5185
|
await writeJson(requestPath, {
|
|
4921
|
-
version:
|
|
5186
|
+
version: 2,
|
|
4922
5187
|
name: entry.name,
|
|
4923
5188
|
taskId: entry.taskId,
|
|
4924
5189
|
plugin: entry.plugin,
|
|
@@ -4926,12 +5191,10 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4926
5191
|
createdAt,
|
|
4927
5192
|
instructions: JUDGE_INSTRUCTIONS,
|
|
4928
5193
|
verdictSchema: VERDICT_SCHEMA,
|
|
4929
|
-
|
|
5194
|
+
change,
|
|
4930
5195
|
percentDifference,
|
|
4931
5196
|
numDiffPixels,
|
|
4932
5197
|
dimensions: entry.dimensions,
|
|
4933
|
-
severity: entry.severity,
|
|
4934
|
-
summary: entry.summary,
|
|
4935
5198
|
regions,
|
|
4936
5199
|
paths: {
|
|
4937
5200
|
locator: judgment.locator,
|
|
@@ -4943,22 +5206,18 @@ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expect
|
|
|
4943
5206
|
verdict: verdictPath
|
|
4944
5207
|
}
|
|
4945
5208
|
});
|
|
4946
|
-
if (!await exists(verdictPath))
|
|
4947
|
-
entry.pending = true;
|
|
4948
|
-
return entry;
|
|
4949
|
-
}
|
|
5209
|
+
if (!await exists(verdictPath)) return entry;
|
|
4950
5210
|
const parsed = parseAgentVerdict(await readJson(verdictPath));
|
|
4951
5211
|
if (!parsed.ok) {
|
|
4952
|
-
entry.pending = true;
|
|
4953
5212
|
entry.verdictError = parsed.error;
|
|
4954
5213
|
return entry;
|
|
4955
5214
|
}
|
|
5215
|
+
entry.pending = false;
|
|
4956
5216
|
entry.verdict = {
|
|
4957
5217
|
label: parsed.label,
|
|
4958
5218
|
headline: parsed.headline,
|
|
4959
5219
|
rationale: parsed.rationale,
|
|
4960
5220
|
action: ACTION_BY_LABEL[parsed.label],
|
|
4961
|
-
source: "agent",
|
|
4962
5221
|
...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
|
|
4963
5222
|
};
|
|
4964
5223
|
return entry;
|
|
@@ -5002,13 +5261,12 @@ const pruneJudgments = async (outputDir, keep) => {
|
|
|
5002
5261
|
}
|
|
5003
5262
|
};
|
|
5004
5263
|
/**
|
|
5005
|
-
* Analyse every non-passing screenshot, write judgment
|
|
5006
|
-
*
|
|
5007
|
-
*
|
|
5264
|
+
* Analyse every non-passing screenshot, write a judgment request for every
|
|
5265
|
+
* changed one, apply any verdicts already written, and persist the full
|
|
5266
|
+
* report to `<outputDir>/.cappa-agent/report.json`.
|
|
5008
5267
|
*/
|
|
5009
5268
|
const runAgentCheck = async (options) => {
|
|
5010
5269
|
const outputDir = node_path.default.resolve(options.outputDir);
|
|
5011
|
-
const judge = options.judge ?? "ambiguous";
|
|
5012
5270
|
const createdAt = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
|
|
5013
5271
|
const screenshots = await collectScreenshots(outputDir);
|
|
5014
5272
|
await node_fs_promises.default.mkdir(agentDir(outputDir), { recursive: true });
|
|
@@ -5016,8 +5274,7 @@ const runAgentCheck = async (options) => {
|
|
|
5016
5274
|
const changed = screenshots.filter((s) => s.category === "changed");
|
|
5017
5275
|
const changedEntries = await mapWithConcurrency(options.concurrency ?? 4, changed, (screenshot) => analyseChanged(screenshot, {
|
|
5018
5276
|
...options,
|
|
5019
|
-
outputDir
|
|
5020
|
-
judge
|
|
5277
|
+
outputDir
|
|
5021
5278
|
}, createdAt));
|
|
5022
5279
|
await pruneJudgments(outputDir, new Set(changedEntries.flatMap((entry) => entry.judgment ? [entry.judgment.dir] : [])));
|
|
5023
5280
|
const otherEntries = screenshots.flatMap((s) => {
|
|
@@ -5042,11 +5299,10 @@ const runAgentCheck = async (options) => {
|
|
|
5042
5299
|
const entries = [...changedEntries, ...otherEntries];
|
|
5043
5300
|
const count = (category) => screenshots.filter((s) => s.category === category).length;
|
|
5044
5301
|
const report = {
|
|
5045
|
-
version:
|
|
5302
|
+
version: 2,
|
|
5046
5303
|
createdAt,
|
|
5047
5304
|
outputDir,
|
|
5048
5305
|
reportPath: agentReportPath(outputDir),
|
|
5049
|
-
judge,
|
|
5050
5306
|
totals: {
|
|
5051
5307
|
total: screenshots.length,
|
|
5052
5308
|
passed: count("passed"),
|
|
@@ -5063,7 +5319,7 @@ const runAgentCheck = async (options) => {
|
|
|
5063
5319
|
/** Read the report the last {@link runAgentCheck} wrote, if any. */
|
|
5064
5320
|
const readAgentReport = async (outputDir) => {
|
|
5065
5321
|
const raw = await readJson(agentReportPath(outputDir));
|
|
5066
|
-
return raw?.version ===
|
|
5322
|
+
return raw?.version === 2 ? raw : void 0;
|
|
5067
5323
|
};
|
|
5068
5324
|
/**
|
|
5069
5325
|
* The report as an agent should first see it: one line of state per
|
|
@@ -5076,11 +5332,11 @@ const toSlimAgentReport = (report) => ({
|
|
|
5076
5332
|
results: report.entries.map((entry) => ({
|
|
5077
5333
|
name: entry.name,
|
|
5078
5334
|
category: entry.category,
|
|
5335
|
+
...entry.change ? { change: entry.change } : {},
|
|
5079
5336
|
...entry.verdict ? { verdict: {
|
|
5080
5337
|
label: entry.verdict.label,
|
|
5081
5338
|
headline: entry.verdict.headline,
|
|
5082
|
-
action: entry.verdict.action
|
|
5083
|
-
source: entry.verdict.source
|
|
5339
|
+
action: entry.verdict.action
|
|
5084
5340
|
} } : {},
|
|
5085
5341
|
...entry.pending ? { pending: true } : {},
|
|
5086
5342
|
...entry.pending && entry.judgment ? { judgment: entry.judgment.dir } : {},
|
|
@@ -5093,7 +5349,7 @@ const toSlimAgentReport = (report) => ({
|
|
|
5093
5349
|
*/
|
|
5094
5350
|
const writeAgentVerdict = async (outputDir, name, input) => {
|
|
5095
5351
|
const dir = judgmentDir(outputDir, name);
|
|
5096
|
-
if (!await exists(node_path.default.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first
|
|
5352
|
+
if (!await exists(node_path.default.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first; only changed screenshots get one.`);
|
|
5097
5353
|
const parsed = parseAgentVerdict(input);
|
|
5098
5354
|
if (!parsed.ok) throw new Error(parsed.error);
|
|
5099
5355
|
const verdictPath = node_path.default.join(dir, VERDICT_FILE);
|
|
@@ -5143,7 +5399,9 @@ exports.ACTION_BY_LABEL = ACTION_BY_LABEL;
|
|
|
5143
5399
|
exports.AGENT_DIRNAME = AGENT_DIRNAME;
|
|
5144
5400
|
exports.AGENT_REPORT_VERSION = AGENT_REPORT_VERSION;
|
|
5145
5401
|
exports.CONSOLE_LOG_LEVELS = CONSOLE_LOG_LEVELS;
|
|
5402
|
+
exports.CONTAINER_LABEL = CONTAINER_LABEL;
|
|
5146
5403
|
exports.CaptureRunner = CaptureRunner;
|
|
5404
|
+
exports.DEFAULT_CONTAINER_IMAGE = require_playwright.DEFAULT_CONTAINER_IMAGE;
|
|
5147
5405
|
exports.DEFAULT_CROP_PADDING = DEFAULT_CROP_PADDING;
|
|
5148
5406
|
exports.DEFAULT_DEBOUNCE_MS = DEFAULT_DEBOUNCE_MS;
|
|
5149
5407
|
exports.DEFAULT_IGNORED_DIRS = DEFAULT_IGNORED_DIRS;
|
|
@@ -5152,8 +5410,6 @@ exports.DEFAULT_MAX_TASKS = DEFAULT_MAX_TASKS;
|
|
|
5152
5410
|
exports.DEFAULT_WEB_SERVER_TIMEOUT_MS = DEFAULT_WEB_SERVER_TIMEOUT_MS;
|
|
5153
5411
|
exports.ENGINE_ERROR_CODES = ENGINE_ERROR_CODES;
|
|
5154
5412
|
exports.FsScreenshotStore = FsScreenshotStore;
|
|
5155
|
-
exports.JUDGED_LABELS = JUDGED_LABELS;
|
|
5156
|
-
exports.JUDGE_MODES = JUDGE_MODES;
|
|
5157
5413
|
exports.LocalEngine = LocalEngine;
|
|
5158
5414
|
exports.MANIFEST_FILENAME = MANIFEST_FILENAME;
|
|
5159
5415
|
exports.MANIFEST_VERSION = MANIFEST_VERSION;
|
|
@@ -5161,7 +5417,6 @@ exports.NO_WEB_SERVER_HINT = NO_WEB_SERVER_HINT;
|
|
|
5161
5417
|
exports.OutputTail = OutputTail;
|
|
5162
5418
|
exports.RunInProgressError = RunInProgressError;
|
|
5163
5419
|
exports.RunStore = RunStore;
|
|
5164
|
-
exports.SUB_PERCEPTUAL_PIXELS = SUB_PERCEPTUAL_PIXELS;
|
|
5165
5420
|
exports.ScreenshotFileSystem = ScreenshotFileSystem;
|
|
5166
5421
|
exports.ScreenshotTool = ScreenshotTool;
|
|
5167
5422
|
exports.UnknownTargetsError = UnknownTargetsError;
|
|
@@ -5174,15 +5429,15 @@ exports.WebServerPool = WebServerPool;
|
|
|
5174
5429
|
exports.agentDir = agentDir;
|
|
5175
5430
|
exports.agentReportPath = agentReportPath;
|
|
5176
5431
|
exports.attachConsoleLogging = attachConsoleLogging;
|
|
5177
|
-
exports.buildHeadline = buildHeadline;
|
|
5178
5432
|
exports.clearJudgment = clearJudgment;
|
|
5179
5433
|
exports.collectScreenshots = collectScreenshots;
|
|
5180
5434
|
exports.compareImages = compareImages;
|
|
5181
5435
|
exports.compareImagesGMSD = compareImagesGMSD;
|
|
5182
5436
|
exports.contextPadding = contextPadding;
|
|
5183
5437
|
exports.defineConfig = defineConfig;
|
|
5184
|
-
exports.
|
|
5438
|
+
exports.describeChange = describeChange;
|
|
5185
5439
|
exports.didScreenshotFail = didScreenshotFail;
|
|
5440
|
+
exports.ensurePlaywrightContainer = ensurePlaywrightContainer;
|
|
5186
5441
|
exports.filterTasks = filterTasks;
|
|
5187
5442
|
exports.findRefusedConnection = findRefusedConnection;
|
|
5188
5443
|
exports.fingerprintImages = fingerprintImages;
|
|
@@ -5190,7 +5445,6 @@ exports.getDeletedScreenshots = getDeletedScreenshots;
|
|
|
5190
5445
|
exports.groupScreenshots = groupScreenshots;
|
|
5191
5446
|
exports.imagesMatch = imagesMatch;
|
|
5192
5447
|
exports.imagesMatchGMSD = imagesMatchGMSD;
|
|
5193
|
-
exports.isJudgedLabel = isJudgedLabel;
|
|
5194
5448
|
exports.isRunInProgressError = isRunInProgressError;
|
|
5195
5449
|
exports.isUnknownTargetsError = isUnknownTargetsError;
|
|
5196
5450
|
exports.isUrlReady = isUrlReady;
|
|
@@ -5203,12 +5457,16 @@ exports.mergeCaptureManifest = mergeCaptureManifest;
|
|
|
5203
5457
|
exports.normalizeChangeType = normalizeChangeType;
|
|
5204
5458
|
exports.padAndClamp = padAndClamp;
|
|
5205
5459
|
exports.parseAgentVerdict = parseAgentVerdict;
|
|
5460
|
+
exports.playwright = require_playwright.playwright;
|
|
5206
5461
|
exports.readAgentReport = readAgentReport;
|
|
5207
5462
|
exports.readCaptureManifest = readCaptureManifest;
|
|
5208
5463
|
exports.readDiffMeta = readDiffMeta;
|
|
5209
5464
|
exports.recordCaptureOrigins = recordCaptureOrigins;
|
|
5465
|
+
exports.removePlaywrightContainers = removePlaywrightContainers;
|
|
5210
5466
|
exports.renderJudgmentTiles = renderJudgmentTiles;
|
|
5211
5467
|
exports.renderOverview = renderOverview;
|
|
5468
|
+
exports.resolveBrowserConfig = require_playwright.resolveBrowserConfig;
|
|
5469
|
+
exports.resolveContainerOptions = require_playwright.resolveContainerOptions;
|
|
5212
5470
|
exports.resolveCrop = resolveCrop;
|
|
5213
5471
|
exports.resolveWebServerConfig = resolveWebServerConfig;
|
|
5214
5472
|
exports.runAgentCheck = runAgentCheck;
|