vitest-plugin-vis 5.0.0 → 5.1.1

package/src/client/page/to_match_image_snapshot.mdx

@@ -68,6 +68,25 @@ it('should use custom snapshot key', async () => {
 })
 ```
 
+#### `createMissingBaseline`
+
+When `true`, if there is **no baseline image yet**,
+the matcher writes the captured image to the baseline path and the assertion succeeds—without using Vitest's `-u` / `updateSnapshot` mode.
+If a baseline already exists, `createMissingBaseline` does not change comparison behavior.
+
+Defaults for **auto** snapshots can come from `vis.setup({ createMissingBaseline: true, auto: ... })`; per-test meta can override with an explicit `createMissingBaseline` value.
+
+```ts
+it('creates page baseline on first run with createMissingBaseline', async () => {
+	render(<MyApp />)
+
+	await page.toMatchImageSnapshot({
+		snapshotKey: 'page_first_run',
+		createMissingBaseline: true
+	})
+})
+```
+
 ### Failure Threshold
 
 #### `failureThreshold` and `failureThresholdType`
@@ -256,7 +275,10 @@ it('should demonstrate all page snapshot options', async () => {
 		timeout: 45000,
 
 		// Testing utility
-		expectToFail: false
+		expectToFail: false,
+
+		// First-run baseline (optional)
+		createMissingBaseline: false
 	})
 })
 ```

package/src/client/snapshot/compare_image_snapshot.logic.ts

@@ -8,6 +8,7 @@ export function prettifyOptions(options: ToMatchImageSnapshotOptions<any> | unde
 		options.timeout ? `timeout: ${options.timeout} ms` : '',
 		`comparisonMethod: ${options.comparisonMethod ?? 'pixel'}`,
 		options.diffOptions ? `diffOptions: ${JSON.stringify(options.diffOptions)}` : '',
+		options.createMissingBaseline ? 'createMissingBaseline: true' : '',
 	]
 		.filter(Boolean)
 		.join('\n                ')

package/src/client/snapshot/compare_image_snapshot.ts

