Configuration

Generate a config file

grantiva init

This writes grantiva.yml in the current directory. The scheme is taken from the name of the .xcworkspace or .xcodeproj it finds there; the simulator defaults to iPhone 16. If grantiva.yml already exists, the command leaves it alone.

grantiva init --scheme MyApp --bundle-id com.example.myapp

grantiva init is the one command with no --json. It still takes --verbose and --quiet.

Configuration reference

# Required (unless using --app-file)
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    # Derived from the binary if --app-file is used

# Screens to capture (VRT)
screens:
  - name: Home
    path: launch

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

  - name: Settings
    path:
      - swipe: up
      - tap: "Settings"
      - assert_visible: "Advanced"
      - tap: "Advanced"

# Standalone Maestro flow files to run (functional tests)
flows:
  - grantiva-flows/tasks.yaml
  - grantiva-flows/shopping.yaml

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

Every top-level key can be overridden on the command line: --scheme, --simulator, --bundle-id.

When you use --app-file to provide a pre-built binary, scheme is not required. The bundle ID is derived from the binary’s Info.plist if not specified.

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
    - type: "search query"     # Type into focused field
    - wait: 2                  # Wait N seconds
    - swipe: up                # up, down, left, right
    - assert_visible: "Advanced" # Fail if element not visible
    - tap: "Advanced"

Action	Description
`launch`	Screenshot immediately after app launch
`tap: "Label"`	Tap element by accessibility label
`type: "text"`	Type text into the focused field
`swipe: direction`	Swipe up, down, left, or right
`wait: N`	Wait N seconds
`assert_visible: "Label"`	Verify an element is visible (fails the screen if not)
`assert_not_visible: "Label"`	Verify an element is not visible
`run_flow: "path.yaml"`	Include steps from another YAML file

A screenshot is taken automatically at the end of each screen’s path.

Flows

The flows: key lists paths to existing Maestro YAML files that grantiva run executes as standalone functional tests, in addition to any screens: entries.

flows:
  - grantiva-flows/tasks.yaml
  - grantiva-flows/shopping.yaml
  - grantiva-flows/calendar.yaml

How it differs from screens:

	`screens:`	`flows:`
Format	Grantiva DSL	Native Maestro YAML
Purpose	VRT capture targets	Functional / smoke tests
Screenshot	Taken automatically at the end	Wherever `takeScreenshot` appears in the file
Baselines	Compared against stored baselines by `grantiva ci run`	Not compared — pass/fail only

Paths are resolved relative to the directory containing grantiva.yml. Flows with the same basename in different directories (smoke/login.yaml, regression/login.yaml) are staged separately, so one cannot shadow the other. grantiva run runs all screens: first, then each flow in flows: order, in a single GrantivaAgent session. By default the suite stops at the first broken flow; --continue-on-failure runs the rest. A runner failure captures a simctl screenshot of the current simulator state for debugging. Screenshots go to .grantiva/captures/, or to <report-dir>/captures when --report-dir is given. grantiva run --flow <path> runs one file and skips screens: entirely.

flows: is only used by grantiva run. The grantiva ci run and grantiva diff pipelines only process screens:.

Maestro compatibility

Grantiva can read Maestro flow files as a drop-in replacement. If you have existing Maestro flows, there’s no need to rewrite them.

Auto-detection

Grantiva auto-detects the format when loading configuration:

Looks for grantiva.yml — parses it as Grantiva or Maestro format (auto-detected)
If there is no grantiva.yml, looks for a .maestro/ directory and loads all flow files

A file is treated as Maestro format when it contains an appId: key or a line starting with - tapOn:, - launchApp, - inputText:, - assertVisible:, or - takeScreenshot:.

Using Maestro flows

Write grantiva.yml in Maestro format, or place flows in .maestro/:

appId: com.example.myapp
---
- launchApp
- tapOn: "Sign In"
- inputText: "user@example.com"
- takeScreenshot: "Login"
- tapOn: "Submit"
- assertVisible: "Welcome"
- takeScreenshot: "Welcome"

