vitest-plugin-vis 2.1.1 → 2.3.0

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;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAA;AAE1C,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;AAEF,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,GAAG;IAC7D,IAAI,EAAE;QAAE,CAAC,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG;YAAE,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;SAAE,CAAA;KAAE,CAAA;CAC5F,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-plugin-vis",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Vitest visual testing plugin",
   "keywords": [
     "image-snapshot",
@@ -40,6 +40,10 @@
       "types": "./esm/presets/auto.d.ts",
       "default": "./esm/presets/auto.js"
     },
+    "./presets/enable": {
+      "types": "./esm/presets/enable.d.ts",
+      "default": "./esm/presets/enable.js"
+    },
     "./presets/manual": {
       "types": "./esm/presets/manual.d.ts",
       "default": "./esm/presets/manual.js"

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',
@@ -94,7 +95,7 @@ export default defineConfig({
 			failureThreshold: 0,
 		})
 	],
-	test:{
+	test: {
 		browser: {/* ... */}
 	}
 })
@@ -113,8 +114,8 @@ export default defineConfig({
 	plugins: [
 		vis({ preset: 'none' })
 	],
-	test:{
-		browser:{/* ... */},
+	test: {
+		browser: {/* ... */},
 		setupFiles: ['vitest.setup.ts']
 	}
 })
@@ -123,13 +124,17 @@ export default defineConfig({
 import { vis } from 'vitest-plugin-vis/setup'
 
 // if you set `preset: none` in `vitest.config.ts`,
-// you can enable `auto` or `manual` setup here
+// you can use a preset manually here.
+
+// Take snapshot at the end of each rendering test.
 vis.presets.auto()
+// Enable snapshot testing for manual snapshot only.
 vis.presets.manual()
+// Enable snapshot testing, allow auto snapshot with `setAutoSnapshotOptions()`
+vis.presets.enable()
 
-
-// or capture image snapshot for all rendering tests
-// for multiple themes (light and dark in this example)
+// Take image snapshot for each rendering test,
+// one snapshot per theme (light and dark in this example).
 //
 // Note that this changes the theme in the `afterEach` hook.
 // If you want to capture manual snapshots in different themes,
@@ -160,10 +165,10 @@ To address this, you can add the following to your `tsconfig.json`:
 
 ## Usage
 
-### Auto Snapshot
+### Auto Preset
 
 By default, the plugin will use the `auto` preset,
-which will take a snapshot at the end of each test.
+which will take a snapshot at the end of each rendering test.
 
 You can control how the auto snapshot is taken using the `setAutoSnapshotOptions` function:
 
@@ -213,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,
@@ -238,7 +243,7 @@ vis.presets.theme({
 })
 ```
 
-### Manual Snapshot
+### Manual Preset
 
 You can also set the preset to `manual` and compare snapshots manually:
 
@@ -251,7 +256,7 @@ export default defineConfig({
 		vis({ preset: 'manual' })
 	],
 	test:{
-		browser:{/* ... */}
+		browser: {/* ... */}
 	}
 })
 
@@ -281,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: {
@@ -292,6 +297,23 @@ it('manual snapshot with options', async ({ expect }) => {
 })
 ```
 
+### Enable Preset
+
+The `enable` preset allows you to take manual snapshot,
+as well as auto snapshot at the end on a rendering test using the `setAutoSnapshotOptions` function:
+
+```ts
+import { setAutoSnapshotOptions } from 'vitest-plugin-vis'
+import { beforeEach, it } from 'vitest'
+
+
+it('take snapshot', async () => {
+	setAutoSnapshotOptions(/* options */) // e.g. `true`
+
+	// ...your test...
+})
+```
+
 ### Has Snapshot
 
 While less common, you can also check if a snapshot exists:
@@ -311,7 +333,7 @@ it('Has Snapshot', async ({ expect }) => {
 })
 ```
 
-This is useful when you are performing some negative test.
+This is useful when you are performing negative test.
 
 ## Git Ignore
 

package/src/client/ctx.ts

@@ -1,10 +1,12 @@
 import { getCurrentSuite, getCurrentTest } from './vitest_suite_proxy.ts'
 
 export const ctx = {
+	autoEnabled: undefined as boolean | undefined,
 	getCurrentTest,
 	getCurrentSuite,
 	__test__reset() {
 		ctx.getCurrentTest = getCurrentTest
 		ctx.getCurrentSuite = getCurrentSuite
+		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,13 +1,12 @@
 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 { CurrentTest, 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'
@@ -17,12 +16,19 @@ import { server } from './vitest_browser_context_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,
+			options?.customizeSnapshotId
+				? await parseImageSnapshotOptions(commands, taskId, isAutoSnapshot, options)
+				: options,
 		)
 
 		if (!info) return
@@ -103,10 +109,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

@@ -26,7 +26,12 @@ export function hasImageSnapshot(this: BrowserPage, options?: ImageSnapshotIdOpt
 	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: !!test.meta.vis?.isAutoSnapshot }),
+				),
+			)
 	}
 
 	return commands.hasImageSnapshot(taskId)

package/src/client/should_take_snapshot.ts

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

package/src/client/snapshot_options.ts

@@ -1,14 +1,6 @@
-import { getCurrentTest } from 'vitest/suite'
 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 }
 
@@ -20,6 +12,10 @@ export type MetaTask =
 	  }
 	| undefined
 
+export function enableAuto() {
+	ctx.autoEnabled = true
+}
+
 /**
  * Set the snapshot options for auto snapshot.
  *
@@ -62,3 +58,25 @@ function parseArgs<M extends ComparisonMethod>(
 function parseMeta<M extends ComparisonMethod>(meta: boolean | SnapshotMeta<M>): SnapshotMeta<M> {
 	return typeof meta === 'boolean' ? ({ enable: meta } as any) : { enable: true, ...meta }
 }
+
+export function extractAutoSnapshotOptions<M extends SnapshotMeta<any> = SnapshotMeta<any>>(
+	task: MetaTask,
+): M | undefined {
+	if (!task) return
+
+	const list: any[] = []
+	let current = task
+	while (current?.suite) {
+		list.unshift(current.suite.meta)
+		current = current.suite
+	}
+	list.unshift(task.file?.meta)
+	list.push(task.meta)
+	return list.reduce(
+		(acc, cur) => {
+			const meta = cur?.[NAME]
+			return meta ? Object.assign({}, acc, meta) : acc
+		},
+		{ enable: ctx.autoEnabled },
+	)
+}

package/src/client/vitest_suite_proxy.ts

@@ -1,3 +1,5 @@
+import type { CurrentTest } from '../shared/types.ts'
+
 let vitestSuite: Awaited<typeof import('vitest/suite')>
 
 if ((globalThis as any).__vitest_browser__) {
@@ -6,5 +8,5 @@ if ((globalThis as any).__vitest_browser__) {
 	})
 }
 
-export const getCurrentTest = () => vitestSuite?.getCurrentTest()
+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 * 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/config/types.ts

@@ -15,7 +15,7 @@ export type VisOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTime
 		/**
 		 * Loads the `test.setupFiles` of the specified preset.
 		 */
-		preset?: 'manual' | 'auto' | 'none' | undefined
+		preset?: 'enable' | 'manual' | 'auto' | 'none' | undefined
 		/**
 		 * The name of the subdirectory that the baseline snapshots get saved in.
 		 *

package/src/index.ts

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

package/src/presets/enable.ts

@@ -0,0 +1,5 @@
+import { vis } from '../setup/vis.ts'
+import '../client/expect/extend.ts'
+import '../client/page/extend.ts'
+
+vis.presets.enable()

package/src/server/vis_context.logic.ts

@@ -1,7 +1,9 @@
 import { join, relative } from 'pathe'
 import { pick } from 'type-plus'
+import { getCurrentTest } from 'vitest/suite'
 import type { VisOptions } from '../config/types.ts'
 import { BASELINE_DIR, DIFF_DIR, RESULT_DIR } from '../shared/constants.ts'
+import type { CurrentTest } from '../shared/types.ts'
 import { file } from './file.ts'
 import { getSnapshotSubpath, resolveSnapshotRootDir } from './snapshot_path.ts'
 import { ctx } from './vis_context.ctx.ts'
@@ -70,11 +72,13 @@ export function createVisContext() {
 		},
 		getSnapshotFilename(info: { taskId: string; task: { count: number } }, snapshotFileId: string | undefined) {
 			if (snapshotFileId) return `${snapshotFileId}.png`
-
+			const test = getCurrentTest() as CurrentTest
+			const isAutoSnapshot = !!test?.meta.vis?.isAutoSnapshot
 			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,49 +1,81 @@
 import dedent from 'dedent'
 import { afterEach, beforeAll } from 'vitest'
-import { type SnapshotMeta, 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 { getAutoSnapshotOptions } from '../client/snapshot_options.internal.js'
+import { enableAuto, extractAutoSnapshotOptions } from '../client/snapshot_options.ts'
 import type { SetupVisSuiteCommand } from '../server/commands/setup_vis_suite.ts'
 
-export function createVis<M extends SnapshotMeta<any>>(commands: SetupVisSuiteCommand) {
+/**
+ * Visual test configuration on the client side.
+ */
+export type VisClientConfigurator<SM extends SnapshotMeta<ComparisonMethod>> = {
+	presets: {
+		/**
+		 * Enable visual testing.
+		 *
+		 * auto snapshot is turned off by default.
+		 * You can specify the test to take a snapshot during `afterEach()` hook with `setAutoSnapshotOptions()`.
+		 */
+		enable(): void
+		/**
+		 * Enable visual testing.
+		 *
+		 * `setAutoSnapshotOptions` will have no effect in this preset.
+		 */
+		manual(): void
+		/**
+		 * Enable automatic visual testing.
+		 *
+		 * This will take a snapshot after each test.
+		 */
+		auto(): void
+		/**
+		 * Enable automatic visual testing with multiple themes.
+		 *
+		 * This will take a snapshot after each test for each theme.
+		 *
+		 * @param themes A record of theme names and their setup functions.
+		 *
+		 * @example
+		 * ```ts
+		 * vis().presets.theme({
+		 *  light() { document.body.classList.add('light') },
+		 *  dark() { document.body.classList.add('dark') },
+		 * })
+		 * ```
+		 */
+		theme<M>(themes: Record<string, (options: M & SM) => Promise<boolean> | Promise<void> | boolean | void>): void
+	}
+	beforeAll: {
+		setup(): Promise<void>
+	}
+	afterEach: {
+		matchImageSnapshot(): Promise<void>
+		matchPerTheme<M>(
+			themes: Record<string, (options: M & SM) => Promise<boolean> | Promise<void> | boolean | void>,
+		): () => Promise<void>
+	}
+}
+
+export function createVis<SM extends SnapshotMeta<ComparisonMethod>>(commands: SetupVisSuiteCommand) {
 	let subjectDataTestId: string | undefined
-	/**
-	 * Visual test configuration on the client side.
-	 */
-	const vis = {
+
+	const vis: VisClientConfigurator<SM> = {
 		presets: {
-			/**
-			 * Enable manual visual testing.
-			 */
+			enable() {
+				beforeAll(vis.beforeAll.setup)
+				afterEach(vis.afterEach.matchImageSnapshot)
+			},
 			manual() {
 				beforeAll(vis.beforeAll.setup)
 			},
-			/**
-			 * Enable automatic visual testing.
-			 *
-			 * This will take a snapshot after each test.
-			 */
 			auto() {
 				beforeAll(vis.beforeAll.setup)
 				afterEach(vis.afterEach.matchImageSnapshot)
+				enableAuto()
 			},
-			/**
-			 * Enable automatic visual testing with multiple themes.
-			 *
-			 * This will take a snapshot after each test for each theme.
-			 *
-			 * @param themes A record of theme names and their setup functions.
-			 *
-			 * @example
-			 * ```ts
-			 * vis().presets.theme({
-			 *  light() { document.body.classList.add('light') },
-			 *  dark() { document.body.classList.add('dark') },
-			 * })
-			 * ```
-			 */
-			theme(themes: Record<string, (options: M) => Promise<boolean> | Promise<void> | boolean | void>) {
+			theme(themes) {
 				beforeAll(vis.beforeAll.setup)
 				afterEach(vis.afterEach.matchPerTheme(themes))
 			},
@@ -59,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,22 @@ 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
+	}
+
+export type CurrentTest = ReturnType<typeof getCurrentTest> & {
+	meta: { [NAME]?: SnapshotMeta<'pixel' | 'ssim'> & { isAutoSnapshot?: boolean | undefined } }
+}

package/esm/client/snapshot_options.internal.d.ts

@@ -1,3 +0,0 @@
-import type { MetaTask, SnapshotMeta } from './snapshot_options.ts';
-export declare function getAutoSnapshotOptions<M extends SnapshotMeta<any> = SnapshotMeta<any>>(task: MetaTask): M | undefined;
-//# sourceMappingURL=snapshot_options.internal.d.ts.map

package/esm/client/snapshot_options.internal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"snapshot_options.internal.d.ts","sourceRoot":"","sources":["../../src/client/snapshot_options.internal.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEnE,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,YAAY,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAkBrH"}

package/esm/client/snapshot_options.internal.js

@@ -1,20 +0,0 @@
-import { NAME } from "../shared/constants.js";
-export function getAutoSnapshotOptions(task) {
-    if (!task)
-        return;
-    const list = [];
-    let current = task;
-    while (current?.suite) {
-        list.unshift(current.suite.meta);
-        current = current.suite;
-    }
-    list.unshift(task.file?.meta);
-    list.push(task.meta);
-    return list.reduce((acc, cur) => {
-        if (cur?.[NAME]) {
-            const { [NAME]: meta } = cur;
-            return Object.assign({}, acc, meta);
-        }
-        return acc;
-    }, {});
-}