@coder/pixel-storybook 0.1.0

package/dist/config.js

@@ -0,0 +1,472 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import * as z from 'zod';
+import { defaultShotConcurrency } from './concurrency.js';
+import { loadProjectConfigFile, loadTSProjectConfigFile, } from './configHelper.js';
+import { log } from './log.js';
+import { BrowserSchema, MaskSchema, ShotModeSchema } from './schemas.js';
+const StorybookShotsSchema = z.object({
+    /**
+     * URL of the Storybook instance or local folder
+     * @default 'storybook-static'
+     */
+    storybookUrl: z.string(),
+    /**
+     * Define areas for all stories where differences will be ignored
+     */
+    mask: z.array(MaskSchema).optional(),
+    /**
+     * Define custom breakpoints for all Storybook shots as width in pixels
+     * @default []
+     * @example
+     * [ 320, 768, 1280 ]
+     */
+    breakpoints: z.array(z.number()).optional(),
+    /**
+     * Target specific element on page with a selector
+     */
+    elementLocator: z.string().optional(),
+    /**
+     * Wait for a specific selector before taking a screenshot
+     * @example '[data-storyloaded]'
+     */
+    waitForSelector: z.string().optional(),
+});
+const StoryLikeSchema = z.object({
+    shotMode: ShotModeSchema,
+    id: z.string().optional(),
+    kind: z.string().optional(),
+    story: z.string().optional(),
+    shotName: z.string().optional(),
+    parameters: z.record(z.unknown()).optional(),
+    filePathBaseline: z.string().optional(),
+    filePathCurrent: z.string().optional(),
+    filePathDifference: z.string().optional(),
+});
+const ShotItem = z.object({
+    shotMode: ShotModeSchema,
+    id: z.string(),
+    shotName: z.string(),
+    url: z.string(),
+    filePathBaseline: z.string(),
+    filePathCurrent: z.string(),
+    filePathDifference: z.string(),
+    browserConfig: z.custom().optional(),
+    threshold: z.number(),
+    waitBeforeScreenshot: z.number().optional(),
+    stabilizeBeforeScreenshot: z.boolean().optional(),
+    importPath: z.string().optional(),
+    mask: z.array(MaskSchema).optional(),
+    viewport: z
+        .object({
+        width: z.number(),
+        height: z.number().optional(),
+    })
+        .optional(),
+    breakpoint: z.number().optional(),
+    breakpointGroup: z.string().optional(),
+    elementLocator: z.string().optional(),
+    waitForSelector: z.string().optional(),
+});
+const TimeoutsSchema = z.object({
+    /**
+     * Timeout for fetching stories
+     * @default 30_000
+     */
+    fetchStories: z.number().default(30_000),
+    /**
+     * Timeout for loading the state of the page
+     * @default 30_000
+     */
+    loadState: z.number().default(30_000),
+    /**
+     * Timeout for waiting for network requests to finish
+     * @default 30_000
+     */
+    networkRequests: z.number().default(30_000),
+});
+const BaseConfigSchema = z.object({
+    /**
+     * Browser to use: chromium, firefox, or webkit
+     * @default 'chromium'
+     */
+    browser: z
+        .union([BrowserSchema, z.array(BrowserSchema).default(['chromium'])])
+        .default('chromium'),
+    /**
+     * Enable Storybook mode
+     */
+    storybookShots: StorybookShotsSchema.optional(),
+    /**
+     * Path to the current image folder
+     * @default '.lostpixel/current/'
+     */
+    imagePathCurrent: z.string().default('.lostpixel/current/'),
+    /**
+     * Define custom breakpoints for all tests as width in pixels
+     * @default []
+     * @example
+     * [ 320, 768, 1280 ]
+     */
+    breakpoints: z.array(z.number()).optional(),
+    /**
+     * Number of concurrent shots to take. Auto-scales with the number of CPUs
+     * available to the process by default (floor `10`, ceiling `32`). Set to
+     * `0` to opt back into the auto default from an explicit config.
+     * @default auto
+     */
+    shotConcurrency: z
+        .number()
+        .nonnegative()
+        .default(() => defaultShotConcurrency())
+        .transform((value) => (value === 0 ? defaultShotConcurrency() : value)),
+    /**
+     * Timeouts for various stages of the test
+     */
+    timeouts: TimeoutsSchema.default({
+        fetchStories: 30_000,
+        loadState: 30_000,
+        networkRequests: 30_000,
+    }),
+    /**
+     * Maximum time to wait before taking a screenshot. When
+     * `stabilizeBeforeScreenshot` is `true` (the default), this is the cap on
+     * the adaptive stability wait. When `false`, this is the fixed sleep.
+     * @default 1_000
+     */
+    waitBeforeScreenshot: z.number().default(1000),
+    /**
+     * When `true`, the wait before taking a screenshot is adaptive: lost-pixel
+     * waits for web fonts, pending images, one committed frame, and a quiet
+     * DOM, bounded above by `waitBeforeScreenshot`. When `false`, falls back
+     * to a fixed sleep of `waitBeforeScreenshot` milliseconds.
+     * @default true
+     */
+    stabilizeBeforeScreenshot: z.boolean().default(true),
+    /**
+     * Time to wait for the first network request to start
+     * @default 200
+     */
+    waitForFirstRequest: z.number().default(200),
+    /**
+     * Time to wait for the last network request to start
+     * @default 1_000
+     */
+    waitForLastRequest: z.number().default(1000),
+    /**
+     * Threshold for the difference between the baseline and current image
+     *
+     * Values between 0 and 1 are interpreted as percentage of the image size
+     *
+     * Values greater or equal to 1 are interpreted as pixel count.
+     * @default 0
+     */
+    threshold: z.number().default(0),
+    /**
+     * How often to retry a shot for a stable result
+     * @default 0
+     */
+    flakynessRetries: z.number().default(0),
+    /**
+     * Time to wait between flakyness retries
+     * @default 2_000
+     */
+    waitBetweenFlakynessRetries: z.number().default(2000),
+    /**
+     * Global shot filter
+     */
+    filterShot: z
+        .function()
+        .args(StoryLikeSchema)
+        .returns(z.boolean())
+        .optional(),
+    /**
+     * Shot and file name generator for images
+     */
+    shotNameGenerator: z
+        .function()
+        .args(StoryLikeSchema)
+        .returns(z.string())
+        .optional(),
+    /**
+     * Configure browser context options
+     */
+    configureBrowser: z
+        .function()
+        .args(StoryLikeSchema)
+        .returns(z.custom())
+        .optional(),
+    /**
+     * Configure page before screenshot
+     */
+    beforeScreenshot: z
+        .function()
+        .args(z.custom(), StoryLikeSchema)
+        .returns(z.promise(z.void()))
+        .optional(),
+    /**
+     * Perform actions after screenshot was taken
+     */
+    afterScreenshot: z
+        .function()
+        .args(z.custom(), StoryLikeSchema)
+        .returns(z.promise(z.void()))
+        .optional(),
+    /**
+     * Launch options for the browser
+     */
+    browserLaunchOptions: z
+        .object({
+        chromium: z.custom().optional(),
+        firefox: z.custom().optional(),
+        webkit: z.custom().optional(),
+    })
+        .optional(),
+});
+export const PlatformModeConfigSchema = BaseConfigSchema.extend({
+    /**
+     * URL of the Lost Pixel API endpoint
+     * @default 'https://api.lost-pixel.com'
+     */
+    lostPixelPlatform: z.string().default('https://api.lost-pixel.com'),
+    /**
+     * API key for the Lost Pixel platform
+     */
+    apiKey: z.string(),
+    /**
+     * Project ID
+     */
+    lostPixelProjectId: z.string(),
+    /**
+     * CI build ID
+     */
+    ciBuildId: z
+        .string({
+        required_error: 'Required (can be set via `CI_BUILD_ID` env variable)',
+    })
+        // @ts-expect-error If not set, it will be caught during config validation
+        .default(process.env.CI_BUILD_ID),
+    /**
+     * CI build number
+     */
+    ciBuildNumber: z
+        .string({
+        required_error: 'Required (can be set via `CI_BUILD_NUMBER` env variable)',
+    })
+        // @ts-expect-error If not set, it will be caught during config validation
+        .default(process.env.CI_BUILD_NUMBER),
+    /**
+     * Git repository name (e.g. 'lost-pixel/lost-pixel-storybook')
+     */
+    repository: z
+        .string({
+        required_error: 'Required (can be set via `REPOSITORY` env variable)',
+    })
+        // @ts-expect-error If not set, it will be caught during config validation
+        .default(process.env.REPOSITORY),
+    /**
+     * Git branch name (e.g. 'main')
+     */
+    commitRefName: z
+        .string({
+        required_error: 'Required (can be set via `COMMIT_REF_NAME` env variable)',
+    })
+        // @ts-expect-error If not set, it will be caught during config validation
+        .default(process.env.COMMIT_REF_NAME),
+    /**
+     * Git commit SHA (e.g. 'b9b8b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9b9')
+     */
+    commitHash: z
+        .string({
+        required_error: 'Required (can be set via `COMMIT_HASH` env variable)',
+    })
+        // @ts-expect-error If not set, it will be caught during config validation
+        .default(process.env.COMMIT_HASH),
+    /**
+     * File path to event.json file
+     */
+    eventFilePath: z.string().optional(),
+    /**
+     * Whether to set the GitHub status check on process start or not
+     *
+     * Setting this option to `true` makes only sense if the repository settings have pending status checks disabled
+     * @default false
+     */
+    setPendingStatusCheck: z.boolean().default(false),
+    /**
+     * Skip taking screenshots and only upload existing images to the platform.
+     *
+     * When enabled, lost-pixel reads `.png` files from `imagePathCurrent`
+     * instead of launching a browser. Useful when screenshots are produced
+     * by an external process.
+     * @default false
+     */
+    uploadOnly: z.boolean().default(false),
+});
+export const GenerateOnlyModeConfigSchema = BaseConfigSchema.extend({
+    /**
+     * Run in local mode
+     * @deprecated Defaults to running in generateOnly mode
+     */
+    generateOnly: z.boolean().optional(),
+    /**
+     * Skip taking screenshots and only upload them to the platform.
+     */
+    uploadOnly: z.boolean().optional(),
+    /**
+     * Flag that decides if process should exit if a difference is found
+     */
+    failOnDifference: z.boolean().optional(),
+    /**
+     * Path to the baseline image folder
+     * @default '.lostpixel/baseline/'
+     */
+    imagePathBaseline: z.string().default('.lostpixel/baseline/'),
+    /**
+     * Path to the difference image folder
+     * @default '.lostpixel/difference/'
+     */
+    imagePathDifference: z.string().default('.lostpixel/difference/'),
+    /**
+     * Number of concurrent screenshots to compare
+     * @default 10
+     */
+    compareConcurrency: z.number().default(10),
+    /**
+     * Which comparison engine to use for diffing images
+     * @default 'pixelmatch'
+     */
+    compareEngine: z.enum(['pixelmatch', 'odiff']).default('pixelmatch'),
+    /**
+     * Filter stories to take screenshots of and run comparisons on (existing shots remain untouched)
+     */
+    filterItemsToCheck: z
+        .function()
+        .args(ShotItem)
+        .returns(z.boolean())
+        .optional(),
+});
+export const ConfigSchema = z.union([
+    PlatformModeConfigSchema,
+    GenerateOnlyModeConfigSchema,
+]);
+// use partial() specifically for the inferred type
+export const FlexibleConfigSchema = z.union([
+    PlatformModeConfigSchema.extend({
+        timeouts: TimeoutsSchema.partial(),
+    }).partial(),
+    GenerateOnlyModeConfigSchema.extend({
+        timeouts: TimeoutsSchema.partial(),
+    }).partial(),
+]);
+export let config;
+export const isPlatformModeConfig = (userConfig) => ('apiKey' in userConfig && typeof userConfig.apiKey === 'string') ||
+    ('lostPixelProjectId' in userConfig &&
+        typeof userConfig.lostPixelProjectId === 'string');
+const printConfigErrors = (error) => {
+    for (const issue of error.issues) {
+        log.process('error', 'config', [
+            'Configuration error:',
+            `  - Path: ${issue.path.join('.')}`,
+            `  - Message: ${issue.message}`,
+        ].join('\n'));
+    }
+};
+export const parseConfig = (userConfig) => {
+    if (isPlatformModeConfig(userConfig)) {
+        const platformCheck = PlatformModeConfigSchema.safeParse(userConfig);
+        if (platformCheck.success) {
+            return platformCheck.data;
+        }
+        printConfigErrors(platformCheck.error);
+    }
+    else {
+        const generateOnlyCheck = GenerateOnlyModeConfigSchema.safeParse(userConfig);
+        if (generateOnlyCheck.success) {
+            return generateOnlyCheck.data;
+        }
+        printConfigErrors(generateOnlyCheck.error);
+    }
+    throw new Error('Configuration error');
+};
+const configDirBase = process.env.LOST_PIXEL_CONFIG_DIR ?? process.cwd();
+const configFileNameBase = path.join(path.isAbsolute(configDirBase) ? '' : process.cwd(), configDirBase, 'lostpixel.config');
+const loadProjectConfig = async () => {
+    log.process('info', 'config', 'Loading project config ...');
+    log.process('info', 'config', 'Current working directory:', process.cwd());
+    if (process.env.LOST_PIXEL_CONFIG_DIR) {
+        log.process('info', 'config', 'Defined config directory:', process.env.LOST_PIXEL_CONFIG_DIR);
+    }
+    const configExtensions = ['ts', 'js', 'cjs', 'mjs'];
+    const configExtensionsString = configExtensions.join('|');
+    log.process('info', 'config', 'Looking for config file:', `${configFileNameBase}.(${configExtensionsString})`);
+    const configFiles = configExtensions
+        .map((ext) => `${configFileNameBase}.${ext}`)
+        .filter((file) => existsSync(file));
+    if (configFiles.length === 0) {
+        log.process('error', 'config', `Couldn't find project config file 'lostpixel.config.(${configExtensionsString})'`);
+        process.exit(1);
+    }
+    if (configFiles.length > 1) {
+        log.process('info', 'config', '✅ Found multiple config files, taking:', configFiles[0]);
+    }
+    else {
+        log.process('info', 'config', '✅ Found config file:', configFiles[0]);
+    }
+    const configFile = configFiles[0];
+    try {
+        const imported = (await loadProjectConfigFile(configFile));
+        return imported;
+    }
+    catch {
+        log.process('error', 'config', 'Loading config using ESBuild failed, using fallback option');
+        try {
+            if (existsSync(`${configFileNameBase}.js`)) {
+                const projectConfig = (await import(`${configFileNameBase}.js`));
+                const resolved = projectConfig?.default ?? projectConfig;
+                log.process('info', 'config', '✅ Successfully loaded configuration from:', `${configFileNameBase}.js`);
+                return resolved;
+            }
+            if (existsSync(`${configFileNameBase}.ts`)) {
+                const imported = (await loadTSProjectConfigFile(configFile));
+                log.process('info', 'config', '✅ Successfully loaded configuration from:', `${configFileNameBase}.ts`);
+                return imported;
+            }
+            log.process('error', 'config', "Couldn't find project config file 'lostpixel.config.js'");
+            process.exit(1);
+        }
+        catch (error) {
+            log.process('error', 'config', `Failed to load config file: ${configFile}`);
+            log.process('error', 'config', error);
+            process.exit(1);
+        }
+    }
+};
+export const configure = async ({ customProjectConfig, localDebugMode, }) => {
+    if (customProjectConfig) {
+        config = parseConfig(customProjectConfig);
+        return;
+    }
+    let loadedProjectConfig = await loadProjectConfig();
+    if (localDebugMode) {
+        let localDebugConfig = loadedProjectConfig;
+        if (isPlatformModeConfig(loadedProjectConfig)) {
+            localDebugConfig = {
+                ...loadedProjectConfig,
+                generateOnly: true,
+                // @ts-expect-error Force it into generateOnly mode by dropping the platform specific properties
+                lostPixelProjectId: undefined,
+                // @ts-expect-error Force it into generateOnly mode by dropping the platform specific properties
+                apiKey: undefined,
+            };
+        }
+        loadedProjectConfig = localDebugConfig;
+    }
+    // Default to Storybook mode if no mode is defined
+    if (!loadedProjectConfig.storybookShots) {
+        loadedProjectConfig.storybookShots = {
+            storybookUrl: 'storybook-static',
+        };
+    }
+    config = parseConfig(loadedProjectConfig);
+};

