vitest-plugin-vis 1.0.4 → 1.1.0

package/esm/server/snapshot.d.ts

@@ -0,0 +1,7 @@
+import type { BrowserCommandContext } from 'vitest/node';
+import type { ImageSnapshotTimeoutOptions } from '../client.ts';
+export declare function takeSnapshot(context: BrowserCommandContext, filePath: string, subject: string, options: ImageSnapshotTimeoutOptions | undefined): Promise<Buffer<ArrayBufferLike>>;
+export declare function takeSnapshotByBrowser(context: BrowserCommandContext, filePath: string, subject: string, options: ImageSnapshotTimeoutOptions | undefined): Promise<Buffer<ArrayBufferLike>>;
+export declare function writeSnapshot(filePath: string, subject: string): Promise<void>;
+export declare function writeSnapshotBuffer(filePath: string, subject: Buffer): Promise<void>;
+//# sourceMappingURL=snapshot.d.ts.map

package/esm/server/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/server/snapshot.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAA;AAK/D,wBAAsB,YAAY,CACjC,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,2BAA2B,GAAG,SAAS,oCAOhD;AAED,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,qBAAqB,EAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,2BAA2B,GAAG,SAAS,oCAOhD;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,iBAGpE;AACD,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,iBAG1E"}

package/esm/server/snapshot.js

@@ -0,0 +1,27 @@
+import { mkdirp } from 'mkdirp';
+import { dirname } from 'pathe';
+import { isBase64String } from "../shared/base64.js";
+import { browserApi } from "./browser_provider/browser_api.js";
+import { file } from './file.js';
+export async function takeSnapshot(context, filePath, subject, options) {
+    if (isBase64String(subject)) {
+        await writeSnapshot(filePath, subject);
+        return Buffer.from(subject, 'base64');
+    }
+    return takeSnapshotByBrowser(context, filePath, subject, options);
+}
+export async function takeSnapshotByBrowser(context, filePath, subject, options) {
+    await mkdirp(dirname(filePath));
+    const browser = browserApi(context);
+    return browser.takeScreenshot(filePath, subject ?? 'body', {
+        timeout: options?.timeout,
+    });
+}
+export async function writeSnapshot(filePath, subject) {
+    await mkdirp(dirname(filePath));
+    await file.writeFile(filePath, subject, { encoding: 'base64' });
+}
+export async function writeSnapshotBuffer(filePath, subject) {
+    await mkdirp(dirname(filePath));
+    await file.writeFile(filePath, subject);
+}

package/esm/shared/convert_threshold_unit.js

