@snapvisor/storybook 6.1.8

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2026 Devino Solutions Inc. (Snapvisor modifications)
+Copyright 2022 Smooth Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+<p align="center">
+  <a href="https://argos-ci.com/?utm_source=github&utm_medium=logo" target="_blank">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/argos-ci/argos/main/resources/logos/github-readme-logo-dark.png">
+    <img alt="Argos" src="https://raw.githubusercontent.com/argos-ci/argos/main/resources/logos/github-readme-logo-light.png" width="360" height="70">
+  </picture>
+  </a>
+</p>
+
+<p align="center"><strong>The open source visual testing platform for AI-native engineering teams.</strong></p>
+
+# Official Argos Storybook integration
+
+[![npm version](https://img.shields.io/npm/v/@snapvisor/storybook.svg)](https://www.npmjs.com/package/@snapvisor/storybook)
+[![npm dm](https://img.shields.io/npm/dm/@snapvisor/storybook.svg)](https://www.npmjs.com/package/@snapvisor/storybook)
+[![npm dt](https://img.shields.io/npm/dt/@snapvisor/storybook.svg)](https://www.npmjs.com/package/@snapvisor/storybook)
+
+Capture and review visual changes of your [Storybook](https://storybook.js.org/) stories with Argos. It runs your stories in a real browser and uploads a screenshot of each one to Argos in your CI.
+
+Visit the [Storybook SDK documentation](https://argos-ci.com/docs/reference/storybook) for guides, the API reference, and more.
+
+## Installation
+
+```sh
+npm install --save-dev @snapvisor/storybook
+```
+
+## Usage
+
+The recommended way to run visual tests is with the [Storybook Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon). Register the Argos plugin in your Vitest config:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { argosVitestPlugin } from "@snapvisor/storybook/vitest-plugin";
+
+export default defineConfig({
+  plugins: [
+    argosVitestPlugin({
+      // Upload the screenshots to Argos only on CI.
+      uploadToArgos: process.env.CI === "true",
+    }),
+  ],
+});
+```
+
+A screenshot is captured for every story automatically. To capture additional screenshots (for example, at different steps of an interaction), call `argosScreenshot` inside a story's `play` function:
+
+```ts
+// Button.stories.tsx
+import { argosScreenshot } from "@snapvisor/storybook/vitest";
+
+export const Example: Story = {
+  play: async (ctx) => {
+    await argosScreenshot(ctx, "example");
+  },
+};
+```
+
+> Using the [Storybook Test Runner](https://storybook.js.org/docs/writing-tests/integrations/test-runner) instead? Import `argosScreenshot` from `@snapvisor/storybook/test-runner` and call it from the `postVisit` hook. See the [Test Runner quickstart](https://argos-ci.com/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart).
+
+## Links
+
+- [Official SDK Docs](https://argos-ci.com/docs/reference/storybook)
+- [Quickstart](https://argos-ci.com/docs/quickstart/storybook-quickstart)
+- [Discord](https://argos-ci.com/discord)

package/dist/test-runner.cjs

@@ -0,0 +1,5 @@
+const argosScreenshot = async (...args) => {
+  const { argosScreenshot } = await import("./test-runner.mjs");
+  return argosScreenshot(...args);
+};
+exports.argosScreenshot = argosScreenshot;

package/dist/test-runner.d.mts

@@ -0,0 +1,60 @@
+import { TestContext } from "@storybook/test-runner";
+import { ArgosScreenshotOptions as ArgosScreenshotOptions$1 } from "@snapvisor/playwright";
+import { Page } from "playwright";
+
+//#region src/utils/parameters.d.ts
+type StorybookGlobals = Record<string, any>;
+type FitToContent = {
+  /**
+   * Padding around the content in pixels.
+   * @default 16
+   */
+  padding: number;
+  /**
+   * Zoom level for the content.
+   * @default 2
+   */
+  zoom: number;
+};
+/**
+ * Argos parameters in Storybook.
+ */
+interface ArgosStorybookParameters {
+  /**
+   * Modes for the story.
+   */
+  modes?: Record<string, StorybookGlobals>;
+  /**
+   * Fit to content option for the story.
+   */
+  fitToContent?: boolean | Partial<FitToContent>;
+}
+//#endregion
+//#region src/utils/screenshot.d.ts
+type ArgosScreenshotOptions = Omit<ArgosScreenshotOptions$1, "viewports">;
+//#endregion
+//#region src/test-runner.d.ts
+/**
+ * Stabilize the UI and takes a screenshot of the application under test.
+ *
+ * @example argosScreenshot(page, context, options)
+ * @see https://argos-ci.com/docs/reference/playwright
+ */
+declare function argosScreenshot(
+/**
+ * Playwright `page` object.
+ */
+
+page: Page,
+/**
+ * Context of the test.
+ */
+
+context: TestContext,
+/**
+ * Options for the screenshot.
+ */
+
+options?: ArgosScreenshotOptions): Promise<void>;
+//#endregion
+export { type ArgosScreenshotOptions, type ArgosStorybookParameters, argosScreenshot };

package/dist/test-runner.mjs

@@ -0,0 +1,311 @@
+import { createRequire } from "node:module";
+import { getStoryContext, waitForPageReady } from "@storybook/test-runner";
+import { DO_NOT_USE_setMetadataConfig, argosScreenshot as argosScreenshot$1 } from "@snapvisor/playwright";
+import { readVersionFromPackage } from "@snapvisor/util";
+//#region src/utils/metadata.ts
+const require = createRequire(import.meta.url);
+/**
+* Get the version of the Argos Playwright SDK.
+*/
+async function getArgosStorybookVersion() {
+	return readVersionFromPackage(require.resolve("@snapvisor/storybook/package.json"));
+}
+//#endregion
+//#region src/utils/storyMetadata.ts
+function toArray(v) {
+	return Array.isArray(v) ? v : v ? [v] : [];
+}
+function mergeTags(...tags) {
+	const merged = tags.flatMap((tags) => toArray(tags));
+	return Array.from(new Set(merged)).filter((tag) => typeof tag === "string" && tag !== "");
+}
+/**
+* Return whether a story context has a play function.
+* Handles both the `play` field (plain story function) and the legacy
+* `playFunction` field present in older Storybook test-runner contexts.
+*/
+function hasPlay(storyContext) {
+	if (!storyContext || typeof storyContext !== "object") return false;
+	return "play" in storyContext && typeof storyContext.play === "function" || "playFunction" in storyContext && typeof storyContext.playFunction === "function";
+}
+/**
+* Build the story metadata object that is attached to a screenshot.
+*
+* @param story - The story shape (id, tags, play flag).
+* @param storyMode - The Storybook mode name (e.g. "dark", "mobile") as defined in `parameters.argos.modes`
+*/
+function getStoryMetadata(story, storyMode) {
+	return {
+		id: story.id,
+		tags: story.tags ?? [],
+		mode: storyMode ?? void 0,
+		play: Boolean(story.play)
+	};
+}
+//#endregion
+//#region src/utils/parameters.ts
+/**
+* Get the default viewport size from the Storybook parameters.
+*/
+function getDefaultViewport(parameters) {
+	const defaultViewport = parameters?.viewport?.defaultViewport;
+	if (defaultViewport) return getViewport(parameters, defaultViewport);
+	return null;
+}
+/**
+* Get the viewport size from the Storybook parameters.
+*/
+function getViewport(parameters, viewportName) {
+	if (typeof viewportName === "number") return {
+		width: viewportName,
+		height: 720
+	};
+	const viewports = parameters?.viewport?.viewports;
+	if (viewports && viewportName in viewports) {
+		if ("styles" in viewports[viewportName] && viewports[viewportName].styles) {
+			const width = parseInt(viewports[viewportName].styles.width, 10);
+			const height = parseInt(viewports[viewportName].styles.height, 10);
+			if (!isNaN(width) && !isNaN(height)) return {
+				width,
+				height
+			};
+		}
+	}
+	return null;
+}
+/**
+* Get the Argos parameters from the Storybook context.
+*/
+function getArgosParameters(parameters) {
+	if ("argos" in parameters && parameters.argos && typeof parameters.argos === "object") return parameters.argos;
+	if ("chromatic" in parameters && parameters.chromatic && typeof parameters.chromatic === "object") return parameters.chromatic;
+	return null;
+}
+const DEFAULT_FIT_TO_CONTENT = {
+	padding: 16,
+	zoom: 2
+};
+function getFitToContentFromParameters(parameters) {
+	const argosParameters = getArgosParameters(parameters);
+	if (argosParameters && "fitToContent" in argosParameters) {
+		if (typeof argosParameters.fitToContent === "boolean") return argosParameters.fitToContent ? DEFAULT_FIT_TO_CONTENT : null;
+		if (typeof argosParameters.fitToContent === "object" && argosParameters.fitToContent) return {
+			...DEFAULT_FIT_TO_CONTENT,
+			...argosParameters.fitToContent
+		};
+	}
+	return DEFAULT_FIT_TO_CONTENT;
+}
+//#endregion
+//#region src/utils/screenshot.ts
+/**
+* Take a screenshot in the context of a Storybook story.
+*/
+async function storybookArgosScreenshot(handler, context, options) {
+	const argosOptions = {
+		...options,
+		stabilize: options?.stabilize ?? {
+			waitForAriaBusy: false,
+			...typeof options?.stabilize === "object" ? options.stabilize : {}
+		}
+	};
+	const version = await getArgosStorybookVersion();
+	const storyUrl = `http://localhost:6006/?path=/story/${context.story.id}`;
+	const metadata = {
+		sdk: {
+			name: "@snapvisor/storybook",
+			version
+		},
+		playwrightLibraries: context.playwrightLibraries,
+		url: storyUrl,
+		test: context.test,
+		story: getStoryMetadata(context.story)
+	};
+	const modes = getArgosParameters(context.story.parameters)?.modes;
+	const allAttachments = [];
+	if (context.mode === "automatic") if (modes) for (const [name, globals] of Object.entries(modes)) {
+		if (globals.disabled) continue;
+		await handler.evaluate((name) => {
+			globalThis.__ARGOS_CURRENT_MODE = name;
+		}, name);
+		const attachments = await runHooksAndScreenshot({
+			handler,
+			context,
+			metadata,
+			options: argosOptions,
+			suffix: getModeSuffix(name),
+			mode: name,
+			globals: {
+				...context.story.globals,
+				...globals
+			}
+		});
+		allAttachments.push(...attachments);
+		await context.setViewportSize("initial");
+		await handler.evaluate(() => {
+			delete globalThis.__ARGOS_CURRENT_MODE;
+		});
+	}
+	else {
+		const attachments = await runHooksAndScreenshot({
+			handler,
+			context,
+			metadata,
+			options: argosOptions,
+			mode: null,
+			globals: context.story.globals ?? {}
+		});
+		await context.setViewportSize("initial");
+		allAttachments.push(...attachments);
+	}
+	else if (context.mode === "manual") {
+		const currentMode = await handler.evaluate(() => {
+			return globalThis.__ARGOS_CURRENT_MODE || null;
+		});
+		if (modes && !currentMode) return;
+		await markStoryAsRendered(handler, context.story.id);
+		DO_NOT_USE_setMetadataConfig({
+			...metadata,
+			story: getStoryMetadata(context.story, currentMode)
+		});
+		await argosScreenshot$1(handler, composeName(context.name, getModeSuffix(currentMode)), options);
+	}
+	await context.afterScreenshot?.({
+		handler,
+		globals: {}
+	});
+	return allAttachments;
+}
+/**
+* Run the story with the given globals.
+*/
+async function runStory(args) {
+	const { handler, globals, storyId } = args;
+	await handler.evaluate(async (globals) => {
+		if ("__ARGOS_STORYBOOK_STORY" in globalThis) {
+			const storyFn = globalThis.__ARGOS_STORYBOOK_STORY;
+			if (!storyFn) throw new Error("@snapvisor/storybook: Unable to find `__ARGOS_STORYBOOK_STORY`.");
+			const canvasElement = (() => {
+				document.getElementById("storybook-root")?.remove();
+				const canvasElement = document.createElement("div");
+				canvasElement.id = "storybook-root";
+				document.body.appendChild(canvasElement);
+				return canvasElement;
+			})();
+			await storyFn.run({
+				globals,
+				canvasElement
+			});
+			return;
+		}
+		const channel = (() => {
+			if ("__STORYBOOK_PREVIEW__" in globalThis) return globalThis.__STORYBOOK_PREVIEW__.channel;
+			return null;
+		})();
+		if (!channel) throw new Error("@snapvisor/storybook: Unable to find `__STORYBOOK_PREVIEW__`.");
+		const initialGlobals = channel.last("globalsUpdated")?.[0].initialGlobals;
+		channel.emit("updateGlobals", { globals: {
+			...initialGlobals,
+			...globals
+		} });
+	}, globals);
+	await markStoryAsRendered(handler, storyId);
+}
+/**
+* Notify Storybook that the story has been rendered.
+* It will run all the necessary hooks (like pseudo-states).
+*/
+async function markStoryAsRendered(handler, storyId) {
+	await handler.evaluate((storyId) => {
+		if ("__ARGOS_STORYBOOK_STORY" in globalThis) {
+			const addons = globalThis.__STORYBOOK_ADDONS_PREVIEW;
+			if (!addons) throw new Error("@snapvisor/storybook: Unable to find `__STORYBOOK_ADDONS_PREVIEW`.");
+			addons.getChannel().emit("storyRendered", storyId);
+		}
+	}, storyId);
+}
+/**
+* Wait for the page to be ready and take a screenshot.
+*/
+async function runHooksAndScreenshot(args) {
+	const { handler, context, options, globals, metadata, mode } = args;
+	await runStory({
+		handler,
+		globals,
+		storyId: context.story.id
+	});
+	const viewport = (globals.viewport ? getViewport(context.story.parameters, globals.viewport) : null) ?? getDefaultViewport(context.story.parameters) ?? "default";
+	await context.setViewportSize(viewport);
+	DO_NOT_USE_setMetadataConfig({
+		...metadata,
+		story: getStoryMetadata(context.story, mode),
+		viewport: viewport && viewport !== "default" ? viewport : void 0
+	});
+	await context.beforeScreenshot?.({
+		handler,
+		globals
+	});
+	return argosScreenshot$1(handler, composeName(context.name, args.suffix), options);
+}
+function getModeSuffix(mode) {
+	return mode ? ` mode-[${mode}]` : "";
+}
+function composeName(name, suffix) {
+	return name + (suffix ?? "");
+}
+//#endregion
+//#region src/test-runner.ts
+const DEFAULT_PLAYWRIGHT_VIEWPORT_SIZE = {
+	width: 1280,
+	height: 720
+};
+/**
+* Stabilize the UI and takes a screenshot of the application under test.
+*
+* @example argosScreenshot(page, context, options)
+* @see https://argos-ci.com/docs/reference/playwright
+*/
+async function argosScreenshot(page, context, options) {
+	const storyContext = await getStoryContext(page, context);
+	const fitToContent = getFitToContentFromParameters(storyContext.parameters);
+	await storybookArgosScreenshot(page, {
+		mode: "automatic",
+		name: storyContext.id,
+		playwrightLibraries: ["@storybook/test-runner"],
+		beforeScreenshot: async ({ handler }) => {
+			await waitForPageReady(handler);
+		},
+		story: {
+			id: storyContext.id,
+			tags: mergeTags(storyContext.tags, storyContext.parameters.tags),
+			play: hasPlay(storyContext),
+			parameters: storyContext.parameters,
+			globals: null
+		},
+		setViewportSize: async (size) => {
+			const actualSize = await page.viewportSize();
+			const absoluteSize = size === "default" || size === "initial" ? DEFAULT_PLAYWRIGHT_VIEWPORT_SIZE : size;
+			if (!actualSize || actualSize.height !== absoluteSize.height || actualSize.width !== absoluteSize.width) {
+				await page.setViewportSize(absoluteSize);
+				await page.waitForFunction(({ width, height }) => window.innerWidth === width && window.innerHeight === height, {
+					width: absoluteSize.width,
+					height: absoluteSize.height
+				});
+			}
+		}
+	}, applyFitToContent(options, fitToContent));
+}
+/**
+* Apply fitToContent options to the screenshot options.
+*/
+function applyFitToContent(options, fitToContent) {
+	if (!fitToContent) return options;
+	const { padding, zoom } = fitToContent;
+	return {
+		...options,
+		element: "#storybook-root",
+		argosCSS: `#storybook-root { padding: ${padding}px; width: fit-content; height: fit-content; zoom: ${zoom}; }` + (options?.argosCSS ?? "")
+	};
+}
+//#endregion
+export { argosScreenshot };

package/dist/vitest-plugin.d.mts

@@ -0,0 +1,54 @@
+import { ArgosScreenshotOptions as ArgosScreenshotOptions$1, MetadataConfig } from "@snapvisor/playwright";
+import { ArgosReporterConfig } from "@snapvisor/vitest/plugin";
+import { Plugin } from "vitest/config";
+import { BrowserCommand } from "vitest/node";
+import { Frame, Page, ViewportSize } from "playwright";
+
+//#region src/utils/parameters.d.ts
+type StorybookGlobals = Record<string, any>;
+//#endregion
+//#region src/utils/screenshot.d.ts
+type StorybookScreenshotContext<Handler extends Page | Frame> = {
+  /**
+   * - "manual" means the `argosScreenshot` has been called in the story play function.
+   * - "automatic" means the screenshot is taken automatically after each test.
+   */
+  mode: "manual" | "automatic";
+  name: string;
+  playwrightLibraries: string[];
+  test?: MetadataConfig["test"];
+  setViewportSize: (size: ViewportSize | "default" | "initial") => Promise<void>;
+  beforeScreenshot?: (input: {
+    handler: Handler;
+    globals: StorybookGlobals;
+  }) => Promise<void>;
+  afterScreenshot?: (input: {
+    handler: Handler;
+    globals: StorybookGlobals;
+  }) => Promise<void>;
+  story: {
+    id: string;
+    tags?: string[];
+    play?: boolean;
+    parameters: Record<string, any>;
+    globals: StorybookGlobals | null;
+  };
+};
+type ArgosScreenshotOptions = Omit<ArgosScreenshotOptions$1, "viewports">;
+//#endregion
+//#region src/vitest-plugin.d.ts
+type ArgosScreenshotCommandArgs = [Pick<StorybookScreenshotContext<Frame>, "name" | "story" | "test" | "mode">];
+interface ArgosVitestPluginOptions extends ArgosReporterConfig, ArgosScreenshotOptions {
+  /**
+   * Upload the report to Argos.
+   * @default true
+   */
+  uploadToArgos?: boolean;
+}
+/**
+ * Create a command for taking Argos screenshots in Vitest.
+ */
+declare const createArgosScreenshotCommand: (pluginOptions?: ArgosVitestPluginOptions) => BrowserCommand<ArgosScreenshotCommandArgs>;
+declare function argosVitestPlugin(options?: ArgosVitestPluginOptions): Plugin;
+//#endregion
+export { ArgosScreenshotCommandArgs, type ArgosScreenshotOptions, ArgosVitestPluginOptions, argosVitestPlugin, createArgosScreenshotCommand };

package/dist/vitest-plugin.mjs

@@ -0,0 +1,312 @@
+import { createRequire } from "node:module";
+import { DO_NOT_USE_setMetadataConfig, argosScreenshot } from "@snapvisor/playwright";
+import { readVersionFromPackage } from "@snapvisor/util";
+import { ArgosReporter } from "@snapvisor/vitest/plugin";
+import { fitIframeToContent, resetTesterScale, setIframeViewportSize } from "@snapvisor/vitest/internal";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/utils/metadata.ts
+const require = createRequire(import.meta.url);
+/**
+* Get the version of the Argos Playwright SDK.
+*/
+async function getArgosStorybookVersion() {
+	return readVersionFromPackage(require.resolve("@snapvisor/storybook/package.json"));
+}
+//#endregion
+//#region src/utils/storyMetadata.ts
+/**
+* Build the story metadata object that is attached to a screenshot.
+*
+* @param story - The story shape (id, tags, play flag).
+* @param storyMode - The Storybook mode name (e.g. "dark", "mobile") as defined in `parameters.argos.modes`
+*/
+function getStoryMetadata(story, storyMode) {
+	return {
+		id: story.id,
+		tags: story.tags ?? [],
+		mode: storyMode ?? void 0,
+		play: Boolean(story.play)
+	};
+}
+//#endregion
+//#region src/utils/parameters.ts
+/**
+* Get the default viewport size from the Storybook parameters.
+*/
+function getDefaultViewport(parameters) {
+	const defaultViewport = parameters?.viewport?.defaultViewport;
+	if (defaultViewport) return getViewport(parameters, defaultViewport);
+	return null;
+}
+/**
+* Get the viewport size from the Storybook parameters.
+*/
+function getViewport(parameters, viewportName) {
+	if (typeof viewportName === "number") return {
+		width: viewportName,
+		height: 720
+	};
+	const viewports = parameters?.viewport?.viewports;
+	if (viewports && viewportName in viewports) {
+		if ("styles" in viewports[viewportName] && viewports[viewportName].styles) {
+			const width = parseInt(viewports[viewportName].styles.width, 10);
+			const height = parseInt(viewports[viewportName].styles.height, 10);
+			if (!isNaN(width) && !isNaN(height)) return {
+				width,
+				height
+			};
+		}
+	}
+	return null;
+}
+/**
+* Get the Argos parameters from the Storybook context.
+*/
+function getArgosParameters(parameters) {
+	if ("argos" in parameters && parameters.argos && typeof parameters.argos === "object") return parameters.argos;
+	if ("chromatic" in parameters && parameters.chromatic && typeof parameters.chromatic === "object") return parameters.chromatic;
+	return null;
+}
+const DEFAULT_FIT_TO_CONTENT = {
+	padding: 16,
+	zoom: 2
+};
+function getFitToContentFromParameters(parameters) {
+	const argosParameters = getArgosParameters(parameters);
+	if (argosParameters && "fitToContent" in argosParameters) {
+		if (typeof argosParameters.fitToContent === "boolean") return argosParameters.fitToContent ? DEFAULT_FIT_TO_CONTENT : null;
+		if (typeof argosParameters.fitToContent === "object" && argosParameters.fitToContent) return {
+			...DEFAULT_FIT_TO_CONTENT,
+			...argosParameters.fitToContent
+		};
+	}
+	return DEFAULT_FIT_TO_CONTENT;
+}
+//#endregion
+//#region src/utils/screenshot.ts
+/**
+* Take a screenshot in the context of a Storybook story.
+*/
+async function storybookArgosScreenshot(handler, context, options) {
+	const argosOptions = {
+		...options,
+		stabilize: options?.stabilize ?? {
+			waitForAriaBusy: false,
+			...typeof options?.stabilize === "object" ? options.stabilize : {}
+		}
+	};
+	const version = await getArgosStorybookVersion();
+	const storyUrl = `http://localhost:6006/?path=/story/${context.story.id}`;
+	const metadata = {
+		sdk: {
+			name: "@snapvisor/storybook",
+			version
+		},
+		playwrightLibraries: context.playwrightLibraries,
+		url: storyUrl,
+		test: context.test,
+		story: getStoryMetadata(context.story)
+	};
+	const modes = getArgosParameters(context.story.parameters)?.modes;
+	const allAttachments = [];
+	if (context.mode === "automatic") if (modes) for (const [name, globals] of Object.entries(modes)) {
+		if (globals.disabled) continue;
+		await handler.evaluate((name) => {
+			globalThis.__ARGOS_CURRENT_MODE = name;
+		}, name);
+		const attachments = await runHooksAndScreenshot({
+			handler,
+			context,
+			metadata,
+			options: argosOptions,
+			suffix: getModeSuffix(name),
+			mode: name,
+			globals: {
+				...context.story.globals,
+				...globals
+			}
+		});
+		allAttachments.push(...attachments);
+		await context.setViewportSize("initial");
+		await handler.evaluate(() => {
+			delete globalThis.__ARGOS_CURRENT_MODE;
+		});
+	}
+	else {
+		const attachments = await runHooksAndScreenshot({
+			handler,
+			context,
+			metadata,
+			options: argosOptions,
+			mode: null,
+			globals: context.story.globals ?? {}
+		});
+		await context.setViewportSize("initial");
+		allAttachments.push(...attachments);
+	}
+	else if (context.mode === "manual") {
+		const currentMode = await handler.evaluate(() => {
+			return globalThis.__ARGOS_CURRENT_MODE || null;
+		});
+		if (modes && !currentMode) return;
+		await markStoryAsRendered(handler, context.story.id);
+		DO_NOT_USE_setMetadataConfig({
+			...metadata,
+			story: getStoryMetadata(context.story, currentMode)
+		});
+		await argosScreenshot(handler, composeName(context.name, getModeSuffix(currentMode)), options);
+	}
+	await context.afterScreenshot?.({
+		handler,
+		globals: {}
+	});
+	return allAttachments;
+}
+/**
+* Run the story with the given globals.
+*/
+async function runStory(args) {
+	const { handler, globals, storyId } = args;
+	await handler.evaluate(async (globals) => {
+		if ("__ARGOS_STORYBOOK_STORY" in globalThis) {
+			const storyFn = globalThis.__ARGOS_STORYBOOK_STORY;
+			if (!storyFn) throw new Error("@snapvisor/storybook: Unable to find `__ARGOS_STORYBOOK_STORY`.");
+			const canvasElement = (() => {
+				document.getElementById("storybook-root")?.remove();
+				const canvasElement = document.createElement("div");
+				canvasElement.id = "storybook-root";
+				document.body.appendChild(canvasElement);
+				return canvasElement;
+			})();
+			await storyFn.run({
+				globals,
+				canvasElement
+			});
+			return;
+		}
+		const channel = (() => {
+			if ("__STORYBOOK_PREVIEW__" in globalThis) return globalThis.__STORYBOOK_PREVIEW__.channel;
+			return null;
+		})();
+		if (!channel) throw new Error("@snapvisor/storybook: Unable to find `__STORYBOOK_PREVIEW__`.");
+		const initialGlobals = channel.last("globalsUpdated")?.[0].initialGlobals;
+		channel.emit("updateGlobals", { globals: {
+			...initialGlobals,
+			...globals
+		} });
+	}, globals);
+	await markStoryAsRendered(handler, storyId);
+}
+/**
+* Notify Storybook that the story has been rendered.
+* It will run all the necessary hooks (like pseudo-states).
+*/
+async function markStoryAsRendered(handler, storyId) {
+	await handler.evaluate((storyId) => {
+		if ("__ARGOS_STORYBOOK_STORY" in globalThis) {
+			const addons = globalThis.__STORYBOOK_ADDONS_PREVIEW;
+			if (!addons) throw new Error("@snapvisor/storybook: Unable to find `__STORYBOOK_ADDONS_PREVIEW`.");
+			addons.getChannel().emit("storyRendered", storyId);
+		}
+	}, storyId);
+}
+/**
+* Wait for the page to be ready and take a screenshot.
+*/
+async function runHooksAndScreenshot(args) {
+	const { handler, context, options, globals, metadata, mode } = args;
+	await runStory({
+		handler,
+		globals,
+		storyId: context.story.id
+	});
+	const viewport = (globals.viewport ? getViewport(context.story.parameters, globals.viewport) : null) ?? getDefaultViewport(context.story.parameters) ?? "default";
+	await context.setViewportSize(viewport);
+	DO_NOT_USE_setMetadataConfig({
+		...metadata,
+		story: getStoryMetadata(context.story, mode),
+		viewport: viewport && viewport !== "default" ? viewport : void 0
+	});
+	await context.beforeScreenshot?.({
+		handler,
+		globals
+	});
+	return argosScreenshot(handler, composeName(context.name, args.suffix), options);
+}
+function getModeSuffix(mode) {
+	return mode ? ` mode-[${mode}]` : "";
+}
+function composeName(name, suffix) {
+	return name + (suffix ?? "");
+}
+//#endregion
+//#region src/vitest-plugin.ts
+/**
+* Create a command for taking Argos screenshots in Vitest.
+*/
+const createArgosScreenshotCommand = (pluginOptions) => {
+	const screenshotOptions = pluginOptions ?? {};
+	return async (ctx, testContext) => {
+		const frame = await ctx.frame();
+		const fitToContent = getFitToContentFromParameters(testContext.story.parameters);
+		const after = await resetTesterScale(ctx);
+		const options = applyFitToContent(screenshotOptions, fitToContent);
+		const userBeforeScreenshot = options?.beforeScreenshot;
+		const optionsWithFit = {
+			...options,
+			beforeScreenshot: async (api) => {
+				await userBeforeScreenshot?.(api);
+				await fitIframeToContent(ctx, { fitWidth: Boolean(fitToContent) });
+			}
+		};
+		const attachments = await storybookArgosScreenshot(frame, {
+			...testContext,
+			playwrightLibraries: ["@storybook/addon-vitest"],
+			setViewportSize: async (size) => {
+				await setIframeViewportSize(ctx, size, { fullPage: screenshotOptions.fullPage ?? !fitToContent });
+			}
+		}, optionsWithFit);
+		await after();
+		return attachments;
+	};
+};
+/**
+* Apply fitToContent options to the screenshot options.
+*/
+function applyFitToContent(options, fitToContent) {
+	if (!fitToContent) return options;
+	const { padding, zoom } = fitToContent;
+	return {
+		...options,
+		element: "body",
+		argosCSS: `body { padding: ${padding}px; width: fit-content; height: fit-content; min-height: initial; zoom: ${zoom}; }` + (options?.argosCSS ?? "")
+	};
+}
+const cwd = process.cwd();
+function argosVitestPlugin(options) {
+	const { root: unresolvedRoot = "./screenshots", uploadToArgos, ...otherOptions } = options ?? {};
+	const root = resolve(cwd, unresolvedRoot);
+	const setupFile = resolve(dirname(fileURLToPath(import.meta.url)), "./vitest-setup-file.mjs");
+	return {
+		name: "@snapvisor/storybook/vitest-plugin",
+		configureVitest({ vitest, project }) {
+			project.config.setupFiles.push(setupFile);
+			if (uploadToArgos) vitest.config.reporters.push(new ArgosReporter({
+				...otherOptions,
+				root
+			}));
+		},
+		config() {
+			return {
+				optimizeDeps: { include: ["@snapvisor/storybook/internal/vitest-setup-file"] },
+				test: { browser: { commands: { argosStorybookScreenshot: createArgosScreenshotCommand({
+					...otherOptions,
+					root
+				}) } } }
+			};
+		}
+	};
+}
+//#endregion
+export { argosVitestPlugin, createArgosScreenshotCommand };

package/dist/vitest-setup-file.mjs

@@ -0,0 +1,57 @@
+import { afterEach } from "vitest";
+//#region src/utils/storyMetadata.ts
+function toArray(v) {
+	return Array.isArray(v) ? v : v ? [v] : [];
+}
+function mergeTags(...tags) {
+	const merged = tags.flatMap((tags) => toArray(tags));
+	return Array.from(new Set(merged)).filter((tag) => typeof tag === "string" && tag !== "");
+}
+/**
+* Return whether a story context has a play function.
+* Handles both the `play` field (plain story function) and the legacy
+* `playFunction` field present in older Storybook test-runner contexts.
+*/
+function hasPlay(storyContext) {
+	if (!storyContext || typeof storyContext !== "object") return false;
+	return "play" in storyContext && typeof storyContext.play === "function" || "playFunction" in storyContext && typeof storyContext.playFunction === "function";
+}
+//#endregion
+//#region src/vitest.ts
+/**
+* Setup Argos hooks for Vitest.
+*/
+function setupArgos(api) {
+	api.afterEach(async (ctx) => {
+		const story = "story" in ctx ? ctx.story : null;
+		if (!story) throw new Error(`@snapvisor/storybook/vitest-plugin should be used with @storybook/addon-vitest/vitest-plugin`);
+		const { server } = await import("vitest/browser");
+		globalThis.__ARGOS_STORYBOOK_STORY = story;
+		await server.commands.argosStorybookScreenshot({
+			mode: "automatic",
+			name: story.id,
+			story: {
+				id: story.id,
+				tags: mergeTags(story.tags, story.parameters.tags),
+				play: hasPlay(story),
+				parameters: story.parameters,
+				globals: story.globals
+			},
+			test: {
+				id: ctx.task.id,
+				title: ctx.task.name,
+				titlePath: [ctx.task.file.name, ctx.task.name],
+				location: {
+					line: ctx.task.location?.line ?? 1,
+					column: ctx.task.location?.column ?? 1,
+					file: ctx.task.file.filepath
+				}
+			}
+		});
+	});
+}
+//#endregion
+//#region src/vitest-setup-file.ts
+setupArgos({ afterEach });
+//#endregion
+export {};

package/dist/vitest.d.mts

@@ -0,0 +1,62 @@
+import * as vitest from "vitest";
+import { ArgosAttachment, ArgosScreenshotOptions as ArgosScreenshotOptions$1, MetadataConfig } from "@snapvisor/playwright";
+import { Frame, Page, ViewportSize } from "playwright";
+//#region src/utils/parameters.d.ts
+type StorybookGlobals = Record<string, any>;
+//#endregion
+//#region src/utils/screenshot.d.ts
+type StorybookScreenshotContext<Handler extends Page | Frame> = {
+  /**
+   * - "manual" means the `argosScreenshot` has been called in the story play function.
+   * - "automatic" means the screenshot is taken automatically after each test.
+   */
+  mode: "manual" | "automatic";
+  name: string;
+  playwrightLibraries: string[];
+  test?: MetadataConfig["test"];
+  setViewportSize: (size: ViewportSize | "default" | "initial") => Promise<void>;
+  beforeScreenshot?: (input: {
+    handler: Handler;
+    globals: StorybookGlobals;
+  }) => Promise<void>;
+  afterScreenshot?: (input: {
+    handler: Handler;
+    globals: StorybookGlobals;
+  }) => Promise<void>;
+  story: {
+    id: string;
+    tags?: string[];
+    play?: boolean;
+    parameters: Record<string, any>;
+    globals: StorybookGlobals | null;
+  };
+};
+type ArgosScreenshotOptions = Omit<ArgosScreenshotOptions$1, "viewports">;
+//#endregion
+//#region src/vitest-plugin.d.ts
+type ArgosScreenshotCommandArgs = [Pick<StorybookScreenshotContext<Frame>, "name" | "story" | "test" | "mode">];
+//#endregion
+//#region src/vitest.d.ts
+declare module "vitest/browser" {
+  interface BrowserCommands {
+    argosStorybookScreenshot: (...args: ArgosScreenshotCommandArgs) => Promise<ArgosAttachment[]>;
+  }
+}
+/**
+ * Setup Argos hooks for Vitest.
+ */
+declare function setupArgos(api: {
+  afterEach: typeof vitest.afterEach;
+}): void;
+/**
+ * Take an Argos screenshot of a story in Vitest.
+ */
+declare function argosScreenshot(story: {
+  parameters: Record<string, any>;
+  globals: StorybookGlobals | null;
+  id: string;
+  tags?: string[];
+  play?: unknown;
+}, name: string): Promise<void>;
+//#endregion
+export { type ArgosScreenshotOptions, argosScreenshot, setupArgos };

package/dist/vitest.mjs

@@ -0,0 +1,82 @@
+//#region src/utils/storyMetadata.ts
+function toArray(v) {
+	return Array.isArray(v) ? v : v ? [v] : [];
+}
+function mergeTags(...tags) {
+	const merged = tags.flatMap((tags) => toArray(tags));
+	return Array.from(new Set(merged)).filter((tag) => typeof tag === "string" && tag !== "");
+}
+/**
+* Return whether a story context has a play function.
+* Handles both the `play` field (plain story function) and the legacy
+* `playFunction` field present in older Storybook test-runner contexts.
+*/
+function hasPlay(storyContext) {
+	if (!storyContext || typeof storyContext !== "object") return false;
+	return "play" in storyContext && typeof storyContext.play === "function" || "playFunction" in storyContext && typeof storyContext.playFunction === "function";
+}
+//#endregion
+//#region src/vitest.ts
+/**
+* Setup Argos hooks for Vitest.
+*/
+function setupArgos(api) {
+	api.afterEach(async (ctx) => {
+		const story = "story" in ctx ? ctx.story : null;
+		if (!story) throw new Error(`@snapvisor/storybook/vitest-plugin should be used with @storybook/addon-vitest/vitest-plugin`);
+		const { server } = await import("vitest/browser");
+		globalThis.__ARGOS_STORYBOOK_STORY = story;
+		await server.commands.argosStorybookScreenshot({
+			mode: "automatic",
+			name: story.id,
+			story: {
+				id: story.id,
+				tags: mergeTags(story.tags, story.parameters.tags),
+				play: hasPlay(story),
+				parameters: story.parameters,
+				globals: story.globals
+			},
+			test: {
+				id: ctx.task.id,
+				title: ctx.task.name,
+				titlePath: [ctx.task.file.name, ctx.task.name],
+				location: {
+					line: ctx.task.location?.line ?? 1,
+					column: ctx.task.location?.column ?? 1,
+					file: ctx.task.file.filepath
+				}
+			}
+		});
+	});
+}
+/**
+* Take an Argos screenshot of a story in Vitest.
+*/
+async function argosScreenshot(story, name) {
+	if (!await checkIsVitestEnv()) return;
+	const { server } = await import("vitest/browser");
+	await server.commands.argosStorybookScreenshot({
+		mode: "manual",
+		name: `${story.id}/${name}`,
+		story: {
+			id: story.id,
+			tags: mergeTags(story.tags, story.parameters.tags),
+			play: hasPlay(story),
+			parameters: story.parameters,
+			globals: story.globals
+		}
+	});
+}
+/**
+* Check if we are running in a Vitest environment.
+*/
+async function checkIsVitestEnv() {
+	try {
+		await import("vitest");
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { argosScreenshot, setupArgos };

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@snapvisor/storybook",
+  "description": "Visual testing for Storybook test runner.",
+  "version": "6.1.8",
+  "author": "Smooth Code",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/argos-ci/argos-javascript.git",
+    "directory": "packages/storybook"
+  },
+  "homepage": "https://argos-ci.com/docs/reference/storybook",
+  "keywords": [
+    "storybook",
+    "storybook-addon",
+    "screenshot",
+    "capture",
+    "testing",
+    "visual testing",
+    "argos",
+    "regression",
+    "visual regression"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    "./test-runner": {
+      "types": "./dist/test-runner.d.mts",
+      "import": "./dist/test-runner.mjs",
+      "require": "./dist/test-runner.cjs",
+      "default": "./dist/test-runner.cjs"
+    },
+    "./vitest": {
+      "types": "./dist/vitest.d.mts",
+      "import": "./dist/vitest.mjs",
+      "default": "./dist/vitest.mjs"
+    },
+    "./vitest-plugin": {
+      "types": "./dist/vitest-plugin.d.mts",
+      "import": "./dist/vitest-plugin.mjs",
+      "default": "./dist/vitest-plugin.mjs"
+    },
+    "./internal/vitest-setup-file": "./dist/vitest-setup-file.mjs",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@snapvisor/core": "6.6.2",
+    "@snapvisor/playwright": "7.3.7",
+    "@snapvisor/util": "4.0.4",
+    "@snapvisor/vitest": "0.3.2"
+  },
+  "devDependencies": {
+    "@snapvisor/cli": "6.4.1",
+    "@snapvisor/util": "workspace:*",
+    "@storybook/addon-docs": "^10.4.6",
+    "@storybook/addon-links": "^10.4.6",
+    "@storybook/addon-themes": "^10.4.6",
+    "@storybook/addon-vitest": "^10.4.6",
+    "@storybook/react-vite": "^10.4.6",
+    "@storybook/test-runner": "^0.24.4",
+    "@types/node": "catalog:",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser": "^4.1.9",
+    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/coverage-v8": "^4.1.9",
+    "@vitest/ui": "^4.1.9",
+    "http-server": "^14.1.1",
+    "playwright": "^1.61.0",
+    "prop-types": "^15.8.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "storybook": "^10.4.6",
+    "storybook-addon-pseudo-states": "^10.4.6",
+    "vitest": "catalog:",
+    "wait-on": "^9.0.10"
+  },
+  "scripts": {
+    "build": "tsdown && cp ./src/test-runner.cjs ./dist",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "test-storybook": "cross-env NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules test-storybook",
+    "install-playwright": "playwright install chromium --with-deps",
+    "argos-upload-runner": "argos upload screenshots --build-name \"argos-storybook-test-runner-e2e-node-$NODE_VERSION-$OS\"",
+    "serve-storybook": "http-server storybook-static --port 6006 --silent",
+    "wait-storybook": "wait-on tcp:127.0.0.1:6006",
+    "build-e2e-runner": "pnpm run build-storybook --quiet && pnpm run install-playwright",
+    "build-e2e": "pnpm run build-e2e-runner",
+    "test-e2e-runner": "pnpm run test-storybook && pnpm run argos-upload-runner",
+    "test-e2e-vitest": "vitest run",
+    "e2e-runner": "pnpm dlx concurrently -k -s first -n \"SB,TEST\" -c \"magenta,blue\" \"pnpm run serve-storybook\" \"pnpm run wait-storybook && pnpm run test-e2e-runner\"",
+    "e2e-vitest": "cross-env BUILD_NAME=\"argos-storybook-vitest-e2e-node-$NODE_VERSION-$OS\" UPLOAD_TO_ARGOS=true pnpm run test-e2e-vitest",
+    "e2e": "pnpm run e2e-runner && rm -rf ./screenshots && pnpm run e2e-vitest",
+    "check-types": "tsc",
+    "check-format": "prettier --check --ignore-unknown --ignore-path=./.gitignore --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
+    "lint": "eslint ."
+  },
+  "gitHead": "7c74326b53f6f513ac4087385b88e8fbd7e92eac"
+}