@cappa/core 0.1.3 → 0.2.1

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.
@@ -1,11 +1,11 @@
1
1
 
2
2
 
3
- > @cappa/core@0.1.2 build /home/tim/cappa/packages/core
3
+ > @cappa/core@0.2.0 build /home/tim/cappa/packages/core
4
4
  > tsdown
5
5
 
6
- ℹ tsdown v0.14.1 powered by rolldown v1.0.0-beta.40
6
+ ℹ tsdown v0.15.7 powered by rolldown v1.0.0-beta.43
7
7
  ℹ Using tsdown config: /home/tim/cappa/packages/core/tsdown.config.ts
8
- (node:287825) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/tim/cappa/packages/core/tsdown.config.ts is not specified and it doesn't parse as CommonJS.
8
+ (node:46891) [MODULE_TYPELESS_PACKAGE_JSON] Warning: Module type of file:///home/tim/cappa/packages/core/tsdown.config.ts is not specified and it doesn't parse as CommonJS.
9
9
  Reparsing as ES module because module syntax was detected. This incurs a performance overhead.
10
10
  To eliminate this warning, add "type": "module" to /home/tim/cappa/packages/core/package.json.
11
11
  (Use `node --trace-warnings ...` to show where the warning was created)
@@ -13,19 +13,13 @@ To eliminate this warning, add "type": "module" to /home/tim/cappa/packages/core
13
13
  ℹ tsconfig: tsconfig.json
14
14
  ℹ Build start
15
15
  ℹ Cleaning 6 files
