vitest-plugin-vis 1.0.5 → 1.2.0

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/_assertions.ts

@@ -0,0 +1,18 @@
+import { isAbsolute } from 'pathe'
+import type { RequiredPick } from 'type-plus'
+import type { BrowserCommandContext } from 'vitest/node'
+
+export function assertTestPathDefined(
+	context: BrowserCommandContext,
+	commandName: string,
+): asserts context is RequiredPick<BrowserCommandContext, 'testPath'> {
+	if (!context.testPath) {
+		throw new Error(`'commands.${commandName}' requires testPath to be defined`)
+	}
+}
+
+export function assertIsRelativePath(relativeFilePath: string, propName: string) {
+	if (isAbsolute(relativeFilePath)) {
+		throw new Error(`'${propName}' must be a relative path`)
+	}
+}

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/has_image_snapshot.ts

@@ -1,5 +1,6 @@
 import type { BrowserCommand } from 'vitest/node'
 import { visContext } from '../vis_context.ts'
+import { assertTestPathDefined } from './_assertions.ts'
 
 export interface HasImageSnapshotCommand {
 	hasImageSnapshot(taskId: string, snapshotId?: string | undefined): Promise<boolean>
@@ -10,9 +11,7 @@ export const hasImageSnapshot: BrowserCommand<[taskId: string, snapshotId?: stri
 	taskId,
 	snapshotId,
 ) => {
-	if (!context.testPath) {
-		throw new Error('Cannot take snapshot without testPath')
-	}
+	assertTestPathDefined(context, 'hasImageSnapshot')
 
 	return visContext.hasImageSnapshot(context.testPath, taskId, snapshotId)
 }

package/src/server/commands/image_snapshot_next_index.ts

@@ -1,5 +1,6 @@
 import type { BrowserCommand } from 'vitest/node'
 import { visContext } from '../vis_context.ts'
+import { assertTestPathDefined } from './_assertions.ts'
 
 export interface ImageSnapshotNextIndexCommand {
 	/**
@@ -9,9 +10,7 @@ export interface ImageSnapshotNextIndexCommand {
 }
 
 export const imageSnapshotNextIndex: BrowserCommand<[taskId: string]> = async (context, taskId) => {
-	if (!context.testPath) {
-		throw new Error('Cannot take snapshot without testPath')
-	}
+	assertTestPathDefined(context, 'imageSnapshotNextIndex')
 
 	return visContext.getTaskCount(context.testPath, taskId)
 }

package/src/server/commands/match_image_snapshot.ts

@@ -1,10 +1,10 @@
 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 { compareImage } from '../../shared/compare_image.ts'
 import { getMaxSize } from '../../shared/get_max_size.ts'
 import { isSameSize } from '../../shared/is_same_size.ts'
 import type {
@@ -12,10 +12,10 @@ 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'
+import { assertTestPathDefined } from './_assertions.ts'
 
 export interface MatchImageSnapshotCommand {
 	matchImageSnapshot: (
@@ -38,9 +38,7 @@ export interface MatchImageSnapshotOptions
 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')
-	}
+	assertTestPathDefined(context, 'matchImageSnapshot')
 
 	// vitest:browser passes in `null` when not defined
 	if (!options) options = {}
@@ -57,12 +55,20 @@ 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)
-
-	const { pass, diffAmount, diffImage } = compareImage(baselineAlignedImage, resultAlignedImage, options)
+	const { width, height } = baselineAlignedImage
+	const diffImage = new PNG({ width, height })
+	const { pass, diffAmount } = compareImage(
+		baselineAlignedImage.data,
+		resultAlignedImage.data,
+		diffImage.data,
+		width,
+		height,
+		options,
+	)
 	if (pass) {
 		if (sizeNotChanged(baselineImage, baselineAlignedImage) && sizeNotChanged(resultImage, resultAlignedImage)) {
 			return
@@ -103,41 +109,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,54 @@
+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 { assertTestPathDefined } from './_assertions.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) => {
+	assertTestPathDefined(context, 'prepareImageSnapshotComparison')
+
+	// 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/setup_vis_suite.ts

@@ -1,5 +1,6 @@
 import type { BrowserCommand } from 'vitest/node'
 import { visContext } from '../vis_context.ts'
+import { assertTestPathDefined } from './_assertions.ts'
 
 export interface SetupVisSuiteCommand {
 	/**
@@ -13,5 +14,7 @@ export interface SetupVisSuiteCommand {
 }
 
 export const setupVisSuite: BrowserCommand<[]> = async (context) => {
+	assertTestPathDefined(context, 'setupVisSuite')
+
 	await visContext.setupSuite(context)
 }

package/src/server/commands/write_image_snapshot.ts

@@ -0,0 +1,26 @@
+import { mkdirp } from 'mkdirp'
+import { dirname, isAbsolute } from 'pathe'
+import type { BrowserCommand } from 'vitest/node'
+import { file } from '../file.ts'
+import { assertIsRelativePath } from './_assertions.ts'
+
+export interface WriteImageSnapshotCommand {
+	/**
+	 * Writes the image snapshot to the file system.
+	 * @param relativeFilePath The file path to write the image snapshot to.
+	 * It is relative to the project root.
+	 * @param imageBase64 The base64 encoded image.
+	 */
+	writeImageSnapshot(relativeFilePath: string, imageBase64: string): Promise<void>
+}
+
+export const writeImageSnapshot: BrowserCommand<[relativeFilePath: string, imageBase64: string]> = async (
+	_,
+	relativeFilePath,
+	imageBase64,
+) => {
+	assertIsRelativePath(relativeFilePath, 'relativeFilePath')
+
+	await mkdirp(dirname(relativeFilePath))
+	await file.writeFile(relativeFilePath, imageBase64, { 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/server/vis_context.logic.ts

@@ -17,7 +17,7 @@ export type PartialBrowserCommandContext = {
 			hookTimeout: number
 		}
 	}
-	testPath: string | undefined
+	testPath: string
 }
 
 export function createVisContext() {
@@ -51,7 +51,7 @@ export function createVisContext() {
 				await globalStateReady
 			}
 
-			const { suiteId, suite } = createSuite(state, context.testPath!, visOptions)
+			const { suiteId, suite } = createSuite(state, context.testPath, visOptions)
 			state.suites[suiteId] = suite
 			await Promise.allSettled([ctx.rimraf(suite.diffDir), ctx.rimraf(suite.resultDir)])
 		},

package/src/shared/compare_image.ts

@@ -0,0 +1,20 @@
+import pixelmatch from 'pixelmatch'
+import { convertThresholdUnit } from './convert_threshold_unit.ts'
+import type { ImageSnapshotCompareOptions } from './types.ts'
+
+export function compareImage(
+	img1: Uint8ClampedArray | Buffer,
+	img2: Uint8ClampedArray | Buffer,
+	output: Uint8ClampedArray | Buffer,
+	width: number,
+	height: number,
+	{ failureThreshold = 0, failureThresholdType = 'pixel', diffOptions }: ImageSnapshotCompareOptions = {},
+) {
+	const pixelDiff = pixelmatch(img1, img2, output, width, height, diffOptions)
+	const diffAmount = convertThresholdUnit({ failureThresholdType, width, height }, pixelDiff)
+
+	return {
+		pass: diffAmount <= failureThreshold,
+		diffAmount,
+	}
+}

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}`)
 	}
 }

package/src/testing/stubBrowserCommandContext.ts

@@ -0,0 +1,4 @@
+import { stub } from 'type-plus'
+import type { BrowserCommandContext } from 'vitest/node'
+
+export const stubBrowserCommandContext = stub.build<BrowserCommandContext>({})

package/src/testing.ts

@@ -1 +1,2 @@
 export * from './testing/constants.ts'
+export * from './testing/stubBrowserCommandContext.ts'

package/esm/client/expect/to_match_image_snapshot.logic.d.ts

@@ -1,2 +0,0 @@
-export declare function parseImageSnapshotSubject(subject: any): any;
-//# sourceMappingURL=to_match_image_snapshot.logic.d.ts.map

package/esm/client/expect/to_match_image_snapshot.logic.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"to_match_image_snapshot.logic.d.ts","sourceRoot":"","sources":["../../../src/client/expect/to_match_image_snapshot.logic.ts"],"names":[],"mappings":"AAGA,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,GAAG,OAOrD"}

package/esm/client/expect/to_match_image_snapshot.logic.js

@@ -1,11 +0,0 @@
-import { isBase64String } from "../../shared/base64.js";
-import { convertElementToCssSelector } from "../selector.js";
-export function parseImageSnapshotSubject(subject) {
-    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}`);
-}

