vitest-plugin-vis 1.0.0

package/src/client/snapshot_options.internal.ts

@@ -0,0 +1,22 @@
+import { NAME } from '../shared/constants.ts'
+import type { MetaTask, SnapshotMeta } from './snapshot_options.ts'
+
+export function getAutoSnapshotOptions(task: MetaTask): SnapshotMeta | 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) => {
+		if (cur?.[NAME]) {
+			const { [NAME]: meta } = cur
+			return Object.assign({}, acc, meta)
+		}
+		return acc
+	}, {})
+}

package/src/client/snapshot_options.ts

@@ -0,0 +1,53 @@
+import { NAME } from '../shared/constants.ts'
+import { ctx } from './ctx.ts'
+import type { ToMatchImageSnapshotOptions } from './expect/to_match_image_snapshot.types.ts'
+
+export type SnapshotMeta = ToMatchImageSnapshotOptions & { enable?: boolean | undefined }
+
+type Suite = { meta: Record<string, any>; suite?: Suite | undefined }
+
+export type MetaTask =
+	| {
+			file?: { meta: Record<string, any> } | undefined
+			suite?: Suite | undefined
+			meta: Record<string, any>
+	  }
+	| undefined
+
+/**
+ * Set the snapshot options for auto snapshot.
+ *
+ * ```ts
+ * beforeAll((suite) => setAutoSnapshotOptions(suite, ...))
+ * beforeEach(({ task }) => setAutoSnapshotOptions(task, ...))
+ *
+ * it('...', ({ task }) => {
+ *   setAutoSnapshotOptions(task, ...)
+ * })
+ * ```
+ *
+ * @param task Optional. Suite or task to set the options.
+ * If not provided, it will set the options for the current test.
+ */
+export function setAutoSnapshotOptions(task: MetaTask, meta: SnapshotMeta | boolean): void
+export function setAutoSnapshotOptions(meta: SnapshotMeta | boolean): void
+export function setAutoSnapshotOptions(
+	...args: [task: MetaTask, meta: SnapshotMeta | boolean] | [meta: SnapshotMeta | boolean]
+): void {
+	const [task, meta] = parseArgs(args)
+	if (task)
+		task.meta[NAME] = {
+			...task.meta[NAME],
+			...meta,
+		}
+}
+
+function parseArgs(
+	args: [task: MetaTask, meta: SnapshotMeta | boolean] | [meta: boolean | SnapshotMeta],
+): [MetaTask | undefined, SnapshotMeta] {
+	return args.length === 1 ? [ctx.getCurrentTest(), parseMeta(args[0])] : [args[0], parseMeta(args[1])]
+}
+
+function parseMeta(meta: boolean | SnapshotMeta): SnapshotMeta {
+	return typeof meta === 'boolean' ? { enable: meta } : { enable: true, ...meta }
+}

package/src/client/task_id.ts

@@ -0,0 +1,16 @@
+type Task = {
+	name: string
+	suite?: Task | undefined
+}
+
+export function toTaskId(task: Task) {
+	const l: any[] = []
+	let t = task
+	while (t?.suite) {
+		l.unshift(t.suite.name.replace(/[^a-z0-9]/gi, '-').toLowerCase())
+		t = t.suite
+	}
+
+	l.push(task.name.replace(/[^a-z0-9]/gi, '-').toLowerCase())
+	return l.join('/')
+}

package/src/client.ts

@@ -0,0 +1,7 @@
+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/should_take_snapshot.ts'
+export * from './client/snapshot_options.ts'
+export * from './client/task_id.ts'
+export type * from './shared/types.ts'

package/src/commands.ts

@@ -0,0 +1,4 @@
+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'

package/src/config/readme.md

@@ -0,0 +1,4 @@
+# Config
+
+Code in this directory is used to configure the plugin.
+Vitest runs the configuration code in a NodeJS main thread.

package/src/config/types.ts

