@coder/pixel-storybook 0.1.0

package/dist/crawler/storybook.js

@@ -0,0 +1,317 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { config, isPlatformModeConfig } from '../config.js';
+import { notSupported } from '../constants.js';
+import { log } from '../log.js';
+import { generateLabel, selectBreakpoints } from '../shots/utils.js';
+import { launchBrowser } from '../utils.js';
+export const getStoryBookUrl = (url) => {
+    if (url.startsWith('http://') ||
+        url.startsWith('https://') ||
+        url.startsWith('file://')) {
+        return url;
+    }
+    if (url.startsWith('/')) {
+        return `file://${url}`;
+    }
+    return `file://${path.normalize(path.join(process.cwd(), url))}`;
+};
+export const getIframeUrl = (url) => url.endsWith('/') ? `${url}iframe.html` : `${url}/iframe.html`;
+export const collectStoriesViaWindowApi = async (context, url, isIframeUrl) => {
+    const page = await context.newPage();
+    const iframeUrl = isIframeUrl
+        ? getStoryBookUrl(url)
+        : getIframeUrl(getStoryBookUrl(url));
+    await page.goto(iframeUrl);
+    await page.waitForFunction(() => window.__STORYBOOK_PREVIEW__, null, {
+        timeout: config.timeouts.fetchStories,
+    });
+    // Storybook >= 8 expose a new preview API that has a `ready` method to be awaited before proceeding
+    const isV8OrAbove = await page.evaluate(async () => {
+        const { __STORYBOOK_PREVIEW__: api } = window;
+        return api.ready !== undefined;
+    });
+    if (isV8OrAbove) {
+        // SB v8 and above
+        await page.evaluate(async () => {
+            const { __STORYBOOK_PREVIEW__: api } = window;
+            if (api.ready) {
+                await api.ready();
+            }
+        });
+    }
+    else {
+        // SB v7 and below
+        await page.waitForFunction(() => window.__STORYBOOK_CLIENT_API__, null, {
+            timeout: config.timeouts.fetchStories,
+        });
+        await page.evaluate(async () => {
+            const { __STORYBOOK_CLIENT_API__: api } = window;
+            if (api.storyStore) {
+                await api.storyStore.cacheAllCSFFiles?.();
+            }
+        });
+    }
+    const result = await page.evaluate(async () => {
+        const parseParameters = (parameters, level = 0) => {
+            if (level > 10) {
+                return 'UNSUPPORTED_DEPTH';
+            }
+            if (Array.isArray(parameters)) {
+                // @ts-expect-error FIXME
+                return parameters.map((value) => parseParameters(value, level + 1));
+            }
+            if (typeof parameters === 'string' ||
+                typeof parameters === 'number' ||
+                typeof parameters === 'boolean' ||
+                parameters === undefined ||
+                typeof parameters === 'function' ||
+                parameters instanceof RegExp ||
+                parameters instanceof Date ||
+                parameters === null) {
+                return parameters;
+            }
+            if (typeof parameters === 'object' && parameters !== null) {
+                // @ts-expect-error FIXME
+                // eslint-disable-next-line unicorn/no-array-reduce
+                return Object.keys(parameters).reduce((acc, key) => {
+                    // @ts-expect-error FIXME
+                    acc[key] = parseParameters(parameters[key], level + 1);
+                    return acc;
+                }, {});
+            }
+            return 'UNSUPPORTED_TYPE';
+        };
+        const mapStories = (stories) => stories.map((story) => {
+            const parameters = parseParameters(story.parameters);
+            return {
+                id: story.id,
+                kind: story.kind,
+                story: story.story,
+                importPath: parameters?.fileName,
+                parameters,
+            };
+        });
+        const { __STORYBOOK_PREVIEW__: previewApi, __STORYBOOK_CLIENT_API__: clientApi, } = window;
+        let stories = [];
+        if (previewApi.extract) {
+            const items = await previewApi.extract();
+            stories = mapStories(Object.values(items));
+        }
+        else if (clientApi.raw) {
+            // Fallback for 6.4 and below
+            stories = mapStories(clientApi.raw());
+        }
+        return { stories };
+    });
+    return result;
+};
+export const collectStoriesViaStoriesJson = async (context, url) => {
+    const storiesJsonUrl = url.endsWith('/')
+        ? `${url}stories.json`
+        : `${url}/stories.json`;
+    let storiesJson;
+    if (storiesJsonUrl.startsWith('file://')) {
+        try {
+            const file = readFileSync(storiesJsonUrl.slice(7));
+            storiesJson = JSON.parse(file.toString());
+        }
+        catch {
+            throw new Error(`Cannot load file ${storiesJsonUrl}`);
+        }
+    }
+    else {
+        const result = await context.request.get(storiesJsonUrl);
+        storiesJson = (await result.json());
+    }
+    if (typeof storiesJson.stories === 'object') {
+        return {
+            stories: Object.values(storiesJson.stories),
+        };
+    }
+    throw new Error(`Cannot load resource ${storiesJsonUrl}`);
+};
+export const collectStories = async (url) => {
+    const browser = await launchBrowser();
+    const context = await browser.newContext();
+    try {
+        log.process('info', 'general', 'Trying to collect stories via window object');
+        const result = await collectStoriesViaWindowApi(context, url);
+        await browser.close();
+        return result;
+    }
+    catch (error) {
+        log.process('info', 'general', 'Fallback to /stories.json');
+        log.process('error', 'general', error);
+    }
+    try {
+        const result = await collectStoriesViaStoriesJson(context, url);
+        await browser.close();
+        return result;
+    }
+    catch (error) {
+        await browser.close();
+        throw error;
+    }
+};
+const generateBrowserConfig = (story) => {
+    const browserConfig = config.configureBrowser?.({
+        ...story,
+        shotMode: 'storybook',
+    });
+    if (story.parameters?.viewport && browserConfig) {
+        browserConfig.viewport ??= {
+            width: 1280,
+            height: 720,
+        };
+        browserConfig.viewport = {
+            ...browserConfig.viewport,
+            ...story.parameters.viewport,
+        };
+    }
+    return browserConfig;
+};
+const generateStoryUrl = (iframeUrl, storyId, args, breakpoint) => {
+    let url = `${iframeUrl}?id=${storyId}&viewMode=story`;
+    if (args) {
+        const argsString = Object.entries(args)
+            .map(([key, value]) => `${key}:${value}`)
+            .join(';');
+        url += `&args=${argsString}`;
+    }
+    if (breakpoint !== undefined) {
+        url += `&width=${breakpoint}`;
+    }
+    return url;
+};
+const kebabCase = (str) => (str ?? '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+const generateFilename = (kind, story, prefix, suffix) => {
+    return [prefix, kebabCase(kind), kebabCase(story), kebabCase(suffix)]
+        .filter(Boolean)
+        .join('--');
+};
+export const generateStorybookShotItems = (baseUrl, stories, mask, modeBreakpoints, browser) => {
+    const iframeUrl = getIframeUrl(getStoryBookUrl(baseUrl));
+    return stories
+        .filter((story) => story.parameters?.lostpixel?.disable !== true)
+        .filter((story) => story.parameters?.storyshots?.disable !== true)
+        .filter((story) => config.filterShot
+        ? config.filterShot({ ...story, shotMode: 'storybook' })
+        : true)
+        .flatMap((story) => {
+        const shotName = config.shotNameGenerator?.({ ...story, shotMode: 'storybook' }) ??
+            generateFilename(story.kind, story.story);
+        let label = generateLabel({ browser });
+        let fileNameWithExt = `${shotName}${label}.png`;
+        const baseShotItem = {
+            shotMode: 'storybook',
+            id: `${story.id}${label}`,
+            shotName: `${shotName}${label}`,
+            importPath: story.importPath,
+            url: generateStoryUrl(iframeUrl, story.id, story.parameters?.lostpixel?.args),
+            filePathBaseline: isPlatformModeConfig(config)
+                ? notSupported
+                : path.join(config.imagePathBaseline, fileNameWithExt),
+            filePathCurrent: path.join(config.imagePathCurrent, fileNameWithExt),
+            filePathDifference: isPlatformModeConfig(config)
+                ? notSupported
+                : path.join(config.imagePathDifference, fileNameWithExt),
+            browserConfig: generateBrowserConfig(story),
+            threshold: story.parameters?.lostpixel?.threshold ?? config.threshold,
+            waitBeforeScreenshot: story.parameters?.lostpixel?.waitBeforeScreenshot ??
+                config.waitBeforeScreenshot,
+            stabilizeBeforeScreenshot: story.parameters?.lostpixel?.stabilizeBeforeScreenshot ??
+                config.stabilizeBeforeScreenshot,
+            mask: [...(mask ?? []), ...(story.parameters?.lostpixel?.mask ?? [])],
+            elementLocator: story.parameters?.lostpixel?.elementLocator ??
+                config?.storybookShots?.elementLocator ??
+                '',
+            waitForSelector: config?.storybookShots?.waitForSelector,
+        };
+        const storyLevelBreakpoints = story.parameters?.lostpixel?.breakpoints ?? [];
+        const breakpoints = selectBreakpoints(config.breakpoints, modeBreakpoints, storyLevelBreakpoints);
+        let shotItems = [];
+        if (!breakpoints || breakpoints.length === 0) {
+            shotItems = [baseShotItem];
+        }
+        else {
+            shotItems = breakpoints.map((breakpoint) => {
+                label = generateLabel({ breakpoint, browser });
+                fileNameWithExt = `${shotName}${label}.png`;
+                return {
+                    ...baseShotItem,
+                    id: `${story.id}${label}`,
+                    shotName: `${shotName}${label}`,
+                    breakpoint,
+                    breakpointGroup: story.id,
+                    filePathBaseline: isPlatformModeConfig(config)
+                        ? notSupported
+                        : path.join(config.imagePathBaseline, fileNameWithExt),
+                    filePathCurrent: path.join(config.imagePathCurrent, fileNameWithExt),
+                    filePathDifference: isPlatformModeConfig(config)
+                        ? notSupported
+                        : path.join(config.imagePathDifference, fileNameWithExt),
+                    viewport: {
+                        width: breakpoint,
+                        height: undefined,
+                    },
+                    url: generateStoryUrl(iframeUrl, story.id, story.parameters?.lostpixel?.args, breakpoint),
+                    browserConfig: generateBrowserConfig({
+                        ...story,
+                        parameters: {
+                            ...story.parameters,
+                            viewport: {
+                                width: breakpoint,
+                            },
+                        },
+                    }),
+                };
+            });
+        }
+        const extraShots = story.parameters?.lostpixel?.extraShots?.flatMap((snapshot) => {
+            const combinedArgs = {
+                ...story.parameters?.lostpixel?.args,
+                ...snapshot.args,
+            };
+            const snapshotShotName = generateFilename(story.kind, story.story, snapshot.prefix, snapshot.suffix);
+            return (breakpoints?.length === 0 ? [undefined] : breakpoints).map((breakpoint) => {
+                label = generateLabel({ breakpoint, browser });
+                fileNameWithExt = `${snapshotShotName}${label}.png`;
+                return {
+                    ...baseShotItem,
+                    id: `${story.id}${label}-${snapshot.name ?? 'snapshot'}`,
+                    shotName: `${snapshotShotName}${label}`,
+                    breakpoint,
+                    breakpointGroup: story.id,
+                    filePathBaseline: isPlatformModeConfig(config)
+                        ? notSupported
+                        : path.join(config.imagePathBaseline, fileNameWithExt),
+                    filePathCurrent: path.join(config.imagePathCurrent, fileNameWithExt),
+                    filePathDifference: isPlatformModeConfig(config)
+                        ? notSupported
+                        : path.join(config.imagePathDifference, fileNameWithExt),
+                    url: generateStoryUrl(iframeUrl, story.id, combinedArgs, breakpoint),
+                    viewport: breakpoint
+                        ? {
+                            width: breakpoint,
+                            height: undefined,
+                        }
+                        : undefined,
+                    browserConfig: generateBrowserConfig({
+                        ...story,
+                        parameters: {
+                            ...story.parameters,
+                            viewport: {
+                                width: breakpoint,
+                            },
+                        },
+                    }),
+                };
+            });
+        }) ?? [];
+        return [...shotItems, ...extraShots];
+    });
+};

