@argos-ci/vitest 0.2.3 → 0.3.0

package/README.md

@@ -80,6 +80,25 @@ test("Button", async () => {
 });
 ```
 
+### Automatic naming
+
+The name is optional. When omitted, Argos derives one from the current test,
+mimicking [Vitest snapshots](https://vitest.dev/guide/snapshot). Several unnamed
+captures in the same test get an incrementing counter so they stay unique:
+
+```ts
+test("Button", async () => {
+  render(<Button>Click me</Button>);
+  await argosScreenshot(); // -> "src/Button.test.tsx > Button 1"
+  await argosScreenshot(); // -> "src/Button.test.tsx > Button 2"
+});
+```
+
+Unlike Vitest — which keeps a per-file `.snap`, so its keys only need to be
+unique within a file — Argos names are **global** across the build. The
+generated name therefore includes the test file path, so two tests with the same
+title in different files never collide.
+
 ## Snapshots
 
 `argosSnapshot` captures a snapshot of any value — not just a screenshot — and
@@ -87,6 +106,10 @@ uploads it to Argos to diff across builds, mimicking
 [Vitest snapshots](https://vitest.dev/guide/snapshot). Unlike `argosScreenshot`,
 it does not need a browser and works in **both** browser and Node tests.
 
+The value comes first; the name is optional. Omit it to auto-name the snapshot
+from the current test (like screenshots above), or pass `options.name` to set it
+explicitly:
+
 ```ts
 import { test } from "vitest";
 import { argosSnapshot } from "@argos-ci/vitest";
@@ -95,7 +118,8 @@ test("API response", async () => {
   const user = await fetchUser();
   // Objects are serialized with `@vitest/pretty-format`, strings are written
   // verbatim.
-  await argosSnapshot("user", user);
+  await argosSnapshot(user); // -> "src/user.test.ts > API response 1"
+  await argosSnapshot(user, { name: "user" }); // explicit name
 });
 ```
 
@@ -103,14 +127,16 @@ Use the `extension` option to control how Argos renders and diffs the snapshot,
 and `tag` to attach tags:
 
 ```ts
