@cappa/core 0.11.0 → 0.12.1

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 CHANGED
@@ -133,6 +133,28 @@ function injectTextMetadata(buffer, metadata) {
133
133
  buffer.subarray(iendChunk.offset)
134
134
  ]);
135
135
  }
136
+ function isValidPngSignature(buffer) {
137
+ if (buffer.length < pngSignature.length) return false;
138
+ return buffer.subarray(0, pngSignature.length).equals(pngSignature);
139
+ }
140
+ const IHDR_MIN_BYTES = 24;
141
+ async function readIhdrDimensions(source) {
142
+ let buf;
143
+ if (typeof source === "string") {
144
+ const fh = await (0, node_fs_promises.open)(source, "r");
145
+ try {
146
+ buf = Buffer.alloc(IHDR_MIN_BYTES);
147
+ await fh.read(buf, 0, IHDR_MIN_BYTES, 0);
148
+ } finally {
149
+ await fh.close();
150
+ }
151
+ } else buf = source;
152
+ if (buf.length < IHDR_MIN_BYTES || !buf.subarray(0, pngSignature.length).equals(pngSignature)) throw new Error("Not a valid PNG");
153
+ return {
154
+ width: buf.readUInt32BE(16),
155
+ height: buf.readUInt32BE(20)
156
+ };
157
+ }
136
158
  /**
137
159
  * Scans a raw PNG buffer and extracts key-value pairs from `tEXt` chunks.
138
160
  */
@@ -249,7 +271,7 @@ async function compareImagesGMSD(image1, image2, withDiff = false, options = {})
249
271
  });
250
272
  return {
251
273
  gmsd,
252
- diffBuffer: diff ? await annotateDiffImage$1(diff, options).toBuffer() : void 0,
274
+ diffBuffer: diff ? await annotateDiffImage(diff, options).toBuffer() : void 0,
253
275
  passed: gmsd <= (options.threshold ?? .1)
254
276
  };
