@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.cjs +105 -36
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +9 -4
- package/dist/index.d.mts +9 -4
- package/dist/index.mjs +110 -42
- package/dist/index.mjs.map +1 -1
- package/package.json +7 -8
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
|
|
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 `
|
|
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
|
|
128
|
-
|
|
127
|
+
var PNG = class PNG {
|
|
128
|
+
width_;
|
|
129
|
+
height_;
|
|
130
|
+
data_;
|
|
129
131
|
sourcePath;
|
|
130
132
|
metadataEntries;
|
|
131
|
-
constructor(
|
|
132
|
-
this.
|
|
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
|
|
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
|
-
|
|
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.
|
|
152
|
+
return this.width_;
|
|
150
153
|
}
|
|
151
154
|
get height() {
|
|
152
|
-
return this.
|
|
155
|
+
return this.height_;
|
|
153
156
|
}
|
|
154
157
|
get data() {
|
|
155
|
-
return this.
|
|
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(
|
|
177
|
-
const baseBuffer =
|
|
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
|
|
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(
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
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(
|
|
509
|
+
const diffMetadata = extractTextMetadata(await fsp.readFile(diffPath));
|
|
442
510
|
if (Object.keys(diffMetadata).length === 0) return;
|
|
443
|
-
const expectedBuffer =
|
|
511
|
+
const expectedBuffer = await fsp.readFile(expectedPath);
|
|
444
512
|
const expectedWithMetadata = injectTextMetadata(expectedBuffer, {
|
|
445
513
|
...extractTextMetadata(expectedBuffer),
|
|
446
514
|
...diffMetadata
|
|
447
515
|
});
|
|
448
|
-
|
|
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,
|