@fohte/storybook-addon 0.1.2 → 0.1.3

package/README.md

@@ -17,8 +17,13 @@ pnpm add -D @fohte/storybook-addon
 
 # Peer dependencies
 pnpm add -D storybook vitest
+
+# Peer dependencies for ./vitest-plugin only
+pnpm add -D @storybook/addon-vitest @storycap-testrun/browser @vitest/browser-playwright
 ```
 
+`@vitest/browser-playwright` pins its own `vitest` peer to its exact version (e.g. `4.1.10` requires `vitest@4.1.10` precisely), even though this package's own `peerDependencies` range for both is the looser `^4.0.0`. Keep the two installed at the same version.
+
 ## Usage
 
 Add the addon to `.storybook/main.ts`:
@@ -69,11 +74,49 @@ initialize({
 })
 ```
 
+## Vitest plugin (`./vitest-plugin`)
+
+Builds a Vitest browser-mode project that runs Storybook stories through [`@storybook/addon-vitest`](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) and captures a screenshot of each with [`@storycap-testrun/browser`](https://github.com/reg-viz/storycap-testrun), patched to shorten storycap's hardcoded 500ms network-idle wait to 100ms.
+
+```ts
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { createStorybookProject } from '@fohte/storybook-addon/vitest-plugin'
+import { defineConfig } from 'vitest/config'
+
+const rootDir = path.dirname(fileURLToPath(import.meta.url))
+
+export default defineConfig({
+  test: {
+    projects: [
+      createStorybookProject({
+        name: 'storybook',
+        rootDir,
+        viewport: { width: 1280, height: 800 },
+        screenshotsSubdir: 'desktop',
+        setupFiles: ['./.storybook/vitest.setup.ts'],
+      }),
+    ],
+  },
+})
+```
+
+Screenshots for a project land in `<rootDir>/__screenshots__/<screenshotsSubdir>` — downstream tooling that consumes these images depends on this exact path, so treat it as a stable contract rather than an implementation detail.
+
+`storycapNetworkIdle` is also exported on its own, for building a project without `createStorybookProject`.
+
+Your `setupFiles` entry needs an `afterEach` that calls storycap's own `screenshot()` — see [`@storycap-testrun/browser`'s "Setup Screenshot Capture"](https://github.com/reg-viz/storycap-testrun/tree/main/packages/browser#2-setup-screenshot-capture) for the exact shape. Don't call `setProjectAnnotations()` there, and don't even mention that identifier in a comment: `@storybook/addon-vitest` decides whether to inject this package's checks by a plain substring search over the setup file's source text, so its mere presence silently disables every check in the project, with no error.
+
+### Check failures don't block the screenshot
+
+This package's checks run inside `@storybook/addon-vitest`'s own render phase, as part of the generated test body — before your `setupFiles`' `afterEach` (the one that calls `screenshot()`) ever runs. A failing check throws there, but Vitest still runs every registered `afterEach` after a test regardless of pass or fail, so the screenshot capture always follows, against whatever the DOM looked like when the check failed. Verified against a story with a deliberate overflow: the check failed, and `screenshot()` still produced a non-blank image showing the actual overflowing content.
+
 ## Addon `afterEach` ordering
 
 Storybook runs multiple addons' `afterEach` hooks serially, in the **reverse** of the order they're listed in `main.ts`'s `addons` array — the addon listed last runs its `afterEach` first. The consuming app's own `preview.ts`/`preview.tsx` `afterEach` runs before every addon's `afterEach`. If one hook throws, the remaining ones are skipped (fail-fast).
 
-This matters once a screenshot-capturing addon is added: to keep "capture first, then let this package's checks fail the test" working, list that addon **after** `@fohte/storybook-addon` in the `addons` array.
+This doesn't apply to `./vitest-plugin`'s screenshot capture: it isn't a Storybook addon, so it never sits in the `addons` array at all — see "Check failures don't block the screenshot" above for how that ordering actually works.
 
 ## Development
 

package/lib/vitest-plugin.d.ts

@@ -0,0 +1,54 @@
+export declare const storycapNetworkIdle: {
+    name: string;
+    transform(code: string, id: string): string | null;
+};
+export interface CreateStorybookProjectOptions {
+    /** Project name, as shown by `vitest --project <name>`. */
+    name: string;
+    /**
+     * Absolute path to the app root that the default `.storybook` config dir
+     * and the screenshot output dir are resolved against — typically
+     * `path.dirname(fileURLToPath(import.meta.url))` from the consumer's own
+     * vitest.config.ts.
+     */
+    rootDir: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Screenshots for this project are written to
+     * `<rootDir>/__screenshots__/<screenshotsSubdir>`. Downstream tooling that
+     * consumes these images depends on this exact path, so treat it as a
+     * stable contract rather than an implementation detail.
+     */
+    screenshotsSubdir: string;
+    setupFiles: string[];
+    excludeTags?: string[];
+    /**
+     * `test.maxWorkers`, applied only when `process.env.CI` is set — Vitest
+     * reads `maxWorkers` per-project rather than falling back to the root
+     * config. Screenshot capture is I/O-bound (network-idle wait, font
+     * loading, CDP metric polling), so this can exceed the CI runner's vCPU
+     * count, but the right number depends on the runner in use — tune it per
+     * consumer rather than trusting this default.
+     */
+    ciMaxWorkers?: number;
+}
+export declare function createStorybookProject({ name, rootDir, viewport, screenshotsSubdir, setupFiles, excludeTags, ciMaxWorkers, }: CreateStorybookProjectOptions): {
+    plugins: any[];
+    test: {
+        browser: {
+            enabled: boolean;
+            provider: import("vitest/node").BrowserProviderOption<import("@vitest/browser-playwright").PlaywrightProviderOptions>;
+            headless: boolean;
+            instances: {
+                browser: "chromium";
+            }[];
+        };
+        setupFiles: string[];
+        maxWorkers?: number;
+        name: string;
+    };
+};
+//# sourceMappingURL=vitest-plugin.d.ts.map

package/lib/vitest-plugin.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { storybookTest } from '@storybook/addon-vitest/vitest-plugin';
+import storycap from '@storycap-testrun/browser/vitest-plugin';
+import { playwright } from '@vitest/browser-playwright';
+// @storycap-testrun/browser ships a bundled .d.ts with its own copy of vite's
+// `Plugin` type, so it's structurally identical but nominally unrelated to
+// ours — cast to sidestep the resulting "unrelated types" error. Typing this
+// as `Plugin` (instead of `any`) reintroduces a cascading "exactOptionalPropertyTypes"
+// mismatch between vite's own `Plugin` and rollup's, so this stays `any`.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- see comment above
+function asPlugin(plugin) {
+    return plugin;
+}
+// @storycap-testrun/browser waits for 500ms of network silence before every
+// capture and exposes no option to shorten it, so every story pays that flat
+// half second per viewport. Only the floor moves: the window still restarts on
+// each resource load, and `document.fonts.ready` plus the metrics-stability
+// poll that follow it are untouched.
+const NETWORK_IDLE_MS = 100;
+// The module arrives here either as the shipped `dist/index.mjs` or as an
+// esbuild pre-bundle, which reformats the minified source but keeps the literal.
+const NETWORK_IDLE_DEFAULT = /=\s*500\s*\)\s*=>\s*new Promise\(/;
+// A Vite plugin that patches @storycap-testrun/browser's own minified
+// source. If a version bump moves the 500ms literal (or removes it), this
+// throws at config-load time instead of silently leaving the 500ms wait in
+// place — the alternative (staying quiet) would just make every capture
+// slower with no visible symptom.
+export const storycapNetworkIdle = {
+    name: 'storycap-network-idle',
+    transform(code, id) {
+        if (!id.includes('@storycap-testrun') ||
+            !code.includes('PerformanceObserver')) {
+            return null;
+        }
+        const patched = code.replace(NETWORK_IDLE_DEFAULT, (match) => match.replace('500', String(NETWORK_IDLE_MS)));
+        if (patched === code) {
+            // This throw fails config loading itself, before any test runs.
+            // eslint-disable-next-line no-restricted-syntax -- Vite plugin transform hook contract: throwing is how a plugin aborts config loading
+            throw new Error(`storycap-network-idle: no 500ms network-idle default found in ${id}. Drop this plugin if @storycap-testrun made the wait configurable, otherwise re-derive the pattern.`);
+        }
+        return patched;
+    },
+};
+export function createStorybookProject({ name, rootDir, viewport, screenshotsSubdir, setupFiles, excludeTags = [], ciMaxWorkers = 8, }) {
+    const configDir = path.join(rootDir, '.storybook');
+    const screenshotsDir = path.join(rootDir, '__screenshots__', screenshotsSubdir);
+    const maxWorkers = process.env['CI'] != null ? ciMaxWorkers : undefined;
+    // storybookTest() below returns a Promise that starts loading a real
+    // Storybook config from `configDir` as soon as it's constructed — nothing
+    // but Vite's own plugin container ever awaits that Promise, so calling
+    // this factory directly against a synthetic `rootDir` in a unit test
+    // surfaces it as an unhandled rejection instead of a useful assertion.
+    // This branch is covered by running against a real Storybook config instead.
+    return {
+        plugins: [
+            storycapNetworkIdle,
+            storybookTest({
+                configDir,
+                tags: { exclude: excludeTags },
+            }),
+            asPlugin(storycap({
+                viewport,
+                output: { dir: screenshotsDir },
+            })),
+        ],
+        test: {
+            name,
+            ...(maxWorkers !== undefined && { maxWorkers }),
+            browser: {
+                enabled: true,
+                // Pin the browser's timezone so time-dependent stories (calendar
+                // "now" indicators, relative timestamps) render identically
+                // regardless of the host machine's local timezone.
+                provider: playwright({ contextOptions: { timezoneId: 'Asia/Tokyo' } }),
+                headless: true,
+                instances: [{ browser: 'chromium' }],
+            },
+            setupFiles,
+        },
+    };
+}
+//# sourceMappingURL=vitest-plugin.js.map

package/package.json

@@ -12,6 +12,10 @@
     "./preview": {
       "types": "./lib/preview.d.ts",
       "default": "./lib/preview.js"
+    },
+    "./vitest-plugin": {
+      "types": "./lib/vitest-plugin.d.ts",
+      "default": "./lib/vitest-plugin.js"
     }
   },
   "imports": {
@@ -27,21 +31,38 @@
     "registry": "https://registry.npmjs.org/"
   },
   "peerDependencies": {
+    "@storybook/addon-vitest": "^10.0.0",
+    "@storycap-testrun/browser": "^2.0.0",
+    "@vitest/browser-playwright": "^4.0.0",
     "storybook": "^10.0.0",
     "vitest": "^4.0.0"
   },
