@crvy/strybk 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.6] - 2026-08-24
+
+### Added
+
+- Add creevey regex deserialization helpers
+- Add creevey skip-option matching
+- Resolve creevey story params from extracted stories
+- Extract merged storybook params at runtime
+- Render captureElement/skip-aware generated tests
+- Add creevey fixture and worker story cache
+
+### Changed
+
+- Drop generate-time creevey source-parsing
+- Unexport shouldSkipByOption helper
+
+### Documentation
+
+- Add captureElement + runtime creevey resolution design spec
+- Add captureElement runtime-resolution implementation plan
+- Document creevey capture/skip/ignoreElements and Playwright prerequisite
+- Add migration note and clarify skip in-dimension matching
+
+### Testing
+
+- Cover _stories and creevey fixture wiring
+## [0.0.5] - 2026-07-06
+
+### Added
+
+- **cli:** Add --help/-h flag to print usage and exit 0
 ## [0.0.4] - 2026-07-03
 
 ### Other

package/README.md

@@ -36,6 +36,35 @@ export default defineConfig({
 });
 ```
 
+## Generated tests
+
+Each generated spec renders a Playwright test per story. At runtime, `parameters.creevey` (read from the running Storybook, merged across global / kind / story levels) drives capture and skip behavior — no Storybook addon required:
+
+- `captureElement: '<selector>'` — captures `page.locator('<selector>')`.
+- `captureElement: null` (or unset) — captures the viewport.
+- `skip: { '<reason>': { in, kinds, stories } }` — marks the test skipped with `<reason>`. Note: `in` matches the **Playwright project name** (not the browser engine), so with the default project name `chromium`, a rule like `{ in: 'chrome' }` won't match — name your Playwright projects to line up with your `in:` rules, or scope rules via `kinds`/`stories`.
+- `ignoreElements: '<selector>' | ['<selector>']` — masks those elements via `toHaveScreenshot({ mask })`.
+
+Example:
+
+```ts
+// stories/MyModal.stories.tsx
+export default {
+  title: "MyModal",
+  parameters: { creevey: { captureElement: "#storybook-root" } },
+};
+
+export const Default = {
+  parameters: { creevey: { ignoreElements: ".timestamp" } },
+};
+```
+
+**Prerequisites for running specs:** `@playwright/test` (peer dependency) and browser binaries (`npx playwright install`). The `crvy-strybk generate` command itself needs neither — only a running Storybook to fetch `index.json`.
+
+## Upgrading from 0.0.x
+
+`metadataExtractors` has been removed. `skip` and `captureElement` now resolve automatically at runtime — remove any `metadataExtractors: ["creevey"]` line from your `strybk.config.ts` and re-run `crvy-strybk generate`. Skipped stories now appear as `skipped` in Playwright reports rather than being omitted from the spec file.
+
 ## Changelog
 
 Preview the next changelog entry:

package/dist/src/cli.d.ts

@@ -4,6 +4,9 @@ export interface GenerateCliArgs {
     configPath: string;
     dryRun: boolean;
 }
+export declare const HELP_TEXT = "Usage: crvy-strybk generate --config <path> [options]\n\nGenerate Playwright screenshot spec files from a running Storybook index.\n\nThe Storybook server must be running at the configured `storybookUrl` so that\nindex.json can be fetched at generate time.\n\nOptions:\n  --config <path>     Path to strybk.config.ts (required)\n  --dry-run           Compute outputs without writing files\n  -h, --help          Show this help message\n";
+export declare function printHelp(): void;
+export declare function wantsHelp(argv: string[]): boolean;
 export declare function parseCliArgs(argv: string[]): GenerateCliArgs;
 export declare function runCli(argv: string[]): Promise<Array<{
     outputPath: string;

package/dist/src/cli.js

@@ -99,6 +99,24 @@ const writeGeneratedFiles = (outputs) => {
         writeFileSync(output.outputPath, output.content);
     }
 };
+export const HELP_TEXT = `Usage: crvy-strybk generate --config <path> [options]
+
+Generate Playwright screenshot spec files from a running Storybook index.
+
+The Storybook server must be running at the configured \`storybookUrl\` so that
+index.json can be fetched at generate time.
+
+Options:
+  --config <path>     Path to strybk.config.ts (required)
+  --dry-run           Compute outputs without writing files
+  -h, --help          Show this help message
+`;
+export function printHelp() {
+    console.log(HELP_TEXT);
+}
+export function wantsHelp(argv) {
+    return argv.includes("--help") || argv.includes("-h");
+}
 export function parseCliArgs(argv) {
     const [command, ...options] = argv;
     if (command !== "generate") {
@@ -155,6 +173,10 @@ export async function runCli(argv) {
     return outputs;
 }
 export async function main(argv = process.argv.slice(2)) {
+    if (wantsHelp(argv)) {
+        printHelp();
+        return;
+    }
     try {
         const outputs = await runCli(argv);
         const dryRun = argv.includes("--dry-run");

package/dist/src/config.d.ts

@@ -9,6 +9,5 @@ export interface StrybkConfig {
     }) => string;
     generatedRegionName?: string;
     deleteOrphans?: boolean;
-    metadataExtractors?: "creevey"[];
 }
 export declare function defineConfig(config: StrybkConfig): StrybkConfig;

package/dist/src/config.js

@@ -2,7 +2,6 @@ export function defineConfig(config) {
     return {
         generatedRegionName: "auto-screenshots",
         deleteOrphans: true,
-        metadataExtractors: [],
         ...config,
     };
 }

package/dist/src/generate/index.js

@@ -1,6 +1,4 @@
-import { readFileSync } from "node:fs";
 import { discoverStoryFiles } from "./discover.js";
-import { extractCreeveyMetadata, FILE_POLICY_KEY } from "./metadata.js";
 import { renderScreenshotSpec } from "./render.js";
 const normalizePath = (value) => value.replace(/\\/gu, "/").replace(/^\.\//u, "");
 const matchesByImportPath = (filePath, importPath) => {
@@ -13,40 +11,20 @@ const resolveStoryTitle = (storyFile, indexEntries) => {
     return pathMatch?.title ?? null;
 };
 const escapeForRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-const toStoryIdSegment = (value) => value
-    .replace(/([a-z0-9])([A-Z])/gu, "$1-$2")
-    .replace(/[^a-zA-Z0-9]+/gu, "-")
-    .replace(/^-+|-+$/gu, "")
-    .toLowerCase();
-const isStorySkipped = (story, storyMetadata) => {
-    if (story.exportName !== undefined) {
-        return storyMetadata[story.exportName]?.skip === true;
-    }
-    const storyIdSegment = story.id.split("--").slice(1).join("--");
-    return Object.entries(storyMetadata).some(([exportName, policy]) => policy.skip === true && toStoryIdSegment(exportName) === storyIdSegment);
-};
 export async function generateScreenshots(args) {
     const storyFiles = await discoverStoryFiles(args.config.storyGlobs, args.configDir === undefined ? {} : { cwd: args.configDir });
     const generatedRegionName = args.config.generatedRegionName ?? "auto-screenshots";
     const manualRegionPattern = new RegExp(`// @generated-end ${escapeForRegExp(generatedRegionName)}\\s*([\\s\\S]*)$`, "u");
-    const shouldExtractCreeveyMetadata = args.config.metadataExtractors?.includes("creevey") ?? false;
     return storyFiles.flatMap((storyFile) => {
         const title = resolveStoryTitle(storyFile, args.indexEntries);
         if (title === null) {
             return [];
         }
         const stories = args.indexEntries.filter((entry) => entry.title === title);
-        const storyMetadata = shouldExtractCreeveyMetadata
-            ? extractCreeveyMetadata(readFileSync(storyFile.filePath, "utf8"))
-            : {};
-        const isFileSkipped = storyMetadata[FILE_POLICY_KEY]?.skip === true;
-        const filteredStories = isFileSkipped
-            ? []
-            : stories.filter((story) => !isStorySkipped(story, storyMetadata));
         const outputPath = args.config.resolveSpecPath({ storyFilePath: storyFile.filePath });
         const existing = args.readExistingFile?.(outputPath) ?? null;
         const manualRegion = existing?.match(manualRegionPattern)?.[1]?.trim() ?? "";
-        if (filteredStories.length === 0 && manualRegion.length === 0) {
+        if (stories.length === 0 && manualRegion.length === 0) {
             return [];
         }
         return [
@@ -55,7 +33,7 @@ export async function generateScreenshots(args) {
                 content: renderScreenshotSpec({
                     config: args.config,
                     title,
-                    stories: filteredStories,
+                    stories,
                     manualRegion,
                 }),
             },

package/dist/src/generate/render.js

@@ -1,8 +1,17 @@
 const escapeSingleQuotes = (value) => value.replace(/'/gu, "\\'");
+const renderTest = (story) => [
+    `  test('${escapeSingleQuotes(story.name)}', async ({ sharedPage, creevey }) => {`,
+    `    const { skip, reason, captureElement, ignoreElements } = creevey.params('${story.id}');`,
+    `    test.skip(skip, reason);`,
+    `    await switchStory(sharedPage, '${story.id}');`,
+    `    const target = captureElement ? sharedPage.locator(captureElement) : sharedPage;`,
+    `    await expect(target).toHaveScreenshot({`,
+    `      mask: ignoreElements.map((selector) => sharedPage.locator(selector)),`,
+    `    });`,
+    `  });`,
+].join("\n");
 export function renderScreenshotSpec(args) {
     const generatedRegionName = args.config.generatedRegionName ?? "auto-screenshots";
-    const tests = args.stories
-        .map((story) => `  test('${escapeSingleQuotes(story.name)}', async ({ sharedPage }) => {\n    await switchStory(sharedPage, '${story.id}');\n    await expect(sharedPage).toHaveScreenshot();\n  });`)
-        .join("\n\n");
+    const tests = args.stories.map(renderTest).join("\n\n");
     return `import { test, expect, switchStory } from '@crvy/strybk';\n\n// @generated-begin ${generatedRegionName}\ntest.describe('${escapeSingleQuotes(args.title)}', () => {\n${tests}\n});\n// @generated-end ${generatedRegionName}\n\n${args.manualRegion}`;
 }

package/dist/src/playwright/fixtures.d.ts

@@ -1,6 +1,8 @@
 import type { Page, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions, TestType } from "@playwright/test";
+import type { CreeveyApi } from "../storybook/creeveyParams.js";
 type StrybkFixtures = {
     sharedPage: Page;
+    creevey: CreeveyApi;
 };
 type PublicStrybkTest = TestType<PlaywrightTestArgs & PlaywrightTestOptions & StrybkFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
 type StrybkFixtureHandles = {

package/dist/src/playwright/fixtures.js

@@ -1,4 +1,6 @@
+import { resolveCreeveyStory } from "../storybook/creeveyParams.js";
 import { createChannelDriver } from "../storybook/channelDriver.js";
+import { extractStories } from "../storybook/extract.js";
 import { loadPlaywrightTestRuntime } from "./runtime.js";
 const animationDisablerStyles = [
     "*, *::before, *::after {",
@@ -67,6 +69,13 @@ export const createStrybkFixtures = () => {
             },
             { scope: "worker" },
         ],
+        _stories: [
+            async ({ _workerPage }, use) => {
+                const stories = await extractStories(_workerPage);
+                await use(stories);
+            },
+            { scope: "worker" },
+        ],
         sharedPage: async ({ _workerPage }, use, testInfo) => {
             const storybookGlobals = getStorybookGlobals(testInfo);
             if (storybookGlobals !== undefined) {
@@ -76,6 +85,13 @@ export const createStrybkFixtures = () => {
             await use(_workerPage);
             await restoreSharedPageBaseline(_workerPage, testInfo.project.use.baseURL);
         },
+        creevey: async ({ _stories }, use, testInfo) => {
+            const browser = testInfo.project.name;
+            const api = {
+                params: (storyId) => resolveCreeveyStory(_stories, storyId, browser),
+            };
+            await use(api);
+        },
     });
     return {
         expect,

package/dist/src/playwright/index.d.ts

@@ -1,5 +1,6 @@
 export { switchStory } from "./switchStory.js";
 export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & {
     sharedPage: import("playwright-core").Page;
+    creevey: import("../storybook/creeveyParams.js").CreeveyApi;
 }, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions>;
 export declare const expect: import("playwright/test").Expect<{}>;

package/dist/src/storybook/creeveyParams.d.ts

@@ -0,0 +1,45 @@
+export interface SerializedRegExp {
+    __regexp: true;
+    source: string;
+    flags: string;
+}
+export declare const isSerializedRegExp: (value: unknown) => value is SerializedRegExp;
+export declare const deserializeRegExp: ({ source, flags }: SerializedRegExp) => RegExp;
+export interface SkipOption {
+    in?: string | string[] | RegExp | SerializedRegExp;
+    kinds?: string | string[] | RegExp | SerializedRegExp;
+    stories?: string | string[] | RegExp | SerializedRegExp;
+}
+export type SkipOptions = boolean | string | Record<string, SkipOption | SkipOption[]>;
+export declare const shouldSkip: (browser: string, meta: {
+    title: string;
+    name: string;
+}, skipOptions: SkipOptions) => boolean | string;
+export interface CreeveyStoryParams {
+    captureElement?: string | null;
+    ignoreElements?: string | string[] | null;
+    skip?: SkipOptions;
+}
+export interface NormalizedCreeveyParams {
+    skip: boolean;
+    reason?: string;
+    captureElement: string | null;
+    ignoreElements: string[];
+}
+export interface StoriesRaw {
+    [storyId: string]: {
+        title: string;
+        name: string;
+        parameters?: {
+            creevey?: CreeveyStoryParams;
+        };
+    };
+}
+export interface CreeveyApi {
+    params(storyId: string): NormalizedCreeveyParams;
+}
+export declare const normalizeCreeveyParams: (raw: CreeveyStoryParams | undefined, browser: string, meta: {
+    title: string;
+    name: string;
+}) => NormalizedCreeveyParams;
+export declare const resolveCreeveyStory: (stories: StoriesRaw, storyId: string, browser: string) => NormalizedCreeveyParams;

package/dist/src/storybook/creeveyParams.js

@@ -0,0 +1,63 @@
+export const isSerializedRegExp = (value) => typeof value === "object" && value !== null && Reflect.get(value, "__regexp") === true;
+export const deserializeRegExp = ({ source, flags }) => new RegExp(source, flags);
+const matchBy = (pattern, value) => (typeof pattern === "string" && pattern === value) ||
+    (Array.isArray(pattern) && pattern.includes(value)) ||
+    (pattern instanceof RegExp && pattern.test(value)) ||
+    (isSerializedRegExp(pattern) && deserializeRegExp(pattern).test(value)) ||
+    pattern === undefined;
+const shouldSkipByOption = (browser, meta, skipOption, reason) => {
+    if (Array.isArray(skipOption)) {
+        for (const option of skipOption) {
+            const result = shouldSkipByOption(browser, meta, option, reason);
+            if (result !== false) {
+                return result;
+            }
+        }
+        return false;
+    }
+    const { in: browsers, kinds, stories } = skipOption;
+    const skipByBrowser = matchBy(browsers, browser);
+    const skipByKind = matchBy(kinds, meta.title);
+    const skipByStory = matchBy(stories, meta.name);
+    return skipByBrowser && skipByKind && skipByStory && reason;
+};
+export const shouldSkip = (browser, meta, skipOptions) => {
+    if (typeof skipOptions !== "object") {
+        return skipOptions;
+    }
+    for (const reason of Object.keys(skipOptions)) {
+        const result = shouldSkipByOption(browser, meta, skipOptions[reason], reason);
+        if (result !== false) {
+            return result;
+        }
+    }
+    return false;
+};
+const toArray = (value) => {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+};
+export const normalizeCreeveyParams = (raw, browser, meta) => {
+    if (raw === undefined) {
+        return { skip: false, captureElement: null, ignoreElements: [] };
+    }
+    const skipResult = raw.skip === undefined ? false : shouldSkip(browser, meta, raw.skip);
+    return {
+        skip: skipResult !== false,
+        reason: typeof skipResult === "string" ? skipResult : undefined,
+        captureElement: raw.captureElement === undefined ? null : raw.captureElement,
+        ignoreElements: toArray(raw.ignoreElements),
+    };
+};
+export const resolveCreeveyStory = (stories, storyId, browser) => {
+    const story = stories[storyId];
+    if (story === undefined) {
+        throw new Error(`Story '${storyId}' not found in extracted Storybook stories`);
+    }
+    return normalizeCreeveyParams(story.parameters?.creevey, browser, {
+        title: story.title,
+        name: story.name,
+    });
+};

package/dist/src/storybook/extract.d.ts

@@ -0,0 +1,4 @@
+import type { Page } from "@playwright/test";
+import type { StoriesRaw } from "./creeveyParams.js";
+export declare const toStoriesRaw: (value: unknown) => StoriesRaw;
+export declare const extractStories: (page: Page) => Promise<StoriesRaw>;

package/dist/src/storybook/extract.js

@@ -0,0 +1,11 @@
+const isStoriesRaw = (value) => typeof value === "object" && value !== null;
+export const toStoriesRaw = (value) => {
+    if (!isStoriesRaw(value)) {
+        throw new Error("Storybook preview not available; is Storybook fully loaded?");
+    }
+    return value;
+};
+export const extractStories = async (page) => toStoriesRaw(await page.evaluate(() => {
+    const preview = window.__STORYBOOK_PREVIEW__;
+    return preview?.extract?.();
+}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvy/strybk",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Generator-first Playwright screenshot testing for Storybook.",
   "keywords": [
     "crvy",

package/dist/src/generate/metadata.d.ts

@@ -1,5 +0,0 @@
-export interface StoryPolicy {
-    skip?: boolean;
-}
-export declare const FILE_POLICY_KEY = "__file__";
-export declare function extractCreeveyMetadata(source: string): Record<string, StoryPolicy>;

package/dist/src/generate/metadata.js

@@ -1,124 +0,0 @@
-export const FILE_POLICY_KEY = "__file__";
-const skipWhitespace = (source, startIndex) => {
-    let index = startIndex;
-    while (/\s/u.test(source[index] ?? "")) {
-        index += 1;
-    }
-    return index;
-};
-const extractObjectLiteral = (source, startIndex) => {
-    const objectStartIndex = skipWhitespace(source, startIndex);
-    if (source[objectStartIndex] !== "{") {
-        return null;
-    }
-    let depth = 0;
-    let inSingleQuote = false;
-    let inDoubleQuote = false;
-    let inTemplateString = false;
-    let inLineComment = false;
-    let inBlockComment = false;
-    for (let index = objectStartIndex; index < source.length; index += 1) {
-        const char = source[index] ?? "";
-        const nextChar = source[index + 1] ?? "";
-        const previousChar = source[index - 1] ?? "";
-        if (inLineComment) {
-            if (char === "\n") {
-                inLineComment = false;
-            }
-            continue;
-        }
-        if (inBlockComment) {
-            if (previousChar === "*" && char === "/") {
-                inBlockComment = false;
-            }
-            continue;
-        }
-        if (inSingleQuote) {
-            if (char === "'" && previousChar !== "\\") {
-                inSingleQuote = false;
-            }
-            continue;
-        }
-        if (inDoubleQuote) {
-            if (char === '"' && previousChar !== "\\") {
-                inDoubleQuote = false;
-            }
-            continue;
-        }
-        if (inTemplateString) {
-            if (char === "`" && previousChar !== "\\") {
-                inTemplateString = false;
-            }
-            continue;
-        }
-        if (char === "/" && nextChar === "/") {
-            inLineComment = true;
-            index += 1;
-            continue;
-        }
-        if (char === "/" && nextChar === "*") {
-            inBlockComment = true;
-            index += 1;
-            continue;
-        }
-        if (char === "'") {
-            inSingleQuote = true;
-            continue;
-        }
-        if (char === '"') {
-            inDoubleQuote = true;
-            continue;
-        }
-        if (char === "`") {
-            inTemplateString = true;
-            continue;
-        }
-        if (char === "{") {
-            depth += 1;
-            continue;
-        }
-        if (char === "}") {
-            depth -= 1;
-            if (depth === 0) {
-                return source.slice(objectStartIndex, index + 1);
-            }
-        }
-    }
-    return null;
-};
-const extractSkipPolicy = (source, scope) => {
-    if (source === null) {
-        return undefined;
-    }
-    const pattern = scope === "parameters"
-        ? /\bcreevey\s*:\s*\{[\s\S]*?\bskip\s*:\s*(true|false)\b/u
-        : /\bparameters\s*:\s*\{[\s\S]*?\bcreevey\s*:\s*\{[\s\S]*?\bskip\s*:\s*(true|false)\b/u;
-    const skipMatch = source.match(pattern);
-    return skipMatch ? { skip: skipMatch[1] === "true" } : undefined;
-};
-const collectPolicies = (source, pattern, scope) => Array.from(source.matchAll(pattern)).flatMap((match) => {
-    const index = match.index ?? 0;
-    const policy = extractSkipPolicy(extractObjectLiteral(source, index + match[0].length), scope);
-    return policy ? [[index, match[1], policy]] : [];
-});
-export function extractCreeveyMetadata(source) {
-    const storyPolicies = [
-        ...collectPolicies(source, /(\w+)\.parameters\s*=/gu, "parameters"),
-        ...collectPolicies(source, /export\s+const\s+(\w+)(?:\s*:\s*[^=]+)?\s*=/gu, "object"),
-    ];
-    const constPolicies = new Map(collectPolicies(source, /const\s+(\w+)(?:\s*:\s*[^=]+)?\s*=/gu, "object").map(([, name, policy]) => [name, policy]));
-    const filePolicies = [
-        ...Array.from(source.matchAll(/export\s+default\b/gu)).flatMap((match) => {
-            const index = match.index ?? 0;
-            const policy = extractSkipPolicy(extractObjectLiteral(source, index + match[0].length), "object");
-            return policy ? [[index, FILE_POLICY_KEY, policy]] : [];
-        }),
-        ...Array.from(source.matchAll(/export\s+default\s+(\w+)\s*;/gu)).flatMap((match) => {
-            const policy = constPolicies.get(match[1]);
-            return policy ? [[match.index ?? 0, FILE_POLICY_KEY, policy]] : [];
-        }),
-    ];
-    return Object.fromEntries([...storyPolicies, ...filePolicies]
-        .sort((left, right) => left[0] - right[0])
-        .map(([, name, policy]) => [name, policy]));
-}