VRT Quick Start

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:

Metric	Default threshold	Description
Pixel diff	2%	Percentage of pixels that differ
Perceptual distance	5.0	CIE76 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

VRT Concepts — how the CLI driver works, baseline lifecycle, and CI vs local auth
CLI Commands reference
Configuration reference
CI Integration guide

Getting Started

iOS SDK

CLI

Concepts

Push

Dashboard

1. Install the CLI

2. Authenticate

3. Initialize your project

4. Define your screens

5. Capture baselines

6. Run comparisons

7. Add to CI

How diffing works

Next steps

​1. Install the CLI

​2. Authenticate

​3. Initialize your project

​4. Define your screens

​5. Capture baselines

​6. Run comparisons

​7. Add to CI

​How diffing works

​Next steps

1. Install the CLI

2. Authenticate

3. Initialize your project

4. Define your screens

5. Capture baselines

6. Run comparisons

7. Add to CI

How diffing works

Next steps