vitest-plugin-vis 1.3.2 → 1.5.0

package/readme.md

@@ -41,6 +41,7 @@ export default defineConfig({
 
 This default configuration will:
 
+- Use `pixelmatch` as the image comparison method.
 - Use the `auto` preset, taking image snapshot at the end on each rendering test.
 - Set config to compare image snapshot with a failure threshold of `0 pixels`.
 - Local (non-CI) image snapshots are saved in the `<root>/__vis__/local` directory.
@@ -60,12 +61,15 @@ export default defineConfig({
 		vis({
 			preset: 'auto',
 			snapshotRootDir: '__vis__',
+			platform: '...', // {process.platform} or `local`
 			customizeSnapshotSubpath: (subpath) => trimCommonFolder(subpath),
 			customizeSnapshotId: (id, index) => `${id}-${index}`,
-			diffOptions: undefined, // pixelmatch options
+			comparisonMethod: 'pixel',
+			// pixelmatch or ssim.js options, depending on `comparisonMethod`.
+			diffOptions: undefined,
 			failureThresholdType: 'pixel',
 			failureThreshold: 0,
-			timeout: 5000 // 30000 on CI
+			timeout: 30000
 		})
 	],
 	test:{
@@ -181,11 +185,13 @@ setAutoSnapshotOptions(true /* or false */)
 // detailed options
 setAutoSnapshotOptions({
 	enable: true,
+	comparisonMethod: 'pixel',
 	customizeSnapshotId: (id, index) => `${id}-custom-${index}`,
-	diffOptions: { threshold: 0.01 } // pixelmatch options,
+	// pixelmatch or ssim.js options, depending on `comparisonMethod`.
+	diffOptions: { threshold: 0.01 },
 	failureThreshold: 0.01,
 	failureThresholdType: 'percent',
-	timeout: 15000
+	timeout: 60000
 })
 ```
 
@@ -238,7 +244,7 @@ it('manual snapshot with options', async () => {
 		diffOptions: {
 			threshold: 0.1
 		},
-		timeout: 15000
+		timeout: 60000
 	})
 })
 ```
@@ -282,6 +288,7 @@ Please follow its guide to set up your environment.
 
 Bonus note, if you want to install [Firefox] on WSL,
 you can follow these steps: [Install Firefox on Ubuntu 22.04](https://askubuntu.com/a/1444967).
+Also, you may need to `sudo apt-get install xdg-utils` to fix [`xdg-settings: not found`](https://serverfault.com/questions/1091926/running-chrome-on-ubuntu-server-how-to-solve-xdg-settings-not-found-using).
 
 ## Running on CI
 
@@ -296,8 +303,6 @@ It is recommended to run your tests serially to avoid flakiness.
 
 Some features in [`jest-image-snapshot`][jest-image-snapshot] are not implemented in [`vitest-plugin-vis`][vitest-plugin-vis] yet.
 This is because through our own usage, we do not found a good use case for them.
-For example, the `ssim` comparison method is not implemented in [`vitest-plugin-vis`][vitest-plugin-vis],
-because we found that figuring out what is the delta using `ssim` is quite difficult.
 
 If you have a good use case for these features, please open an issue or PR.
 

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

@@ -1,20 +1,20 @@
 import type {
+	ComparisonMethod,
 	ImageSnapshotCompareOptions,
 	ImageSnapshotIdOptions,
 	ImageSnapshotTimeoutOptions,
 } from '../../shared/types.ts'
 
 export interface ImageSnapshotMatcher {
-	toMatchImageSnapshot(options?: ToMatchImageSnapshotOptions | undefined): Promise<void>
+	toMatchImageSnapshot<M extends ComparisonMethod>(options?: ToMatchImageSnapshotOptions<M> | undefined): Promise<void>
 }
 
-export interface ToMatchImageSnapshotOptions
-	extends ImageSnapshotTimeoutOptions,
-		ImageSnapshotIdOptions,
-		ImageSnapshotCompareOptions {
-	/**
-	 * Expect the matcher to fail.
-	 * If it passes, it will throw an error with details.
-	 */
-	expectToFail?: boolean | undefined
-}
+export type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTimeoutOptions &
+	ImageSnapshotIdOptions &
+	ImageSnapshotCompareOptions<M> & {
+		/**
+		 * Expect the matcher to fail.
+		 * If it passes, it will throw an error with details.
+		 */
+		expectToFail?: boolean | undefined
+	}

package/src/client/image_snapshot_matcher.logic.ts

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

package/src/client/image_snapshot_matcher.ts

@@ -6,6 +6,7 @@ import type { PrepareImageSnapshotComparisonCommand } from '../server/commands/p
 import type { WriteImageSnapshotCommand } from '../server/commands/write_image_snapshot.ts'
 import { isBase64String } from '../shared/base64.ts'
 import { compareImage } from '../shared/compare_image.ts'
+import type { ComparisonMethod } from '../shared/types.ts'
 import { alignImagesToSameSize } from './align_images.ts'
 import type { ToMatchImageSnapshotOptions } from './expect/to_match_image_snapshot.types.ts'
 import { toDataURL, toImageData } from './image_data.ts'
@@ -17,7 +18,7 @@ import { server } from './vitest_browser_context_proxy.ts'
 export function imageSnapshotMatcher(
 	commands: PrepareImageSnapshotComparisonCommand & WriteImageSnapshotCommand & ImageSnapshotNextIndexCommand,
 ) {
-	return async function matchImageSnapshot(test: Task, subject: any, options?: ToMatchImageSnapshotOptions) {
+	return async function matchImageSnapshot(test: Task, subject: any, options?: ToMatchImageSnapshotOptions<any>) {
 		const taskId = toTaskId(test)
 		const info = await commands.prepareImageSnapshotComparison(
 			taskId,
@@ -27,6 +28,8 @@ export function imageSnapshotMatcher(
 
 		if (!info) return
 
+		options = { ...info, ...options } as any
+
 		const baselineImage = await toImageData(info.baseline)
 		const resultImage = await toImageData(info.result)
 		const [baselineAlignedImage, resultAlignedImage] = alignImagesToSameSize(baselineImage, resultImage)
@@ -101,7 +104,7 @@ async function writeSnapshot(commands: WriteImageSnapshotCommand, path: string,
 async function parseImageSnapshotOptions(
 	commands: ImageSnapshotNextIndexCommand,
 	taskId: string,
-	options: ToMatchImageSnapshotOptions,
+	options: ToMatchImageSnapshotOptions<any>,
 ) {
 	const index = await commands.imageSnapshotNextIndex(taskId)
 	const { customizeSnapshotId, ...rest } = options

package/src/client/should_take_snapshot.ts

@@ -9,7 +9,7 @@ import type { SnapshotMeta } from './snapshot_options.ts'
  * no `snapshot` tag: false
  * disabled by `!snapshot` tag: false
  */
-export function shouldTakeSnapshot(meta?: SnapshotMeta | undefined) {
+export function shouldTakeSnapshot(meta?: SnapshotMeta<any> | undefined) {
 	const m = meta ?? getAutoSnapshotOptions(ctx.getCurrentTest())
 	return document.body.childElementCount > 0 && m?.enable !== false
 }

package/src/client/snapshot_options.internal.ts

@@ -1,7 +1,7 @@
 import { NAME } from '../shared/constants.ts'
 import type { MetaTask, SnapshotMeta } from './snapshot_options.ts'
 
-export function getAutoSnapshotOptions(task: MetaTask): SnapshotMeta | undefined {
+export function getAutoSnapshotOptions(task: MetaTask): SnapshotMeta<any> | undefined {
 	if (!task) return
 
 	const list: any[] = []

package/src/client/snapshot_options.ts

@@ -1,8 +1,9 @@
 import { NAME } from '../shared/constants.ts'
+import type { ComparisonMethod } from '../shared/types.ts'
 import { ctx } from './ctx.ts'
 import type { ToMatchImageSnapshotOptions } from './expect/to_match_image_snapshot.types.ts'
 
-export type SnapshotMeta = ToMatchImageSnapshotOptions & { enable?: boolean | undefined }
+export type SnapshotMeta<M extends ComparisonMethod> = ToMatchImageSnapshotOptions<M> & { enable?: boolean | undefined }
 
 type Suite = { meta: Record<string, any>; suite?: Suite | undefined }
 
@@ -29,10 +30,13 @@ export type MetaTask =
  * @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]
+export function setAutoSnapshotOptions<M extends ComparisonMethod>(
+	task: MetaTask,
+	meta: SnapshotMeta<M> | boolean,
+): void
+export function setAutoSnapshotOptions<M extends ComparisonMethod>(meta: SnapshotMeta<M> | boolean): void
+export function setAutoSnapshotOptions<M extends ComparisonMethod>(
+	...args: [task: MetaTask, meta: SnapshotMeta<M> | boolean] | [meta: SnapshotMeta<M> | boolean]
 ): void {
 	const [task, meta] = parseArgs(args)
 	if (task)
@@ -42,12 +46,12 @@ export function setAutoSnapshotOptions(
 		}
 }
 
-function parseArgs(
-	args: [task: MetaTask, meta: SnapshotMeta | boolean] | [meta: boolean | SnapshotMeta],
-): [MetaTask | undefined, SnapshotMeta] {
+function parseArgs<M extends ComparisonMethod>(
+	args: [task: MetaTask, meta: SnapshotMeta<M> | boolean] | [meta: boolean | SnapshotMeta<M>],
+): [MetaTask | undefined, SnapshotMeta<M>] {
 	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 }
+function parseMeta<M extends ComparisonMethod>(meta: boolean | SnapshotMeta<M>): SnapshotMeta<M> {
+	return typeof meta === 'boolean' ? ({ enable: meta } as any) : { enable: true, ...meta }
 }

package/src/config/types.ts

@@ -1,35 +1,52 @@
-import type { ToMatchImageSnapshotOptions } from '../client/expect/to_match_image_snapshot.types.ts'
+import type {
+	ComparisonMethod,
+	ImageSnapshotCompareOptions,
+	ImageSnapshotIdOptions,
+	ImageSnapshotTimeoutOptions,
+} from '../shared/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
-}
+export type { ComparisonMethod }
+
+export type VisOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTimeoutOptions &
+	ImageSnapshotIdOptions &
+	ImageSnapshotCompareOptions<M> & {
+		/**
+		 * Loads the `test.setupFiles` of the specified preset.
+		 */
+		preset?: 'manual' | 'auto' | 'none' | undefined
+		/**
+		 * The name of the subdirectory that the baseline snapshots get saved in.
+		 *
+		 * <snapshotRootDir>/<platform>/<snapshotSubpath>/<snapshotId>.png
+		 *
+		 * Default: undefined
+		 */
+		platform?: string | 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

@@ -2,6 +2,7 @@ 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 { ComparisonMethod } from '../shared/types.ts'
 import type { VisOptions } from './types.ts'
 
 /**
@@ -10,7 +11,7 @@ import type { VisOptions } from './types.ts'
  * If options are not provided, the plugin will use the default options,
  * which enables the `auto` preset.
  */
-export function vis(options: VisOptions = { preset: 'auto' }) {
+export function vis<M extends ComparisonMethod = 'pixel'>(options: VisOptions<M> = { preset: 'auto' } as any) {
 	visContext.setOptions(options)
 	const preset = options?.preset
 	return {

package/src/server/commands/match_image_snapshot.ts

@@ -1,5 +1,4 @@
 import dedent from 'dedent'
-import ci from 'is-ci'
 import { resolve } from 'pathe'
 import { PNG } from 'pngjs'
 import type { BrowserCommand } from 'vitest/node'
@@ -25,15 +24,14 @@ export interface MatchImageSnapshotCommand {
 	) => Promise<void>
 }
 
-export interface MatchImageSnapshotOptions
-	extends ImageSnapshotTimeoutOptions,
-		ImageSnapshotIdOptions,
-		ImageSnapshotCompareOptions {
-	/**
-	 * The snapshot file id calculated on the client side.
-	 */
-	snapshotFileId?: string | undefined
-}
+export type MatchImageSnapshotOptions = ImageSnapshotTimeoutOptions &
+	ImageSnapshotIdOptions &
+	ImageSnapshotCompareOptions<any> & {
+		/**
+		 * The snapshot file id calculated on the client side.
+		 */
+		snapshotFileId?: string | undefined
+	}
 
 export const matchImageSnapshot: BrowserCommand<
 	[taskId: string, subject: string, options?: MatchImageSnapshotOptions | undefined]
@@ -42,7 +40,7 @@ export const matchImageSnapshot: BrowserCommand<
 
 	// vitest:browser passes in `null` when not defined
 	if (!options) options = {}
-	options.timeout = options.timeout ?? (ci ? 30000 : 5000)
+	options.timeout = options.timeout ?? 30000
 
 	const info = visContext.getSnapshotInfo(context.testPath, taskId, options)
 	const baselineBuffer = await file.tryReadFile(info.baselinePath)

package/src/server/commands/prepare_image_snapshot_comparison.ts

@@ -1,6 +1,11 @@
-import ci from 'is-ci'
 import type { BrowserCommand } from 'vitest/node'
 import { isBase64String } from '../../shared/base64.ts'
+import type {
+	FailureThresholdOptions,
+	ImageSnapshotTimeoutOptions,
+	PixelComparisonOptions,
+	SsimComparisonOptions,
+} from '../../shared/types.ts'
 import { file } from '../file.ts'
 import { takeSnapshot, takeSnapshotByBrowser, writeSnapshot } from '../snapshot.ts'
 import { visContext } from '../vis_context.ts'
@@ -14,7 +19,9 @@ type ImageSnapshotComparisonInfo = {
 	diffPath: string
 	baseline: string
 	result: string
-}
+} & ImageSnapshotTimeoutOptions &
+	FailureThresholdOptions &
+	(SsimComparisonOptions | PixelComparisonOptions)
 
 export interface PrepareImageSnapshotComparisonCommand {
 	prepareImageSnapshotComparison: (
@@ -31,7 +38,7 @@ export const prepareImageSnapshotComparison: BrowserCommand<
 
 	// vitest:browser passes in `null` when not defined
 	if (!options) options = {}
-	options.timeout = options.timeout ?? (ci ? 30000 : 5000)
+	options.timeout = options.timeout ?? 30000
 
 	const info = visContext.getSnapshotInfo(context.testPath, taskId, options)
 	const baselineBuffer = await file.tryReadFile(info.baselinePath)

package/src/server/snapshot_path.ts

@@ -2,11 +2,11 @@ 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) {
+export function resolveSnapshotRootDir(options: Pick<VisOptions, 'snapshotRootDir'> | undefined) {
 	return options?.snapshotRootDir ?? SNAPSHOT_ROOT_DIR
 }
 
-export function getSnapshotSubpath(suiteName: string, options: VisOptions) {
+export function getSnapshotSubpath(suiteName: string, options: Pick<VisOptions, 'customizeSnapshotSubpath'>) {
 	const customizeSnapshotSubpath = options.customizeSnapshotSubpath ?? trimCommonFolder
 	return customizeSnapshotSubpath(suiteName)
 }

package/src/server/vis_context.ctx.ts

@@ -5,7 +5,6 @@ import { rimraf } from 'rimraf'
 export const ctx = {
 	rimraf,
 	getSnapshotPlatform() {
-		/* v8 ignore next */
 		return ci ? process.platform : 'local'
 	},
 }

package/src/server/vis_context.logic.ts

@@ -1,4 +1,5 @@
 import { join, relative } from 'pathe'
+import { pick } from 'type-plus'
 import type { VisOptions } from '../config/types.ts'
 import { DIFF_DIR, RESULT_DIR } from '../shared/constants.ts'
 import { file } from './file.ts'
@@ -21,12 +22,12 @@ export type PartialBrowserCommandContext = {
 }
 
 export function createVisContext() {
-	let visOptions: VisOptions = {}
+	let visOptions: VisOptions<any> = {}
 	let state: VisState
 	let globalStateReady: Promise<VisState>
 
 	const context = {
-		setOptions(options: VisOptions = {}) {
+		setOptions<M extends 'pixel' | 'ssim'>(options: VisOptions<M> = {} as any) {
 			visOptions = options
 		},
 		__test__getOptions() {
@@ -67,6 +68,7 @@ export function createVisContext() {
 			const diffPath = join(diffDir, snapshotFilename)
 
 			return {
+				...pick(visOptions, 'comparisonMethod', 'diffOptions', 'failureThreshold', 'failureThresholdType', 'timeout'),
 				baselinePath,
 				resultPath,
 				diffPath,
@@ -102,10 +104,13 @@ export function createVisContext() {
 	return context
 }
 
-async function setupState(suite: PartialBrowserCommandContext, visOptions: VisOptions) {
+async function setupState(
+	suite: PartialBrowserCommandContext,
+	visOptions: Pick<VisOptions, 'snapshotRootDir' | 'platform'>,
+) {
 	const snapshotRootDir = resolveSnapshotRootDir(visOptions)
 	const projectPath = suite.project.config.root
-	const platform = ctx.getSnapshotPlatform()
+	const platform = visOptions.platform ?? ctx.getSnapshotPlatform()
 
 	const state = {
 		projectPath,
@@ -123,7 +128,7 @@ async function setupState(suite: PartialBrowserCommandContext, visOptions: VisOp
 	return state
 }
 
-export function createSuite(state: VisState, testPath: string, options: VisOptions) {
+export function createSuite(state: VisState, testPath: string, options: Pick<VisOptions, 'customizeSnapshotSubpath'>) {
 	const suiteId = getSuiteId(state, testPath, options)
 	return {
 		suiteId,
@@ -136,6 +141,6 @@ export function createSuite(state: VisState, testPath: string, options: VisOptio
 	}
 }
 
-export function getSuiteId(state: VisState, testPath: string, options: VisOptions) {
+export function getSuiteId(state: VisState, testPath: string, options: Pick<VisOptions, 'customizeSnapshotSubpath'>) {
 	return getSnapshotSubpath(relative(state.projectPath, testPath), options)
 }

package/src/setup/create_vis.ts

@@ -87,7 +87,7 @@ export function createVis(commands: SetupVisSuiteCommand) {
 							.map(([themeId, error]) => {
 								return `Theme \`${themeId}\` failed: ${error.message}`
 							})
-							.join('\n')}`,
+							.join('\n\n')}`,
 						)
 					}
 				}

package/src/shared/compare_image.ts

@@ -1,20 +1,69 @@
 import pixelmatch from 'pixelmatch'
+import { type Options, ssim } from 'ssim.js'
 import { convertThresholdUnit } from './convert_threshold_unit.ts'
-import type { ImageSnapshotCompareOptions } from './types.ts'
+import type { ComparisonMethod, ImageSnapshotCompareOptions } from './types.ts'
 
-export function compareImage(
+export function compareImage<M extends ComparisonMethod>(
 	img1: Uint8ClampedArray | Buffer,
 	img2: Uint8ClampedArray | Buffer,
 	output: Uint8ClampedArray | Buffer,
 	width: number,
 	height: number,
-	{ failureThreshold = 0, failureThresholdType = 'pixel', diffOptions }: ImageSnapshotCompareOptions = {},
+	options: ImageSnapshotCompareOptions<M> = {} as any,
 ) {
-	const pixelDiff = pixelmatch(img1, img2, output, width, height, diffOptions)
-	const diffAmount = convertThresholdUnit({ failureThresholdType, width, height }, pixelDiff)
+	const pixelDiff =
+		options.comparisonMethod === 'ssim'
+			? compareWithSsim(img1, img2, output, width, height, options.diffOptions)
+			: pixelmatch(img1, img2, output, width, height, options.diffOptions)
+	const diffAmount = convertThresholdUnit(
+		{ failureThresholdType: options.failureThresholdType ?? 'pixel', width, height },
+		pixelDiff,
+	)
 
 	return {
-		pass: diffAmount <= failureThreshold,
+		pass: diffAmount <= (options.failureThreshold ?? 0),
 		diffAmount,
 	}
 }
+
+/**
+ * @author This code is based on `jest-image-snapshot` implementation.
+ */
+function compareWithSsim(
+	img1: Uint8ClampedArray | Buffer,
+	img2: Uint8ClampedArray | Buffer,
+	output: Uint8ClampedArray | Buffer,
+	width: number,
+	height: number,
+	diffOptions?: Partial<Options>,
+) {
+	const newImage = { data: img1, width: width, height: height }
+	const baselineImage = { data: img2, width: width, height: height }
+	const { ssim_map, mssim } = ssim(newImage as any, baselineImage as any, {
+		ssim: 'bezkrovny',
+		...diffOptions,
+	})
+	// Converts the SSIM value to different pixels based on image width and height
+	// conforms to how pixelmatch works.
+	const diffPixels = Math.round((1 - mssim) * width * height)
+	const diffRgbaPixels = new DataView(output.buffer, output.byteOffset)
+	for (let ln = 0; ln !== height; ++ln) {
+		for (let pos = 0; pos !== width; ++pos) {
+			const rPos = ln * width + pos
+			// initial value is transparent.  We'll add in the SSIM offset.
+			// red (ff) green (00) blue (00) alpha (00)
+			const diffValue =
+				0xff000000 +
+				Math.floor(
+					0xff *
+						(1 -
+							ssim_map.data[
+								ssim_map.width * Math.round((ssim_map.height * ln) / height) +
+									Math.round((ssim_map.width * pos) / width)
+							]!),
+				)
+			diffRgbaPixels.setUint32(rPos * 4, diffValue)
+		}
+	}
+	return diffPixels
+}

package/src/shared/types.ts

@@ -1,10 +1,11 @@
 import type { PixelmatchOptions } from 'pixelmatch'
+import type { Options as SsimOptions } from 'ssim.js'
 
 export interface ImageSnapshotTimeoutOptions {
 	/**
 	 * Timeout for taking the snapshot.
 	 *
-	 * Default: 5000 ms locally, 30000 ms on CI.
+	 * Default: 30000 ms (30 seconds)
 	 */
 	timeout?: number | undefined
 }
@@ -19,11 +20,9 @@ export interface ImageSnapshotIdOptions {
 	customizeSnapshotId?: (id: string, index: number) => string
 }
 
-export interface ImageSnapshotCompareOptions {
-	/**
-	 * Custom options passed to 'pixelmatch'
-	 */
-	diffOptions?: PixelmatchOptions | undefined
+export type ComparisonMethod = 'pixel' | 'ssim'
+
+export type FailureThresholdOptions = {
 	/**
 	 * Failure threshold should measure in `pixel` or `percent`.
 	 *
@@ -37,3 +36,23 @@ export interface ImageSnapshotCompareOptions {
 	 */
 	failureThreshold?: number | undefined
 }
+
+export type SsimComparisonOptions<M = 'ssim'> = {
+	comparisonMethod: M
+	/**
+	 * Custom options passed to 'ssim'
+	 */
+	diffOptions?: Partial<SsimOptions> | undefined
+}
+export type PixelComparisonOptions<M = 'pixel'> = {
+	comparisonMethod?: M | undefined
+	/**
+	 * Custom options passed to 'pixelmatch'
+	 */
+	diffOptions?: PixelmatchOptions | undefined
+}
+
+export type ImageSnapshotCompareOptions<M extends ComparisonMethod = 'pixel'> = (M extends 'ssim'
+	? SsimComparisonOptions<M>
+	: PixelComparisonOptions<M>) &
+	FailureThresholdOptions