@cappa/core 0.0.2
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/CHANGELOG.md +7 -0
- package/package.json +45 -0
- package/src/config.ts +13 -0
- package/src/index.ts +15 -0
- package/src/plugin.ts +25 -0
- package/src/screenshot.ts +298 -0
- package/src/types.ts +36 -0
- package/src/utils/types.ts +13 -0
- package/tsconfig.json +9 -0
- package/tsdown.config.ts +11 -0
package/CHANGELOG.md
ADDED
package/package.json
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@cappa/core",
|
|
3
|
+
"version": "0.0.2",
|
|
4
|
+
"description": "Core Playwright screenshot functionality for Cappa",
|
|
5
|
+
"author": "tim-richter",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"publishConfig": {
|
|
8
|
+
"access": "public"
|
|
9
|
+
},
|
|
10
|
+
"sideEffects": false,
|
|
11
|
+
"main": "./dist/index.js",
|
|
12
|
+
"types": "./dist/index.d.ts",
|
|
13
|
+
"exports": {
|
|
14
|
+
".": {
|
|
15
|
+
"import": "./dist/index.mjs",
|
|
16
|
+
"require": "./dist/index.js"
|
|
17
|
+
},
|
|
18
|
+
"./package.json": "./package.json"
|
|
19
|
+
},
|
|
20
|
+
"dependencies": {
|
|
21
|
+
"playwright": "^1.54.2"
|
|
22
|
+
},
|
|
23
|
+
"devDependencies": {
|
|
24
|
+
"tsdown": "0.14.1",
|
|
25
|
+
"@types/node": "22.13.10",
|
|
26
|
+
"vitest": "3.2.4",
|
|
27
|
+
"@vitest/ui": "3.2.4",
|
|
28
|
+
"@vitest/coverage-v8": "3.2.4",
|
|
29
|
+
"typescript": "5.7.3"
|
|
30
|
+
},
|
|
31
|
+
"keywords": [
|
|
32
|
+
"screenshot",
|
|
33
|
+
"playwright",
|
|
34
|
+
"core"
|
|
35
|
+
],
|
|
36
|
+
"module": "./dist/index.mjs",
|
|
37
|
+
"scripts": {
|
|
38
|
+
"test": "echo \"Error: no test specified\" && exit 1",
|
|
39
|
+
"example:basic": "node examples/basic-usage.js",
|
|
40
|
+
"example:batch": "node examples/batch-screenshots.js",
|
|
41
|
+
"example:responsive": "node examples/responsive-screenshots.js",
|
|
42
|
+
"example:element": "node examples/element-screenshots.js",
|
|
43
|
+
"build": "tsdown"
|
|
44
|
+
}
|
|
45
|
+
}
|
package/src/config.ts
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { PossiblePromise } from "./utils/types";
|
|
2
|
+
import type { UserConfig } from "./types";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Type helper to make it easier to use vite.config.ts accepts a direct UserConfig object, or a function that returns it. The function receives a ConfigEnv object.
|
|
6
|
+
*/
|
|
7
|
+
export function defineConfig(
|
|
8
|
+
options:
|
|
9
|
+
| PossiblePromise<UserConfig | Array<UserConfig>>
|
|
10
|
+
| (() => PossiblePromise<UserConfig | Array<UserConfig>>)
|
|
11
|
+
): typeof options {
|
|
12
|
+
return options;
|
|
13
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import ScreenshotTool from "./screenshot";
|
|
2
|
+
import type { PluginFunction, Plugin, PluginDef } from "./plugin";
|
|
3
|
+
import { defineConfig } from "./config";
|
|
4
|
+
import type { Exposed, ScreenshotOptions, UserConfig } from "./types";
|
|
5
|
+
|
|
6
|
+
export {
|
|
7
|
+
ScreenshotTool,
|
|
8
|
+
defineConfig,
|
|
9
|
+
type PluginFunction,
|
|
10
|
+
type Plugin,
|
|
11
|
+
type PluginDef,
|
|
12
|
+
type UserConfig,
|
|
13
|
+
type ScreenshotOptions,
|
|
14
|
+
type Exposed,
|
|
15
|
+
};
|
package/src/plugin.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import ScreenshotTool from "./screenshot";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Plugin function type definition
|
|
5
|
+
*/
|
|
6
|
+
export type PluginFunction = (
|
|
7
|
+
screenshotTool: ScreenshotTool,
|
|
8
|
+
options?: any
|
|
9
|
+
) => Promise<any[]>;
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Plugin definition interface
|
|
13
|
+
*/
|
|
14
|
+
export type PluginDef = {
|
|
15
|
+
name: string;
|
|
16
|
+
description: string;
|
|
17
|
+
version: string;
|
|
18
|
+
execute: PluginFunction;
|
|
19
|
+
validateOptions?: (options: any) => boolean;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Plugin function type definition
|
|
24
|
+
*/
|
|
25
|
+
export type Plugin<Config = any> = (config?: Config) => PluginDef;
|
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
import {
|
|
2
|
+
type Browser,
|
|
3
|
+
type BrowserContext,
|
|
4
|
+
chromium,
|
|
5
|
+
firefox,
|
|
6
|
+
type Page,
|
|
7
|
+
type PageScreenshotOptions,
|
|
8
|
+
webkit,
|
|
9
|
+
} from "playwright";
|
|
10
|
+
import path from "node:path";
|
|
11
|
+
import fs from "node:fs";
|
|
12
|
+
|
|
13
|
+
class ScreenshotTool {
|
|
14
|
+
browserType: string;
|
|
15
|
+
headless: boolean;
|
|
16
|
+
viewport: { width: number; height: number };
|
|
17
|
+
outputDir: string;
|
|
18
|
+
quality: number;
|
|
19
|
+
fullPage: boolean;
|
|
20
|
+
browser: Browser | null = null;
|
|
21
|
+
context: BrowserContext | null = null;
|
|
22
|
+
constructor(options: {
|
|
23
|
+
browserType?: string;
|
|
24
|
+
headless?: boolean;
|
|
25
|
+
viewport?: { width: number; height: number };
|
|
26
|
+
outputDir?: string;
|
|
27
|
+
quality?: number;
|
|
28
|
+
fullPage?: boolean;
|
|
29
|
+
}) {
|
|
30
|
+
this.browserType = options.browserType || "chromium";
|
|
31
|
+
this.headless = options.headless !== false; // Default to headless
|
|
32
|
+
this.viewport = options.viewport || { width: 1920, height: 1080 };
|
|
33
|
+
this.outputDir = options.outputDir || "./screenshots";
|
|
34
|
+
this.quality = options.quality || 90;
|
|
35
|
+
this.fullPage = options.fullPage !== false; // Default to full page
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
async init() {
|
|
39
|
+
// Create output directory if it doesn't exist
|
|
40
|
+
if (!fs.existsSync(this.outputDir)) {
|
|
41
|
+
fs.mkdirSync(this.outputDir, { recursive: true });
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
// Launch browser based on type
|
|
45
|
+
const browserMap = {
|
|
46
|
+
chromium,
|
|
47
|
+
firefox,
|
|
48
|
+
webkit,
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
const browserClass =
|
|
52
|
+
browserMap[this.browserType as keyof typeof browserMap];
|
|
53
|
+
if (!browserClass) {
|
|
54
|
+
throw new Error(`Unsupported browser type: ${this.browserType}`);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
this.browser = await browserClass.launch({
|
|
58
|
+
headless: this.headless,
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
this.context = await this.browser.newContext({
|
|
62
|
+
reducedMotion: "reduce",
|
|
63
|
+
deviceScaleFactor: 1,
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
async close() {
|
|
68
|
+
if (this.browser) {
|
|
69
|
+
await this.browser.close();
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
async newPage() {
|
|
74
|
+
if (!this.context) {
|
|
75
|
+
throw new Error("Browser not initialized");
|
|
76
|
+
}
|
|
77
|
+
const page = await this.context?.newPage();
|
|
78
|
+
await page.setViewportSize(this.viewport);
|
|
79
|
+
return page;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
async goTo(page: Page, url: string) {
|
|
83
|
+
if (!this.context) {
|
|
84
|
+
throw new Error("Browser not initialized");
|
|
85
|
+
}
|
|
86
|
+
await page.goto(url, { waitUntil: "domcontentloaded" });
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
getFilePath(filename: string) {
|
|
90
|
+
const filepath = path.join(this.outputDir, filename);
|
|
91
|
+
return filepath;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
async takeScreenshot(
|
|
95
|
+
page: Page,
|
|
96
|
+
filename: string,
|
|
97
|
+
options: {
|
|
98
|
+
fullPage?: boolean;
|
|
99
|
+
type?: string;
|
|
100
|
+
quality?: number;
|
|
101
|
+
waitForSelector?: string;
|
|
102
|
+
waitForTimeout?: number;
|
|
103
|
+
} = {}
|
|
104
|
+
) {
|
|
105
|
+
if (!this.browser) {
|
|
106
|
+
throw new Error("Browser not initialized");
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
try {
|
|
110
|
+
// Wait for selector if specified
|
|
111
|
+
if (options.waitForSelector) {
|
|
112
|
+
console.log(`Waiting for selector: ${options.waitForSelector}`);
|
|
113
|
+
await page.waitForSelector(options.waitForSelector, { timeout: 10000 });
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// Wait for custom timeout or default
|
|
117
|
+
const waitTime =
|
|
118
|
+
options.waitForTimeout !== undefined ? options.waitForTimeout : 0;
|
|
119
|
+
if (waitTime > 0) {
|
|
120
|
+
console.log(`Waiting for ${waitTime}ms for dynamic content`);
|
|
121
|
+
await page.waitForTimeout(waitTime);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
// Generate filename
|
|
125
|
+
const filepath = this.getFilePath(filename);
|
|
126
|
+
|
|
127
|
+
// Take screenshot
|
|
128
|
+
const screenshotOptions = {
|
|
129
|
+
path: filepath,
|
|
130
|
+
fullPage:
|
|
131
|
+
(options.fullPage as boolean) !== undefined
|
|
132
|
+
? options.fullPage
|
|
133
|
+
: this.fullPage,
|
|
134
|
+
type: (options.type as "jpeg" | "png") || "jpeg",
|
|
135
|
+
quality: (options.quality as number) || this.quality,
|
|
136
|
+
} satisfies PageScreenshotOptions;
|
|
137
|
+
|
|
138
|
+
await page.screenshot(screenshotOptions);
|
|
139
|
+
|
|
140
|
+
console.log(`Screenshot saved: ${filepath}`);
|
|
141
|
+
return filepath;
|
|
142
|
+
} catch (error) {
|
|
143
|
+
console.error(
|
|
144
|
+
`Error taking screenshot of ${page.url()}:`,
|
|
145
|
+
(error as Error).message
|
|
146
|
+
);
|
|
147
|
+
throw error;
|
|
148
|
+
} finally {
|
|
149
|
+
await page.close();
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
async takeElementScreenshot(
|
|
154
|
+
page: Page,
|
|
155
|
+
selector: string,
|
|
156
|
+
options: {
|
|
157
|
+
filename?: string;
|
|
158
|
+
fullPage?: boolean;
|
|
159
|
+
type?: string;
|
|
160
|
+
quality?: number;
|
|
161
|
+
} = {}
|
|
162
|
+
) {
|
|
163
|
+
if (!this.browser) {
|
|
164
|
+
throw new Error("Browser not initialized");
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
try {
|
|
168
|
+
// Wait for element to be visible
|
|
169
|
+
await page.waitForSelector(selector, { timeout: 10000 });
|
|
170
|
+
|
|
171
|
+
const element = await page.$(selector);
|
|
172
|
+
if (!element) {
|
|
173
|
+
throw new Error(`Element not found: ${selector}`);
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
const filename =
|
|
177
|
+
(options.filename as string | undefined) ||
|
|
178
|
+
`${selector.replace(/[^a-zA-Z0-9]/g, "_")}.png`;
|
|
179
|
+
const filepath = this.getFilePath(filename);
|
|
180
|
+
|
|
181
|
+
const elementScreenshotOptions = {
|
|
182
|
+
path: filepath,
|
|
183
|
+
type: (options.type as "jpeg" | "png") || "jpeg",
|
|
184
|
+
quality: (options.quality as number) || this.quality,
|
|
185
|
+
} satisfies PageScreenshotOptions;
|
|
186
|
+
|
|
187
|
+
await element.screenshot(elementScreenshotOptions);
|
|
188
|
+
|
|
189
|
+
console.log(`Element screenshot saved: ${filepath}`);
|
|
190
|
+
return filepath;
|
|
191
|
+
} catch (error) {
|
|
192
|
+
console.error(
|
|
193
|
+
`Error taking element screenshot of ${page.url()}:`,
|
|
194
|
+
(error as Error).message
|
|
195
|
+
);
|
|
196
|
+
throw error;
|
|
197
|
+
} finally {
|
|
198
|
+
await page.close();
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
async batchScreenshots(urls: string[], options = {}) {
|
|
203
|
+
const results: {
|
|
204
|
+
url: string;
|
|
205
|
+
success: boolean;
|
|
206
|
+
filepath: string;
|
|
207
|
+
error?: string;
|
|
208
|
+
}[] = [];
|
|
209
|
+
|
|
210
|
+
for (const url of urls) {
|
|
211
|
+
try {
|
|
212
|
+
const page = await this.newPage();
|
|
213
|
+
await this.goTo(page, url);
|
|
214
|
+
const filepath = await this.takeScreenshot(page, url, options);
|
|
215
|
+
results.push({ url, success: true, filepath });
|
|
216
|
+
} catch (error) {
|
|
217
|
+
results.push({
|
|
218
|
+
url,
|
|
219
|
+
success: false,
|
|
220
|
+
error: (error as Error).message,
|
|
221
|
+
filepath: "",
|
|
222
|
+
});
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
return results;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
async takeResponsiveScreenshots(
|
|
230
|
+
url: string,
|
|
231
|
+
viewports: { width: number; height: number; name: string }[] = [
|
|
232
|
+
{ width: 1920, height: 1080, name: "desktop" },
|
|
233
|
+
{ width: 768, height: 1024, name: "tablet" },
|
|
234
|
+
{ width: 375, height: 667, name: "mobile" },
|
|
235
|
+
],
|
|
236
|
+
options: {
|
|
237
|
+
fullPage?: boolean;
|
|
238
|
+
type?: string;
|
|
239
|
+
quality?: number;
|
|
240
|
+
} = {}
|
|
241
|
+
) {
|
|
242
|
+
if (!this.context) {
|
|
243
|
+
throw new Error("Browser not initialized");
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
const results: {
|
|
247
|
+
viewport: string;
|
|
248
|
+
success: boolean;
|
|
249
|
+
filepath: string;
|
|
250
|
+
error?: string;
|
|
251
|
+
}[] = [];
|
|
252
|
+
|
|
253
|
+
for (const viewport of viewports) {
|
|
254
|
+
try {
|
|
255
|
+
const page = await this.context?.newPage();
|
|
256
|
+
await page.setViewportSize(viewport);
|
|
257
|
+
|
|
258
|
+
await page.goto(url, { waitUntil: "domcontentloaded" });
|
|
259
|
+
await page.waitForTimeout(2000);
|
|
260
|
+
|
|
261
|
+
const filename = `${viewport.name}.png`;
|
|
262
|
+
const filepath = this.getFilePath(filename);
|
|
263
|
+
|
|
264
|
+
const responsiveScreenshotOptions = {
|
|
265
|
+
path: filepath,
|
|
266
|
+
fullPage:
|
|
267
|
+
(options.fullPage as boolean) !== undefined
|
|
268
|
+
? options.fullPage
|
|
269
|
+
: this.fullPage,
|
|
270
|
+
type: (options.type as "jpeg" | "png") || "png",
|
|
271
|
+
quality: (options.quality as number) || this.quality,
|
|
272
|
+
};
|
|
273
|
+
|
|
274
|
+
await page.screenshot(responsiveScreenshotOptions);
|
|
275
|
+
|
|
276
|
+
await page.close();
|
|
277
|
+
|
|
278
|
+
console.log(`Responsive screenshot saved: ${filepath}`);
|
|
279
|
+
results.push({ viewport: viewport.name, success: true, filepath });
|
|
280
|
+
} catch (error) {
|
|
281
|
+
console.error(
|
|
282
|
+
`Error taking responsive screenshot for ${viewport.name}:`,
|
|
283
|
+
(error as Error).message
|
|
284
|
+
);
|
|
285
|
+
results.push({
|
|
286
|
+
viewport: viewport.name,
|
|
287
|
+
success: false,
|
|
288
|
+
error: (error as Error).message,
|
|
289
|
+
filepath: "",
|
|
290
|
+
});
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
return results;
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
export default ScreenshotTool;
|
package/src/types.ts
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import type { PluginDef, Plugin } from "./plugin";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Config used in `cappa.config.ts`
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* import { defineConfig } from '@cappa/core'
|
|
8
|
+
* export default defineConfig({
|
|
9
|
+
* ...
|
|
10
|
+
* })
|
|
11
|
+
*/
|
|
12
|
+
export type UserConfig = {
|
|
13
|
+
/**
|
|
14
|
+
* The project root directory, which can be either an absolute path or a path relative to the location of your `cappa.config.ts` file.
|
|
15
|
+
* @default process.cwd()
|
|
16
|
+
*/
|
|
17
|
+
root?: string;
|
|
18
|
+
/**
|
|
19
|
+
* 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.
|
|
20
|
+
*/
|
|
21
|
+
plugins?: Array<Plugin | PluginDef>;
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
export type ScreenshotOptions = {
|
|
25
|
+
fullPage?: boolean;
|
|
26
|
+
type?: string;
|
|
27
|
+
quality?: number;
|
|
28
|
+
waitForSelector?: string;
|
|
29
|
+
waitForTimeout?: number;
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
export interface Exposed {
|
|
33
|
+
emitCapture(opt: ScreenshotOptions): void;
|
|
34
|
+
getBaseScreenshotOptions(): ScreenshotOptions;
|
|
35
|
+
waitBrowserMetricsStable(): Promise<void>;
|
|
36
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export type PossiblePromise<T> = Promise<T> | T;
|
|
2
|
+
|
|
3
|
+
type ArrayWithLength<
|
|
4
|
+
T extends number,
|
|
5
|
+
U extends any[] = []
|
|
6
|
+
> = U["length"] extends T ? U : ArrayWithLength<T, [true, ...U]>;
|
|
7
|
+
|
|
8
|
+
export type GreaterThan<
|
|
9
|
+
T extends number,
|
|
10
|
+
U extends number
|
|
11
|
+
> = ArrayWithLength<U> extends [...ArrayWithLength<T>, ...infer _]
|
|
12
|
+
? false
|
|
13
|
+
: true;
|
package/tsconfig.json
ADDED