vitest-plugin-vis 5.1.8 → 5.2.1

package/src/overview.mdx

@@ -82,6 +82,8 @@ In each platform directory, there are 3 directories:
 - `__baselines__`: The directory for the baseline snapshots. This should be committed to the repository (except for `local`).
 - `__results__`: The directory for the current snapshots created when Vitest runs.
 - `__diffs__`: The directory for the diffs between the current snapshot and the baseline snapshot.
+  For each failing snapshot, it also holds the changed regions (`<name>.regions.json`)
+  and a review image of the changed regions (`<name>.review.png`).
 
 Because of that, you should add the following lines to your `.gitignore` file:
 

package/src/server/vis_server_context.logic.ts

@@ -69,6 +69,7 @@ export function createVisServerContext() {
 					'diffOptions',
 					'failureThreshold',
 					'failureThresholdType',
+					'reviewImage',
 					'timeout',
 				),
 				baselinePath,

package/src/shared/changed_regions.ts

@@ -0,0 +1,163 @@
+/**
+ * A rectangular area of an image, in pixels.
+ */
+export type ChangedRegion = {
+	x: number
+	y: number
+	width: number
+	height: number
+}
+
+/**
+ * How far, in pixels, the changed-pixel mask grows before it is split into regions.
+ * Changes closer than twice this distance end up in the same region.
+ */
+export const CHANGED_REGION_MARGIN = 16
+
+/**
+ * Finds the areas of an image that changed.
+ *
+ * The changed-pixel mask grows by `margin` pixels in every direction,
+ * and each connected area becomes one box.
+ * Boxes that overlap are merged.
+ *
+ * @param mask One byte per pixel; non-zero marks a changed pixel.
+ * @returns The boxes, sorted top to bottom, then left to right.
+ */
+export function findChangedRegions(
+	mask: ArrayLike<number>,
+	width: number,
+	height: number,
+	margin = CHANGED_REGION_MARGIN,
+): ChangedRegion[] {
+	const grown = growMask(mask, width, height, margin)
+	return mergeOverlappingRegions(labelRegions(grown, width, height))
+}
+
+/**
+ * Grows the mask by `margin` pixels in every direction (a square dilation),
+ * in two passes so the cost does not depend on the margin.
+ */
+function growMask(mask: ArrayLike<number>, width: number, height: number, margin: number) {
+	const horizontal = new Uint8Array(width * height)
+	const rowCounts = new Int32Array(width + 1)
+	for (let y = 0; y < height; y++) {
+		const row = y * width
+		for (let x = 0; x < width; x++) rowCounts[x + 1] = rowCounts[x]! + (mask[row + x] ? 1 : 0)
+		if (rowCounts[width] === 0) continue
+		for (let x = 0; x < width; x++) {
+			const from = Math.max(0, x - margin)
+			const to = Math.min(width, x + margin + 1)
+			if (rowCounts[to]! - rowCounts[from]! > 0) horizontal[row + x] = 1
+		}
+	}
+
+	const grown = new Uint8Array(width * height)
+	const columnCounts = new Int32Array(height + 1)
+	for (let x = 0; x < width; x++) {
+		for (let y = 0; y < height; y++) columnCounts[y + 1] = columnCounts[y]! + horizontal[y * width + x]!
+		if (columnCounts[height] === 0) continue
+		for (let y = 0; y < height; y++) {
+			const from = Math.max(0, y - margin)
+			const to = Math.min(height, y + margin + 1)
+			if (columnCounts[to]! - columnCounts[from]! > 0) grown[y * width + x] = 1
+		}
+	}
+	return grown
+}
+
+/**
+ * Returns the bounding box of each 4-connected area of the mask.
+ */
+function labelRegions(mask: Uint8Array, width: number, height: number) {
+	const visited = new Uint8Array(width * height)
+	const stack = new Int32Array(width * height)
+	const regions: ChangedRegion[] = []
+	for (let start = 0; start < mask.length; start++) {
+		if (!mask[start] || visited[start]) continue
+		let minX = width
+		let minY = height
+		let maxX = -1
+		let maxY = -1
+		let top = 0
+		stack[top++] = start
+		visited[start] = 1
+		while (top > 0) {
+			const i = stack[--top]!
+			const x = i % width
+			const y = (i - x) / width
+			if (x < minX) minX = x
+			if (x > maxX) maxX = x
+			if (y < minY) minY = y
+			if (y > maxY) maxY = y
+			if (x > 0 && mask[i - 1] && !visited[i - 1]) {
+				visited[i - 1] = 1
+				stack[top++] = i - 1
+			}
+			if (x < width - 1 && mask[i + 1] && !visited[i + 1]) {
+				visited[i + 1] = 1
+				stack[top++] = i + 1
+			}
+			if (y > 0 && mask[i - width] && !visited[i - width]) {
+				visited[i - width] = 1
+				stack[top++] = i - width
+			}
+			if (y < height - 1 && mask[i + width] && !visited[i + width]) {
+				visited[i + width] = 1
+				stack[top++] = i + width
+			}
+		}
+		regions.push({ x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 })
+	}
+	return regions
+}
+
+/**
+ * Merges boxes that overlap until no two boxes overlap.
+ *
+ * @returns The boxes, sorted top to bottom, then left to right.
+ */
+export function mergeOverlappingRegions(regions: ChangedRegion[]): ChangedRegion[] {
+	const result = regions.map((r) => ({ ...r }))
+	let merged = true
+	while (merged) {
+		merged = false
+		for (let i = 0; i < result.length; i++) {
+			for (let j = i + 1; j < result.length; j++) {
+				const a = result[i]!
+				const b = result[j]!
+				if (!overlaps(a, b)) continue
+				const x = Math.min(a.x, b.x)
+				const y = Math.min(a.y, b.y)
+				result[i] = {
+					x,
+					y,
+					width: Math.max(a.x + a.width, b.x + b.width) - x,
+					height: Math.max(a.y + a.height, b.y + b.height) - y,
+				}
+				result.splice(j, 1)
+				j = i
+				merged = true
+			}
+		}
+	}
+	return result.sort((a, b) => a.y - b.y || a.x - b.x)
+}
+
+function overlaps(a: ChangedRegion, b: ChangedRegion) {
+	return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height
+}
+
+/**
+ * Describes the regions for a failure message,
+ * e.g. `2 regions: 106x37 at (0,0), 40x20 at (300,512)`.
+ */
+export function formatChangedRegions(regions: ChangedRegion[], maxListed = 5) {
+	if (regions.length === 0) return 'no region found'
+	const listed = regions
+		.slice(0, maxListed)
+		.map((r) => `${r.width}x${r.height} at (${r.x},${r.y})`)
+		.join(', ')
+	const more = regions.length > maxListed ? `, and ${regions.length - maxListed} more` : ''
+	return `${regions.length} ${regions.length === 1 ? 'region' : 'regions'}: ${listed}${more}`
+}