+  "peerDependenciesMeta": {
+    "@storybook/addon-vitest": {
+      "optional": true
+    },
+    "@storycap-testrun/browser": {
+      "optional": true
+    },
+    "@vitest/browser-playwright": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "neverthrow": "8.2.0"
   },
   "devDependencies": {
     "@commitlint/cli": "21.2.1",
     "@eslint/eslintrc": "3.3.6",
-    "@fohte/eslint-config": "0.4.0",
+    "@fohte/eslint-config": "0.4.1",
     "@ninoseki/eslint-plugin-neverthrow": "0.2.0",
+    "@storybook/addon-vitest": "10.5.7",
+    "@storycap-testrun/browser": "2.1.1",
     "@tsconfig/node-lts": "24.0.0",
     "@tsconfig/strictest": "2.0.8",
     "@types/jsdom": "30.0.0",
     "@types/node": "24.13.3",
+    "@vitest/browser-playwright": "4.1.10",
     "concurrently": "10.0.4",
     "eslint": "10.6.0",
     "jsdom": "30.0.1",
@@ -51,7 +72,7 @@
     "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
-  "version": "0.1.2",
+  "version": "0.1.3",
   "scripts": {
     "clean": "rimraf lib tsconfig.tsbuildinfo",
     "prebuild": "pnpm run clean",