> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tester.army/mobile/llms.txt.
> For full documentation content, see https://docs.tester.army/mobile/llms-full.txt.

# App Uploads

Before you can automate mobile tests in CI, you need a simulator build to test against.

## What you need to upload

TesterArmy currently supports iOS Simulator builds in one of these formats:

* `.app.zip`
* `.app.tar.gz`

> **Warning: Simulator builds only**
>
> Do not upload an `.ipa`. That is a device build. TesterArmy needs a `.app` bundle built for **iOS
> Simulator**.

## Build for iOS Simulator

If you already have an Xcode project, build a simulator app with `xcodebuild`:

```bash
xcodebuild -workspace ios/MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Release \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath ios/build \
  build
```

The simulator app bundle usually ends up here:

```bash
ios/build/Build/Products/Release-iphonesimulator/MyApp.app
```

If you are using Expo / React Native, the [mobile example app](https://github.com/tester-army/mobile-example) is a good reference. Its build flow looks like this:

```bash
npx expo prebuild --platform ios

xcodebuild -workspace ios/testerarmy.xcworkspace \
  -scheme testerarmy \
  -configuration Release \
  -sdk iphonesimulator \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath ios/build \
  build
```

## Zip the `.app` bundle

For dashboard uploads and direct API uploads, archive the `.app` bundle after the build completes:

```bash
cd ios/build/Build/Products/Release-iphonesimulator
zip -r MyApp.app.zip MyApp.app

# or using tar
# tar -czf MyApp.app.tar.gz MyApp.app
```

You should end up with a file like `MyApp.app.zip`.

## Upload via the dashboard

Go to your project and click the **Mobile** tab. Then click **Browse Files** and select the `.app.zip` or `.app.tar.gz` file you built.

![Upload app via dashboard](https://files.buildwithfern.com/testerarmy.docs.buildwithfern.com/c207c311784e0182343e69592fb0032c0849891f9035a24dde21c4c7a8333b00/docs/assets/docs/uploading-mobile-app.png)

## Create your first mobile test

Before adding CI, create at least one mobile test in the dashboard:

1. Upload your simulator build.
2. Create a new test or open an existing one.
3. In the test's **App Upload** tab, select the uploaded app.
4. Run the test manually and make sure it passes.

![Selecting an app](https://files.buildwithfern.com/testerarmy.docs.buildwithfern.com/1f9f4a6f471b3e1da79db817a22537b2b8acbc7c0b83c5ecef8866512c98beca/docs/assets/docs/select-mobile-app-for-test.png)

When writing prompts, guide the agent like you would guide a human user.

**Weak prompt example:** *"Open settings"*

**Strong prompt example:** *"Tap the profile icon in the top right, open Settings, and verify the notifications toggle is visible"*

Specific prompts produce more reliable tests and make CI failures easier to understand.

If you need to manage uploads programmatically outside GitHub Actions, see the API Reference tab.

## Notes

* Use `removeAfter` to auto-delete temporary uploads created during CI.
* Each project has a 2 GB storage limit.
* Our GitHub Action can upload the `.app` directory directly, so you do not need to zip it when running through GitHub Actions.