vitest-plugin-vis 2.2.0 → 2.3.1

package/esm/setup/create_vis.js

@@ -1,9 +1,9 @@
 import dedent from 'dedent';
 import { afterEach, beforeAll } from 'vitest';
-import { setAutoSnapshotOptions, toTaskId } from "../client.js";
+import { toTaskId } from "../client.js";
 import { ctx } from "../client/ctx.js";
 import { shouldTakeSnapshot } from "../client/should_take_snapshot.js";
-import { enableAuto, getAutoSnapshotOptions } from "../client/snapshot_options.js";
+import { enableAuto, extractAutoSnapshotOptions } from "../client/snapshot_options.js";
 export function createVis(commands) {
     let subjectDataTestId;
     const vis = {
@@ -35,9 +35,10 @@ export function createVis(commands) {
                 const test = ctx.getCurrentTest();
                 if ((test?.result?.errors?.length ?? 0) > 0)
                     return;
-                const meta = getAutoSnapshotOptions(test);
+                const meta = extractAutoSnapshotOptions(test);
                 if (!shouldTakeSnapshot(meta))
                     return;
+                test.meta.vis = { ...test.meta.vis, isAutoSnapshot: true };
                 await test.context.expect(getSubject(meta?.subjectDataTestId ?? subjectDataTestId)).toMatchImageSnapshot(meta);
             },
             matchPerTheme(themes) {
@@ -45,7 +46,7 @@ export function createVis(commands) {
                     const test = ctx.getCurrentTest();
                     if ((test?.result?.errors?.length ?? 0) > 0)
                         return;
-                    const meta = getAutoSnapshotOptions(test);
+                    const meta = extractAutoSnapshotOptions(test);
                     if (!shouldTakeSnapshot(meta))
                         return;
                     const errors = [];
@@ -60,7 +61,7 @@ export function createVis(commands) {
                                 .toMatchImageSnapshot({
                                 ...meta,
                                 customizeSnapshotId: meta?.customizeSnapshotId
-                                    ? ({ id, index }) => `${meta.customizeSnapshotId({ id, index })}-${themeId}`
+                                    ? ({ id, index }) => `${meta.customizeSnapshotId({ id, index, isAutoSnapshot: true })}-${themeId}`
                                     : ({ id }) => `${id}-${themeId}`,
                             });
                         }

package/esm/setup/vis.d.ts

@@ -1,5 +1,5 @@
 /**
  * Visual test configuration on the client side.
  */
-export declare const vis: import("./create_vis.ts").VisClientConfigurator<import("../index.ts").SnapshotMeta<any>>;
+export declare const vis: import("./create_vis.ts").VisClientConfigurator<import("../index.ts").SnapshotMeta<import("../index.ts").ComparisonMethod>>;
 //# sourceMappingURL=vis.d.ts.map

package/esm/setup/vis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vis.d.ts","sourceRoot":"","sources":["../../src/setup/vis.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,GAAG,0FAAsB,CAAA"}
+{"version":3,"file":"vis.d.ts","sourceRoot":"","sources":["../../src/setup/vis.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,GAAG,6HAAsB,CAAA"}

package/esm/shared/types.d.ts

@@ -18,6 +18,7 @@ export interface ImageSnapshotIdOptions {
     customizeSnapshotId?: (context: {
         id: string;
         index: number;
+        isAutoSnapshot: boolean;
     }) => string;
 }
 export type ComparisonMethod = 'pixel' | 'ssim';
@@ -59,4 +60,15 @@ export type AutoSnapshotOptions = {
      */
     subjectDataTestId?: string | undefined;
 };
+export type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTimeoutOptions & ImageSnapshotIdOptions & ImageSnapshotCompareOptions<M> & {
+    /**
+     * Expect the matcher to fail.
+     * If it passes, it will throw an error with details.
+     */
+    expectToFail?: boolean | undefined;
+};
+export type SnapshotMeta<M extends ComparisonMethod> = ToMatchImageSnapshotOptions<M> & AutoSnapshotOptions & {
+    enable?: boolean | undefined;
+    [key: string]: unknown;
+};
 //# sourceMappingURL=types.d.ts.map

package/esm/shared/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,YAAY,CAAA;AACxC,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,SAAS,CAAA;AAErD,MAAM,WAAW,2BAA2B;IAC3C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC/B,EAAE,EAAE,MAAM,CAAA;QAGV,KAAK,EAAE,MAAM,CAAA;KACb,KAAK,MAAM,CAAA;CACZ;AAED,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAA;AAE/C,MAAM,MAAM,uBAAuB,GAAG;IACrC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAA;IACtD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,GAAG,MAAM,IAAI;IAC/C,gBAAgB,EAAE,CAAC,CAAA;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,SAAS,CAAA;CAC9C,CAAA;AACD,MAAM,MAAM,sBAAsB,CAAC,CAAC,GAAG,OAAO,IAAI;IACjD,gBAAgB,CAAC,EAAE,CAAC,GAAG,SAAS,CAAA;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;CAC1D,CAAA;AAED,MAAM,MAAM,2BAA2B,CAAC,CAAC,SAAS,gBAAgB,GAAG,OAAO,IAAI,CAAC,CAAC,SAAS,MAAM,GAC9F,qBAAqB,CAAC,CAAC,CAAC,GACxB,sBAAsB,CAAC,CAAC,CAAC,CAAC,GAC5B,uBAAuB,CAAA;AAExB,MAAM,MAAM,mBAAmB,GAAG;IACjC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,YAAY,CAAA;AACxC,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,SAAS,CAAA;AAIrD,MAAM,WAAW,2BAA2B;IAC3C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC/B,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,EAAE,MAAM,CAAA;QACb,cAAc,EAAE,OAAO,CAAA;KACvB,KAAK,MAAM,CAAA;CACZ;AAED,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAA;AAE/C,MAAM,MAAM,uBAAuB,GAAG;IACrC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAA;IACtD;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC,CAAA;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,GAAG,MAAM,IAAI;IAC/C,gBAAgB,EAAE,CAAC,CAAA;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,SAAS,CAAA;CAC9C,CAAA;AACD,MAAM,MAAM,sBAAsB,CAAC,CAAC,GAAG,OAAO,IAAI;IACjD,gBAAgB,CAAC,EAAE,CAAC,GAAG,SAAS,CAAA;IAChC;;OAEG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;CAC1D,CAAA;AAED,MAAM,MAAM,2BAA2B,CAAC,CAAC,SAAS,gBAAgB,GAAG,OAAO,IAAI,CAAC,CAAC,SAAS,MAAM,GAC9F,qBAAqB,CAAC,CAAC,CAAC,GACxB,sBAAsB,CAAC,CAAC,CAAC,CAAC,GAC5B,uBAAuB,CAAA;AAExB,MAAM,MAAM,mBAAmB,GAAG;IACjC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC,CAAA;AACD,MAAM,MAAM,2BAA2B,CAAC,CAAC,SAAS,gBAAgB,GAAG,OAAO,IAAI,2BAA2B,GAC1G,sBAAsB,GACtB,2BAA2B,CAAC,CAAC,CAAC,GAAG;IAChC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAClC,CAAA;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,gBAAgB,IAAI,2BAA2B,CAAC,CAAC,CAAC,GACpF,mBAAmB,GAAG;IACrB,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-plugin-vis",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Vitest visual testing plugin",
   "keywords": [
     "image-snapshot",

package/readme.md

@@ -83,7 +83,8 @@ export default defineConfig({
 			}) => `__vis__/${ci ? platform : 'local'}`,
 			platform: '...', // {process.platform} or `local` (deprecated use `snapshotRootDir` instead)
 			customizeSnapshotSubpath: (subpath) => trimCommonFolder(subpath),
-			customizeSnapshotId: ({ id, index }) => `${id}-${index}`,
+			// will change to "isAutoSnapshot ? `${id}-auto` : `${id}-${index}`" in the next major release.
+			customizeSnapshotId: ({ id, index, isAutoSnapshot }) => `${id}-${index}`,
 			// set a default subject (e.g. 'subject') to capture image snapshot
 			subjectDataTestId: undefined,
 			comparisonMethod: 'pixel',
@@ -217,7 +218,7 @@ setAutoSnapshotOptions(true /* or false */)
 setAutoSnapshotOptions({
 	enable: true,
 	comparisonMethod: 'pixel',
-	customizeSnapshotId: ({ id, index }) => `${id}-custom-${index}`,
+	customizeSnapshotId: ({ id, index, isAutoSnapshot }) => `${id}-custom-${index}`,
 	// pixelmatch or ssim.js options, depending on `comparisonMethod`.
 	diffOptions: { threshold: 0.01 },
 	failureThreshold: 0.01,
@@ -285,7 +286,7 @@ it('manual snapshot with options', async ({ expect }) => {
 	page.render(<div data-testid="subject">hello world</div>)
 	const subject = page.getByTestId('subject')
 	await expect(subject).toMatchImageSnapshot({
-		customizeSnapshotId: ({ id, index }) => `${id}-custom-${index}`,
+		customizeSnapshotId: ({ id, index, isAutoSnapshot }) => `${id}-custom-${index}`,
 		failureThreshold: 0.01,
 		failureThresholdType: 'percent',
 		diffOptions: {

package/src/client/ctx.ts

@@ -1,12 +1,12 @@
 import { getCurrentSuite, getCurrentTest } from './vitest_suite_proxy.ts'
 
 export const ctx = {
-	autoEnabled: false,
+	autoEnabled: undefined as boolean | undefined,
 	getCurrentTest,
 	getCurrentSuite,
 	__test__reset() {
 		ctx.getCurrentTest = getCurrentTest
 		ctx.getCurrentSuite = getCurrentSuite
-		ctx.autoEnabled = false
+		ctx.autoEnabled = undefined
 	},
 }

package/src/client/expect/to_match_image_snapshot.ts

@@ -1,9 +1,9 @@
 import { commands } from '@vitest/browser/context'
 import type { AsyncExpectationResult } from '@vitest/expect'
+import type { ToMatchImageSnapshotOptions } from '../../shared/types.ts'
 import { ctx } from '../ctx.ts'
 import { imageSnapshotMatcher } from '../image_snapshot_matcher.ts'
 import { success } from './expectation_result.ts'
-import type { ToMatchImageSnapshotOptions } from './to_match_image_snapshot.types.ts'
 
 export function toMatchImageSnapshot(
 	/**

package/src/client/expect/to_match_image_snapshot.types.ts

@@ -1,20 +1,5 @@
-import type {
-	ComparisonMethod,
-	ImageSnapshotCompareOptions,
-	ImageSnapshotIdOptions,
-	ImageSnapshotTimeoutOptions,
-} from '../../shared/types.ts'
+import type { ComparisonMethod, ToMatchImageSnapshotOptions } from '../../shared/types.ts'
 
 export interface ImageSnapshotMatcher {
 	toMatchImageSnapshot<M extends ComparisonMethod>(options?: ToMatchImageSnapshotOptions<M> | undefined): Promise<void>
 }
-
-export type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTimeoutOptions &
-	ImageSnapshotIdOptions &
-	ImageSnapshotCompareOptions<M> & {
-		/**
-		 * Expect the matcher to fail.
-		 * If it passes, it will throw an error with details.
-		 */
-		expectToFail?: boolean | undefined
-	}

package/src/client/image_snapshot_matcher.logic.ts

@@ -1,4 +1,4 @@
-import type { ToMatchImageSnapshotOptions } from './expect/to_match_image_snapshot.types.ts'
+import type { ToMatchImageSnapshotOptions } from '../shared/types.ts'
 
 export function prettifyOptions(options: ToMatchImageSnapshotOptions<any> | undefined) {
 	if (!options) return 'none'

package/src/client/image_snapshot_matcher.ts

@@ -1,28 +1,37 @@
+import { isA } from '@vitest/expect'
 import dedent from 'dedent'
 import { resolve } from 'pathe'
-import type { Task } from 'vitest'
 import type { ImageSnapshotNextIndexCommand } from '../commands.ts'
 import type { PrepareImageSnapshotComparisonCommand } from '../server/commands/prepare_image_snapshot_comparison.ts'
 import type { WriteImageSnapshotCommand } from '../server/commands/write_image_snapshot.ts'
 import { isBase64String } from '../shared/base64.ts'
 import { compareImage } from '../shared/compare_image.ts'
+import type { ToMatchImageSnapshotOptions } from '../shared/types.ts'
 import { alignImagesToSameSize } from './align_images.ts'
-import type { ToMatchImageSnapshotOptions } from './expect/to_match_image_snapshot.types.ts'
 import { toDataURL, toImageData } from './image_data.ts'
 import { prettifyOptions } from './image_snapshot_matcher.logic.ts'
 import { convertElementToCssSelector } from './selector.ts'
 import { toTaskId } from './task_id.ts'
 import { server } from './vitest_browser_context_proxy.ts'
+import type { CurrentTest } from './vitest_suite_proxy.ts'
 
 export function imageSnapshotMatcher(
 	commands: PrepareImageSnapshotComparisonCommand & WriteImageSnapshotCommand & ImageSnapshotNextIndexCommand,
 ) {
-	return async function matchImageSnapshot(test: Task, subject: any, options?: ToMatchImageSnapshotOptions<any>) {
+	return async function matchImageSnapshot(
+		test: CurrentTest & {},
+		subject: any,
+		options?: ToMatchImageSnapshotOptions<any>,
+	) {
+		const isAutoSnapshot = !!test.meta.vis?.isAutoSnapshot
 		const taskId = toTaskId(test)
 		const info = await commands.prepareImageSnapshotComparison(
 			taskId,
 			parseImageSnapshotSubject(subject),
-			options?.customizeSnapshotId ? await parseImageSnapshotOptions(commands, taskId, options) : options,
+			isAutoSnapshot,
+			options?.customizeSnapshotId
+				? await parseImageSnapshotOptions(commands, taskId, isAutoSnapshot, options)
+				: options,
 		)
 
 		if (!info) return
@@ -103,10 +112,11 @@ async function writeSnapshot(commands: WriteImageSnapshotCommand, path: string,
 async function parseImageSnapshotOptions(
 	commands: ImageSnapshotNextIndexCommand,
 	taskId: string,
+	isAutoSnapshot: boolean,
 	options: ToMatchImageSnapshotOptions<any>,
 ) {
 	const index = await commands.imageSnapshotNextIndex(taskId)
 	const { customizeSnapshotId, ...rest } = options
-	const snapshotFileId = customizeSnapshotId!({ id: taskId, index })
+	const snapshotFileId = customizeSnapshotId!({ id: taskId, index, isAutoSnapshot })
 	return { ...rest, snapshotFileId }
 }

package/src/client/page/has_image_snapshot.ts

@@ -23,11 +23,18 @@ export function hasImageSnapshot(this: BrowserPage, options?: ImageSnapshotIdOpt
 		)
 	}
 	const taskId = toTaskId(test)
+	const isAutoSnapshot = !!test.meta.vis?.isAutoSnapshot
 	if (options?.customizeSnapshotId) {
 		return commands
 			.imageSnapshotNextIndex(taskId)
-			.then((index) => commands.hasImageSnapshot(taskId, options.customizeSnapshotId!({ id: taskId, index })))
+			.then((index) =>
+				commands.hasImageSnapshot(
+					taskId,
+					options.customizeSnapshotId!({ id: taskId, index, isAutoSnapshot }),
+					isAutoSnapshot,
+				),
+			)
 	}
 
-	return commands.hasImageSnapshot(taskId)
+	return commands.hasImageSnapshot(taskId, undefined, isAutoSnapshot)
 }

package/src/client/should_take_snapshot.ts

@@ -1,5 +1,6 @@
+import type { SnapshotMeta } from '../shared/types.ts'
 import { ctx } from './ctx.ts'
-import { type SnapshotMeta, getAutoSnapshotOptions } from './snapshot_options.ts'
+import { extractAutoSnapshotOptions } from './snapshot_options.ts'
 
 /**
  * Determine should snapshot be taken.
@@ -9,6 +10,6 @@ import { type SnapshotMeta, getAutoSnapshotOptions } from './snapshot_options.ts
  * disabled by `!snapshot` tag: false
  */
 export function shouldTakeSnapshot(meta?: SnapshotMeta<any> | undefined) {
-	const m = meta ?? getAutoSnapshotOptions(ctx.getCurrentTest())
+	const m = meta ?? extractAutoSnapshotOptions(ctx.getCurrentTest())
 	return document.body.childElementCount > 0 && m?.enable
 }

package/src/client/snapshot_options.ts

@@ -1,13 +1,6 @@
 import { NAME } from '../shared/constants.ts'
-import type { AutoSnapshotOptions, ComparisonMethod } from '../shared/types.ts'
+import type { ComparisonMethod, SnapshotMeta } from '../shared/types.ts'
 import { ctx } from './ctx.ts'
-import type { ToMatchImageSnapshotOptions } from './expect/to_match_image_snapshot.types.ts'
-
-export type SnapshotMeta<M extends ComparisonMethod> = ToMatchImageSnapshotOptions<M> &
-	AutoSnapshotOptions & {
-		enable?: boolean | undefined
-		[key: string]: unknown
-	}
 
 type Suite = { meta: Record<string, any>; suite?: Suite | undefined }
 
@@ -66,7 +59,9 @@ function parseMeta<M extends ComparisonMethod>(meta: boolean | SnapshotMeta<M>):
 	return typeof meta === 'boolean' ? ({ enable: meta } as any) : { enable: true, ...meta }
 }
 
-export function getAutoSnapshotOptions<M extends SnapshotMeta<any> = SnapshotMeta<any>>(task: MetaTask): M | undefined {
+export function extractAutoSnapshotOptions<M extends SnapshotMeta<any> = SnapshotMeta<any>>(
+	task: MetaTask,
+): M | undefined {
 	if (!task) return
 
 	const list: any[] = []
@@ -79,11 +74,8 @@ export function getAutoSnapshotOptions<M extends SnapshotMeta<any> = SnapshotMet
 	list.push(task.meta)
 	return list.reduce(
 		(acc, cur) => {
-			if (cur?.[NAME]) {
-				const { [NAME]: meta } = cur
-				return Object.assign({}, acc, meta)
-			}
-			return acc
+			const meta = cur?.[NAME]
+			return meta ? Object.assign({}, acc, meta) : acc
 		},
 		{ enable: ctx.autoEnabled },
 	)

package/src/client/vitest_suite_proxy.ts

@@ -1,3 +1,6 @@
+import type { NAME } from '../shared/constants.ts'
+import type { SnapshotMeta } from '../shared/types.ts'
+
 let vitestSuite: Awaited<typeof import('vitest/suite')>
 
 if ((globalThis as any).__vitest_browser__) {
@@ -6,5 +9,9 @@ if ((globalThis as any).__vitest_browser__) {
 	})
 }
 
-export const getCurrentTest = () => vitestSuite?.getCurrentTest()
+export type CurrentTest = ReturnType<typeof vitestSuite.getCurrentTest> & {
+	meta: { [NAME]?: SnapshotMeta<'pixel' | 'ssim'> & { isAutoSnapshot?: boolean | undefined } }
+}
+
+export const getCurrentTest = () => vitestSuite?.getCurrentTest() as CurrentTest
 export const getCurrentSuite = () => vitestSuite?.getCurrentSuite()

package/src/client.ts

@@ -2,6 +2,6 @@ export * from './client/expect/expectation_result.ts'
 export type * from './client/expect/to_match_image_snapshot.types.ts'
 export * from './client/image_snapshot_matcher.ts'
 export * from './client/should_take_snapshot.ts'
-export { type MetaTask, type SnapshotMeta, setAutoSnapshotOptions } from './client/snapshot_options.ts'
+export { setAutoSnapshotOptions, type MetaTask } from './client/snapshot_options.ts'
 export * from './client/task_id.ts'
 export type * from './shared/types.ts'

package/src/index.ts

@@ -2,4 +2,5 @@
 import './client/expect/augment.ts'
 import './client/page/augment.ts'
 
-export { type MetaTask, type SnapshotMeta, setAutoSnapshotOptions } from './client/snapshot_options.ts'
+export { setAutoSnapshotOptions, type MetaTask } from './client/snapshot_options.ts'
+export type * from './shared/types.ts'

package/src/server/commands/has_image_snapshot.ts

@@ -3,15 +3,13 @@ import { visContext } from '../vis_context.ts'
 import { assertTestPathDefined } from './_assertions.ts'
 
 export interface HasImageSnapshotCommand {
-	hasImageSnapshot(taskId: string, snapshotId?: string | undefined): Promise<boolean>
+	hasImageSnapshot(taskId: string, snapshotId: string | undefined, isAutoSnapshot: boolean): Promise<boolean>
 }
 
-export const hasImageSnapshot: BrowserCommand<[taskId: string, snapshotId?: string | undefined]> = async (
-	context,
-	taskId,
-	snapshotId,
-) => {
+export const hasImageSnapshot: BrowserCommand<
+	[taskId: string, snapshotId: string | undefined, isAutoSnapshot: boolean]
+> = async (context, taskId, snapshotId, isAutoSnapshot) => {
 	assertTestPathDefined(context, 'hasImageSnapshot')
 
-	return visContext.hasImageSnapshot(context.testPath, taskId, snapshotId)
+	return visContext.hasImageSnapshot(context.testPath, taskId, snapshotId, isAutoSnapshot)
 }

package/src/server/commands/match_image_snapshot.ts

@@ -20,6 +20,7 @@ export interface MatchImageSnapshotCommand {
 	matchImageSnapshot: (
 		taskId: string | undefined,
 		subject: string,
+		isAutoSnapshot: boolean,
 		options?: MatchImageSnapshotOptions | undefined,
 	) => Promise<void>
 }
@@ -34,15 +35,15 @@ export type MatchImageSnapshotOptions = ImageSnapshotTimeoutOptions &
 	}
 
 export const matchImageSnapshot: BrowserCommand<
-	[taskId: string, subject: string, options?: MatchImageSnapshotOptions | undefined]
-> = async (context, taskId, subject, options) => {
+	[taskId: string, subject: string, isAutoSnapshot: boolean, options?: MatchImageSnapshotOptions | undefined]
+> = async (context, taskId, subject, isAutoSnapshot, options) => {
 	assertTestPathDefined(context, 'matchImageSnapshot')
 
 	// vitest:browser passes in `null` when not defined
 	if (!options) options = {}
 	options.timeout = options.timeout ?? 30000
 
-	const info = visContext.getSnapshotInfo(context.testPath, taskId, options)
+	const info = visContext.getSnapshotInfo(context.testPath, taskId, isAutoSnapshot, options)
 	const baselineBuffer = await file.tryReadFile(info.baselinePath)
 	if (!baselineBuffer) {
 		if (isBase64String(subject)) {

package/src/server/commands/prepare_image_snapshot_comparison.ts

@@ -27,20 +27,21 @@ export interface PrepareImageSnapshotComparisonCommand {
 	prepareImageSnapshotComparison: (
 		taskId: string | undefined,
 		subject: string,
+		isAutoSnapshot: boolean,
 		options?: MatchImageSnapshotOptions | undefined,
 	) => Promise<ImageSnapshotComparisonInfo | undefined>
 }
 
 export const prepareImageSnapshotComparison: BrowserCommand<
-	[taskId: string, snapshotId: string, options?: MatchImageSnapshotOptions | undefined]
-> = async (context, taskId, subject, options) => {
+	[taskId: string, snapshotId: string, isAutoSnapshot: boolean, options?: MatchImageSnapshotOptions | undefined]
+> = async (context, taskId, subject, isAutoSnapshot, options) => {
 	assertTestPathDefined(context, 'prepareImageSnapshotComparison')
 
 	// vitest:browser passes in `null` when not defined
 	if (!options) options = {}
 	options.timeout = options.timeout ?? 30000
 
-	const info = visContext.getSnapshotInfo(context.testPath, taskId, options)
+	const info = visContext.getSnapshotInfo(context.testPath, taskId, isAutoSnapshot, options)
 	const baselineBuffer = await file.tryReadFile(info.baselinePath)
 	if (!baselineBuffer) {
 		if (isBase64String(subject)) {

package/src/server/vis_context.logic.ts

@@ -43,11 +43,16 @@ export function createVisContext() {
 			await Promise.allSettled([ctx.rimraf(suite.diffDir), ctx.rimraf(suite.resultDir)])
 			return pick(state, 'subjectDataTestId')
 		},
-		getSnapshotInfo(testPath: string, name: string, options?: { snapshotFileId?: string | undefined }) {
-			const info = context.getSuiteInfo(testPath, name)
-			const snapshotFilename = context.getSnapshotFilename(info, options?.snapshotFileId)
+		getSnapshotInfo(
+			testPath: string,
+			name: string,
+			isAutoSnapshot: boolean,
+			options?: { snapshotFileId?: string | undefined },
+		) {
+			const suiteInfo = context.getSuiteInfo(testPath, name)
+			const snapshotFilename = context.getSnapshotFilename(suiteInfo, options?.snapshotFileId, isAutoSnapshot)
 
-			const { baselineDir, resultDir, diffDir, task } = info
+			const { baselineDir, resultDir, diffDir, task } = suiteInfo
 
 			task.count = task.count + 1
 			const baselinePath = join(baselineDir, snapshotFilename)
@@ -64,17 +69,22 @@ export function createVisContext() {
 		getTaskCount(testPath: string, taskId: string) {
 			return context.getSuiteInfo(testPath, taskId).task.count
 		},
-		hasImageSnapshot(testPath: string, taskId: string, snapshotFileId: string | undefined) {
+		hasImageSnapshot(testPath: string, taskId: string, snapshotFileId: string | undefined, isAutoSnapshot: boolean) {
 			const info = context.getSuiteInfo(testPath, taskId)
-			return file.existFile(join(info.baselineDir, context.getSnapshotFilename(info, snapshotFileId)))
+			return file.existFile(join(info.baselineDir, context.getSnapshotFilename(info, snapshotFileId, isAutoSnapshot)))
 		},
-		getSnapshotFilename(info: { taskId: string; task: { count: number } }, snapshotFileId: string | undefined) {
-			if (snapshotFileId) return `${snapshotFileId}.png`
+		getSnapshotFilename(
+			info: { taskId: string; task: { count: number } },
 
+			snapshotFileId: string | undefined,
+			isAutoSnapshot: boolean,
+		) {
+			if (snapshotFileId) return `${snapshotFileId}.png`
 			const customizeSnapshotId = visOptions.customizeSnapshotId ?? (({ id, index }) => `${id}-${index}`)
 			return `${customizeSnapshotId({
 				id: info.taskId,
 				index: info.task.count,
+				isAutoSnapshot,
 			})}.png`
 		},
 		getSuiteInfo(testPath: string, taskId: string) {

package/src/setup/create_vis.ts

@@ -1,15 +1,15 @@
 import dedent from 'dedent'
 import { afterEach, beforeAll } from 'vitest'
-import { type SnapshotMeta, setAutoSnapshotOptions, toTaskId } from '../client.ts'
+import { type ComparisonMethod, type SnapshotMeta, toTaskId } from '../client.ts'
 import { ctx } from '../client/ctx.ts'
 import { shouldTakeSnapshot } from '../client/should_take_snapshot.ts'
-import { enableAuto, getAutoSnapshotOptions } from '../client/snapshot_options.ts'
+import { enableAuto, extractAutoSnapshotOptions } from '../client/snapshot_options.ts'
 import type { SetupVisSuiteCommand } from '../server/commands/setup_vis_suite.ts'
 
 /**
  * Visual test configuration on the client side.
  */
-export type VisClientConfigurator<M extends SnapshotMeta<any>> = {
+export type VisClientConfigurator<SM extends SnapshotMeta<ComparisonMethod>> = {
 	presets: {
 		/**
 		 * Enable visual testing.
@@ -45,23 +45,23 @@ export type VisClientConfigurator<M extends SnapshotMeta<any>> = {
 		 * })
 		 * ```
 		 */
-		theme(themes: Record<string, (options: M) => Promise<boolean> | Promise<void> | boolean | void>): void
+		theme<M>(themes: Record<string, (options: M & SM) => Promise<boolean> | Promise<void> | boolean | void>): void
 	}
 	beforeAll: {
 		setup(): Promise<void>
 	}
 	afterEach: {
 		matchImageSnapshot(): Promise<void>
-		matchPerTheme(
-			themes: Record<string, (options: M) => Promise<boolean> | Promise<void> | boolean | void>,
+		matchPerTheme<M>(
+			themes: Record<string, (options: M & SM) => Promise<boolean> | Promise<void> | boolean | void>,
 		): () => Promise<void>
 	}
 }
 
-export function createVis<M extends SnapshotMeta<any>>(commands: SetupVisSuiteCommand) {
+export function createVis<SM extends SnapshotMeta<ComparisonMethod>>(commands: SetupVisSuiteCommand) {
 	let subjectDataTestId: string | undefined
 
-	const vis: VisClientConfigurator<M> = {
+	const vis: VisClientConfigurator<SM> = {
 		presets: {
 			enable() {
 				beforeAll(vis.beforeAll.setup)
@@ -75,7 +75,7 @@ export function createVis<M extends SnapshotMeta<any>>(commands: SetupVisSuiteCo
 				afterEach(vis.afterEach.matchImageSnapshot)
 				enableAuto()
 			},
-			theme(themes: Record<string, (options: M) => Promise<boolean> | Promise<void> | boolean | void>) {
+			theme(themes) {
 				beforeAll(vis.beforeAll.setup)
 				afterEach(vis.afterEach.matchPerTheme(themes))
 			},
@@ -91,38 +91,40 @@ export function createVis<M extends SnapshotMeta<any>>(commands: SetupVisSuiteCo
 
 				if ((test?.result?.errors?.length ?? 0) > 0) return
 
-				const meta = getAutoSnapshotOptions(test)
+				const meta = extractAutoSnapshotOptions(test)
 				if (!shouldTakeSnapshot(meta)) return
 
+				test.meta.vis = { ...test.meta.vis, isAutoSnapshot: true }
+
 				await test!.context.expect(getSubject(meta?.subjectDataTestId ?? subjectDataTestId)).toMatchImageSnapshot(meta)
 			},
-			matchPerTheme(themes: Record<string, (options: M) => Promise<boolean> | Promise<void> | boolean | void>) {
+			matchPerTheme(themes) {
 				return async function matchImageSnapshot() {
 					const test = ctx.getCurrentTest()
 					if ((test?.result?.errors?.length ?? 0) > 0) return
 
-					const meta = getAutoSnapshotOptions<M>(test)
+					const meta = extractAutoSnapshotOptions(test)
 					if (!shouldTakeSnapshot(meta)) return
-					const errors: any[] = []
+					const errors: Array<[string, Error]> = []
 					for (const themeId in themes) {
 						try {
 							await new Promise((a) => setTimeout(a, 10))
-							const r = await themes[themeId]!(meta!)
+							const r = await themes[themeId]!(meta! as any)
 							if (r === false) continue
 							await test!.context
 								.expect(getSubject(meta?.subjectDataTestId ?? subjectDataTestId))
 								.toMatchImageSnapshot({
 									...meta,
 									customizeSnapshotId: meta?.customizeSnapshotId
-										? ({ id, index }) => `${meta.customizeSnapshotId!({ id, index })}-${themeId}`
+										? ({ id, index }) => `${meta.customizeSnapshotId!({ id, index, isAutoSnapshot: true })}-${themeId}`
 										: ({ id }) => `${id}-${themeId}`,
 								})
 						} catch (error) {
-							errors.push([themeId, error])
+							errors.push([themeId, error as Error])
 						}
 					}
 					if (errors.length > 0) {
-						if (errors.length === 1) throw errors[0][1]
+						if (errors.length === 1) throw errors[0]![1]
 						const taskId = toTaskId(test!)
 						throw new AggregateError(
 							errors,

package/src/shared/types.ts

@@ -1,5 +1,7 @@
 import type pixelMatch from 'pixelmatch'
 import type { Options as SsimOptions } from 'ssim.js'
+import type { getCurrentTest } from 'vitest/suite'
+import type { NAME } from './constants.ts'
 
 export interface ImageSnapshotTimeoutOptions {
 	/**
@@ -19,9 +21,8 @@ export interface ImageSnapshotIdOptions {
 	 */
 	customizeSnapshotId?: (context: {
 		id: string
-		// width: number
-		// height: number
 		index: number
+		isAutoSnapshot: boolean
 	}) => string
 }
 
@@ -71,3 +72,18 @@ export type AutoSnapshotOptions = {
 	 */
 	subjectDataTestId?: string | undefined
 }
+export type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTimeoutOptions &
+	ImageSnapshotIdOptions &
+	ImageSnapshotCompareOptions<M> & {
+		/**
+		 * Expect the matcher to fail.
+		 * If it passes, it will throw an error with details.
+		 */
+		expectToFail?: boolean | undefined
+	}
+
+export type SnapshotMeta<M extends ComparisonMethod> = ToMatchImageSnapshotOptions<M> &
+	AutoSnapshotOptions & {
+		enable?: boolean | undefined
+		[key: string]: unknown
+	}