16
- Warning: Invalid input options (1 issue found)
17
- - For the "resolve.tsconfigFilename". It is deprecated. Please use the top-level `tsconfig` option instead. 
18
- Warning: Invalid input options (1 issue found)
19
- - For the "resolve.tsconfigFilename". It is deprecated. Please use the top-level `tsconfig` option instead. 
20
- ℹ [CJS] dist/index.js 10.91 kB │ gzip: 3.28 kB
21
- ℹ [CJS] dist/index.js.map 20.29 kB │ gzip: 5.71 kB
22
- ℹ [CJS] 2 files, total: 31.20 kB
23
- Warning: Invalid input options (1 issue found)
24
- - For the "resolve.tsconfigFilename". It is deprecated. Please use the top-level `tsconfig` option instead. 
25
- ℹ [ESM] dist/index.mjs  9.30 kB │ gzip: 2.79 kB
26
- ℹ [ESM] dist/index.mjs.map 20.21 kB │ gzip: 5.67 kB
27
- ℹ [ESM] dist/index.d.mts  6.36 kB │ gzip: 2.15 kB
28
- ℹ [ESM] 3 files, total: 35.88 kB
29
- ℹ [CJS] dist/index.d.ts 6.36 kB │ gzip: 2.14 kB
30
- ℹ [CJS] 1 files, total: 6.36 kB
31
- ✔ Build complete in 1271ms
16
+ ℹ [CJS] dist/index.js 21.06 kB │ gzip: 5.48 kB
17
+ ℹ [CJS] dist/index.js.map 39.29 kB │ gzip: 9.84 kB
18
+ ℹ [CJS] 2 files, total: 60.35 kB
19
+ ℹ [ESM] dist/index.mjs 19.26 kB │ gzip: 4.97 kB
20
+ ℹ [ESM] dist/index.mjs.map 39.18 kB │ gzip: 9.79 kB
21
+ ℹ [ESM] dist/index.d.mts 10.53 kB │ gzip: 3.06 kB
22
+ ℹ [ESM] 3 files, total: 68.98 kB
23
+ ℹ [CJS] dist/index.d.ts 10.53 kB │ gzip: 3.05 kB
24
+ ℹ [CJS] 1 files, total: 10.53 kB
25
+ ✔ Build complete in 1124ms
@@ -0,0 +1,53 @@
1
+
2
+
3
+ > @cappa/core@0.1.3 test /home/tim/cappa/packages/core
4
+ > vitest
5
+
6
+ [?25l
7
+  DEV  v3.2.4 /home/tim/cappa/packages/core
8
+
9
+ [?2026h
10
+  ❯ src/compare.test.ts [queued]
11
+
12
+  Test Files 0 passed (1)
13
+  Tests 0 passed (0)
14
+  Start at 17:14:17
15
+  Duration 100ms
16
+ [?2026l[?2026h
17
+  ❯ src/compare.test.ts 1/21
18
+
19
+  Test Files 0 passed (1)
20
+  Tests 1 passed (21)
21
+  Start at 17:14:17
22
+  Duration 299ms
23
+ [?2026l ✓ src/compare.test.ts (21 tests) 53ms
24
+ ✓ compare > compareImages > should return 0% difference for identical images 5ms
25
+ ✓ compare > compareImages > should return 100% difference for completely different images 3ms
26
+ ✓ compare > compareImages > should work with file paths 4ms
27
+ ✓ compare > compareImages > should work with mixed file path and buffer 3ms
28
+ ✓ compare > compareImages > should respect maxDiffPercentage parameter 4ms
29
+ ✓ compare > compareImages > should apply threshold option correctly 2ms
30
+ ✓ compare > compareImages > should throw error for mismatched dimensions 1ms
31
+ ✓ compare > compareImages > should handle custom compare options 1ms
32
+ ✓ compare > compareImages > should handle identical file paths 1ms
33
+ ✓ compare > imagesMatch > should return true for identical images 1ms
34
+ ✓ compare > imagesMatch > should return false for completely different images 1ms
35
+ ✓ compare > imagesMatch > should respect maxDifferencePercent 2ms
36
+ ✓ compare > imagesMatch > should work with file paths 6ms
37
+ ✓ compare > imagesMatch > should pass through compare options 1ms
38
+ ✓ compare > saveDiffImage > should save diff image to file 2ms
39
+ ✓ compare > saveDiffImage > should throw error when no diff buffer available 0ms
40
+ ✓ compare > error handling > should handle non-existent file paths 1ms
41
+ ✓ compare > error handling > should handle invalid image buffers 0ms
42
+ ✓ compare > edge cases > should handle 1x1 pixel images 0ms
43
+ ✓ compare > edge cases > should handle very large difference percentages 0ms
44
+ ✓ compare > edge cases > should handle zero difference threshold 0ms
45
+
46
+  Test Files  1 passed (1)
47
+  Tests  21 passed (21)
48
+  Start at  17:14:17
49
+  Duration  327ms (transform 47ms, setup 0ms, collect 81ms, tests 53ms, environment 0ms, prepare 55ms)
50
+
51
+  PASS  Waiting for file changes...
52
+ press h to show help, press q to quit
53
+ [?25h[?25h ELIFECYCLE  Test failed. See above for more details.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,26 @@
1
1
  # @cappa/core
2
2
 
3
+ ## 0.2.1
4
+
5
+ ### Patch Changes
6
+
7
+ - 526857a: feat: add variant and play function support
8
+ - Updated dependencies [526857a]
9
+ - @cappa/logger@0.0.4
10
+
11
+ ## 0.2.0
12
+
13
+ ### Minor Changes
14
+
15
+ - 5b1f66f: Add support for capturing screenshot variants and configure Storybook stories to request multiple viewport screenshots.
16
+ - 88b3648: Centralize screenshot directory management in the core package and update the CLI and server to consume the shared helpers.
17
+
18
+ ### Patch Changes
19
+
20
+ - 87c8ab9: Document how screenshot retries work in the docs so users know how to
21
+ configure and reason about the behaviour.
22
+ - a1d91c6: feat: add viewport options
23
+
3
24
  ## 0.1.3
4
25
 
5
26
  ### Patch Changes
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Tim Richter
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,20 @@
1
+ # Core Package
2
+
3
+ This package contains the core functionality for Cappa.
4
+
5
+ It is the foundation of the Cappa CLI and server.
6
+ It wraps the Playwright API and provides a set of helpers for capturing screenshots.
7
+
8
+ It also provides an api to interact with the local files system to store the screenshots.
9
+
10
+ ## Example
11
+
12
+ ```ts
13
+ import { ScreenshotTool } from "@cappa/core";
14
+
15
+ const screenshotTool = new ScreenshotTool();
16
+
17
+ screenshotTool.capture(page, "my-page", {
18
+ fullPage: true,
19
+ });
20
+ ```
package/dist/index.d.mts 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,52 @@ declare class ScreenshotTool {
100
205
  comparisonResult: null;
101
206
  passed: boolean;
102
207
  }>;
208
+ getVariantFilename(filename: string, variant: ScreenshotVariant): string;
209
+ /**
210
+ * Captures a single screenshot with the given options
211
+ */
212
+ private captureSingleScreenshot;
213
+ capture(page: Page, filename: string, options: ScreenshotOptions, extras?: ScreenshotCaptureExtras): Promise<ScreenshotCaptureResult>;
214
+ /**
215
+ * Applies SVG and UI optimizations for screenshots
216
+ */
217
+ private applyScreenshotOptimizations;
218
+ /**
219
+ * Captures screenshots for multiple variants, each with their own URL
220
+ */
221
+ captureWithVariants(page: Page, baseFilename: string, baseUrl: string, baseOptions: ScreenshotSettings, variants: ScreenshotVariantWithUrl[], extras?: ScreenshotCaptureExtras): Promise<ScreenshotCaptureResult>;
103
222
  /**
104
223
  * Gets the exponential backoff delay
105
224
  */
106
225
  getIncBackoffDelay(i: number, delay: number): number;
107
- hasExpectedImage(filename: string): boolean;
108
- getExpectedImageBuffer(filename: string): Buffer;
226
+ /**
227
+ * Get a page from the pool by index
228
+ */
229
+ getPageFromPool(index: number): Page;
109
230
  }
110
231
  //#endregion
111
232
  //#region src/plugin.d.ts
112
233
  /**
113
- * Plugin function type definition
234
+ * Plugin task interface
235
+ */
236
+ type PluginTask<TData = any> = {
237
+ id: string;
238
+ url: string;
239
+ data?: TData;
240
+ };
241
+ /**
242
+ * Plugin function type definition (legacy)
114
243
  */
115
244
  type PluginFunction = (screenshotTool: ScreenshotTool) => Promise<any[]>;
116
245
  /**
117
246
  * Plugin definition interface
118
247
  */
119
- type PluginDef = {
248
+ type PluginDef<TResult = any, TContext = any, TData = any> = {
120
249
  name: string;
121
250
  description: string;
122
- execute: PluginFunction;
251
+ discover: (screenshotTool: ScreenshotTool) => Promise<PluginTask<TData>[]>;
252
+ execute: (task: PluginTask<TData>, page: Page, screenshotTool: ScreenshotTool, context: TContext) => Promise<TResult>;
253
+ initPage?: (page: Page, screenshotTool: ScreenshotTool) => Promise<TContext>;
123
254
  };
124
255
  /**
125
256
  * Plugin function type definition
@@ -194,18 +325,43 @@ type UserConfig = {
194
325
  * The number of times to retry a screenshot if it fails
195
326
  */
196
327
  retries?: number;
328
+ /**
329
+ * The number of parallel browser contexts to use for taking screenshots
330
+ */
331
+ concurrency?: number;
197
332
  /**
198
333
  * An array of Cappa plugins used for generation.
199
334
  * Each plugin may have additional configurable options (defined within the plugin itself).
200
335
  */
201
336
  plugins?: Array<Plugin | PluginDef>;
202
337
  };
203
- type ScreenshotOptions = {
338
+ type Viewport = {
339
+ width: number;
340
+ height: number;
341
+ };
342
+ type ScreenshotSettings = {
204
343
  fullPage?: boolean;
205
344
  delay?: number;
206
345
  skip?: boolean;
207
346
  mask?: Locator[];
208
347
  omitBackground?: boolean;
348
+ viewport?: Viewport;
349
+ };
350
+ type ScreenshotVariant = {
351
+ id: string;
352
+ label?: string;
353
+ filename?: string;
354
+ options?: ScreenshotSettings;
355
+ };
356
+ type ScreenshotVariantWithUrl = {
357
+ id: string;
358
+ label?: string;
359
+ filename?: string;
360
+ url: string;
361
+ options?: ScreenshotSettings;
362
+ };
363
+ type ScreenshotOptions = ScreenshotSettings & {
364
+ variants?: ScreenshotVariant[];
209
365
  };
210
366
  interface Screenshot {
211
367
  id: string;
@@ -223,5 +379,5 @@ interface Screenshot {
223
379
  */
224
380
  declare function defineConfig(options: PossiblePromise<UserConfig | Array<UserConfig>> | (() => PossiblePromise<UserConfig | Array<UserConfig>>)): typeof options;
225
381
  //#endregion
226
- export { type Plugin, type PluginDef, type PluginFunction, type Screenshot, type ScreenshotOptions, ScreenshotTool, type UserConfig, defineConfig };
382
+ 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 ScreenshotVariantWithUrl, type UserConfig, type Viewport, defineConfig };
227
383
  //# sourceMappingURL=index.d.mts.map