package/dist/crawler/utils.d.ts

@@ -0,0 +1,6 @@
+import http from 'node:http';
+export declare const launchStaticWebServer: (basePath: string) => Promise<{
+    server: http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+    port: number;
+    url: string;
+}>;

package/dist/crawler/utils.js

@@ -0,0 +1,20 @@
+import http from 'node:http';
+import { getPort } from 'get-port-please';
+import handler from 'serve-handler';
+export const launchStaticWebServer = async (basePath) => {
+    const port = await getPort({
+        random: true,
+    });
+    const server = http.createServer(async (request, response) => {
+        return handler(request, response, {
+            public: basePath.startsWith('file://') ? basePath.slice(7) : basePath,
+            cleanUrls: false,
+        });
+    });
+    server.listen(port);
+    return {
+        server,
+        port,
+        url: `http://localhost:${port}`,
+    };
+};

package/dist/createShots.d.ts

@@ -0,0 +1,30 @@
+export declare const createShots: () => Promise<{
+    shotMode: "storybook";
+    id: string;
+    shotName: string;
+    url: string;
+    filePathBaseline: string;
+    filePathCurrent: string;
+    filePathDifference: string;
+    threshold: number;
+    browserConfig?: import("playwright-core").BrowserContextOptions | undefined;
+    waitBeforeScreenshot?: number | undefined;
+    stabilizeBeforeScreenshot?: boolean | undefined;
+    stabilization?: {
+        status: "stable" | "fonts-not-ready" | "images-not-ready" | "unstable";
+        elapsedMs: number;
+        capMs: number;
+    } | undefined;
+    importPath?: string | undefined;
+    mask?: {
+        selector: string;
+    }[] | undefined;
+    viewport?: {
+        width: number;
+        height?: number | undefined;
+    } | undefined;
+    breakpoint?: number | undefined;
+    breakpointGroup?: string | undefined;
+    elementLocator?: string | undefined;
+    waitForSelector?: string | undefined;
+}[]>;

