npm - @argos-ci/vitest - Versions diffs - 0.2.3 - Mend

@argos-ci/vitest 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/LICENSE +7 -0
package/README.md +119 -0
package/dist/index.d.mts +175 -0
package/dist/index.mjs +1076 -0
package/dist/internal.d.mts +77 -0
package/dist/internal.mjs +145 -0
package/dist/plugin.d.mts +203 -0
package/dist/plugin.mjs +361 -0
package/dist/snapshot-file-jtgfnw7g.mjs +74 -0
package/package.json +85 -0

package/dist/plugin.mjs ADDED Viewed

@@ -0,0 +1,361 @@
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { DO_NOT_USE_setMetadataConfig, argosScreenshot } from "@argos-ci/playwright";
+import { resolveViewport } from "@argos-ci/browser";
+import { createDirectory, getMetadataPath, getScreenshotName, readVersionFromPackage, writeMetadata } from "@argos-ci/util";
+import { writeFile } from "node:fs/promises";
+import { getSnapshotMimeType, upload } from "@argos-ci/core";
+//#region src/iframe.ts
+/**
+* Selector of the iframe Vitest renders the test into on the orchestrator page.
+*/
+const VITEST_IFRAME_SELECTOR = "iframe[data-vitest=\"true\"]";
+/**
+* ID of the Vitest "tester" element that wraps the iframe with a `scale(...)`
+* transform.
+*/
+const VITEST_TESTER_ID = "vitest-tester";
+/**
+* Remove the scale from the Vitest `#vitest-tester` element before taking a
+* screenshot to avoid ending up with small screenshots.
+* @returns A function to restore the scale after the screenshot.
+*/
+async function resetTesterScale(ctx) {
+	await ctx.page.evaluate((testerId) => {
+		const tester = document.getElementById(testerId);
+		if (!(tester instanceof HTMLElement)) return;
+		if (!tester.getAttribute("data-scale")) throw new Error("Vitest iframe data-scale attribute not found");
+		tester.dataset.bckTransform = tester.style.transform;
+		tester.style.transform = `scale(1)`;
+	}, VITEST_TESTER_ID);
+	return async () => {
+		await ctx.page.evaluate((testerId) => {
+			const tester = document.getElementById(testerId);
+			if (!(tester instanceof HTMLElement)) return;
+			tester.style.transform = tester.dataset.bckTransform ?? "";
+		}, VITEST_TESTER_ID);
+	};
+}
+/**
+* Resize the Vitest iframe.
+*
+* The story/test renders inside an `<iframe data-vitest="true">` on the host
+* page and we screenshot the iframe's `<body>`. Anything overflowing the iframe
+* box is not painted, so the iframe must be sized to hold the content.
+*
+* @param size - The viewport size, `"default"` to keep the natural size, or
+*   `"initial"` to restore the size backed up on the first resize.
+* @param options.fullPage - When `true`, grow the height to fit the content
+*   while keeping the viewport width (Playwright-style full page).
+*/
+async function setIframeViewportSize(ctx, size, options = {}) {
+	await ctx.page.evaluate(({ size, fullPage, selector }) => {
+		const iframe = document.querySelector(selector);
+		if (!(iframe instanceof HTMLIFrameElement)) throw new Error("Vitest iframe not found");
+		if (!iframe.contentDocument) throw new Error("Vitest iframe contentDocument not found");
+		if (size === "initial") {
+			if (iframe.dataset.initialWidth && iframe.dataset.initialHeight) {
+				iframe.style.width = iframe.dataset.initialWidth;
+				iframe.style.height = iframe.dataset.initialHeight;
+			}
+			return;
+		}
+		if (!iframe.dataset.initialWidth && !iframe.dataset.initialHeight) {
+			iframe.dataset.initialWidth = iframe.style.width;
+			iframe.dataset.initialHeight = iframe.style.height;
+		}
+		if (size !== "default") iframe.style.width = `${size.width}px`;
+		if (fullPage) {
+			if (!iframe.contentWindow) throw new Error(`Can't access iframe window`);
+			const viewportHeight = size === "default" ? iframe.contentWindow.innerHeight : size.height;
+			iframe.style.height = "auto";
+			iframe.style.height = viewportHeight < iframe.contentDocument.body.offsetHeight ? `${iframe.contentDocument.body.offsetHeight}px` : "100%";
+		} else if (size !== "default") {
+			iframe.style.height = "auto";
+			iframe.style.height = `${size.height}px`;
+		}
+	}, {
+		size,
+		fullPage: options.fullPage ?? false,
+		selector: VITEST_IFRAME_SELECTOR
+	});
+}
+/**
+* Grow the Vitest iframe to fit its content so nothing is clipped.
+*
+* This must run *after* `argosCSS` (which may inject a `zoom`) is applied,
+* because `setIframeViewportSize` sizes the iframe *before* the content's final
+* size is known. It only ever grows the iframe, never shrinks it.
+*
+* @param options.fitWidth - Also grow the iframe horizontally to paint content
+*   wider than the viewport. When `false`, only the height grows (to match
+*   Playwright's `fullPage` semantics: full height, viewport width).
+*/
+async function fitIframeToContent(ctx, options) {
+	await ctx.page.evaluate(({ fitWidth, selector }) => {
+		const iframe = document.querySelector(selector);
+		if (!(iframe instanceof HTMLIFrameElement) || !iframe.contentDocument) return;
+		const { body, documentElement } = iframe.contentDocument;
+		const contentHeight = Math.max(body.scrollHeight, body.offsetHeight, documentElement.scrollHeight);
+		if (contentHeight > iframe.clientHeight) iframe.style.height = `${contentHeight}px`;
+		if (fitWidth) {
+			const contentWidth = Math.max(body.scrollWidth, body.offsetWidth, documentElement.scrollWidth);
+			if (contentWidth > iframe.clientWidth) iframe.style.width = `${contentWidth}px`;
+		}
+	}, {
+		fitWidth: options.fitWidth,
+		selector: VITEST_IFRAME_SELECTOR
+	});
+}
+//#endregion
+//#region src/screenshot.ts
+/**
+* Take a screenshot of the Vitest iframe body using the Playwright SDK.
+*
+* This is the shared primitive both the standalone command and Storybook build
+* on. It:
+* - strips the Vitest-specific `viewports`/`fullPage` options (they drive the
+*   iframe resize, not Playwright);
+* - wraps `beforeScreenshot` so the content is grown to fit *after* `argosCSS`
+*   (and any user `beforeScreenshot`) has been applied — otherwise wide/tall
+*   content would be clipped;
+* - captures the iframe's `<body>` via `@argos-ci/playwright`.
+*
+* @param config.fitWidth - Grow the iframe horizontally as well as vertically
+*   to fit the content (used when not capturing a fixed viewport width).
+*/
+async function screenshotFrame(ctx, name, options, config) {
+	const { viewports: _viewports, fullPage: _fullPage, ...rest } = options;
+	const userBeforeScreenshot = rest.beforeScreenshot;
+	const playwrightOptions = {
+		...rest,
+		beforeScreenshot: async (api) => {
+			await userBeforeScreenshot?.(api);
+			await fitIframeToContent(ctx, { fitWidth: config.fitWidth });
+		}
+	};
+	return argosScreenshot(await ctx.frame(), name, playwrightOptions);
+}
+//#endregion
+//#region src/version.ts
+const require = createRequire(import.meta.url);
+/**
+* Get the version of the Argos Vitest SDK.
+*/
+async function getArgosVitestVersion() {
+	return readVersionFromPackage(require.resolve("@argos-ci/vitest/package.json"));
+}
+/**
+* Get the version of Vitest itself (used as the automation library for
+* `argosSnapshot`, which does not rely on a browser).
+*/
+async function getVitestVersion() {
+	return readVersionFromPackage(require.resolve("vitest/package.json"));
+}
+//#endregion
+//#region src/command.ts
+/**
+* Create the `argosScreenshot` browser command used to capture Argos
+* screenshots from Vitest browser tests.
+*
+* Non-serializable options (`beforeScreenshot`, `afterScreenshot`, a
+* `Locator`/`ElementHandle` `element`, …) come from `pluginOptions` (node side)
+* and are merged with the serializable per-call options (per-call wins).
+*/
+const createArgosScreenshotCommand = (pluginOptions = {}) => {
+	return async (ctx, name, options) => {
+		if (!name) throw new Error("The `name` argument is required.");
+		const merged = {
+			...pluginOptions,
+			...options
+		};
+		const fullPage = merged.fullPage ?? false;
+		const fitWidth = !fullPage;
+		const restore = await resetTesterScale(ctx);
+		try {
+			const version = await getArgosVitestVersion();
+			const setMetadata = (viewport) => {
+				DO_NOT_USE_setMetadataConfig({
+					sdk: {
+						name: "@argos-ci/vitest",
+						version
+					},
+					playwrightLibraries: ["@vitest/browser-playwright"],
+					viewport
+				});
+			};
+			const attachments = [];
+			if (merged.viewports && merged.viewports.length > 0) for (const viewport of merged.viewports) {
+				const size = resolveViewport(viewport);
+				await setIframeViewportSize(ctx, size, { fullPage });
+				setMetadata(size);
+				const shot = await screenshotFrame(ctx, getScreenshotName(name, { viewportWidth: size.width }), merged, { fitWidth: false });
+				attachments.push(...shot);
+				await setIframeViewportSize(ctx, "initial", { fullPage });
+			}
+			else {
+				await setIframeViewportSize(ctx, "default", { fullPage });
+				setMetadata();
+				const shot = await screenshotFrame(ctx, name, merged, { fitWidth });
+				attachments.push(...shot);
+			}
+			return attachments;
+		} finally {
+			await restore();
+		}
+	};
+};
+/**
+* Default extension of a serialized snapshot file.
+*/
+const DEFAULT_EXTENSION = ".txt";
+/**
+* Marker inserted before the extension so the reporter can reliably pick up
+* snapshots (`**\/*.snapshot.*`) without matching screenshots or ARIA files.
+*/
+const SNAPSHOT_INFIX = ".snapshot";
+/**
+* Normalize a user-provided extension to a leading-dot form (`.txt`).
+*/
+function normalizeExtension(extension) {
+	return extension.startsWith(".") ? extension : `.${extension}`;
+}
+/**
+* Write a serialized snapshot (and its metadata) to disk and return the
+* corresponding Argos attachments.
+*
+* This is the shared Node-side primitive used by both the browser command (which
+* receives the already-serialized string over RPC) and the Node code path.
+*/
+async function writeSnapshotFile(name, content, options = {}) {
+	if (!name) throw new Error("The `name` argument is required.");
+	const root = options.root ?? "./screenshots";
+	const extension = normalizeExtension(options.extension ?? DEFAULT_EXTENSION);
+	const snapshotPath = resolve(root, `${getScreenshotName(name)}${SNAPSHOT_INFIX}${extension}`);
+	const [vitestVersion, sdkVersion] = await Promise.all([getVitestVersion(), getArgosVitestVersion()]);
+	const tags = options.tag ? Array.isArray(options.tag) ? options.tag : [options.tag] : void 0;
+	const metadata = {
+		automationLibrary: {
+			name: "vitest",
+			version: vitestVersion
+		},
+		sdk: {
+			name: "@argos-ci/vitest",
+			version: sdkVersion
+		},
+		...tags ? { tags } : {}
+	};
+	await createDirectory(dirname(snapshotPath));
+	await Promise.all([writeFile(snapshotPath, content, "utf-8"), writeMetadata(snapshotPath, metadata)]);
+	return [{
+		name: `argos/snapshot___${name}`,
+		contentType: getSnapshotMimeType(snapshotPath),
+		path: snapshotPath
+	}, {
+		name: `argos/snapshot/metadata___${name}`,
+		contentType: "application/json",
+		path: getMetadataPath(snapshotPath)
+	}];
+}
+//#endregion
+//#region src/snapshot-command.ts
+/**
+* Create the `argosSnapshot` browser command used to write serialized snapshots
+* from Vitest browser tests. The serialized string is produced on the browser
+* side and this command writes it (and its metadata) to disk on the Node side.
+*/
+const createArgosSnapshotCommand = (pluginOptions = {}) => {
+	return async (_ctx, name, content, options) => {
+		if (!name) throw new Error("The `name` argument is required.");
+		return writeSnapshotFile(name, content, {
+			root: pluginOptions.root,
+			...options
+		});
+	};
+};
+//#endregion
+//#region src/reporter.ts
+/**
+* Vitest reporter that uploads the screenshots captured during the run to Argos.
+*/
+var ArgosReporter = class {
+	vitest;
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	onInit(vitest) {
+		this.vitest = vitest;
+	}
+	async onFinished() {
+		await this.onTestRunEnd();
+	}
+	async onTestRunEnd() {
+		if (this.vitest.config.watch) return;
+		const res = await upload({
+			files: [
+				"**/*.png",
+				"**/*.aria.yml",
+				"**/*.snapshot.*"
+			],
+			ignore: ["**/*.argos.json"],
+			...this.config
+		});
+		console.log(`✅ Argos build created: ${res.build.url}`);
+	}
+};
+//#endregion
+//#region src/plugin.ts
+const cwd = process.cwd();
+/**
+* Vitest plugin that registers the `argosScreenshot` browser command and,
+* optionally, the reporter that uploads the captured screenshots to Argos.
+*
+* @example
+* ```ts
+* import { defineConfig } from "vitest/config";
+* import { playwright } from "@vitest/browser-playwright";
+* import { argosVitestPlugin } from "@argos-ci/vitest/plugin";
+*
+* export default defineConfig({
+*   plugins: [argosVitestPlugin({ uploadToArgos: true })],
+*   test: {
+*     browser: {
+*       enabled: true,
+*       provider: playwright(),
+*       instances: [{ browser: "chromium" }],
+*     },
+*   },
+* });
+* ```
+*/
+function argosVitestPlugin(options) {
+	const { root: unresolvedRoot = "./screenshots", uploadToArgos, ...otherOptions } = options ?? {};
+	const root = resolve(cwd, unresolvedRoot);
+	return {
+		name: "@argos-ci/vitest",
+		configureVitest({ vitest }) {
+			if (uploadToArgos) vitest.config.reporters.push(new ArgosReporter({
+				...otherOptions,
+				root
+			}));
+		},
+		config() {
+			return {
+				optimizeDeps: { include: ["@argos-ci/vitest"] },
+				test: { browser: { commands: {
+					argosScreenshot: createArgosScreenshotCommand({
+						...otherOptions,
+						root
+					}),
+					argosSnapshot: createArgosSnapshotCommand({
+						...otherOptions,
+						root
+					})
+				} } }
+			};
+		}
+	};
+}
+//#endregion
+export { ArgosReporter, argosVitestPlugin, createArgosScreenshotCommand, createArgosSnapshotCommand };

