@cappa/core 0.1.3 → 0.2.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.ts CHANGED
@@ -8,17 +8,130 @@ interface CompareResult {
8
8
  percentDifference: number;
9
9
  diffBuffer?: Buffer;
10
10
  passed: boolean;
11
+ error?: string;
12
+ differentSizes: boolean;
11
13
  }
14
+ //#endregion
15
+ //#region src/filesystem.d.ts
12
16
  /**
13
- * Compare two PNG images and return the difference
14
- * @param image1 - First image (file path or Buffer)
15
- * @param image2 - Second image (file path or Buffer)
16
- * @param withDiff - Whether to create a diff image
17
- * @param options - Comparison options
18
- * @returns Comparison result
17
+ * Class for interacting with the local file system to store the screenshots.
19
18
  */
19
+ declare class ScreenshotFileSystem {
20
+ private readonly actualDir;
21
+ private readonly expectedDir;
22
+ private readonly diffDir;
23
+ constructor(outputDir: string);
24
+ clearActual(): void;
25
+ clearDiff(): void;
26
+ clearActualAndDiff(): void;
27
+ /**
28
+ * Approve a screenshot based on its actual file path.
29
+ * @param actualFilePath - The path to the actual screenshot file.
30
+ * @returns The paths to the actual, expected, and diff screenshot files.
31
+ */
32
+ approveFromActualPath(actualFilePath: string): {
33
+ actualPath: string;
34
+ expectedPath: string;
35
+ diffPath: string;
36
+ };
37
+ /**
38
+ * Approve a screenshot based on its name.
39
+ * @param name - The name of the screenshot. Can include '.png' extension.
40
+ * @returns The paths to the actual, expected, and diff screenshot files.
41
+ */
42
+ approveByName(name: string): {
43
+ actualPath: string;
44
+ expectedPath: string;
45
+ diffPath: string;
46
+ };
47
+ /**
48
+ * Approve a screenshot based on a relative path.
49
+ * @param relativePath - The relative path to the screenshot.
50
+ * @returns The paths to the actual, expected, and diff screenshot files.
51
+ */
52
+ private approveRelative;
53
+ /**
54
+ * Ensure the parent directory of a file exists. If not, it creates it.
55
+ * @param filePath - The path to the file.
56
+ */
57
+ private ensureParentDir;
58
+ /**
59
+ * Remove a directory and all its contents.
60
+ * @param dir - The path to the directory.
61
+ */
62
+ private removeDir;
63
+ /**
64
+ * Get the actual directory path
65
+ */
66
+ getActualDir(): string;
67
+ /**
68
+ * Get the expected directory path
69
+ */
70
+ getExpectedDir(): string;
71
+ /**
72
+ * Get the diff directory path
73
+ */
74
+ getDiffDir(): string;
75
+ /**
76
+ * Get the path to an actual screenshot file
77
+ */
78
+ getActualFilePath(filename: string): string;
79
+ /**
80
+ * Get the path to an expected screenshot file
81
+ */
82
+ getExpectedFilePath(filename: string): string;
83
+ /**
84
+ * Get the path to a diff screenshot file
85
+ */
86
+ getDiffFilePath(filename: string): string;
87
+ /**
88
+ * Write a file to the actual directory
89
+ */
90
+ writeActualFile(filename: string, data: Buffer): void;
91
+ /**
92
+ * Write a file to the diff directory
93
+ */
94
+ writeDiffFile(filename: string, data: Buffer): void;
95
+ /**
96
+ * Check if an expected file exists
97
+ */
98
+ hasExpectedFile(filename: string): boolean;
99
+ /**
100
+ * Read an expected file
101
+ */
102
+ readExpectedFile(filename: string): Buffer;
103
+ /**
104
+ * Resolve the actual path of a screenshot file.
105
+ * @param filePath - The path to the screenshot file.
106
+ * @returns The actual path of the screenshot file.
107
+ */
108
+ private resolveActualPath;
109
+ }
20
110
  //#endregion
21
111
  //#region src/screenshot.d.ts