package/dist/createShots.js

@@ -0,0 +1,54 @@
+import { mapLimit } from './concurrency.js';
+import { config, isPlatformModeConfig } from './config.js';
+import { collectStories, generateStorybookShotItems, } from './crawler/storybook.js';
+import { launchStaticWebServer } from './crawler/utils.js';
+import { log } from './log.js';
+import { takeScreenShots } from './shots/shots.js';
+import { getBrowsers, removeFilesInFolder } from './utils.js';
+export const createShots = async () => {
+    const { storybookShots, imagePathCurrent } = config;
+    const shotItems = [];
+    removeFilesInFolder(imagePathCurrent);
+    if (!isPlatformModeConfig(config)) {
+        removeFilesInFolder(config.imagePathDifference);
+    }
+    const browsers = getBrowsers();
+    if (storybookShots) {
+        const { storybookUrl, mask } = storybookShots;
+        log.process('info', 'general', `\n=== [Storybook Mode] ${storybookUrl} ===\n`);
+        let storybookWebUrl = storybookUrl;
+        let localServer;
+        if (!storybookUrl.startsWith('http://') &&
+            !storybookUrl.startsWith('https://')) {
+            const staticWebServer = await launchStaticWebServer(storybookUrl);
+            storybookWebUrl = staticWebServer.url;
+            localServer = staticWebServer.server;
+        }
+        try {
+            const collection = await collectStories(storybookWebUrl);
+            if (!collection?.stories || collection.stories.length === 0) {
+                throw new Error('Error: Stories not found');
+            }
+            log.process('info', 'general', `Found ${collection.stories.length} stories`);
+            await mapLimit(browsers, browsers.length, async (browser) => {
+                const items = generateStorybookShotItems(storybookWebUrl, collection.stories, mask, storybookShots.breakpoints, browsers.length > 1 ? browser : undefined);
+                const filterItemsToCheck = 'filterItemsToCheck' in config
+                    ? config.filterItemsToCheck
+                    : undefined;
+                const filteredShotItems = filterItemsToCheck
+                    ? items.filter((item) => filterItemsToCheck(item))
+                    : items;
+                shotItems.push(...items);
+                log.process('info', 'general', `Prepared ${filteredShotItems.length} stories for screenshots on ${browser.name()}`);
+                await takeScreenShots(filteredShotItems, browser);
+            });
+            localServer?.close();
+        }
+        catch (error) {
+            localServer?.close();
+            throw error;
+        }
+        log.process('info', 'general', 'Screenshots done!');
+    }
+    return shotItems;
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './config.js';
+export type { StoryParameters } from './crawler/storybook.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './config.js';

package/dist/log.d.ts

@@ -0,0 +1,26 @@
+import type { ShotMode } from './types.js';
+type LogLevel = 'info' | 'error' | 'warn' | 'debug';
+type LogEntry = {
+    timestamp: Date;
+    level: LogLevel;
+    item?: {
+        shotMode: ShotMode;
+        uniqueItemId: string;
+        itemIndex: number;
+        totalItems: number;
+    };
+    source: 'process' | 'browser';
+    context: 'general' | 'api' | 'console' | 'network' | 'timeout' | 'config';
+    content: unknown[];
+};
+export type LogMemory = LogEntry[];
+export declare const logMemory: LogMemory;
+export declare const log: {
+    item: (item: LogEntry["item"]) => {
+        process(level: LogEntry["level"], context: LogEntry["context"], ...content: unknown[]): void;
+        browser(level: LogEntry["level"], context: LogEntry["context"], ...content: unknown[]): void;
+    };
+    process(level: LogEntry["level"], context: LogEntry["context"], ...content: unknown[]): void;
+    browser(level: LogEntry["level"], context: LogEntry["context"], ...content: unknown[]): void;
+};
+export {};

package/dist/log.js

@@ -0,0 +1,99 @@
+export const logMemory = [];
+const serializeError = (error) => ({
+    message: error.message,
+    name: error.name,
+    stack: error.stack,
+});
+const serializeErrors = (content) => content.map((item) => {
+    if (item instanceof Error) {
+        return serializeError(item);
+    }
+    return item;
+});
+const renderLog = (entry) => {
+    if (entry.source === 'browser' && entry.context === 'console') {
+        return;
+    }
+    if (entry.source === 'browser' && entry.context === 'network') {
+        return;
+    }
+    const { log } = console;
+    const logPrefix = [];
+    if (entry.item) {
+        logPrefix.push(`[${entry.item.itemIndex + 1}/${entry.item.totalItems}]`);
+    }
+    if (!['general', 'api', 'config'].includes(entry.context)) {
+        logPrefix.push(`[${entry.context}]`);
+    }
+    if (entry.level === 'error') {
+        logPrefix.push('❌');
+    }
+    if (entry.item?.uniqueItemId) {
+        log(...logPrefix, ...entry.content, `(${entry.item?.uniqueItemId})`);
+    }
+    else {
+        log(...logPrefix, ...entry.content);
+    }
+};
+export const log = {
+    item: (item) => ({
+        process(level, context, ...content) {
+            const entry = {
+                timestamp: new Date(),
+                level,
+                item,
+                source: 'process',
+                context,
+                content,
+            };
+            renderLog(entry);
+            logMemory.push({
+                ...entry,
+                content: serializeErrors(content),
+            });
+        },
+        browser(level, context, ...content) {
+            const entry = {
+                timestamp: new Date(),
+                level,
+                item,
+                source: 'browser',
+                context,
+                content,
+            };
+            renderLog(entry);
+            logMemory.push({
+                ...entry,
+                content: serializeErrors(content),
+            });
+        },
+    }),
+    process(level, context, ...content) {
+        const entry = {
+            timestamp: new Date(),
+            level,
+            source: 'process',
+            context,
+            content,
+        };
+        renderLog(entry);
+        logMemory.push({
+            ...entry,
+            content: serializeErrors(content),
+        });
+    },
+    browser(level, context, ...content) {
+        const entry = {
+            timestamp: new Date(),
+            level,
+            source: 'browser',
+            context,
+            content,
+        };
+        renderLog(entry);
+        logMemory.push({
+            ...entry,
+            content: serializeErrors(content),
+        });
+    },
+};

package/dist/runner.d.ts

@@ -0,0 +1,4 @@
+import type { GenerateOnlyModeConfig, PlatformModeConfig } from './config.js';
+export declare const runner: (config: GenerateOnlyModeConfig) => Promise<void>;
+export declare const getPlatformApiToken: (config: PlatformModeConfig) => Promise<string>;
+export declare const platformRunner: (config: PlatformModeConfig, apiToken: string) => Promise<void>;