vitest-plugin-vis 4.0.0 → 4.2.0

package/src/server/commands/load_image_snapshot_results.ts

@@ -1,27 +1,8 @@
+import type { ImageSnapshotResult } from '../../shared/commands.types.ts'
 import { visServerContext } from '../vis_server_context.ts'
 import type { ExtendedBrowserCommand } from '../vis_server_context.types.ts'
 import { assertTestPathDefined } from './_assertions.ts'
 
-export interface ImageSnapshotResult {
-	filename: string
-	/**
-	 * The base64 encoded image of the baseline snapshot.
-	 */
-	baseline?: string | undefined
-	/**
-	 * The base64 encoded image of the result snapshot.
-	 */
-	result?: string | undefined
-	/**
-	 * The base64 encoded image of the diff snapshot.
-	 */
-	diff?: string | undefined
-}
-
-export interface LoadImageSnapshotResultsCommand {
-	loadImageSnapshotResults(taskId: string): Promise<ImageSnapshotResult[]>
-}
-
 export const loadImageSnapshotResults: ExtendedBrowserCommand<[taskId: string]> = async (
 	context,
 	taskId,

package/src/server/commands/prepare_image_snapshot_comparison.ts

@@ -1,60 +1,14 @@
 import { resolve } from 'pathe'
 import { isBase64String } from '../../shared/base64.ts'
-import type {
-	FailureThresholdOptions,
-	ImageSnapshotTimeoutOptions,
-	PixelComparisonOptions,
-	SsimComparisonOptions,
-} from '../../shared/types.ts'
+import type { PrepareImageSnapshotComparisonCommand } from '../../shared/commands.types.ts'
+import type { ImageSnapshotComparisonInfo } from '../../shared/types.ts'
 import { file } from '../externals/file.ts'
 import { getProjectRoot } from '../project.ts'
-import { takeSnapshot, takeSnapshotByBrowser } from '../snapshot.ts'
+import { takeSnapshot } from '../snapshot.ts'
 import { snapshotWriter } from '../snapshot_writer.ts'
 import { visServerContext } from '../vis_server_context.ts'
 import type { ExtendedBrowserCommand } from '../vis_server_context.types.ts'
 import { assertTestPathDefined } from './_assertions.ts'
-import type { MatchImageSnapshotOptions } from './types.ts'
-
-export type ImageSnapshotComparisonInfo = {
-	/**
-	 * Path to the project root.
-	 */
-	projectRoot: string
-	/**
-	 * Path to the baseline image relative to the project root.
-	 */
-	baselinePath: string
-	/**
-	 * Path to the result image relative to the project root.
-	 */
-	resultPath: string
-	/**
-	 * Path to the diff image relative to the project root.
-	 */
-	diffPath: string
-	/**
-	 * Base64 encoded baseline image.
-	 */
-	baseline: string
-	/**
-	 * Base64 encoded result image.
-	 */
-	result: string
-	/**
-	 * Base64 encoded diff image.
-	 */
-	diff?: string | undefined
-} & ImageSnapshotTimeoutOptions &
-	FailureThresholdOptions &
-	(SsimComparisonOptions | PixelComparisonOptions)
-
-export interface PrepareImageSnapshotComparisonCommand {
-	prepareImageSnapshotComparison: (
-		taskId: string,
-		subject: string,
-		options?: MatchImageSnapshotOptions | undefined,
-	) => Promise<ImageSnapshotComparisonInfo | undefined>
-}
 
 export const prepareImageSnapshotComparison: ExtendedBrowserCommand<
 	Parameters<PrepareImageSnapshotComparisonCommand['prepareImageSnapshotComparison']>
@@ -68,20 +22,20 @@ export const prepareImageSnapshotComparison: ExtendedBrowserCommand<
 	const info = await visServerContext.getSnapshotInfo(context, taskId, options)
 
 	const baselineBuffer = await file.tryReadFile(resolve(projectRoot, info.baselinePath))
-	if (!baselineBuffer) {
-		if (isBase64String(subject)) {
-			await snapshotWriter.writeBase64(resolve(projectRoot, info.baselinePath), subject)
-		} else {
-			await takeSnapshotByBrowser(context, projectRoot, info.baselinePath, subject, options)
+	if (!baselineBuffer && isBase64String(subject)) {
+		await snapshotWriter.writeBase64(resolve(projectRoot, info.resultPath), subject)
+		return {
+			...info,
+			projectRoot,
+			result: subject,
 		}
-		return
 	}
 
 	const resultBuffer = await takeSnapshot(context, projectRoot, info.resultPath, subject, options)
 	return {
 		...info,
 		projectRoot,
-		baseline: baselineBuffer.toString('base64'),
+		baseline: baselineBuffer?.toString('base64'),
 		result: resultBuffer.toString('base64'),
 	}
 }

package/src/server/commands/prepare_page_image_snapshot_comparison.ts

@@ -1,53 +1,11 @@
 import { resolve } from 'pathe'
-import type {
-	FailureThresholdOptions,
-	ImageSnapshotTimeoutOptions,
-	PixelComparisonOptions,
-	SsimComparisonOptions,
-} from '../../shared/types.ts'
+import type { PreparePageImageSnapshotComparisonCommand } from '../../shared/commands.types.ts'
 import { file } from '../externals/file.ts'
 import { getProjectRoot } from '../project.ts'
 import { takePageSnapshot } from '../snapshot.ts'
 import { visServerContext } from '../vis_server_context.ts'
 import type { ExtendedBrowserCommand } from '../vis_server_context.types.ts'
 import { assertTestPathDefined } from './_assertions.ts'
-import type { MatchImageSnapshotOptions } from './types.ts'
-
-type ImageSnapshotComparisonInfo = {
-	/**
-	 * Path to the project root.
-	 */
-	projectRoot: string
-	/**
-	 * Path to the baseline image relative to the project root.
-	 */
-	baselinePath: string
-	/**
-	 * Path to the result image relative to the project root.
-	 */
-	resultPath: string
-	/**
-	 * Path to the diff image relative to the project root.
-	 */
-	diffPath: string
-	/**
-	 * Base64 encoded baseline image.
-	 */
-	baseline: string
-	/**
-	 * Base64 encoded result image.
-	 */
-	result: string
-} & ImageSnapshotTimeoutOptions &
-	FailureThresholdOptions &
-	(SsimComparisonOptions | PixelComparisonOptions)
-
-export interface PreparePageImageSnapshotComparisonCommand {
-	preparePageImageSnapshotComparison: (
-		taskId: string,
-		options?: MatchImageSnapshotOptions | undefined,
-	) => Promise<ImageSnapshotComparisonInfo | undefined>
-}
 
 export const preparePageImageSnapshotComparison: ExtendedBrowserCommand<
 	Parameters<PreparePageImageSnapshotComparisonCommand['preparePageImageSnapshotComparison']>
@@ -60,16 +18,11 @@ export const preparePageImageSnapshotComparison: ExtendedBrowserCommand<
 	const projectRoot = getProjectRoot(context)
 	const info = await visServerContext.getSnapshotInfo(context, taskId, options)
 	const baselineBuffer = await file.tryReadFile(resolve(projectRoot, info.baselinePath))
-	if (!baselineBuffer) {
-		await takePageSnapshot(context, projectRoot, info.baselinePath, options)
-		return
-	}
-
 	const resultBuffer = await takePageSnapshot(context, projectRoot, info.resultPath, options)
 	return {
 		...info,
 		projectRoot,
-		baseline: baselineBuffer.toString('base64'),
+		baseline: baselineBuffer?.toString('base64'),
 		result: resultBuffer.toString('base64'),
 	}
 }

package/src/server/commands/setup_vis_suite.ts

@@ -1,31 +1,7 @@
-import type { Pick } from 'type-plus'
-import type { VisOptions } from '../../config/types.ts'
 import { setupSuite } from '../suite.ts'
 import type { ExtendedBrowserCommand, ExtendedBrowserCommandContext } from '../vis_server_context.types.ts'
 import { assertTestPathDefined } from './_assertions.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<
-		Pick<
-			VisOptions,
-			| 'comparisonMethod'
-			| 'diffOptions'
-			| 'failureThreshold'
-			| 'failureThresholdType'
-			| 'snapshotKey'
-			| 'subject'
-			| 'timeout'
-		>
-	>
-}
-
 export const setupVisSuite: ExtendedBrowserCommand<[]> = async (context): Promise<{ subject: string | undefined }> => {
 	assertTestPathDefined(context, 'setupVisSuite')
 	return setupSuite(context as unknown as ExtendedBrowserCommandContext)

package/src/server/snapshot_path.ts

@@ -6,12 +6,14 @@ import { trimCommonFolder } from '../shared/trim_common_folder.ts'
 import type { ExtendedBrowserCommandContext } from './vis_server_context.types.ts'
 
 export function resolveSnapshotRootDir(browserCommandContext: ExtendedBrowserCommandContext, options: VisOptions) {
-	if (!options.snapshotRootDir) return getSnapshotRootDir(SNAPSHOT_ROOT_DIR)
+	if (!options.snapshotRootDir) return getSnapshotRootDir()
 	const snapshotRootDir = options.snapshotRootDir
 	if (typeof snapshotRootDir === 'string') return getSnapshotRootDir(snapshotRootDir)
 	const { config } = browserCommandContext.project.browser
 	return snapshotRootDir({
 		ci,
+		rootDir: SNAPSHOT_ROOT_DIR,
+		projectName: browserCommandContext.project.name,
 		browserName: config.browser.name,
 		providerName: browserCommandContext.provider.name,
 		platform,

package/src/server/vis_server_context.logic.ts

@@ -1,7 +1,7 @@
 import { basename, join, resolve } from 'pathe'
 import { pick } from 'type-plus'
 import type { ImageSnapshotKeyOptions } from '../client-api.ts'
-import type { ImageSnapshotResult } from './commands/load_image_snapshot_results.ts'
+import type { ImageSnapshotResult } from '../shared/commands.types.ts'
 import { file } from './externals/file.ts'
 import { getSuite, getTaskSubpath } from './suite.ts'
 import { getVisOption } from './vis_options.ts'

package/src/{setup.create_vis.mdx → setup/create_vis.mdx}

@@ -1,12 +1,11 @@
 import { Meta, Markdown ,Canvas} from "@storybook/addon-docs/blocks";
 
-<Meta
-tags={['deprecated']}
-title="vitest-plugin-vis/setup/createVis"
-/>
+<Meta title="setup/createVis" tags={['deprecated']} />
+
+# `createVis`
 
 🪦 Deprecated
 
 `createVis` in `vitest-plugin-vis/setup` is deprecated.
 
-It is moved to `/client-api`.
+It is moved to `vitest-plugin-vis/setup-api`.

package/src/{client/setup → setup}/create_vis.ts

@@ -1,27 +1,9 @@
-import dedent from 'dedent'
-import { afterEach, beforeAll } from 'vitest'
-import type { SetupVisSuiteCommand } from '../../server/commands/setup_vis_suite.ts'
-import type { ComparisonMethod } from '../../shared/types.ts'
-import { extractAutoSnapshotOptions, setAutoSnapshotOptions } from '../auto_snapshot_options.ts'
-import { ctx } from '../ctx.ts'
-import { shouldTakeSnapshot } from '../should_take_snapshot.ts'
-import type { SnapshotMeta } from '../snapshot_meta.ts'
-import { toTaskId } from '../task_id.ts'
-
-export type SetupVisOptions<GM extends Record<string, any> | unknown = unknown> = {
-	auto?:
-		| boolean
-		| (<C extends ComparisonMethod, M extends Record<string, any> | unknown = unknown>(
-				options: SnapshotMeta<C> & M & GM,
-		  ) => Promise<boolean> | Promise<void> | boolean | void)
-		| Record<
-				string,
-				| boolean
-				| (<C extends ComparisonMethod, M extends Record<string, any> | unknown = unknown>(
-						options: SnapshotMeta<C> & M & GM,
-				  ) => Promise<boolean> | Promise<void> | boolean | void)
-		  >
-}
+import { afterEach, beforeAll, expect } from 'vitest'
+import { setAutoSnapshotOptions } from '../auto_snapshots/auto_snapshot_options.ts'
+import type { SnapshotMeta } from '../auto_snapshots/snapshot_meta.ts'
+import { autoSnapshotMatcher } from '../client/suite/auto_snapshot_matcher.ts'
+import type { SetupVisSuiteCommand } from '../shared/commands.types.ts'
+import type { ComparisonMethod, SetupVisOptions } from '../shared/types.ts'
 
 /**
  * Visual test configuration on the client side.
@@ -110,10 +92,19 @@ export type VisClientConfigurator<GM extends Record<string, any> | unknown = unk
 		): void
 	}
 	beforeAll: {
+		/**
+		 * @deprecated No known use case.
+		 */
 		setup(): Promise<void>
 	}
 	afterEach: {
+		/**
+		 * @deprecated No known use case.
+		 */
 		matchImageSnapshot(): Promise<void>
+		/**
+		 * @deprecated No known use case.
+		 */
 		matchPerTheme<C extends ComparisonMethod, M extends Record<string, any> | unknown = unknown>(
 			themes: Record<
 				string,
@@ -124,106 +115,63 @@ export type VisClientConfigurator<GM extends Record<string, any> | unknown = unk
 }
 
 export function createVis<GM extends Record<string, any> | unknown = unknown>(commands: SetupVisSuiteCommand) {
-	let subject: string | undefined
+	const matcher = autoSnapshotMatcher(commands, expect)
 
 	const vis: VisClientConfigurator<GM> = {
 		setup(options) {
 			if (!options || options.auto === false) {
-				beforeAll(vis.beforeAll.setup)
+				beforeAll(matcher.setup)
 			} else {
 				beforeAll(async () => {
-					await vis.beforeAll.setup()
+					await matcher.setup()
 					setAutoSnapshotOptions(true)
 				})
 			}
 
 			if (typeof options?.auto === 'function') {
-				afterEach(
-					vis.afterEach.matchPerTheme({
-						auto: options.auto,
-					}),
-				)
+				afterEach(matcher.createMatcher({ auto: options.auto }))
 			} else if (typeof options?.auto === 'object') {
-				afterEach(vis.afterEach.matchPerTheme(options.auto))
+				afterEach(matcher.createMatcher(options.auto))
 			} else {
-				afterEach(vis.afterEach.matchImageSnapshot)
+				afterEach(matcher.createMatcher({ async auto() {} }))
 			}
 		},
 		presets: {
 			enable() {
-				beforeAll(vis.beforeAll.setup)
-				afterEach(vis.afterEach.matchImageSnapshot)
+				beforeAll(matcher.setup)
+				afterEach(matcher.createMatcher({ async auto() {} }))
 			},
 			manual() {
-				beforeAll(vis.beforeAll.setup)
+				beforeAll(matcher.setup)
 			},
 			auto() {
 				beforeAll(async () => {
-					await vis.beforeAll.setup()
+					await matcher.setup()
 					setAutoSnapshotOptions(true)
 				})
-				afterEach(vis.afterEach.matchImageSnapshot)
+				afterEach(matcher.createMatcher({ async auto() {} }))
 			},
 			theme(themes) {
 				beforeAll(async () => {
-					await vis.beforeAll.setup()
+					await matcher.setup()
 					setAutoSnapshotOptions(true)
 				})
-				afterEach(vis.afterEach.matchPerTheme(themes))
+				afterEach(matcher.createMatcher(themes))
 			},
 		},
 		beforeAll: {
 			async setup() {
-				subject = (await commands.setupVisSuite()).subject
+				await matcher.setup()
 			},
 		},
 		afterEach: {
 			async matchImageSnapshot() {
-				return vis.afterEach.matchPerTheme({ async auto() {} })()
+				return matcher.createMatcher({ async auto() {} })()
 			},
 			matchPerTheme(themes) {
-				return async function matchImageSnapshot() {
-					const test = ctx.getCurrentTest()
-					if ((test?.result?.errors?.length ?? 0) > 0) return
-
-					const meta = extractAutoSnapshotOptions(test)
-					if (!shouldTakeSnapshot(meta)) return
-					const errors: Array<[string, Error]> = []
-					for (const themeId in themes) {
-						try {
-							await new Promise((a) => setTimeout(a, 10))
-							const theme = themes[themeId]
-							const r = typeof theme === 'function' ? await theme(meta! as any) : theme
-							if (r === false) continue
-							await test!.context.expect(getSubject(meta?.subject ?? subject)).toMatchImageSnapshot({
-								...meta,
-								snapshotKey: meta?.snapshotKey ?? themeId,
-							})
-						} catch (error) {
-							errors.push([themeId, error as 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\n')}`,
-						)
-					}
-				}
+				return matcher.createMatcher(themes)
 			},
 		},
 	}
 	return vis
 }
-
-function getSubject(selectors: string | undefined) {
-	return selectors ? (document.querySelector(selectors) ?? document.body) : document.body
-}

package/src/setup/overview.mdx

@@ -0,0 +1,17 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="setup" />
+
+# Overview
+
+`vitest-plugin-vis/setup` provides the API to setup the plugin on the client side.
+
+It provides the API you needed in `vitest.setup.ts`.
+
+## Augmentation
+
+When you import `vitest-plugin-vis/setup`, it will augment `expect` and `page` to provide methods for visual testing.
+
+- `expect().toMatchImageSnapshot()`: Match the image snapshot.
+- `page.toMatchImageSnapshot()`: Match the image snapshot.
+- `page.hasImageSnapshot()`: Check if the image snapshot exists.

package/src/setup/readme.md

@@ -0,0 +1,7 @@
+# setup
+
+Code in this directory is used to setup the plugin in `vitest.setup.ts`.
+
+The code is executed in Vitest browser runner worker.
+
+This worker is running on a headless chrome with `window.name` set to `vitest-iframe`.

package/src/{setup.vis.mdx → setup/vis.mdx}

@@ -1,15 +1,10 @@
-import { Meta, Source } from "@storybook/addon-docs/blocks";
+import { Meta } from "@storybook/addon-docs/blocks";
 
-<Meta title="vitest-plugin-vis/setup/vis" />
+<Meta title="setup/vis" />
 
-`vis` from `vitest-plugin-vis/setup` is the main mechanism to setup the plugin on the client side.
+# `vis`
 
-```ts
-// vitest.setup.ts
-import { vis } from 'vitest-plugin-vis/setup'
-
-vis.setup()
-```
+`vis` object from `vitest-plugin-vis/setup` provides the API to setup the plugin on the client side.
 
 ## Basic Setup
 
@@ -23,7 +18,7 @@ vis.setup()
 // Enable auto snapshots for all tests
 vis.setup({ auto: true })
 
-// Disable auto snapshots (same as vis.setup())
+// Disable auto snapshots (same as `vis.setup()`)
 vis.setup({ auto: false })
 ```
 
@@ -46,6 +41,8 @@ vis.setup({
 })
 ```
 
+The function will be called during the `afterEach()` phase of the test.
+
 ## Multi-Theme Setup
 
 Set up automatic snapshots for multiple themes (e.g., light and dark mode):
@@ -56,11 +53,11 @@ import { vis } from 'vitest-plugin-vis/setup'
 
 vis.setup({
 	auto: {
-		async light() {
+		light: async () => {
 			document.body.classList.remove('dark')
 			document.body.classList.add('light')
 		},
-		async dark() {
+		dark: async () => {
 			document.body.classList.add('dark')
 			document.body.classList.remove('light')
 		}
@@ -78,11 +75,11 @@ import { vis } from 'vitest-plugin-vis/setup'
 
 vis.setup({
 	auto: {
-		async light({ meta }) {
+		light: async ({ meta }) => {
 			if (meta['skipLight']) return false
 			document.body.classList.remove('dark')
 		},
-		async dark({ meta }) {
+		dark: async ({ meta }) => {
 			if (meta['skipDark']) return false
 			document.body.classList.add('dark')
 		}
@@ -100,19 +97,19 @@ import { vis } from 'vitest-plugin-vis/setup'
 
 vis.setup({
 	auto: {
-		async desktop() {
+		desktop: async () => {
 			document.body.style.width = '1200px'
 			document.body.classList.add('desktop')
 		},
-		async tablet() {
+		tablet: async () => {
 			document.body.style.width = '768px'
 			document.body.classList.add('tablet')
 		},
-		async mobile() {
+		mobile: async () => {
 			document.body.style.width = '375px'
 			document.body.classList.add('mobile')
 		},
-		async 'dark-desktop'({ meta }) {
+		'dark-desktop': async ({ meta }) => {
 			if (meta['skipDark']) return false
 			document.body.style.width = '1200px'
 			document.body.classList.add('desktop', 'dark')

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

@@ -1,6 +1,10 @@
-// `vitest-plugin-vis/setup` provides code needed in `vitest.setup.ts`.
-import './client/expect/extend.ts'
-import './client/page/extend.ts'
+import './setup-api.ts'
 
-export * from './client/setup/create_vis.ts'
-export * from './client/setup/vis.ts'
+export * from './setup/vis.ts'
+
+import { createVis as createVisDeprecated } from './setup/create_vis.ts'
+
+/**
+ * @deprecated Use `createVis` from `vitest-plugin-vis/setup-api` instead.
+ */
+export const createVis = createVisDeprecated

package/src/shared/commands.types.ts

@@ -0,0 +1,71 @@
+import type { Pick } from 'type-plus'
+import type { VisOptions } from '../config/types.ts'
+import type { ImageSnapshotComparisonInfo, MatchImageSnapshotOptions } from './types.ts'
+
+export interface PrepareImageSnapshotComparisonCommand {
+	prepareImageSnapshotComparison: (
+		taskId: string,
+		subject: string,
+		options?: MatchImageSnapshotOptions | undefined,
+	) => Promise<ImageSnapshotComparisonInfo>
+}
+
+export interface PreparePageImageSnapshotComparisonCommand {
+	preparePageImageSnapshotComparison: (
+		taskId: string,
+		options?: MatchImageSnapshotOptions | undefined,
+	) => Promise<ImageSnapshotComparisonInfo>
+}
+
+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<
+		Pick<
+			VisOptions,
+			| 'comparisonMethod'
+			| 'diffOptions'
+			| 'failureThreshold'
+			| 'failureThresholdType'
+			| 'snapshotKey'
+			| 'subject'
+			| 'timeout'
+		>
+	>
+}
+
+export interface LoadImageSnapshotResultsCommand {
+	loadImageSnapshotResults(taskId: string): Promise<ImageSnapshotResult[]>
+}
+
+export interface ImageSnapshotResult {
+	filename: string
+	/**
+	 * The base64 encoded image of the baseline snapshot.
+	 */
+	baseline?: string | undefined
+	/**
+	 * The base64 encoded image of the result snapshot.
+	 */
+	result?: string | undefined
+	/**
+	 * The base64 encoded image of the diff snapshot.
+	 */
+	diff?: string | undefined
+}
+
+export interface HasImageSnapshotCommand {
+	hasImageSnapshot(taskId: string, snapshotKey: string | undefined): Promise<boolean>
+}
+
+export interface ImageSnapshotNextIndexCommand {
+	/**
+	 * Get the index of the snapshot image to be created.
+	 */
+	imageSnapshotNextIndex(taskId: string): Promise<number>
+}