---
title: Mobile testing
description: Configure native Android and iOS targets, local or BrowserStack devices, app installs, and required mobile app-state behavior.
---



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 [#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 [#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 [#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 [#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-it]

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

<CommandSnippet command="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 [#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.