@@ -0,0 +1,35 @@
+import type { ToMatchImageSnapshotOptions } from '../client/expect/to_match_image_snapshot.types.ts'
+
+export interface VisOptions extends ToMatchImageSnapshotOptions {
+	/**
+	 * Loads the `test.setupFiles` of the specified preset.
+	 */
+	preset?: 'manual' | 'auto' | 'none' | undefined
+	/**
+	 * The snapshot folder relative to the root of the project.
+	 *
+	 * Default: `__vis__`
+	 */
+	snapshotRootDir?: string | undefined
+	/**
+	 * Customize the snapshot subpath.
+	 *
+	 * The snapshot subpath is used along with `snapshotRootDir` to determine the folder of the snapshots:
+	 *
+	 * - baseline: `<snapshotRootDir>/<platform>/<snapshotSubpath>/<snapshotId>.png`
+	 * - result: `<snapshotRootDir>/__results__/<snapshotSubpath>/<snapshotId>.png`
+	 * - diff: `<snapshotRootDir>/__diffs__/<snapshotSubpath>/<snapshotId>.png`
+	 *
+	 * Typically, you place your test files either in a dedicated `tests` folder or in the `src` folder along with your source code.
+	 * By default, the snapshot subpath is the test file path with that folder removed to reduces nesting of the snapshot folders.
+	 *
+	 * If you place your test files in multiple folders,
+	 * such as in both `tests` and `src` folders,
+	 * and they might have files with the same name and create conflicting snapshots,
+	 * you can set this to customize the snapshot subpath.
+	 *
+	 * @param subPath - The path of the test file to be used as the snapshot sub path.
+	 * If you want to keep the full path, you can simply return it.
+	 */
+	customizeSnapshotSubpath?: (subPath: string) => string
+}

package/src/config/vis.ts

@@ -0,0 +1,30 @@
+import type { Plugin } from 'vite'
+import { commands } from '../server/commands/extend.ts'
+import { visContext } from '../server/vis_context.ts'
+import { NAME } from '../shared/constants.ts'
+import type { VisOptions } from './types.ts'
+
+/**
+ * Create a Vite plugin for visual testing.
+ *
+ * If options are not provided, the plugin will use the default options,
+ * which enables the `auto` preset.
+ */
+export function vis(options: VisOptions = { preset: 'auto' }) {
+	visContext.setOptions(options)
+	const preset = options?.preset
+	return {
+		name: NAME,
+		config() {
+			return {
+				test: {
+					browser: {
+						name: undefined as unknown as string,
+						commands,
+					},
+					setupFiles: preset && preset !== 'none' ? [`vitest-plugin-vis/presets/${preset}`] : undefined,
+				},
+			}
+		},
+	} satisfies Plugin
+}

package/src/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/index.ts

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

package/src/presets/auto.ts

@@ -0,0 +1,4 @@
+import 'vitest-browser-react'
+import { vis } from '../setup/vis.ts'
+
+vis.presets.auto()

package/src/presets/manual.ts

@@ -0,0 +1,4 @@
+import 'vitest-browser-react'
+import { vis } from '../setup/vis.ts'
+
+vis.presets.manual()

package/src/server/browser_provider/browser_api.ts

@@ -0,0 +1,13 @@
+import type { BrowserCommandContext } from 'vitest/node'
+import { playwright } from './playwright.ts'
+import { webdriverio } from './webdriverio.ts'
+
+export function browserApi(context: BrowserCommandContext) {
+	if (context.provider.name === 'playwright') {
+		return playwright(context)
+	}
+	if (context.provider.name === 'webdriverio') {
+		return webdriverio(context)
+	}
+	throw new Error(`Unsupported provider: ${context.provider.name}`)
+}

package/src/server/browser_provider/playwright.ts

@@ -0,0 +1,16 @@
+import type { BrowserCommandContext } from 'vitest/node'
+import type { BrowserApi } from './types.ts'
+
+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 buffer = await subject.screenshot({
+				timeout: options?.timeout,
+				path: filePath,
+			})
+			return buffer.toString('base64')
+		},
+	}
+}

package/src/server/browser_provider/types.ts

@@ -0,0 +1,11 @@
+export interface BrowserApi {
+	takeScreenshot(
+		filePath: string,
+		selector: string,
+		options:
+			| {
+					timeout?: number | undefined
+			  }
+			| undefined,
+	): Promise<string>
+}

package/src/server/browser_provider/webdriverio.ts

@@ -0,0 +1,13 @@
+import type { BrowserCommandContext } from 'vitest/node'
+import type { BrowserApi } from './types.ts'
+
+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 buffer = await element.saveScreenshot(filePath)
+			return buffer.toString('base64')
+		},
+	}
+}

package/src/server/commands/extend.ts

