Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grantiva.io/llms.txt

Use this file to discover all available pages before exploring further.

​
GitHub Actions

name: Visual Regression
on: pull_request

jobs:
  vrt:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4

      - name: Install Grantiva CLI
        run: brew install grantiva/tap/grantiva

      - name: Run visual regression tests
        env:
          GRANTIVA_API_KEY: ${{ secrets.GRANTIVA_API_KEY }}
        run: grantiva ci run
The CLI automatically posts results as a GitHub Check Run on the pull request.

​
Environment variables

VariableDescription
GRANTIVA_API_KEYAPI key for authentication (required in CI)
GRANTIVA_API_URLBase URL override (default: https://api.grantiva.io)

​
Pre-built binaries

Grantiva can consume pre-built .app bundles or .ipa archives instead of building from source. This decouples the build from the test, enabling faster and more flexible CI pipelines. 
# Use a pre-built .app bundle (skips xcodebuild, still installs)
grantiva ci run --app-file ./build/MyApp.app

# Use an .ipa from a CI artifact
grantiva ci run --app-file ./artifacts/MyApp.ipa

# App is already installed on the simulator (skip build and install)
grantiva ci run --no-build
When --app-file is provided:
  • The xcodebuild step is skipped entirely
  • The binary is validated to be a simulator build (not a device build)
  • The bundle ID is derived from the binary’s Info.plist if not specified
  • .ipa files are automatically extracted (.app from Payload/)
  • scheme is not required in grantiva.yml

​
Split build and test

Separate the build and test into different CI jobs. This lets you cache build artifacts, reuse them across multiple test runs, and run visual regression on different device configurations in parallel. 
jobs:
  build:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: |
          xcodebuild build -scheme MyApp \
            -destination 'generic/platform=iOS Simulator' \
            -derivedDataPath build/
      - uses: actions/upload-artifact@v4
        with:
          name: app-binary
          path: build/Build/Products/Debug-iphonesimulator/MyApp.app

  visual-regression:
    needs: build
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: app-binary
          path: ./app
      - name: Install Grantiva CLI
        run: brew install grantiva/tap/grantiva
      - name: Visual regression
        env:
          GRANTIVA_API_KEY: ${{ secrets.GRANTIVA_API_KEY }}
        run: grantiva ci run --app-file ./app/MyApp.app
Benefits:
  • Build and test can be separate jobs (even separate machines)
  • Build artifacts can be cached and reused across multiple test runs
  • Visual regression doesn’t re-build when only baselines changed
  • Multiple Grantiva configs (different screen sizes, locales) can run in parallel against the same binary

​
JSON output for scripting

grantiva ci run --json | jq '.failed_count'
Exit code is 0 if all screens pass, 1 if any fail — works with CI if conditions.

​
Approving new baselines

When UI changes are intentional, approve the new screenshots: 
grantiva diff approve
Or approve specific screens: 
grantiva diff approve "Home" "Settings"
Approved captures become the new baselines for future comparisons.

​
Results

After each run, the CLI outputs:
  • Run ID and dashboard URL
  • Screen-by-screen pass/fail status
  • Pixel diff percentage and perceptual distance per screen
  • Total duration
Results are also visible in the Grantiva dashboard under your project.