@argos-ci/storybook 5.2.15 → 5.3.0

package/dist/test-runner.cjs

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

package/dist/{test-runner.d.ts → test-runner.d.mts}

@@ -1,36 +1,39 @@
-import { TestContext } from '@storybook/test-runner';
-import { ArgosScreenshotOptions as ArgosScreenshotOptions$1 } from '@argos-ci/playwright';
-import { Page } from 'playwright';
+import { TestContext } from "@storybook/test-runner";
+import { ArgosScreenshotOptions as ArgosScreenshotOptions$1 } from "@argos-ci/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;
+  /**
+   * 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>;
+  /**
+   * 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.
  *
@@ -41,14 +44,17 @@ declare function argosScreenshot(
 /**
  * Playwright `page` object.
  */
-page: Page, 
+
+page: Page,
 /**
  * Context of the test.
  */
-context: TestContext, 
+
+context: TestContext,
 /**
  * Options for the screenshot.
  */
-options?: ArgosScreenshotOptions): Promise<void>;
 
-export { type ArgosScreenshotOptions, type ArgosStorybookParameters, argosScreenshot };
+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 "@argos-ci/playwright";
+import { readVersionFromPackage } from "@argos-ci/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("@argos-ci/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: "@argos-ci/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("@argos-ci/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("@argos-ci/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("@argos-ci/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/playwright#api-overview
+*/
+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,56 @@
+import { ArgosScreenshotOptions as ArgosScreenshotOptions$1, MetadataConfig } from "@argos-ci/playwright";
+import { UploadParameters } from "@argos-ci/core";
+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-reporter.d.ts
+type ArgosReporterConfig = UploadParameters;
+//#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 };