@@ -5,6 +5,6 @@ export function convertThresholdUnit({ failureThresholdType, width, height }, pi
         case 'percent':
             return (pixelDiff / (width * height)) * 100;
         default:
-            throw new Error(`Invalid failureThresholdType: ${failureThresholdType}`);
+            throw new Error(`Unsupported failureThresholdType: ${failureThresholdType}`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-plugin-vis",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Vitest visual testing plugin",
   "keywords": [
     "image-snapshot",
@@ -64,7 +64,7 @@
     "dedent": "^1.5.1",
     "is-ci": "^4.0.0",
     "mkdirp": "^3.0.1",
-    "pathe": "^1.1.2",
+    "pathe": "^2.0.0",
     "pixelmatch": "^6.0.0",
     "pngjs": "^7.0.0",
     "rimraf": "^6.0.1",

package/readme.md

@@ -53,14 +53,14 @@ You can customize the configuration:
 ```ts
 // vitest.config.ts
 import { defineConfig } from 'vitest/config'
-import { vis } from 'vitest-plugin-vis/config'
+import { vis, trimCommonFolder } from 'vitest-plugin-vis/config'
 
 export default defineConfig({
 	plugins: [
 		vis({
 			preset: 'auto',
 			snapshotRootDir: '__vis__',
-			customizeSnapshotSubpath: (subpath) => subpath,
+			customizeSnapshotSubpath: (subpath) => trimCommonFolder(subpath),
 			customizeSnapshotId: (id, index) => `${id}-${index}`,
 			diffOptions: undefined, // pixelmatch options
 			failureThresholdType: 'pixel',

package/src/client/align_images.ts

@@ -0,0 +1,11 @@
+import { getMaxSize } from '../shared/get_max_size.ts'
+import { isSameSize } from '../shared/is_same_size.ts'
+import { createImageResizer } from './image_resizer.ts'
+
+export function alignImagesToSameSize(image1: ImageData, image2: ImageData): [image1: ImageData, image2: ImageData] {
+	if (isSameSize(image1, image2)) return [image1, image2] as const
+
+	const size = getMaxSize(image1, image2)
+	const resize = createImageResizer(size)
+	return [resize(image1), resize(image2)] as const
+}

package/src/client/compare_image.ts

@@ -0,0 +1,21 @@
+import pixelmatch from 'pixelmatch'
+import { convertThresholdUnit } from '../shared/convert_threshold_unit.ts'
+import type { ImageSnapshotCompareOptions } from '../shared/types.ts'
+
+export function compareImage(
+	baselineImage: ImageData,
+	resultImage: ImageData,
+	{ failureThreshold = 0, failureThresholdType = 'pixel', diffOptions }: ImageSnapshotCompareOptions = {},
+) {
+	const { width, height } = resultImage
+	const diffImage = new ImageData(width, height)
+
+	const pixelDiff = pixelmatch(resultImage.data, baselineImage.data, diffImage.data, width, height, diffOptions)
+	const diffAmount = convertThresholdUnit({ failureThresholdType, width, height }, pixelDiff)
+
+	return {
+		pass: diffAmount <= failureThreshold,
+		diffAmount,
+		diffImage,
+	}
+}

package/src/client/expect/to_match_image_snapshot.ts

@@ -1,9 +1,7 @@
-import { commands } from '@vitest/browser/context'
 import type { AsyncExpectationResult } from '@vitest/expect'
 import { ctx } from '../ctx.ts'
-import { toTaskId } from '../task_id.ts'
+import { matchImageSnapshot } from '../match_image_snapshot.ts'
 import { success } from './expectation_result.ts'
-import { parseImageSnapshotSubject } from './to_match_image_snapshot.logic.ts'
 import type { ToMatchImageSnapshotOptions } from './to_match_image_snapshot.types.ts'
 
 export function toMatchImageSnapshot(
@@ -26,18 +24,5 @@ export function toMatchImageSnapshot(
 		)
 	}
 
-	const s = parseImageSnapshotSubject(subject)
-	const taskId = toTaskId(test)
-	return toMatchImageSnapshotAsync(taskId, s, options).then(() => success)
-}
-
-async function toMatchImageSnapshotAsync(taskId: string, subject: string, options?: ToMatchImageSnapshotOptions) {
-	if (options?.customizeSnapshotId) {
-		const index = await commands.imageSnapshotNextIndex(taskId)
-		const { customizeSnapshotId, ...rest } = options
-		const snapshotFileId = customizeSnapshotId(taskId, index)
-		return commands.matchImageSnapshot(taskId, subject, { ...rest, snapshotFileId })
-	}
-
-	return commands.matchImageSnapshot(taskId, subject, options)
+	return matchImageSnapshot(test, subject, options).then(() => success)
 }

package/src/client/image_data.ts

@@ -0,0 +1,36 @@
+export function toImageData(base64: string) {
+	return new Promise<ImageData>((resolve, reject) => {
+		const img = new Image()
+		img.src = `data:image/png;base64,${base64}`
+
+		img.onload = () => {
+			const canvas = document.createElement('canvas')
+			canvas.width = img.width
+			canvas.height = img.height
+			const ctx = canvas.getContext('2d')!
+			ctx.drawImage(img, 0, 0)
+			resolve(ctx.getImageData(0, 0, canvas.width, canvas.height))
+		}
+
+		img.onerror = () => {
+			reject(new Error('Failed to load image'))
+		}
+	})
+}
+
+export async function toDataURL(imageData: ImageData) {
+	const canvas = document.createElement('canvas')
+	canvas.width = imageData.width
+	canvas.height = imageData.height
+	const ctx = canvas.getContext('2d')!
+	ctx.putImageData(imageData, 0, 0)
+	return new Promise<string>((resolve) => {
+		canvas.toBlob((blob) => {
+			const reader = new FileReader()
+			reader.onload = () => {
+				resolve(reader.result as string)
+			}
+			reader.readAsDataURL(blob!)
+		})
+	})
+}

package/src/client/image_resizer.ts

@@ -0,0 +1,59 @@
+import { isSameSize } from '../shared/is_same_size.ts'
+
+export const createImageResizer =
+	({ width, height }: { width: number; height: number }) =>
+	(image: ImageData) => {
+		if (isSameSize(image, { width, height })) return image
+
+		const inArea = (x: number, y: number) => y <= image.height && x <= image.width
+
+		const data = new Uint8ClampedArray(width * height * 4)
+		const result = new ImageData(data, width, height, { colorSpace: image.colorSpace })
+
+		for (let y = 0; y < height; y++) {
+			for (let x = 0; x < width; x++) {
+				const idx = (width * y + x) << 2
+				if (inArea(x, y)) {
+					const old = (image.width * y + x) << 2
+					result.data[idx] = image.data[old]!
+					result.data[idx + 1] = image.data[old + 1]!
+					result.data[idx + 2] = image.data[old + 2]!
+					result.data[idx + 3] = image.data[old + 3]!
+				} else {
+					result.data[idx] = 0
+					result.data[idx + 1] = 0
+					result.data[idx + 2] = 0
+					result.data[idx + 3] = 64
+				}
+			}
+		}
+
+		return result
+	}
+
+// slower
+export const createImageResizer2 =
+	({ width, height }: { width: number; height: number }) =>
+	(image: ImageData) => {
+		if (isSameSize(image, { width, height })) return image
+
+		const inArea = (x: number, y: number) => y <= image.height && x <= image.width
+
+		const data = new Uint8ClampedArray(width * height * 4)
+		const result = new ImageData(data, width, height, { colorSpace: image.colorSpace })
+
+		const copyBytes = image.width * 4
+		for (let y = 0; y < height; y++) {
+			result.data.set(image.data.slice(y * image.width, copyBytes), y * width * 4)
+			for (let x = image.width; x < width; x++) {
+				const idx = (width * y + x) << 2
+				if (!inArea(x, y)) {
+					result.data[idx] = 0
+					result.data[idx + 1] = 0
+					result.data[idx + 2] = 0
+					result.data[idx + 3] = 64
+				}
+			}
+		}
+		return result
+	}

package/src/client/match_image_snapshot.logic.ts

@@ -0,0 +1,13 @@
+import type { ToMatchImageSnapshotOptions } from './expect/to_match_image_snapshot.types.ts'
+
+export function prettifyOptions(options: ToMatchImageSnapshotOptions | undefined) {
+	if (!options) return 'none'
+
+	return [
+		`failureThreshold: ${options.failureThreshold ?? 0} ${options.failureThresholdType ?? 'pixel'}`,
+		options.diffOptions ? `diffOptions: ${JSON.stringify(options.diffOptions)}` : '',
+		options.timeout ? `timeout: ${options.timeout} ms` : '',
+	]
+		.filter(Boolean)
+		.join(', ')
+}

package/src/client/match_image_snapshot.ts

@@ -0,0 +1,78 @@
+import { commands } from '@vitest/browser/context'
+import dedent from 'dedent'
+import { resolve } from 'pathe'
+import type { Task } from 'vitest'
+import { isBase64String } from '../shared/base64.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'
+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,
+	)
+
+	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
+	}
+
+	await writeSnapshot(info.diffPath, diffImage)
+
+	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)}`,
+	)
+}
+
+/**
+ * @deprecated internalized. Use `matchImageSnapshot` directly instead.
+ */
+export function parseImageSnapshotSubject(subject: any) {
+	if (subject instanceof Element) return convertElementToCssSelector(subject)
+	if (subject?.['selector']) return subject['selector']
+	if (isBase64String(subject)) return subject
+	throw new Error(
+		`'toMatchImageSnapshot()' expects the subject to be an element, locator, or image encoded in base64 string, but got: ${subject}`,
+	)
+}
+
+async function writeSnapshot(path: string, image: ImageData) {
+	const content = (await toDataURL(image)).split(',')[1]!
+	return commands.writeImageSnapshot(path, content)
+}
+
+async function parseImageSnapshotOptions(taskId: string, options: ToMatchImageSnapshotOptions) {
+	const index = await commands.imageSnapshotNextIndex(taskId)
+	const { customizeSnapshotId, ...rest } = options
+	const snapshotFileId = customizeSnapshotId!(taskId, index)
+	return { ...rest, snapshotFileId }
+}

package/src/client/task_id.ts

@@ -3,6 +3,9 @@ type Task = {
 	suite?: Task | undefined
 }
 
+/**
+ * @deprecated not needed anymore. Use `matchImageSnapshot` directly instead.
+ */
 export function toTaskId(task: Task) {
 	const l: any[] = []
 	let t = task

package/src/client/vitest_browser_context_proxy.ts

@@ -0,0 +1,44 @@
+import type { BrowserCommands, Platform } from '@vitest/browser/context'
+import type { SerializedConfig } from 'vitest'
+
+let ctx: Awaited<typeof import('@vitest/browser/context')>
+
+if ((globalThis as any).__vitest_browser__) {
+	import('@vitest/browser/context').then((m) => {
+		ctx = m
+	})
+}
+
+export const server = new Proxy<{
+	/**
+	 * Platform the Vitest server is running on.
+	 * The same as calling `process.platform` on the server.
+	 */
+	platform: Platform
+	/**
+	 * Runtime version of the Vitest server.
+	 * The same as calling `process.version` on the server.
+	 */
+	version: string
+	/**
+	 * Name of the browser provider.
+	 */
+	provider: string
+	/**
+	 * Name of the current browser.
+	 */
+	browser: string
+	/**
+	 * Available commands for the browser.
+	 * @see {@link https://vitest.dev/guide/browser/commands}
+	 */
+	commands: BrowserCommands
+	/**
+	 * Serialized test config.
+	 */
+	config: SerializedConfig
+}>({} as any, {
+	get(target, prop) {
+		return (target as any)[prop] ?? (ctx?.server as any)[prop]
+	},
+})

package/src/client.ts

@@ -1,6 +1,6 @@
 export * from './client/expect/expectation_result.ts'
-export * from './client/expect/to_match_image_snapshot.logic.ts'
 export type * from './client/expect/to_match_image_snapshot.types.ts'
+export * from './client/match_image_snapshot.ts'
 export * from './client/should_take_snapshot.ts'
 export * from './client/snapshot_options.ts'
 export * from './client/task_id.ts'

package/src/server/browser_provider/playwright.ts

@@ -5,7 +5,7 @@ export function playwright(context: BrowserCommandContext): BrowserApi {
 	return {
 		async takeScreenshot(filePath, selector, options) {
 			// The `Locator` type from `vitest` has less props than the `Locator` in `playwright`
-			const subject = context.iframe.locator(selector ?? 'body')
+			const subject = context.iframe.locator(selector)
 			return subject.screenshot({
 				timeout: options?.timeout,
 				path: filePath,

package/src/server/browser_provider/webdriverio.ts

@@ -5,7 +5,7 @@ export function webdriverio(context: BrowserCommandContext): BrowserApi {
 	const page = (context.provider as any).browser!
 	return {
 		async takeScreenshot(filePath, selector) {
-			const element = await page.$(`${selector ?? 'body'}`)
+			const element = await page.$(`${selector}`)
 			return element.saveScreenshot(filePath)
 		},
 	}

package/src/server/commands/extend.ts

@@ -1,13 +1,20 @@
 import { type HasImageSnapshotCommand, hasImageSnapshot } from './has_image_snapshot.ts'
 import { type ImageSnapshotNextIndexCommand, imageSnapshotNextIndex } from './image_snapshot_next_index.ts'
 import { type MatchImageSnapshotCommand, matchImageSnapshot } from './match_image_snapshot.ts'
+import {
+	type PrepareImageSnapshotComparisonCommand,
+	prepareImageSnapshotComparison,
+} from './prepare_image_snapshot_comparison.ts'
 import { type SetupVisSuiteCommand, setupVisSuite } from './setup_vis_suite.ts'
+import { type WriteImageSnapshotCommand, writeImageSnapshot } from './write_image_snapshot.ts'
 
 declare module '@vitest/browser/context' {
 	interface BrowserCommands
 		extends SetupVisSuiteCommand,
 			ImageSnapshotNextIndexCommand,
 			HasImageSnapshotCommand,
+			PrepareImageSnapshotComparisonCommand,
+			WriteImageSnapshotCommand,
 			MatchImageSnapshotCommand {}
 }
 
@@ -16,4 +23,6 @@ export const commands = {
 	imageSnapshotNextIndex,
 	hasImageSnapshot,
 	matchImageSnapshot,
+	prepareImageSnapshotComparison,
+	writeImageSnapshot,
 }

package/src/server/commands/match_image_snapshot.ts

@@ -1,9 +1,8 @@
 import dedent from 'dedent'
 import ci from 'is-ci'
-import { mkdirp } from 'mkdirp'
-import { dirname, resolve } from 'pathe'
+import { resolve } from 'pathe'
 import { PNG } from 'pngjs'
-import type { BrowserCommand, BrowserCommandContext } from 'vitest/node'
+import type { BrowserCommand } from 'vitest/node'
 import { isBase64String } from '../../shared/base64.ts'
 import { getMaxSize } from '../../shared/get_max_size.ts'
 import { isSameSize } from '../../shared/is_same_size.ts'
@@ -12,9 +11,9 @@ import type {
 	ImageSnapshotIdOptions,
 	ImageSnapshotTimeoutOptions,
 } from '../../shared/types.ts'
-import { browserApi } from '../browser_provider/browser_api.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'
 
 export interface MatchImageSnapshotCommand {
@@ -57,7 +56,7 @@ export const matchImageSnapshot: BrowserCommand<
 		return
 	}
 
-	const resultBuffer = await takeSnapshot(context, subject, info.resultPath, options)
+	const resultBuffer = await takeSnapshot(context, info.resultPath, subject, options)
 	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)
@@ -77,6 +76,11 @@ export const matchImageSnapshot: BrowserCommand<
 		)
 	}
 
+	if (context.project.config.snapshotOptions.updateSnapshot === 'all') {
+		await writeSnapshotBuffer(info.baselinePath, resultImage.data)
+		return
+	}
+
 	await writeSnapshotBuffer(info.diffPath, diffImage.data)
 
 	throw new Error(
@@ -98,41 +102,6 @@ export const matchImageSnapshot: BrowserCommand<
 	)
 }
 
-async function takeSnapshot(
-	context: BrowserCommandContext,
-	subject: string,
-	filePath: string,
-	options: ImageSnapshotTimeoutOptions | undefined,
-) {
-	if (isBase64String(subject)) {
-		await writeSnapshot(filePath, subject)
-		return Buffer.from(subject, 'base64')
-	}
-	return takeSnapshotByBrowser(context, filePath, subject, options)
-}
-
-async function takeSnapshotByBrowser(
-	context: BrowserCommandContext,
-	filePath: string,
-	subject: string,
-	options: ImageSnapshotTimeoutOptions | undefined,
-) {
-	await mkdirp(dirname(filePath))
-	const browser = browserApi(context)
-	return browser.takeScreenshot(filePath, subject, {
-		timeout: options?.timeout,
-	})
-}
-
-async function writeSnapshot(filePath: string, subject: string) {
-	await mkdirp(dirname(filePath))
-	await file.writeFile(filePath, subject, { encoding: 'base64' })
-}
-async function writeSnapshotBuffer(filePath: string, subject: Buffer) {
-	await mkdirp(dirname(filePath))
-	await file.writeFile(filePath, subject)
-}
-
 function alignImageSizes(baseline: PNG, result: PNG) {
 	if (isSameSize(baseline, result)) return [baseline, result] as const
 

package/src/server/commands/prepare_image_snapshot_comparison.ts

@@ -0,0 +1,55 @@
+import ci from 'is-ci'
+import type { BrowserCommand } from 'vitest/node'
+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 type { MatchImageSnapshotOptions } from './match_image_snapshot.ts'
+
+type ImageSnapshotComparisonInfo = {
+	projectRoot: string
+	baselinePath: string
+	resultPath: string
+	diffPath: string
+	baseline: string
+	result: string
+}
+
+export interface PrepareImageSnapshotComparisonCommand {
+	prepareImageSnapshotComparison: (
+		taskId: string | undefined,
+		subject: string,
+		options?: MatchImageSnapshotOptions | undefined,
+	) => Promise<ImageSnapshotComparisonInfo | undefined>
+}
+
+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')
+	}
+
+	// vitest:browser passes in `null` when not defined
+	if (!options) options = {}
+	options.timeout = options.timeout ?? (ci ? 30000 : 5000)
+
+	const info = visContext.getSnapshotInfo(context.testPath, taskId, options)
+	const baselineBuffer = await file.tryReadFile(info.baselinePath)
+	if (!baselineBuffer) {
+		if (isBase64String(subject)) {
+			await writeSnapshot(info.baselinePath, subject)
+		} else {
+			await takeSnapshotByBrowser(context, info.baselinePath, subject, options)
+		}
+		return
+	}
+
+	const resultBuffer = await takeSnapshot(context, info.resultPath, subject, options)
+	return {
+		...info,
+		projectRoot: context.project.runner.root,
+		baseline: baselineBuffer.toString('base64'),
+		result: resultBuffer.toString('base64'),
+	}
+}

package/src/server/commands/write_image_snapshot.ts

@@ -0,0 +1,20 @@
+import { mkdirp } from 'mkdirp'
+import { dirname } from 'pathe'
+import type { BrowserCommand } from 'vitest/node'
+import { file } from '../file.ts'
+
+export interface WriteImageSnapshotCommand {
+	writeImageSnapshot(taskId: string, snapshotId?: string | undefined): Promise<boolean>
+}
+
+export const writeImageSnapshot: BrowserCommand<[filePath: string, base64: string]> = async (
+	context,
+	filePath,
+	base64,
+) => {
+	if (!context.testPath) {
+		throw new Error('Cannot take snapshot without testPath')
+	}
+	await mkdirp(dirname(filePath))
+	await file.writeFile(filePath, base64, { encoding: 'base64' })
+}

package/src/server/snapshot.ts

@@ -0,0 +1,42 @@
+import { mkdirp } from 'mkdirp'
+import { dirname } from 'pathe'
+import type { BrowserCommandContext } from 'vitest/node'
+import type { ImageSnapshotTimeoutOptions } from '../client.ts'
+import { isBase64String } from '../shared/base64.ts'
+import { browserApi } from './browser_provider/browser_api.ts'
+import { file } from './file.js'
+
+export async function takeSnapshot(
+	context: BrowserCommandContext,
+	filePath: string,
+	subject: string,
+	options: ImageSnapshotTimeoutOptions | undefined,
+) {
+	if (isBase64String(subject)) {
+		await writeSnapshot(filePath, subject)
+		return Buffer.from(subject, 'base64')
+	}
+	return takeSnapshotByBrowser(context, filePath, subject, options)
+}
+
+export async function takeSnapshotByBrowser(
+	context: BrowserCommandContext,
+	filePath: string,
+	subject: string,
+	options: ImageSnapshotTimeoutOptions | undefined,
+) {
+	await mkdirp(dirname(filePath))
+	const browser = browserApi(context)
+	return browser.takeScreenshot(filePath, subject ?? 'body', {
+		timeout: options?.timeout,
+	})
+}
+
+export async function writeSnapshot(filePath: string, subject: string) {
+	await mkdirp(dirname(filePath))
+	await file.writeFile(filePath, subject, { encoding: 'base64' })
+}
+export async function writeSnapshotBuffer(filePath: string, subject: Buffer) {
+	await mkdirp(dirname(filePath))
+	await file.writeFile(filePath, subject)
+}

package/src/shared/convert_threshold_unit.ts

@@ -8,6 +8,6 @@ export function convertThresholdUnit(
 		case 'percent':
 			return (pixelDiff / (width * height)) * 100
 		default:
-			throw new Error(`Invalid failureThresholdType: ${failureThresholdType}`)
+			throw new Error(`Unsupported failureThresholdType: ${failureThresholdType}`)
 	}
 }