@@ -23,7 +23,7 @@ export async function compareImageSnapshot(
 	const resultImage = await toImageData(info.result)
 
 	if (!info.baseline) {
-		if (server.config.snapshotOptions.updateSnapshot === 'all') {
+		if (server.config.snapshotOptions.updateSnapshot === 'all' || options?.createMissingBaseline === true) {
 			await writeSnapshot(commands, resolve(info.projectRoot, info.baselinePath), resultImage)
 			return
 		}
@@ -45,7 +45,7 @@ export async function compareImageSnapshot(
 		diffImage.data,
 		width,
 		height,
-		options,
+		options as ToMatchImageSnapshotOptions<any>,
 	)
 	if (pass) {
 		if (options?.expectToFail) {

package/src/client/suite/auto_snapshot_matcher.ts

@@ -2,7 +2,7 @@ import dedent from 'dedent'
 import { extractAutoSnapshotOptions } from '../../auto_snapshots/_extract_auto_snapshot_options.ts'
 import type { SnapshotMeta } from '../../auto_snapshots/snapshot_meta.ts'
 import type { SetupVisSuiteCommand } from '../../shared/commands.types.ts'
-import type { ComparisonMethod } from '../../shared/types.ts'
+import type { ComparisonMethod, SetupVisOptions } from '../../shared/types.ts'
 import { shouldTakeSnapshot } from '../snapshot/should_take_snapshot.ts'
 import { toTaskId } from '../task/task_id.ts'
 import { ctx } from './_ctx.ts'
@@ -22,6 +22,7 @@ export function autoSnapshotMatcher<GM extends Record<string, any> | unknown = u
 				string,
 				boolean | ((options: SnapshotMeta<C> & M & GM) => Promise<boolean> | Promise<void> | boolean | void)
 			>,
+			suiteDefaults?: Pick<SetupVisOptions<GM>, 'createMissingBaseline'> | undefined,
 		) {
 			return async function matchImageSnapshot() {
 				const test = ctx.getCurrentTest()
@@ -35,9 +36,16 @@ export function autoSnapshotMatcher<GM extends Record<string, any> | unknown = u
 						const theme = themes[themeId]
 						const r = typeof theme === 'function' ? await theme(meta! as any) : theme
 						if (r === false) continue
+						const effectiveCreateMissingBaseline =
+							meta != null && Object.hasOwn(meta as object, 'createMissingBaseline')
+								? (meta as { createMissingBaseline?: boolean }).createMissingBaseline
+								: suiteDefaults?.createMissingBaseline
 						await expect(getSubject(meta?.subject ?? subject)).toMatchImageSnapshot({
 							...meta,
 							snapshotKey: meta?.snapshotKey ?? themeId,
+							...(effectiveCreateMissingBaseline !== undefined
+								? { createMissingBaseline: effectiveCreateMissingBaseline }
+								: {}),
 						})
 					} catch (error) {
 						errors.push([themeId, error as Error])
@@ -47,7 +55,7 @@ export function autoSnapshotMatcher<GM extends Record<string, any> | unknown = u
 					if (errors.length === 1) throw errors[0]![1]
 					const taskId = toTaskId(test!)
 					throw new AggregateError(
-						errors,
+						errors.map(([, e]) => e),
 						dedent`Snapshot \`${taskId}\` mismatched
 
 					${errors

package/src/config/types.ts

@@ -72,4 +72,18 @@ export type VisOptions<M extends ComparisonMethod = 'pixel'> = (M extends 'ssim'
 		 * @returns The customized snapshot subpath.
 		 */
 		snapshotSubpath?: ((options: { subpath: string }) => string) | undefined
+		/**
+		 * When `true`, shortenspaths that would exceed Windows-safe limits (full path length at
+		 * least 250, below classic `MAX_PATH` 260, or a final path component longer than 255):
+		 * - After `snapshotRootDir` and `snapshotSubpath`, if the path
+		 *   would exceed that budget, the **final** subpath segment is shortened to
+		 *   `{firstToken}-{hash12}{ext}` (tersify-style).
+		 * - When writing a baseline, if the **actual** absolute path for the legacy `taskId-key.png` file would
+		 *   exceed the budget, only the final segment of that relative path is shortened the same way (nested
+		 *   `describe` directories from `taskId` stay as-is so `taskId-*.png` globs still work).
+		 * `snapshotRootDir` itself is not rewritten.
+		 *
+		 * @default false
+		 */
+		shortenLongSnapshotPaths?: boolean | undefined
 	}

package/src/exports/client-api.ts

@@ -0,0 +1,13 @@
+import '../server/commands/augment.ts'
+
+export * from '../auto_snapshots/auto_snapshot_options.ts'
+export * from '../client/actions/has_image_snapshot_action.ts'
+export * from '../client/actions/load_image_snapshot_results_action.ts'
+export * from '../client/actions/match_image_snapshot_action.ts'
+export * from '../client/actions/match_page_image_snapshot_action.ts'
+export * from '../client/expect/expectation_result.ts'
+export type * from '../client/expect/to_match_image_snapshot.types.ts'
+export * from '../client/suite/auto_snapshot_matcher.ts'
+export * from '../client/task/task_id.ts'
+export * from '../shared/constants.ts'
+export type * from '../shared/types.ts'

package/src/exports/config.ts

@@ -0,0 +1,3 @@
+export type * from '../config/types.ts'
+export * from '../config/vis.ts'
+export * from '../shared/trim_common_folder.ts'

package/src/exports/server-utils.ts

@@ -0,0 +1,7 @@
+export { getSnapshotRootDir } from '../server/snapshot_path.ts'
+export {
+	resolveLegacySnapshotFileRelativePath,
+	resolveSnapshotSubpathWithinLimits,
+} from '../server/snapshot_path_limits.ts'
+export { BASELINE_DIR, DIFF_DIR, SNAPSHOT_ROOT_DIR } from '../shared/constants.ts'
+export { trimCommonFolder } from '../shared/trim_common_folder.ts'

package/src/exports/setup-api.ts

@@ -0,0 +1,5 @@
+// `vitest-plugin-vis/setup` provides code needed in `vitest.setup.ts`.
+import '../client/expect/extend.ts'
+import '../client/page/extend.ts'
+
+export * from '../setup/create_vis.ts'

package/src/exports/setup.ts

@@ -0,0 +1,3 @@
+import './setup-api.ts'
+
+export * from '../setup/vis.ts'

package/src/exports/testing/node.ts

@@ -0,0 +1,4 @@
+/** Node / Vitest project tests only — not safe for browser Vitest. */
+export { stubSuite } from '../../server/testing/stubSuite.ts'
+export { getVisOption } from '../../server/vis_options.ts'
+export * from '../../testing/constants.ts'

package/src/exports/testing.ts

@@ -0,0 +1 @@
+export * from '../testing/constants.ts'

package/src/server/commands/prepare_image_snapshot_comparison.ts

@@ -28,7 +28,7 @@ export const prepareImageSnapshotComparison: ExtendedBrowserCommand<
 			...info,
 			projectRoot,
 			result: subject,
-		}
+		} as ImageSnapshotComparisonInfo
 	}
 
 	const resultBuffer = await takeSnapshot(context, projectRoot, info.resultPath, subject, options)
@@ -37,5 +37,5 @@ export const prepareImageSnapshotComparison: ExtendedBrowserCommand<
 		projectRoot,
 		baseline: baselineBuffer?.toString('base64'),
 		result: resultBuffer.toString('base64'),
-	}
+	} as ImageSnapshotComparisonInfo
 }

package/src/server/commands/prepare_page_image_snapshot_comparison.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'pathe'
 import type { PreparePageImageSnapshotComparisonCommand } from '../../shared/commands.types.ts'
+import type { ImageSnapshotComparisonInfo } from '../../shared/types.ts'
 import { file } from '../externals/file.ts'
 import { getProjectRoot } from '../project.ts'
 import { takePageSnapshot } from '../snapshot.ts'
@@ -24,5 +25,5 @@ export const preparePageImageSnapshotComparison: ExtendedBrowserCommand<
 		projectRoot,
 		baseline: baselineBuffer?.toString('base64'),
 		result: resultBuffer.toString('base64'),
-	}
+	} as ImageSnapshotComparisonInfo
 }

package/src/server/snapshot_path_limits.ts

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto'
+import { basename, dirname, extname, join, resolve } from 'pathe'
+
+/** Classic Win32 `MAX_PATH` includes NUL; tools often treat ~259 as usable. */
+export const WIN_MAX_PATH = 260
+
+/**
+ * Budget under {@link WIN_MAX_PATH} to leave margin for tooling and long `projectRoot` prefixes.
+ */
+export const WIN_SNAPSHOT_PATH_BUDGET = 250
+
+/** NTFS maximum length of a single path component (directory or file name). */
+export const NTFS_MAX_FILENAME = 255
+
+/** Max length of the readable prefix taken from the original basename (tersify-style). */
+const SNAPSHOT_SUBPATH_PREFIX_MAX_LEN = 24
+
+/**
+ * Minimal probe file under the snapshot folder — detects when the directory prefix alone is too long.
+ */
+const SNAPSHOT_SUBPATH_PROBE_MIN_BASENAME = '0.png'
+
+export function absoluteSnapshotFilePath(projectRoot: string, baselineDir: string, snapshotFilename: string): string {
+	return resolve(projectRoot, join(baselineDir, snapshotFilename))
+}
+
+/**
+ * @returns true when the legacy absolute path should be shortened for Windows-safe tooling.
+ */
+export function legacySnapshotPathExceedsLimit(absolutePath: string): boolean {
+	if (absolutePath.length >= WIN_SNAPSHOT_PATH_BUDGET) return true
+	if (basename(absolutePath).length > NTFS_MAX_FILENAME) return true
+	return false
+}
+
+/**
+ * First readable token of a snapshot basename stem (before the first `.`), similar in spirit to
+ * [tersify](https://github.com/unional/tersify) terse labels — keeps a short human hint, not the whole name.
+ */
+function snapshotBasenameTersifyPrefix(stem: string): string {
+	if (!stem) return 'snap'
+	const dot = stem.indexOf('.')
+	const first = dot === -1 ? stem : stem.slice(0, dot)
+	const cleaned = first.replace(/[^\w-]/g, '')
+	return (cleaned || 'snap').slice(0, SNAPSHOT_SUBPATH_PREFIX_MAX_LEN)
+}
+
+/**
+ * Keeps all directory segments of {@link rawSnapshotSubpath}; only the final filename is replaced with
+ * `{prefix}-{hash12}{ext}` where `prefix` comes from the first segment of the original stem (e.g. `Button.stories.ts` → `Button`).
+ */
+export function formatCondensedSnapshotSubpath(rawSnapshotSubpath: string): string {
+	const norm = rawSnapshotSubpath.replace(/\\/g, '/')
+	const dir = dirname(norm)
+	const file = basename(norm)
+	const ext = extname(file)
+	const stem = ext ? file.slice(0, -ext.length) : file
+	const prefix = snapshotBasenameTersifyPrefix(stem)
+	const h = createHash('sha256').update(norm).digest('hex').slice(0, 12)
+	const shortFile = `${prefix}-${h}${ext}`
+	if (dir === '.' || dir === '') return shortFile
+	return join(dir, shortFile)
+}
+
+/**
+ * `snapshotBaselineRootAbs` is the absolute `__baselines__` root; with `rawSnapshotSubpath` this yields the
+ * test-module snapshot directory. Only checks whether that layout can host a tiny baseline file; long
+ * `taskId-key.png` paths are handled with {@link resolveLegacySnapshotFileRelativePath} using real names.
+ */
+function rawSnapshotSubpathExceedsSafePathBudget(snapshotBaselineRootAbs: string, rawSnapshotSubpath: string): boolean {
+	const dirAbs = resolve(snapshotBaselineRootAbs, rawSnapshotSubpath)
+
+	if (legacySnapshotPathExceedsLimit(resolve(dirAbs, SNAPSHOT_SUBPATH_PROBE_MIN_BASENAME))) return true
+
+	for (const segment of rawSnapshotSubpath.split(/[/\\]/)) {
+		if (segment.length > NTFS_MAX_FILENAME) return true
+	}
+
+	return false
+}
+
+/**
+ * Returns {@link rawSnapshotSubpath} or a tersified final segment when `shortenLongSnapshotPaths` is on and
+ * `snapshotBaselineRootAbs` + subpath + a minimal `0.png` would exceed {@link legacySnapshotPathExceedsLimit},
+ * or a subpath segment exceeds NTFS length. Long snapshot **filenames** (`taskId-key.png`) are shortened
+ * separately via {@link resolveLegacySnapshotFileRelativePath}. Baseline, result, and diff trees share the
+ * same resolved subpath via {@link getTaskSubpath}.
+ */
+export function resolveSnapshotSubpathWithinLimits(params: {
+	snapshotBaselineRootAbs: string
+	rawSnapshotSubpath: string
+	shortenLongSnapshotPaths: boolean
+}): string {
+	const { snapshotBaselineRootAbs, rawSnapshotSubpath, shortenLongSnapshotPaths } = params
+	if (!shortenLongSnapshotPaths) return rawSnapshotSubpath
+
+	if (!rawSnapshotSubpathExceedsSafePathBudget(snapshotBaselineRootAbs, rawSnapshotSubpath)) {
+		return rawSnapshotSubpath
+	}
+
+	return formatCondensedSnapshotSubpath(rawSnapshotSubpath)
+}
+
+/**
+ * When `shortenLongSnapshotPaths` is on and the legacy `{@link getLegacySnapshotFilename}` path exceeds
+ * {@link legacySnapshotPathExceedsLimit}, rewrites only the final path segment (after the last `/`) like
+ * {@link formatCondensedSnapshotSubpath}, so nested `taskId` directories stay intact and `…-*.png` globs keep working.
+ */
+export function resolveLegacySnapshotFileRelativePath(params: {
+	projectRoot: string
+	baselineDir: string
+	legacySnapshotFilename: string
+	shortenLongSnapshotPaths: boolean
+}): string {
+	const { projectRoot, baselineDir, legacySnapshotFilename, shortenLongSnapshotPaths } = params
+	if (!shortenLongSnapshotPaths) return legacySnapshotFilename
+
+	const norm = legacySnapshotFilename.replace(/\\/g, '/')
+	const abs = absoluteSnapshotFilePath(projectRoot, baselineDir, norm)
+	if (!legacySnapshotPathExceedsLimit(abs)) return legacySnapshotFilename
+
+	return formatCondensedSnapshotSubpath(norm)
+}
+
+export function getLegacySnapshotFilename(params: {
+	taskId: string
+	explicitSnapshotKey: string | undefined
+	defaultSnapshotKey: string | undefined
+	taskCount: number
+}): string {
+	const key =
+		params.explicitSnapshotKey ??
+		(typeof params.defaultSnapshotKey === 'string' ? params.defaultSnapshotKey : String(params.taskCount))
+	return `${params.taskId}-${key}.png`
+}

package/src/server/suite.ts

@@ -1,8 +1,9 @@
-import { join, relative } from 'pathe'
+import { join, relative, resolve } from 'pathe'
 import type { VisOptions } from '../config/types.ts'
 import { BASELINE_DIR, DIFF_DIR, RESULT_DIR } from '../shared/constants.ts'
 import { getProjectName, getProjectRoot } from './project.ts'
 import { getSnapshotSubpath, resolveSnapshotRootDir } from './snapshot_path.ts'
+import { resolveSnapshotSubpathWithinLimits } from './snapshot_path_limits.ts'
 import { getVisOption } from './vis_options.ts'
 import { deps } from './vis_server_context.deps.ts'
 import type { ExtendedBrowserCommandContext, VisSuite, VisSuites } from './vis_server_context.types.ts'
@@ -75,7 +76,11 @@ async function createSuite(
 	return state
 }
 
-export function createModule(state: VisSuite, testPath: string, options: Pick<VisOptions, 'snapshotSubpath'>) {
+export function createModule(
+	state: VisSuite,
+	testPath: string,
+	options: Pick<VisOptions, 'snapshotSubpath' | 'shortenLongSnapshotPaths'>,
+) {
 	const taskSubpath = getTaskSubpath(state, testPath, options)
 	return {
 		taskSubpath,
@@ -86,8 +91,18 @@ export function createModule(state: VisSuite, testPath: string, options: Pick<Vi
 	}
 }
 
-export function getTaskSubpath(state: VisSuite, testPath: string, options: Pick<VisOptions, 'snapshotSubpath'>) {
-	return getSnapshotSubpath(relative(state.projectRoot, testPath), options)
+export function getTaskSubpath(
+	state: VisSuite,
+	testPath: string,
+	options: Pick<VisOptions, 'snapshotSubpath' | 'shortenLongSnapshotPaths'>,
+) {
+	const raw = getSnapshotSubpath(relative(state.projectRoot, testPath), options)
+	const snapshotBaselineRootAbs = resolve(state.projectRoot, state.snapshotBaselineDir)
+	return resolveSnapshotSubpathWithinLimits({
+		snapshotBaselineRootAbs,
+		rawSnapshotSubpath: raw,
+		shortenLongSnapshotPaths: options.shortenLongSnapshotPaths === true,
+	})
 }
 
 export function getSuite(context: ExtendedBrowserCommandContext) {

package/src/server/vis_options.ts

@@ -8,6 +8,13 @@ const DEFAULT_PROJECT_NAME = '__default'
 
 const visOptions: Record<string, VisOptions<any> | undefined> = {}
 
+/** Clears stored options (for tests that share this module). */
+export function clearVisOptionsRegistryForTesting() {
+	for (const key of Object.keys(visOptions)) {
+		delete visOptions[key]
+	}
+}
+
 export function setVisOption(
 	userConfig: { test?: { name?: TestUserConfig['name'] | undefined } },
 	options: VisOptions<any> | undefined,
@@ -22,5 +29,7 @@ export function setVisOption(
 
 export function getVisOption(context: ExtendedBrowserCommandContext) {
 	const id = getProjectName(context) || DEFAULT_PROJECT_NAME
-	return visOptions[id] ?? {}
+	const base = visOptions[DEFAULT_PROJECT_NAME] ?? {}
+	const override = visOptions[id] ?? {}
+	return { ...base, ...override }
 }

package/src/server/vis_server_context.logic.ts

@@ -1,8 +1,13 @@
 import { basename, join, resolve } from 'pathe'
 import { pick } from 'type-plus'
-import type { ImageSnapshotKeyOptions } from '../client-api.ts'
+import type { ImageSnapshotKeyOptions } from '../exports/client-api.ts'
 import type { ImageSnapshotResult } from '../shared/commands.types.ts'
 import { file } from './externals/file.ts'
+import {
+	absoluteSnapshotFilePath,
+	getLegacySnapshotFilename,
+	resolveLegacySnapshotFileRelativePath,
+} from './snapshot_path_limits.ts'
 import { getSuite, getTaskSubpath } from './suite.ts'
 import { getVisOption } from './vis_options.ts'
 import type { ExtendedBrowserCommandContext } from './vis_server_context.types.ts'
@@ -11,16 +16,23 @@ export function createVisServerContext() {
 	const context = {
 		async getSnapshotResults(browserContext: ExtendedBrowserCommandContext, taskId: string) {
 			const suiteInfo = await context.getSuiteInfo(browserContext, taskId)
-			const baselines = await file.glob(join(suiteInfo.projectRoot, suiteInfo.baselineDir, `${suiteInfo.taskId}-*.png`))
-			const results = await file.glob(join(suiteInfo.projectRoot, suiteInfo.resultDir, `${suiteInfo.taskId}-*.png`))
-			const diffs = await file.glob(join(suiteInfo.projectRoot, suiteInfo.diffDir, `${suiteInfo.taskId}-*.png`))
+			const base = resolve(suiteInfo.projectRoot, suiteInfo.baselineDir)
+
+			const legacyPattern = join(base, `${suiteInfo.taskId}-*.png`)
+			const baselines = await file.glob(legacyPattern)
+
+			const resultPattern = join(resolve(suiteInfo.projectRoot, suiteInfo.resultDir), `${suiteInfo.taskId}-*.png`)
+			const results = await file.glob(resultPattern)
+
+			const diffPattern = join(resolve(suiteInfo.projectRoot, suiteInfo.diffDir), `${suiteInfo.taskId}-*.png`)
+			const diffs = await file.glob(diffPattern)
 
 			const r: ImageSnapshotResult[] = []
 			await Promise.all(
 				baselines.map(async (baselinePath) => {
 					const filename = basename(baselinePath)
-					const resultPath = results.find((r) => r.endsWith(filename))
-					const diffPath = diffs.find((d) => d.endsWith(filename))
+					const resultPath = results.find((p) => p.endsWith(filename))
+					const diffPath = diffs.find((p) => p.endsWith(filename))
 
 					const baselineBuffer = await file.tryReadFile(baselinePath)
 					const resultBuffer = await file.tryReadFile(resultPath)
@@ -45,7 +57,7 @@ export function createVisServerContext() {
 
 			const { baselineDir, resultDir, diffDir, task } = suiteInfo
 
-			task.count = task.count + 1
+			task.count += 1
 			const baselinePath = join(baselineDir, snapshotFilename)
 			const resultPath = join(resultDir, snapshotFilename)
 			const diffPath = join(diffDir, snapshotFilename)
@@ -74,22 +86,40 @@ export function createVisServerContext() {
 			snapshotKey: string | undefined,
 		) {
 			const info = await context.getSuiteInfo(browserContext, taskId)
-
-			return file.existFile(
-				resolve(info.projectRoot, info.baselineDir, context.getSnapshotFilename(browserContext, info, snapshotKey)),
-			)
+			const visOptions = getVisOption(browserContext)
+			const legacyFilename = getLegacySnapshotFilename({
+				taskId: info.taskId,
+				explicitSnapshotKey: snapshotKey,
+				defaultSnapshotKey: typeof visOptions.snapshotKey === 'string' ? visOptions.snapshotKey : undefined,
+				taskCount: info.task.count,
+			})
+			const filename = resolveLegacySnapshotFileRelativePath({
+				projectRoot: info.projectRoot,
+				baselineDir: info.baselineDir,
+				legacySnapshotFilename: legacyFilename,
+				shortenLongSnapshotPaths: visOptions.shortenLongSnapshotPaths === true,
+			})
+			const legacyAbs = absoluteSnapshotFilePath(info.projectRoot, info.baselineDir, filename)
+			return file.existFile(legacyAbs)
 		},
 		getSnapshotFilename(
 			browserContext: ExtendedBrowserCommandContext,
-			info: { taskId: string; task: { count: number } },
+			info: { taskId: string; task: { count: number }; suiteId: string; baselineDir: string; projectRoot: string },
 			snapshotKey: string | undefined,
 		) {
-			if (snapshotKey) return `${info.taskId}-${snapshotKey}.png`
 			const visOptions = getVisOption(browserContext)
-			if (typeof visOptions.snapshotKey === 'string') {
-				return `${info.taskId}-${visOptions.snapshotKey}.png`
-			}
-			return `${info.taskId}-${info.task.count}.png`
+			const legacyFilename = getLegacySnapshotFilename({
+				taskId: info.taskId,
+				explicitSnapshotKey: snapshotKey,
+				defaultSnapshotKey: typeof visOptions.snapshotKey === 'string' ? visOptions.snapshotKey : undefined,
+				taskCount: info.task.count,
+			})
+			return resolveLegacySnapshotFileRelativePath({
+				projectRoot: info.projectRoot,
+				baselineDir: info.baselineDir,
+				legacySnapshotFilename: legacyFilename,
+				shortenLongSnapshotPaths: visOptions.shortenLongSnapshotPaths === true,
+			})
 		},
 		async getSuiteInfo(browserContext: ExtendedBrowserCommandContext, taskId: string) {
 			const projectState = await getSuite(browserContext)

package/src/setup/create_vis.ts

@@ -44,21 +44,22 @@ export function createVis<GM extends Record<string, any> | unknown = unknown>(co
 
 	const vis: VisClientConfigurator<GM> = {
 		setup(options) {
-			if (!options || options.auto === false) {
-				beforeAll(matcher.setup)
-			} else {
-				beforeAll(async () => {
-					await matcher.setup()
-					setAutoSnapshotOptions(true)
-				})
-			}
+			const suiteDefaults =
+				options?.createMissingBaseline !== undefined
+					? { createMissingBaseline: options.createMissingBaseline }
+					: undefined
+
+			beforeAll(async () => {
+				await matcher.setup()
+				setAutoSnapshotOptions(!!options?.auto)
+			})
 
 			if (typeof options?.auto === 'function') {
-				afterEach(matcher.createMatcher({ auto: options.auto }))
+				afterEach(matcher.createMatcher({ auto: options.auto }, suiteDefaults))
 			} else if (typeof options?.auto === 'object') {
-				afterEach(matcher.createMatcher(options.auto))
+				afterEach(matcher.createMatcher(options.auto, suiteDefaults))
 			} else {
-				afterEach(matcher.createMatcher({ async auto() {} }))
+				afterEach(matcher.createMatcher({ async auto() {} }, suiteDefaults))
 			}
 		},
 	}

package/src/shared/types.ts

@@ -94,6 +94,15 @@ export type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> =
 		 * If it passes, it will throw an error with details.
 		 */
 		expectToFail?: boolean | undefined
+		/**
+		 * Create a baseline image when none exists on disk.
+		 *
+		 * If `true`, the captured image is written to the baseline path and the assertion succeeds,
+		 * without Vitest `-u` / `updateSnapshot: 'all'`.
+		 *
+		 * @default false
+		 */
+		createMissingBaseline?: boolean | undefined
 	}
 
 export interface PageImageSnapshotOptions {
@@ -145,7 +154,12 @@ export type ImageSnapshotComparisonInfo = {
 
 export type MatchImageSnapshotOptions = ImageSnapshotTimeoutOptions &
 	ImageSnapshotCompareOptions<any> &
-	ImageSnapshotKeyOptions
+	ImageSnapshotKeyOptions & {
+		/**
+		 * When `true`, write a missing baseline on first run (see {@link ToMatchImageSnapshotOptions} `createMissingBaseline`).
+		 */
+		createMissingBaseline?: boolean | undefined
+	}
 
 export type SetupVisOptions<GM extends Record<string, any> | unknown = unknown> = {
 	auto?:
@@ -160,4 +174,10 @@ export type SetupVisOptions<GM extends Record<string, any> | unknown = unknown>
 						options: SnapshotMeta<C> & M & GM,
 				  ) => Promise<boolean> | Promise<void> | boolean | void)
 		  >
+	/**
+	 * Default {@link ToMatchImageSnapshotOptions#createMissingBaseline} for auto snapshots.
+	 *
+	 * @default false
+	 */
+	createMissingBaseline?: boolean | undefined
 }

package/dist/client-api.mjs

@@ -1,11 +0,0 @@
-import { BASELINE_DIR, DIFF_DIR, NAME, RESULT_DIR, SNAPSHOT_ROOT_DIR } from "./shared/constants.mjs";
-import { setAutoSnapshotOptions } from "./auto_snapshots/auto_snapshot_options.mjs";
-import { hasImageSnapshotAction } from "./client/actions/has_image_snapshot_action.mjs";
-import { loadImageSnapshotResultsAction } from "./client/actions/load_image_snapshot_results_action.mjs";
-import { matchImageSnapshotAction } from "./client/actions/match_image_snapshot_action.mjs";
-import { matchPageImageSnapshotAction } from "./client/actions/match_page_image_snapshot_action.mjs";
-import { success } from "./client/expect/expectation_result.mjs";
-import { toTaskId } from "./client/task/task_id.mjs";
-import { autoSnapshotMatcher } from "./client/suite/auto_snapshot_matcher.mjs";
-
-export { BASELINE_DIR, DIFF_DIR, NAME, RESULT_DIR, SNAPSHOT_ROOT_DIR, autoSnapshotMatcher, hasImageSnapshotAction, loadImageSnapshotResultsAction, matchImageSnapshotAction, matchPageImageSnapshotAction, setAutoSnapshotOptions, success, toTaskId };

package/dist/config.d.mts

@@ -1,5 +0,0 @@
-import { ComparisonMethod, PixelComparisonOptions, PixelDiffOptions, SsimComparisonOptions, SsimDiffOptions } from "./shared/types.mjs";
-import { VisOptions } from "./config/types.mjs";
-import { vis } from "./config/vis.mjs";
-import { trimCommonFolder } from "./shared/trim_common_folder.mjs";
-export { ComparisonMethod, PixelComparisonOptions, PixelDiffOptions, SsimComparisonOptions, SsimDiffOptions, VisOptions, trimCommonFolder, vis };

package/dist/config.mjs

@@ -1,4 +0,0 @@
-import { trimCommonFolder } from "./shared/trim_common_folder.mjs";
-import { vis } from "./config/vis.mjs";
-
-export { trimCommonFolder, vis };

package/dist/presets/auto.mjs

@@ -1,9 +0,0 @@
-import { vis } from "../setup/vis.mjs";
-import "../setup.mjs";
-
-//#region src/presets/auto.ts
-vis.setup({ auto: true });
-
-//#endregion
-export {  };
-//# sourceMappingURL=auto.mjs.map

package/dist/presets/auto.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"auto.mjs","names":[],"sources":["../../src/presets/auto.ts"],"sourcesContent":["import { vis } from '../setup.ts'\n\nvis.setup({ auto: true })\n"],"mappings":";;;;AAEA,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC"}

package/dist/presets/manual.mjs

@@ -1,9 +0,0 @@
-import { vis } from "../setup/vis.mjs";
-import "../setup.mjs";
-
-//#region src/presets/manual.ts
-vis.setup({ auto: false });
-
-//#endregion
-export {  };
-//# sourceMappingURL=manual.mjs.map

package/dist/presets/manual.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"manual.mjs","names":[],"sources":["../../src/presets/manual.ts"],"sourcesContent":["import { vis } from '../setup.ts'\n\nvis.setup({ auto: false })\n"],"mappings":";;;;AAEA,IAAI,MAAM,EAAE,MAAM,OAAO,CAAC"}

package/dist/server-utils.d.mts

@@ -1,4 +0,0 @@
-import { BASELINE_DIR, DIFF_DIR, NAME, RESULT_DIR, SNAPSHOT_ROOT_DIR } from "./shared/constants.mjs";
-import { trimCommonFolder } from "./shared/trim_common_folder.mjs";
-import { getSnapshotRootDir } from "./server/snapshot_path.mjs";
-export { BASELINE_DIR, DIFF_DIR, NAME, RESULT_DIR, SNAPSHOT_ROOT_DIR, getSnapshotRootDir, trimCommonFolder };