vitest-plugin-vis 1.0.0

package/src/server/vis_context.logic.ts

@@ -0,0 +1,141 @@
+import { join, relative } from 'pathe'
+import type { VisOptions } from '../config/types.ts'
+import { DIFF_DIR, RESULT_DIR } from '../shared/constants.ts'
+import { file } from './file.ts'
+import { getSnapshotSubpath, resolveSnapshotRootDir } from './snapshot_path.ts'
+import { ctx } from './vis_context.ctx.ts'
+import type { VisState } from './vis_context.types.ts'
+
+export type PartialBrowserCommandContext = {
+	project: {
+		config: {
+			root: string
+			snapshotOptions: {
+				updateSnapshot: 'all' | 'new' | 'none'
+			}
+			testTimeout: number
+			hookTimeout: number
+		}
+	}
+	testPath: string | undefined
+}
+
+export function createVisContext() {
+	let visOptions: VisOptions = {}
+	let state: VisState
+	let globalStateReady: Promise<VisState>
+
+	const context = {
+		setOptions(options: VisOptions = {}) {
+			visOptions = options
+		},
+		__test__getOptions() {
+			return visOptions
+		},
+		__test__reset() {
+			visOptions = undefined as any
+		},
+		__test__getState() {
+			return state
+		},
+		/**
+		 * Setup suite is called on each test file's beforeAll hook.
+		 * Test files include vitest test files and storybook story files.
+		 * It needs to make sure there is no race condition between the test files.
+		 */
+		async setupSuite(context: PartialBrowserCommandContext) {
+			if (!globalStateReady) {
+				globalStateReady = setupState(context, visOptions)
+				state = await globalStateReady
+			} else {
+				await globalStateReady
+			}
+
+			const { suiteId, suite } = createSuite(state, context.testPath!, visOptions)
+			state.suites[suiteId] = suite
+			await Promise.allSettled([ctx.rimraf(suite.diffDir), ctx.rimraf(suite.resultDir)])
+		},
+		getSnapshotInfo(testPath: string, name: string, options?: { snapshotFileId?: string | undefined }) {
+			const info = context.getSuiteInfo(testPath, name)
+			const snapshotFilename = context.getSnapshotFilename(info, options?.snapshotFileId)
+
+			const { baselineDir, resultDir, diffDir, task } = info
+
+			task.count = task.count + 1
+			const baselinePath = join(baselineDir, snapshotFilename)
+			const resultPath = join(resultDir, snapshotFilename)
+			const diffPath = join(diffDir, snapshotFilename)
+
+			return {
+				baselinePath,
+				resultPath,
+				diffPath,
+			}
+		},
+		getTaskCount(testPath: string, taskId: string) {
+			return context.getSuiteInfo(testPath, taskId).task.count
+		},
+		hasImageSnapshot(testPath: string, taskId: string, snapshotFileId: string | undefined) {
+			const info = context.getSuiteInfo(testPath, taskId)
+			return file.existFile(join(info.baselineDir, context.getSnapshotFilename(info, snapshotFileId)))
+		},
+		getSnapshotFilename(info: { taskId: string; task: { count: number } }, snapshotFileId: string | undefined) {
+			if (snapshotFileId) return `${snapshotFileId}.png`
+
+			const customizeSnapshotId = visOptions.customizeSnapshotId ?? ((id, index) => `${id}-${index}`)
+			return `${customizeSnapshotId(info.taskId, info.task.count)}.png`
+		},
+		getSuiteInfo(testPath: string, taskId: string) {
+			const suiteId = getSuiteId(state, testPath, visOptions)
+			const suite = state.suites[suiteId]!
+			const task = (suite.tasks[taskId] = suite.tasks[taskId] ?? { count: 1 })
+			return {
+				suiteId,
+				taskId,
+				baselineDir: suite.baselineDir,
+				resultDir: suite.resultDir,
+				diffDir: suite.diffDir,
+				task,
+			}
+		},
+	}
+	return context
+}
+
+async function setupState(suite: PartialBrowserCommandContext, visOptions: VisOptions) {
+	const snapshotRootDir = resolveSnapshotRootDir(visOptions)
+	const projectPath = suite.project.config.root
+	const platform = ctx.getSnapshotPlatform()
+
+	const state = {
+		projectPath,
+		platform,
+		testTimeout: suite.project.config.testTimeout,
+		hookTimeout: suite.project.config.hookTimeout,
+		snapshotRootDir,
+		snapshotBaselineDir: join(snapshotRootDir, platform),
+		snapshotResultDir: join(snapshotRootDir, RESULT_DIR),
+		snapshotDiffDir: join(snapshotRootDir, DIFF_DIR),
+		snapshotRootPath: join(projectPath, snapshotRootDir),
+		suites: {},
+	}
+	await Promise.allSettled([ctx.rimraf(join(state.snapshotDiffDir)), ctx.rimraf(join(state.snapshotResultDir))])
+	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 {
+		suiteId,
+		suite: {
+			baselineDir: join(state.snapshotBaselineDir, suiteId),
+			resultDir: join(state.snapshotResultDir, suiteId),
+			diffDir: join(state.snapshotDiffDir, suiteId),
+			tasks: {},
+		},
+	}
+}

