Skip to main content

​
Supported platforms

visor supports two mobile platforms:
PlatformDriver stackDefault device name
AndroidAppium with UiAutomator2emulator-5554
iOSAppium with XCUITestiPhone 17 Pro
visor is mobile-only today. Web support is not implemented.

​
Runtime modes

visor can run in two modes.

​
Real runtime

In real runtime mode, visor connects to an Appium server and interacts with an actual simulator, emulator, or device. What real runtime requires:
  • a reachable Appium server (or auto-start enabled)
  • 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

​
Mock runtime

In mock runtime mode, visor does not talk to a real device. Mock mode is useful when you want to:
  • validate wiring and payload handling
  • produce deterministic test artifacts
  • exercise run and benchmark flows without device infrastructure
Mock mode behavior:
  • screenshots are written as a valid 1x1 PNG
  • UI source is written as a minimal XML document
  • visibility assertions fail only when the target contains missing or not_found

​
Default runtime values

When you do not set an explicit runtime value, visor resolves defaults.
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
Android default deviceemulator-5554
iOS default deviceiPhone 17 Pro
For scenario execution, platform is resolved from the scenario unless you override it at runtime.

​
Environment variables

visor reads runtime configuration 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_ANDROID_DEVICEAndroid device or emulator identifier
VISOR_IOS_BUNDLE_IDiOS bundle identifier
VISOR_IOS_DEVICEiOS simulator or device name
VISOR_ATTACH_TO_RUNNINGReuse running app process (true/1/yes/on)
VISOR_APPIUM_CMDCommand visor uses when it needs to launch Appium
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_ANDROID_DEVICE
  • PATF_IOS_BUNDLE_ID
  • PATF_IOS_DEVICE
  • 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. scenario-level defaults where applicable
  3. environment variables
  4. built-in defaults
The main resolved values are:
  • platform
  • device
  • timeout
  • artifact output directory
  • server URL
  • app identifier
  • runtime mode

​
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

​
Appium lifecycle and connectivity preflight

For scenario execution and direct action commands in real runtime mode, visor performs a preflight check against the Appium host and port. If Appium is unreachable and auto-start is enabled (default), visor attempts to launch Appium first. If Appium is unreachable and auto-start is disabled (--no-auto-start-appium), visor fails early with a target initialization error. When visor auto-starts Appium for a command, it also stops that managed Appium process when the command completes. You can also manage lifecycle explicitly 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