vitest-plugin-vis 1.1.0 → 1.3.0

package/esm/server/vis_context.logic.js

@@ -99,9 +99,6 @@ async function setupState(suite, visOptions) {
     await Promise.allSettled([ctx.rimraf(join(state.snapshotDiffDir)), ctx.rimraf(join(state.snapshotResultDir))]);
     return state;
 }
-export function getSuiteId(state, testPath, options) {
-    return getSnapshotSubpath(relative(state.projectPath, testPath), options);
-}
 export function createSuite(state, testPath, options) {
     const suiteId = getSuiteId(state, testPath, options);
     return {
@@ -114,3 +111,6 @@ export function createSuite(state, testPath, options) {
         },
     };
 }
+export function getSuiteId(state, testPath, options) {
+    return getSnapshotSubpath(relative(state.projectPath, testPath), options);
+}

package/esm/shared/compare_image.d.ts

@@ -0,0 +1,6 @@
+import type { ImageSnapshotCompareOptions } from './types.ts';
+export declare function compareImage(img1: Uint8ClampedArray | Buffer, img2: Uint8ClampedArray | Buffer, output: Uint8ClampedArray | Buffer, width: number, height: number, { failureThreshold, failureThresholdType, diffOptions }?: ImageSnapshotCompareOptions): {
+    pass: boolean;
+    diffAmount: number;
+};
+//# sourceMappingURL=compare_image.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compare_image.d.ts","sourceRoot":"","sources":["../../src/shared/compare_image.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAA;AAE7D,wBAAgB,YAAY,CAC3B,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAChC,IAAI,EAAE,iBAAiB,GAAG,MAAM,EAChC,MAAM,EAAE,iBAAiB,GAAG,MAAM,EAClC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,EAAE,gBAAoB,EAAE,oBAA8B,EAAE,WAAW,EAAE,GAAE,2BAAgC;;;EASvG"}

package/esm/shared/compare_image.js

@@ -0,0 +1,10 @@
+import pixelmatch from 'pixelmatch';
+import { convertThresholdUnit } from "./convert_threshold_unit.js";
+export function compareImage(img1, img2, output, width, height, { failureThreshold = 0, failureThresholdType = 'pixel', diffOptions } = {}) {
+    const pixelDiff = pixelmatch(img1, img2, output, width, height, diffOptions);
+    const diffAmount = convertThresholdUnit({ failureThresholdType, width, height }, pixelDiff);
+    return {
+        pass: diffAmount <= failureThreshold,
+        diffAmount,
+    };
+}

package/esm/testing/stubBrowserCommandContext.d.ts

@@ -0,0 +1,3 @@
+import type { BrowserCommandContext } from 'vitest/node';
+export declare const stubBrowserCommandContext: (stub?: import("type-plus").RecursivePartial<BrowserCommandContext> | undefined) => BrowserCommandContext;
+//# sourceMappingURL=stubBrowserCommandContext.d.ts.map

package/esm/testing/stubBrowserCommandContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stubBrowserCommandContext.d.ts","sourceRoot":"","sources":["../../src/testing/stubBrowserCommandContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD,eAAO,MAAM,yBAAyB,2GAAwC,CAAA"}

package/esm/testing/stubBrowserCommandContext.js

@@ -0,0 +1,2 @@
+import { stub } from 'type-plus';
+export const stubBrowserCommandContext = stub.build({});

package/esm/testing.d.ts

@@ -1,2 +1,3 @@
 export * from './testing/constants.ts';
+export * from './testing/stubBrowserCommandContext.ts';
 //# sourceMappingURL=testing.d.ts.map

package/esm/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAA"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAA;AACtC,cAAc,wCAAwC,CAAA"}

package/esm/testing.js

@@ -1 +1,2 @@
 export * from "./testing/constants.js";