112
+ interface ScreenshotCaptureDetails {
113
+ filename: string;
114
+ filepath?: string;
115
+ comparisonResult?: CompareResult;
116
+ diffImagePath?: string;
117
+ skipped?: boolean;
118
+ }
119
+ interface ScreenshotVariantCaptureDetails extends ScreenshotCaptureDetails {
120
+ id: string;
121
+ label?: string;
122
+ }
123
+ interface ScreenshotCaptureResult {
124
+ base: ScreenshotCaptureDetails;
125
+ variants: ScreenshotVariantCaptureDetails[];
126
+ }
127
+ interface ScreenshotCaptureExtras {
128
+ saveDiffImage?: boolean;
129
+ diffImageFilename?: string;
130
+ variants?: Record<string, {
131
+ saveDiffImage?: boolean;
132
+ diffImageFilename?: string;
133
+ }>;
134
+ }
22
135
  declare class ScreenshotTool {
23
136
  browserType: "chromium" | "firefox" | "webkit";
24
137
  headless: boolean;
@@ -27,15 +140,16 @@ declare class ScreenshotTool {
27
140
  height: number;
28
141
  };
29
142
  outputDir: string;
30
- actualDir: string;
31
- diffDir: string;
32
- expectedDir: string;
33
143
  browser: Browser | null;
34
144
  context: BrowserContext | null;
35
145
  page: Page | null;
146
+ concurrency: number;
147
+ contexts: BrowserContext[];
148
+ pages: Page[];
36
149
  diff: DiffConfig;
37
150
  logger: Logger;
38
151
  retries: number;
152
+ filesystem: ScreenshotFileSystem;
39
153
  constructor(options: {
40
154
  browserType?: "chromium" | "firefox" | "webkit";
41
155
  headless?: boolean;
@@ -46,6 +160,7 @@ declare class ScreenshotTool {
46
160
  outputDir?: string;
47
161
  diff?: DiffConfig;
48
162
  retries?: number;
163
+ concurrency?: number;
49
164
  });
50
165
  /**
51
166
  * Initialize playwright and page
@@ -61,26 +176,19 @@ declare class ScreenshotTool {
61
176
  */
62
177
  goTo(page: Page, url: string): Promise<void>;
63
178
  /**
64
- * Creates directories for screenshots and other files
65
- */
66
- private createDirectories;
67
- /**
68
- * Gets the path to the actual screenshot file
69
- */
70
- getActualFilePath(filename: string): string;
71
- /**
72
- * Gets the path to the diff screenshot file
179
+ * Takes a screenshot of the page
73
180
  */
74
- getDiffFilePath(filename: string): string;
181
+ takeScreenshot(page: Page, filename: string, options: ScreenshotSettings): Promise<string | undefined>;
75
182
  /**
76
- * Gets the path to the expected screenshot file
183
+ * Sets the viewport size and executes the action, ensuring the original viewport is restored
184
+ * even if the action throws an error.
77
185
  */
78
- getExpectedFilePath(filename: string): string;
186
+ private withViewport;
79
187
  /**
80
- * Takes a screenshot of the page
188
+ * Takes a screenshot and returns the buffer (for comparison purposes)
81
189
  */
82
- takeScreenshot(page: Page, filename: string, options: ScreenshotOptions): Promise<string | undefined>;
83
- takeScreenshotWithComparison(page: Page, filename: string, referenceImage: Buffer, options: ScreenshotOptions & {
190
+ takeScreenshotBuffer(page: Page, options: ScreenshotSettings): Promise<Buffer>;
191
+ takeScreenshotWithComparison(page: Page, filename: string, referenceImage: Buffer, options: ScreenshotSettings & {
84
192
  saveDiffImage?: boolean;
85
193
  diffImageFilename?: string;
86
194
  }): Promise<{
@@ -88,11 +196,8 @@ declare class ScreenshotTool {
88
196
  comparisonResult: CompareResult;
89
197
  diffImagePath?: string;
90
198
  }>;
91
- retryScreenshot(page: Page, filename: string, referenceImage: Buffer, options: ScreenshotOptions & {
92
- saveDiffImage?: boolean;
93
- diffImageFilename?: string;
94
- }): Promise<{
95
- screenshotPath: string;
199
+ retryScreenshot(page: Page, referenceImage: Buffer, options: ScreenshotSettings): Promise<{
200
+ screenshotPath: Buffer<ArrayBufferLike>;
96
201
  comparisonResult: CompareResult;
97
202
  passed: boolean;
98
203
  } | {
@@ -100,26 +205,40 @@ declare class ScreenshotTool {
100
205
  comparisonResult: null;
101
206
  passed: boolean;
102
207
  }>;
208
+ getVariantFilename(filename: string, variant: ScreenshotVariant): string;
209
+ capture(page: Page, filename: string, options: ScreenshotOptions, extras?: ScreenshotCaptureExtras): Promise<ScreenshotCaptureResult>;
103
210
  /**
104
211
  * Gets the exponential backoff delay
105
212
  */
106
213
  getIncBackoffDelay(i: number, delay: number): number;
107
- hasExpectedImage(filename: string): boolean;
108
- getExpectedImageBuffer(filename: string): Buffer;
214
+ /**
215
+ * Get a page from the pool by index
216
+ */
217
+ getPageFromPool(index: number): Page;
109
218
  }
110
219
  //#endregion
111
220
  //#region src/plugin.d.ts
112
221
  /**
113
- * Plugin function type definition
222
+ * Plugin task interface
223
+ */
224
+ type PluginTask<TData = any> = {
225
+ id: string;
226
+ url: string;
227
+ data?: TData;
228
+ };
229
+ /**
230
+ * Plugin function type definition (legacy)
114
231
  */
115
232
  type PluginFunction = (screenshotTool: ScreenshotTool) => Promise<any[]>;
116
233
  /**
117
234
  * Plugin definition interface
118
235
  */
119
- type PluginDef = {
236
+ type PluginDef<TResult = any, TContext = any, TData = any> = {
120
237
  name: string;
121
238
  description: string;
122
- execute: PluginFunction;
239
+ discover: (screenshotTool: ScreenshotTool) => Promise<PluginTask<TData>[]>;
240
+ execute: (task: PluginTask<TData>, page: Page, screenshotTool: ScreenshotTool, context: TContext) => Promise<TResult>;
241
+ initPage?: (page: Page, screenshotTool: ScreenshotTool) => Promise<TContext>;
123
242
  };
124
243
  /**
125
244
  * Plugin function type definition
@@ -194,18 +313,36 @@ type UserConfig = {
194
313
  * The number of times to retry a screenshot if it fails
195
314
  */
196
315
  retries?: number;
316
+ /**
317
+ * The number of parallel browser contexts to use for taking screenshots
318
+ */
319
+ concurrency?: number;
197
320
  /**
198
321
  * An array of Cappa plugins used for generation.
199
322
  * Each plugin may have additional configurable options (defined within the plugin itself).
200
323
  */
201
324
  plugins?: Array<Plugin | PluginDef>;
202
325
  };
203
- type ScreenshotOptions = {
326
+ type Viewport = {
327
+ width: number;
328
+ height: number;
329
+ };
330
+ type ScreenshotSettings = {
204
331
  fullPage?: boolean;
205
332
  delay?: number;
206
333
  skip?: boolean;
207
334
  mask?: Locator[];
208
335
  omitBackground?: boolean;
336
+ viewport?: Viewport;
337
+ };
338
+ type ScreenshotVariant = {
339
+ id: string;
340
+ label?: string;
341
+ filename?: string;
342
+ options?: ScreenshotSettings;
343
+ };
344
+ type ScreenshotOptions = ScreenshotSettings & {
345
+ variants?: ScreenshotVariant[];
209
346
  };
210
347
  interface Screenshot {
211
348
  id: string;
@@ -223,5 +360,5 @@ interface Screenshot {
223
360
  */
224
361
  declare function defineConfig(options: PossiblePromise<UserConfig | Array<UserConfig>> | (() => PossiblePromise<UserConfig | Array<UserConfig>>)): typeof options;
225
362
  //#endregion
226
- export { type Plugin, type PluginDef, type PluginFunction, type Screenshot, type ScreenshotOptions, ScreenshotTool, type UserConfig, defineConfig };
363
+ export { 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 UserConfig, type Viewport, defineConfig };
227
364
  //# sourceMappingURL=index.d.ts.map