diff.ts

Blame: the commit that last changed each line · file · history

`88e406aa` 2026-04-13 Pavel Safronov	1	/**
	2	* scripts/diff.ts
	3	*
	4	* Compares screenshots/composite.png against screenshots/golden/composite.png
	5	* using pixelmatch.
	6	*
	7	* Exit codes:
	8	* 0 — images match (within threshold)
	9	* 1 — images differ (above threshold) — diff saved to screenshots/diff.png
	10	* 2 — golden file missing (run `pnpm screenshot --update` first)
	11	*
	12	* Usage (standalone):
	13	* pnpm diff-screenshots
	14	*
	15	* The screenshot.ts script calls compareWithGolden() directly.
	16	*/
	17
	18	import pixelmatch from 'pixelmatch'
	19	import { PNG } from 'pngjs'
	20	import { existsSync, readFileSync, writeFileSync } from 'node:fs'
	21	import { join } from 'node:path'
	22	import { fileURLToPath } from 'node:url'
	23
	24	const ROOT = fileURLToPath(new URL('..', import.meta.url))
	25	const OUT_DIR = join(ROOT, 'screenshots')
	26	const DIFF_FILE = join(OUT_DIR, 'diff.png')
	27
	28	/** Fraction of pixels that must change before we consider the images different. */
	29	const THRESHOLD = 0.005 // 0.5 %
	30
	31	/**
	32	* Compare `composite.png` against the golden copy.
	33	* Returns `null` when there is no golden to compare against.
	34	* Otherwise returns an object with the diff result.
	35	*/
	36	export async function compareWithGolden(): Promise<{
	37	changed: number
	38	total: number
	39	pct: number
	40	pass: boolean
	41	diffFile: string \| null
	42	} \| null> {
	43	const current = join(OUT_DIR, 'composite.png')
	44	const golden = join(OUT_DIR, 'golden', 'composite.png')
	45
	46	if (!existsSync(golden)) return null
	47	if (!existsSync(current)) throw new Error(`Missing composite: ${current}`)
	48
	49	const imgA = PNG.sync.read(readFileSync(golden))
	50	const imgB = PNG.sync.read(readFileSync(current))
	51
	52	// If dimensions differ, treat every pixel as changed
	53	if (imgA.width !== imgB.width \|\| imgA.height !== imgB.height) {
	54	const total = Math.max(imgA.width * imgA.height, imgB.width * imgB.height)
	55	return { changed: total, total, pct: 1, pass: false, diffFile: null }
	56	}
	57
	58	const { width, height } = imgA
	59	const diff = new PNG({ width, height })
	60
	61	const changed = pixelmatch(
	62	imgA.data, imgB.data, diff.data,
	63	width, height,
	64	{ threshold: 0.1, alpha: 0.3 },
	65	)
	66
	67	const total = width * height
	68	const pct = changed / total
	69	const pass = pct <= THRESHOLD
	70
	71	let diffFile: string \| null = null
	72	if (!pass) {
	73	writeFileSync(DIFF_FILE, PNG.sync.write(diff))
	74	diffFile = DIFF_FILE
	75	}
	76
	77	return { changed, total, pct, pass, diffFile }
	78	}
	79
	80	// ── Run standalone ────────────────────────────────────────────────────────
	81	// Only execute when this file is the entry point, not when imported as a module.
	82	const isMain = process.argv[1] &&
	83	(process.argv[1].endsWith('diff.ts') \|\| process.argv[1].endsWith('diff.js'))
	84
	85	if (!isMain) { /* imported — skip standalone logic */ }
	86	else {
	87
	88	const result = await compareWithGolden()
	89
	90	if (result === null) {
	91	console.log('No golden composite found.')
	92	console.log('Run `pnpm screenshot --update` to create one.')
	93	process.exit(2)
	94	}
	95
	96	const pctStr = (result.pct * 100).toFixed(2)
	97	const thStr = (THRESHOLD * 100).toFixed(1)
	98
	99	if (result.pass) {
	100	console.log(`✓ Images match (${pctStr}% changed, threshold ${thStr}%)`)
	101	process.exit(0)
	102	} else {
	103	console.error(`✗ Images differ: ${pctStr}% of pixels changed (threshold ${thStr}%)`)
	104	if (result.diffFile) {
	105	console.error(` Diff saved to ${result.diffFile}`)
	106	}
	107	console.error(' Run `pnpm screenshot --update` to accept the new output as golden.')
	108	process.exit(1)
	109	}
	110
	111	} // end isMain