@cappa/core 0.7.1 → 0.7.3

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.d.cts CHANGED
@@ -49,21 +49,26 @@ declare class ScreenshotFileSystem {
49
49
  * @param actualFilePath - The path to the actual screenshot file.
50
50
  * @returns The paths to the actual, expected, and diff screenshot files.
51
51
  */
52
- approveFromActualPath(actualFilePath: string): {
52
+ approveFromActualPath(actualFilePath: string): Promise<{
53
53
  actualPath: string;
54
54
  expectedPath: string;
55
55
  diffPath: string;
56
- };
56
+ }>;
57
+ /**
58
+ * Apply baseline updates for grouped screenshots (same rules as `cappa approve`).
59
+ */
60
+ approveScreenshots(screenshots: Screenshot[], diff: DiffOptions): Promise<void>;
61
+ private approveOneScreenshot;
57
62
  /**
58
63
  * Approve a screenshot based on its name.
59
64
  * @param name - The name of the screenshot. Can include '.png' extension.
60
65
  * @returns The paths to the actual, expected, and diff screenshot files.
61
66
  */
62
- approveByName(name: string): {
67
+ approveByName(name: string): Promise<{
63
68
  actualPath: string;
64
69
  expectedPath: string;
65
70
  diffPath: string;
66
- };
71
+ }>;
67
72
  /**
68
73
  * Approve a screenshot based on a relative path.
69
74
  * @param relativePath - The relative path to the screenshot.
package/dist/index.d.mts CHANGED
@@ -49,21 +49,26 @@ declare class ScreenshotFileSystem {
49
49
  * @param actualFilePath - The path to the actual screenshot file.
50
50
  * @returns The paths to the actual, expected, and diff screenshot files.
51
51
  */
52
- approveFromActualPath(actualFilePath: string): {
52
+ approveFromActualPath(actualFilePath: string): Promise<{
53
53
  actualPath: string;
54
54
  expectedPath: string;
55
55
  diffPath: string;
56
- };
56
+ }>;
57
+ /**
58
+ * Apply baseline updates for grouped screenshots (same rules as `cappa approve`).
59
+ */
60
+ approveScreenshots(screenshots: Screenshot[], diff: DiffOptions): Promise<void>;
61
+ private approveOneScreenshot;
57
62
  /**
58
63
  * Approve a screenshot based on its name.
59
64
  * @param name - The name of the screenshot. Can include '.png' extension.
60
65
  * @returns The paths to the actual, expected, and diff screenshot files.
61
66
  */
62
- approveByName(name: string): {
67
+ approveByName(name: string): Promise<{
63
68
  actualPath: string;
64
69
  expectedPath: string;
65
70
  diffPath: string;
66
- };
71
+ }>;
67
72
  /**
68
73
  * Approve a screenshot based on a relative path.
69
74
  * @param relativePath - The relative path to the screenshot.
package/dist/index.mjs CHANGED
@@ -2,7 +2,7 @@ import fs from "node:fs";
2
2
  import gmsd from "@blazediff/gmsd";
3
3
  import { getLogger } from "@cappa/logger";
4
4
  import fsp, { glob, readFile, writeFile } from "node:fs/promises";
5
- import { PNG } from "pngjs";
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
@@ -204,7 +211,7 @@ async function compareImagesGMSD(image1, image2, withDiff = false, options = {})
204
211
  gmsd: Infinity,
205
212
  passed: false
206
213
  };
207
- const diff = withDiff ? PNG$1.create(width, height) : void 0;
214
+ const diff = withDiff ? PNG.create(width, height) : void 0;
208
215
  try {
209
216
  const gmsd = compare$1(png1.data, png2.data, diff?.data, width, height, {
210
217
  downsample: options.downsample ?? 0,
@@ -212,7 +219,7 @@ async function compareImagesGMSD(image1, image2, withDiff = false, options = {})
212
219
  });
213
220
  return {
214
221
  gmsd,
215
- diffBuffer: diff ? annotateDiffImage$1(diff, options).toBuffer() : void 0,
222
+ diffBuffer: diff ? await annotateDiffImage$1(diff, options).toBuffer() : void 0,
216
223
  passed: gmsd <= (options.threshold ?? .1)
217
224
  };
218
225
  } catch (error) {
@@ -228,7 +235,7 @@ async function compareImagesGMSD(image1, image2, withDiff = false, options = {})
228
235
  * Load a PNG image from file path or Buffer
229
236
  */
230
237
  async function loadPNG$1(source) {
231
- return PNG$1.load(source);
238
+ return PNG.load(source);
232
239
  }
233
240
  function annotateDiffImage$1(image, options) {
234
241
  image.setMetadata("cappa.diff.algorithm", "gmsd");
@@ -271,7 +278,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
271
278
  passed: false,
272
279
  differentSizes: true
273
280
  };
274
- const diff = withDiff ? PNG$1.create(width, height) : void 0;
281
+ const diff = withDiff ? PNG.create(width, height) : void 0;
275
282
  try {
276
283
  const numDiffPixels = compare(png1.data, png2.data, diff?.data, width, height, options);
277
284
  const totalPixels = width * height;
@@ -280,7 +287,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
280
287
  numDiffPixels,
281
288
  totalPixels,
282
289
  percentDifference,
283
- diffBuffer: diff ? annotateDiffImage(diff, options).toBuffer() : void 0,
290
+ diffBuffer: diff ? await annotateDiffImage(diff, options).toBuffer() : void 0,
284
291
  passed: isPassed(percentDifference, numDiffPixels, options),
285
292
  differentSizes: false
286
293
  };
@@ -300,7 +307,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
300
307
  * Load a PNG image from file path or Buffer
301
308
  */
302
309
  async function loadPNG(source) {
303
- return PNG$1.load(source);
310
+ return PNG.load(source);
304
311
  }
305
312
  function annotateDiffImage(image, options) {
306
313
  image.setMetadata("cappa.diff.algorithm", "pixel");
@@ -337,8 +344,8 @@ const isPassed = (percentDifference, numDiffPixels, options) => {
337
344
  * Create different size png image with all pixels red
338
345
  * @returns
339
346
  */
340
- function createDiffSizePngImage(width, height) {
341
- const png = PNG$1.create(width, height);
347
+ async function createDiffSizePngImage(width, height) {
348
+ const png = PNG.create(width, height);
342
349
  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
343
350
  const idx = width * y + x << 2;
344
351
  png.data[idx] = 255;
@@ -357,7 +364,30 @@ function defineConfig(options) {
357
364
  return options;
358
365
  }
359
366
  //#endregion
367
+ //#region src/mapWithConcurrency.ts
368
+ /**
369
+ * Run async work over `items` with at most `concurrency` tasks in flight.
370
+ * Preserves failure behavior: the first rejection rejects the returned promise.
371
+ */
372
+ async function mapWithConcurrency(concurrency, items, fn) {
373
+ if (items.length === 0) return;
374
+ const limit = Math.max(1, concurrency);
375
+ const workerCount = Math.min(limit, items.length);
376
+ let next = 0;
377
+ const worker = async () => {
378
+ while (true) {
379
+ const i = next++;
380
+ if (i >= items.length) return;
381
+ const item = items[i];
382
+ if (item === void 0) return;
383
+ await fn(item);
384
+ }
385
+ };
386
+ await Promise.all(Array.from({ length: workerCount }, () => worker()));
387
+ }
388
+ //#endregion
360
389
  //#region src/filesystem.ts
390
+ const APPROVE_SCREENSHOTS_CONCURRENCY = 8;
361
391
  /**
362
392
  * Class for interacting with the local file system to store the screenshots.
363
393
  */
@@ -397,18 +427,49 @@ var ScreenshotFileSystem = class {
397
427
  * @param actualFilePath - The path to the actual screenshot file.
398
428
  * @returns The paths to the actual, expected, and diff screenshot files.
399
429
  */
400
- approveFromActualPath(actualFilePath) {
430
+ async approveFromActualPath(actualFilePath) {
401
431
  const actualAbsolute = this.resolveActualPath(actualFilePath);
402
432
  const relativePath = path.relative(this.actual, actualAbsolute);
403
433
  if (relativePath.startsWith("..")) throw new Error(`Cannot approve screenshot outside of actual directory: ${actualFilePath}`);
404
434
  return this.approveRelative(relativePath);
405
435
  }
406
436
  /**
437
+ * Apply baseline updates for grouped screenshots (same rules as `cappa approve`).
438
+ */
439
+ async approveScreenshots(screenshots, diff) {
440
+ const outputDir = path.dirname(this.actual);
441
+ await mapWithConcurrency(APPROVE_SCREENSHOTS_CONCURRENCY, screenshots, (screenshot) => this.approveOneScreenshot(screenshot, outputDir, diff));
442
+ }
443
+ async approveOneScreenshot(screenshot, outputDir, diff) {
444
+ const logger = getLogger();
445
+ logger.debug(`Approving screenshot with category: ${screenshot.category}`);
446
+ if (screenshot.category === "new") {
447
+ logger.debug(`Approving new screenshot: ${screenshot.actualPath}`);
448
+ await this.approveFromActualPath(path.resolve(outputDir, screenshot.actualPath));
449
+ return;
450
+ }
451
+ if (screenshot.category === "deleted") {
452
+ logger.debug(`Deleting expected screenshot: ${screenshot.expectedPath}`);
453
+ await fsp.unlink(path.resolve(outputDir, screenshot.expectedPath));
454
+ return;
455
+ }
456
+ if (screenshot.category === "changed") {
457
+ logger.debug(`Deleting diff screenshot: ${screenshot.diffPath}`);
458
+ await fsp.unlink(path.resolve(outputDir, screenshot.diffPath));
459
+ await this.approveFromActualPath(path.resolve(outputDir, screenshot.actualPath));
460
+ return;
461
+ }
462
+ if (screenshot.category === "passed") {
463
+ if (!screenshot.expectedPath) throw new Error("Expected path is required for passed screenshots");
464
+ if (!await imagesMatch(path.resolve(outputDir, screenshot.actualPath), path.resolve(outputDir, screenshot.expectedPath), diff.type === "gmsd" ? { threshold: diff.threshold } : diff)) await this.approveFromActualPath(path.resolve(outputDir, screenshot.actualPath));
465
+ }
466
+ }
467
+ /**
407
468
  * Approve a screenshot based on its name.
408
469
  * @param name - The name of the screenshot. Can include '.png' extension.
409
470
  * @returns The paths to the actual, expected, and diff screenshot files.
410
471
  */
411
- approveByName(name) {
472
+ async approveByName(name) {
412
473
  const relativeWithExtension = name.endsWith(".png") ? name : `${name}.png`;
413
474
  return this.approveRelative(relativeWithExtension);
414
475
  }
@@ -417,35 +478,42 @@ var ScreenshotFileSystem = class {
417
478
  * @param relativePath - The relative path to the screenshot.
418
479
  * @returns The paths to the actual, expected, and diff screenshot files.
419
480
  */
420
- approveRelative(relativePath) {
481
+ async approveRelative(relativePath) {
421
482
  const actualPath = path.resolve(this.actual, relativePath);
422
483
  const expectedPath = path.resolve(this.expected, relativePath);
423
484
  const diffPath = path.resolve(this.diff, relativePath);
424
- this.ensureParentDirSync(expectedPath);
425
- fs.copyFileSync(actualPath, expectedPath);
426
- if (fs.existsSync(diffPath)) {
427
- this.copyDiffMetadataToExpected(diffPath, expectedPath);
428
- fs.unlinkSync(diffPath);
485
+ await this.ensureParentDir(expectedPath);
486
+ await fsp.copyFile(actualPath, expectedPath);
487
+ try {
488
+ await fsp.access(diffPath);
489
+ } catch {
490
+ return {
491
+ actualPath,
492
+ expectedPath,
493
+ diffPath
494
+ };
429
495
  }
496
+ await this.copyDiffMetadataToExpected(diffPath, expectedPath);
497
+ await fsp.unlink(diffPath);
430
498
  return {
431
499
  actualPath,
432
500
  expectedPath,
433
501
  diffPath
434
502
  };
435
503
  }
436
- copyDiffMetadataToExpected(diffPath, expectedPath) {
504
+ async copyDiffMetadataToExpected(diffPath, expectedPath) {
437
505
  const diffExtension = path.extname(diffPath).toLowerCase();
438
506
  const expectedExtension = path.extname(expectedPath).toLowerCase();
439
507
  if (diffExtension !== ".png" || expectedExtension !== ".png") return;
440
508
  try {
441
- const diffMetadata = extractTextMetadata(fs.readFileSync(diffPath));
509
+ const diffMetadata = extractTextMetadata(await fsp.readFile(diffPath));
442
510
  if (Object.keys(diffMetadata).length === 0) return;
443
- const expectedBuffer = fs.readFileSync(expectedPath);
511
+ const expectedBuffer = await fsp.readFile(expectedPath);
444
512
  const expectedWithMetadata = injectTextMetadata(expectedBuffer, {
445
513
  ...extractTextMetadata(expectedBuffer),
446
514
  ...diffMetadata
447
515
  });
448
- fs.writeFileSync(expectedPath, expectedWithMetadata);
516
+ await fsp.writeFile(expectedPath, expectedWithMetadata);
449
517
  } catch {}
450
518
  }
451
519
  /**
@@ -789,7 +857,7 @@ var ScreenshotTool = class {
789
857
  this.logger.warn(`Screenshot has different sizes than reference image`);
790
858
  const diffFilename = options.diffImageFilename || filename;
791
859
  diffImagePath = this.filesystem.getDiffFilePath(diffFilename);
792
- const diffBuffer = createDiffSizePngImage(200, 200);
860
+ const diffBuffer = await createDiffSizePngImage(200, 200);
793
861
  await this.filesystem.writeDiffFile(diffFilename, diffBuffer);
794
862
  this.logger.debug(`Diff Size image saved: ${diffImagePath}`);
795
863
  }
@@ -985,7 +1053,7 @@ var ScreenshotTool = class {
985
1053
  await page.goto(baseUrl);
986
1054
  await this.applyScreenshotOptimizations(page);
987
1055
  await extras.waitForStability?.(page);
988
- }
1056
+ } else baseStart = performance.now();
989
1057
  const baseCaptureResult = await this.captureSingleScreenshot(page, baseFilename, baseOptions, {
990
1058
  saveDiffImage: baseSaveDiff,
991
1059
  diffImageFilename: baseDiffFilename,