@storysnap/cli 1.2.1 → 2.0.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/README.md CHANGED
@@ -183,7 +183,7 @@ jobs:
183
183
  - uses: actions/checkout@v4
184
184
  - uses: actions/setup-node@v4
185
185
  with:
186
- node-version: '20'
186
+ node-version: '22'
187
187
 
188
188
  - name: Install dependencies
189
189
  run: npm ci
@@ -204,7 +204,7 @@ jobs:
204
204
 
205
205
  ```yaml
206
206
  visual-tests:
207
- image: mcr.microsoft.com/playwright:v1.40.0-jammy
207
+ image: mcr.microsoft.com/playwright:v1.63.0-noble
208
208
  script:
209
209
  - npm ci
210
210
  - npm run build-storybook
@@ -285,7 +285,7 @@ npx playwright install-deps
285
285
 
286
286
  ## Requirements
287
287
 
288
- - Node.js 18 or higher
288
+ - Node.js 22.12 or higher
289
289
  - A running Storybook instance (v6.0+)
290
290
 
291
291
  ## License
@@ -82,8 +82,8 @@ export interface Baseline {
82
82
  }
83
83
  export declare class ApiError extends Error {
84
84
  statusCode: number;
85
- response?: unknown | undefined;
86
- constructor(message: string, statusCode: number, response?: unknown | undefined);
85
+ response?: unknown;
86
+ constructor(message: string, statusCode: number, response?: unknown);
87
87
  }
88
88
  export declare class ApiClient {
89
89
  private apiUrl;
@@ -1,10 +1,14 @@
1
1
  import { z } from 'zod';
2
- declare const browserSchema: z.ZodEnum<["chromium", "firefox", "webkit"]>;
2
+ declare const browserSchema: z.ZodEnum<{
3
+ chromium: "chromium";
4
+ firefox: "firefox";
5
+ webkit: "webkit";
6
+ }>;
3
7
  export type Browser = z.infer<typeof browserSchema>;
4
- export declare const configSchema: z.ZodEffects<z.ZodObject<{
8
+ export declare const configSchema: z.ZodObject<{
5
9
  storybookUrl: z.ZodOptional<z.ZodString>;
6
10
  storybookStaticDir: z.ZodOptional<z.ZodString>;
7
- storage: z.ZodDefault<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
11
+ storage: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
8
12
  type: z.ZodLiteral<"s3">;
9
13
  bucket: z.ZodString;
10
14
  region: z.ZodString;
@@ -12,174 +16,32 @@ export declare const configSchema: z.ZodEffects<z.ZodObject<{
12
16
  endpoint: z.ZodOptional<z.ZodString>;
13
17
  accessKeyId: z.ZodOptional<z.ZodString>;
14
18
  secretAccessKey: z.ZodOptional<z.ZodString>;
15
- }, "strip", z.ZodTypeAny, {
16
- type: "s3";
17
- bucket: string;
18
- region: string;
19
- prefix?: string | undefined;
20
- endpoint?: string | undefined;
21
- accessKeyId?: string | undefined;
22
- secretAccessKey?: string | undefined;
23
- }, {
24
- type: "s3";
25
- bucket: string;
26
- region: string;
27
- prefix?: string | undefined;
28
- endpoint?: string | undefined;
29
- accessKeyId?: string | undefined;
30
- secretAccessKey?: string | undefined;
31
- }>, z.ZodObject<{
19
+ }, z.core.$strip>, z.ZodObject<{
32
20
  type: z.ZodLiteral<"local">;
33
21
  directory: z.ZodString;
34
- }, "strip", z.ZodTypeAny, {
35
- type: "local";
36
- directory: string;
37
- }, {
38
- type: "local";
39
- directory: string;
40
- }>]>>;
22
+ }, z.core.$strip>], "type">>;
41
23
  viewport: z.ZodDefault<z.ZodObject<{
42
24
  width: z.ZodDefault<z.ZodNumber>;
43
25
  height: z.ZodDefault<z.ZodNumber>;
44
- }, "strip", z.ZodTypeAny, {
45
- width: number;
46
- height: number;
47
- }, {
48
- width?: number | undefined;
49
- height?: number | undefined;
50
- }>>;
51
- browsers: z.ZodDefault<z.ZodArray<z.ZodEnum<["chromium", "firefox", "webkit"]>, "many">>;
26
+ }, z.core.$strip>>;
27
+ browsers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
28
+ chromium: "chromium";
29
+ firefox: "firefox";
30
+ webkit: "webkit";
31
+ }>>>;
52
32
  threshold: z.ZodOptional<z.ZodNumber>;
53
33
  maxDiffPercent: z.ZodOptional<z.ZodNumber>;
54
34
  localSnapshotsDir: z.ZodOptional<z.ZodString>;
55
- include: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
56
- exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
35
+ include: z.ZodOptional<z.ZodArray<z.ZodString>>;
36
+ exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
57
37
  waitForSelector: z.ZodDefault<z.ZodString>;
58
38
  waitTimeout: z.ZodDefault<z.ZodNumber>;
59
39
  concurrency: z.ZodDefault<z.ZodNumber>;
40
+ ignoreSelectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
41
+ ignoreColor: z.ZodOptional<z.ZodString>;
60
42
  apiUrl: z.ZodOptional<z.ZodString>;
61
43
  apiToken: z.ZodOptional<z.ZodString>;
62
- }, "strip", z.ZodTypeAny, {
63
- storage: {
64
- type: "s3";
65
- bucket: string;
66
- region: string;
67
- prefix?: string | undefined;
68
- endpoint?: string | undefined;
69
- accessKeyId?: string | undefined;
70
- secretAccessKey?: string | undefined;
71
- } | {
72
- type: "local";
73
- directory: string;
74
- };
75
- viewport: {
76
- width: number;
77
- height: number;
78
- };
79
- browsers: ("chromium" | "firefox" | "webkit")[];
80
- waitForSelector: string;
81
- waitTimeout: number;
82
- concurrency: number;
83
- storybookUrl?: string | undefined;
84
- storybookStaticDir?: string | undefined;
85
- threshold?: number | undefined;
86
- maxDiffPercent?: number | undefined;
87
- localSnapshotsDir?: string | undefined;
88
- include?: string[] | undefined;
89
- exclude?: string[] | undefined;
90
- apiUrl?: string | undefined;
91
- apiToken?: string | undefined;
92
- }, {
93
- storybookUrl?: string | undefined;
94
- storybookStaticDir?: string | undefined;
95
- storage?: {
96
- type: "s3";
97
- bucket: string;
98
- region: string;
99
- prefix?: string | undefined;
100
- endpoint?: string | undefined;
101
- accessKeyId?: string | undefined;
102
- secretAccessKey?: string | undefined;
103
- } | {
104
- type: "local";
105
- directory: string;
106
- } | undefined;
107
- viewport?: {
108
- width?: number | undefined;
109
- height?: number | undefined;
110
- } | undefined;
111
- browsers?: ("chromium" | "firefox" | "webkit")[] | undefined;
112
- threshold?: number | undefined;
113
- maxDiffPercent?: number | undefined;
114
- localSnapshotsDir?: string | undefined;
115
- include?: string[] | undefined;
116
- exclude?: string[] | undefined;
117
- waitForSelector?: string | undefined;
118
- waitTimeout?: number | undefined;
119
- concurrency?: number | undefined;
120
- apiUrl?: string | undefined;
121
- apiToken?: string | undefined;
122
- }>, {
123
- storage: {
124
- type: "s3";
125
- bucket: string;
126
- region: string;
127
- prefix?: string | undefined;
128
- endpoint?: string | undefined;
129
- accessKeyId?: string | undefined;
130
- secretAccessKey?: string | undefined;
131
- } | {
132
- type: "local";
133
- directory: string;
134
- };
135
- viewport: {
136
- width: number;
137
- height: number;
138
- };
139
- browsers: ("chromium" | "firefox" | "webkit")[];
140
- waitForSelector: string;
141
- waitTimeout: number;
142
- concurrency: number;
143
- storybookUrl?: string | undefined;
144
- storybookStaticDir?: string | undefined;
145
- threshold?: number | undefined;
146
- maxDiffPercent?: number | undefined;
147
- localSnapshotsDir?: string | undefined;
148
- include?: string[] | undefined;
149
- exclude?: string[] | undefined;
150
- apiUrl?: string | undefined;
151
- apiToken?: string | undefined;
152
- }, {
153
- storybookUrl?: string | undefined;
154
- storybookStaticDir?: string | undefined;
155
- storage?: {
156
- type: "s3";
157
- bucket: string;
158
- region: string;
159
- prefix?: string | undefined;
160
- endpoint?: string | undefined;
161
- accessKeyId?: string | undefined;
162
- secretAccessKey?: string | undefined;
163
- } | {
164
- type: "local";
165
- directory: string;
166
- } | undefined;
167
- viewport?: {
168
- width?: number | undefined;
169
- height?: number | undefined;
170
- } | undefined;
171
- browsers?: ("chromium" | "firefox" | "webkit")[] | undefined;
172
- threshold?: number | undefined;
173
- maxDiffPercent?: number | undefined;
174
- localSnapshotsDir?: string | undefined;
175
- include?: string[] | undefined;
176
- exclude?: string[] | undefined;
177
- waitForSelector?: string | undefined;
178
- waitTimeout?: number | undefined;
179
- concurrency?: number | undefined;
180
- apiUrl?: string | undefined;
181
- apiToken?: string | undefined;
182
- }>;
44
+ }, z.core.$strip>;
183
45
  export type ConfigInput = z.input<typeof configSchema>;
184
46
  export type Config = z.output<typeof configSchema>;
185
47
  export declare function validateConfig(input: unknown): Config;
@@ -53,6 +53,13 @@ export const configSchema = z.object({
53
53
  // page settling, so a few in parallel cut the run time almost linearly; the
54
54
  // ceiling is the machine running the browsers and the Storybook serving them.
55
55
  concurrency: z.number().int().min(1).default(4),
56
+ // Elements matching these are painted over in every capture, as is anything
57
+ // marked data-storysnap-ignore, so dynamic content - dates, avatars, ads -
58
+ // cannot fail a run. Handy for markup written for another tool, such as
59
+ // Chromatic's [data-chromatic="ignore"] and .chromatic-ignore.
60
+ ignoreSelectors: z.array(z.string().min(1)).optional(),
61
+ // The colour of that paint. Any CSS colour.
62
+ ignoreColor: z.string().min(1).optional(),
56
63
  // API configuration (optional - can also use ~/.storysnap/credentials)
57
64
  apiUrl: z.string().url().optional(),
58
65
  apiToken: z.string().optional(),
@@ -15,6 +15,11 @@ export declare class ScreenshotEngine {
15
15
  * to its messages, which buries the actual reason when printed per story.
16
16
  */
17
17
  export declare function describeCaptureError(error: unknown): string;
18
+ /** Marks an element whose contents are left out of the comparison. */
19
+ export declare const IGNORE_ATTRIBUTE = "data-storysnap-ignore";
20
+ export declare const DEFAULT_IGNORE_COLOR = "#808080";
21
+ /** The built-in attribute plus any selectors the config adds, as one selector list. */
22
+ export declare function getIgnoreSelector(extraSelectors?: readonly string[]): string;
18
23
  export declare function getScreenshotKey(storyId: string, browser: Browser): string;
19
24
  export declare function parseScreenshotKey(key: string): {
20
25
  storyId: string;
@@ -52,9 +52,14 @@ export class ScreenshotEngine {
52
52
  });
53
53
  // Additional wait for any animations or lazy loading
54
54
  await this.waitForStability(page);
55
+ // Ignored elements are painted over in every capture, baseline and
56
+ // current alike, so their contents never register as a diff. The box
57
+ // still follows the element, so moving or resizing it does.
55
58
  const buffer = await page.screenshot({
56
59
  fullPage: false,
57
60
  type: 'png',
61
+ mask: [page.locator(getIgnoreSelector(this.config.ignoreSelectors))],
62
+ maskColor: this.config.ignoreColor ?? DEFAULT_IGNORE_COLOR,
58
63
  });
59
64
  return {
60
65
  storyId: story.id,
@@ -115,6 +120,13 @@ export function describeCaptureError(error) {
115
120
  const message = error instanceof Error ? error.message : String(error);
116
121
  return message.split('\n')[0].trim() || 'Unknown capture error';
117
122
  }
123
+ /** Marks an element whose contents are left out of the comparison. */
124
+ export const IGNORE_ATTRIBUTE = 'data-storysnap-ignore';
125
+ export const DEFAULT_IGNORE_COLOR = '#808080';
126
+ /** The built-in attribute plus any selectors the config adds, as one selector list. */
127
+ export function getIgnoreSelector(extraSelectors = []) {
128
+ return [`[${IGNORE_ATTRIBUTE}]`, ...extraSelectors].join(', ');
129
+ }
118
130
  export function getScreenshotKey(storyId, browser) {
119
131
  return `${storyId}::${browser}`;
120
132
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@storysnap/cli",
3
- "version": "1.2.1",
3
+ "version": "2.0.0",
4
4
  "description": "Visual regression testing for Storybook - capture screenshots, detect changes, and maintain baselines",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -53,27 +53,26 @@
53
53
  },
54
54
  "homepage": "https://github.com/Kosai106/storysnap#readme",
55
55
  "dependencies": {
56
- "@aws-sdk/client-s3": "^3.400.0",
57
- "chalk": "^5.3.0",
58
- "commander": "^11.0.0",
59
- "glob": "^10.3.0",
60
- "ora": "^7.0.0",
61
- "pixelmatch": "^5.3.0",
62
- "playwright": "^1.40.0",
56
+ "@aws-sdk/client-s3": "^3.1147.0",
57
+ "chalk": "^6.0.1",
58
+ "commander": "^15.0.0",
59
+ "glob": "^13.0.6",
60
+ "ora": "^9.4.1",
61
+ "pixelmatch": "^8.0.0",
62
+ "playwright": "^1.63.0",
63
63
  "pngjs": "^7.0.0",
64
- "zod": "^3.22.0"
64
+ "zod": "^4.6.5"
65
65
  },
66
66
  "devDependencies": {
67
- "@types/node": "^20.10.0",
68
- "@types/pixelmatch": "^5.2.6",
69
- "@types/pngjs": "^6.0.4",
70
- "@vitest/coverage-v8": "^2.0.0",
71
- "typescript": "^5.3.0",
72
- "vitest": "^2.0.0",
73
- "@storysnap/shared": "1.0.0"
67
+ "@storysnap/shared": "1.0.0",
68
+ "@types/node": "^22.12.0",
69
+ "@types/pngjs": "^6.0.5",
70
+ "@vitest/coverage-v8": "^5.0.3",
71
+ "typescript": "^7.0.2",
72
+ "vitest": "^5.0.3"
74
73
  },
75
74
  "engines": {
76
- "node": ">=18.0.0"
75
+ "node": ">=22.12.0"
77
76
  },
78
77
  "scripts": {
79
78
  "build": "tsc",