@@ -0,0 +1,19 @@
+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 SetupVisSuiteCommand, setupVisSuite } from './setup_vis_suite.ts'
+
+declare module '@vitest/browser/context' {
+	interface BrowserCommands
+		extends SetupVisSuiteCommand,
+			ImageSnapshotNextIndexCommand,
+			HasImageSnapshotCommand,
+			MatchImageSnapshotCommand {}
+}
+
+export const commands = {
+	setupVisSuite,
+	imageSnapshotNextIndex,
+	hasImageSnapshot,
+	matchImageSnapshot,
+}

package/src/server/commands/has_image_snapshot.ts

@@ -0,0 +1,18 @@
+import type { BrowserCommand } from 'vitest/node'
+import { visContext } from '../vis_context.ts'
+
+export interface HasImageSnapshotCommand {
+	hasImageSnapshot(taskId: string, snapshotId?: string | undefined): Promise<boolean>
+}
+
+export const hasImageSnapshot: BrowserCommand<[taskId: string, snapshotId?: string | undefined]> = async (
+	context,
+	taskId,
+	snapshotId,
+) => {
+	if (!context.testPath) {
+		throw new Error('Cannot take snapshot without testPath')
+	}
+
+	return visContext.hasImageSnapshot(context.testPath, taskId, snapshotId)
+}

package/src/server/commands/image_snapshot_next_index.ts

@@ -0,0 +1,17 @@
+import type { BrowserCommand } from 'vitest/node'
+import { visContext } from '../vis_context.ts'
+
+export interface ImageSnapshotNextIndexCommand {
+	/**
+	 * Get the index of the snapshot image to be created.
+	 */
+	imageSnapshotNextIndex(taskId: string): Promise<number>
+}
+
+export const imageSnapshotNextIndex: BrowserCommand<[taskId: string]> = async (context, taskId) => {
+	if (!context.testPath) {
+		throw new Error('Cannot take snapshot without testPath')
+	}
+
+	return visContext.getTaskCount(context.testPath, taskId)
+}

package/src/server/commands/is_ci.ts

@@ -0,0 +1,7 @@
+// import ci from 'is-ci'
+
+// export interface IsCICommand {
+// 	isCI: () => Promise<boolean>
+// }
+
+// export const isCI = async () => ci

package/src/server/commands/match_image_snapshot.ts

