---
title: "Mobile testing"
description: "Configure native Android and iOS agent-qa targets with local or BrowserStack devices, app installs, and the appState setting that preserves or resets app state."
canonical_url: "https://vostride.com/docs/agent-qa/guides/mobile-testing"
md_url: "https://vostride.com/docs/agent-qa/guides/mobile-testing.md"
last_updated: "2026-08-17T02:33:16+05:30"
---

# Mobile testing

> Configure native Android and iOS agent-qa targets with local or BrowserStack devices, app installs, and the appState setting that preserves or resets app state.

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`.

```yaml
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`.

```yaml
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`:

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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:

```bash
npx agent-qa run tests/mobile-inbox.yaml
```

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

```bash
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](/docs/agent-qa/guides/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.