@cappa/plugin-storybook 0.1.3 → 0.2.1

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,9 +1,59 @@
1
- import type { Plugin } from "@cappa/core";
1
+ import type {
2
+ Plugin,
3
+ ScreenshotCaptureExtras,
4
+ ScreenshotVariantWithUrl,
5
+ } from "@cappa/core";
2
6
  import { getLogger } from "@cappa/logger";
3
- import chalk from "chalk";
4
- import type { ScreenshotOptionsStorybook } from "../types";
7
+ import type { Page } from "playwright-core";
8
+ import type {
9
+ ScreenshotOptionsStorybook,
10
+ ScreenshotVariantOptionsStorybook,
11
+ StorybookRenderOptions,
12
+ } from "../types";
13
+ import { buildStorybookIframeUrl } from "./storybook-url";
5
14
  import { buildFilename, freezeUI, waitForVisualIdle } from "./util";
6
15
 
16
+ /**
17
+ * Wait for the play function to complete by checking the playAfterEach flag
18
+ * Only waits if the story actually has a play function
19
+ */
20
+ async function waitForPlayFunctionCompletion(page: Page, storyName: string) {
21
+ const logger = getLogger();
22
+
23
+ try {
24
+ // First check if this story has a play function
25
+ const hasPlayFunction = await page.evaluate(
26
+ () => (window as any).__cappa_has_play_function === true,
27
+ );
28
+
29
+ if (!hasPlayFunction) {
30
+ return;
31
+ }
32
+
33
+ logger.debug(
34
+ `Waiting for play function to complete for story: ${storyName}`,
35
+ );
36
+
37
+ await page.waitForFunction(() => (window as any).playAfterEach === true, {
38
+ timeout: 10000,
39
+ });
40
+
41
+ logger.debug(`Play function completed for story: ${storyName}`);
42
+
43
+ // Reset the flags for the next story
44
+ await page.evaluate(() => {
45
+ (window as any).playAfterEach = false;
46
+ (window as any).__cappa_has_play_function = false;
47
+ });
48
+ } catch {
49
+ // Reset flags even on timeout
50
+ await page.evaluate(() => {
51
+ (window as any).playAfterEach = false;
52
+ (window as any).__cappa_has_play_function = false;
53
+ });
54
+ }
55
+ }
56
+
7
57
  export interface StorybookStory {
8
58
  id: string;
9
59
  name: string;
@@ -24,6 +74,7 @@ interface StorybookPluginOptions {
24
74
  defaultViewport?: { width: number; height: number };
25
75
  waitForSelector?: string;
26
76
  waitForTimeout?: number;
77
+ storybook?: StorybookRenderOptions;
27
78
  }
28
79
 
29
80
  /**
@@ -49,8 +100,8 @@ export const cappaPluginStorybook: Plugin<StorybookPluginOptions> = (
49
100
  name: "StorybookPlugin",
50
101
  description:
51
102
  "Takes screenshots of Storybook stories with configurable options",
52
- version: "1.0.0",
53
- execute: async (screenshotTool) => {
103
+
104
+ discover: async () => {
54
105
  if (!options) {
55
106
  throw new Error("Storybook plugin options are required");
56
107
  }
@@ -64,12 +115,12 @@ export const cappaPluginStorybook: Plugin<StorybookPluginOptions> = (
64
115
  storybookUrl,
65
116
  includeStories = [],
66
117
  excludeStories = [],
118
+ storybook: defaultStorybookOptions,
67
119
  } = options;
68
120
 
69
121
  const storiesUrl = `${storybookUrl}/index.json`;
70
122
  logger.debug(`Fetching stories from: ${storiesUrl}`);
71
123
 
72
- // Fetch stories from Storybook
73
124
  const response = await fetch(storiesUrl);
74
125
  if (!response.ok) {
75
126
  throw new Error(
@@ -77,209 +128,262 @@ export const cappaPluginStorybook: Plugin<StorybookPluginOptions> = (
77
128
  );
78
129
  }
79
130
 
80
- try {
81
- const data = (await response.json()) as StorybookStoriesResponse;
82
- const stories = Object.values(data.entries);
131
+ const data = (await response.json()) as StorybookStoriesResponse;
132
+ const stories = Object.values(data.entries);
83
133
 
84
- // Filter stories based on include/exclude patterns
85
- let filteredStories = stories;
134
+ // Filter stories based on include/exclude patterns
135
+ let filteredStories = stories;
86
136
 
87
- if (includeStories.length > 0) {
88
- filteredStories = filteredStories.filter((story) =>
89
- includeStories.some(
137
+ if (includeStories.length > 0) {
138
+ filteredStories = filteredStories.filter((story) =>
139
+ includeStories.some(
140
+ (pattern) =>
141
+ story.title.includes(pattern) || story.name.includes(pattern),
142
+ ),
143
+ );
144
+ }
145
+
146
+ if (excludeStories.length > 0) {
147
+ filteredStories = filteredStories.filter(
148
+ (story) =>
149
+ !excludeStories.some(
90
150
  (pattern) =>
91
151
  story.title.includes(pattern) || story.name.includes(pattern),
92
152
  ),
93
- );
94
- }
153
+ );
154
+ }
95
155
 
96
- if (excludeStories.length > 0) {
97
- filteredStories = filteredStories.filter(
98
- (story) =>
99
- !excludeStories.some(
100
- (pattern) =>
101
- story.title.includes(pattern) || story.name.includes(pattern),
102
- ),
156
+ filteredStories = filteredStories.filter(
157
+ (story) => story.type === "story",
158
+ );
159
+
160
+ logger.start(`Found ${filteredStories.length} stories to screenshot...`);
161
+
162
+ // Return tasks
163
+ return filteredStories.map((story) => ({
164
+ id: story.id,
165
+ url: buildStorybookIframeUrl({
166
+ baseUrl: storybookUrl,
167
+ storyId: story.id,
168
+ viewMode: defaultStorybookOptions?.viewMode,
169
+ args: defaultStorybookOptions?.args,
170
+ globals: defaultStorybookOptions?.globals,
171
+ query: defaultStorybookOptions?.query,
172
+ fullscreen: defaultStorybookOptions?.fullscreen,
173
+ singleStory: defaultStorybookOptions?.singleStory,
174
+ }),
175
+ data: {
176
+ story,
177
+ },
178
+ }));
179
+ },
180
+
181
+ initPage: async () => {
182
+ return {
183
+ latchMap: new Map<
184
+ string,
185
+ {
186
+ p: Promise<ScreenshotOptionsStorybook>;
187
+ resolve: (v: ScreenshotOptionsStorybook) => void;
188
+ }
189
+ >(),
190
+ };
191
+ },
192
+
193
+ // Phase 2: Execute single story
194
+ execute: async (task, page, screenshotTool, context) => {
195
+ const { url, data } = task;
196
+ const { story } = data;
197
+ const logger = getLogger();
198
+ const { storybook: defaultStorybookOptions } = options || {};
199
+
200
+ try {
201
+ // Setup exposed function for this page
202
+ const currentLatch = createLatch<ScreenshotOptionsStorybook>();
203
+ context.latchMap.set(story.id, currentLatch);
204
+
205
+ if (
206
+ await page.evaluate(() => {
207
+ return (window as any).__cappa_parameters === undefined;
208
+ })
209
+ ) {
210
+ await page.exposeFunction(
211
+ "__cappa_parameters",
212
+ async (id: string, payload: ScreenshotOptionsStorybook) => {
213
+ context.latchMap.get(id)?.resolve?.(payload);
214
+ },
103
215
  );
104
216
  }
105
217
 
106
- // Filter docs etc
107
- filteredStories = filteredStories.filter(
108
- (story) => story.type === "story",
109
- );
218
+ page.on("console", (message) => {
219
+ logger.debug("console", message.text());
220
+ });
221
+ page.on("pageerror", (error) => {
222
+ logger.debug("pageerror", error);
223
+ });
110
224
 
111
- logger.start(
112
- `Found ${filteredStories.length} stories to screenshot...`,
113
- );
225
+ // Navigate to story
226
+ await page.goto(url);
227
+
228
+ // Get story parameters
229
+ const storyParameters = await context.latchMap.get(story.id)?.p;
230
+ context.latchMap.delete(story.id);
231
+
232
+ const variantParameters = storyParameters?.variants ?? [];
233
+
234
+ if (storyParameters?.skip) {
235
+ logger.warn(`Skipping story ${story.title} - ${story.name}`);
236
+ return {
237
+ storyId: story.id,
238
+ storyName: `${story.title} - ${story.name}`,
239
+ skipped: true,
240
+ };
241
+ }
242
+
243
+ if (storyParameters && Object.keys(storyParameters).length > 0) {
244
+ logger.debug("Taking screenshot with options", storyParameters);
245
+ }
114
246
 
115
- const results: Array<{
116
- storyId: string;
117
- storyName: string;
118
- filepath?: string;
119
- success?: boolean;
120
- error?: string;
121
- skipped?: boolean;
122
- }> = [];
247
+ const resolvedViewport =
248
+ storyParameters?.viewport ?? screenshotTool.viewport;
123
249
 
124
- await screenshotTool.init();
250
+ await page.setViewportSize(resolvedViewport);
125
251
 
126
- let currentLatch = createLatch<ScreenshotOptionsStorybook>();
252
+ await freezeUI(page);
253
+ await waitForVisualIdle(page);
127
254
 
128
- await screenshotTool.page?.exposeFunction(
129
- "__cappa_parameters",
130
- async (payload: ScreenshotOptionsStorybook) => {
131
- currentLatch.resolve(payload);
132
- },
255
+ // Wait for play function to complete if it exists
256
+ await waitForPlayFunctionCompletion(
257
+ page,
258
+ `${story.title} - ${story.name}`,
133
259
  );
134
260
 
135
- // Take screenshots of each story
136
- for (const story of filteredStories) {
137
- try {
138
- const storyUrl = `${storybookUrl}/iframe.html?id=${story.id}&viewMode=story`;
139
-
140
- const page = screenshotTool.page;
141
- if (!page) {
142
- throw new Error("Page not initialized");
143
- }
144
-
145
- page.on("console", (message) => {
146
- logger.debug("console", message.text());
147
- });
148
- page.on("pageerror", (error) => {
149
- logger.debug("pageerror", error);
150
- });
151
-
152
- await page.goto(storyUrl);
153
-
154
- const options = await currentLatch.p;
155
- currentLatch = createLatch<ScreenshotOptionsStorybook>();
156
-
157
- if (options.skip) {
158
- logger.warn(`Skipping story ${story.title} - ${story.name}`);
159
- results.push({
160
- storyId: story.id,
161
- storyName: `${story.title} - ${story.name}`,
162
- skipped: true,
163
- });
164
- continue;
165
- }
166
-
167
- if (options && Object.keys(options).length > 0) {
168
- logger.debug("Taking screenshot with options", options);
169
- }
170
-
171
- await freezeUI(page);
172
- await waitForVisualIdle(page);
173
-
174
- if (options.delay) {
175
- await page.waitForTimeout(options.delay);
176
- }
177
-
178
- // Take screenshot with story-specific filename
179
- const filename = buildFilename(story);
180
- const expectedExists = screenshotTool.hasExpectedImage(filename);
181
-
182
- let actualFilepath: string | undefined;
183
- if (expectedExists) {
184
- const { screenshotPath, comparisonResult } =
185
- await screenshotTool.takeScreenshotWithComparison(
186
- page,
187
- filename,
188
- screenshotTool.getExpectedImageBuffer(filename),
189
- {
190
- fullPage: options.fullPage,
191
- mask: options.mask?.map((selector) =>
192
- page.locator(selector),
193
- ),
194
- omitBackground: options.omitBackground,
195
- saveDiffImage: true,
196
- },
197
- );
198
-
199
- actualFilepath = screenshotPath;
200
-
201
- results.push({
202
- storyId: story.id,
203
- storyName: `${story.title} - ${story.name}`,
204
- filepath: actualFilepath,
205
- success: comparisonResult.passed,
206
- });
207
- } else {
208
- logger.info(
209
- `Expected image not found for story ${story.title} - ${story.name}, taking screenshot`,
210
- );
211
- actualFilepath = await screenshotTool.takeScreenshot(
212
- page,
213
- filename,
214
- {
215
- fullPage: options.fullPage,
216
- mask: options.mask?.map((selector) => page.locator(selector)),
217
- omitBackground: options.omitBackground,
218
- },
219
- );
220
-
221
- results.push({
222
- storyId: story.id,
223
- storyName: `${story.title} - ${story.name}`,
224
- filepath: actualFilepath,
225
- success: true,
226
- });
227
- }
228
- } catch (error) {
229
- logger.error(
230
- `Error taking screenshot of story ${story.title} - ${story.name}:`,
231
- (error as Error).message,
232
- );
233
- results.push({
234
- storyId: story.id,
235
- storyName: `${story.title} - ${story.name}`,
236
- error: (error as Error)?.message ?? "Unknown error",
237
- });
238
- }
239
- }
261
+ const toLocatorMask = (mask?: string[]) =>
262
+ mask?.map((selector) => page.locator(selector));
240
263
 
241
- // Print error report if there are any errors
242
- if (results.some((r) => r.error)) {
243
- logger.error(
244
- `Error report: \n${results
245
- .filter((r) => r.error)
246
- .map((r) => `${r.storyName}: ${r.error}`)
247
- .join("\n")}`,
264
+ const filename = buildFilename(story);
265
+ const expectedExists =
266
+ screenshotTool.filesystem.hasExpectedFile(filename);
267
+ if (!expectedExists) {
268
+ logger.info(
269
+ `Expected image not found for story ${story.title} - ${story.name}, taking screenshot`,
248
270
  );
249
271
  }
250
272
 
251
- // Print skipped stories if there are any
252
- if (results.some((r) => r.skipped)) {
253
- logger.warn(
254
- `Skipped stories: \n${results
255
- .filter((r) => r.skipped)
256
- .map((r) => `${r.storyName}`)
257
- .join("\n")}`,
273
+ // Convert variants to the new format with URLs
274
+ const variantsWithUrls: ScreenshotVariantWithUrl[] =
275
+ variantParameters.map(
276
+ (variant: ScreenshotVariantOptionsStorybook) => {
277
+ const variantFilename =
278
+ variant.filename ||
279
+ screenshotTool.getVariantFilename(filename, {
280
+ id: variant.id,
281
+ label: variant.label,
282
+ filename: variant.filename,
283
+ });
284
+
285
+ // Merge variant args with default storybook options
286
+ const mergedArgs = {
287
+ ...defaultStorybookOptions?.args,
288
+ ...variant.options?.args,
289
+ };
290
+
291
+ return {
292
+ id: variant.id,
293
+ label: variant.label,
294
+ filename: variantFilename,
295
+ url: buildStorybookIframeUrl({
296
+ baseUrl: options?.storybookUrl || "",
297
+ storyId: story.id,
298
+ viewMode: defaultStorybookOptions?.viewMode,
299
+ args: mergedArgs,
300
+ globals: defaultStorybookOptions?.globals,
301
+ query: defaultStorybookOptions?.query,
302
+ fullscreen: defaultStorybookOptions?.fullscreen,
303
+ singleStory: defaultStorybookOptions?.singleStory,
304
+ }),
305
+ options: variant.options
306
+ ? {
307
+ ...variant.options,
308
+ mask: toLocatorMask(variant.options.mask),
309
+ }
310
+ : undefined,
311
+ };
312
+ },
258
313
  );
314
+
315
+ const baseOptions = {
316
+ fullPage: storyParameters?.fullPage,
317
+ delay: storyParameters?.delay,
318
+ omitBackground: storyParameters?.omitBackground,
319
+ skip: storyParameters?.skip,
320
+ viewport: storyParameters?.viewport ?? screenshotTool.viewport,
321
+ mask: toLocatorMask(storyParameters?.mask),
322
+ };
323
+
324
+ const variantFilenameMap = new Map<string, string>();
325
+ for (const variant of variantsWithUrls) {
326
+ const variantFilename = variant.filename;
327
+ if (!variantFilename) continue; // Skip if no filename
328
+
329
+ variantFilenameMap.set(variant.id, variantFilename);
330
+
331
+ if (!screenshotTool.filesystem.hasExpectedFile(variantFilename)) {
332
+ logger.info(
333
+ `Expected image not found for variant ${story.title} - ${story.name} [${variant.label ?? variant.id}], taking screenshot`,
334
+ );
335
+ }
259
336
  }
260
337
 
261
- const skipped = results.filter((r) => r.skipped);
262
- const failed = results.filter(
263
- (r) => r.error || (!r.skipped && !r.success),
338
+ const variantExtrasEntries = variantsWithUrls.map(
339
+ (variant) =>
340
+ [
341
+ variant.id,
342
+ {
343
+ saveDiffImage: true,
344
+ diffImageFilename: variant.filename,
345
+ },
346
+ ] as const,
264
347
  );
265
- const successful = results.filter((r) => r.success);
266
-
267
- const output = [
268
- `${chalk.yellow("Skipped stories:")} ${skipped.length}`,
269
- `${chalk.red("Failed stories:")} ${failed.length}`,
270
- `${chalk.green("Successful stories:")} ${successful.length}`,
271
- `${chalk.blue("Total stories:")} ${results.length}`,
272
- ];
273
-
274
- logger.box({
275
- title: "Storybook Report",
276
- message: output.join("\n"),
277
- });
278
348
 
279
- return results;
349
+ const captureExtras: ScreenshotCaptureExtras = {
350
+ saveDiffImage: true,
351
+ diffImageFilename: filename,
352
+ variants: variantExtrasEntries.length
353
+ ? Object.fromEntries(variantExtrasEntries)
354
+ : undefined,
355
+ };
356
+
357
+ const captureResult = await screenshotTool.captureWithVariants(
358
+ page,
359
+ filename,
360
+ url,
361
+ baseOptions,
362
+ variantsWithUrls,
363
+ captureExtras,
364
+ );
365
+
366
+ return {
367
+ storyId: story.id,
368
+ storyName: `${story.title} - ${story.name}`,
369
+ filepath: captureResult.base.filepath,
370
+ success: captureResult.base.skipped
371
+ ? undefined
372
+ : captureResult.base.comparisonResult
373
+ ? captureResult.base.comparisonResult.passed
374
+ : Boolean(captureResult.base.filepath),
375
+ skipped: captureResult.base.skipped,
376
+ };
280
377
  } catch (error) {
281
- logger.error("Error in Storybook plugin:", (error as Error).message);
282
- throw error;
378
+ logger.error(
379
+ `Error taking screenshot of story ${story.title} - ${story.name}:`,
380
+ (error as Error).message,
381
+ );
382
+ return {
383
+ storyId: story.id,
384
+ storyName: `${story.title} - ${story.name}`,
385
+ error: (error as Error)?.message ?? "Unknown error",
386
+ };
283
387
  }
284
388
  },
285
389
  };
@@ -0,0 +1,43 @@
1
+ import { describe, expect, it } from "vitest";
2
+
3
+ import { buildStorybookIframeUrl } from "./storybook-url";
4
+
5
+ describe("buildStorybookIframeUrl", () => {
6
+ it("builds a default url", () => {
7
+ expect(
8
+ buildStorybookIframeUrl({
9
+ baseUrl: "https://storybook.example.com",
10
+ storyId: "button--primary",
11
+ }),
12
+ ).toBe(
13
+ "https://storybook.example.com/iframe.html?id=button--primary&viewMode=story&full=1&singleStory=true",
14
+ );
15
+ });
16
+
17
+ it("includes args, globals and query parameters", () => {
18
+ expect(
19
+ buildStorybookIframeUrl({
20
+ baseUrl: "https://storybook.example.com",
21
+ storyId: "button--primary",
22
+ args: { label: "Click Me", count: 2 },
23
+ globals: { locale: "en", darkMode: true },
24
+ query: { nav: false },
25
+ }),
26
+ ).toBe(
27
+ "https://storybook.example.com/iframe.html?id=button--primary&viewMode=story&args=label%3AClick%2520Me%3Bcount%3A2&globals=locale%3Aen%3BdarkMode%3Atrue&full=1&singleStory=true&nav=false",
28
+ );
29
+ });
30
+
31
+ it("omits fullscreen and single story flags when disabled", () => {
32
+ expect(
33
+ buildStorybookIframeUrl({
34
+ baseUrl: "https://storybook.example.com",
35
+ storyId: "button--primary",
36
+ fullscreen: false,
37
+ singleStory: false,
38
+ }),
39
+ ).toBe(
40
+ "https://storybook.example.com/iframe.html?id=button--primary&viewMode=story",
41
+ );
42
+ });
43
+ });
@@ -0,0 +1,55 @@
1
+ import type { StorybookRenderOptions } from "../types";
2
+
3
+ type SBUrlOptions = StorybookRenderOptions & {
4
+ baseUrl: string;
5
+ storyId: string;
6
+ };
7
+
8
+ function encodePairs(obj: Record<string, unknown> | undefined) {
9
+ if (!obj || !Object.keys(obj).length) return "";
10
+ return Object.entries(obj)
11
+ .filter(([, v]) => v !== undefined)
12
+ .map(([k, v]) => {
13
+ const val =
14
+ typeof v === "string"
15
+ ? encodeURIComponent(v)
16
+ : typeof v === "number" || typeof v === "boolean"
17
+ ? String(v)
18
+ : encodeURIComponent(JSON.stringify(v));
19
+ return `${encodeURIComponent(k)}:${val}`;
20
+ })
21
+ .join(";");
22
+ }
23
+
24
+ export function buildStorybookIframeUrl({
25
+ baseUrl,
26
+ storyId,
27
+ viewMode = "story",
28
+ args,
29
+ globals,
30
+ query,
31
+ fullscreen = true,
32
+ singleStory = true,
33
+ }: SBUrlOptions) {
34
+ const u = new URL("/iframe.html", baseUrl);
35
+ u.searchParams.set("id", storyId);
36
+ u.searchParams.set("viewMode", viewMode);
37
+
38
+ const argPairs = encodePairs(args);
39
+ if (argPairs) u.searchParams.set("args", argPairs);
40
+
41
+ const globalPairs = encodePairs(globals);
42
+ if (globalPairs) u.searchParams.set("globals", globalPairs);
43
+
44
+ if (fullscreen) u.searchParams.set("full", "1");
45
+ if (singleStory) u.searchParams.set("singleStory", "true");
46
+
47
+ if (query) {
48
+ for (const [k, v] of Object.entries(query)) {
49
+ if (v === undefined) continue;
50
+ u.searchParams.set(k, String(v));
51
+ }
52
+ }
53
+
54
+ return u.toString();
55
+ }
package/src/index.ts CHANGED
@@ -1,3 +1,5 @@
1
1
  export { cappaPluginStorybook } from "./cappa/plugin";
2
2
 
3
3
  export const previewAnnotations = [require.resolve("./preview.mjs")];
4
+
5
+ export type { ScreenshotOptionsStorybook as CappaStorybookOptions } from "./types";
@@ -8,15 +8,17 @@ export const withCappaDecorator = makeDecorator({
8
8
  wrapper: (getStory, context, { parameters }) => {
9
9
  (window as any).__cappa_screenshot = true;
10
10
 
11
- const _hasPlayFunction = context.playFunction != null;
11
+ // Set indicator if this story has a play function
12
+ if (context.playFunction != null) {
13
+ (window as any).__cappa_has_play_function = true;
14
+ }
12
15
 
13
16
  queueMicrotask(async () => {
14
17
  try {
15
18
  const cappaParameters = await waitForExposed("__cappa_parameters");
16
-
17
- cappaParameters(parameters ?? {});
19
+ cappaParameters(context.id, parameters ?? {});
18
20
  } catch (error) {
19
- console.error(error);
21
+ console.error("Cappa decorator error:", error);
20
22
  }
21
23
  });
22
24
 
@@ -5,5 +5,6 @@ export const decorators = [withCappaDecorator];
5
5
  export const parameters = {};
6
6
 
7
7
  export const afterEach = () => {
8
+ // Set the flag to indicate that the play function has completed
8
9
  (window as any).playAfterEach = true;
9
10
  };
@@ -7,7 +7,7 @@
7
7
  export const waitForExposed = (
8
8
  name: string,
9
9
  timeoutMs = 5000,
10
- ): Promise<(parameters: any) => void> => {
10
+ ): Promise<(id: string, parameters: any) => void> => {
11
11
  return new Promise((resolve, reject) => {
12
12
  const start = performance.now();
13
13