@cappa/core 0.7.0 → 0.7.2

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.mjs CHANGED
@@ -1,8 +1,8 @@
1
1
  import fs from "node:fs";
2
2
  import gmsd from "@blazediff/gmsd";
3
3
  import { getLogger } from "@cappa/logger";
4
- import { glob, readFile, writeFile } from "node:fs/promises";
5
- import { PNG } from "pngjs";
4
+ import fsp, { glob, readFile, writeFile } from "node:fs/promises";
5
+ import sharp from "sharp";
6
6
  import blazediff from "@blazediff/core";
7
7
  import path from "node:path";
8
8
  import { chromium, firefox, webkit } from "playwright-core";
@@ -121,38 +121,41 @@ function extractTextMetadata(buffer) {
121
121
  //#endregion
122
122
  //#region src/features/png/png.ts
123
123
  /**
124
- * A wrapper around `pngjs` that adds support for reading and writing
125
- * textual metadata (tEXt chunks).
124
+ * A wrapper around `sharp` that adds support for reading and writing
125
+ * textual metadata (tEXt chunks). Used for fast PNG decode/encode.
126
126
  */
127
- var PNG$1 = class PNG$1 {
128
- image;
127
+ var PNG = class PNG {
128
+ width_;
129
+ height_;
130
+ data_;
129
131
  sourcePath;
130
132
  metadataEntries;
131
- constructor(image, sourcePath, metadata) {
132
- this.image = image;
133
+ constructor(width, height, data, sourcePath, metadata) {
134
+ this.width_ = width;
135
+ this.height_ = height;
136
+ this.data_ = data;
133
137
  this.sourcePath = sourcePath;
134
138
  this.metadataEntries = { ...metadata ?? {} };
135
139
  }
136
140
  static create(width, height) {
137
- return new PNG$1(new PNG({
138
- width,
139
- height
140
- }));
141
+ return new PNG(width, height, Buffer.alloc(width * height * 4, 0));
141
142
  }
142
143
  static async load(source) {
143
144
  const buffer = typeof source === "string" ? await readFile(source) : source;
144
- const png = PNG.sync.read(buffer);
145
145
  const metadata = extractTextMetadata(buffer);
146
- return new PNG$1(png, typeof source === "string" ? source : void 0, metadata);
146
+ const { data: raw, info } = await sharp(buffer).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
147
+ const data = Buffer.from(raw);
148
+ const sourcePath = typeof source === "string" ? source : void 0;
149
+ return new PNG(info.width, info.height, data, sourcePath, metadata);
147
150
  }
148
151
  get width() {
149
- return this.image.width;
152
+ return this.width_;
150
153
  }
151
154
  get height() {
152
- return this.image.height;
155
+ return this.height_;
153
156
  }
154
157
  get data() {
155
- return this.image.data;
158
+ return this.data_;
156
159
  }
157
160
  get metadata() {
158
161
  return { ...this.metadataEntries };
@@ -173,15 +176,19 @@ var PNG$1 = class PNG$1 {
173
176
  clearMetadata() {
174
177
  this.metadataEntries = {};
175
178
  }
176
- toBuffer(options) {
177
- const baseBuffer = PNG.sync.write(this.image, options);
179
+ async toBuffer() {
180
+ const baseBuffer = await sharp(this.data_, { raw: {
181
+ width: this.width_,
182
+ height: this.height_,
183
+ channels: 4
184
+ } }).png().toBuffer();
178
185
  if (Object.keys(this.metadataEntries).length === 0) return baseBuffer;
179
186
  return injectTextMetadata(baseBuffer, this.metadataEntries);
180
187
  }
181
- async save(filepath, options) {
188
+ async save(filepath) {
182
189
  const targetPath = filepath ?? this.sourcePath;
183
190
  if (!targetPath) throw new Error("No filepath provided for saving PNG");
184
- await writeFile(targetPath, this.toBuffer(options));
191
+ await writeFile(targetPath, await this.toBuffer());
185
192
  }
186
193
  };
187
194
  //#endregion
@@ -198,14 +205,13 @@ const compare$1 = (image1, image2, diff, width, height, options) => {
198
205
  * @returns Comparison result
199
206
  */
200
207
  async function compareImagesGMSD(image1, image2, withDiff = false, options = {}) {
201
- const png1 = await loadPNG$1(image1);
202
- const png2 = await loadPNG$1(image2);
208
+ const [png1, png2] = await Promise.all([loadPNG$1(image1), loadPNG$1(image2)]);
203
209
  const { width, height } = png1;
204
210
  if (width !== png2.width || height !== png2.height) return {
205
211
  gmsd: Infinity,
206
212
  passed: false
207
213
  };
208
- const diff = withDiff ? PNG$1.create(width, height) : void 0;
214
+ const diff = withDiff ? PNG.create(width, height) : void 0;
209
215
  try {
210
216
  const gmsd = compare$1(png1.data, png2.data, diff?.data, width, height, {
211
217
  downsample: options.downsample ?? 0,
@@ -213,7 +219,7 @@ async function compareImagesGMSD(image1, image2, withDiff = false, options = {})
213
219
  });
214
220
  return {
215
221
  gmsd,
216
- diffBuffer: diff ? annotateDiffImage$1(diff, options).toBuffer() : void 0,
222
+ diffBuffer: diff ? await annotateDiffImage$1(diff, options).toBuffer() : void 0,
217
223
  passed: gmsd <= (options.threshold ?? .1)
218
224
  };
219
225
  } catch (error) {
@@ -229,7 +235,7 @@ async function compareImagesGMSD(image1, image2, withDiff = false, options = {})
229
235
  * Load a PNG image from file path or Buffer
230
236
  */
231
237
  async function loadPNG$1(source) {
232
- return PNG$1.load(source);
238
+ return PNG.load(source);
233
239
  }
234
240
  function annotateDiffImage$1(image, options) {
235
241
  image.setMetadata("cappa.diff.algorithm", "gmsd");
@@ -263,8 +269,7 @@ const compare = (image1, image2, diff, width, height, options) => {
263
269
  * @returns Comparison result
264
270
  */
265
271
  async function compareImages(image1, image2, withDiff = false, options = {}) {
266
- const png1 = await loadPNG(image1);
267
- const png2 = await loadPNG(image2);
272
+ const [png1, png2] = await Promise.all([loadPNG(image1), loadPNG(image2)]);
268
273
  const { width, height } = png1;
269
274
  if (width !== png2.width || height !== png2.height) return {
270
275
  numDiffPixels: 0,
@@ -273,7 +278,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
273
278
  passed: false,
274
279
  differentSizes: true
275
280
  };
276
- const diff = withDiff ? PNG$1.create(width, height) : void 0;
281
+ const diff = withDiff ? PNG.create(width, height) : void 0;
277
282
  try {
278
283
  const numDiffPixels = compare(png1.data, png2.data, diff?.data, width, height, options);
279
284
  const totalPixels = width * height;
@@ -282,7 +287,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
282
287
  numDiffPixels,
283
288
  totalPixels,
284
289
  percentDifference,
285
- diffBuffer: diff ? annotateDiffImage(diff, options).toBuffer() : void 0,
290
+ diffBuffer: diff ? await annotateDiffImage(diff, options).toBuffer() : void 0,
286
291
  passed: isPassed(percentDifference, numDiffPixels, options),
287
292
  differentSizes: false
288
293
  };
@@ -302,7 +307,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
302
307
  * Load a PNG image from file path or Buffer
303
308
  */
304
309
  async function loadPNG(source) {
305
- return PNG$1.load(source);
310
+ return PNG.load(source);
306
311
  }
307
312
  function annotateDiffImage(image, options) {
308
313
  image.setMetadata("cappa.diff.algorithm", "pixel");
@@ -339,8 +344,8 @@ const isPassed = (percentDifference, numDiffPixels, options) => {
339
344
  * Create different size png image with all pixels red
340
345
  * @returns
341
346
  */
342
- function createDiffSizePngImage(width, height) {
343
- const png = PNG$1.create(width, height);
347
+ async function createDiffSizePngImage(width, height) {
348
+ const png = PNG.create(width, height);
344
349
  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
345
350
  const idx = width * y + x << 2;
346
351
  png.data[idx] = 255;
@@ -371,9 +376,9 @@ var ScreenshotFileSystem = class {
371
376
  this.actual = path.resolve(outputDir, "actual");
372
377
  this.expected = path.resolve(outputDir, "expected");
373
378
  this.diff = path.resolve(outputDir, "diff");
374
- this.ensureParentDir(this.actual);
375
- this.ensureParentDir(this.expected);
376
- this.ensureParentDir(this.diff);
379
+ this.ensureParentDirSync(this.actual);
380
+ this.ensureParentDirSync(this.expected);
381
+ this.ensureParentDirSync(this.diff);
377
382
  }
378
383
  clearActual() {
379
384
  this.removeDir(this.actual);
@@ -423,7 +428,7 @@ var ScreenshotFileSystem = class {
423
428
  const actualPath = path.resolve(this.actual, relativePath);
424
429
  const expectedPath = path.resolve(this.expected, relativePath);
425
430
  const diffPath = path.resolve(this.diff, relativePath);
426
- this.ensureParentDir(expectedPath);
431
+ this.ensureParentDirSync(expectedPath);
427
432
  fs.copyFileSync(actualPath, expectedPath);
428
433
  if (fs.existsSync(diffPath)) {
429
434
  this.copyDiffMetadataToExpected(diffPath, expectedPath);
@@ -454,7 +459,14 @@ var ScreenshotFileSystem = class {
454
459
  * Ensure the parent directory of a file exists. If not, it creates it.
455
460
  * @param filePath - The path to the file.
456
461
  */
457
- ensureParentDir(filePath) {
462
+ async ensureParentDir(filePath) {
463
+ const dir = path.dirname(filePath);
464
+ await fsp.mkdir(dir, { recursive: true });
465
+ }
466
+ /**
467
+ * Synchronous version used only during constructor initialization.
468
+ */
469
+ ensureParentDirSync(filePath) {
458
470
  const dir = path.dirname(filePath);
459
471
  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
460
472
  }
@@ -507,33 +519,41 @@ var ScreenshotFileSystem = class {
507
519
  /**
508
520
  * Write a file to the actual directory
509
521
  */
510
- writeActualFile(filename, data) {
522
+ async writeActualFile(filename, data) {
511
523
  const filepath = this.getActualFilePath(filename);
512
- this.ensureParentDir(filepath);
513
- fs.writeFileSync(filepath, data);
524
+ await this.ensureParentDir(filepath);
525
+ await fsp.writeFile(filepath, data);
514
526
  }
515
527
  /**
516
528
  * Write a file to the diff directory
517
529
  */
518
- writeDiffFile(filename, data) {
530
+ async writeDiffFile(filename, data) {
519
531
  const filepath = this.getDiffFilePath(filename);
520
- this.ensureParentDir(filepath);
521
- fs.writeFileSync(filepath, data);
532
+ await this.ensureParentDir(filepath);
533
+ await fsp.writeFile(filepath, data);
522
534
  }
523
535
  /**
524
536
  * Check if an expected file exists
525
537
  */
526
- hasExpectedFile(filename) {
538
+ async hasExpectedFile(filename) {
527
539
  const expectedPath = this.getExpectedFilePath(filename);
528
- return fs.existsSync(expectedPath);
540
+ try {
541
+ await fsp.access(expectedPath);
542
+ return true;
543
+ } catch {
544
+ return false;
545
+ }
529
546
  }
530
547
  /**
531
548
  * Read an expected file
532
549
  */
533
- readExpectedFile(filename) {
550
+ async readExpectedFile(filename) {
534
551
  const expectedPath = this.getExpectedFilePath(filename);
535
- if (!fs.existsSync(expectedPath)) throw new Error(`Expected image not found: ${expectedPath}`);
536
- return fs.readFileSync(expectedPath);
552
+ try {
553
+ return await fsp.readFile(expectedPath);
554
+ } catch {
555
+ throw new Error(`Expected image not found: ${expectedPath}`);
556
+ }
537
557
  }
538
558
  /**
539
559
  * Resolve the actual path of a screenshot file.
@@ -678,7 +698,7 @@ var ScreenshotTool = class {
678
698
  if (options.skip) return;
679
699
  try {
680
700
  const filepath = this.filesystem.getActualFilePath(filename);
681
- this.filesystem.ensureParentDir(filepath);
701
+ await this.filesystem.ensureParentDir(filepath);
682
702
  const screenshotOptions = {
683
703
  path: filepath,
684
704
  fullPage: options.fullPage ?? this.fullPage,
@@ -761,7 +781,7 @@ var ScreenshotTool = class {
761
781
  };
762
782
  const retryScreenshot = await this.retryScreenshot(page, referenceImage, screenshotSettings, diffOverride);
763
783
  if (!retryScreenshot.screenshotPath) throw new Error("Screenshot buffer is undefined");
764
- this.filesystem.writeActualFile(filename, retryScreenshot.screenshotPath);
784
+ await this.filesystem.writeActualFile(filename, retryScreenshot.screenshotPath);
765
785
  this.logger.debug(`Actual screenshot saved: ${filepath}`);
766
786
  if (retryScreenshot.passed) this.logger.success(`Screenshot passed visual comparison`);
767
787
  else this.logger.error(`Screenshot failed visual comparison`);
@@ -769,15 +789,15 @@ var ScreenshotTool = class {
769
789
  if (options.saveDiffImage && retryScreenshot.comparisonResult?.diffBuffer && !retryScreenshot.passed) {
770
790
  const diffFilename = options.diffImageFilename || filename;
771
791
  diffImagePath = this.filesystem.getDiffFilePath(diffFilename);
772
- this.filesystem.writeDiffFile(diffFilename, retryScreenshot.comparisonResult.diffBuffer);
792
+ await this.filesystem.writeDiffFile(diffFilename, retryScreenshot.comparisonResult.diffBuffer);
773
793
  this.logger.debug(`Diff image saved: ${diffImagePath}`);
774
794
  }
775
795
  if (retryScreenshot.comparisonResult !== null && typeof retryScreenshot.comparisonResult === "object" && "differentSizes" in retryScreenshot.comparisonResult && retryScreenshot.comparisonResult.differentSizes) {
776
796
  this.logger.warn(`Screenshot has different sizes than reference image`);
777
797
  const diffFilename = options.diffImageFilename || filename;
778
798
  diffImagePath = this.filesystem.getDiffFilePath(diffFilename);
779
- const diffBuffer = createDiffSizePngImage(200, 200);
780
- this.filesystem.writeDiffFile(diffFilename, diffBuffer);
799
+ const diffBuffer = await createDiffSizePngImage(200, 200);
800
+ await this.filesystem.writeDiffFile(diffFilename, diffBuffer);
781
801
  this.logger.debug(`Diff Size image saved: ${diffImagePath}`);
782
802
  }
783
803
  return {
@@ -842,14 +862,15 @@ var ScreenshotTool = class {
842
862
  result.skipped = true;
843
863
  return result;
844
864
  }
865
+ const start = extras.captureStart ?? performance.now();
845
866
  const saveDiff = extras.saveDiffImage ?? false;
846
867
  const diffFilename = extras.diffImageFilename ?? filename;
847
868
  const diffOverride = extras.diff;
848
- if (!this.filesystem.hasExpectedFile(filename)) {
869
+ if (!await this.filesystem.hasExpectedFile(filename)) {
849
870
  this.logger.debug(`Expected image not found for ${filename}, taking screenshot`);
850
871
  result.filepath = await this.takeScreenshot(page, filename, options);
851
872
  } else {
852
- const { screenshotPath, comparisonResult, diffImagePath } = await this.takeScreenshotWithComparison(page, filename, this.filesystem.readExpectedFile(filename), {
873
+ const { screenshotPath, comparisonResult, diffImagePath } = await this.takeScreenshotWithComparison(page, filename, await this.filesystem.readExpectedFile(filename), {
853
874
  ...options,
854
875
  saveDiffImage: saveDiff,
855
876
  diffImageFilename: diffFilename
@@ -858,6 +879,8 @@ var ScreenshotTool = class {
858
879
  result.comparisonResult = comparisonResult;
859
880
  result.diffImagePath = diffImagePath;
860
881
  }
882
+ const duration = Math.round(performance.now() - start);
883
+ this.logger.debug(`${filename} captured in ${duration}ms`);
861
884
  return result;
862
885
  }
863
886
  async capture(page, filename, options, extras = {}) {
@@ -883,7 +906,8 @@ var ScreenshotTool = class {
883
906
  const baseCaptureResult = await this.captureSingleScreenshot(page, filename, baseOptions, {
884
907
  saveDiffImage: baseSaveDiff,
885
908
  diffImageFilename: baseDiffFilename,
886
- diff: baseDiffOverride
909
+ diff: baseDiffOverride,
910
+ captureStart: extras.captureStart
887
911
  });
888
912
  baseResult.filepath = baseCaptureResult.filepath;
889
913
  baseResult.comparisonResult = baseCaptureResult.comparisonResult;
@@ -961,16 +985,19 @@ var ScreenshotTool = class {
961
985
  const baseSaveDiff = extras.saveDiffImage ?? false;
962
986
  const baseDiffFilename = extras.diffImageFilename ?? baseFilename;
963
987
  const baseDiffOverride = extras.diff;
988
+ let baseStart;
964
989
  if (!extras.skipBaseNavigation) {
990
+ baseStart = performance.now();
965
991
  getLogger().debug(`Going to base URL: ${baseUrl}`);
966
992
  await page.goto(baseUrl);
967
993
  await this.applyScreenshotOptimizations(page);
968
994
  await extras.waitForStability?.(page);
969
- }
995
+ } else baseStart = performance.now();
970
996
  const baseCaptureResult = await this.captureSingleScreenshot(page, baseFilename, baseOptions, {
971
997
  saveDiffImage: baseSaveDiff,
972
998
  diffImageFilename: baseDiffFilename,
973
- diff: baseDiffOverride
999
+ diff: baseDiffOverride,
1000
+ captureStart: extras.captureStart ?? baseStart
974
1001
  });
975
1002
  baseResult.filepath = baseCaptureResult.filepath;
976
1003
  baseResult.comparisonResult = baseCaptureResult.comparisonResult;
@@ -992,6 +1019,7 @@ var ScreenshotTool = class {
992
1019
  variantResults.push(variantResult);
993
1020
  continue;
994
1021
  }
1022
+ const variantStart = performance.now();
995
1023
  getLogger().debug(`Going to variant URL: ${variant.url}`);
996
1024
  await page.goto(variant.url);
997
1025
  await this.applyScreenshotOptimizations(page);
@@ -1003,7 +1031,8 @@ var ScreenshotTool = class {
1003
1031
  const variantCaptureResult = await this.captureSingleScreenshot(page, variantFilename, variantOptions, {
1004
1032
  saveDiffImage: variantSaveDiff,
1005
1033
  diffImageFilename: variantDiffFilename,
1006
- diff: variantDiffOverride
1034
+ diff: variantDiffOverride,
1035
+ captureStart: variantStart
1007
1036
  });
1008
1037
  variantResult.filepath = variantCaptureResult.filepath;
1009
1038
  variantResult.comparisonResult = variantCaptureResult.comparisonResult;