@storysnap/cli 2.1.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.
@@ -1,15 +1,71 @@
1
- import type { Story, Screenshot, StorySnapConfig, Browser } from '@storysnap/shared';
1
+ import { type Page } from 'playwright';
2
+ import type { Story, Screenshot, StorySnapConfig, Browser, Viewport } from '@storysnap/shared';
2
3
  export declare class ScreenshotEngine {
3
4
  private browsers;
5
+ /** Recorded in each browser's screenshots, for comparing baselines across machines. */
6
+ private environments;
4
7
  private config;
5
8
  private baseUrl;
6
9
  constructor(config: StorySnapConfig);
7
10
  initialize(): Promise<void>;
8
11
  close(): Promise<void>;
9
- captureStory(story: Story, browserName: Browser): Promise<Screenshot>;
12
+ /**
13
+ * Captures a story at each of its viewports, trying again up to
14
+ * `captureRetries` times when the capture throws. A story that needed a
15
+ * retry is marked flaky at every viewport.
16
+ */
17
+ captureStoryWithRetries(story: Story, browserName: Browser): Promise<Screenshot[]>;
18
+ /**
19
+ * Captures a story once per viewport. The story's parameters, which can
20
+ * change the viewports, are only readable once it has rendered, so it is
21
+ * first loaded at the first configured viewport; every other viewport gets
22
+ * a page of its own, loaded at that size, rather than a resized one - a
23
+ * component that measures the window once on mount must look the way it
24
+ * would if opened at that size.
25
+ */
26
+ captureStory(story: Story, browserName: Browser): Promise<Screenshot[]>;
27
+ /**
28
+ * Opens the story at a viewport, in a mode, and waits for Storybook to
29
+ * finish rendering it - play function included - and for its root to be
30
+ * visible. The mode's globals go in the URL, so the story renders - and its
31
+ * play function runs - in the mode from the start.
32
+ */
33
+ private openStory;
34
+ /** Waits for a rendered story to settle as its parameters ask, then captures it. */
35
+ private shoot;
36
+ /** A screenshot with no image yet: the shape failures and skips are reported in. */
37
+ private blank;
38
+ private get freeze();
10
39
  captureStories(stories: Story[], onProgress?: (completed: number, total: number, story: Story, browser: Browser) => void): Promise<Map<string, Screenshot>>;
11
- private waitForStability;
12
40
  }
41
+ /** Retries for a capture that throws: a timeout, a crashed page. */
42
+ export declare const DEFAULT_CAPTURE_RETRIES = 1;
43
+ /** How long to wait for images to load and decode before capturing anyway. */
44
+ export declare const ASSET_TIMEOUT_MS = 10000;
45
+ /**
46
+ * Waits for web fonts and for the images on the page to load and decode, so a
47
+ * capture never shows fallback glyphs or an empty image box. Lazy images
48
+ * outside the viewport are skipped, and an image that never loads holds the
49
+ * capture up for at most `timeoutMs`.
50
+ */
51
+ export declare function waitForAssets(page: Page, timeoutMs?: number): Promise<void>;
52
+ export interface StabilityOptions {
53
+ /** Screenshots to take at most before settling for the last one. */
54
+ maxAttempts?: number;
55
+ /** Pause between two screenshots. */
56
+ intervalMs?: number;
57
+ }
58
+ /**
59
+ * Takes screenshots until two in a row are byte-identical and returns that
60
+ * one; if the page never settles, returns the last one taken with `stable`
61
+ * false. With animations frozen most pages match on the second screenshot, so
62
+ * this is usually quicker than a fixed settle delay while still catching late
63
+ * layout shifts.
64
+ */
65
+ export declare function captureWhenStable(take: () => Promise<Buffer>, { maxAttempts, intervalMs }?: StabilityOptions): Promise<{
66
+ buffer: Buffer;
67
+ stable: boolean;
68
+ }>;
13
69
  /**
14
70
  * The first line of a capture error. Playwright appends a multi-line call log
15
71
  * to its messages, which buries the actual reason when printed per story.
@@ -20,10 +76,41 @@ export declare const IGNORE_ATTRIBUTE = "data-storysnap-ignore";
20
76
  export declare const DEFAULT_IGNORE_COLOR = "#808080";
21
77
  /** The built-in attribute plus any selectors the config adds, as one selector list. */
