@cappa/core 0.4.1 → 0.4.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/filesystem.ts DELETED
@@ -1,202 +0,0 @@
1
- import fs from "node:fs";
2
- import path from "node:path";
3
-
4
- /**
5
- * Class for interacting with the local file system to store the screenshots.
6
- */
7
- export class ScreenshotFileSystem {
8
- private readonly actualDir: string;
9
- private readonly expectedDir: string;
10
- private readonly diffDir: string;
11
-
12
- constructor(outputDir: string) {
13
- this.actualDir = path.resolve(outputDir, "actual");
14
- this.expectedDir = path.resolve(outputDir, "expected");
15
- this.diffDir = path.resolve(outputDir, "diff");
16
-
17
- this.ensureParentDir(this.actualDir);
18
- this.ensureParentDir(this.expectedDir);
19
- this.ensureParentDir(this.diffDir);
20
- }
21
-
22
- clearActual() {
23
- this.removeDir(this.actualDir);
24
- }
25
-
26
- clearDiff() {
27
- this.removeDir(this.diffDir);
28
- }
29
-
30
- clearActualAndDiff() {
31
- this.clearActual();
32
- this.clearDiff();
33
- }
34
-
35
- /**
36
- * Approve a screenshot based on its actual file path.
37
- * @param actualFilePath - The path to the actual screenshot file.
38
- * @returns The paths to the actual, expected, and diff screenshot files.
39
- */
40
- approveFromActualPath(actualFilePath: string) {
41
- const actualAbsolute = this.resolveActualPath(actualFilePath);
42
- const relativePath = path.relative(this.actualDir, actualAbsolute);
43
-
44
- if (relativePath.startsWith("..")) {
45
- throw new Error(
46
- `Cannot approve screenshot outside of actual directory: ${actualFilePath}`,
47
- );
48
- }
49
-
50
- return this.approveRelative(relativePath);
51
- }
52
-
53
- /**
54
- * Approve a screenshot based on its name.
55
- * @param name - The name of the screenshot. Can include '.png' extension.
56
- * @returns The paths to the actual, expected, and diff screenshot files.
57
- */
58
- approveByName(name: string) {
59
- const relativeWithExtension = name.endsWith(".png") ? name : `${name}.png`;
60
-
61
- return this.approveRelative(relativeWithExtension);
62
- }
63
-
64
- /**
65
- * Approve a screenshot based on a relative path.
66
- * @param relativePath - The relative path to the screenshot.
67
- * @returns The paths to the actual, expected, and diff screenshot files.
68
- */
69
- private approveRelative(relativePath: string) {
70
- const actualPath = path.resolve(this.actualDir, relativePath);
71
- const expectedPath = path.resolve(this.expectedDir, relativePath);
72
- const diffPath = path.resolve(this.diffDir, relativePath);
73
-
74
- this.ensureParentDir(expectedPath);
75
-
76
- fs.copyFileSync(actualPath, expectedPath);
77
-
78
- if (fs.existsSync(diffPath)) {
79
- fs.unlinkSync(diffPath);
80
- }
81
-
82
- return {
83
- actualPath,
84
- expectedPath,
85
- diffPath,
86
- };
87
- }
88
-
89
- /**
90
- * Ensure the parent directory of a file exists. If not, it creates it.
91
- * @param filePath - The path to the file.
92
- */
93
- ensureParentDir(filePath: string) {
94
- const dir = path.dirname(filePath);
95
-
96
- if (!fs.existsSync(dir)) {
97
- fs.mkdirSync(dir, { recursive: true });
98
- }
99
- }
100
-
101
- /**
102
- * Remove a directory and all its contents.
103
- * @param dir - The path to the directory.
104
- */
105
- private removeDir(dir: string) {
106
- if (fs.existsSync(dir)) {
107
- fs.rmSync(dir, { recursive: true, force: true });
108
- }
109
- }
110
-
111
- /**
112
- * Get the actual directory path
113
- */
114
- getActualDir(): string {
115
- return this.actualDir;
116
- }
117
-
118
- /**
119
- * Get the expected directory path
120
- */
121
- getExpectedDir(): string {
122
- return this.expectedDir;
123
- }
124
-
125
- /**
126
- * Get the diff directory path
127
- */
128
- getDiffDir(): string {
129
- return this.diffDir;
130
- }
131
-
132
- /**
133
- * Get the path to an actual screenshot file
134
- */
135
- getActualFilePath(filename: string): string {
136
- return path.resolve(this.actualDir, filename);
137
- }
138
-
139
- /**
140
- * Get the path to an expected screenshot file
141
- */
142
- getExpectedFilePath(filename: string): string {
143
- return path.resolve(this.expectedDir, filename);
144
- }
145
-
146
- /**
147
- * Get the path to a diff screenshot file
148
- */
149
- getDiffFilePath(filename: string): string {
150
- return path.resolve(this.diffDir, filename);
151
- }
152
-
153
- /**
154
- * Write a file to the actual directory
155
- */
156
- writeActualFile(filename: string, data: Buffer): void {
157
- const filepath = this.getActualFilePath(filename);
158
- this.ensureParentDir(filepath);
159
- fs.writeFileSync(filepath, data);
160
- }
161
-
162
- /**
163
- * Write a file to the diff directory
164
- */
165
- writeDiffFile(filename: string, data: Buffer): void {
166
- const filepath = this.getDiffFilePath(filename);
167
- this.ensureParentDir(filepath);
168
- fs.writeFileSync(filepath, data);
169
- }
170
-
171
- /**
172
- * Check if an expected file exists
173
- */
174
- hasExpectedFile(filename: string): boolean {
175
- const expectedPath = this.getExpectedFilePath(filename);
176
- return fs.existsSync(expectedPath);
177
- }
178
-
179
- /**
180
- * Read an expected file
181
- */
182
- readExpectedFile(filename: string): Buffer {
183
- const expectedPath = this.getExpectedFilePath(filename);
184
- if (!fs.existsSync(expectedPath)) {
185
- throw new Error(`Expected image not found: ${expectedPath}`);
186
- }
187
- return fs.readFileSync(expectedPath);
188
- }
189
-
190
- /**
191
- * Resolve the actual path of a screenshot file.
192
- * @param filePath - The path to the screenshot file.
193
- * @returns The actual path of the screenshot file.
194
- */
195
- private resolveActualPath(filePath: string) {
196
- if (path.isAbsolute(filePath)) {
197
- return filePath;
198
- }
199
-
200
- return path.resolve(this.actualDir, filePath);
201
- }
202
- }
package/src/index.ts DELETED
@@ -1,45 +0,0 @@
1
- import { compareImages, imagesMatch } from "./compare";
2
- import { defineConfig } from "./config";
3
- import { ScreenshotFileSystem } from "./filesystem";
4
- import type { Plugin, PluginDef, PluginFunction } from "./plugin";
5
- import ScreenshotTool, {
6
- type ScreenshotCaptureDetails,
7
- type ScreenshotCaptureExtras,
8
- type ScreenshotCaptureResult,
9
- type ScreenshotVariantCaptureDetails,
10
- } from "./screenshot";
11
- import type {
12
- ConfigEnv,
13
- FailedScreenshot,
14
- Screenshot,
15
- ScreenshotOptions,
16
- ScreenshotSettings,
17
- ScreenshotVariant,
18
- ScreenshotVariantWithUrl,
19
- UserConfig,
20
- Viewport,
21
- } from "./types";
22
-
23
- export {
24
- ScreenshotTool,
25
- ScreenshotFileSystem,
26
- defineConfig,
27
- compareImages,
28
- imagesMatch,
29
- type PluginFunction,
30
- type Plugin,
31
- type PluginDef,
32
- type ConfigEnv,
33
- type UserConfig,
34
- type ScreenshotOptions,
35
- type ScreenshotSettings,
36
- type ScreenshotVariant,
37
- type ScreenshotVariantWithUrl,
38
- type Screenshot,
39
- type FailedScreenshot,
40
- type ScreenshotCaptureResult,
41
- type ScreenshotCaptureDetails,
42
- type ScreenshotVariantCaptureDetails,
43
- type ScreenshotCaptureExtras,
44
- type Viewport,
45
- };
package/src/plugin.ts DELETED
@@ -1,43 +0,0 @@
1
- import type { Page } from "playwright-core";
2
- import type ScreenshotTool from "./screenshot";
3
-
4
- /**
5
- * Plugin task interface
6
- */
7
- export type PluginTask<TData = any> = {
8
- id: string; // unique identifier for logging
9
- url: string; // url of the task
10
- data?: TData; // plugin-specific task data
11
- };
12
-
13
- /**
14
- * Plugin function type definition (legacy)
15
- */
16
- export type PluginFunction = (screenshotTool: ScreenshotTool) => Promise<any[]>;
17
-
18
- /**
19
- * Plugin definition interface
20
- */
21
- export type PluginDef<TResult = any, TContext = any, TData = any> = {
22
- name: string;
23
- description: string;
24
-
25
- // Phase 1: Discover all tasks
26
- discover: (screenshotTool: ScreenshotTool) => Promise<PluginTask<TData>[]>;
27
-
28
- // Phase 2: Execute a single task
29
- execute: (
30
- task: PluginTask<TData>,
31
- page: Page,
32
- screenshotTool: ScreenshotTool,
33
- context: TContext,
34
- ) => Promise<TResult>;
35
-
36
- // Optional: called once per page before executing tasks on that page
37
- initPage?: (page: Page, screenshotTool: ScreenshotTool) => Promise<TContext>;
38
- };
39
-
40
- /**
41
- * Plugin function type definition
42
- */
43
- export type Plugin<Config = any> = (config?: Config) => PluginDef;
@@ -1,40 +0,0 @@
1
- import { initLogger } from "@cappa/logger";
2
- import { beforeAll, describe, expect, it } from "vitest";
3
- import ScreenshotTool from "./screenshot";
4
-
5
- beforeAll(() => {
6
- initLogger(0);
7
- });
8
-
9
- describe("ScreenshotTool getVariantFilename", () => {
10
- it("appends the variant id as a suffix", () => {
11
- const tool = new ScreenshotTool({ outputDir: "/tmp" });
12
-
13
- const filename = tool.getVariantFilename("components/Button.png", {
14
- id: "mobile",
15
- });
16
-
17
- expect(filename).toBe("components/Button--mobile.png");
18
- });
19
-
20
- it("sanitizes invalid characters in the variant id", () => {
21
- const tool = new ScreenshotTool({ outputDir: "/tmp" });
22
-
23
- const filename = tool.getVariantFilename("Badge.png", {
24
- id: "📱 mobile view",
25
- });
26
-
27
- expect(filename).toBe("Badge--mobile-view.png");
28
- });
29
-
30
- it("uses a provided filename when present", () => {
31
- const tool = new ScreenshotTool({ outputDir: "/tmp" });
32
-
33
- const filename = tool.getVariantFilename("Badge.png", {
34
- id: "mobile",
35
- filename: "Badge/mobile-custom.png",
36
- });
37
-
38
- expect(filename).toBe("Badge/mobile-custom.png");
39
- });
40
- });