package/src/shared/compare_image.ts

@@ -1,7 +1,7 @@
 import pixelmatch from 'pixelmatch'
 import { type Options, ssim } from 'ssim.js'
 import { convertThresholdUnit } from './convert_threshold_unit.ts'
-import type { ComparisonMethod, ImageSnapshotCompareOptions } from './types.ts'
+import type { ComparisonMethod, ImageSnapshotCompareOptions, PixelDiffOptions } from './types.ts'
 
 export function compareImage<M extends ComparisonMethod>(
 	img1: Uint8ClampedArray | Buffer,
@@ -26,6 +26,38 @@ export function compareImage<M extends ComparisonMethod>(
 	}
 }
 
+/**
+ * A pixel counts as changed in the SSIM comparison when its SSIM value is below this.
+ */
+export const SSIM_CHANGED_THRESHOLD = 0.95
+
+/**
+ * Returns one byte per pixel, non-zero where the pixel changed.
+ *
+ * The pixel method runs pixelmatch again in mask mode, so anti-aliased pixels are not included.
+ * The SSIM method reads the diff written by {@link compareImage} and applies {@link SSIM_CHANGED_THRESHOLD}.
+ */
+export function getChangedMask<M extends ComparisonMethod>(
+	img1: Uint8ClampedArray | Buffer,
+	img2: Uint8ClampedArray | Buffer,
+	diff: Uint8ClampedArray | Buffer,
+	width: number,
+	height: number,
+	options: ImageSnapshotCompareOptions<M> = {} as any,
+) {
+	const mask = new Uint8Array(width * height)
+	if (options.comparisonMethod === 'ssim') {
+		// `compareWithSsim()` writes `1 - ssim` to the alpha channel
+		const minAlpha = 0xff * (1 - SSIM_CHANGED_THRESHOLD)
+		for (let i = 0; i < mask.length; i++) if (diff[i * 4 + 3]! > minAlpha) mask[i] = 1
+		return mask
+	}
+	const output = new Uint8ClampedArray(width * height * 4)
+	pixelmatch(img1, img2, output, width, height, { ...(options.diffOptions as PixelDiffOptions), diffMask: true })
+	for (let i = 0; i < mask.length; i++) if (output[i * 4 + 3]) mask[i] = 1
+	return mask
+}
+
 /**
  * @author This code is based on `jest-image-snapshot` implementation.
  */

package/src/shared/constants.ts

@@ -3,3 +3,5 @@ export const SNAPSHOT_ROOT_DIR = '__vis__'
 export const BASELINE_DIR = '__baselines__'
 export const RESULT_DIR = '__results__'
 export const DIFF_DIR = '__diffs__'