package/dist/configHelper.d.ts

@@ -0,0 +1,2 @@
+export declare const loadProjectConfigFile: (configFilepath: string) => Promise<unknown>;
+export declare const loadTSProjectConfigFile: (configFilepath: string) => Promise<unknown>;

package/dist/configHelper.js

@@ -0,0 +1,34 @@
+import { log } from './log.js';
+export const loadProjectConfigFile = async (configFilepath) => {
+    try {
+        const mod = (await import(configFilepath));
+        return mod?.default ?? mod?.config ?? mod;
+    }
+    catch (error) {
+        log.process('error', 'config', error);
+        throw error;
+    }
+};
+let unregisterTsx;
+const setupTsx = async () => {
+    if (unregisterTsx) {
+        return;
+    }
+    try {
+        const tsx = await import('tsx/esm/api');
+        unregisterTsx = tsx.register();
+    }
+    catch (error) {
+        // @ts-expect-error Error type definition is missing 'code'
+        if (['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'].includes(error.code)) {
+            log.process('error', 'config', `Please install "tsx" to use a TypeScript configuration file`);
+            process.exit(1);
+        }
+        process.exit(1);
+    }
+};
+export const loadTSProjectConfigFile = async (configFilepath) => {
+    await setupTsx();
+    const imported = (await import(configFilepath));
+    return imported?.default ?? imported?.config;
+};

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const notSupported = "not supported";
+export declare const MEDIA_UPLOAD_CONCURRENCY = 10;

