@cappa/plugin-storybook 0.1.3 → 0.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,7 +1,16 @@
1
- import type { Plugin } from "@cappa/core";
1
+ import type {
2
+ Plugin,
3
+ ScreenshotCaptureExtras,
4
+ ScreenshotOptions,
5
+ ScreenshotVariant,
6
+ } from "@cappa/core";
2
7
  import { getLogger } from "@cappa/logger";
3
- import chalk from "chalk";
4
- import type { ScreenshotOptionsStorybook } from "../types";
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
 
7
16
  export interface StorybookStory {
@@ -24,6 +33,7 @@ interface StorybookPluginOptions {
24
33
  defaultViewport?: { width: number; height: number };
25
34
  waitForSelector?: string;
26
35
  waitForTimeout?: number;
36
+ storybook?: StorybookRenderOptions;
27
37
  }
28
38
 
29
39
  /**
@@ -49,8 +59,8 @@ export const cappaPluginStorybook: Plugin<StorybookPluginOptions> = (
49
59
  name: "StorybookPlugin",
50
60
  description:
51
61
  "Takes screenshots of Storybook stories with configurable options",
52
- version: "1.0.0",
53
- execute: async (screenshotTool) => {
62
+
63
+ discover: async () => {
54
64
  if (!options) {
55
65
  throw new Error("Storybook plugin options are required");
56
66
  }
@@ -64,12 +74,12 @@ export const cappaPluginStorybook: Plugin<StorybookPluginOptions> = (
64
74
  storybookUrl,
65
75
  includeStories = [],
66
76
  excludeStories = [],
77
+ storybook: defaultStorybookOptions,
67
78
  } = options;
68
79
 
69
80
  const storiesUrl = `${storybookUrl}/index.json`;
70
81
  logger.debug(`Fetching stories from: ${storiesUrl}`);
71
82
 
72
- // Fetch stories from Storybook
73
83
  const response = await fetch(storiesUrl);
74
84
  if (!response.ok) {
75
85
  throw new Error(
@@ -77,209 +87,228 @@ export const cappaPluginStorybook: Plugin<StorybookPluginOptions> = (
77
87
  );
78
88
  }
79
89
 
80
- try {
81
- const data = (await response.json()) as StorybookStoriesResponse;
82
- const stories = Object.values(data.entries);
90
+ const data = (await response.json()) as StorybookStoriesResponse;
91
+ const stories = Object.values(data.entries);
92
+
93
+ // Filter stories based on include/exclude patterns
94
+ let filteredStories = stories;
83
95
 
84
- // Filter stories based on include/exclude patterns
85
- let filteredStories = stories;
96
+ if (includeStories.length > 0) {
97
+ filteredStories = filteredStories.filter((story) =>
98
+ includeStories.some(
99
+ (pattern) =>
100
+ story.title.includes(pattern) || story.name.includes(pattern),
101
+ ),
102
+ );
103
+ }
86
104
 
87
- if (includeStories.length > 0) {
88
- filteredStories = filteredStories.filter((story) =>
89
- includeStories.some(
105
+ if (excludeStories.length > 0) {
106
+ filteredStories = filteredStories.filter(
107
+ (story) =>
108
+ !excludeStories.some(
90
109
  (pattern) =>
91
110
  story.title.includes(pattern) || story.name.includes(pattern),
92
111
  ),
93
- );
94
- }
112
+ );
113
+ }
95
114
 
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
- ),
115
+ filteredStories = filteredStories.filter(
116
+ (story) => story.type === "story",
117
+ );
118
+
119
+ logger.start(`Found ${filteredStories.length} stories to screenshot...`);
120
+
121
+ // Return tasks
122
+ return filteredStories.map((story) => ({
123
+ id: story.id,
124
+ url: buildStorybookIframeUrl({
125
+ baseUrl: storybookUrl,
126
+ storyId: story.id,
127
+ viewMode: defaultStorybookOptions?.viewMode,
128
+ args: defaultStorybookOptions?.args,
129
+ globals: defaultStorybookOptions?.globals,
130
+ query: defaultStorybookOptions?.query,
131
+ fullscreen: defaultStorybookOptions?.fullscreen,
132
+ singleStory: defaultStorybookOptions?.singleStory,
133
+ }),
134
+ data: {
135
+ story,
136
+ },
137
+ }));
138
+ },
139
+
140
+ initPage: async () => {
141
+ return {
142
+ latchMap: new Map<
143
+ string,
144
+ {
145
+ p: Promise<ScreenshotOptionsStorybook>;
146
+ resolve: (v: ScreenshotOptionsStorybook) => void;
147
+ }
148
+ >(),
149
+ };
150
+ },
151
+
152
+ // Phase 2: Execute single story
153
+ execute: async (task, page, screenshotTool, context) => {
154
+ const { url, data } = task;
155
+ const { story } = data;
156
+ const logger = getLogger();
157
+
158
+ try {
159
+ // Setup exposed function for this page
160
+ const currentLatch = createLatch<ScreenshotOptionsStorybook>();
161
+ context.latchMap.set(story.id, currentLatch);
162
+
163
+ if (
164
+ await page.evaluate(() => {
165
+ return (window as any).__cappa_parameters === undefined;
166
+ })
167
+ ) {
168
+ await page.exposeFunction(
169
+ "__cappa_parameters",
170
+ async (id: string, payload: ScreenshotOptionsStorybook) => {
171
+ context.latchMap.get(id)?.resolve?.(payload);
172
+ },
103
173
  );
104
174
  }
105
175
 
106
- // Filter docs etc
107
- filteredStories = filteredStories.filter(
108
- (story) => story.type === "story",
109
- );
110
-
111
- logger.start(
112
- `Found ${filteredStories.length} stories to screenshot...`,
113
- );
176
+ page.on("console", (message) => {
177
+ logger.debug("console", message.text());
178
+ });
179
+ page.on("pageerror", (error) => {
180
+ logger.debug("pageerror", error);
181
+ });
114
182
 
115
- const results: Array<{
116
- storyId: string;
117
- storyName: string;
118
- filepath?: string;
119
- success?: boolean;
120
- error?: string;
121
- skipped?: boolean;
122
- }> = [];
183
+ // Navigate to story
184
+ await page.goto(url);
123
185
 
124
- await screenshotTool.init();
186
+ // Get story parameters
187
+ const storyParameters = await context.latchMap.get(story.id)?.p;
188
+ context.latchMap.delete(story.id);
125
189
 
126
- let currentLatch = createLatch<ScreenshotOptionsStorybook>();
190
+ const variantParameters = storyParameters?.variants ?? [];
127
191
 
128
- await screenshotTool.page?.exposeFunction(
129
- "__cappa_parameters",
130
- async (payload: ScreenshotOptionsStorybook) => {
131
- currentLatch.resolve(payload);
132
- },
133
- );
192
+ if (storyParameters?.skip) {
193
+ logger.warn(`Skipping story ${story.title} - ${story.name}`);
194
+ return {
195
+ storyId: story.id,
196
+ storyName: `${story.title} - ${story.name}`,
197
+ skipped: true,
198
+ };
199
+ }
134
200
 
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
- }
201
+ if (storyParameters && Object.keys(storyParameters).length > 0) {
202
+ logger.debug("Taking screenshot with options", storyParameters);
239
203
  }
240
204
 
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")}`,
205
+ const resolvedViewport =
206
+ storyParameters?.viewport ?? screenshotTool.viewport;
207
+
208
+ await page.setViewportSize(resolvedViewport);
209
+
210
+ await freezeUI(page);
211
+ await waitForVisualIdle(page);
212
+
213
+ const toLocatorMask = (mask?: string[]) =>
214
+ mask?.map((selector) => page.locator(selector));
215
+
216
+ const screenshotVariants: ScreenshotVariant[] = variantParameters.map(
217
+ (variant: ScreenshotVariantOptionsStorybook) => ({
218
+ id: variant.id,
219
+ label: variant.label,
220
+ filename: variant.filename,
221
+ options: variant.options
222
+ ? {
223
+ ...variant.options,
224
+ mask: toLocatorMask(variant.options.mask),
225
+ }
226
+ : undefined,
227
+ }),
228
+ );
229
+
230
+ const screenshotOptions: ScreenshotOptions = {
231
+ fullPage: storyParameters?.fullPage,
232
+ delay: storyParameters?.delay,
233
+ omitBackground: storyParameters?.omitBackground,
234
+ skip: storyParameters?.skip,
235
+ viewport: storyParameters?.viewport ?? screenshotTool.viewport,
236
+ mask: toLocatorMask(storyParameters?.mask),
237
+ variants: screenshotVariants.length ? screenshotVariants : undefined,
238
+ };
239
+
240
+ const filename = buildFilename(story);
241
+ const expectedExists =
242
+ screenshotTool.filesystem.hasExpectedFile(filename);
243
+ if (!expectedExists) {
244
+ logger.info(
245
+ `Expected image not found for story ${story.title} - ${story.name}, taking screenshot`,
248
246
  );
249
247
  }
250
248
 
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")}`,
249
+ const variantFilenameMap = new Map<string, string>();
250
+ for (const variant of screenshotVariants) {
251
+ const variantFilename = screenshotTool.getVariantFilename(
252
+ filename,
253
+ variant,
258
254
  );
255
+ variantFilenameMap.set(variant.id, variantFilename);
256
+
257
+ if (!screenshotTool.filesystem.hasExpectedFile(variantFilename)) {
258
+ logger.info(
259
+ `Expected image not found for variant ${story.title} - ${story.name} [${variant.label ?? variant.id}], taking screenshot`,
260
+ );
261
+ }
259
262
  }
260
263
 
261
- const skipped = results.filter((r) => r.skipped);
262
- const failed = results.filter(
263
- (r) => r.error || (!r.skipped && !r.success),
264
+ const variantExtrasEntries = screenshotVariants.map(
265
+ (variant) =>
266
+ [
267
+ variant.id,
268
+ {
269
+ saveDiffImage: true,
270
+ diffImageFilename:
271
+ variantFilenameMap.get(variant.id) ?? filename,
272
+ },
273
+ ] as const,
274
+ );
275
+
276
+ const captureExtras: ScreenshotCaptureExtras = {
277
+ saveDiffImage: true,
278
+ diffImageFilename: filename,
279
+ variants: variantExtrasEntries.length
280
+ ? Object.fromEntries(variantExtrasEntries)
281
+ : undefined,
282
+ };
283
+
284
+ const captureResult = await screenshotTool.capture(
285
+ page,
286
+ filename,
287
+ screenshotOptions,
288
+ captureExtras,
264
289
  );
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
290
 
279
- return results;
291
+ return {
292
+ storyId: story.id,
293
+ storyName: `${story.title} - ${story.name}`,
294
+ filepath: captureResult.base.filepath,
295
+ success: captureResult.base.skipped
296
+ ? undefined
297
+ : captureResult.base.comparisonResult
298
+ ? captureResult.base.comparisonResult.passed
299
+ : Boolean(captureResult.base.filepath),
300
+ skipped: captureResult.base.skipped,
301
+ };
280
302
  } catch (error) {
281
- logger.error("Error in Storybook plugin:", (error as Error).message);
282
- throw error;
303
+ logger.error(
304
+ `Error taking screenshot of story ${story.title} - ${story.name}:`,
305
+ (error as Error).message,
306
+ );
307
+ return {
308
+ storyId: story.id,
309
+ storyName: `${story.title} - ${story.name}`,
310
+ error: (error as Error)?.message ?? "Unknown error",
311
+ };
283
312
  }
284
313
  },
285
314
  };
@@ -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
+ }
@@ -14,7 +14,7 @@ export const withCappaDecorator = makeDecorator({
14
14
  try {
15
15
  const cappaParameters = await waitForExposed("__cappa_parameters");
16
16
 
17
- cappaParameters(parameters ?? {});
17
+ cappaParameters(context.id, parameters ?? {});
18
18
  } catch (error) {
19
19
  console.error(error);
20
20
  }
@@ -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
 
package/src/types.ts CHANGED
@@ -1,5 +1,30 @@
1
- import type { ScreenshotOptions } from "@cappa/core";
1
+ export interface StorybookRenderOptions {
2
+ viewMode?: "story" | "docs";
3
+ args?: Record<string, unknown>;
4
+ globals?: Record<string, string | number | boolean>;
5
+ query?: Record<string, string | number | boolean>;
6
+ fullscreen?: boolean;
7
+ singleStory?: boolean;
8
+ }
2
9
 
3
- export type ScreenshotOptionsStorybook = Omit<ScreenshotOptions, "mask"> & {
4
- mask: string[];
5
- };
10
+ export interface ScreenshotVariantOverrideStorybook {
11
+ fullPage?: boolean;
12
+ delay?: number;
13
+ skip?: boolean;
14
+ mask?: string[];
15
+ omitBackground?: boolean;
16
+ viewport?: { width: number; height: number };
17
+ }
18
+
19
+ export interface ScreenshotVariantOptionsStorybook {
20
+ id: string;
21
+ label?: string;
22
+ filename?: string;
23
+ options?: ScreenshotVariantOverrideStorybook;
24
+ }
25
+
26
+ export interface ScreenshotOptionsStorybook
27
+ extends ScreenshotVariantOverrideStorybook {
28
+ variants?: ScreenshotVariantOptionsStorybook[];
29
+ storybook?: StorybookRenderOptions;
30
+ }
package/tsconfig.json ADDED
@@ -0,0 +1,13 @@
1
+ {
2
+ "extends": "../../config-ts/bundler.json",
3
+ "compilerOptions": {
4
+ "baseUrl": ".",
5
+ "types": ["vitest"]
6
+ },
7
+ "include": [
8
+ "src/**/*",
9
+ "./package.json",
10
+ "./tsdown.config.ts",
11
+ "./vitest.config.ts"
12
+ ]
13
+ }
package/src/tsconfig.json DELETED
@@ -1,7 +0,0 @@
1
- {
2
- "extends": "@cappa/config-ts/base.json",
3
- "compilerOptions": {
4
- "types": ["vitest/globals"]
5
- },
6
- "include": ["src/**/*.ts"]
7
- }