Each takeScreenshot becomes a named screen capture point. Commands between screenshots become navigation steps.

Supported Maestro commands

Maestro command	Grantiva mapping
`tapOn` / `doubleTapOn` / `longPressOn`	`tap` (supports `text:` and `id:` selectors)
`inputText`	`type`
`assertVisible`	`assert_visible`
`assertNotVisible`	`assert_not_visible`
`scroll` / `scroll: {direction: down}`	`swipe: up` (direction inverted)
`swipe: {start: ..., end: ...}`	`swipe` (direction derived from coordinates)
`runFlow` / `runFlow: {file: ...}`	`run_flow`
`extendedWaitUntil: {text: ...}`	`assert_visible`
`waitForAnimationToEnd`	`wait` (timeout converted to seconds)
`takeScreenshot: "name"`	Screen capture boundary
`launchApp` / `stopApp` / `killApp` / `back`	Handled by Grantiva, or skipped

Unsupported commands (pressKey, setPermissions, evalScript, repeat, and others) are silently skipped.

Sub-flows

Maestro sub-flows referenced via runFlow are also parsed in Maestro format when auto-detected. You can mix Grantiva and Maestro flow files.

Diff thresholds

Setting	Default	Description
`threshold`	`0.02`	Maximum pixel difference percentage (2%)
`perceptual_threshold`	`5.0`	Maximum CIE76 perceptual color distance

A screen fails if either threshold is exceeded.

Build settings

Pass extra flags directly to xcodebuild:

build_settings:
  - "OTHER_SWIFT_FLAGS=-DDEBUG_MODE"
  - "SWIFT_OPTIMIZATION_LEVEL=-Onone"

Each entry is appended verbatim to the xcodebuild invocation. The --derived-data-path flag is available on every command that builds the app. When both are given it wins: any -derivedDataPath in build_settings is stripped and replaced. Absolute and relative paths both work, including paths containing spaces.

Accessibility rules

a11y:
  rules:
    - missing_label                   # Interactive elements with no accessibility label
    - small_tap_target                # Tap targets smaller than 44×44pt

a11y.rules selects which rules the grantiva_a11y_check MCP tool enforces. Both rules run when the key is absent.

Directory structure

Commands write under .grantiva/ in your project:

.grantiva/
├── captures/          # Screenshots from capture and run
│   └── diffs/         # Diff images for failed comparisons
├── baselines/         # Local baseline images (if not using cloud baselines)
└── recordings/        # grantiva record output, with extracted frames alongside

grantiva run --report-dir <dir> moves the runner’s report.json, assets, failure screenshots, and captures under that directory instead, so nothing is written to ./.grantiva. Credentials live outside the project, at ~/.grantiva/auth.json. Keep-alive session files are at ~/.grantiva/runner/sessions/, and the simulator capacity registry at ~/.grantiva/simulator-capacity/.

Next steps

Commands — every flag that overrides these settings
VRT quick start
Simulator management

Getting Started

SDKs

CLI

Concepts

Push

Dashboard

Generate a config file

Configuration reference

Screens

Simple launch screenshot

Navigation steps

Flows

Maestro compatibility

Auto-detection

Using Maestro flows

Supported Maestro commands

Sub-flows

Diff thresholds

Build settings

Accessibility rules

Directory structure

Next steps

​Generate a config file

​Configuration reference

​Screens

​Simple launch screenshot

​Navigation steps

​Flows

​Maestro compatibility

​Auto-detection

​Using Maestro flows

​Supported Maestro commands

​Sub-flows

​Diff thresholds

​Build settings

​Accessibility rules

​Directory structure

​Next steps

Generate a config file

Configuration reference

Screens

Simple launch screenshot

Navigation steps

Flows

Maestro compatibility

Auto-detection

Using Maestro flows

Supported Maestro commands

Sub-flows

Diff thresholds

Build settings

Accessibility rules

Directory structure

Next steps