Skip to main content

​
Supported platforms

visor supports two mobile platforms:
PlatformDriver stack
AndroidAppium with UiAutomator2
iOSAppium with XCUITest
visor is mobile-only today. Web support is not implemented.

​
Runtime

visor connects to an Appium server and interacts with an actual simulator, emulator, or device. Runtime execution requires:
  • a running Visor daemon from visor start
  • a booted iOS or Android target
  • installed Node runtime dependencies, including Appium and WebdriverIO
  • a valid app identifier or environment-based fallback
Platform note:
  • Android app-id maps to appPackage
  • iOS app-id maps to bundleId and must match an app already installed on the selected simulator or device
  • the Android package name and iOS bundle identifier can differ for the same product

​
Device selection

visor requires a running device target for runtime commands. Pass --device when you know the target identifier: 
visor run checkout-smoke.json --device emulator-5554 --app-id com.example.app
If you omit --device, visor detects running Android devices and booted iOS simulators:
  • Android devices come from adb devices entries in the device state
  • iOS simulators come from xcrun simctl list devices booted
When exactly one target is detected, visor uses it automatically. When multiple targets are detected in an interactive terminal, visor prompts you to choose one. In a non-interactive shell, visor returns a failure envelope and asks you to rerun with --device. The runtime platform is inferred from the selected device. The CLI does not accept --platform.

​
Default runtime values

When you do not set an explicit runtime value, visor resolves defaults for non-device settings.
SettingDefault value
Appium server URLhttp://127.0.0.1:4723
Android app id fallbackcom.example.app
iOS bundle id fallbackcom.example.app
Android default activity fallback.MainActivity

​
Environment variables

visor reads these runtime settings from environment variables when explicit runtime input is not provided.
Environment variablePurpose
VISOR_ANDROID_APP_PACKAGEAndroid app package name
VISOR_ANDROID_APP_ACTIVITYAndroid launch activity
VISOR_IOS_BUNDLE_IDiOS bundle identifier
VISOR_ATTACH_TO_RUNNINGReuse running app process (true/1/yes/on)
VISOR_APPIUM_CMDCommand visor start uses when it needs to launch Appium
VISOR_WEBDRIVER_CONNECTION_TIMEOUT_MSWebDriverIO request timeout for Appium calls
VISOR_WEBDRIVER_CONNECTION_RETRY_COUNTWebDriverIO retry count for Appium calls
VISOR_APP_MAP_DIRHost directory for persisted app maps
VISOR_NO_MAPDisable app-map reads and writes (true/1/yes/on)
VISOR_DISABLE_MAPAlias for VISOR_NO_MAP
Legacy PATF_* fallbacks are only supported for the mobile runtime variables implemented in the adapter layer:
  • PATF_ANDROID_APP_PACKAGE
  • PATF_ANDROID_APP_ACTIVITY
  • PATF_IOS_BUNDLE_ID
  • PATF_ATTACH_TO_RUNNING
There is no PATF_* fallback for Appium command resolution.

​
Runtime resolution order

For scenario runs and benchmarks, visor resolves runtime settings in this order:
  1. explicit runtime input
  2. detected running device target, when --device is omitted
  3. scenario-level defaults where applicable
  4. environment variables
  5. built-in defaults
The main resolved values are:
  • platform
  • device
  • timeout
  • artifact output directory
  • server URL
  • app identifier

​
App-map state

Mapped execution stores local host state under .visor/maps by default. The map identity is scoped by platform and app id, so observations from different flows in the same app accumulate into one shared map while Android and iOS maps remain separate. The persistent map stores schema version, screen variants, source-derived labels, normalized fingerprints, navigation edges, destination contracts, confidence, and stale-path evidence. It does not embed screenshots. Use VISOR_APP_MAP_DIR to move map state, or pass --no-map / set VISOR_NO_MAP=true to disable both reading and writing the map for a run.

​
Attach mode

When you pass --attach (or set VISOR_ATTACH_TO_RUNNING=true), visor asks Appium to reuse the already running app process instead of launching from scratch.
  • Android capabilities used: noReset=true, fullReset=false, autoLaunch=false, dontStopAppOnReset=true
  • iOS capabilities used: noReset=true, fullReset=false, autoLaunch=false, shouldTerminateApp=false, forceAppLaunch=false

​
Runtime lifecycle and connectivity preflight

For scenario execution and direct action commands, start the Visor daemon first: 
visor start
visor start ensures Appium is reachable and starts a local daemon that keeps WebDriver sessions warm for subsequent commands. Runtime commands fail early if the daemon is not running. If another Appium process is already listening on the selected server-url, visor start fails instead of reusing it. Stop the existing Appium process or choose a different --server-url so Visor owns the Appium lifecycle. Manage lifecycle with:
  • visor start
  • visor status
  • visor stop

​
Current limitations

The runtime layer currently has these important limits:
  • no web runtime
  • no desktop runtime
  • no built-in device provisioning
  • no multi-app orchestration within a single run
  • no assertion engine beyond visibility checks