+export const REVIEW_IMAGE_SUFFIX = '.review.png'
+export const CHANGED_REGIONS_SUFFIX = '.regions.json'

package/src/shared/review_image.ts

@@ -0,0 +1,180 @@
+import type { ChangedRegion } from './changed_regions.ts'
+
+/**
+ * Raw RGBA pixels, compatible with `ImageData`.
+ */
+export type PixelImage = {
+	data: Uint8ClampedArray<ArrayBuffer>
+	width: number
+	height: number
+}
+
+/**
+ * The longest edge of the review image, in pixels.
+ */
+export const REVIEW_IMAGE_MAX_EDGE = 2576
+
+/**
+ * The review image is skipped when there are more regions than this.
+ */
+export const REVIEW_IMAGE_MAX_REGIONS = 5
+
+/**
+ * The review image is skipped when the regions cover more than this share of the image.
+ */
+export const REVIEW_IMAGE_MAX_COVERAGE = 0.5
+
+const CROP_GAP = 4
+const REGION_GAP = 16
+const GAP_COLOR = [128, 128, 128, 255] as const
+const CHANGED_COLOR = [255, 0, 0, 255] as const
+
+/**
+ * Returns why a review image does not help, or `undefined` when it does.
+ */
+export function getReviewImageSkipReason({
+	baseline,
+	result,
+	regions,
+}: {
+	baseline: { width: number; height: number }
+	result: { width: number; height: number }
+	regions: ChangedRegion[]
+}) {
+	if (baseline.width !== result.width || baseline.height !== result.height) return 'the image size changed'
+	if (regions.length === 0) return 'no changed region found'
+	if (regions.length > REVIEW_IMAGE_MAX_REGIONS)
+		return `${regions.length} regions, more than ${REVIEW_IMAGE_MAX_REGIONS}`
+	const area = regions.reduce((sum, r) => sum + r.width * r.height, 0)
+	const coverage = area / (baseline.width * baseline.height)
+	if (coverage > REVIEW_IMAGE_MAX_COVERAGE) return `the regions cover ${Math.round(coverage * 100)}% of the image`
+	return undefined
+}
+
+/**
+ * Creates one image that shows, for each region, the baseline crop, the result crop, and the diff crop.
+ *
+ * A wide region places its crops top to bottom, a narrow one left to right.
+ * Regions are placed top to bottom.
+ * The diff crop shows the baseline in grayscale at full contrast with the changed pixels in red.
+ * The image is scaled down to fit {@link REVIEW_IMAGE_MAX_EDGE}.
+ *
+ * @param mask One byte per pixel of the baseline; non-zero marks a changed pixel.
+ */
+export function createReviewImage(
+	baseline: PixelImage,
+	result: PixelImage,
+	mask: ArrayLike<number>,
+	regions: ChangedRegion[],
+): PixelImage {
+	const panels = regions.map((region) => {
+		const crops = [crop(baseline, region), crop(result, region), createDiffCrop(baseline, mask, region)]
+		return region.width > region.height ? stack(crops, 'vertical', CROP_GAP) : stack(crops, 'horizontal', CROP_GAP)
+	})
+	return fitWithin(stack(panels, 'vertical', REGION_GAP), REVIEW_IMAGE_MAX_EDGE)
+}
+
+function crop(image: PixelImage, { x, y, width, height }: ChangedRegion): PixelImage {
+	const data = new Uint8ClampedArray(width * height * 4)
+	for (let row = 0; row < height; row++) {
+		const start = ((y + row) * image.width + x) * 4
+		data.set(image.data.subarray(start, start + width * 4), row * width * 4)
+	}
+	return { data, width, height }
+}
+
+function createDiffCrop(
+	image: PixelImage,
+	mask: ArrayLike<number>,
+	{ x, y, width, height }: ChangedRegion,
+): PixelImage {
+	const data = new Uint8ClampedArray(width * height * 4)
+	for (let row = 0; row < height; row++) {
+		for (let col = 0; col < width; col++) {
+			const i = (y + row) * image.width + x + col
+			const pos = (row * width + col) * 4
+			if (mask[i]) {
+				data.set(CHANGED_COLOR, pos)
+				continue
+			}
+			const src = i * 4
+			const r = image.data[src]!
+			const g = image.data[src + 1]!
+			const b = image.data[src + 2]!
+			const a = image.data[src + 3]!
+			const luma = 0.29889531 * r + 0.58662247 * g + 0.11448223 * b
+			// blend with white by the pixel's own alpha only, so the baseline is not faded
+			const gray = 255 + ((luma - 255) * a) / 255
+			data[pos] = gray
+			data[pos + 1] = gray
+			data[pos + 2] = gray
+			data[pos + 3] = 255
+		}
+	}
+	return { data, width, height }
+}
+
+function stack(images: PixelImage[], direction: 'horizontal' | 'vertical', gap: number): PixelImage {
+	const horizontal = direction === 'horizontal'
+	const gaps = gap * (images.length - 1)
+	const width = horizontal
+		? images.reduce((sum, image) => sum + image.width, gaps)
+		: Math.max(...images.map((image) => image.width))
+	const height = horizontal
+		? Math.max(...images.map((image) => image.height))
+		: images.reduce((sum, image) => sum + image.height, gaps)
+	const data = new Uint8ClampedArray(width * height * 4)
+	for (let i = 0; i < data.length; i += 4) data.set(GAP_COLOR, i)
+
+	let offset = 0
+	for (const image of images) {
+		const x = horizontal ? offset : 0
+		const y = horizontal ? 0 : offset
+		for (let row = 0; row < image.height; row++) {
+			data.set(image.data.subarray(row * image.width * 4, (row + 1) * image.width * 4), ((y + row) * width + x) * 4)
+		}
+		offset += (horizontal ? image.width : image.height) + gap
+	}
+	return { data, width, height }
+}
+
+/**
+ * Scales the image down, averaging the pixels each target pixel covers,
+ * so its longest edge is at most `maxEdge`.
+ */
+function fitWithin(image: PixelImage, maxEdge: number): PixelImage {
+	const scale = maxEdge / Math.max(image.width, image.height)
+	if (scale >= 1) return image
+
+	const width = Math.max(1, Math.round(image.width * scale))
+	const height = Math.max(1, Math.round(image.height * scale))
+	const data = new Uint8ClampedArray(width * height * 4)
+	for (let y = 0; y < height; y++) {
+		const fromY = Math.floor((y * image.height) / height)
+		const toY = Math.max(fromY + 1, Math.floor(((y + 1) * image.height) / height))
+		for (let x = 0; x < width; x++) {
+			const fromX = Math.floor((x * image.width) / width)
+			const toX = Math.max(fromX + 1, Math.floor(((x + 1) * image.width) / width))
+			let r = 0
+			let g = 0
+			let b = 0
+			let a = 0
+			for (let sy = fromY; sy < toY; sy++) {
+				for (let sx = fromX; sx < toX; sx++) {
+					const src = (sy * image.width + sx) * 4
+					r += image.data[src]!
+					g += image.data[src + 1]!
+					b += image.data[src + 2]!
+					a += image.data[src + 3]!
+				}
+			}
+			const count = (toY - fromY) * (toX - fromX)
+			const pos = (y * width + x) * 4
+			data[pos] = r / count
+			data[pos + 1] = g / count
+			data[pos + 2] = b / count
+			data[pos + 3] = a / count
+		}
+	}
+	return { data, width, height }
+}