+export * from "./testing/stubBrowserCommandContext.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-plugin-vis",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Vitest visual testing plugin",
   "keywords": [
     "image-snapshot",
@@ -80,6 +80,7 @@
     "@vitest/coverage-v8": "^2.1.8",
     "@vitest/expect": "^2.1.8",
     "cross-env": "^7.0.3",
+    "never-fail": "^1.1.4",
     "npm-run-all2": "^7.0.2",
     "playwright": "^1.49.0",
     "react": "^19.0.0",

package/readme.md

@@ -103,7 +103,7 @@ vis.presets.auto()
 vis.presets.manual()
 
 
-// or capture image snapshot for all stories with `snapshot` tag,
+// or capture image snapshot for all rendering tests
 // for multiple themes (light and dark in this example)
 vis.presets.theme({
 	light() { document.body.classList.remove('dark') },
@@ -111,11 +111,30 @@ vis.presets.theme({
 })
 ```
 
+### TypeScript Configuration
+
+The main usage of this addon is to use the `toMatchImageSnapshot` matcher.
+
+Since it is exposed under the `expect` object of `vitest`,
+you typically do not need to import `storybook-addon-vis` directly.
+
+Because of this, TypeScript may not recognize the matcher.
+To address this, you can add the following to your `tsconfig.json`:
+
+```json
+{
+	"compilerOptions": {
+		"types": ["vitest-plugin-vis"]
+	}
+}
+```
+
 ## Usage
 
 ### Auto Snapshot
 
-By default, the plugin will use the `auto` preset, which will take a snapshot at the end of each test.
+By default, the plugin will use the `auto` preset,
+which will take a snapshot at the end of each test.
 
 You can control how the auto snapshot is taken using the `setAutoSnapshotOptions` function:
 
@@ -153,6 +172,23 @@ describe('nested scope', () => {
 })
 ```
 
+The options are similar to `expect(...).toMatchImageSnapshot(options)`:
+
+```ts
+// enable/disable auto snapshot
+setAutoSnapshotOptions(true /* or false */)
+
+// detailed options
+setAutoSnapshotOptions({
+	enable: true,
+	customizeSnapshotId: (id, index) => `${id}-custom-${index}`,
+	diffOptions: { threshold: 0.01 } // pixelmatch options,
+	failureThreshold: 0.01,
+	failureThresholdType: 'percent',
+	timeout: 15000
+})
+```
+
 ### Manual Snapshot
 
 You can also set the preset to `manual` and compare snapshots manually:

package/src/client/expect/augment.ts

@@ -0,0 +1,8 @@
+import type { ImageSnapshotMatcher } from './to_match_image_snapshot.types.ts'
+
+declare global {
+	namespace jest {
+		// biome-ignore lint/correctness/noUnusedVariables: augmentation must have matching type params.
+		interface Matchers<R, T> extends ImageSnapshotMatcher {}
+	}
+}

package/src/client/expect/extend.ts

@@ -1,12 +1,5 @@
 import { expect } from 'vitest'
 import { toMatchImageSnapshot } from './to_match_image_snapshot.ts'
-import type { ImageSnapshotMatcher } from './to_match_image_snapshot.types.ts'
-
-declare global {
-	namespace jest {
-		// biome-ignore lint/correctness/noUnusedVariables: augmentation must have matching type params.
-		interface Matchers<R, T> extends ImageSnapshotMatcher {}
-	}
-}
+import './augment.ts'
 
 expect.extend({ toMatchImageSnapshot })

package/src/client/expect/to_match_image_snapshot.ts

@@ -1,6 +1,7 @@
+import { commands } from '@vitest/browser/context'
 import type { AsyncExpectationResult } from '@vitest/expect'
 import { ctx } from '../ctx.ts'
-import { matchImageSnapshot } from '../match_image_snapshot.ts'
+import { imageSnapshotMatcher } from '../match_image_snapshot.ts'
 import { success } from './expectation_result.ts'
 import type { ToMatchImageSnapshotOptions } from './to_match_image_snapshot.types.ts'
 
@@ -24,5 +25,5 @@ export function toMatchImageSnapshot(
 		)
 	}
 
-	return matchImageSnapshot(test, subject, options).then(() => success)
+	return imageSnapshotMatcher(commands)(test, subject, options).then(() => success)
 }

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

@@ -11,4 +11,10 @@ export interface ImageSnapshotMatcher {
 export interface ToMatchImageSnapshotOptions
 	extends ImageSnapshotTimeoutOptions,
 		ImageSnapshotIdOptions,
-		ImageSnapshotCompareOptions {}
+		ImageSnapshotCompareOptions {
+	/**
+	 * Expect the matcher to fail.
+	 * If it passes, it will throw an error with details.
+	 */
+	expectToFail?: boolean | undefined
+}

package/src/client/match_image_snapshot.logic.ts

@@ -4,7 +4,7 @@ export function prettifyOptions(options: ToMatchImageSnapshotOptions | undefined
 	if (!options) return 'none'
 
 	return [
-		`failureThreshold: ${options.failureThreshold ?? 0} ${options.failureThresholdType ?? 'pixel'}`,
+		`failureThreshold: ${options.failureThreshold ?? 0} ${options.failureThresholdType ?? 'pixels'}`,
 		options.diffOptions ? `diffOptions: ${JSON.stringify(options.diffOptions)}` : '',
 		options.timeout ? `timeout: ${options.timeout} ms` : '',
 	]

package/src/client/match_image_snapshot.ts

@@ -1,10 +1,12 @@
-import { commands } from '@vitest/browser/context'
 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 { alignImagesToSameSize } from './align_images.ts'
-import { compareImage } from './compare_image.ts'
 import type { ToMatchImageSnapshotOptions } from './expect/to_match_image_snapshot.types.ts'
 import { toDataURL, toImageData } from './image_data.ts'
 import { prettifyOptions } from './match_image_snapshot.logic.ts'
@@ -12,45 +14,71 @@ import { convertElementToCssSelector } from './selector.ts'
 import { toTaskId } from './task_id.ts'
 import { server } from './vitest_browser_context_proxy.ts'
 
-export async function matchImageSnapshot(test: Task, subject: any, options?: ToMatchImageSnapshotOptions) {
-	const taskId = toTaskId(test)
-	const info = await commands.prepareImageSnapshotComparison(
-		taskId,
-		parseImageSnapshotSubject(subject),
-		options?.customizeSnapshotId ? await parseImageSnapshotOptions(taskId, options) : options,
-	)
+export function imageSnapshotMatcher(
+	commands: PrepareImageSnapshotComparisonCommand & WriteImageSnapshotCommand & ImageSnapshotNextIndexCommand,
+) {
+	return async function matchImageSnapshot(test: Task, subject: any, options?: ToMatchImageSnapshotOptions) {
+		const taskId = toTaskId(test)
+		const info = await commands.prepareImageSnapshotComparison(
+			taskId,
+			parseImageSnapshotSubject(subject),
+			options?.customizeSnapshotId ? await parseImageSnapshotOptions(commands, taskId, options) : options,
+		)
 
-	if (!info) return
+		if (!info) return
 
-	const baselineImage = await toImageData(info.baseline)
-	const resultImage = await toImageData(info.result)
-	const [baselineAlignedImage, resultAlignedImage] = alignImagesToSameSize(baselineImage, resultImage)
-	const { pass, diffAmount, diffImage } = compareImage(baselineAlignedImage, resultAlignedImage, options)
-	if (pass) return
-	if (server.config.snapshotOptions.updateSnapshot === 'all') {
-		await writeSnapshot(info.baselinePath, resultImage)
-		return
-	}
+		const baselineImage = await toImageData(info.baseline)
+		const resultImage = await toImageData(info.result)
+		const [baselineAlignedImage, resultAlignedImage] = alignImagesToSameSize(baselineImage, resultImage)
+		const { width, height } = baselineAlignedImage
+		const diffImage = new ImageData(width, height)
+		const { pass, diffAmount } = compareImage(
+			baselineAlignedImage.data,
+			resultAlignedImage.data,
+			diffImage.data,
+			width,
+			height,
+			options,
+		)
+		if (pass) {
+			if (options?.expectToFail) {
+				throw new Error(
+					dedent`Snapshot \`${taskId}\` matched but expected to fail.
 
-	await writeSnapshot(info.diffPath, diffImage)
+							Options:    ${prettifyOptions(options)}
+							DiffAmount: ${options.failureThresholdType === 'percent' ? `${diffAmount}%` : `${diffAmount} pixels`}
 
-	throw new Error(
-		dedent`Snapshot \`${taskId}\` mismatched
-
-			${
-				options?.failureThreshold
-					? options?.failureThresholdType === 'percent'
-						? `Expected image to match within ${options.failureThreshold}% but was differ by ${diffAmount}%.`
-						: `Expected image to match within ${options.failureThreshold} pixels but was differ by ${diffAmount} pixels.`
-					: `Expected image to match but was differ by ${options?.failureThresholdType === 'percent' ? `${diffAmount}%` : `${diffAmount} pixels`}.`
+							Expected:   ${resolve(info.projectRoot, info.baselinePath)}
+							Actual:     ${resolve(info.projectRoot, info.resultPath)}`,
+				)
 			}
+			return
+		}
+		if (server.config.snapshotOptions.updateSnapshot === 'all') {
+			await writeSnapshot(commands, info.baselinePath, resultImage)
+			return
+		}
 
-			Options:    ${prettifyOptions(options)}
+		await writeSnapshot(commands, info.diffPath, diffImage)
 
-			Expected:   ${resolve(info.projectRoot, info.baselinePath)}
-			Actual:     ${resolve(info.projectRoot, info.resultPath)}
-			Difference: ${resolve(info.projectRoot, info.diffPath)}`,
-	)
+		throw new Error(
+			dedent`Snapshot \`${taskId}\` mismatched
+
+					${
+						options?.failureThreshold
+							? options?.failureThresholdType === 'percent'
+								? `Expected image to match within ${options.failureThreshold}% but was differ by ${diffAmount}%.`
+								: `Expected image to match within ${options.failureThreshold} pixels but was differ by ${diffAmount} pixels.`
+							: `Expected image to match but was differ by ${options?.failureThresholdType === 'percent' ? `${diffAmount}%` : `${diffAmount} pixels`}.`
+					}
+
+					Options:    ${prettifyOptions(options)}
+
+					Expected:   ${resolve(info.projectRoot, info.baselinePath)}
+					Actual:     ${resolve(info.projectRoot, info.resultPath)}
+					Difference: ${resolve(info.projectRoot, info.diffPath)}`,
+		)
+	}
 }
 
 /**
@@ -65,12 +93,16 @@ export function parseImageSnapshotSubject(subject: any) {
 	)
 }
 
-async function writeSnapshot(path: string, image: ImageData) {
+async function writeSnapshot(commands: WriteImageSnapshotCommand, path: string, image: ImageData) {
 	const content = (await toDataURL(image)).split(',')[1]!
 	return commands.writeImageSnapshot(path, content)
 }
 
-async function parseImageSnapshotOptions(taskId: string, options: ToMatchImageSnapshotOptions) {
+async function parseImageSnapshotOptions(
+	commands: ImageSnapshotNextIndexCommand,
+	taskId: string,
+	options: ToMatchImageSnapshotOptions,
+) {
 	const index = await commands.imageSnapshotNextIndex(taskId)
 	const { customizeSnapshotId, ...rest } = options
 	const snapshotFileId = customizeSnapshotId!(taskId, index)

package/src/client/page/augment.ts

@@ -0,0 +1,5 @@
+import type { HasImageSnapshotAction } from './has_image_snapshot.ts'
+
+declare module '@vitest/browser/context' {
+	interface BrowserPage extends HasImageSnapshotAction {}
+}

package/src/client/page/extend.ts

@@ -1,8 +1,5 @@
 import { page } from '@vitest/browser/context'
-import { type HasImageSnapshotAction, hasImageSnapshot } from './has_image_snapshot.ts'
-
-declare module '@vitest/browser/context' {
-	interface BrowserPage extends HasImageSnapshotAction {}
-}
+import './augment.ts'
+import { hasImageSnapshot } from './has_image_snapshot.ts'
 
 page.extend({ hasImageSnapshot })

package/src/client/selector.ts

@@ -3,20 +3,7 @@
  *
  * @see https://github.com/vitest-dev/vitest/blob/main/packages/browser/src/client/utils.ts
  */
-import type { Locator } from '@vitest/browser/context'
 
-export function convertToSelector(elementOrLocator: Element | Locator): string {
-	if (!elementOrLocator) {
-		throw new Error('Expected element or locator to be defined.')
-	}
-	if (elementOrLocator instanceof Element) {
-		return convertElementToCssSelector(elementOrLocator)
-	}
-	if ('selector' in elementOrLocator) {
-		return (elementOrLocator as any).selector
-	}
-	throw new Error('Expected element or locator to be an instance of Element or Locator.')
-}
 export function convertElementToCssSelector(element: Element) {
 	if (!element || !(element instanceof Element)) {
 		throw new Error(`Expected DOM element to be an instance of Element, received ${typeof element}`)

package/src/commands.ts

@@ -2,3 +2,5 @@ export * from './server/commands/has_image_snapshot.ts'
 export * from './server/commands/image_snapshot_next_index.ts'
 export * from './server/commands/match_image_snapshot.ts'
 export * from './server/commands/setup_vis_suite.ts'
+export * from './server/commands/prepare_image_snapshot_comparison.ts'
+export * from './server/commands/write_image_snapshot.ts'

package/src/index.ts

@@ -1,2 +1,5 @@
 // `vitest-plugin-vis` provides code that can be used in test files.
+import './client/expect/augment.ts'
+import './client/page/augment.ts'
+
 export * from './client/snapshot_options.ts'

package/src/presets/auto.ts

@@ -1,4 +1,5 @@
-import 'vitest-browser-react'
 import { vis } from '../setup/vis.ts'
+import '../client/expect/extend.ts'
+import '../client/page/extend.ts'
 
 vis.presets.auto()

package/src/presets/manual.ts

@@ -1,4 +1,5 @@
-import 'vitest-browser-react'
 import { vis } from '../setup/vis.ts'
+import '../client/expect/extend.ts'
+import '../client/page/extend.ts'
 
 vis.presets.manual()

package/src/server/commands/_assertions.ts

@@ -0,0 +1,18 @@
+import { isAbsolute } from 'pathe'
+import type { RequiredPick } from 'type-plus'
+import type { BrowserCommandContext } from 'vitest/node'
+
+export function assertTestPathDefined(
+	context: BrowserCommandContext,
+	commandName: string,
+): asserts context is RequiredPick<BrowserCommandContext, 'testPath'> {
+	if (!context.testPath) {
+		throw new Error(`'commands.${commandName}' requires testPath to be defined`)
+	}
+}
+
+export function assertIsRelativePath(relativeFilePath: string, propName: string) {
+	if (isAbsolute(relativeFilePath)) {
+		throw new Error(`'${propName}' must be a relative path`)
+	}
+}

package/src/server/commands/has_image_snapshot.ts

@@ -1,5 +1,6 @@
 import type { BrowserCommand } from 'vitest/node'
 import { visContext } from '../vis_context.ts'
+import { assertTestPathDefined } from './_assertions.ts'
 
 export interface HasImageSnapshotCommand {
 	hasImageSnapshot(taskId: string, snapshotId?: string | undefined): Promise<boolean>
@@ -10,9 +11,7 @@ export const hasImageSnapshot: BrowserCommand<[taskId: string, snapshotId?: stri
 	taskId,
 	snapshotId,
 ) => {
-	if (!context.testPath) {
-		throw new Error('Cannot take snapshot without testPath')
-	}
+	assertTestPathDefined(context, 'hasImageSnapshot')
 
 	return visContext.hasImageSnapshot(context.testPath, taskId, snapshotId)
 }

package/src/server/commands/image_snapshot_next_index.ts

@@ -1,5 +1,6 @@
 import type { BrowserCommand } from 'vitest/node'
 import { visContext } from '../vis_context.ts'
+import { assertTestPathDefined } from './_assertions.ts'
 
 export interface ImageSnapshotNextIndexCommand {
 	/**
@@ -9,9 +10,7 @@ export interface ImageSnapshotNextIndexCommand {
 }
 
 export const imageSnapshotNextIndex: BrowserCommand<[taskId: string]> = async (context, taskId) => {
-	if (!context.testPath) {
-		throw new Error('Cannot take snapshot without testPath')
-	}
+	assertTestPathDefined(context, 'imageSnapshotNextIndex')
 
 	return visContext.getTaskCount(context.testPath, taskId)
 }

package/src/server/commands/match_image_snapshot.ts

@@ -4,6 +4,7 @@ import { resolve } from 'pathe'
 import { PNG } from 'pngjs'
 import type { BrowserCommand } from 'vitest/node'
 import { isBase64String } from '../../shared/base64.ts'
+import { compareImage } from '../../shared/compare_image.ts'
 import { getMaxSize } from '../../shared/get_max_size.ts'
 import { isSameSize } from '../../shared/is_same_size.ts'
 import type {
@@ -11,10 +12,10 @@ import type {
 	ImageSnapshotIdOptions,
 	ImageSnapshotTimeoutOptions,
 } from '../../shared/types.ts'
-import { compareImage } from '../compare_image.ts'
 import { file } from '../file.ts'
 import { takeSnapshot, takeSnapshotByBrowser, writeSnapshot, writeSnapshotBuffer } from '../snapshot.ts'
 import { visContext } from '../vis_context.ts'
+import { assertTestPathDefined } from './_assertions.ts'
 
 export interface MatchImageSnapshotCommand {
 	matchImageSnapshot: (
@@ -37,9 +38,7 @@ export interface MatchImageSnapshotOptions
 export const matchImageSnapshot: BrowserCommand<
 	[taskId: string, subject: string, options?: MatchImageSnapshotOptions | undefined]
 > = async (context, taskId, subject, options) => {
-	if (!context.testPath) {
-		throw new Error('Cannot match snapshot without testPath')
-	}
+	assertTestPathDefined(context, 'matchImageSnapshot')
 
 	// vitest:browser passes in `null` when not defined
 	if (!options) options = {}
@@ -60,8 +59,16 @@ export const matchImageSnapshot: BrowserCommand<
 	const baselineImage = PNG.sync.read(baselineBuffer, { skipRescale: true, checkCRC: false })
 	const resultImage = PNG.sync.read(resultBuffer, { skipRescale: true, checkCRC: false })
 	const [baselineAlignedImage, resultAlignedImage] = alignImageSizes(baselineImage, resultImage)
-
-	const { pass, diffAmount, diffImage } = compareImage(baselineAlignedImage, resultAlignedImage, options)
+	const { width, height } = baselineAlignedImage
+	const diffImage = new PNG({ width, height })
+	const { pass, diffAmount } = compareImage(
+		baselineAlignedImage.data,
+		resultAlignedImage.data,
+		diffImage.data,
+		width,
+		height,
+		options,
+	)
 	if (pass) {
 		if (sizeNotChanged(baselineImage, baselineAlignedImage) && sizeNotChanged(resultImage, resultAlignedImage)) {
 			return

package/src/server/commands/prepare_image_snapshot_comparison.ts

@@ -4,6 +4,7 @@ import { isBase64String } from '../../shared/base64.ts'
 import { file } from '../file.ts'
 import { takeSnapshot, takeSnapshotByBrowser, writeSnapshot } from '../snapshot.ts'
 import { visContext } from '../vis_context.ts'
+import { assertTestPathDefined } from './_assertions.ts'
 import type { MatchImageSnapshotOptions } from './match_image_snapshot.ts'
 
 type ImageSnapshotComparisonInfo = {
@@ -26,9 +27,7 @@ export interface PrepareImageSnapshotComparisonCommand {
 export const prepareImageSnapshotComparison: BrowserCommand<
 	[taskId: string, snapshotId: string, options?: MatchImageSnapshotOptions | undefined]
 > = async (context, taskId, subject, options) => {
-	if (!context.testPath) {
-		throw new Error('Cannot match snapshot without testPath')
-	}
+	assertTestPathDefined(context, 'prepareImageSnapshotComparison')
 
 	// vitest:browser passes in `null` when not defined
 	if (!options) options = {}

package/src/server/commands/setup_vis_suite.ts

@@ -1,5 +1,6 @@
 import type { BrowserCommand } from 'vitest/node'
 import { visContext } from '../vis_context.ts'
+import { assertTestPathDefined } from './_assertions.ts'
 
 export interface SetupVisSuiteCommand {
 	/**
@@ -13,5 +14,7 @@ export interface SetupVisSuiteCommand {
 }
 
 export const setupVisSuite: BrowserCommand<[]> = async (context) => {
+	assertTestPathDefined(context, 'setupVisSuite')
+
 	await visContext.setupSuite(context)
 }

package/src/server/commands/write_image_snapshot.ts

@@ -1,20 +1,26 @@
 import { mkdirp } from 'mkdirp'
-import { dirname } from 'pathe'
+import { dirname, isAbsolute } from 'pathe'
 import type { BrowserCommand } from 'vitest/node'
 import { file } from '../file.ts'
+import { assertIsRelativePath } from './_assertions.ts'
 
 export interface WriteImageSnapshotCommand {
-	writeImageSnapshot(taskId: string, snapshotId?: string | undefined): Promise<boolean>
+	/**
+	 * Writes the image snapshot to the file system.
+	 * @param relativeFilePath The file path to write the image snapshot to.
+	 * It is relative to the project root.
+	 * @param imageBase64 The base64 encoded image.
+	 */
+	writeImageSnapshot(relativeFilePath: string, imageBase64: string): Promise<void>
 }
 
-export const writeImageSnapshot: BrowserCommand<[filePath: string, base64: string]> = async (
-	context,
-	filePath,
-	base64,
+export const writeImageSnapshot: BrowserCommand<[relativeFilePath: string, imageBase64: string]> = async (
+	_,
+	relativeFilePath,
+	imageBase64,
 ) => {
-	if (!context.testPath) {
-		throw new Error('Cannot take snapshot without testPath')
-	}
-	await mkdirp(dirname(filePath))
-	await file.writeFile(filePath, base64, { encoding: 'base64' })
+	assertIsRelativePath(relativeFilePath, 'relativeFilePath')
+
+	await mkdirp(dirname(relativeFilePath))
+	await file.writeFile(relativeFilePath, imageBase64, { encoding: 'base64' })
 }

package/src/server/vis_context.logic.ts

@@ -17,7 +17,7 @@ export type PartialBrowserCommandContext = {
 			hookTimeout: number
 		}
 	}
-	testPath: string | undefined
+	testPath: string
 }
 
 export function createVisContext() {
@@ -51,7 +51,7 @@ export function createVisContext() {
 				await globalStateReady
 			}
 
-			const { suiteId, suite } = createSuite(state, context.testPath!, visOptions)
+			const { suiteId, suite } = createSuite(state, context.testPath, visOptions)
 			state.suites[suiteId] = suite
 			await Promise.allSettled([ctx.rimraf(suite.diffDir), ctx.rimraf(suite.resultDir)])
 		},
@@ -123,10 +123,6 @@ async function setupState(suite: PartialBrowserCommandContext, visOptions: VisOp
 	return state
 }
 
-export function getSuiteId(state: VisState, testPath: string, options: VisOptions) {
-	return getSnapshotSubpath(relative(state.projectPath, testPath), options)
-}
-
 export function createSuite(state: VisState, testPath: string, options: VisOptions) {
 	const suiteId = getSuiteId(state, testPath, options)
 	return {
@@ -139,3 +135,7 @@ export function createSuite(state: VisState, testPath: string, options: VisOptio
 		},
 	}
 }
+
+export function getSuiteId(state: VisState, testPath: string, options: VisOptions) {
+	return getSnapshotSubpath(relative(state.projectPath, testPath), options)
+}