22
78
  export declare function getIgnoreSelector(extraSelectors?: readonly string[]): string;
23
- export declare function getScreenshotKey(storyId: string, browser: Browser): string;
79
+ /**
80
+ * The captures of each story in each browser - one per viewport, or a single
81
+ * failed one - keyed `storyId::browser`, in capture order.
82
+ */
83
+ export declare function groupCaptures(screenshots: Map<string, Screenshot>): Map<string, Screenshot[]>;
84
+ /** ` @ 375x667` for a capture at a viewport other than the configured one; empty otherwise. */
85
+ export declare function viewportLabel(viewport: Viewport, configured: Viewport): string;
86
+ /** ` [dark] @ 375x667`: what tells a story's captures apart, after its name. */
87
+ export declare function captureLabel(capture: {
88
+ viewport: Viewport;
89
+ mode?: string;
90
+ }, configured: Viewport): string;
91
+ /** Identifies one capture: a story, in a browser, at a viewport, in a mode. */
92
+ export declare function getScreenshotKey(screenshot: {
93
+ storyId: string;
94
+ browser: Browser;
95
+ width: number;
96
+ height: number;
97
+ mode?: string;
98
+ }): string;
24
99
  export declare function parseScreenshotKey(key: string): {
25
100
  storyId: string;
26
101
  browser: Browser;
102
+ viewport: Viewport;
103
+ mode: string;
104
+ };
105
+ /**
106
+ * Takes the stories their parameters disabled out of a capture: out of the
107
+ * story list, so totals and "not captured" counts leave them alone, and out
108
+ * of the screenshots, so nothing downstream mistakes them for failures.
109
+ * Parameters are the same in every browser, so one skip drops the story.
110
+ */
111
+ export declare function dropSkipped(stories: Story[], screenshots: Map<string, Screenshot>): {
112
+ stories: Story[];
113
+ skipped: Story[];
27
114
  };
28
115
  export declare function captureScreenshots(config: StorySnapConfig, stories: Story[], onProgress?: (completed: number, total: number, story: Story, browser: Browser) => void): Promise<Map<string, Screenshot>>;
29
116
  //# sourceMappingURL=screenshot.d.ts.map
@@ -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: this.config.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
- const url = getStoryUrl(this.baseUrl, story.id);
127
+ await watchStoryErrors(page);
128
+ const url = getStoryUrl(this.baseUrl, story.id) + (globals ? `&globals=${globals}` : '');
46
129
  await page.goto(url, { waitUntil: 'networkidle' });
47
- // Wait for the story root element to be visible
48
- const selector = this.config.waitForSelector ?? '#storybook-root';
49
- await page.waitForSelector(selector, {
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
- // Additional wait for any animations or lazy loading
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
- finally {
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 delay - so several pages run at once. Each still gets a fresh
82
- // page, keeping stories as isolated from one another as before.
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 = await this.captureStory(story, browserName);
87
- screenshots.set(screenshotKey, screenshot);
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
- screenshots.set(screenshotKey, {
93
- storyId: story.id,
94
- browser: browserName,
95
- buffer: Buffer.alloc(0),
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
- async waitForStability(page) {
109
- // Wait for network to be idle
110
- await page.waitForLoadState('networkidle');
111
- // Wait a short time for any CSS animations to complete and render to stabilize
112
- await page.waitForTimeout(200);
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
- export function getScreenshotKey(storyId, browser) {
131
- return `${storyId}::${browser}`;
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
- return { storyId, browser: browser };
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