> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile App Testing

> Test native iOS and Android apps with AI-powered automation

QA.tech supports testing native iOS and Android applications using the same AI agent that powers web testing. The agent interacts with your app through touch gestures, hardware controls, and deep links.

## Network Access

QA.tech test runs originate from a fixed pool of IP addresses. If your app connects to a backend that has a **firewall, VPN gateway, IP allowlist, or rate-limiting rules**, you must whitelist these IPs to allow test traffic through.

<Warning>
  Without whitelisting, your tests may fail with network errors, timeouts, or
  unexpected login failures even though the app itself works fine.
</Warning>

### QA.tech IP Addresses

Find the current list of mobile testing IP ranges in the app under [**Settings → Network**](https://app.qa.tech/current-project/settings/network) — see the **Mobile Testing IP Whitelist** section.

<Note>
  Mobile testing uses a different set of IP ranges than web testing, so the
  [Outbound IPs API](/api-reference/infrastructure/get-outbound-ips) does not
  cover them. IP addresses may change — always use the live **Mobile Testing IP
  Whitelist** in Settings → Network as the authoritative source.
</Note>

### How to Add the Whitelist

Add the IP ranges from [Settings → Network](https://app.qa.tech/current-project/settings/network) to your security system's allowlist. The exact steps depend on your setup — see the [IP Access Control](/configuration/ip-access-control) guide for platform-specific instructions covering Cloudflare, AWS CloudFront, and other firewalls.

Common places to add these rules:

* Backend firewall or security group (AWS, GCP, Azure)
* API gateway rate-limiting or allowlist rules
* VPN / zero-trust gateway (e.g. Tailscale, Cloudflare Access, Zscaler)
* Mobile backend service IP allowlists

## Test Environments

Mobile tests run on cloud-hosted iOS Simulators and Android Emulators. Configure the simulator or emulator under **Settings → Device Presets** — see [Mobile Device Presets](/test-features/device-presets#mobile-device-presets) for device model, OS version, orientation, location, network log capture, and override priority.

| Environment | Status | Description |
| - | - | - |
| Cloud emulators | Available | iOS Simulator and Android Emulator in cloud |
| Real devices | Coming soon | Physical iOS and Android device testing |

## Limitations

Cloud iOS Simulators and Android Emulators cover touch, navigation, GPS, and deep links. They do not include some hardware sensors.

| Feature | Status | Notes |
| - | - | - |
| Tap, double tap, long press, swipe, type | Available | iOS and Android |
| Home, app switcher, launch, close, restart, deep links | Available | iOS and Android |
| Back button | Android only | |
| Volume up and down | Available | iOS and Android |
| Rotate during a test | Android only | On iOS, set orientation on the [device preset](/test-features/device-presets#mobile-device-presets) before the run |
| GPS location | Available | Set on the [device preset](/test-features/device-presets#mobile-device-presets) |
| Network request logs | Available | Enable **Capture Network Logs** on the device preset |
| Live view | Available | Watch the session from the test trace |
| Wait For dependencies | Available | [Resume From](/core-concepts/dependencies#resume-from) is not supported for mobile |
| Companion / other apps | Available | Up to three additional builds on the same device |
| Real physical devices | Coming soon | Tests run on simulators and emulators |
| Device console logs | Coming soon | |
| Microphone / audio input | Not available | Speech, dictation, voice notes, and voice search. Playing an audio file into the microphone is web-only |
| Camera | Not available | Live camera feed, QR codes, and barcode scanning |
| Bluetooth | Not available | Pairing, beacons, and nearby devices |
| NFC | Not available | Payments, tags, and tap-to-pair |
| Multi-touch / pinch-to-zoom | Not available | Maps and image zoom that require two fingers |
| Face ID / fingerprint | Not available | Biometric prompts are not simulated |
| Device shake | Not available | Shake-to-undo and similar gestures |
| App Store / Play Store builds | Not available | Upload a simulator or emulator build. See [Preparing Your App Build](#preparing-your-app-build) |

<Note>
  Some Android apps detect the emulator as a rooted device and refuse to start.
  If that happens, skip the rooted-device check on your staging build.
</Note>

## Debugging and Observability

| Feature | Status | Description |
| - | - | - |
| Live view | Available | Watch tests run in real time from the test trace while a session is active |
| Network request logs | Available | Inspect HTTP requests in the test trace when network capture is enabled on the [device preset](/test-features/device-presets#mobile-device-presets) |
| Device console logs | Coming soon | App console output in the test trace |

## AI Chat and Test Dependencies

When mobile testing is enabled for your organization, you can create, edit, and run mobile tests through the [AI Chat Assistant](/core-concepts/ai-chat-assistant) — the same natural-language workflow as web testing.

For [test dependencies](/core-concepts/dependencies):

* **Wait For** — supported. Use it to control execution order between mobile tests.
* **Resume From** — not supported for mobile apps. Mobile tests cannot inherit app state from another test.

## Coming Soon

* Real device testing on physical iOS and Android hardware (selectable through device presets)
* Device console logs in the test trace

## Preparing Your App Build

<Note>
  Mobile testing requires a simulator or emulator build of your app, not an
  AppStore or Play Store distribution build. Follow the steps below for your
  platform.
</Note>

<Tabs>
  <Tab title="iOS">
    Prepare an **iOS Simulator build** (`.app` file compressed as `.zip` or `.tar.gz`). AppStore distribution builds (`.ipa`) are not supported - they are device-specific and cannot run on simulators.

    ### Build with Xcode

    Run and build your application in Xcode while targeting an iOS Simulator.

    Once the build is complete and the app is running in the simulator, locate the `.app` file:

    1. In Xcode, go to **Product** → **Show Build Folder in Finder**
    2. Navigate to **Products/Debug-iphonesimulator/**
    3. Find your `.app` file

    ### Build with Xcode Command Line Tools

    <CodeGroup>
      ```bash .xcodeproj theme={null}
      xcodebuild -project '{project_name}.xcodeproj' \
        -scheme '{scheme_name}' \
        -sdk iphonesimulator \
        -configuration Debug
      ```

      ```bash .xcworkspace theme={null}
      xcodebuild -workspace '{your_workspace_name}.xcworkspace' \
        -scheme '{scheme_name}' \
        -sdk iphonesimulator \
        -configuration Debug
      ```
    </CodeGroup>

    The `.app` file is output to:

    ```
    build/Debug-iphonesimulator/
    ```

    ### Compress the .app file

    Once you have the `.app` file, compress it before uploading:

    ```bash theme={null}
    zip -r AppName.zip AppName.app
    ```

    Upload the resulting `.zip` (or `.tar.gz`) file - not the raw `.app` directory.
  </Tab>

  <Tab title="Android">
    Prepare an **APK file** for your app. If your project produces an Android App Bundle (`.aab`), convert it to `.apk` first using the steps below.

    ### Build with Android Studio

    Select **Build** → **Build APK(s)** → **Build APK(s)**

    Once complete, click **locate** in the dialog that appears, or navigate to:

    ```
    {project_name}/{app_module}/build/outputs/apk/
    ```

    ### Build with Gradle

    Run the `assemble` command for your preferred build variant:

    ```bash theme={null}
    ./gradlew assembleDebug
    ```

    The `.apk` file is output to:

    ```
    {project_name}/{app_module}/build/outputs/apk/
    ```

    ### Expo and React Native managed workflow

    Native Android examples assume `android/` already exists. Expo and React Native managed apps gitignore that folder. In CI, generate it before upload:

    ```yaml theme={null}
    - run: npm ci
    - run: npx expo prebuild --platform android --non-interactive --no-install
    - run: cd android && ./gradlew assembleDebug --no-daemon
    ```

    The debug APK path is typically `android/app/build/outputs/apk/debug/app-debug.apk`. EAS preview APKs also work if you wait for the build and download the artifact. Still upload a simulator or emulator binary, not a store `.ipa`.

    ### Convert AAB to APK

    If you only have an Android App Bundle (`.aab`), convert it using [bundletool](https://developer.android.com/tools/bundletool):

    ```bash theme={null}
    # Generate a universal APK set
    bundletool build-apks --bundle=/{your_app}/{name}.aab \
        --output=/{your_app}/{name}.apks \
        --mode=universal

    # Extract a single APK from the set
    unzip -p /{your_app}/{name}.apks universal.apk > /{your_app}/{name}.apk
    ```

    Upload the resulting `.apk` file.
  </Tab>
</Tabs>

## Setting Up a Mobile App in QA.tech

<Steps>
  <Step title="Create a Mobile Application">
    In your project, go to **Settings → Applications & Envs** and create a new
    application. Select **Mobile App** as the application type.
  </Step>

  <Step title="Add an Environment">
    Add an environment to your mobile application. Select the platform - **iOS** or **Android** - and give the environment a name (for example: Staging or Production).

    No URL is required for mobile apps.
  </Step>

  <Step title="Upload Your App Build">
    Upload your app build file:

    * iOS: `.zip` or `.tar.gz` containing your `.app` simulator build (max 4 GB)
    * Android: `.apk` file (max 4 GB)
  </Step>

  <Step title="Add Other Apps (Optional)">
    Use **Other Apps** when the primary app needs companion, authentication, or
    helper apps installed on the same device. Upload up to three additional
    builds. They must use the same platform and have different bundle IDs or
    package names.
  </Step>

  <Step title="Create and Run Tests">
    Create tests for your mobile application. The AI agent will interact with your app using touch gestures and device controls.
  </Step>
</Steps>

## CI and PR testing

A pull request does not give QA.tech a preview URL for a native app. CI must upload the PR simulator or emulator binary and pin the run to that file with `applicationBuildShortId`.

See [PR Testing for Mobile Apps](/pr-testing/agents/mobile) for GitHub Actions, GitLab, and Bitrise workflows (test plans and change reviews).

## Other Apps

A mobile environment can install one primary build and up to three **other apps** on the same simulator or emulator. Each environment pins exact build versions, so staging and production environments can use different versions of the same helper app.

Use other apps for packages that participate in the same device session but do not need their own QA.tech test suite. Create a separate [Application](/core-concepts/applications-and-environments#applications) when the app has independent tests or should run in a separate environment.

<Note>
  Other apps currently require the Appetize mobile backend. All builds in an
  environment must target the same platform and use distinct bundle IDs or
  package names.
</Note>

## AI Agent Capabilities

The agent interacts with your app using the following actions:

### Touch Interactions

| Action | Description |
| - | - |
| Tap | Tap at a specific point on the screen |
| Double tap | Double-tap at a specific point |
| Long press | Press and hold at a point for a configurable duration |
| Swipe | Swipe from one point to another |
| Type | Tap a field and type text |
| Clear and type | Clear an existing field value, then type |

### Device Controls

| Action | Platforms | Description |
| - | - | - |
| Home button | iOS, Android | Press the device home button |
| Back button | Android only | Press the Android back button |
| App switcher | iOS, Android | Open the app switcher |
| Launch app | iOS, Android | Launch an app by bundle ID or package name |
| Close app | iOS, Android | Close the current app |
| Open URL | iOS, Android | Open a URL or deep link |
| Rotate | Android only | Switch between portrait and landscape |
| Volume up/down | iOS, Android | Press hardware volume keys |

See [Limitations](#limitations) for hardware and environment constraints.

## Requirements

Mobile testing is enabled per organization. Contact [support](mailto:hi@qa.tech) to enable mobile testing for your account.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.