Skip to main content

​
1. Install the CLI

brew install grantiva/tap/grantiva
Verify your environment: 
grantiva doctor

​
2. Authenticate

grantiva auth login
This opens your browser for login. For CI, use an API key: 
grantiva auth login --api-key YOUR_API_KEY

​
3. Initialize your project

cd /path/to/your/xcode/project
grantiva init
This creates grantiva.yml with auto-detected scheme and simulator settings.

​
4. Define your screens

Edit grantiva.yml to list the screens you want to test: 
scheme: MyApp
simulator: iPhone 16

screens:
  - name: Home
    path: launch

  - name: Profile
    path:
      - tap: "Profile"
      - wait: 1

  - name: Settings
    path:
      - tap: "Settings"
      - wait: 1

​
5. Capture baselines

Take initial screenshots: 
grantiva diff capture
Approve them as baselines: 
grantiva diff approve

​
6. Run comparisons

After making changes, compare against baselines: 
grantiva diff compare
Or run the full pipeline (build + capture + compare + upload): 
grantiva ci run

​
7. Add to CI

# .github/workflows/vrt.yml
name: Visual Regression
on: pull_request

jobs:
  vrt:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - run: brew install grantiva/tap/grantiva
      - name: Run VRT
        env:
          GRANTIVA_API_KEY: ${{ secrets.GRANTIVA_API_KEY }}
        run: grantiva ci run
Results are posted as a GitHub Check Run on your pull request.

​
How diffing works

Each screen is compared using two metrics:
MetricDefault thresholdDescription
Pixel diff2%Percentage of pixels that differ
Perceptual distance5.0CIE76 color space distance (more human-aware)
A screen fails if either threshold is exceeded. Adjust in grantiva.yml: 
diff:
  threshold: 0.01          # Stricter: 1% pixel diff
  perceptual_threshold: 3.0 # Stricter perceptual distance

​
Next steps