@cappa/core 0.5.1 → 0.6.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.d.cts CHANGED
@@ -134,7 +134,7 @@ declare class ScreenshotFileSystem {
134
134
  interface ScreenshotCaptureDetails {
135
135
  filename: string;
136
136
  filepath?: string;
137
- comparisonResult?: CompareResult$1;
137
+ comparisonResult?: CompareResult$1 | CompareResult;
138
138
  diffImagePath?: string;
139
139
  skipped?: boolean;
140
140
  }
@@ -152,13 +152,13 @@ interface ScreenshotCaptureExtras {
152
152
  variants?: Record<string, {
153
153
  saveDiffImage?: boolean;
154
154
  diffImageFilename?: string;
155
- diff?: DiffConfig;
155
+ diff?: DiffOptions;
156
156
  }>;
157
157
  /**
158
158
  * Optional diff configuration override applied to this capture.
159
159
  * Merged on top of the global ScreenshotTool diff config.
160
160
  */
161
- diff?: DiffConfig;
161
+ diff?: DiffOptions;
162
162
  }
163
163
  declare class ScreenshotTool {
164
164
  browserType: "chromium" | "firefox" | "webkit";
@@ -167,6 +167,7 @@ declare class ScreenshotTool {
167
167
  width: number;
168
168
  height: number;
169
169
  };
170
+ fullPage: boolean;
170
171
  outputDir: string;
171
172
  browser: Browser | null;
172
173
  context: BrowserContext | null;
@@ -174,7 +175,7 @@ declare class ScreenshotTool {
174
175
  concurrency: number;
175
176
  contexts: BrowserContext[];
176
177
  pages: Page[];
177
- diff: DiffConfig;
178
+ diff: DiffOptions;
178
179
  logger: Logger;
179
180
  retries: number;
180
181
  filesystem: ScreenshotFileSystem;
@@ -186,12 +187,15 @@ declare class ScreenshotTool {
186
187
  width: number;
187
188
  height: number;
188
189
  };
190
+ fullPage?: boolean;
189
191
  outputDir?: string;
190
- diff?: DiffConfig;
192
+ diff?: DiffOptions;
191
193
  retries?: number;
192
194
  concurrency?: number;
193
195
  logConsoleEvents?: boolean;
194
196
  });
197
+ private resolveDiffOptions;
198
+ private mergeDiffOptions;
195
199
  /**
196
200
  * Initialize playwright and page
197
201
  */
@@ -221,14 +225,14 @@ declare class ScreenshotTool {
221
225
  takeScreenshotWithComparison(page: Page, filename: string, referenceImage: Buffer, options: ScreenshotSettings & {
222
226
  saveDiffImage?: boolean;
223
227
  diffImageFilename?: string;
224
- }, diffOverride?: DiffConfig): Promise<{
228
+ }, diffOverride?: DiffOptions): Promise<{
225
229
  screenshotPath: string;
226
- comparisonResult: CompareResult$1;
230
+ comparisonResult: CompareResult$1 | CompareResult;
227
231
  diffImagePath?: string;
228
232
  }>;
229
- retryScreenshot(page: Page, referenceImage: Buffer, options: ScreenshotSettings, diffOverride?: DiffConfig): Promise<{
233
+ retryScreenshot(page: Page, referenceImage: Buffer, options: ScreenshotSettings, diffOverride?: DiffOptions): Promise<{
230
234
  screenshotPath: Buffer<ArrayBufferLike>;
231
- comparisonResult: CompareResult$1;
235
+ comparisonResult: CompareResult | CompareResult$1;
232
236
  passed: boolean;
233
237
  } | {
234
238
  screenshotPath: null;
@@ -372,6 +376,13 @@ interface DiffConfigGMSD {
372
376
  */
373
377
  c?: number;
374
378
  }
379
+ type DiffOptionsPixel = {
380
+ type?: "pixel";
381
+ } & DiffConfig;
382
+ type DiffOptionsGMSD = {
383
+ type: "gmsd";
384
+ } & DiffConfigGMSD;
385
+ type DiffOptions = DiffOptionsPixel | DiffOptionsGMSD;
375
386
  /**
376
387
  * Config used in `cappa.config.ts`
377
388
  *
@@ -389,11 +400,7 @@ type UserConfig = {
389
400
  /**
390
401
  * Configuration for the comparison of images
391
402
  */
392
- diff?: ({
393
- type: "pixel";
394
- } & DiffConfig) | ({
395
- type: "gmsd";
396
- } & DiffConfigGMSD);
403
+ diff?: DiffOptions;
397
404
  /**
398
405
  * The number of times to retry a screenshot if it fails
399
406
  */
@@ -419,6 +426,22 @@ type UserConfig = {
419
426
  * Receives the failing screenshots so they can be uploaded or processed.
420
427
  */
421
428
  onFail?: (screenshots: FailedScreenshot[]) => PossiblePromise<void>;
429
+ /**
430
+ * Default screenshot settings applied globally.
431
+ * Plugins and per-task options can override these.
432
+ */
433
+ screenshot?: {
434
+ /**
435
+ * Whether to take full page screenshots by default.
436
+ * @default true
437
+ */
438
+ fullPage?: boolean;
439
+ /**
440
+ * Default viewport size for screenshots.
441
+ * @default { width: 1920, height: 1080 }
442
+ */
443
+ viewport?: Viewport;
444
+ };
422
445
  /**
423
446
  * Configuration for the review UI.
424
447
  */
@@ -529,5 +552,5 @@ declare function imagesMatchGMSD(image1: string | Buffer, image2: string | Buffe
529
552
  */
530
553
  declare function defineConfig(options: PossiblePromise<UserConfig> | ((env: ConfigEnv) => PossiblePromise<UserConfig>)): typeof options;
531
554
  //#endregion
532
- export { type ChangedScreenshot, type ConfigEnv, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type FailedScreenshot, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginDef, type PluginFunction, type Screenshot, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, ScreenshotFileSystem, type ScreenshotOptions, type ScreenshotSettings, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type UserConfig, type Viewport, compareImages, compareImagesGMSD, defineConfig, imagesMatch, imagesMatchGMSD };
555
+ export { type ChangedScreenshot, type ConfigEnv, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type FailedScreenshot, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginDef, type PluginFunction, type Screenshot, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, ScreenshotFileSystem, type ScreenshotOptions, type ScreenshotSettings, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type UserConfig, type Viewport, compareImages, compareImagesGMSD, defineConfig, imagesMatch, imagesMatchGMSD };
533
556
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.mts CHANGED
@@ -136,7 +136,7 @@ declare class ScreenshotFileSystem {
136
136
  interface ScreenshotCaptureDetails {
137
137
  filename: string;
138
138
  filepath?: string;
139
- comparisonResult?: CompareResult$1;
139
+ comparisonResult?: CompareResult$1 | CompareResult;
140
140
  diffImagePath?: string;
141
141
  skipped?: boolean;
142
142
  }
@@ -154,13 +154,13 @@ interface ScreenshotCaptureExtras {
154
154
  variants?: Record<string, {
155
155
  saveDiffImage?: boolean;
156
156
  diffImageFilename?: string;
157
- diff?: DiffConfig;
157
+ diff?: DiffOptions;
158
158
  }>;
159
159
  /**
160
160
  * Optional diff configuration override applied to this capture.
161
161
  * Merged on top of the global ScreenshotTool diff config.
162
162
  */
163
- diff?: DiffConfig;
163
+ diff?: DiffOptions;
164
164
  }
165
165
  declare class ScreenshotTool {
166
166
  browserType: "chromium" | "firefox" | "webkit";
@@ -169,6 +169,7 @@ declare class ScreenshotTool {
169
169
  width: number;
170
170
  height: number;
171
171
  };
172
+ fullPage: boolean;
172
173
  outputDir: string;
173
174
  browser: Browser | null;
174
175
  context: BrowserContext | null;
@@ -176,7 +177,7 @@ declare class ScreenshotTool {
176
177
  concurrency: number;
177
178
  contexts: BrowserContext[];
178
179
  pages: Page[];
179
- diff: DiffConfig;
180
+ diff: DiffOptions;
180
181
  logger: Logger;
181
182
  retries: number;
182
183
  filesystem: ScreenshotFileSystem;
@@ -188,12 +189,15 @@ declare class ScreenshotTool {
188
189
  width: number;
189
190
  height: number;
190
191
  };
192
+ fullPage?: boolean;
191
193
  outputDir?: string;
192
- diff?: DiffConfig;
194
+ diff?: DiffOptions;
193
195
  retries?: number;
194
196
  concurrency?: number;
195
197
  logConsoleEvents?: boolean;
196
198
  });
199
+ private resolveDiffOptions;
200
+ private mergeDiffOptions;
197
201
  /**
198
202
  * Initialize playwright and page
199
203
  */
@@ -223,14 +227,14 @@ declare class ScreenshotTool {
223
227
  takeScreenshotWithComparison(page: Page, filename: string, referenceImage: Buffer, options: ScreenshotSettings & {
224
228
  saveDiffImage?: boolean;
225
229
  diffImageFilename?: string;
226
- }, diffOverride?: DiffConfig): Promise<{
230
+ }, diffOverride?: DiffOptions): Promise<{
227
231
  screenshotPath: string;
228
- comparisonResult: CompareResult$1;
232
+ comparisonResult: CompareResult$1 | CompareResult;
229
233
  diffImagePath?: string;
230
234
  }>;
231
- retryScreenshot(page: Page, referenceImage: Buffer, options: ScreenshotSettings, diffOverride?: DiffConfig): Promise<{
235
+ retryScreenshot(page: Page, referenceImage: Buffer, options: ScreenshotSettings, diffOverride?: DiffOptions): Promise<{
232
236
  screenshotPath: Buffer<ArrayBufferLike>;
233
- comparisonResult: CompareResult$1;
237
+ comparisonResult: CompareResult | CompareResult$1;
234
238
  passed: boolean;
235
239
  } | {
236
240
  screenshotPath: null;
@@ -374,6 +378,13 @@ interface DiffConfigGMSD {
374
378
  */
375
379
  c?: number;
376
380
  }
381
+ type DiffOptionsPixel = {
382
+ type?: "pixel";
383
+ } & DiffConfig;
384
+ type DiffOptionsGMSD = {
385
+ type: "gmsd";
386
+ } & DiffConfigGMSD;
387
+ type DiffOptions = DiffOptionsPixel | DiffOptionsGMSD;
377
388
  /**
378
389
  * Config used in `cappa.config.ts`
379
390
  *
@@ -391,11 +402,7 @@ type UserConfig = {
391
402
  /**
392
403
  * Configuration for the comparison of images
393
404
  */
394
- diff?: ({
395
- type: "pixel";
396
- } & DiffConfig) | ({
397
- type: "gmsd";
398
- } & DiffConfigGMSD);
405
+ diff?: DiffOptions;
399
406
  /**
400
407
  * The number of times to retry a screenshot if it fails
401
408
  */
@@ -421,6 +428,22 @@ type UserConfig = {
421
428
  * Receives the failing screenshots so they can be uploaded or processed.
422
429
  */
423
430
  onFail?: (screenshots: FailedScreenshot[]) => PossiblePromise<void>;
431
+ /**
432
+ * Default screenshot settings applied globally.
433
+ * Plugins and per-task options can override these.
434
+ */
435
+ screenshot?: {
436
+ /**
437
+ * Whether to take full page screenshots by default.
438
+ * @default true
439
+ */
440
+ fullPage?: boolean;
441
+ /**
442
+ * Default viewport size for screenshots.
443
+ * @default { width: 1920, height: 1080 }
444
+ */
445
+ viewport?: Viewport;
446
+ };
424
447
  /**
425
448
  * Configuration for the review UI.
426
449
  */
@@ -531,5 +554,5 @@ declare function imagesMatchGMSD(image1: string | Buffer, image2: string | Buffe
531
554
  */
532
555
  declare function defineConfig(options: PossiblePromise<UserConfig> | ((env: ConfigEnv) => PossiblePromise<UserConfig>)): typeof options;
533
556
  //#endregion
534
- export { type ChangedScreenshot, type ConfigEnv, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type FailedScreenshot, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginDef, type PluginFunction, type Screenshot, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, ScreenshotFileSystem, type ScreenshotOptions, type ScreenshotSettings, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type UserConfig, type Viewport, compareImages, compareImagesGMSD, defineConfig, imagesMatch, imagesMatchGMSD };
557
+ export { type ChangedScreenshot, type ConfigEnv, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type FailedScreenshot, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginDef, type PluginFunction, type Screenshot, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, ScreenshotFileSystem, type ScreenshotOptions, type ScreenshotSettings, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type UserConfig, type Viewport, compareImages, compareImagesGMSD, defineConfig, imagesMatch, imagesMatchGMSD };
535
558
  //# sourceMappingURL=index.d.mts.map
package/dist/index.mjs CHANGED
@@ -206,14 +206,14 @@ async function compareImagesGMSD(image1, image2, withDiff = false, options = {})
206
206
  const { width, height } = png1;
207
207
  const diff = withDiff ? PNG$1.create(width, height) : void 0;
208
208
  try {
209
- const gmsd$1 = compare$1(png1.data, png2.data, diff?.data, width, height, {
209
+ const gmsd = compare$1(png1.data, png2.data, diff?.data, width, height, {
210
210
  downsample: options.downsample ?? 0,
211
211
  c: options.c ?? 170
212
212
  });
213
213
  return {
214
- gmsd: gmsd$1,
214
+ gmsd,
215
215
  diffBuffer: diff ? annotateDiffImage$1(diff, options).toBuffer() : void 0,
216
- passed: gmsd$1 <= (options.threshold ?? .1)
216
+ passed: gmsd <= (options.threshold ?? .1)
217
217
  };
218
218
  } catch (error) {
219
219
  getLogger().error(error.message || "Unknown error");
@@ -555,17 +555,25 @@ var ScreenshotFileSystem = class {
555
555
 
556
556
  //#endregion
557
557
  //#region src/screenshot.ts
558
- const defaultDiffConfig = {
558
+ const defaultPixelDiffConfig = {
559
+ type: "pixel",
559
560
  threshold: .1,
560
561
  includeAA: false,
561
562
  fastBufferCheck: true,
562
563
  maxDiffPixels: 0,
563
564
  maxDiffPercentage: 0
564
565
  };
566
+ const defaultGMSDDiffConfig = {
567
+ type: "gmsd",
568
+ threshold: .1,
569
+ downsample: 0,
570
+ c: 170
571
+ };
565
572
  var ScreenshotTool = class {
566
573
  browserType;
567
574
  headless;
568
575
  viewport;
576
+ fullPage;
569
577
  outputDir;
570
578
  browser = null;
571
579
  context = null;
@@ -585,17 +593,40 @@ var ScreenshotTool = class {
585
593
  width: 1920,
586
594
  height: 1080
587
595
  };
596
+ this.fullPage = options.fullPage ?? true;
588
597
  this.outputDir = options.outputDir || "./screenshots";
589
- this.diff = {
590
- ...defaultDiffConfig,
591
- ...options.diff
592
- };
598
+ this.diff = this.resolveDiffOptions(options.diff);
593
599
  this.concurrency = Math.max(1, options.concurrency || 1);
594
600
  this.logConsoleEvents = options.logConsoleEvents ?? true;
595
601
  this.logger = getLogger();
596
602
  this.retries = options.retries || 2;
597
603
  this.filesystem = new ScreenshotFileSystem(this.outputDir);
598
604
  }
605
+ resolveDiffOptions(diff) {
606
+ if (diff?.type === "gmsd") return {
607
+ ...defaultGMSDDiffConfig,
608
+ ...diff
609
+ };
610
+ return {
611
+ ...defaultPixelDiffConfig,
612
+ ...diff,
613
+ type: "pixel"
614
+ };
615
+ }
616
+ mergeDiffOptions(override) {
617
+ const base = this.resolveDiffOptions(this.diff);
618
+ if (!override) return base;
619
+ if (override.type === "gmsd" || base.type === "gmsd") return {
620
+ ...base.type === "gmsd" ? base : defaultGMSDDiffConfig,
621
+ ...override,
622
+ type: "gmsd"
623
+ };
624
+ return {
625
+ ...base,
626
+ ...override,
627
+ type: "pixel"
628
+ };
629
+ }
599
630
  /**
600
631
  * Initialize playwright and page
601
632
  */
@@ -650,7 +681,7 @@ var ScreenshotTool = class {
650
681
  this.filesystem.ensureParentDir(filepath);
651
682
  const screenshotOptions = {
652
683
  path: filepath,
653
- fullPage: options.fullPage,
684
+ fullPage: options.fullPage ?? this.fullPage,
654
685
  type: "png",
655
686
  timeout: 6e4,
656
687
  mask: options.mask,
@@ -660,7 +691,10 @@ var ScreenshotTool = class {
660
691
  caret: "hide"
661
692
  };
662
693
  await this.withViewport(page, options.viewport, async () => {
663
- if (options.delay) await page.waitForTimeout(options.delay);
694
+ if (options.delay) {
695
+ this.logger.debug(`Waiting ${options.delay}ms before taking screenshot`);
696
+ await page.waitForTimeout(options.delay);
697
+ }
664
698
  await page.screenshot(screenshotOptions);
665
699
  });
666
700
  this.logger.success(`Screenshot saved: ${filepath}`);
@@ -693,7 +727,7 @@ var ScreenshotTool = class {
693
727
  if (options.skip) throw new Error("Screenshot skipped");
694
728
  try {
695
729
  const screenshotOptions = {
696
- fullPage: options.fullPage,
730
+ fullPage: options.fullPage ?? this.fullPage,
697
731
  type: "png",
698
732
  timeout: 6e4,
699
733
  mask: options.mask,
@@ -703,7 +737,10 @@ var ScreenshotTool = class {
703
737
  caret: "hide"
704
738
  };
705
739
  return await this.withViewport(page, options.viewport, async () => {
706
- if (options.delay) await page.waitForTimeout(options.delay);
740
+ if (options.delay) {
741
+ this.logger.debug(`Waiting ${options.delay}ms before taking screenshot`);
742
+ await page.waitForTimeout(options.delay);
743
+ }
707
744
  return page.screenshot(screenshotOptions);
708
745
  });
709
746
  } catch (error) {
@@ -716,7 +753,7 @@ var ScreenshotTool = class {
716
753
  try {
717
754
  const filepath = this.filesystem.getActualFilePath(filename);
718
755
  const screenshotSettings = {
719
- fullPage: options.fullPage,
756
+ fullPage: options.fullPage ?? this.fullPage,
720
757
  mask: options.mask,
721
758
  omitBackground: options.omitBackground,
722
759
  delay: options.delay,
@@ -735,7 +772,7 @@ var ScreenshotTool = class {
735
772
  this.filesystem.writeDiffFile(diffFilename, retryScreenshot.comparisonResult.diffBuffer);
736
773
  this.logger.debug(`Diff image saved: ${diffImagePath}`);
737
774
  }
738
- if (retryScreenshot.comparisonResult.differentSizes) {
775
+ if (typeof retryScreenshot.comparisonResult === "object" && "differentSizes" in retryScreenshot.comparisonResult && retryScreenshot.comparisonResult.differentSizes) {
739
776
  this.logger.warn(`Screenshot has different sizes than reference image`);
740
777
  const diffFilename = options.diffImageFilename || filename;
741
778
  diffImagePath = this.filesystem.getDiffFilePath(diffFilename);
@@ -754,18 +791,15 @@ var ScreenshotTool = class {
754
791
  }
755
792
  }
756
793
  async retryScreenshot(page, referenceImage, options, diffOverride) {
757
- const diffConfig = diffOverride ? {
758
- ...this.diff,
759
- ...diffOverride
760
- } : this.diff;
794
+ const diffConfig = this.mergeDiffOptions(diffOverride);
761
795
  for (let i = 0; i < this.retries; i++) try {
762
796
  const screenshotBuffer = await this.takeScreenshotBuffer(page, {
763
797
  ...options,
764
798
  delay: this.getIncBackoffDelay(i, options.delay || 0)
765
799
  });
766
800
  if (!screenshotBuffer) throw new Error("Screenshot buffer is undefined");
767
- const comparisonResult = await compareImages(screenshotBuffer, referenceImage, true, diffConfig);
768
- if (comparisonResult.differentSizes) return {
801
+ const comparisonResult = diffConfig.type === "gmsd" ? await compareImagesGMSD(screenshotBuffer, referenceImage, true, diffConfig) : await compareImages(screenshotBuffer, referenceImage, true, diffConfig);
802
+ if ("differentSizes" in comparisonResult && comparisonResult.differentSizes) return {
769
803
  screenshotPath: screenshotBuffer,
770
804
  comparisonResult,
771
805
  passed: false
@@ -783,7 +817,10 @@ var ScreenshotTool = class {
783
817
  comparisonResult,
784
818
  passed: true
785
819
  };
786
- else this.logger.warn(`Comparison did not match. Retrying in ${this.getIncBackoffDelay(i + 1, options.delay || 0)}ms... \nComparison result: ${comparisonResult.numDiffPixels} pixels different (${comparisonResult.percentDifference.toFixed(2)}%)`);
820
+ else {
821
+ const summary = "numDiffPixels" in comparisonResult ? `${comparisonResult.numDiffPixels} pixels different (${comparisonResult.percentDifference.toFixed(2)}%)` : `gmsd score ${comparisonResult.gmsd.toFixed(4)}`;
822
+ this.logger.warn(`Comparison did not match. Retrying in ${this.getIncBackoffDelay(i + 1, options.delay || 0)}ms... \nComparison result: ${summary}`);
823
+ }
787
824
  } catch (error) {
788
825
  this.logger.error(`Error taking screenshot after ${i + 1} retries:`, error.message);
789
826
  }
@@ -996,8 +1033,7 @@ var ScreenshotTool = class {
996
1033
  return this.pages[index];
997
1034
  }
998
1035
  };
999
- var screenshot_default = ScreenshotTool;
1000
1036
 
1001
1037
  //#endregion
1002
- export { ScreenshotFileSystem, screenshot_default as ScreenshotTool, compareImages, compareImagesGMSD, defineConfig, imagesMatch, imagesMatchGMSD };
1038
+ export { ScreenshotFileSystem, ScreenshotTool, compareImages, compareImagesGMSD, defineConfig, imagesMatch, imagesMatchGMSD };
1003
1039
  //# sourceMappingURL=index.mjs.map