VRT Quick Start

1. Install the CLI

brew install grantiva/tap/grantiva

Verify your environment:

grantiva doctor

Then extract the embedded UI automation runner:

grantiva runner install

2. Authenticate

grantiva auth login

This opens your browser for login, and saves the credentials to ~/.grantiva/auth.json. For CI, use an API key instead:

grantiva auth login --api-key gpat_your_key

Or set GRANTIVA_API_KEY in the environment, which takes precedence over the saved file.

3. Initialize your project

cd /path/to/your/xcode/project
grantiva init

This creates grantiva.yml. The scheme is read from the name of the .xcworkspace or .xcodeproj in the directory, and the simulator defaults to iPhone 16 — edit either if that is wrong.

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 when the GitHub App is configured. grantiva ci run exits 0 when every screen passes and 1 when any fails — the results are uploaded either way. Review the run from the terminal without leaving CI:

run_id=$(grantiva ci run --json | jq -r .run_id)
grantiva console vrt runs get acme/my-app "$run_id"

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, the baseline lifecycle, and CI vs local auth
Commands — every grantiva command and flag
Configuration — the full grantiva.yml reference
CI integration — GitHub Actions, pre-built binaries, and parallel runs
VRT review — accept, flag, and approve runs from the terminal

Getting Started

SDKs

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