Mobile testing

Mobile tests run against android or ios targets and a device profile. Native app tests must set use.mobile.appState to either preserve or reset so the runner knows whether to keep or reset installed app state.

Configure a native app target

Android targets use appPackage and usually appActivity. iOS targets use bundleId.

registry:
  targets:
    issue-tracker-android:
      platform: android
      appPackage: com.acme.issuetracker
      appActivity: .MainActivity
      app:
        path: apps/issue-tracker-debug.apk
    issue-tracker-ios:
      platform: ios
      bundleId: com.acme.issuetracker
      app:
        path: apps/IssueTracker.app

app.path must be relative to the config file. Keep large app binaries outside commits unless your repository intentionally stores test builds.

Select a local device

Local mobile runs use Appium and a device profile with transport: local.

registry:
  devices:
    android-local:
      platform: android
      transport: local
      match:
        avd: Pixel_8_API_35
        automationName: UiAutomator2
    ios-local:
      platform: ios
      transport: local
      match:
        udid: 00000000-0000-0000-0000-000000000000
        automationName: XCUITest

Reference the device from the test with use.device:

test-id: t_vog-earing-wap-git-tim-assert-teras-mill-aus-ila
name: Open the mobile inbox
target: issue-tracker-android
use:
  device: android-local
  mobile:
    appState: reset
steps:
  - Open the app.
  - Verify the inbox tab is visible.

Use reset when a test needs a clean app state. Use preserve when the test depends on an existing install, session, or prepared local state.

Run on BrowserStack

BrowserStack mobile runs use a device profile with transport: browserstack. Native app targets for BrowserStack must provide app.browserstack; local app.path is not used as a BrowserStack substitute.

registry:
  targets:
    issue-tracker-android:
      platform: android
      appPackage: com.acme.issuetracker
      appActivity: .MainActivity
      app:
        browserstack: bs://uploaded-app-id
  devices:
    android-browserstack:
      platform: android
      transport: browserstack
      match:
        deviceName: Google Pixel 8
        osVersion: "14.0"

Then select that device in the test or with the CLI.

use:
  device: android-browserstack
  mobile:
    appState: preserve

Keep app state explicit

The runner rejects native mobile tests that omit use.mobile.appState. Put it in the global config for one project-wide policy, in the suite for a group of tests, or in each test when flows need different behavior.

use:
  mobile:
    appState: reset

For suites, set one use.device when every child test should use the same mobile device. If the suite does not set a device, every child test must resolve to one device, and child tests cannot mix multiple devices in the same suite run.

Run it

Run a mobile test the same way you run a web test:

>npx agent-qa run tests/mobile-inbox.yaml

Use --device when you want to override the file-backed device selection for one run:

npx agent-qa run tests/mobile-inbox.yaml --device android-browserstack

Auth state and mobile app state

Web auth state is documented separately in Auth state. Native Android and iOS runs do not use use.authState.

For native apps, use.mobile.appState: preserve is the fast path when a test should reuse installed app data. This is broader than auth: it can preserve caches, preferences, and other app data. agent-qa does not export generic secure-storage, keychain, shared-preferences, app-private, or native mobile token data.