@cappa/core 0.1.1 → 0.1.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/src/index.ts CHANGED
@@ -1,12 +1,7 @@
1
1
  import { defineConfig } from "./config";
2
2
  import type { Plugin, PluginDef, PluginFunction } from "./plugin";
3
3
  import ScreenshotTool from "./screenshot";
4
- import type {
5
- Exposed,
6
- Screenshot,
7
- ScreenshotOptions,
8
- UserConfig,
9
- } from "./types";
4
+ import type { Screenshot, ScreenshotOptions, UserConfig } from "./types";
10
5
 
11
6
  export {
12
7
  ScreenshotTool,
@@ -16,6 +11,5 @@ export {
16
11
  type PluginDef,
17
12
  type UserConfig,
18
13
  type ScreenshotOptions,
19
- type Exposed,
20
14
  type Screenshot,
21
15
  };
package/src/plugin.ts CHANGED
@@ -1,13 +1,9 @@
1
- import type { ConsolaInstance } from "consola";
2
1
  import type ScreenshotTool from "./screenshot";
3
2
 
4
3
  /**
5
4
  * Plugin function type definition
6
5
  */
7
- export type PluginFunction = (
8
- screenshotTool: ScreenshotTool,
9
- logger: ConsolaInstance,
10
- ) => Promise<any[]>;
6
+ export type PluginFunction = (screenshotTool: ScreenshotTool) => Promise<any[]>;
11
7
 
12
8
  /**
13
9
  * Plugin definition interface
@@ -15,9 +11,7 @@ export type PluginFunction = (
15
11
  export type PluginDef = {
16
12
  name: string;
17
13
  description: string;
18
- version: string;
19
14
  execute: PluginFunction;
20
- validateOptions?: (options: any) => boolean;
21
15
  };
22
16
 
23
17
  /**
package/src/screenshot.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import fs from "node:fs";
2
2
  import path from "node:path";
3
+ import { getLogger, type Logger } from "@cappa/logger";
3
4
  import {
4
5
  type Browser,
5
6
  type BrowserContext,
@@ -15,7 +16,7 @@ import {
15
16
  type CompareResult,
16
17
  compareImages,
17
18
  } from "./compare";
18
- import type { DiffConfig } from "./types";
19
+ import type { DiffConfig, ScreenshotOptions } from "./types";
19
20
 
20
21
  const defaultDiffConfig: DiffConfig = {
21
22
  threshold: 0.1,
@@ -26,39 +27,45 @@ const defaultDiffConfig: DiffConfig = {
26
27
  };
27
28
 
28
29
  class ScreenshotTool {
29
- browserType: string;
30
+ browserType: "chromium" | "firefox" | "webkit";
30
31
  headless: boolean;
31
32
  viewport: { width: number; height: number };
32
33
  outputDir: string;
33
34
  actualDir: string;
34
35
  diffDir: string;
35
36
  expectedDir: string;
36
- fullPage: boolean;
37
37
  browser: Browser | null = null;
38
38
  context: BrowserContext | null = null;
39
39
  page: Page | null = null;
40
40
  diff: DiffConfig;
41
+ logger: Logger;
42
+ retries: number;
41
43
 
42
44
  constructor(options: {
43
- browserType?: string;
45
+ browserType?: "chromium" | "firefox" | "webkit";
44
46
  headless?: boolean;
45
47
  viewport?: { width: number; height: number };
46
48
  outputDir?: string;
47
- fullPage?: boolean;
48
49
  diff?: DiffConfig;
50
+ retries?: number;
49
51
  }) {
50
52
  this.browserType = options.browserType || "chromium";
51
53
  this.headless = options.headless !== false; // Default to headless
52
54
  this.viewport = options.viewport || { width: 1920, height: 1080 };
53
55
  this.outputDir = options.outputDir || "./screenshots";
54
- this.fullPage = options.fullPage !== false; // Default to full page
55
56
  this.diff = { ...defaultDiffConfig, ...options.diff };
56
57
  // Set up subdirectories
57
58
  this.actualDir = path.join(this.outputDir, "actual");
58
59
  this.diffDir = path.join(this.outputDir, "diff");
59
60
  this.expectedDir = path.join(this.outputDir, "expected");
61
+
62
+ this.logger = getLogger();
63
+ this.retries = options.retries || 2;
60
64
  }
61
65
 
66
+ /**
67
+ * Initialize playwright and page
68
+ */
62
69
  async init() {
63
70
  // Create output directories if they don't exist
64
71
  this.createDirectories();
@@ -70,8 +77,7 @@ class ScreenshotTool {
70
77
  webkit,
71
78
  };
72
79
 
73
- const browserClass =
74
- browserMap[this.browserType as keyof typeof browserMap];
80
+ const browserClass = browserMap[this.browserType];
75
81
  if (!browserClass) {
76
82
  throw new Error(`Unsupported browser type: ${this.browserType}`);
77
83
  }
@@ -88,12 +94,16 @@ class ScreenshotTool {
88
94
  reducedMotion: "reduce",
89
95
  deviceScaleFactor: 2,
90
96
  userAgent: `${await defaultUserAgent} CappaStorybook`,
97
+ viewport: this.viewport,
91
98
  });
92
99
 
93
100
  this.page = await this.context?.newPage();
94
- this.page?.setViewportSize(this.viewport);
95
101
  }
