build

The build command is the primary command for visual regression testing. It captures screenshots, compares them against baselines, and reports results.

Usage

npx ui-inspect build [options]

Options

Flag	Type	Default	Description
`--project <id>`	`string`	config file	Project ID from dashboard
`--branch <name>`	`string`	auto-detect	Git branch name
`--commit <sha>`	`string`	auto-detect	Commit SHA
`--base-url <url>`	`string`	`http://localhost:3000`	Base URL for screenshots
`--dir <path>`	`string`	—	Load screenshots from directory instead of capturing
`--json`	`boolean`	`false`	Output results as JSON
`--dry-run`	`boolean`	`false`	Run without uploading results
`--skip-capture`	`boolean`	`false`	Skip screenshot capture phase
`--threshold <n>`	`number`	`0.1`	Pixel diff threshold (0-1)
`--fail-on-diff`	`boolean`	`false`	Exit with code 1 if diffs found
`--auto-approve`	`boolean`	`false`	Auto-approve new baselines
`--report`	`boolean`	`false`	Post PR comment with results
`--pr <number>`	`number`	—	GitHub PR number for reporting
`--turbosnap`	`boolean`	`false`	Enable smart snapshot filtering
`--base-branch <name>`	`string`	`main`	Base branch for TurboSnap

How it works

Creates a build record in the database
TurboSnap analysis (optional) — determines which screenshots need re-testing based on git changes
Captures screenshots — launches Puppeteer, navigates to each URL, captures at each viewport
Fetches baselines — retrieves existing baseline images for comparison
Runs smart diff — SSIM perceptual comparison + pixel matching + anti-flake filtering + layout shift detection
Batch creates comparisons — uploads all results
Finalizes build — calculates totals, determines pass/fail
Auto-approve (optional) — approves screenshots without existing baselines
PR comment (optional) — posts results to GitHub PR

Examples

Basic visual test

npx ui-inspect build --project proj_abc123

CI/CD with PR reporting

npx ui-inspect build \
  --project proj_abc123 \
  --fail-on-diff \
  --report \
  --pr 42 \
  --turbosnap

Using pre-captured screenshots

npx ui-inspect build \
  --project proj_abc123 \
  --dir ./screenshots \
  --skip-capture

Dry run for testing

npx ui-inspect build \
  --project proj_abc123 \
  --dry-run \
  --json

Output

✓ Build created: build_abc123
✓ TurboSnap: testing 3/10 screenshots (70% skipped)
✓ Captured 6 screenshots
✓ Compared against baselines

Results:
  ✓ homepage/desktop — No diff
  ✓ homepage/mobile — No diff
  ⚠ button/desktop — 1.2% diff (below threshold)
  ✗ card/desktop — 18.4% diff (FAILED)

Summary: 3 passed, 1 below threshold, 1 failed
Build: FAILED

Smart diff analysis

Each comparison runs through the smart diff pipeline:

Pixel matching — Raw pixel-by-pixel comparison with configurable threshold
SSIM — Structural Similarity Index for perceptual quality assessment
Layout shift detection — Detects horizontal and vertical content shifts
Anti-flake filtering — Removes anti-aliasing noise and sub-pixel rendering artifacts
Stability scoring — Classifies results as stable, likely-flaky, or flaky

On this page