similarbuild 0.1.0

package/templates/skills/sb-compare-visual/scripts/tests/test-compare-visual.mjs

@@ -0,0 +1,626 @@
+#!/usr/bin/env node
+// test-compare-visual.mjs — Smoke tests for compare-visual.mjs.
+// Covers: --help, arg validation, missing files. Plus optional integration
+// tests with on-the-fly generated PNG fixtures (skip gracefully if sharp /
+// pixelmatch / pngjs aren't installed).
+//
+// No chromium required → coverage can be deeper than the playwright-gated skills.
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve, join } from 'node:path'
+import { mkdir, writeFile, readFile, rm, stat } from 'node:fs/promises'
+import { strict as assert } from 'node:assert'
+import { tmpdir } from 'node:os'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const SCRIPT = resolve(here, '..', 'compare-visual.mjs')
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  try {
+    const result = fn()
+    if (result && typeof result.then === 'function') {
+      return result.then(
+        () => {
+          process.stdout.write(`ok - ${name}\n`)
+          passed++
+        },
+        (err) => {
+          process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+          failed++
+        },
+      )
+    }
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+function skip(name, reason) {
+  process.stdout.write(`ok - ${name} # SKIP ${reason}\n`)
+  passed++
+}
+
+function run(args) {
+  return spawnSync('node', [SCRIPT, ...args], { encoding: 'utf8' })
+}
+
+// ─── help + arg validation (no deps required) ──────────────────────────────
+
+test('--help exits 0 and prints usage', () => {
+  const r = run(['--help'])
+  assert.equal(r.status, 0, `exit code was ${r.status}\n${r.stderr}`)
+  assert.match(r.stdout, /compare-visual\.mjs/)
+  assert.match(r.stdout, /--live-screenshot/)
+  assert.match(r.stdout, /--build-screenshot/)
+  assert.match(r.stdout, /--output-dir/)
+  assert.match(r.stdout, /--threshold/)
+})
+
+test('missing --live-screenshot exits 2', () => {
+  const r = run(['--build-screenshot', '/tmp/x.png', '--output-dir', '/tmp/x'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --live-screenshot/)
+})
+
+test('missing --build-screenshot exits 2', () => {
+  const r = run(['--live-screenshot', '/tmp/x.png', '--output-dir', '/tmp/x'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --build-screenshot/)
+})
+
+test('missing --output-dir exits 2', () => {
+  const r = run(['--live-screenshot', '/tmp/x.png', '--build-screenshot', '/tmp/y.png'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --output-dir/)
+})
+
+test('non-numeric --threshold exits 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/x.png',
+    '--build-screenshot', '/tmp/y.png',
+    '--output-dir', '/tmp/x',
+    '--threshold', 'abc',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--threshold must be a number/)
+})
+
+test('--threshold > 100 exits 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/x.png',
+    '--build-screenshot', '/tmp/y.png',
+    '--output-dir', '/tmp/x',
+    '--threshold', '150',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--threshold must be a number/)
+})
+
+test('--pixel-threshold > 1 exits 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/x.png',
+    '--build-screenshot', '/tmp/y.png',
+    '--output-dir', '/tmp/x',
+    '--pixel-threshold', '5',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--pixel-threshold must be a number/)
+})
+
+test('--help mentions --crop-live-bbox', () => {
+  const r = run(['--help'])
+  assert.equal(r.status, 0)
+  assert.match(r.stdout, /--crop-live-bbox/)
+  assert.match(r.stdout, /--crop-live-dpr/)
+})
+
+test('--crop-live-bbox malformed exits 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/x.png',
+    '--build-screenshot', '/tmp/y.png',
+    '--output-dir', '/tmp/x',
+    '--crop-live-bbox', '0,0,abc,10',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--crop-live-bbox/)
+})
+
+test('--crop-live-bbox wrong arity exits 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/x.png',
+    '--build-screenshot', '/tmp/y.png',
+    '--output-dir', '/tmp/x',
+    '--crop-live-bbox', '0,0,10',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--crop-live-bbox/)
+})
+
+test('--crop-live-bbox negative dims exit 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/x.png',
+    '--build-screenshot', '/tmp/y.png',
+    '--output-dir', '/tmp/x',
+    '--crop-live-bbox', '0,0,-5,10',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--crop-live-bbox/)
+})
+
+test('--help mentions --crop-build-bbox', () => {
+  const r = run(['--help'])
+  assert.equal(r.status, 0)
+  assert.match(r.stdout, /--crop-build-bbox/)
+  assert.match(r.stdout, /--crop-build-dpr/)
+})
+
+test('--crop-build-bbox malformed exits 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/x.png',
+    '--build-screenshot', '/tmp/y.png',
+    '--output-dir', '/tmp/x',
+    '--crop-build-bbox', '0,0,abc,10',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--crop-build-bbox/)
+})
+
+test('--crop-build-bbox wrong arity exits 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/x.png',
+    '--build-screenshot', '/tmp/y.png',
+    '--output-dir', '/tmp/x',
+    '--crop-build-bbox', '0,0,10',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--crop-build-bbox/)
+})
+
+test('missing live-screenshot file exits 2', () => {
+  const r = run([
+    '--live-screenshot', '/tmp/sb-compare-does-not-exist-abc.png',
+    '--build-screenshot', '/tmp/sb-compare-does-not-exist-xyz.png',
+    '--output-dir', '/tmp/sb-compare-test-out',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /not found/)
+})
+
+// ─── integration: generate PNG fixtures + run end-to-end ────────────────────
+// These tests are valuable BECAUSE the script has no chromium dep — we can
+// cover the full pixel + token + exit-code path without mocking the world.
+
+let PNG = null
+let pixelmatchAvailable = false
+let sharpAvailable = false
+try {
+  ;({ PNG } = await import('pngjs'))
+} catch {}
+try {
+  await import('pixelmatch')
+  pixelmatchAvailable = true
+} catch {}
+try {
+  await import('sharp')
+  sharpAvailable = true
+} catch {}
+
+const integrationReady = PNG && pixelmatchAvailable && sharpAvailable
+
+function makePng(width, height, rgba) {
+  const png = new PNG({ width, height })
+  for (let i = 0; i < width * height; i++) {
+    png.data[i * 4 + 0] = rgba[0]
+    png.data[i * 4 + 1] = rgba[1]
+    png.data[i * 4 + 2] = rgba[2]
+    png.data[i * 4 + 3] = rgba[3] ?? 255
+  }
+  return PNG.sync.write(png)
+}
+
+const TMPROOT = join(tmpdir(), `sb-compare-visual-test-${Date.now()}`)
+
+if (!integrationReady) {
+  skip('integration: identical PNGs → diffPercent 0, exit 0', 'sharp/pixelmatch/pngjs not installed')
+  skip('integration: opposite-color PNGs → diffPercent 100, exit 3', 'sharp/pixelmatch/pngjs not installed')
+  skip('integration: differing dimensions are padded, not resized', 'sharp/pixelmatch/pngjs not installed')
+  skip('integration: token cross-check populates structuredDiffs', 'sharp/pixelmatch/pngjs not installed')
+  skip('integration: passes when below custom threshold', 'sharp/pixelmatch/pngjs not installed')
+} else {
+  await mkdir(TMPROOT, { recursive: true })
+
+  const RED = [255, 0, 0, 255]
+  const BLUE = [0, 0, 255, 255]
+
+  await test('integration: identical PNGs → diffPercent 0, exit 0', async () => {
+    const dir = join(TMPROOT, 'identical')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(8, 8, RED))
+    await writeFile(build, makePng(8, 8, RED))
+    const out = join(dir, 'out')
+    const r = run(['--live-screenshot', live, '--build-screenshot', build, '--output-dir', out])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.passed, true)
+    assert.equal(json.diffPixels, 0)
+    assert.equal(json.diffPercent, 0)
+    const diffMapStat = await stat(join(out, 'diff-map.png'))
+    assert.ok(diffMapStat.size > 0, 'diff-map.png should be written even when identical')
+    const reportRaw = await readFile(join(out, 'report.json'), 'utf8')
+    const report = JSON.parse(reportRaw)
+    assert.equal(report.diffPixels, 0)
+  })
+
+  await test('integration: opposite-color PNGs → diffPercent 100, exit 3', async () => {
+    const dir = join(TMPROOT, 'opposite')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(8, 8, RED))
+    await writeFile(build, makePng(8, 8, BLUE))
+    const out = join(dir, 'out')
+    const r = run(['--live-screenshot', live, '--build-screenshot', build, '--output-dir', out])
+    assert.equal(r.status, 3, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.passed, false)
+    assert.equal(json.diffPixels, 64)
+    assert.equal(json.totalPixels, 64)
+    assert.equal(json.diffPercent, 100)
+  })
+
+  await test('integration: differing dimensions are padded, not resized', async () => {
+    // live 8x8 red; build 16x8 red. Padding the live to 16x8 with transparent
+    // pixels means the right half is "build has content, live doesn't" — every
+    // right-half pixel diffs. Resize would scale and bleed red across the
+    // whole image (nearly zero diff). We assert ~50% diff to prove padding.
+    const dir = join(TMPROOT, 'dimensions')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(8, 8, RED))
+    await writeFile(build, makePng(16, 8, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--threshold', '90',
+    ])
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.dimensions.canvas.width, 16)
+    assert.equal(json.dimensions.canvas.height, 8)
+    // The right half of `live` is transparent padding vs solid red on build → diff.
+    assert.ok(json.diffPercent >= 40 && json.diffPercent <= 60, `expected ~50% diff, got ${json.diffPercent}`)
+  })
+
+  await test('integration: token cross-check populates structuredDiffs', async () => {
+    const dir = join(TMPROOT, 'tokens')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(8, 8, RED))
+    await writeFile(build, makePng(8, 8, RED))
+    const tokensLive = join(dir, 'tokens-live.json')
+    const tokensBuild = join(dir, 'tokens-build.json')
+    await writeFile(tokensLive, JSON.stringify({
+      tokens: { h1: { present: true, 'font-size': '27px', color: '#d8112a' } },
+      geometry: { viewportOverflow: false, totalHeight: 1000 },
+    }))
+    await writeFile(tokensBuild, JSON.stringify({
+      tokens: { h1: { present: true, 'font-size': '24px', color: '#d82a11' } },
+      geometry: { viewportOverflow: false, totalHeight: 1000 },
+    }))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--tokens-live', tokensLive,
+      '--tokens-build', tokensBuild,
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.tokenDiff.compared, true)
+    assert.equal(json.tokenDiff.count, 2)
+    // Both diffs are 'high' (font-size delta > 1px, color hex changed)
+    assert.ok(json.structuredDiffs.length === 2)
+    assert.ok(json.structuredDiffs.every((d) => d.severity === 'high'))
+  })
+
+  await test('integration: passes when below custom threshold', async () => {
+    const dir = join(TMPROOT, 'threshold')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    // 100x100 red live, 100x100 mostly-red build with one diff strip
+    await writeFile(live, makePng(100, 100, RED))
+    const buildPng = new PNG({ width: 100, height: 100 })
+    for (let i = 0; i < 100 * 100; i++) {
+      // 1% blue: just the first row (100 of 10000 pixels = 1%)
+      const isBlue = i < 100
+      buildPng.data[i * 4 + 0] = isBlue ? 0 : 255
+      buildPng.data[i * 4 + 1] = 0
+      buildPng.data[i * 4 + 2] = isBlue ? 255 : 0
+      buildPng.data[i * 4 + 3] = 255
+    }
+    await writeFile(build, PNG.sync.write(buildPng))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--threshold', '5',
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.passed, true)
+    assert.ok(json.diffPercent < 5, `diffPercent ${json.diffPercent} should be < 5`)
+  })
+
+  await test('integration: --crop-live-bbox crops live before diff', async () => {
+    // 30x10 live: rows 0-9 are red. Build is 10x10 red. Without crop, padding
+    // makes ~67% of pixels (cols 10-29) transparent-vs-red → big diff. With
+    // --crop-live-bbox 0,0,10,10 dpr=1, live becomes 10x10 red → 0% diff.
+    const dir = join(TMPROOT, 'crop-bbox')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(30, 10, RED))
+    await writeFile(build, makePng(10, 10, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-live-bbox', '0,0,10,10',
+      '--crop-live-dpr', '1',
+      '--threshold', '5',
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.passed, true)
+    assert.equal(json.diffPixels, 0)
+    assert.equal(json.dimensions.live.width, 10, 'live should be cropped to 10x10')
+    assert.equal(json.dimensions.live.height, 10)
+    assert.ok(json.croppedLiveTo, 'croppedLiveTo should be populated')
+    assert.equal(json.croppedLiveTo.w, 10)
+    assert.equal(json.croppedLiveTo.h, 10)
+    assert.equal(json.croppedLiveTo.dpr, 1)
+    const cropStat = await stat(join(out, 'live-cropped.png'))
+    assert.ok(cropStat.size > 0, 'live-cropped.png should be written')
+  })
+
+  await test('integration: --crop-live-bbox with dpr=3 multiplies coordinates', async () => {
+    // 30x30 live, build 9x9. Bbox 0,0,3,3 with dpr=3 → crop to 9x9 → 0% diff.
+    const dir = join(TMPROOT, 'crop-dpr')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(30, 30, RED))
+    await writeFile(build, makePng(9, 9, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-live-bbox', '0,0,3,3',
+      '--crop-live-dpr', '3',
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.dimensions.live.width, 9, 'dpr should multiply bbox by 3')
+    assert.equal(json.dimensions.live.height, 9)
+    assert.equal(json.croppedLiveTo.screenshotPx.width, 9)
+    assert.equal(json.croppedLiveTo.screenshotPx.height, 9)
+  })
+
+  await test('integration: --crop-live-bbox clamps when bbox extends past edge', async () => {
+    // Live is 10x10, bbox 0,0,20,20 dpr=1 → clamp to 10x10. No error, just clamp.
+    const dir = join(TMPROOT, 'crop-clamp')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(10, 10, RED))
+    await writeFile(build, makePng(10, 10, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-live-bbox', '0,0,20,20',
+      '--crop-live-dpr', '1',
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.dimensions.live.width, 10)
+    assert.equal(json.dimensions.live.height, 10)
+    assert.equal(json.croppedLiveTo.screenshotPx.width, 10, 'width should be clamped')
+    assert.equal(json.croppedLiveTo.screenshotPx.height, 10)
+  })
+
+  await test('integration: --crop-live-bbox entirely outside exits 1', async () => {
+    const dir = join(TMPROOT, 'crop-outside')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(10, 10, RED))
+    await writeFile(build, makePng(10, 10, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-live-bbox', '50,50,10,10',
+      '--crop-live-dpr', '1',
+    ])
+    assert.equal(r.status, 1, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    assert.match(r.stderr, /entirely outside/)
+  })
+
+  await test('integration: omitting --crop-live-bbox leaves croppedLiveTo null', async () => {
+    const dir = join(TMPROOT, 'crop-null')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(10, 10, RED))
+    await writeFile(build, makePng(10, 10, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+    ])
+    assert.equal(r.status, 0)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.croppedLiveTo, null)
+    assert.equal(json.croppedBuildTo, null)
+  })
+
+  await test('integration: --crop-build-bbox crops build before diff', async () => {
+    // 10x10 live, 10x30 build (build has dead viewport space below). Without
+    // crop-build, padding live makes ~67% diff. With crop-build 0,0,10,10
+    // dpr=1, build becomes 10x10 → 0% diff. Symmetric of crop-live.
+    const dir = join(TMPROOT, 'crop-build-bbox')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(10, 10, RED))
+    await writeFile(build, makePng(10, 30, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-build-bbox', '0,0,10,10',
+      '--crop-build-dpr', '1',
+      '--threshold', '5',
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.passed, true)
+    assert.equal(json.diffPixels, 0)
+    assert.equal(json.dimensions.build.width, 10)
+    assert.equal(json.dimensions.build.height, 10)
+    assert.ok(json.croppedBuildTo)
+    assert.equal(json.croppedBuildTo.w, 10)
+    assert.equal(json.croppedBuildTo.h, 10)
+    const cropStat = await stat(join(out, 'build-cropped.png'))
+    assert.ok(cropStat.size > 0, 'build-cropped.png should be written')
+  })
+
+  await test('integration: --crop-build-bbox with dpr=3 multiplies coordinates', async () => {
+    // 30x30 build, live 9x9. Bbox 0,0,3,3 dpr=3 → crop build to 9x9 → 0% diff.
+    const dir = join(TMPROOT, 'crop-build-dpr')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(9, 9, RED))
+    await writeFile(build, makePng(30, 30, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-build-bbox', '0,0,3,3',
+      '--crop-build-dpr', '3',
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.dimensions.build.width, 9, 'dpr should multiply build bbox by 3')
+    assert.equal(json.dimensions.build.height, 9)
+    assert.equal(json.croppedBuildTo.screenshotPx.width, 9)
+    assert.equal(json.croppedBuildTo.screenshotPx.height, 9)
+  })
+
+  await test('integration: --crop-build-bbox clamps when bbox extends past edge', async () => {
+    const dir = join(TMPROOT, 'crop-build-clamp')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(10, 10, RED))
+    await writeFile(build, makePng(10, 10, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-build-bbox', '0,0,20,20',
+      '--crop-build-dpr', '1',
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.croppedBuildTo.screenshotPx.width, 10)
+    assert.equal(json.croppedBuildTo.screenshotPx.height, 10)
+  })
+
+  await test('integration: --crop-build-bbox entirely outside exits 1', async () => {
+    const dir = join(TMPROOT, 'crop-build-outside')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(10, 10, RED))
+    await writeFile(build, makePng(10, 10, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-build-bbox', '50,50,10,10',
+      '--crop-build-dpr', '1',
+    ])
+    assert.equal(r.status, 1, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    assert.match(r.stderr, /entirely outside/)
+  })
+
+  await test('integration: both --crop-live-bbox and --crop-build-bbox apply together', async () => {
+    // 30x30 live, 30x30 build, both red. Crop live to 0,0,10,10 dpr=1, crop
+    // build to 0,0,10,10 dpr=1 → both 10x10 red → 0% diff. Verifies the two
+    // crops are independent and both write debug PNGs.
+    const dir = join(TMPROOT, 'crop-both')
+    await mkdir(dir, { recursive: true })
+    const live = join(dir, 'live.png')
+    const build = join(dir, 'build.png')
+    await writeFile(live, makePng(30, 30, RED))
+    await writeFile(build, makePng(30, 30, RED))
+    const out = join(dir, 'out')
+    const r = run([
+      '--live-screenshot', live,
+      '--build-screenshot', build,
+      '--output-dir', out,
+      '--crop-live-bbox', '0,0,10,10',
+      '--crop-live-dpr', '1',
+      '--crop-build-bbox', '0,0,10,10',
+      '--crop-build-dpr', '1',
+    ])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.diffPixels, 0)
+    assert.equal(json.dimensions.live.width, 10)
+    assert.equal(json.dimensions.build.width, 10)
+    assert.ok(json.croppedLiveTo)
+    assert.ok(json.croppedBuildTo)
+    const liveStat = await stat(join(out, 'live-cropped.png'))
+    const buildStat = await stat(join(out, 'build-cropped.png'))
+    assert.ok(liveStat.size > 0)
+    assert.ok(buildStat.size > 0)
+  })
+
+  // Cleanup
+  await rm(TMPROOT, { recursive: true, force: true }).catch(() => {})
+}
+
+if (failed > 0) {
+  process.stdout.write(`\n${failed} failed, ${passed} passed\n`)
+  process.exit(1)
+}
+process.stdout.write(`\n${passed} passed\n`)
+process.exit(0)