@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/.turbo/turbo-build.log +13 -19
- package/.turbo/turbo-test.log +53 -0
- package/CHANGELOG.md +13 -0
- package/LICENSE +21 -0
- package/README.md +20 -0
- package/dist/index.d.mts +173 -36
- package/dist/index.d.ts +173 -36
- package/dist/index.js +391 -86
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +391 -87
- package/dist/index.mjs.map +1 -1
- package/package.json +9 -11
- package/src/compare.test.ts +9 -4
- package/src/compare.ts +76 -23
- package/src/filesystem.test.ts +83 -0
- package/src/filesystem.ts +202 -0
- package/src/index.ts +23 -2
- package/src/plugin.ts +26 -3
- package/src/screenshot.test.ts +40 -0
- package/src/screenshot.ts +344 -104
- package/src/types.ts +19 -1
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
|
-
*
|
|
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
|
-
*
|
|
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
|
-
|
|
181
|
+
takeScreenshot(page: Page, filename: string, options: ScreenshotSettings): Promise<string | undefined>;
|
|
75
182
|
/**
|
|
76
|
-
*
|
|
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
|
-
|
|
186
|
+
private withViewport;
|
|
79
187
|
/**
|
|
80
|
-
* Takes a screenshot
|
|
188
|
+
* Takes a screenshot and returns the buffer (for comparison purposes)
|
|
81
189
|
*/
|
|
82
|
-
|
|
83
|
-
takeScreenshotWithComparison(page: Page, filename: string, referenceImage: Buffer, options:
|
|
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,
|
|
92
|
-
|
|
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
|
-
|
|
108
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|