blinkdiff

Per-build visual diffing for iOS and macOS apps, native or React Native.

Declare a handful of golden journeys as YAML. On every pull request, blinkdiff drives them on a simulator (or the Mac), screenshots the checkpoints, diffs against baselines committed in your repo, and comments on the PR with what moved. Approve intended changes with one comment. No SDK in your app, no test target in your project, no service to sign up for.

flow.yaml ──▶ driver (XCUITest) ──▶ screenshots ──▶ diff vs baseline ──▶ report + PR comment + exit code

Why it works for any app

The driver is a generic XCUITest bundle that launches your app by bundle id and walks it through the accessibility tree. SwiftUI, UIKit, AppKit and React Native all expose the same labels and identifiers (an RN testID becomes accessibilityIdentifier), so one driver covers all of them, and it never has to be compiled into your app.

Install

Requirements: macOS with Xcode, xcodegen (brew install xcodegen), Node 20+.

npm i -g blinkdiff        # or use npx
blinkdiff doctor          # checks Xcode, xcodegen, simulators

Quick start

cd your-repo
blinkdiff init                      # blinkdiff.yaml + flows/example.yaml
# put your app on the simulator (expo run:ios / xcodebuild ... / drag the .app in)
# edit flows/example.yaml: bundle id + a few taps + screenshots
blinkdiff run flows/example.yaml    # first run creates the baseline
blinkdiff run flows/example.yaml    # PASS · 3/3 unchanged
git add .blinkdiff/baseline flows blinkdiff.yaml

Change something in the app, run again:

!! welcome                      changed 4.213%
   settings                     same 0%
FAIL · 1 changed, 0 new, 0 missing
  approve: blinkdiff approve flows/example.yaml

Open the report (--open): baseline / current / diff side by side and an onion-skin slider per screenshot.

In CI

blinkdiff init --github

adds two workflows: the PR check (jakefleming/blinkdiff@main) and the /blinkdiff approve comment handler. Add your app build step where marked, push, done. Every PR then gets a sticky comment like:

blinkdiff: FAIL · 1 of 12 screenshots differ from baseline. | flow | platform | device | shots | same | changed | … | |---|---|---|---:|---:|---:|---| | signin | ios | iPhone 16 | 5 | 4 | 1 | … | signin / validation-empty: changed (3.1% of pixels) Report and screenshots

Comment /blinkdiff approve and the bot commits the new baselines to the PR branch. Full details, including the Expo and native build snippets and how the approve step finds the right artifact: docs/ci.md.

Flows

name: signin
platform: ios                 # ios | macos
app: com.example.app          # bundle id
steps:
  - launch
  - waitFor: Welcome
  - screenshot: welcome
  - tap: Sign in                          # label / title / identifier
  - type: {target: Email, text: [email protected]}
  - tap: {id: submit}                     # RN testID
  - screenshot: {name: validation, mask: [{x: 0, y: 0, w: 1, h: 0.06}]}
  - terminate

Every step, target rules, masks, and the authoring aid that dumps a screen's accessibility tree: docs/flows.md.

Commands

blinkdiff init [--github]           scaffold config, example flow, workflows
blinkdiff run <flow> [--approve]    drive one flow, diff, report
blinkdiff ci [dir|flow ...]         every flow: report/index.html, summary.md, results.json
blinkdiff approve <flow>            promote the staged run to baseline
blinkdiff promote [--from <dir>]    promote every staged flow (used by the CI approve step)
blinkdiff report <flow>             rebuild the HTML report from the last run
blinkdiff doctor                    toolchain check

Exit codes: 0 matched · 1 changed / missing / flow stopped · 2 usage · 3 infrastructure.

State lives in .blinkdiff/: baseline/<flow>/<device_os>/ is committed (baselines are per capture target, so local iOS 26.3 and CI's iOS 26.2 never fight), runs/, report/ and pending/ are ignored (a .gitignore is generated). The driver is built once per blinkdiff version into ~/Library/Caches/blinkdiff/.

Determinism

blinkdiff pins what it can: simulator + runtime, status bar (9:41, full battery), appearance, keyboard autocorrect and prediction off, per-character typing, pointer parked off-window on macOS, system alerts auto-dismissed. Two runs of an unchanged, deterministic app diff at 0%. Relative dates, live data and animations are yours to mock, mask (masks:), or wait past; retries: 1 absorbs a one-off flake without hiding a real change.

Status

Verified end to end on: a React Native / Expo app (5 checkpoints through sign-in, 0% across repeated runs, addressed by label only), Apple Settings on the iOS simulator, and a native macOS app. Unit tests: npm test. Repo CI dogfoods the action on a clean macos-15 runner.

Roadmap: multiple devices per flow, per-flow parallelism across simulators, Android.

Layout

bin/blinkdiff.js       CLI
lib/flow.js             YAML → steps, validation
lib/driver.js           simulator prep, driver build (cache dir), xcodebuild
lib/run.js              run + retry + pending staging + promote
lib/diff.js             pixelmatch, masks
lib/report.js           HTML report, index, summary.md, results.json
lib/init.js             scaffolding
lib/paths.js            roots, state dir, cache dir, config
driver/                 xcodegen spec + the XCUITest step interpreter (iOS + macOS)
action.yml              GitHub Action: run + artifact + PR comment
approve/action.yml      GitHub Action: /blinkdiff approve
docs/                   ci.md, flows.md
test/                   node:test suite

Copyright Minim Industries LLC. See LICENSE.