255
277
  } catch (error) {
@@ -267,7 +289,7 @@ async function compareImagesGMSD(image1, image2, withDiff = false, options = {})
267
289
  async function loadPNG(source) {
268
290
  return PNG.load(source);
269
291
  }
270
- function annotateDiffImage$1(image, options) {
292
+ function annotateDiffImage(image, options) {
271
293
  image.setMetadata("cappa.diff.algorithm", "gmsd");
272
294
  for (const [key, value] of Object.entries(options)) {
273
295
  if (value === void 0) continue;
@@ -296,18 +318,19 @@ async function resolveInputPath(source, fileName, state) {
296
318
  await node_fs_promises.default.access(source, node_fs.default.constants.R_OK);
297
319
  return node_path.default.resolve(source);
298
320
  }
299
- await PNG.load(source);
321
+ if (!isValidPngSignature(source)) throw new Error("Invalid PNG buffer: missing PNG signature");
300
322
  const root = await ensureTempRoot(state);
301
323
  const dest = node_path.default.join(root, fileName);
302
324
  await node_fs_promises.default.writeFile(dest, source);
303
325
  return dest;
304
326
  }
305
- function toNativeOptions(config) {
327
+ function toNativeOptions(config, withDiff) {
306
328
  const extra = config;
307
329
  const out = {
308
330
  threshold: extra.threshold,
309
331
  antialiasing: extra.includeAA ?? false
310
332
  };
333
+ if (extra.interpret && withDiff) out.interpret = true;
311
334
  if (extra.diffMask !== void 0) out.diffMask = extra.diffMask;
312
335
  if (extra.compression !== void 0) out.compression = extra.compression;
313
336
  if (extra.quality !== void 0) out.quality = extra.quality;
@@ -333,7 +356,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
333
356
  }
334
357
  let nativeResult;
335
358
  try {
336
- nativeResult = await (0, _blazediff_core_native.compare)(p1, p2, withDiff ? diffPath : void 0, toNativeOptions(options));
359
+ nativeResult = await (0, _blazediff_core_native.compare)(p1, p2, withDiff ? diffPath : void 0, toNativeOptions(options, withDiff));
337
360
  } catch (error) {
338
361
  (0, _cappa_logger.getLogger)().error(error.message || "Unknown error");
339
362
  return {
@@ -355,7 +378,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
355
378
  differentSizes: true
356
379
  };
357
380
  }
358
- const { width, height } = await PNG.load(p1);
381
+ const { width, height } = await readIhdrDimensions(p1);
359
382
  const totalPixels = width * height;
360
383
  if (nativeResult.match) return {
361
384
  numDiffPixels: 0,
@@ -367,8 +390,10 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
367
390
  };
368
391
  let diffBuffer;
369
392
  if (withDiff && diffPath) {
370
- const raw = await node_fs_promises.default.readFile(diffPath);
371
- diffBuffer = await annotateDiffImage(await PNG.load(raw), options).toBuffer();
393
+ const rawDiff = await node_fs_promises.default.readFile(diffPath);
394
+ const diffMetadata = { "cappa.diff.algorithm": "pixel" };
395
+ for (const [key, value] of Object.entries(options)) if (value !== void 0) diffMetadata[`cappa.diff.${key}`] = String(value);
396
+ diffBuffer = injectTextMetadata(rawDiff, diffMetadata);
372
397
  }
373
398
  const numDiffPixels = nativeResult.diffCount;
374
399
  const percentDifference = nativeResult.diffPercentage;
@@ -378,7 +403,8 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
378
403
  percentDifference,
379
404
  diffBuffer,
380
405
  passed: isPassed(percentDifference, numDiffPixels, options),
381
- differentSizes: false
406
+ differentSizes: false,
407
+ interpretation: nativeResult.interpretation
382
408
  };
383
409
  } finally {
384
410
  if (state.tempRoot) await node_fs_promises.default.rm(state.tempRoot, {
@@ -387,14 +413,6 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
387
413
  }).catch(() => {});
388
414
  }
389
415
  }
390
- function annotateDiffImage(image, options) {
391
- image.setMetadata("cappa.diff.algorithm", "pixel");
392
- for (const [key, value] of Object.entries(options)) {
393
- if (value === void 0) continue;
394
- image.setMetadata(`cappa.diff.${key}`, String(value));
395
- }
396
- return image;
397
- }
398
416
  /**
399
417
  * Quick comparison function that returns only pass/fail
400
418
  * @param image1 - First image (file path or Buffer)
@@ -446,26 +464,48 @@ function defineConfig(options) {
446
464
  /**
447
465
  * Run async work over `items` with at most `concurrency` tasks in flight.
448
466
  * Preserves failure behavior: the first rejection rejects the returned promise.
467
+ * Results are returned in the same order as the input items.
449
468
  */
450
469
  async function mapWithConcurrency(concurrency, items, fn) {
451
- if (items.length === 0) return;
470
+ if (items.length === 0) return [];
452
471
  const workerCount = Math.min(Math.max(1, concurrency), items.length);
472
+ const results = new Array(items.length);
453
473
  let next = 0;
454
- const worker = async () => {
474
+ const worker = async (workerIndex) => {
455
475
  while (true) {
456
476
  const i = next++;
457
477
  if (i >= items.length) return;
458
478
  const item = items[i];
459
479
  if (item === void 0) return;
460
- await fn(item);
480
+ results[i] = await fn(item, workerIndex);
461
481
  }
462
482
  };
463
- await Promise.all(Array.from({ length: workerCount }, () => worker()));
483
+ await Promise.all(Array.from({ length: workerCount }, (_, i) => worker(i)));
484
+ return results;
464
485
  }
465
486
  //#endregion
466
487
  //#region src/filesystem.ts
467
488
  const APPROVE_SCREENSHOTS_CONCURRENCY = 8;
468
489
  /**
490
+ * Map a diff image path to its sidecar metadata path (`.png` -> `.json`).
491
+ */
492
+ function toDiffMetaPath(diffImagePath) {
493
+ const ext = node_path.default.extname(diffImagePath);
494
+ return ext ? `${diffImagePath.slice(0, -ext.length)}.json` : `${diffImagePath}.json`;
495
+ }
496
+ /**
497
+ * Read a diff metadata sidecar, returning `undefined` when it is missing or
498
+ * cannot be parsed (so callers can degrade gracefully).
499
+ */
500
+ async function readDiffMeta(diffImagePath) {
501
+ try {
502
+ const raw = await node_fs_promises.default.readFile(toDiffMetaPath(diffImagePath), "utf8");
503
+ return JSON.parse(raw);
504
+ } catch {
505
+ return;
506
+ }
507
+ }
508
+ /**
469
509
  * Class for interacting with the local file system to store the screenshots.
470
510
  */
471
511
  var ScreenshotFileSystem = class {
@@ -532,7 +572,9 @@ var ScreenshotFileSystem = class {
532
572
  }
533
573
  if (screenshot.category === "changed") {
534
574
  logger.debug(`Deleting diff screenshot: ${screenshot.diffPath}`);
535
- await node_fs_promises.default.unlink(node_path.default.resolve(outputDir, screenshot.diffPath));
575
+ const diffPath = node_path.default.resolve(outputDir, screenshot.diffPath);
576
+ await node_fs_promises.default.unlink(diffPath);
577
+ await node_fs_promises.default.rm(toDiffMetaPath(diffPath), { force: true });
536
578
  await this.approveFromActualPath(node_path.default.resolve(outputDir, screenshot.actualPath));
537
579
  return;
538
580
  }
@@ -572,6 +614,7 @@ var ScreenshotFileSystem = class {
572
614
  }
573
615
  await this.copyDiffMetadataToExpected(diffPath, expectedPath);
574
616
  await node_fs_promises.default.unlink(diffPath);
617
+ await node_fs_promises.default.rm(toDiffMetaPath(diffPath), { force: true });
575
618
  return {
576
619
  actualPath,
577
620
  expectedPath,
@@ -671,6 +714,20 @@ var ScreenshotFileSystem = class {
671
714
  await node_fs_promises.default.writeFile(filepath, data);
672
715
  }
673
716
  /**
717
+ * Get the path to a diff metadata sidecar file (`<name>.json`)
718
+ */
719
+ getDiffMetaFilePath(filename) {
720
+ return toDiffMetaPath(this.getDiffFilePath(filename));
721
+ }
722
+ /**
723
+ * Write a diff metadata sidecar (`diff/<name>.json`) next to the diff image.
724
+ */
725
+ async writeDiffMetaFile(filename, meta) {
726
+ const filepath = this.getDiffMetaFilePath(filename);
727
+ await this.ensureParentDir(filepath);
728
+ await node_fs_promises.default.writeFile(filepath, JSON.stringify(meta));
729
+ }
730
+ /**
674
731
  * Check if an expected file exists
675
732
  */
676
733
  async hasExpectedFile(filename) {
@@ -936,6 +993,12 @@ var ScreenshotTool = class {
936
993
  diffImagePath = this.filesystem.getDiffFilePath(diffFilename);
937
994
  await this.filesystem.writeDiffFile(diffFilename, retryScreenshot.comparisonResult.diffBuffer);
938
995
  this.logger.debug(`Diff image saved: ${diffImagePath}`);
996
+ const result = retryScreenshot.comparisonResult;
997
+ if ("numDiffPixels" in result && result.interpretation) await this.filesystem.writeDiffMetaFile(diffFilename, {
998
+ numDiffPixels: result.numDiffPixels,
999
+ percentDifference: result.percentDifference,
1000
+ interpretation: result.interpretation
1001
+ });
939
1002
  }
940
1003
  if (retryScreenshot.comparisonResult !== null && typeof retryScreenshot.comparisonResult === "object" && "differentSizes" in retryScreenshot.comparisonResult && retryScreenshot.comparisonResult.differentSizes) {
941
1004
  this.logger.warn(`Screenshot has different sizes than reference image`);
@@ -1015,7 +1078,7 @@ var ScreenshotTool = class {
1015
1078
  this.logger.debug(`Expected image not found for ${filename}, taking screenshot`);
1016
1079
  result.filepath = await this.takeScreenshot(page, filename, options);
1017
1080
  } else {
1018
- const { screenshotPath, comparisonResult, diffImagePath } = await this.takeScreenshotWithComparison(page, filename, await this.filesystem.readExpectedFile(filename), {
1081
+ const { screenshotPath, comparisonResult, diffImagePath } = await this.takeScreenshotWithComparison(page, filename, this.filesystem.getExpectedFilePath(filename), {
1019
1082
  ...options,
1020
1083
  saveDiffImage: saveDiff,
1021
1084
  diffImageFilename: diffFilename
@@ -1214,5 +1277,8 @@ exports.compareImagesGMSD = compareImagesGMSD;
1214
1277
  exports.defineConfig = defineConfig;
1215
1278
  exports.imagesMatch = imagesMatch;
1216
1279
  exports.imagesMatchGMSD = imagesMatchGMSD;
1280
+ exports.mapWithConcurrency = mapWithConcurrency;
1281
+ exports.readDiffMeta = readDiffMeta;
1282
+ exports.toDiffMetaPath = toDiffMetaPath;
1217
1283
 
1218
1284
  //# sourceMappingURL=index.cjs.map