package/src/server/vis_context.ts

@@ -0,0 +1,3 @@
+import { createVisContext } from './vis_context.logic.ts'
+
+export const visContext = createVisContext()

package/src/server/vis_context.types.ts

@@ -0,0 +1,25 @@
+export type VisState = {
+	projectPath: string
+	platform: string
+	testTimeout: number
+	hookTimeout: number
+	snapshotRootDir: string
+	snapshotBaselineDir: string
+	snapshotResultDir: string
+	snapshotDiffDir: string
+	snapshotRootPath: string
+	suites: Record<
+		string,
+		{
+			baselineDir: string
+			resultDir: string
+			diffDir: string
+			tasks: Record<
+				string,
+				{
+					count: number
+				}
+			>
+		}
+	>
+}

package/src/setup/create_vis.ts

@@ -0,0 +1,98 @@
+import dedent from 'dedent'
+import { afterEach, beforeAll, expect } from 'vitest'
+import { toTaskId } from '../client.ts'
+import { ctx } from '../client/ctx.ts'
+import { shouldTakeSnapshot } from '../client/should_take_snapshot.ts'
+import { getAutoSnapshotOptions } from '../client/snapshot_options.internal.js'
+import type { SetupVisSuiteCommand } from '../server/commands/setup_vis_suite.ts'
+
+export function createVis(commands: SetupVisSuiteCommand) {
+	/**
+	 * Visual test configuration on the client side.
+	 */
+	const vis = {
+		presets: {
+			/**
+			 * Enable manual visual testing.
+			 */
+			manual() {
+				beforeAll(vis.beforeAll.setup)
+			},
+			/**
+			 * Enable automatic visual testing.
+			 *
+			 * This will take a snapshot after each test.
+			 */
+			auto() {
+				beforeAll(vis.beforeAll.setup)
+				afterEach(vis.afterEach.matchImageSnapshot)
+			},
+			/**
+			 * Enable automatic visual testing with multiple themes.
+			 *
+			 * This will take a snapshot after each test for each theme.
+			 *
+			 * @param themes A record of theme names and their setup functions.
+			 *
+			 * @example
+			 * ```ts
+			 * vis().presets.theme({
+			 *  light() { document.body.classList.add('light') },
+			 *  dark() { document.body.classList.add('dark') },
+			 * })
+			 * ```
+			 */
+			theme(themes: Record<string, () => void | Promise<void>>) {
+				beforeAll(vis.beforeAll.setup)
+				afterEach(vis.afterEach.matchPerTheme(themes))
+			},
+		},
+		beforeAll: {
+			async setup() {
+				await commands.setupVisSuite()
+			},
+		},
+		afterEach: {
+			async matchImageSnapshot() {
+				const meta = getAutoSnapshotOptions(ctx.getCurrentTest())
+				if (!shouldTakeSnapshot(meta)) return
+				await expect(document.body).toMatchImageSnapshot(meta)
+			},
+			matchPerTheme(themes: Record<string, () => Promise<void> | void>) {
+				return async function matchImageSnapshot() {
+					const test = ctx.getCurrentTest()
+					const meta = getAutoSnapshotOptions(test)
+					if (!shouldTakeSnapshot(meta)) return
+
+					const errors: any[] = []
+					for (const themeId in themes) {
+						try {
+							await themes[themeId]!()
+							await expect(document.body).toMatchImageSnapshot({
+								...meta,
+								customizeSnapshotId: (id) => `${id}-${themeId}`,
+							})
+						} catch (error) {
+							errors.push([themeId, error])
+						}
+					}
+					if (errors.length > 0) {
+						if (errors.length === 1) throw errors[0][1]
+						const taskId = toTaskId(test!)
+						throw new AggregateError(
+							errors,
+							dedent`Snapshot \`${taskId}\` mismatched
+
+						${errors
+							.map(([themeId, error]) => {
+								return `Theme \`${themeId}\` failed: ${error.message}`
+							})
+							.join('\n')}`,
+						)
+					}
+				}
+			},
+		},
+	}
+	return vis
+}

package/src/setup/vis.ts

@@ -0,0 +1,7 @@
+import { commands } from '@vitest/browser/context'
+import { createVis } from './create_vis.ts'
+
+/**
+ * Visual test configuration on the client side.
+ */
+export const vis = createVis(commands)

package/src/setup.ts

@@ -0,0 +1,9 @@
+// `vitest-plugin-vis/setup` provides code needed in `vitest.setup.ts`.
+import './client/expect/extend.ts'
+import './client/page/extend.ts'
+
+export * from './setup/vis.ts'
+
+// This is exported for main/app boundary separation
+// They can co-exist in the same export file thanks to ESM.
+export * from './setup/create_vis.ts'

package/src/shared/base64.ts

@@ -0,0 +1,3 @@
+export function isBase64String(value: unknown): value is string {
+	return typeof value === 'string' && /^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$/.test(value)
+}

package/src/shared/constants.ts

@@ -0,0 +1,4 @@
+export const NAME = 'vis'
+export const SNAPSHOT_ROOT_DIR = '__vis__'
+export const RESULT_DIR = '__results__'
+export const DIFF_DIR = '__diffs__'

package/src/shared/convert_threshold_unit.ts

@@ -0,0 +1,13 @@
+export function convertThresholdUnit(
+	{ failureThresholdType, width, height }: { failureThresholdType: 'pixel' | 'percent'; width: number; height: number },
+	pixelDiff: number,
+): number {
+	switch (failureThresholdType) {
+		case 'pixel':
+			return pixelDiff
+		case 'percent':
+			return (pixelDiff / (width * height)) * 100
+		default:
+			throw new Error(`Invalid failureThresholdType: ${failureThresholdType}`)
+	}
+}

package/src/shared/get_max_size.ts

@@ -0,0 +1,5 @@
+export function getMaxSize(image1: { width: number; height: number }, image2: { width: number; height: number }) {
+	const width = Math.max(image1.width, image2.width)
+	const height = Math.max(image1.height, image2.height)
+	return { width, height }
+}

package/src/shared/is_same_size.ts

@@ -0,0 +1,3 @@
+export function isSameSize(image1: { width: number; height: number }, image2: { width: number; height: number }) {
+	return image1.width === image2.width && image1.height === image2.height
+}

package/src/shared/trim_common_folder.ts

@@ -0,0 +1,10 @@
+/**
+ * Trim off common folder such as `src` or `tests` from the test file path.
+ * This is used to generate the default snapshot sub-path.
+ */
+export function trimCommonFolder(suiteName: string) {
+	const suiteDir = suiteName.split('/', 1)[0]!
+	if (['tests', 'test', 'src', 'source', 'js', 'ts', 'lib'].includes(suiteDir))
+		return suiteName.slice(suiteDir.length + 1)
+	return suiteName
+}

package/src/shared/types.ts

@@ -0,0 +1,39 @@
+import type { PixelmatchOptions } from 'pixelmatch'
+
+export interface ImageSnapshotTimeoutOptions {
+	/**
+	 * Timeout for taking the snapshot.
+	 *
+	 * Default: 5000 ms locally, 30000 ms on CI.
+	 */
+	timeout?: number | undefined
+}
+
+export interface ImageSnapshotIdOptions {
+	/**
+	 * Customize the snapshot id. This is used as the filename of the snapshot: `${snapshotId}.png`
+	 *
+	 * @param id The id of the snapshot.
+	 * @param index The index of the snapshot.
+	 */
+	customizeSnapshotId?: (id: string, index: number) => string
+}
+
+export interface ImageSnapshotCompareOptions {
+	/**
+	 * Custom options passed to 'pixelmatch'
+	 */
+	diffOptions?: PixelmatchOptions | undefined
+	/**
+	 * Failure threshold should measure in `pixel` or `percent`.
+	 *
+	 * Default is `pixel`.
+	 */
+	failureThresholdType?: 'pixel' | 'percent' | undefined
+	/**
+	 * Failure tolerance threshold.
+	 *
+	 * Default is `0`.
+	 */
+	failureThreshold?: number | undefined
+}