-await argosSnapshot("config", JSON.stringify(config, null, 2), {
+await argosSnapshot(JSON.stringify(config, null, 2), {
+  name: "config",
   extension: ".json",
   tag: "config",
 });
 ```
 
-Snapshots are written to the same folder as screenshots and uploaded by the
-reporter when `uploadToArgos` is enabled.
+Screenshots and snapshots are both written to the `./snapshots` directory by
+default (configurable via the plugin `root` option) and uploaded by the reporter
+when `uploadToArgos` is enabled.
 
 ## Links
 

package/dist/index.d.mts

@@ -1,6 +1,11 @@
+import { ScreenshotMetadata } from "@argos-ci/util";
 import { ArgosAttachment } from "@argos-ci/playwright";
 import { StabilizationPluginOptions, ViewportOption } from "@argos-ci/browser";
 
+//#region src/metadata.d.ts
+/** The `test` slice of {@link ScreenshotMetadata}. */
+type TestMetadata = ScreenshotMetadata["test"];
+//#endregion
 //#region src/options.d.ts
 /**
  * Options passed when calling `argosScreenshot` from a browser test.
@@ -76,12 +81,22 @@ interface VitestScreenshotOptions {
  * applied on the test side *before* the value is sent to Node.
  */
 interface VitestSnapshotOptions {
+  /**
+   * Unique name of the snapshot.
+   *
+   * When omitted, Argos generates one automatically from the current test,
+   * mimicking {@link https://vitest.dev/guide/snapshot Vitest's snapshot naming}.
+   * The generated name includes the test file path so names stay unique across
+   * files (Argos names are global across the build, unlike Vitest's per-file
+   * `.snap`).
+   */
+  name?: string;
   /**
    * Folder where the snapshot is written.
    *
-   * In Node tests this defaults to `"./screenshots"`. In browser tests it
+   * In Node tests this defaults to `"./snapshots"`. In browser tests it
    * defaults to the plugin `root` and can be overridden per call.
-   * @default "./screenshots"
+   * @default "./snapshots"
    */
   root?: string;
   /**
@@ -102,16 +117,17 @@ interface VitestSnapshotOptions {
 }
 /**
  * Subset of {@link VitestSnapshotOptions} that can cross the Vitest
- * browser/node RPC boundary (everything but `serialize`, which is applied
- * before the value is sent to Node).
+ * browser/node RPC boundary. Excludes `serialize` (applied before the value is
+ * sent to Node) and `name` (resolved on the test side and passed to the Node
+ * primitives as a separate argument).
  */
-type SerializableSnapshotOptions = Omit<VitestSnapshotOptions, "serialize">;
+type SerializableSnapshotOptions = Omit<VitestSnapshotOptions, "serialize" | "name">;
 //#endregion
 //#region src/index.d.ts
 declare module "vitest/browser" {
   interface BrowserCommands {
-    argosScreenshot: (name: string, options?: VitestScreenshotOptions) => Promise<ArgosAttachment[]>;
-    argosSnapshot: (name: string, content: string, options?: SerializableSnapshotOptions) => Promise<ArgosAttachment[]>;
+    argosScreenshot: (name: string, options?: VitestScreenshotOptions, test?: TestMetadata) => Promise<ArgosAttachment[]>;
+    argosSnapshot: (name: string, content: string, options?: SerializableSnapshotOptions, test?: TestMetadata) => Promise<ArgosAttachment[]>;
   }
 }
 /**
@@ -120,6 +136,12 @@ declare module "vitest/browser" {
  * Requires the {@link https://www.npmjs.com/package/@argos-ci/vitest Argos Vitest plugin}
  * to be registered in your Vitest config.
  *
+ * The `name` is optional: when omitted, Argos generates one automatically from
+ * the current test, mimicking {@link https://vitest.dev/guide/snapshot Vitest's
+ * snapshot naming}. The name includes the test file path (Argos names are global
+ * across the build, unlike Vitest's per-file `.snap`), so names stay unique
+ * across files.
+ *
  * @example
  * ```ts
  * import { render } from "vitest-browser-react";
@@ -127,15 +149,18 @@ declare module "vitest/browser" {
  *
  * test("Button", async () => {
  *   render(<Button>Click me</Button>);
- *   await argosScreenshot("button");
+ *   await argosScreenshot("button"); // explicit name
+ *   await argosScreenshot();         // -> "src/Button.test.tsx > Button 1"
  * });
  * ```
  *
- * @param name - Unique name of the screenshot.
+ * @param name - Unique name of the screenshot. Omit to generate one from the
+ *   current test.
  * @param options - Serializable screenshot options.
  * @returns The attachments captured, or an empty array outside of Vitest.
  */
 declare function argosScreenshot(name: string, options?: VitestScreenshotOptions): Promise<ArgosAttachment[]>;
+declare function argosScreenshot(options?: VitestScreenshotOptions): Promise<ArgosAttachment[]>;
 /**
  * Take an Argos snapshot of any serializable value, mimicking
  * {@link https://vitest.dev/guide/snapshot Vitest snapshots}.
@@ -145,23 +170,29 @@ declare function argosScreenshot(name: string, options?: VitestScreenshotOptions
  * file that Argos picks up and diffs across builds. It works both in Vitest
  * browser tests and in plain Node tests.
  *
+ * The name is optional: pass it via `options.name`, or omit it to have Argos
+ * generate one automatically from the current test, mimicking
+ * {@link https://vitest.dev/guide/snapshot Vitest's snapshot naming}. The name
+ * includes the test file path (Argos names are global across the build, unlike
+ * Vitest's per-file `.snap`), so names stay unique across files.
+ *
  * @example
  * ```ts
  * import { argosSnapshot } from "@argos-ci/vitest";
  *
  * test("API response", async () => {
  *   const data = await fetchUser();
- *   await argosSnapshot("user", data);
+ *   await argosSnapshot(data);                   // -> "src/user.test.ts > API response 1"
+ *   await argosSnapshot(data, { name: "user" }); // explicit name
  * });
  * ```
  *
- * @param name - Unique name of the snapshot.
  * @param content - The value to snapshot. Strings are written as-is; any other
  *   value is serialized.
- * @param options - Snapshot options.
+ * @param options - Snapshot options, including an optional `name`.
  * @returns The attachments written, or an empty array outside of Vitest.
  */
-declare function argosSnapshot(name: string, content: unknown, options?: VitestSnapshotOptions): Promise<ArgosAttachment[]>;
+declare function argosSnapshot(content: unknown, options?: VitestSnapshotOptions): Promise<ArgosAttachment[]>;
 /**
  * Check if we are running in a Vitest environment.
  */

package/dist/index.mjs

@@ -1,3 +1,143 @@
+//#region src/test-context.ts
+/**
+* Get the current Vitest test task, or `undefined` when not inside a test.
+*
+* Vitest >= 4.1 exposes `TestRunner.getCurrentTest()` from the `vitest` entry
+* point; the `vitest/suite` export is deprecated. We prefer the new API and
+* fall back to `vitest/suite` for older 4.x. Both are imported dynamically so
+* importing `@argos-ci/vitest` in a non-Vitest environment does not pull Vitest
+* in — only call this once you know Vitest is available.
+*/
+async function getCurrentTest() {
+	const runner = (await import("vitest")).TestRunner;
+	if (runner?.getCurrentTest) return runner.getCurrentTest();
+	return (await import("vitest/suite")).getCurrentTest();
+}
+//#endregion
+//#region src/auto-name.ts
+/**
+* Maximum length of a single filename component on common filesystems (ext4,
+* APFS, NTFS all cap at 255 bytes/chars).
+*/
+const MAX_FILENAME_LENGTH = 255;
+/**
+* Per-test counter used to generate unique automatic names, keyed by the
+* current test task. A `WeakMap` lets the entries be garbage-collected with the
+* test tasks, so nothing leaks across files or runs.
+*/
+const counters = /* @__PURE__ */ new WeakMap();
+/**
+* Truncate `text` to `length` characters, replacing the tail with an ellipsis.
+*/
+function truncate(text, length) {
+	if (text.length <= length) return text;
+	return `${text.slice(0, Math.max(0, length - 1))}…`;
+}
+/**
+* Resolve the name of a screenshot or snapshot.
+*
+* When an explicit `name` is provided, it is returned as-is. Otherwise a name
+* is generated automatically from the current Vitest test, mimicking
+* {@link https://vitest.dev/guide/snapshot Vitest's own snapshot naming}:
+* `` `${test.fullName} ${count}` ``, where `count` increments per test so
+* several auto-named captures in the same test stay unique.
+*
+* Unlike Vitest — which stores snapshots in a per-file `.snap`, so its keys only
+* need to be unique within a file — Argos names are global across the whole
+* build. The name therefore includes the test file path so two tests with the
+* same title in different files do not collide. Vitest's `fullName` already
+* starts with the file path; we prepend it defensively in case that changes.
+*
+* The name is kept short enough that the final filename — including the
+* extension(s) the caller appends (e.g. `.snapshot.txt`, ` vw-800.png`) and the
+* `.argos.json` metadata sidecar — fits within {@link MAX_FILENAME_LENGTH}.
+* Mirroring the Playwright SDK, when the readable name would overflow we fall
+* back to the test id (short and unique) so truncated names never collide, then
+* keep as much of the readable name as fits.
+*
+* Must only be called once we know we are running inside Vitest (the caller
+* checks `checkIsVitestEnv` first).
+*
+* @param name - Explicit name, or `undefined`/empty to auto-generate one.
+* @param options.reservedLength - Number of characters the caller appends after
+*   the returned name when building the filename (extensions + metadata
+*   suffix), reserved so the whole filename stays within the limit.
+* @returns The resolved, non-empty name.
+*/
+async function resolveAutoName(name, options = {}) {
+	if (name) return name;
+	const test = await getCurrentTest();
+	if (!test) throw new Error("Argos could not generate an automatic name because it is not running inside a Vitest test. Pass an explicit `name` argument.");
+	const count = (counters.get(test) ?? 0) + 1;
+	counters.set(test, count);
+	const file = test.file?.name;
+	const fullName = file && !test.fullName.startsWith(file) ? `${file} > ${test.fullName}` : test.fullName;
+	const suffix = ` ${count}`;
+	const maxBase = MAX_FILENAME_LENGTH - (options.reservedLength ?? 0) - suffix.length;
+	return `${fullName.length > maxBase ? truncate(`${test.id} ${fullName}`, maxBase) : fullName}${suffix}`;
+}
+//#endregion
+//#region src/metadata.ts
+/**
+* Build the title path of a task (`[file, ...describes, title]`), replicating
+* Vitest's own `getNames` helper so it matches the framework's conventions.
+*/
+function getTitlePath(task) {
+	const names = [task.name];
+	let current = task;
+	while (current.suite) {
+		current = current.suite;
+		if (current.name) names.unshift(current.name);
+	}
+	if (current !== task.file) names.unshift(task.file.name);
+	return names;
+}
+/**
+* Build the Argos `test` metadata from a Vitest test task, mirroring the
+* Playwright SDK.
+*
+* `location.file` is left absolute here; the Node side (the Playwright SDK for
+* screenshots, {@link writeSnapshotFile} for snapshots) resolves it relative to
+* the git repository — the same treatment the Playwright SDK applies.
+*/
+function buildTestMetadata(task) {
+	return {
+		id: task.id,
+		title: task.name,
+		titlePath: getTitlePath(task),
+		tags: task.tags && task.tags.length > 0 ? task.tags : void 0,
+		retries: task.retry ?? void 0,
+		retry: task.result?.retryCount ?? void 0,
+		repeat: task.result?.repeatCount ?? task.repeats ?? void 0,
+		location: {
+			file: task.file.filepath,
+			line: task.location?.line ?? 0,
+			column: task.location?.column ?? 0
+		},
+		annotations: task.annotations && task.annotations.length > 0 ? task.annotations.map((annotation) => ({
+			type: annotation.type,
+			description: annotation.message,
+			location: annotation.location ? {
+				file: annotation.location.file ?? task.file.filepath,
+				line: annotation.location.line ?? 0,
+				column: annotation.location.column ?? 0
+			} : void 0
+		})) : void 0
+	};
+}
+/**
+* Get the Argos `test` metadata for the current Vitest test, or `null` when not
+* running inside a test.
+*
+* Runs on the test side (browser or Node) where the test context is available;
+* the resulting plain object crosses the browser/Node RPC boundary unchanged.
+*/
+async function getTestMetadata() {
+	const task = await getCurrentTest();
+	if (!task) return null;
+	return buildTestMetadata(task);
+}
+//#endregion
 //#region ../../node_modules/.pnpm/tinyrainbow@3.1.0/node_modules/tinyrainbow/dist/index.js
 var b = {
 	reset: [0, 0],
@@ -992,30 +1132,19 @@ function serializeSnapshot(content, options = {}) {
 //#endregion
 //#region src/index.ts
 /**
-* Take an Argos screenshot in a Vitest browser test.
-*
-* Requires the {@link https://www.npmjs.com/package/@argos-ci/vitest Argos Vitest plugin}
-* to be registered in your Vitest config.
-*
-* @example
-* ```ts
-* import { render } from "vitest-browser-react";
-* import { argosScreenshot } from "@argos-ci/vitest";
-*
-* test("Button", async () => {
-*   render(<Button>Click me</Button>);
-*   await argosScreenshot("button");
-* });
-* ```
-*
-* @param name - Unique name of the screenshot.
-* @param options - Serializable screenshot options.
-* @returns The attachments captured, or an empty array outside of Vitest.
+* Characters reserved after a screenshot name when building its filename: the
+* `` ` vw-<width>` `` viewport suffix, the largest capture extension
+* (`.aria.yml`), and the metadata sidecar. Keeps auto-generated names within
+* the filesystem limit.
 */
-async function argosScreenshot(name, options) {
+const SCREENSHOT_NAME_RESERVED = 29;
+async function argosScreenshot(nameOrOptions, maybeOptions) {
+	const name = typeof nameOrOptions === "string" ? nameOrOptions : void 0;
+	const options = typeof nameOrOptions === "string" ? maybeOptions : nameOrOptions;
 	if (!await checkIsVitestEnv()) return [];
+	const [resolvedName, test] = await Promise.all([resolveAutoName(name, { reservedLength: SCREENSHOT_NAME_RESERVED }), getTestMetadata()]);
 	const { server } = await import("vitest/browser");
-	return server.commands.argosScreenshot(name, options);
+	return server.commands.argosScreenshot(resolvedName, options ?? {}, test);
 }
 /**
 * Take an Argos snapshot of any serializable value, mimicking
@@ -1026,33 +1155,41 @@ async function argosScreenshot(name, options) {
 * file that Argos picks up and diffs across builds. It works both in Vitest
 * browser tests and in plain Node tests.
 *
+* The name is optional: pass it via `options.name`, or omit it to have Argos
+* generate one automatically from the current test, mimicking
+* {@link https://vitest.dev/guide/snapshot Vitest's snapshot naming}. The name
+* includes the test file path (Argos names are global across the build, unlike
+* Vitest's per-file `.snap`), so names stay unique across files.
+*
 * @example
 * ```ts
 * import { argosSnapshot } from "@argos-ci/vitest";
 *
 * test("API response", async () => {
 *   const data = await fetchUser();
-*   await argosSnapshot("user", data);
+*   await argosSnapshot(data);                   // -> "src/user.test.ts > API response 1"
+*   await argosSnapshot(data, { name: "user" }); // explicit name
 * });
 * ```
 *
-* @param name - Unique name of the snapshot.
 * @param content - The value to snapshot. Strings are written as-is; any other
 *   value is serialized.
-* @param options - Snapshot options.
+* @param options - Snapshot options, including an optional `name`.
 * @returns The attachments written, or an empty array outside of Vitest.
 */
-async function argosSnapshot(name, content, options = {}) {
-	if (!name) throw new Error("The `name` argument is required.");
+async function argosSnapshot(content, options = {}) {
 	if (!await checkIsVitestEnv()) return [];
+	const rawExtension = options.extension ?? ".txt";
+	const extension = rawExtension.startsWith(".") ? rawExtension : `.${rawExtension}`;
+	const [resolvedName, test] = await Promise.all([resolveAutoName(options.name, { reservedLength: 9 + extension.length + 11 }), getTestMetadata()]);
 	const serialized = serializeSnapshot(content, options);
-	const { serialize: _serialize, ...serializableOptions } = options;
+	const { serialize: _serialize, name: _name, ...serializableOptions } = options;
 	if (checkIsBrowserEnv()) {
 		const { server } = await import("vitest/browser");
-		return server.commands.argosSnapshot(name, serialized, serializableOptions);
+		return server.commands.argosSnapshot(resolvedName, serialized, serializableOptions, test);
 	}
-	const { writeSnapshotFile } = await import("./snapshot-file-jtgfnw7g.mjs");
-	return writeSnapshotFile(name, serialized, serializableOptions);
+	const { writeSnapshotFile } = await import("./snapshot-file-DYQmhYf1.mjs");
+	return writeSnapshotFile(resolvedName, serialized, serializableOptions, test);
 }
 /**
 * Check if we are running in a Vitest environment.

package/dist/plugin.d.mts

@@ -1,5 +1,6 @@
 import { ArgosScreenshotOptions } from "@argos-ci/playwright";
 import { StabilizationPluginOptions, ViewportOption } from "@argos-ci/browser";
+import { ScreenshotMetadata } from "@argos-ci/util";
 import { UploadParameters } from "@argos-ci/core";
 import { Plugin } from "vitest/config";
 import { BrowserCommand, Vitest } from "vitest/node";
@@ -85,12 +86,22 @@ interface VitestScreenshotOptions {
  * applied on the test side *before* the value is sent to Node.
  */
 interface VitestSnapshotOptions {
+  /**
+   * Unique name of the snapshot.
+   *
+   * When omitted, Argos generates one automatically from the current test,
+   * mimicking {@link https://vitest.dev/guide/snapshot Vitest's snapshot naming}.
+   * The generated name includes the test file path so names stay unique across
+   * files (Argos names are global across the build, unlike Vitest's per-file
+   * `.snap`).
+   */
+  name?: string;
   /**
    * Folder where the snapshot is written.
    *
-   * In Node tests this defaults to `"./screenshots"`. In browser tests it
+   * In Node tests this defaults to `"./snapshots"`. In browser tests it
    * defaults to the plugin `root` and can be overridden per call.
-   * @default "./screenshots"
+   * @default "./snapshots"
    */
   root?: string;
   /**
@@ -111,10 +122,11 @@ interface VitestSnapshotOptions {
 }
 /**
  * Subset of {@link VitestSnapshotOptions} that can cross the Vitest
- * browser/node RPC boundary (everything but `serialize`, which is applied
- * before the value is sent to Node).
+ * browser/node RPC boundary. Excludes `serialize` (applied before the value is
+ * sent to Node) and `name` (resolved on the test side and passed to the Node
+ * primitives as a separate argument).
  */
-type SerializableSnapshotOptions = Omit<VitestSnapshotOptions, "serialize">;
+type SerializableSnapshotOptions = Omit<VitestSnapshotOptions, "serialize" | "name">;
 /**
  * Options for the Argos Vitest plugin.
  *
@@ -132,12 +144,16 @@ interface ArgosVitestPluginOptions extends ArgosReporterConfig, ArgosScreenshotO
   uploadToArgos?: boolean;
 }
 //#endregion
+//#region src/metadata.d.ts
+/** The `test` slice of {@link ScreenshotMetadata}. */
+type TestMetadata = ScreenshotMetadata["test"];
+//#endregion
 //#region src/command.d.ts
 /**
  * Arguments of the `argosScreenshot` browser command.
  * Only serializable values cross the browser/node RPC boundary.
  */
-type ArgosScreenshotCommandArgs = [name: string, options?: VitestScreenshotOptions];
+type ArgosScreenshotCommandArgs = [name: string, options?: VitestScreenshotOptions, test?: TestMetadata];
 /**
  * Create the `argosScreenshot` browser command used to capture Argos
  * screenshots from Vitest browser tests.
@@ -154,7 +170,7 @@ declare const createArgosScreenshotCommand: (pluginOptions?: ArgosVitestPluginOp
  * Only serializable values cross the browser/node RPC boundary — the value is
  * already serialized to a string on the browser side.
  */
-type ArgosSnapshotCommandArgs = [name: string, content: string, options?: SerializableSnapshotOptions];
+type ArgosSnapshotCommandArgs = [name: string, content: string, options?: SerializableSnapshotOptions, test?: TestMetadata];
 /**
  * Create the `argosSnapshot` browser command used to write serialized snapshots
  * from Vitest browser tests. The serialized string is produced on the browser

package/dist/plugin.mjs

@@ -1,10 +1,10 @@
 import { createRequire } from "node:module";
-import { dirname, resolve } from "node:path";
+import { dirname, relative, 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 { createDirectory, getGitRepositoryPath, getMetadataPath, getScreenshotName, readVersionFromPackage, writeMetadata } from "@argos-ci/util";
 import { writeFile } from "node:fs/promises";
-import { getSnapshotMimeType, upload } from "@argos-ci/core";
+import { getSnapshotMimeType, readConfig, upload } from "@argos-ci/core";
 //#region src/iframe.ts
 /**
 * Selector of the iframe Vitest renders the test into on the orchestrator page.
@@ -163,7 +163,7 @@ async function getVitestVersion() {
 * and are merged with the serializable per-call options (per-call wins).
 */
 const createArgosScreenshotCommand = (pluginOptions = {}) => {
-	return async (ctx, name, options) => {
+	return async (ctx, name, options, test) => {
 		if (!name) throw new Error("The `name` argument is required.");
 		const merged = {
 			...pluginOptions,
@@ -180,8 +180,9 @@ const createArgosScreenshotCommand = (pluginOptions = {}) => {
 						name: "@argos-ci/vitest",
 						version
 					},
-					playwrightLibraries: ["@vitest/browser-playwright"],
-					viewport
+					playwrightLibraries: ["vitest"],
+					viewport,
+					test
 				});
 			};
 			const attachments = [];
@@ -205,6 +206,24 @@ const createArgosScreenshotCommand = (pluginOptions = {}) => {
 		}
 	};
 };
+//#endregion
+//#region src/snapshot-file.ts
+/**
+* Resolve a `test` metadata's `location.file` relative to the git repository,
+* matching the Playwright SDK. The test side reports an absolute path.
+*/
+async function resolveTestLocation(test) {
+	if (!test?.location) return test;
+	const repositoryPath = await getGitRepositoryPath();
+	if (!repositoryPath) return test;
+	return {
+		...test,
+		location: {
+			...test.location,
+			file: relative(repositoryPath, test.location.file)
+		}
+	};
+}
 /**
 * Default extension of a serialized snapshot file.
 */
@@ -227,12 +246,16 @@ function normalizeExtension(extension) {
 * 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 = {}) {
+async function writeSnapshotFile(name, content, options = {}, test) {
 	if (!name) throw new Error("The `name` argument is required.");
-	const root = options.root ?? "./screenshots";
+	const root = options.root ?? "./snapshots";
 	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 [vitestVersion, sdkVersion, resolvedTest] = await Promise.all([
+		getVitestVersion(),
+		getArgosVitestVersion(),
+		resolveTestLocation(test)
+	]);
 	const tags = options.tag ? Array.isArray(options.tag) ? options.tag : [options.tag] : void 0;
 	const metadata = {
 		automationLibrary: {
@@ -243,7 +266,8 @@ async function writeSnapshotFile(name, content, options = {}) {
 			name: "@argos-ci/vitest",
 			version: sdkVersion
 		},
-		...tags ? { tags } : {}
+		...tags ? { tags } : {},
+		...resolvedTest ? { test: resolvedTest } : {}
 	};
 	await createDirectory(dirname(snapshotPath));
 	await Promise.all([writeFile(snapshotPath, content, "utf-8"), writeMetadata(snapshotPath, metadata)]);
@@ -265,17 +289,38 @@ async function writeSnapshotFile(name, content, options = {}) {
 * side and this command writes it (and its metadata) to disk on the Node side.
 */
 const createArgosSnapshotCommand = (pluginOptions = {}) => {
-	return async (_ctx, name, content, options) => {
+	return async (_ctx, name, content, options, test) => {
 		if (!name) throw new Error("The `name` argument is required.");
 		return writeSnapshotFile(name, content, {
 			root: pluginOptions.root,
 			...options
-		});
+		}, test);
 	};
 };
 //#endregion
 //#region src/reporter.ts
 /**
+* Derive the Argos parallel configuration from Vitest's shard settings, matching
+* the Playwright reporter.
+*
+* Vitest's `--shard=<index>/<count>` populates `config.shard` as
+* `{ index, count }` (the `index` is 1-based, like the Argos `parallel.index`).
+* When sharding is active, Argos still needs `ARGOS_PARALLEL_NONCE` to group the
+* shards into a single build; the total and index default to the shard values
+* but can be overridden via `ARGOS_PARALLEL_TOTAL` / `ARGOS_PARALLEL_INDEX`.
+*/
+async function getParallelFromConfig(config) {
+	const { shard } = config;
+	if (!shard || shard.count === 1) return null;
+	const argosConfig = await readConfig();
+	if (!argosConfig.parallelNonce) throw new Error("Vitest shard mode detected. Please specify the ARGOS_PARALLEL_NONCE environment variable. Read https://argos-ci.com/docs/parallel-testing");
+	return {
+		total: argosConfig.parallelTotal ?? shard.count,
+		nonce: argosConfig.parallelNonce,
+		index: argosConfig.parallelIndex ?? shard.index
+	};
+}
+/**
 * Vitest reporter that uploads the screenshots captured during the run to Argos.
 */
 var ArgosReporter = class {
@@ -299,6 +344,7 @@ var ArgosReporter = class {
 				"**/*.snapshot.*"
 			],
 			ignore: ["**/*.argos.json"],
+			parallel: await getParallelFromConfig(this.vitest.config) ?? void 0,
 			...this.config
 		});
 		console.log(`✅ Argos build created: ${res.build.url}`);
@@ -330,7 +376,7 @@ const cwd = process.cwd();
 * ```
 */
 function argosVitestPlugin(options) {
-	const { root: unresolvedRoot = "./screenshots", uploadToArgos, ...otherOptions } = options ?? {};
+	const { root: unresolvedRoot = "./snapshots", uploadToArgos, ...otherOptions } = options ?? {};
 	const root = resolve(cwd, unresolvedRoot);
 	return {
 		name: "@argos-ci/vitest",
@@ -343,16 +389,19 @@ function argosVitestPlugin(options) {
 		config() {
 			return {
 				optimizeDeps: { include: ["@argos-ci/vitest"] },
-				test: { browser: { commands: {
-					argosScreenshot: createArgosScreenshotCommand({
-						...otherOptions,
-						root
-					}),
-					argosSnapshot: createArgosSnapshotCommand({
-						...otherOptions,
-						root
-					})
-				} } }
+				test: {
+					includeTaskLocation: true,
+					browser: { commands: {
+						argosScreenshot: createArgosScreenshotCommand({
+							...otherOptions,
+							root
+						}),
+						argosSnapshot: createArgosSnapshotCommand({
+							...otherOptions,
+							root
+						})
+					} }
+				}
 			};
 		}
 	};

package/dist/{snapshot-file-jtgfnw7g.mjs → snapshot-file-DYQmhYf1.mjs}

@@ -1,8 +1,8 @@
 import { createRequire } from "node:module";
 import { writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname, relative, resolve } from "node:path";
 import { getSnapshotMimeType } from "@argos-ci/core";
-import { createDirectory, getMetadataPath, getScreenshotName, readVersionFromPackage, writeMetadata } from "@argos-ci/util";
+import { createDirectory, getGitRepositoryPath, getMetadataPath, getScreenshotName, readVersionFromPackage, writeMetadata } from "@argos-ci/util";
 //#region src/version.ts
 const require = createRequire(import.meta.url);
 /**
@@ -18,6 +18,24 @@ async function getArgosVitestVersion() {
 async function getVitestVersion() {
 	return readVersionFromPackage(require.resolve("vitest/package.json"));
 }
+//#endregion
+//#region src/snapshot-file.ts
+/**
+* Resolve a `test` metadata's `location.file` relative to the git repository,
+* matching the Playwright SDK. The test side reports an absolute path.
+*/
+async function resolveTestLocation(test) {
+	if (!test?.location) return test;
+	const repositoryPath = await getGitRepositoryPath();
+	if (!repositoryPath) return test;
+	return {
+		...test,
+		location: {
+			...test.location,
+			file: relative(repositoryPath, test.location.file)
+		}
+	};
+}
 /**
 * Default extension of a serialized snapshot file.
 */
@@ -40,12 +58,16 @@ function normalizeExtension(extension) {
 * 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 = {}) {
+async function writeSnapshotFile(name, content, options = {}, test) {
 	if (!name) throw new Error("The `name` argument is required.");
-	const root = options.root ?? "./screenshots";
+	const root = options.root ?? "./snapshots";
 	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 [vitestVersion, sdkVersion, resolvedTest] = await Promise.all([
+		getVitestVersion(),
+		getArgosVitestVersion(),
+		resolveTestLocation(test)
+	]);
 	const tags = options.tag ? Array.isArray(options.tag) ? options.tag : [options.tag] : void 0;
 	const metadata = {
 		automationLibrary: {
@@ -56,7 +78,8 @@ async function writeSnapshotFile(name, content, options = {}) {
 			name: "@argos-ci/vitest",
 			version: sdkVersion
 		},
-		...tags ? { tags } : {}
+		...tags ? { tags } : {},
+		...resolvedTest ? { test: resolvedTest } : {}
 	};
 	await createDirectory(dirname(snapshotPath));
 	await Promise.all([writeFile(snapshotPath, content, "utf-8"), writeMetadata(snapshotPath, metadata)]);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@argos-ci/vitest",
   "description": "Vitest SDK for visual testing with Argos.",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "author": "Smooth Code",
   "license": "MIT",
   "repository": {
@@ -52,8 +52,8 @@
   },
   "dependencies": {
     "@argos-ci/browser": "6.4.4",
-    "@argos-ci/core": "6.5.3",
-    "@argos-ci/playwright": "7.3.4",
+    "@argos-ci/core": "6.6.0",
+    "@argos-ci/playwright": "7.3.5",
     "@argos-ci/util": "4.0.4"
   },
   "peerDependencies": {
@@ -81,5 +81,5 @@
     "check-format": "prettier --check --ignore-unknown --ignore-path=./.gitignore --ignore-path=../../.gitignore --ignore-path=../../.prettierignore .",
     "lint": "eslint ."
   },
-  "gitHead": "1b25b7c1109a3d032d627c5f9d2f2c3937731aea"
+  "gitHead": "51c052e00a5361ca40c4695f16706d841be4e2da"
 }