@@ -0,0 +1,139 @@
+import dedent from 'dedent'
+import ci from 'is-ci'
+import { mkdirp } from 'mkdirp'
+import { dirname, resolve } from 'pathe'
+import { PNG } from 'pngjs'
+import type { BrowserCommand, BrowserCommandContext } 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'
+import type {
+	ImageSnapshotCompareOptions,
+	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 { visContext } from '../vis_context.ts'
+
+export interface MatchImageSnapshotCommand {
+	matchImageSnapshot: (
+		taskId: string | undefined,
+		subject: string,
+		options?: MatchImageSnapshotOptions | undefined,
+	) => Promise<void>
+}
+
+export interface MatchImageSnapshotOptions
+	extends ImageSnapshotTimeoutOptions,
+		ImageSnapshotIdOptions,
+		ImageSnapshotCompareOptions {
+	/**
+	 * The snapshot file id calculated on the client side.
+	 */
+	snapshotFileId?: string | undefined
+}
+
+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')
+	}
+
+	// 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 baselineBase64 = await file.tryReadFileBase64(info.baselinePath)
+	if (!baselineBase64) {
+		await takeSnapshot(context, subject, info.baselinePath, options)
+		return
+	}
+
+	const resultBase64 = await takeSnapshot(context, subject, info.resultPath, options)
+	const baselineImage = PNG.sync.read(Buffer.from(baselineBase64, 'base64'))
+	const resultImage = PNG.sync.read(Buffer.from(resultBase64, 'base64'))
+	const [baselineAlignedImage, resultAlignedImage] = isSameSize(baselineImage, resultImage)
+		? [baselineImage, resultImage]
+		: alignImageSizes(baselineImage, resultImage)
+
+	const { pass, diffAmount, diffImage } = compareImage(baselineAlignedImage, resultAlignedImage, options)
+	if (pass) {
+		if (sizeNotChanged(baselineImage, baselineAlignedImage)) {
+			return
+		}
+		throw new Error(
+			dedent`Snapshot \`${taskId}\` mismatched
+
+				The image size changed form ${baselineImage.width}x${baselineImage.height} to ${resultImage.width}x${resultImage.height}
+
+				Expected:   ${resolve(context.project.runner.root, info.baselinePath)}
+				Actual:     ${resolve(context.project.runner.root, info.resultPath)}`,
+		)
+	}
+
+	const diffBase64 = PNG.sync.write(diffImage).toString('base64')
+	await writeSnapshot(diffBase64, 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:    ${JSON.stringify(options)}
+
+			Expected:   ${resolve(context.project.runner.root, info.baselinePath)}
+			Actual:     ${resolve(context.project.runner.root, info.resultPath)}
+			Difference: ${resolve(context.project.runner.root, info.diffPath)}`,
+	)
+}
+
+async function takeSnapshot(
+	context: BrowserCommandContext,
+	subject: string,
+	filePath: string,
+	options: ImageSnapshotTimeoutOptions | undefined,
+) {
+	if (isBase64String(subject)) {
+		return writeSnapshot(subject, filePath)
+	}
+
+	await mkdirp(dirname(filePath))
+	const browser = browserApi(context)
+	return browser.takeScreenshot(filePath, subject, {
+		timeout: options?.timeout,
+	})
+}
+
+async function writeSnapshot(subject: string, filePath: string) {
+	await mkdirp(dirname(filePath))
+	await file.writeFileBase64(filePath, subject)
+	return subject
+}
+
+function alignImageSizes(baseline: PNG, result: PNG) {
+	const size = getMaxSize(baseline, result)
+
+	const baselineAligned = new PNG(size)
+	const resultAligned = new PNG(size)
+
+	baselineAligned.data.fill(0)
+	resultAligned.data.fill(0)
+
+	PNG.bitblt(baseline, baselineAligned, 0, 0, baseline.width, baseline.height)
+	PNG.bitblt(result, resultAligned, 0, 0, result.width, result.height)
+
+	return [baselineAligned, resultAligned] as const
+}
+function sizeNotChanged(baselineImage: PNG, baselineAlignedImage: PNG) {
+	return baselineImage === baselineAlignedImage
+}

package/src/server/commands/setup_vis_suite.ts

@@ -0,0 +1,17 @@
+import type { BrowserCommand } from 'vitest/node'
+import { visContext } from '../vis_context.ts'
+
+export interface SetupVisSuiteCommand {
+	/**
+	 * Sets up the visual testing suite by cleaning up previous snapshot and diff output directories.
+	 * When this command is run for the first time,
+	 * it will remove the results and diffs directory of all suites.
+	 *
+	 * In subsequent runs, it will only remove the results and diffs directory of the current suite.
+	 */
+	setupVisSuite: () => Promise<void>
+}
+
+export const setupVisSuite: BrowserCommand<[]> = async (context) => {
+	await visContext.setupSuite(context)
+}

package/src/server/compare_image.ts

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

package/src/server/file.ts

@@ -0,0 +1,15 @@
+import { readFile, stat, writeFile } from 'node:fs/promises'
+
+export const file = {
+	async tryReadFileBase64(filePath: string): Promise<string | undefined> {
+		return readFile(filePath, { encoding: 'base64' }).catch(() => undefined)
+	},
+	writeFileBase64(filePath: string, data: string) {
+		return writeFile(filePath, data, { encoding: 'base64' })
+	},
+	existFile(filePath: string) {
+		return stat(filePath)
+			.then((s) => s.isFile())
+			.catch(() => false)
+	},
+}

package/src/server/readme.md

@@ -0,0 +1,5 @@
+# Server
+
+This is the server part of the plugin.
+Vitest Browser runs this code in a NodeJS worker.
+It is a separate process from the config/main process.

package/src/server/snapshot_path.ts

@@ -0,0 +1,12 @@
+import type { VisOptions } from '../config/types.ts'
+import { SNAPSHOT_ROOT_DIR } from '../shared/constants.ts'
+import { trimCommonFolder } from '../shared/trim_common_folder.ts'
+
+export function resolveSnapshotRootDir(options: VisOptions | undefined) {
+	return options?.snapshotRootDir ?? SNAPSHOT_ROOT_DIR
+}
+
+export function getSnapshotSubpath(suiteName: string, options: VisOptions) {
+	const customizeSnapshotSubpath = options.customizeSnapshotSubpath ?? trimCommonFolder
+	return customizeSnapshotSubpath(suiteName)
+}

package/src/server/vis_context.ctx.ts

@@ -0,0 +1,12 @@
+/* v8 ignore start */
+import ci from 'is-ci'
+import { rimraf } from 'rimraf'
+
+export const ctx = {
+	rimraf,
+	getSnapshotPlatform() {
+		/* v8 ignore next */
+		return ci ? process.platform : 'local'
+	},
+}
+/* v8 ignore end */