@storysnap/cli 2.0.0 → 2.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/dist/api/client.d.ts +34 -1
- package/dist/api/client.js +3 -1
- package/dist/cli/commands/test.d.ts +1 -0
- package/dist/cli/commands/test.js +119 -62
- package/dist/cli/commands/update.d.ts +1 -0
- package/dist/cli/commands/update.js +62 -30
- package/dist/cli/environment-warning.d.ts +17 -0
- package/dist/cli/environment-warning.js +42 -0
- package/dist/cli/index.js +11 -3
- package/dist/cli/review.d.ts +9 -0
- package/dist/cli/review.js +10 -0
- package/dist/cli/select-stories.d.ts +6 -1
- package/dist/cli/select-stories.js +16 -0
- package/dist/cli/verdict.d.ts +17 -0
- package/dist/cli/verdict.js +22 -0
- package/dist/config/schema.d.ts +11 -0
- package/dist/config/schema.js +18 -0
- package/dist/core/capture-environment.d.ts +19 -0
- package/dist/core/capture-environment.js +102 -0
- package/dist/core/changed.js +10 -23
- package/dist/core/compare.d.ts +3 -1
- package/dist/core/compare.js +30 -10
- package/dist/core/git-context.d.ts +25 -0
- package/dist/core/git-context.js +75 -0
- package/dist/core/git.d.ts +11 -0
- package/dist/core/git.js +25 -0
- package/dist/core/hash.d.ts +7 -0
- package/dist/core/hash.js +11 -0
- package/dist/core/modes.d.ts +50 -0
- package/dist/core/modes.js +124 -0
- package/dist/core/screenshot.d.ts +91 -4
- package/dist/core/screenshot.js +266 -47
- package/dist/core/story-parameters.d.ts +48 -0
- package/dist/core/story-parameters.js +122 -0
- package/dist/core/story-render.d.ts +31 -0
- package/dist/core/story-render.js +75 -0
- package/dist/core/storybook.d.ts +16 -2
- package/dist/core/storybook.js +18 -6
- package/dist/core/viewports.d.ts +14 -0
- package/dist/core/viewports.js +27 -0
- package/package.json +9 -10
package/dist/core/screenshot.js
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
import { chromium, firefox, webkit } from 'playwright';
|
|
2
2
|
import { getStoryUrl } from './storybook.js';
|
|
3
3
|
import { DEFAULT_CONCURRENCY, mapWithConcurrency } from './concurrency.js';
|
|
4
|
+
import { readStoryParameters, resolveStoryParameters } from './story-parameters.js';
|
|
5
|
+
import { resolveViewports, sameViewport } from './viewports.js';
|
|
6
|
+
import { waitForStoryToSettle, watchStoryErrors } from './story-render.js';
|
|
7
|
+
import { globalsParameter, resolveModes, sameMode, verifyModeApplied } from './modes.js';
|
|
8
|
+
import { describeCaptureEnvironment, withCaptureEnvironment } from './capture-environment.js';
|
|
4
9
|
const BROWSER_MAP = {
|
|
5
10
|
chromium,
|
|
6
11
|
firefox,
|
|
@@ -8,6 +13,8 @@ const BROWSER_MAP = {
|
|
|
8
13
|
};
|
|
9
14
|
export class ScreenshotEngine {
|
|
10
15
|
browsers = new Map();
|
|
16
|
+
/** Recorded in each browser's screenshots, for comparing baselines across machines. */
|
|
17
|
+
environments = new Map();
|
|
11
18
|
config;
|
|
12
19
|
baseUrl;
|
|
13
20
|
constructor(config) {
|
|
@@ -25,6 +32,7 @@ export class ScreenshotEngine {
|
|
|
25
32
|
headless: true,
|
|
26
33
|
});
|
|
27
34
|
this.browsers.set(browserName, browser);
|
|
35
|
+
this.environments.set(browserName, describeCaptureEnvironment(browserName, browser.version()));
|
|
28
36
|
}
|
|
29
37
|
}
|
|
30
38
|
async close() {
|
|
@@ -32,71 +40,184 @@ export class ScreenshotEngine {
|
|
|
32
40
|
await browser.close();
|
|
33
41
|
}
|
|
34
42
|
this.browsers.clear();
|
|
43
|
+
this.environments.clear();
|
|
35
44
|
}
|
|
45
|
+
/**
|
|
46
|
+
* Captures a story at each of its viewports, trying again up to
|
|
47
|
+
* `captureRetries` times when the capture throws. A story that needed a
|
|
48
|
+
* retry is marked flaky at every viewport.
|
|
49
|
+
*/
|
|
50
|
+
async captureStoryWithRetries(story, browserName) {
|
|
51
|
+
const retries = this.config.captureRetries ?? DEFAULT_CAPTURE_RETRIES;
|
|
52
|
+
for (let attempt = 0;; attempt++) {
|
|
53
|
+
try {
|
|
54
|
+
const screenshots = await this.captureStory(story, browserName);
|
|
55
|
+
return attempt > 0 ? screenshots.map((screenshot) => ({ ...screenshot, flaky: true })) : screenshots;
|
|
56
|
+
}
|
|
57
|
+
catch (error) {
|
|
58
|
+
if (attempt >= retries) {
|
|
59
|
+
throw error;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Captures a story once per viewport. The story's parameters, which can
|
|
66
|
+
* change the viewports, are only readable once it has rendered, so it is
|
|
67
|
+
* first loaded at the first configured viewport; every other viewport gets
|
|
68
|
+
* a page of its own, loaded at that size, rather than a resized one - a
|
|
69
|
+
* component that measures the window once on mount must look the way it
|
|
70
|
+
* would if opened at that size.
|
|
71
|
+
*/
|
|
36
72
|
async captureStory(story, browserName) {
|
|
37
73
|
const browser = this.browsers.get(browserName);
|
|
38
74
|
if (!browser) {
|
|
39
75
|
throw new Error(`Browser ${browserName} not initialized. Call initialize() first.`);
|
|
40
76
|
}
|
|
77
|
+
// Opened in the first configured mode, at the first configured viewport:
|
|
78
|
+
// the capture most stories start with, so this page is rarely wasted.
|
|
79
|
+
const [firstViewport] = resolveViewports(this.config);
|
|
80
|
+
const [firstMode] = resolveModes(this.config.modes, undefined);
|
|
81
|
+
const first = await this.openStory(browser, story, firstViewport, firstMode);
|
|
82
|
+
try {
|
|
83
|
+
// Parameters live in the running preview, not in index.json, so they are
|
|
84
|
+
// read once the story has rendered.
|
|
85
|
+
const parameters = resolveStoryParameters(await readStoryParameters(first, story.id));
|
|
86
|
+
if (parameters.disable) {
|
|
87
|
+
return [{ ...this.blank(story, browserName, firstViewport), skipped: true }];
|
|
88
|
+
}
|
|
89
|
+
// Every mode at every viewport, each on a page loaded that way.
|
|
90
|
+
const screenshots = [];
|
|
91
|
+
for (const mode of resolveModes(this.config.modes, parameters.modes)) {
|
|
92
|
+
for (const viewport of resolveViewports(this.config, parameters.viewports)) {
|
|
93
|
+
if (sameViewport(viewport, firstViewport) && sameMode(mode, firstMode)) {
|
|
94
|
+
screenshots.push(await this.shoot(first, story, browserName, viewport, mode, parameters));
|
|
95
|
+
continue;
|
|
96
|
+
}
|
|
97
|
+
const page = await this.openStory(browser, story, viewport, mode);
|
|
98
|
+
try {
|
|
99
|
+
screenshots.push(await this.shoot(page, story, browserName, viewport, mode, parameters));
|
|
100
|
+
}
|
|
101
|
+
finally {
|
|
102
|
+
await page.close();
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
return screenshots;
|
|
107
|
+
}
|
|
108
|
+
finally {
|
|
109
|
+
await first.close();
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Opens the story at a viewport, in a mode, and waits for Storybook to
|
|
114
|
+
* finish rendering it - play function included - and for its root to be
|
|
115
|
+
* visible. The mode's globals go in the URL, so the story renders - and its
|
|
116
|
+
* play function runs - in the mode from the start.
|
|
117
|
+
*/
|
|
118
|
+
async openStory(browser, story, viewport, mode) {
|
|
119
|
+
const globals = globalsParameter(mode);
|
|
41
120
|
const page = await browser.newPage({
|
|
42
|
-
viewport
|
|
121
|
+
viewport,
|
|
122
|
+
// Components that honour prefers-reduced-motion skip their motion
|
|
123
|
+
// entirely, which is steadier than catching it at any particular frame.
|
|
124
|
+
reducedMotion: this.freeze ? 'reduce' : 'no-preference',
|
|
43
125
|
});
|
|
44
126
|
try {
|
|
45
|
-
|
|
127
|
+
await watchStoryErrors(page);
|
|
128
|
+
const url = getStoryUrl(this.baseUrl, story.id) + (globals ? `&globals=${globals}` : '');
|
|
46
129
|
await page.goto(url, { waitUntil: 'networkidle' });
|
|
47
|
-
//
|
|
48
|
-
|
|
49
|
-
await page
|
|
130
|
+
// Before the root: a story whose render threw may never show it, and
|
|
131
|
+
// its own error says far more than a selector timeout would.
|
|
132
|
+
await waitForStoryToSettle(page, this.config.waitTimeout ?? DEFAULT_WAIT_TIMEOUT);
|
|
133
|
+
await page.waitForSelector(this.config.waitForSelector ?? '#storybook-root', {
|
|
50
134
|
state: 'visible',
|
|
51
135
|
timeout: this.config.waitTimeout,
|
|
52
136
|
});
|
|
53
|
-
|
|
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.
|
|
58
|
-
const buffer = await page.screenshot({
|
|
59
|
-
fullPage: false,
|
|
60
|
-
type: 'png',
|
|
61
|
-
mask: [page.locator(getIgnoreSelector(this.config.ignoreSelectors))],
|
|
62
|
-
maskColor: this.config.ignoreColor ?? DEFAULT_IGNORE_COLOR,
|
|
63
|
-
});
|
|
64
|
-
return {
|
|
65
|
-
storyId: story.id,
|
|
66
|
-
browser: browserName,
|
|
67
|
-
buffer: Buffer.from(buffer),
|
|
68
|
-
width: this.config.viewport.width,
|
|
69
|
-
height: this.config.viewport.height,
|
|
70
|
-
};
|
|
137
|
+
return page;
|
|
71
138
|
}
|
|
72
|
-
|
|
139
|
+
catch (error) {
|
|
73
140
|
await page.close();
|
|
141
|
+
throw error;
|
|
74
142
|
}
|
|
75
143
|
}
|
|
144
|
+
/** Waits for a rendered story to settle as its parameters ask, then captures it. */
|
|
145
|
+
async shoot(page, story, browserName, viewport, mode, parameters) {
|
|
146
|
+
// A global the project does not declare would be dropped by Storybook,
|
|
147
|
+
// and the capture would quietly be the story without the mode.
|
|
148
|
+
await verifyModeApplied(page, mode);
|
|
149
|
+
if (parameters.waitForSelector) {
|
|
150
|
+
// Any visible match, not the first match: Storybook's own hidden UI
|
|
151
|
+
// (its error overlay has buttons, for one) can match a broad selector
|
|
152
|
+
// first and would never become visible. Not scoped to the root either,
|
|
153
|
+
// since portals - modals, popovers - render outside it.
|
|
154
|
+
await page
|
|
155
|
+
.locator(parameters.waitForSelector)
|
|
156
|
+
.filter({ visible: true })
|
|
157
|
+
.first()
|
|
158
|
+
.waitFor({ state: 'visible', timeout: this.config.waitTimeout });
|
|
159
|
+
}
|
|
160
|
+
await waitForAssets(page);
|
|
161
|
+
if (parameters.delay) {
|
|
162
|
+
await page.waitForTimeout(parameters.delay);
|
|
163
|
+
}
|
|
164
|
+
const ignoreSelectors = [...(this.config.ignoreSelectors ?? []), ...(parameters.ignoreSelectors ?? [])];
|
|
165
|
+
// Ignored elements are painted over in every capture, baseline and
|
|
166
|
+
// current alike, so their contents never register as a diff. The box
|
|
167
|
+
// still follows the element, so moving or resizing it does.
|
|
168
|
+
const { buffer, stable } = await captureWhenStable(() => page.screenshot({
|
|
169
|
+
fullPage: false,
|
|
170
|
+
type: 'png',
|
|
171
|
+
// Finite CSS animations and transitions jump to their end state and
|
|
172
|
+
// infinite ones go back to their start, so a capture never lands
|
|
173
|
+
// mid-frame. The text caret is hidden either way.
|
|
174
|
+
animations: this.freeze ? 'disabled' : 'allow',
|
|
175
|
+
caret: 'hide',
|
|
176
|
+
mask: [page.locator(getIgnoreSelector(ignoreSelectors))],
|
|
177
|
+
maskColor: this.config.ignoreColor ?? DEFAULT_IGNORE_COLOR,
|
|
178
|
+
}));
|
|
179
|
+
return {
|
|
180
|
+
...this.blank(story, browserName, viewport),
|
|
181
|
+
...(mode.name && { mode: mode.name }),
|
|
182
|
+
buffer: withCaptureEnvironment(Buffer.from(buffer), this.environments.get(browserName) ?? browserName),
|
|
183
|
+
...(stable ? {} : { flaky: true }),
|
|
184
|
+
...(parameters.threshold !== undefined && { threshold: parameters.threshold }),
|
|
185
|
+
...(parameters.maxDiffPercent !== undefined && { maxDiffPercent: parameters.maxDiffPercent }),
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
/** A screenshot with no image yet: the shape failures and skips are reported in. */
|
|
189
|
+
blank(story, browserName, viewport) {
|
|
190
|
+
return {
|
|
191
|
+
storyId: story.id,
|
|
192
|
+
browser: browserName,
|
|
193
|
+
buffer: Buffer.alloc(0),
|
|
194
|
+
width: viewport.width,
|
|
195
|
+
height: viewport.height,
|
|
196
|
+
};
|
|
197
|
+
}
|
|
198
|
+
get freeze() {
|
|
199
|
+
return this.config.disableAnimations ?? true;
|
|
200
|
+
}
|
|
76
201
|
async captureStories(stories, onProgress) {
|
|
77
202
|
const screenshots = new Map();
|
|
78
203
|
const tasks = stories.flatMap((story) => this.config.browsers.map((browserName) => ({ story, browserName })));
|
|
79
204
|
let completed = 0;
|
|
80
205
|
// Most of a capture is spent waiting - for the network to go idle, for
|
|
81
|
-
// the settle
|
|
82
|
-
//
|
|
206
|
+
// fonts and images, for the page to settle - so several stories run at
|
|
207
|
+
// once. Each still gets fresh pages, keeping stories isolated.
|
|
83
208
|
await mapWithConcurrency(tasks, this.config.concurrency ?? DEFAULT_CONCURRENCY, async ({ story, browserName }) => {
|
|
84
|
-
const screenshotKey = getScreenshotKey(story.id, browserName);
|
|
85
209
|
try {
|
|
86
|
-
const screenshot
|
|
87
|
-
|
|
210
|
+
for (const screenshot of await this.captureStoryWithRetries(story, browserName)) {
|
|
211
|
+
screenshots.set(getScreenshotKey(screenshot), screenshot);
|
|
212
|
+
}
|
|
88
213
|
}
|
|
89
214
|
catch (error) {
|
|
90
215
|
// An empty buffer marks the failure for the callers; the reason travels
|
|
91
|
-
// with it so they can say why rather than just that it failed.
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
width: 0,
|
|
97
|
-
height: 0,
|
|
98
|
-
error: describeCaptureError(error),
|
|
99
|
-
});
|
|
216
|
+
// with it so they can say why rather than just that it failed. The
|
|
217
|
+
// story's own viewports are unknown here, so it is filed under the
|
|
218
|
+
// first configured one.
|
|
219
|
+
const failed = { ...this.blank(story, browserName, resolveViewports(this.config)[0]), error: describeCaptureError(error) };
|
|
220
|
+
screenshots.set(getScreenshotKey(failed), failed);
|
|
100
221
|
}
|
|
101
222
|
completed++;
|
|
102
223
|
if (onProgress) {
|
|
@@ -105,12 +226,67 @@ export class ScreenshotEngine {
|
|
|
105
226
|
});
|
|
106
227
|
return screenshots;
|
|
107
228
|
}
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
229
|
+
}
|
|
230
|
+
/** How long to wait for a story to render, as `waitTimeout` defaults to. */
|
|
231
|
+
const DEFAULT_WAIT_TIMEOUT = 30_000;
|
|
232
|
+
/** Retries for a capture that throws: a timeout, a crashed page. */
|
|
233
|
+
export const DEFAULT_CAPTURE_RETRIES = 1;
|
|
234
|
+
/** How long to wait for images to load and decode before capturing anyway. */
|
|
235
|
+
export const ASSET_TIMEOUT_MS = 10_000;
|
|
236
|
+
/**
|
|
237
|
+
* Waits for web fonts and for the images on the page to load and decode, so a
|
|
238
|
+
* capture never shows fallback glyphs or an empty image box. Lazy images
|
|
239
|
+
* outside the viewport are skipped, and an image that never loads holds the
|
|
240
|
+
* capture up for at most `timeoutMs`.
|
|
241
|
+
*/
|
|
242
|
+
export async function waitForAssets(page, timeoutMs = ASSET_TIMEOUT_MS) {
|
|
243
|
+
await page.evaluate(async (timeout) => {
|
|
244
|
+
// Runs in the browser. The CLI is typed for Node, without the DOM library,
|
|
245
|
+
// so the little of the DOM this needs is described here.
|
|
246
|
+
const { document, innerWidth, innerHeight } = globalThis;
|
|
247
|
+
// A lazy image outside the viewport is never requested, so it would hold
|
|
248
|
+
// every capture up for the whole timeout - and it is not in the shot.
|
|
249
|
+
const offscreen = (img) => {
|
|
250
|
+
const box = img.getBoundingClientRect();
|
|
251
|
+
return box.bottom < 0 || box.right < 0 || box.top > innerHeight || box.left > innerWidth;
|
|
252
|
+
};
|
|
253
|
+
const settled = (async () => {
|
|
254
|
+
await document.fonts.ready;
|
|
255
|
+
await Promise.all(Array.from(document.images, async (img) => {
|
|
256
|
+
if (!img.complete && img.loading === 'lazy' && offscreen(img)) {
|
|
257
|
+
return;
|
|
258
|
+
}
|
|
259
|
+
if (!img.complete) {
|
|
260
|
+
await new Promise((resolve) => {
|
|
261
|
+
img.addEventListener('load', () => resolve(), { once: true });
|
|
262
|
+
img.addEventListener('error', () => resolve(), { once: true });
|
|
263
|
+
});
|
|
264
|
+
}
|
|
265
|
+
// decode() rejects for broken images; they are as loaded as they get.
|
|
266
|
+
await img.decode().catch(() => undefined);
|
|
267
|
+
}));
|
|
268
|
+
})();
|
|
269
|
+
await Promise.race([settled, new Promise((resolve) => setTimeout(resolve, timeout))]);
|
|
270
|
+
}, timeoutMs);
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* Takes screenshots until two in a row are byte-identical and returns that
|
|
274
|
+
* one; if the page never settles, returns the last one taken with `stable`
|
|
275
|
+
* false. With animations frozen most pages match on the second screenshot, so
|
|
276
|
+
* this is usually quicker than a fixed settle delay while still catching late
|
|
277
|
+
* layout shifts.
|
|
278
|
+
*/
|
|
279
|
+
export async function captureWhenStable(take, { maxAttempts = 5, intervalMs = 100 } = {}) {
|
|
280
|
+
let previous = await take();
|
|
281
|
+
for (let attempt = 1; attempt < maxAttempts; attempt++) {
|
|
282
|
+
await new Promise((resolve) => setTimeout(resolve, intervalMs));
|
|
283
|
+
const current = await take();
|
|
284
|
+
if (current.equals(previous)) {
|
|
285
|
+
return { buffer: current, stable: true };
|
|
286
|
+
}
|
|
287
|
+
previous = current;
|
|
113
288
|
}
|
|
289
|
+
return { buffer: previous, stable: false };
|
|
114
290
|
}
|
|
115
291
|
/**
|
|
116
292
|
* The first line of a capture error. Playwright appends a multi-line call log
|
|
@@ -127,12 +303,55 @@ export const DEFAULT_IGNORE_COLOR = '#808080';
|
|
|
127
303
|
export function getIgnoreSelector(extraSelectors = []) {
|
|
128
304
|
return [`[${IGNORE_ATTRIBUTE}]`, ...extraSelectors].join(', ');
|
|
129
305
|
}
|
|
130
|
-
|
|
131
|
-
|
|
306
|
+
/**
|
|
307
|
+
* The captures of each story in each browser - one per viewport, or a single
|
|
308
|
+
* failed one - keyed `storyId::browser`, in capture order.
|
|
309
|
+
*/
|
|
310
|
+
export function groupCaptures(screenshots) {
|
|
311
|
+
const groups = new Map();
|
|
312
|
+
for (const screenshot of screenshots.values()) {
|
|
313
|
+
const key = `${screenshot.storyId}::${screenshot.browser}`;
|
|
314
|
+
groups.set(key, [...(groups.get(key) ?? []), screenshot]);
|
|
315
|
+
}
|
|
316
|
+
return groups;
|
|
317
|
+
}
|
|
318
|
+
/** ` @ 375x667` for a capture at a viewport other than the configured one; empty otherwise. */
|
|
319
|
+
export function viewportLabel(viewport, configured) {
|
|
320
|
+
return viewport.width === configured.width && viewport.height === configured.height
|
|
321
|
+
? ''
|
|
322
|
+
: ` @ ${viewport.width}x${viewport.height}`;
|
|
323
|
+
}
|
|
324
|
+
/** ` [dark] @ 375x667`: what tells a story's captures apart, after its name. */
|
|
325
|
+
export function captureLabel(capture, configured) {
|
|
326
|
+
return `${capture.mode ? ` [${capture.mode}]` : ''}${viewportLabel(capture.viewport, configured)}`;
|
|
327
|
+
}
|
|
328
|
+
/** Identifies one capture: a story, in a browser, at a viewport, in a mode. */
|
|
329
|
+
export function getScreenshotKey(screenshot) {
|
|
330
|
+
return `${screenshot.storyId}::${screenshot.browser}::${screenshot.width}x${screenshot.height}::${screenshot.mode ?? ''}`;
|
|
132
331
|
}
|
|
133
332
|
export function parseScreenshotKey(key) {
|
|
134
|
-
const [storyId, browser] = key.split('::');
|
|
135
|
-
|
|
333
|
+
const [storyId, browser, size, ...mode] = key.split('::');
|
|
334
|
+
const [width, height] = size.split('x').map(Number);
|
|
335
|
+
// A mode name may itself contain '::'.
|
|
336
|
+
return { storyId, browser: browser, viewport: { width, height }, mode: mode.join('::') };
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* Takes the stories their parameters disabled out of a capture: out of the
|
|
340
|
+
* story list, so totals and "not captured" counts leave them alone, and out
|
|
341
|
+
* of the screenshots, so nothing downstream mistakes them for failures.
|
|
342
|
+
* Parameters are the same in every browser, so one skip drops the story.
|
|
343
|
+
*/
|
|
344
|
+
export function dropSkipped(stories, screenshots) {
|
|
345
|
+
const skippedIds = new Set([...screenshots.values()].filter((screenshot) => screenshot.skipped).map((screenshot) => screenshot.storyId));
|
|
346
|
+
for (const [key, screenshot] of screenshots) {
|
|
347
|
+
if (skippedIds.has(screenshot.storyId)) {
|
|
348
|
+
screenshots.delete(key);
|
|
349
|
+
}
|
|
350
|
+
}
|
|
351
|
+
return {
|
|
352
|
+
stories: stories.filter((story) => !skippedIds.has(story.id)),
|
|
353
|
+
skipped: stories.filter((story) => skippedIds.has(story.id)),
|
|
354
|
+
};
|
|
136
355
|
}
|
|
137
356
|
export async function captureScreenshots(config, stories, onProgress) {
|
|
138
357
|
const engine = new ScreenshotEngine(config);
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import type { Page } from 'playwright';
|
|
3
|
+
/**
|
|
4
|
+
* What a story can override about its own capture and comparison, through
|
|
5
|
+
* `parameters.storysnap` in its CSF file:
|
|
6
|
+
*
|
|
7
|
+
* export const Clock = { parameters: { storysnap: { delay: 300 } } };
|
|
8
|
+
*/
|
|
9
|
+
export declare const storysnapParametersSchema: z.ZodObject<{
|
|
10
|
+
disable: z.ZodOptional<z.ZodBoolean>;
|
|
11
|
+
delay: z.ZodOptional<z.ZodNumber>;
|
|
12
|
+
ignoreSelectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
13
|
+
threshold: z.ZodOptional<z.ZodNumber>;
|
|
14
|
+
maxDiffPercent: z.ZodOptional<z.ZodNumber>;
|
|
15
|
+
waitForSelector: z.ZodOptional<z.ZodString>;
|
|
16
|
+
viewports: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
|
|
17
|
+
width: z.ZodNumber;
|
|
18
|
+
height: z.ZodNumber;
|
|
19
|
+
}, z.core.$strip>]>>>;
|
|
20
|
+
modes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
|
|
21
|
+
disable: z.ZodLiteral<true>;
|
|
22
|
+
}, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>]>>]>>>;
|
|
23
|
+
}, z.core.$strict>;
|
|
24
|
+
export type StoryParameters = z.infer<typeof storysnapParametersSchema>;
|
|
25
|
+
/** The two parameter objects as read from the preview, before validation. */
|
|
26
|
+
export interface RawStoryParameters {
|
|
27
|
+
storysnap?: unknown;
|
|
28
|
+
chromatic?: unknown;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Validates a story's parameters and folds Chromatic's into StorySnap's, with
|
|
32
|
+
* `storysnap` winning where both set the same thing. Throws with a message
|
|
33
|
+
* naming the bad parameter, so the story errors instead of being captured
|
|
34
|
+
* with settings it did not ask for.
|
|
35
|
+
*/
|
|
36
|
+
export declare function resolveStoryParameters(raw: RawStoryParameters | null): StoryParameters;
|
|
37
|
+
/**
|
|
38
|
+
* Reads the rendered story's `storysnap` and `chromatic` parameters from the
|
|
39
|
+
* Storybook preview. Returns null when the page has no Storybook preview to
|
|
40
|
+
* ask - a static stand-in, say - in which case the story has no parameters.
|
|
41
|
+
*
|
|
42
|
+
* Storybook 7 and later expose the preview as `__STORYBOOK_PREVIEW__`; 8 moved
|
|
43
|
+
* its store from `storyStore` to `storyStoreValue`. Storybook 6 has
|
|
44
|
+
* `__STORYBOOK_STORY_STORE__` instead. Only plain data survives the trip out
|
|
45
|
+
* of the page, so functions in parameters are dropped.
|
|
46
|
+
*/
|
|
47
|
+
export declare function readStoryParameters(page: Page, storyId: string): Promise<RawStoryParameters | null>;
|
|
48
|
+
//# sourceMappingURL=story-parameters.d.ts.map
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { viewportInputSchema } from '../config/schema.js';
|
|
3
|
+
import { parameterModesSchema } from './modes.js';
|
|
4
|
+
/**
|
|
5
|
+
* What a story can override about its own capture and comparison, through
|
|
6
|
+
* `parameters.storysnap` in its CSF file:
|
|
7
|
+
*
|
|
8
|
+
* export const Clock = { parameters: { storysnap: { delay: 300 } } };
|
|
9
|
+
*/
|
|
10
|
+
export const storysnapParametersSchema = z
|
|
11
|
+
.object({
|
|
12
|
+
/** Leave the story out of capture entirely. */
|
|
13
|
+
disable: z.boolean().optional(),
|
|
14
|
+
/** Extra wait, in ms, after the story has rendered and before capturing. */
|
|
15
|
+
delay: z.number().int().min(0).max(30_000).optional(),
|
|
16
|
+
/** Masked in this story's captures, on top of the configured ones. */
|
|
17
|
+
ignoreSelectors: z.array(z.string().min(1)).optional(),
|
|
18
|
+
/** pixelmatch's per-pixel colour sensitivity for this story. */
|
|
19
|
+
threshold: z.number().min(0).max(1).optional(),
|
|
20
|
+
/** How much of this story's image may differ before it fails, in percent. */
|
|
21
|
+
maxDiffPercent: z.number().min(0).max(100).optional(),
|
|
22
|
+
/** Waited for, visible, after the configured `waitForSelector`. */
|
|
23
|
+
waitForSelector: z.string().min(1).optional(),
|
|
24
|
+
/** Captured at each of these instead of the configured viewports. */
|
|
25
|
+
viewports: z.array(viewportInputSchema).min(1).optional(),
|
|
26
|
+
/** Captured in each of these modes instead of the configured ones. */
|
|
27
|
+
modes: parameterModesSchema.optional(),
|
|
28
|
+
})
|
|
29
|
+
// A misspelt key would otherwise be silently ignored, leaving the story
|
|
30
|
+
// captured exactly as before with nothing to say why.
|
|
31
|
+
.strict();
|
|
32
|
+
/**
|
|
33
|
+
* The subset of Chromatic's parameters with a StorySnap equivalent, so stories
|
|
34
|
+
* written for Chromatic behave the same here. Everything else Chromatic
|
|
35
|
+
* understands is ignored rather than rejected.
|
|
36
|
+
*/
|
|
37
|
+
const chromaticParametersSchema = z.object({
|
|
38
|
+
disableSnapshot: z.boolean().optional(),
|
|
39
|
+
delay: z.number().int().min(0).max(30_000).optional(),
|
|
40
|
+
// Chromatic's diffThreshold is the same pixelmatch sensitivity.
|
|
41
|
+
diffThreshold: z.number().min(0).max(1).optional(),
|
|
42
|
+
// Widths, at the configured viewport's height.
|
|
43
|
+
viewports: z.array(z.number().int().min(1)).min(1).optional(),
|
|
44
|
+
// Chromatic's modes may also name a viewport; here a mode is globals only
|
|
45
|
+
// and every mode is captured at every viewport, so that key is dropped.
|
|
46
|
+
modes: z
|
|
47
|
+
.record(z.string(), z.record(z.string(), z.unknown()))
|
|
48
|
+
.transform((modes) => Object.fromEntries(Object.entries(modes).map(([name, { viewport: _viewport, ...rest }]) => [name, rest])))
|
|
49
|
+
.pipe(parameterModesSchema)
|
|
50
|
+
.optional(),
|
|
51
|
+
});
|
|
52
|
+
/**
|
|
53
|
+
* Validates a story's parameters and folds Chromatic's into StorySnap's, with
|
|
54
|
+
* `storysnap` winning where both set the same thing. Throws with a message
|
|
55
|
+
* naming the bad parameter, so the story errors instead of being captured
|
|
56
|
+
* with settings it did not ask for.
|
|
57
|
+
*/
|
|
58
|
+
export function resolveStoryParameters(raw) {
|
|
59
|
+
if (!raw) {
|
|
60
|
+
return {};
|
|
61
|
+
}
|
|
62
|
+
const chromatic = chromaticParametersSchema.safeParse(raw.chromatic ?? {});
|
|
63
|
+
if (!chromatic.success) {
|
|
64
|
+
throw new Error(`Invalid parameters.chromatic: ${describeIssues(chromatic.error)}`);
|
|
65
|
+
}
|
|
66
|
+
const storysnap = storysnapParametersSchema.safeParse(raw.storysnap ?? {});
|
|
67
|
+
if (!storysnap.success) {
|
|
68
|
+
throw new Error(`Invalid parameters.storysnap: ${describeIssues(storysnap.error)}`);
|
|
69
|
+
}
|
|
70
|
+
const fromChromatic = {
|
|
71
|
+
disable: chromatic.data.disableSnapshot,
|
|
72
|
+
delay: chromatic.data.delay,
|
|
73
|
+
threshold: chromatic.data.diffThreshold,
|
|
74
|
+
viewports: chromatic.data.viewports,
|
|
75
|
+
modes: chromatic.data.modes,
|
|
76
|
+
};
|
|
77
|
+
return Object.fromEntries(Object.entries({ ...fromChromatic, ...withoutUndefined(storysnap.data) }).filter(([, v]) => v !== undefined));
|
|
78
|
+
}
|
|
79
|
+
function withoutUndefined(value) {
|
|
80
|
+
return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined));
|
|
81
|
+
}
|
|
82
|
+
function describeIssues(error) {
|
|
83
|
+
return error.issues
|
|
84
|
+
.map((issue) => {
|
|
85
|
+
if (issue.code === 'unrecognized_keys') {
|
|
86
|
+
return `unknown ${issue.keys.length === 1 ? 'key' : 'keys'} ${issue.keys.map((k) => `"${k}"`).join(', ')}`;
|
|
87
|
+
}
|
|
88
|
+
const path = issue.path.join('.');
|
|
89
|
+
return path ? `${path}: ${issue.message}` : issue.message;
|
|
90
|
+
})
|
|
91
|
+
.join('; ');
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Reads the rendered story's `storysnap` and `chromatic` parameters from the
|
|
95
|
+
* Storybook preview. Returns null when the page has no Storybook preview to
|
|
96
|
+
* ask - a static stand-in, say - in which case the story has no parameters.
|
|
97
|
+
*
|
|
98
|
+
* Storybook 7 and later expose the preview as `__STORYBOOK_PREVIEW__`; 8 moved
|
|
99
|
+
* its store from `storyStore` to `storyStoreValue`. Storybook 6 has
|
|
100
|
+
* `__STORYBOOK_STORY_STORE__` instead. Only plain data survives the trip out
|
|
101
|
+
* of the page, so functions in parameters are dropped.
|
|
102
|
+
*/
|
|
103
|
+
export async function readStoryParameters(page, storyId) {
|
|
104
|
+
return page.evaluate(async (id) => {
|
|
105
|
+
const scope = globalThis;
|
|
106
|
+
let parameters;
|
|
107
|
+
const preview = scope.__STORYBOOK_PREVIEW__;
|
|
108
|
+
const store = preview?.storyStoreValue ?? preview?.storyStore;
|
|
109
|
+
if (store?.loadStory) {
|
|
110
|
+
parameters = (await store.loadStory({ storyId: id })).parameters;
|
|
111
|
+
}
|
|
112
|
+
else if (scope.__STORYBOOK_STORY_STORE__?.fromId) {
|
|
113
|
+
parameters = scope.__STORYBOOK_STORY_STORE__.fromId(id)?.parameters;
|
|
114
|
+
}
|
|
115
|
+
else {
|
|
116
|
+
return null;
|
|
117
|
+
}
|
|
118
|
+
const pick = (value) => (value === undefined ? undefined : JSON.parse(JSON.stringify(value)));
|
|
119
|
+
return { storysnap: pick(parameters?.storysnap), chromatic: pick(parameters?.chromatic) };
|
|
120
|
+
}, storyId);
|
|
121
|
+
}
|
|
122
|
+
//# sourceMappingURL=story-parameters.js.map
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { Page } from 'playwright';
|
|
2
|
+
/** What went wrong while Storybook rendered a story, as its preview reported it. */
|
|
3
|
+
export interface StoryRenderErrors {
|
|
4
|
+
/** The story's play function threw. */
|
|
5
|
+
play?: string;
|
|
6
|
+
/** Rendering the story threw. */
|
|
7
|
+
render?: string;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Records the exceptions Storybook reports for the story on this page. Has to
|
|
11
|
+
* be installed before the page loads: the events are emitted once, during
|
|
12
|
+
* the render, on the preview's channel.
|
|
13
|
+
*
|
|
14
|
+
* Storybook 9 and later report a failed play function through this event
|
|
15
|
+
* only - the render still ends `finished` and nothing shows on the page - so
|
|
16
|
+
* listening is the one way to tell it apart from a play that succeeded.
|
|
17
|
+
*/
|
|
18
|
+
export declare function watchStoryErrors(page: Page): Promise<void>;
|
|
19
|
+
/**
|
|
20
|
+
* Waits until Storybook has finished rendering the story, play function
|
|
21
|
+
* included, so the capture shows its end state rather than whatever the play
|
|
22
|
+
* function had got to. Throws if the play function or the render threw, so
|
|
23
|
+
* the story errors instead of being captured half-done.
|
|
24
|
+
*
|
|
25
|
+
* A page with no Storybook preview - a static stand-in - has nothing to wait
|
|
26
|
+
* for and passes straight through.
|
|
27
|
+
*/
|
|
28
|
+
export declare function waitForStoryToSettle(page: Page, timeoutMs: number): Promise<void>;
|
|
29
|
+
/** The error a story's render ended in, if any, as one the capture fails with. */
|
|
30
|
+
export declare function throwForRenderErrors(errors: StoryRenderErrors, phase: string | undefined): void;
|
|
31
|
+
//# sourceMappingURL=story-render.d.ts.map
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Storybook render phases after which the story will not change by itself:
|
|
3
|
+
* `finished` from Storybook 8, `completed` in 7, and `errored`. The phases
|
|
4
|
+
* before them include `playing`, while a play function is still running.
|
|
5
|
+
*/
|
|
6
|
+
const SETTLED_PHASES = ['finished', 'completed', 'errored'];
|
|
7
|
+
/**
|
|
8
|
+
* Records the exceptions Storybook reports for the story on this page. Has to
|
|
9
|
+
* be installed before the page loads: the events are emitted once, during
|
|
10
|
+
* the render, on the preview's channel.
|
|
11
|
+
*
|
|
12
|
+
* Storybook 9 and later report a failed play function through this event
|
|
13
|
+
* only - the render still ends `finished` and nothing shows on the page - so
|
|
14
|
+
* listening is the one way to tell it apart from a play that succeeded.
|
|
15
|
+
*/
|
|
16
|
+
export async function watchStoryErrors(page) {
|
|
17
|
+
await page.addInitScript(() => {
|
|
18
|
+
const scope = globalThis;
|
|
19
|
+
const errors = {};
|
|
20
|
+
scope.__storysnapErrors = errors;
|
|
21
|
+
const describe = (error) => (error && typeof error === 'object' && 'message' in error ? String(error.message) : String(error)) ||
|
|
22
|
+
'Unknown error';
|
|
23
|
+
const timer = setInterval(() => {
|
|
24
|
+
const channel = scope.__STORYBOOK_ADDONS_CHANNEL__;
|
|
25
|
+
if (!channel) {
|
|
26
|
+
return;
|
|
27
|
+
}
|
|
28
|
+
clearInterval(timer);
|
|
29
|
+
const emit = channel.emit.bind(channel);
|
|
30
|
+
channel.emit = (event, ...args) => {
|
|
31
|
+
if (event === 'playFunctionThrewException') {
|
|
32
|
+
errors.play ??= describe(args[0]);
|
|
33
|
+
}
|
|
34
|
+
else if (event === 'storyThrewException') {
|
|
35
|
+
errors.render ??= describe(args[0]);
|
|
36
|
+
}
|
|
37
|
+
return emit(event, ...args);
|
|
38
|
+
};
|
|
39
|
+
}, 1);
|
|
40
|
+
});
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Waits until Storybook has finished rendering the story, play function
|
|
44
|
+
* included, so the capture shows its end state rather than whatever the play
|
|
45
|
+
* function had got to. Throws if the play function or the render threw, so
|
|
46
|
+
* the story errors instead of being captured half-done.
|
|
47
|
+
*
|
|
48
|
+
* A page with no Storybook preview - a static stand-in - has nothing to wait
|
|
49
|
+
* for and passes straight through.
|
|
50
|
+
*/
|
|
51
|
+
export async function waitForStoryToSettle(page, timeoutMs) {
|
|
52
|
+
await page.waitForFunction((settled) => {
|
|
53
|
+
const scope = globalThis;
|
|
54
|
+
const preview = scope.__STORYBOOK_PREVIEW__;
|
|
55
|
+
return !preview || settled.includes(preview.currentRender?.phase ?? '');
|
|
56
|
+
}, SETTLED_PHASES, { timeout: timeoutMs, polling: 50 });
|
|
57
|
+
const { errors, phase } = await page.evaluate(() => {
|
|
58
|
+
const scope = globalThis;
|
|
59
|
+
return { errors: scope.__storysnapErrors ?? {}, phase: scope.__STORYBOOK_PREVIEW__?.currentRender?.phase };
|
|
60
|
+
});
|
|
61
|
+
throwForRenderErrors(errors, phase);
|
|
62
|
+
}
|
|
63
|
+
/** The error a story's render ended in, if any, as one the capture fails with. */
|
|
64
|
+
export function throwForRenderErrors(errors, phase) {
|
|
65
|
+
if (errors.play) {
|
|
66
|
+
throw new Error(`Play function failed: ${errors.play}`);
|
|
67
|
+
}
|
|
68
|
+
if (errors.render) {
|
|
69
|
+
throw new Error(`Story failed to render: ${errors.render}`);
|
|
70
|
+
}
|
|
71
|
+
if (phase === 'errored') {
|
|
72
|
+
throw new Error('Story failed to render');
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
//# sourceMappingURL=story-render.js.map
|