package/src/shared/types.ts

@@ -21,6 +21,22 @@ export interface ImageSnapshotKeyOptions {
 	snapshotKey?: string | undefined
 }
 
+export interface ReviewImageOptions {
+	/**
+	 * When the snapshot mismatches, write a review image next to the diff.
+	 *
+	 * The review image places the baseline, result, and diff crops of each changed region side by side,
+	 * so a person or an agent can see what changed without opening the full images.
+	 * It is skipped when cropping does not help:
+	 * the image size changed, there are many regions, or the regions cover most of the image.
+	 *
+	 * The changed regions are written as JSON next to the diff either way.
+	 *
+	 * @default true
+	 */
+	reviewImage?: boolean | undefined
+}
+
 export type ComparisonMethod = 'pixel' | 'ssim'
 
 export type FailureThresholdOptions = {
@@ -90,7 +106,8 @@ export type ImageSnapshotSubjectOptions = {
 }
 export type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTimeoutOptions &
 	ImageSnapshotKeyOptions &
-	ImageSnapshotCompareOptions<M> & {
+	ImageSnapshotCompareOptions<M> &
+	ReviewImageOptions & {
 		/**
 		 * Expect the matcher to fail.
 		 * If it passes, it will throw an error with details.
@@ -152,11 +169,13 @@ export type ImageSnapshotComparisonInfo = {
 	diff?: string | undefined
 } & ImageSnapshotTimeoutOptions &
 	FailureThresholdOptions &
+	ReviewImageOptions &
 	(SsimComparisonOptions | PixelComparisonOptions)
 
 export type MatchImageSnapshotOptions = ImageSnapshotTimeoutOptions &
 	ImageSnapshotCompareOptions<any> &
-	ImageSnapshotKeyOptions & {
+	ImageSnapshotKeyOptions &
+	ReviewImageOptions & {
 		/**
 		 * When `true`, write a missing baseline on first run (see {@link ToMatchImageSnapshotOptions} `createMissingBaseline`).
 		 */