package/dist/constants.js

@@ -0,0 +1,2 @@
+export const notSupported = 'not supported';
+export const MEDIA_UPLOAD_CONCURRENCY = 10;

package/dist/crawler/storybook.d.ts

@@ -0,0 +1,51 @@
+import type { BrowserContext, BrowserType } from 'playwright-core';
+import type { Mask, ShotItem } from '../types.js';
+type ExtraShots = {
+    name?: string;
+    args?: Record<string, unknown>;
+    prefix?: string;
+    suffix?: string;
+};
+export type StoryParameters = {
+    lostpixel?: {
+        disable?: boolean;
+        threshold?: number;
+        waitBeforeScreenshot?: number;
+        stabilizeBeforeScreenshot?: boolean;
+        mask?: Mask[];
+        breakpoints?: number[];
+        args?: Record<string, unknown>;
+        extraShots?: ExtraShots[];
+        elementLocator?: string;
+    };
+    viewport?: {
+        width?: number;
+        height?: number;
+    };
+    fileName?: string;
+};
+export type Story = {
+    id: string;
+    kind: string;
+    story: string;
+    name?: string;
+    title?: string;
+    importPath?: string;
+    parameters?: StoryParameters & {
+        storyshots?: {
+            disable?: boolean;
+        };
+    };
+};
+type CrawlerResult = {
+    stories: Story[] | undefined;
+};
+export declare const getStoryBookUrl: (url: string) => string;
+export declare const getIframeUrl: (url: string) => string;
+export declare const collectStoriesViaWindowApi: (context: BrowserContext, url: string, isIframeUrl?: boolean) => Promise<CrawlerResult>;
+export declare const collectStoriesViaStoriesJson: (context: BrowserContext, url: string) => Promise<{
+    stories: Story[];
+}>;
+export declare const collectStories: (url: string) => Promise<CrawlerResult>;
+export declare const generateStorybookShotItems: (baseUrl: string, stories: Story[], mask?: Mask[], modeBreakpoints?: number[], browser?: BrowserType) => ShotItem[];
+export {};