package/dist/snapshot-file-jtgfnw7g.mjs ADDED Viewed

@@ -0,0 +1,74 @@
+import { createRequire } from "node:module";
+import { writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { getSnapshotMimeType } from "@argos-ci/core";
+import { createDirectory, getMetadataPath, getScreenshotName, readVersionFromPackage, writeMetadata } from "@argos-ci/util";
+//#region src/version.ts
+const require = createRequire(import.meta.url);
+/**
+* Get the version of the Argos Vitest SDK.
+*/
+async function getArgosVitestVersion() {
+	return readVersionFromPackage(require.resolve("@argos-ci/vitest/package.json"));
+}
+/**
+* Get the version of Vitest itself (used as the automation library for
+* `argosSnapshot`, which does not rely on a browser).
+*/
+async function getVitestVersion() {
+	return readVersionFromPackage(require.resolve("vitest/package.json"));
+}
+/**
+* Default extension of a serialized snapshot file.
+*/
+const DEFAULT_EXTENSION = ".txt";
+/**
+* Marker inserted before the extension so the reporter can reliably pick up
+* snapshots (`**\/*.snapshot.*`) without matching screenshots or ARIA files.
+*/
+const SNAPSHOT_INFIX = ".snapshot";
+/**
+* Normalize a user-provided extension to a leading-dot form (`.txt`).
+*/
+function normalizeExtension(extension) {
+	return extension.startsWith(".") ? extension : `.${extension}`;
+}
+/**
+* Write a serialized snapshot (and its metadata) to disk and return the
+* corresponding Argos attachments.
+*
+* This is the shared Node-side primitive used by both the browser command (which
+* receives the already-serialized string over RPC) and the Node code path.
+*/
+async function writeSnapshotFile(name, content, options = {}) {
+	if (!name) throw new Error("The `name` argument is required.");
+	const root = options.root ?? "./screenshots";
+	const extension = normalizeExtension(options.extension ?? DEFAULT_EXTENSION);
+	const snapshotPath = resolve(root, `${getScreenshotName(name)}${SNAPSHOT_INFIX}${extension}`);
+	const [vitestVersion, sdkVersion] = await Promise.all([getVitestVersion(), getArgosVitestVersion()]);
+	const tags = options.tag ? Array.isArray(options.tag) ? options.tag : [options.tag] : void 0;
+	const metadata = {
+		automationLibrary: {
+			name: "vitest",
+			version: vitestVersion
+		},
+		sdk: {
+			name: "@argos-ci/vitest",
+			version: sdkVersion
+		},
+		...tags ? { tags } : {}
+	};
+	await createDirectory(dirname(snapshotPath));
+	await Promise.all([writeFile(snapshotPath, content, "utf-8"), writeMetadata(snapshotPath, metadata)]);
+	return [{
+		name: `argos/snapshot___${name}`,
+		contentType: getSnapshotMimeType(snapshotPath),
+		path: snapshotPath
+	}, {
+		name: `argos/snapshot/metadata___${name}`,
+		contentType: "application/json",
+		path: getMetadataPath(snapshotPath)
+	}];
+}
+//#endregion
+export { writeSnapshotFile };

package/package.json ADDED Viewed

@@ -0,0 +1,85 @@
+{
+  "name": "@argos-ci/vitest",
+  "description": "Vitest SDK for visual testing with Argos.",
+  "version": "0.2.3",
+  "author": "Smooth Code",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/argos-ci/argos-javascript.git",
+    "directory": "packages/vitest"
+  },
+  "homepage": "https://argos-ci.com/docs/sdks-reference/vitest",
+  "bugs": {
+    "url": "https://github.com/argos-ci/argos-javascript/issues"
+  },
+  "keywords": [
+    "vitest",
+    "vitest-plugin",
+    "vitest-browser",
+    "screenshot",
+    "capture",
+    "testing",
+    "visual testing",
+    "argos",
+    "regression",
+    "visual regression"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.mts",
+      "import": "./dist/plugin.mjs",
+      "default": "./dist/plugin.mjs"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.mts",
+      "import": "./dist/internal.mjs",
+      "default": "./dist/internal.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@argos-ci/browser": "6.4.4",
+    "@argos-ci/core": "6.5.3",
+    "@argos-ci/playwright": "7.3.4",
+    "@argos-ci/util": "4.0.4"
+  },
+  "peerDependencies": {
+    "@vitest/browser": ">=4",
+    "@vitest/browser-playwright": ">=4",
+    "playwright": ">=1",
+    "vitest": ">=4"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@vitest/browser": "^4.1.9",
+    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/pretty-format": "^4.1.9",
+    "playwright": "^1.61.0",
+    "vitest": "catalog:"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run --project unit",
+    "test-e2e": "vitest run --project e2e",
+    "install-playwright": "playwright install chromium --with-deps",
+    "build-e2e": "pnpm run install-playwright",
+    "e2e": "cross-env BUILD_NAME=\"argos-vitest-e2e-node-$NODE_VERSION-$OS\" UPLOAD_TO_ARGOS=true pnpm run test-e2e",
+    "check-types": "tsc",
+    "check-format": "prettier --check --ignore-unknown --ignore-path=./.gitignore --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
+    "lint": "eslint ."
+  },
+  "gitHead": "1b25b7c1109a3d032d627c5f9d2f2c3937731aea"
+}