package/esm/server/commands/is_ci.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=is_ci.d.ts.map

package/esm/server/commands/is_ci.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is_ci.d.ts","sourceRoot":"","sources":["../../../src/server/commands/is_ci.ts"],"names":[],"mappings":""}

package/esm/server/commands/is_ci.js

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

package/esm/server/compare_image.d.ts

@@ -1,8 +0,0 @@
-import { PNG } from 'pngjs';
-import type { ImageSnapshotCompareOptions } from '../shared/types.ts';
-export declare function compareImage(baselineImage: PNG, resultImage: PNG, { failureThreshold, failureThresholdType, diffOptions }?: ImageSnapshotCompareOptions): {
-    pass: boolean;
-    diffAmount: number;
-    diffImage: PNG;
-};
-//# sourceMappingURL=compare_image.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"compare_image.d.ts","sourceRoot":"","sources":["../../src/server/compare_image.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAE3B,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAA;AAErE,wBAAgB,YAAY,CAC3B,aAAa,EAAE,GAAG,EAClB,WAAW,EAAE,GAAG,EAChB,EAAE,gBAAoB,EAAE,oBAA8B,EAAE,WAAW,EAAE,GAAE,2BAAgC;;;;EAyBvG"}

package/esm/server/compare_image.js

@@ -1,16 +0,0 @@
-import pixelmatch from 'pixelmatch';
-import { PNG } from 'pngjs';
-import { convertThresholdUnit } from "../shared/convert_threshold_unit.js";
-export function compareImage(baselineImage, resultImage, { failureThreshold = 0, failureThresholdType = 'pixel', diffOptions } = {}) {
-    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/client/expect/to_match_image_snapshot.logic.ts

@@ -1,11 +0,0 @@
-import { isBase64String } from '../../shared/base64.ts'
-import { convertElementToCssSelector } from '../selector.ts'
-
-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}`,
-	)
-}

package/src/server/commands/is_ci.ts

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

package/src/server/compare_image.ts

@@ -1,34 +0,0 @@
-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,
-	}
-}