Skip to main content

​
Generate a config file

grantiva init
This creates grantiva.yml in your project root. The CLI auto-detects your Xcode scheme and workspace. 
grantiva init --scheme MyApp --bundle-id com.example.myapp

​
Configuration reference

# Required
scheme: MyApp
simulator: iPhone 16

# Optional
workspace: MyApp.xcworkspace    # If using a workspace
project: MyApp.xcodeproj        # If not using a workspace
bundle_id: com.example.myapp

# Screens to capture
screens:
  - name: Home
    path: launch

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

  - name: Settings
    path:
      - swipe: up
      - tap: "Settings"
      - wait: 2

# Diff thresholds
diff:
  threshold: 0.02              # Max pixel diff % (0–1.0)
  perceptual_threshold: 5.0    # Max CIE76 color distance

​
Screens

Each screen has a name and a path that describes how to navigate to it.

​
Simple launch screenshot

- name: Home
  path: launch

- name: Settings
  path:
    - tap: "Settings"          # Tap by accessibility label
    - wait: 2                  # Wait N seconds
    - swipe: up                # up, down, left, right
    - tap: "Advanced"
ActionDescription
launchScreenshot immediately after app launch
tap: "Label"Tap element by accessibility label
swipe: directionSwipe up, down, left, or right
wait: NWait N seconds
A screenshot is automatically taken at the end of each screen’s path.

​
Diff thresholds

SettingDefaultDescription
threshold0.02Maximum pixel difference percentage (2%)
perceptual_threshold5.0Maximum CIE76 perceptual color distance
A screen fails if either threshold is exceeded.

​
Directory structure

After running commands, Grantiva creates: 
.grantiva/
├── captures/          # Screenshots from capture runs
│   └── diffs/         # Diff images for failed comparisons
└── baselines/         # Local baseline images (if not using cloud)
Credentials are stored at ~/.grantiva/auth.json.