96
102
 
103
+ /**
104
+ * Closes browser
105
+ * If not closed, the process will not exit
106
+ */
97
107
  async close() {
98
108
  if (this.context) {
99
109
  await this.context.close();
@@ -103,6 +113,9 @@ class ScreenshotTool {
103
113
  }
104
114
  }
105
115
 
116
+ /**
117
+ * Navigates to a URL with "domcontentloaded" waitUntil
118
+ */
106
119
  async goTo(page: Page, url: string) {
107
120
  if (!this.context) {
108
121
  throw new Error("Browser not initialized");
@@ -110,6 +123,9 @@ class ScreenshotTool {
110
123
  await page.goto(url, { waitUntil: "domcontentloaded" });
111
124
  }
112
125
 
126
+ /**
127
+ * Creates directories for screenshots and other files
128
+ */
113
129
  private createDirectories() {
114
130
  // Create main output directory and subdirectories
115
131
  const directories = [
@@ -122,41 +138,48 @@ class ScreenshotTool {
122
138
  for (const dir of directories) {
123
139
  if (!fs.existsSync(dir)) {
124
140
  fs.mkdirSync(dir, { recursive: true });
125
- console.log(`Created directory: ${dir}`);
141
+ this.logger.debug(`Initialized directory: ${dir}`);
126
142
  }
127
143
  }
128
144
  }
129
145
 
146
+ /**
147
+ * Gets the path to the actual screenshot file
148
+ */
130
149
  getActualFilePath(filename: string): string {
131
150
  return path.join(this.actualDir, filename);
132
151
  }
133
152
 
153
+ /**
154
+ * Gets the path to the diff screenshot file
155
+ */
134
156
  getDiffFilePath(filename: string): string {
135
157
  return path.join(this.diffDir, filename);
136
158
  }
137
159
 
160
+ /**
161
+ * Gets the path to the expected screenshot file
162
+ */
138
163
  getExpectedFilePath(filename: string): string {
139
164
  return path.join(this.expectedDir, filename);
140
165
  }
141
166
 
142
- // Keep original method for backward compatibility
143
- getFilePath(filename: string) {
144
- return this.getActualFilePath(filename);
145
- }
146
-
167
+ /**
168
+ * Takes a screenshot of the page
169
+ */
147
170
  async takeScreenshot(
148
171
  page: Page,
149
172
  filename: string,
150
- options: {
151
- fullPage?: boolean;
152
- mask?: Locator[];
153
- omitBackground?: boolean;
154
- } = {},
173
+ options: ScreenshotOptions,
155
174
  ) {
156
175
  if (!this.browser) {
157
176
  throw new Error("Browser not initialized");
158
177
  }
159
178
 
179
+ if (options.skip) {
180
+ return;
181
+ }
182
+
160
183
  try {
161
184
  // Generate filename - save to actual directory
162
185
  const filepath = this.getActualFilePath(filename);
@@ -164,74 +187,27 @@ class ScreenshotTool {
164
187
  // Take screenshot
165
188
  const screenshotOptions = {
166
189
  path: filepath,
167
- fullPage:
168
- (options.fullPage as boolean) !== undefined
169
- ? options.fullPage
170
- : this.fullPage,
171
- type: "png",
190
+ fullPage: options.fullPage,
191
+ type: "png" as const,
172
192
  timeout: 60000,
173
193
  mask: options.mask,
174
194
  omitBackground: options.omitBackground,
175
195
  scale: "css" as const,
176
196
  } satisfies PageScreenshotOptions;
177
197
 
178
- await page.screenshot(screenshotOptions);
179
-
180
- console.log(`Screenshot saved: ${filepath}`);
181
- return filepath;
182
- } catch (error) {
183
- console.error(
184
- `Error taking screenshot of ${page.url()}:`,
185
- (error as Error).message,
186
- );
187
- throw error;
188
- }
189
- }
190
-
191
- async takeElementScreenshot(
192
- page: Page,
193
- selector: string,
194
- options: {
195
- filename?: string;
196
- fullPage?: boolean;
197
- } = {},
198
- ) {
199
- if (!this.browser) {
200
- throw new Error("Browser not initialized");
201
- }
202
-
203
- try {
204
- // Wait for element to be visible
205
- await page.waitForSelector(selector, { timeout: 10000 });
206
-
207
- const element = await page.$(selector);
208
- if (!element) {
209
- throw new Error(`Element not found: ${selector}`);
198
+ if (options.delay) {
199
+ await page.waitForTimeout(options.delay);
210
200
  }
211
201
 
212
- const filename =
213
- (options.filename as string | undefined) ||
214
- `${selector.replace(/[^a-zA-Z0-9]/g, "_")}.png`;
215
- // Save to actual directory
216
- const filepath = this.getActualFilePath(filename);
217
-
218
- const elementScreenshotOptions = {
219
- path: filepath,
220
- type: "png",
221
- } satisfies PageScreenshotOptions;
222
-
223
- await element.screenshot(elementScreenshotOptions);
202
+ await page.screenshot(screenshotOptions);
224
203
 
225
- console.log(`Element screenshot saved: ${filepath}`);
226
204
  return filepath;
227
205
  } catch (error) {
228
- console.error(
229
- `Error taking element screenshot of ${page.url()}:`,
206
+ this.logger.error(
207
+ `Error taking screenshot of ${page.url()}:`,
230
208
  (error as Error).message,
231
209
  );
232
210
  throw error;
233
- } finally {
234
- await page.close();
235
211
  }
236
212
  }
237
213
 
@@ -239,16 +215,10 @@ class ScreenshotTool {
239
215
  page: Page,
240
216
  filename: string,
241
217
  referenceImage: Buffer,
242
- options: {
243
- fullPage?: boolean;
244
- mask?: Locator[];
245
- omitBackground?: boolean;
246
- // Comparison options
247
- compareOptions?: CompareOptions;
248
- maxDifferencePercent?: number;
218
+ options: ScreenshotOptions & {
249
219
  saveDiffImage?: boolean;
250
220
  diffImageFilename?: string;
251
- } = {},
221
+ },
252
222
  ): Promise<{
253
223
  screenshotPath: string;
254
224
  comparisonResult: CompareResult;
@@ -265,10 +235,7 @@ class ScreenshotTool {
265
235
 
266
236
  // Take screenshot and get buffer
267
237
  const screenshotOptions = {
268
- fullPage:
269
- (options.fullPage as boolean) !== undefined
270
- ? options.fullPage
271
- : this.fullPage,
238
+ fullPage: options.fullPage,
272
239
  type: "png" as const,
273
240
  timeout: 60000,
274
241
  mask: options.mask,
@@ -276,51 +243,55 @@ class ScreenshotTool {
276
243
  scale: "css" as const,
277
244
  } satisfies PageScreenshotOptions;
278
245
 
279
- // Get screenshot as buffer for comparison
280
- const screenshotBuffer = await page.screenshot(screenshotOptions);
281
-
282
- // Save screenshot to actual directory
283
- fs.writeFileSync(filepath, screenshotBuffer);
284
-
285
- console.log(`Screenshot saved: ${filepath}`);
286
-
287
- // Perform comparison
288
- const comparisonResult = await compareImages(
289
- screenshotBuffer,
246
+ const retryScreenshot = await this.retryScreenshot(
247
+ page,
248
+ filename,
290
249
  referenceImage,
291
- true,
292
- { ...this.diff, ...options.compareOptions },
250
+ screenshotOptions,
293
251
  );
294
252
 
295
- console.log(
296
- `Comparison result: ${comparisonResult.numDiffPixels} pixels different (${comparisonResult.percentDifference.toFixed(2)}%) (${
297
- comparisonResult.passed ? "PASSED" : "FAILED"
298
- })`,
299
- );
253
+ if (!retryScreenshot.screenshotPath) {
254
+ throw new Error("Screenshot buffer is undefined");
255
+ }
256
+
257
+ // Save screenshot to actual directory
258
+ fs.writeFileSync(filepath, retryScreenshot.screenshotPath);
259
+ this.logger.success(`Screenshot saved: ${filepath}`);
260
+
261
+ if (retryScreenshot.passed) {
262
+ this.logger.success(`Screenshot passed visual comparison`);
263
+ } else {
264
+ this.logger.error(`Screenshot failed visual comparison`);
265
+ }
300
266
 
301
267
  let diffImagePath: string | undefined;
302
268
 
303
269
  // Save diff image if requested and there are differences
304
270
  if (
305
271
  options.saveDiffImage &&
306
- comparisonResult.diffBuffer &&
307
- !comparisonResult.passed
272
+ retryScreenshot.comparisonResult.diffBuffer &&
273
+ !retryScreenshot.passed
308
274
  ) {
309
275
  const diffFilename = options.diffImageFilename || filename;
310
276
  // Save to diff directory
311
277
  diffImagePath = this.getDiffFilePath(diffFilename);
312
278
 
313
279
  fs.mkdirSync(path.dirname(diffImagePath), { recursive: true });
314
- fs.writeFileSync(diffImagePath, comparisonResult.diffBuffer);
280
+ fs.writeFileSync(
281
+ diffImagePath,
282
+ retryScreenshot.comparisonResult.diffBuffer,
283
+ );
284
+
285
+ this.logger.debug(`Diff image saved: ${diffImagePath}`);
315
286
  }
316
287
 
317
288
  return {
318
289
  screenshotPath: filepath,
319
- comparisonResult,
290
+ comparisonResult: retryScreenshot.comparisonResult,
320
291
  diffImagePath,
321
292
  };
322
293
  } catch (error) {
323
- console.error(
294
+ this.logger.error(
324
295
  `Error taking screenshot with comparison of ${page.url()}:`,
325
296
  (error as Error).message,
326
297
  );
@@ -328,100 +299,76 @@ class ScreenshotTool {
328
299
  }
329
300
  }
330
301
 
331
- async batchScreenshots(urls: string[], options = {}) {
332
- const results: {
333
- url: string;
334
- success: boolean;
335
- filepath: string;
336
- error?: string;
337
- }[] = [];
338
-
339
- for (const url of urls) {
340
- try {
341
- const page = this.page;
342
- if (!page) {
343
- throw new Error("Page not initialized");
344
- }
345
- await this.goTo(page, url);
346
- const filepath = await this.takeScreenshot(page, url, options);
347
- results.push({ url, success: true, filepath });
348
- } catch (error) {
349
- results.push({
350
- url,
351
- success: false,
352
- error: (error as Error).message,
353
- filepath: "",
354
- });
355
- }
356
- }
357
-
358
- return results;
359
- }
360
-
361
- async takeResponsiveScreenshots(
362
- url: string,
363
- viewports: { width: number; height: number; name: string }[] = [
364
- { width: 1920, height: 1080, name: "desktop" },
365
- { width: 768, height: 1024, name: "tablet" },
366
- { width: 375, height: 667, name: "mobile" },
367
- ],
368
- options: {
369
- fullPage?: boolean;
370
- } = {},
302
+ async retryScreenshot(
303
+ page: Page,
304
+ filename: string,
305
+ referenceImage: Buffer,
306
+ options: ScreenshotOptions & {
307
+ saveDiffImage?: boolean;
308
+ diffImageFilename?: string;
309
+ },
371
310
  ) {
372
- if (!this.context) {
373
- throw new Error("Browser not initialized");
374
- }
375
-
376
- const results: {
377
- viewport: string;
378
- success: boolean;
379
- filepath: string;
380
- error?: string;
381
- }[] = [];
382
-
383
- for (const viewport of viewports) {
311
+ for (let i = 0; i < this.retries; i++) {
384
312
  try {
385
- const page = await this.context?.newPage();
386
- await page.setViewportSize(viewport);
387
-
388
- await page.goto(url, { waitUntil: "domcontentloaded" });
389
- await page.waitForTimeout(2000);
390
-
391
- const filename = `${viewport.name}.png`;
392
- // Save to actual directory
393
- const filepath = this.getActualFilePath(filename);
313
+ const screenshotBuffer = await this.takeScreenshot(page, filename, {
314
+ ...options,
315
+ delay: this.getIncBackoffDelay(i, options.delay || 0),
316
+ });
394
317
 
395
- const responsiveScreenshotOptions = {
396
- path: filepath,
397
- fullPage:
398
- (options.fullPage as boolean) !== undefined
399
- ? options.fullPage
400
- : this.fullPage,
401
- type: "png" as const,
402
- };
318
+ if (!screenshotBuffer) {
319
+ throw new Error("Screenshot buffer is undefined");
320
+ }
403
321
 
404
- await page.screenshot(responsiveScreenshotOptions);
322
+ const comparisonResult = await compareImages(
323
+ screenshotBuffer,
324
+ referenceImage,
325
+ true,
326
+ { ...this.diff, ...options },
327
+ );
405
328
 
406
- await page.close();
329
+ // last retry
330
+ if (i === this.retries - 1 && !comparisonResult.passed) {
331
+ this.logger.error(
332
+ `Failed to match screenshot after ${this.retries} retries`,
333
+ );
334
+ return {
335
+ screenshotPath: screenshotBuffer,
336
+ comparisonResult,
337
+ passed: false,
338
+ };
339
+ }
407
340
 
408
- console.log(`Responsive screenshot saved: ${filepath}`);
409
- results.push({ viewport: viewport.name, success: true, filepath });
341
+ if (comparisonResult.passed) {
342
+ return {
343
+ screenshotPath: screenshotBuffer,
344
+ comparisonResult,
345
+ passed: true,
346
+ };
347
+ } else {
348
+ this.logger.warn(
349
+ `Comparison did not match. Retrying in ${this.getIncBackoffDelay(i + 1, options.delay || 0)}ms... \nComparison result: ${comparisonResult.numDiffPixels} pixels different (${comparisonResult.percentDifference.toFixed(2)}%)`,
350
+ );
351
+ }
410
352
  } catch (error) {
411
- console.error(
412
- `Error taking responsive screenshot for ${viewport.name}:`,
353
+ this.logger.error(
354
+ `Error taking screenshot after ${i + 1} retries:`,
413
355
  (error as Error).message,
414
356
  );
415
- results.push({
416
- viewport: viewport.name,
417
- success: false,
418
- error: (error as Error).message,
419
- filepath: "",
420
- });
421
357
  }
422
358
  }
423
359
 
424
- return results;
360
+ return {
361
+ screenshotPath: null,
362
+ comparisonResult: null,
363
+ passed: false,
364
+ };
365
+ }
366
+
367
+ /**
368
+ * Gets the exponential backoff delay
369
+ */
370
+ getIncBackoffDelay(i: number, delay: number): number {
371
+ return i > 0 ? 500 * 2 ** (i - 1) + (delay || 0) : 0;
425
372
  }
426
373
 
427
374
  // Utility method to check if expected image exists
package/src/types.ts CHANGED
@@ -1,13 +1,17 @@
1
+ import type { Locator } from "playwright-core";
1
2
  import type { Plugin, PluginDef } from "./plugin";
2
3
 
3
4
  export type PossiblePromise<T> = Promise<T> | T;
4
5
 
6
+ /**
7
+ * Configuration for the comparison of images
8
+ */
5
9
  export interface DiffConfig {
6
10
  /**
7
11
  * Matching threshold (0-1). Lower = more sensitive
8
12
  * Default = 0.1
9
13
  *
10
- * This affects how similar a pixel needs to be to the reference image to be considered the same.
14
+ * This affects how similar a pixel needs to be in the reference image to be considered the same.
11
15
  */
12
16
  threshold?: number;
13
17
  /**
@@ -55,34 +59,32 @@ export interface DiffConfig {
55
59
  */
56
60
  export type UserConfig = {
57
61
  /**
58
- * The project root directory, which can be either an absolute path or a path relative to the location of your `cappa.config.ts` file.
59
- * @default process.cwd()
62
+ * The directory to save screenshots and other files in
60
63
  */
61
- root?: string;
62
64
  outputDir?: string;
65
+ /**
66
+ * Configuration for the comparison of images
67
+ */
63
68
  diff?: DiffConfig;
64
69
  /**
65
- * An array of Cappa plugins used for generation. Each plugin may have additional configurable options (defined within the plugin itself). If a plugin relies on another plugin, an error will occur if the required dependency is missing. Refer to "pre" for more details.
70
+ * The number of times to retry a screenshot if it fails
71
+ */
72
+ retries?: number;
73
+ /**
74
+ * An array of Cappa plugins used for generation.
75
+ * Each plugin may have additional configurable options (defined within the plugin itself).
66
76
  */
67
77
  plugins?: Array<Plugin | PluginDef>;
68
78
  };
69
79
 
70
80
  export type ScreenshotOptions = {
71
81
  fullPage?: boolean;
72
- waitForSelector?: string;
73
- waitForTimeout?: number;
74
82
  delay?: number;
75
83
  skip?: boolean;
76
- mask?: string[];
84
+ mask?: Locator[];
77
85
  omitBackground?: boolean;
78
86
  };
79
87
 
80
- export interface Exposed {
81
- emitCapture(opt: ScreenshotOptions): void;
82
- getBaseScreenshotOptions(): ScreenshotOptions;
83
- waitBrowserMetricsStable(): Promise<void>;
84
- }
85
-
86
88
  export interface Screenshot {
87
89
  id: string;
88
90
  name: string;