How to Configure Your App for iOS VM Testing

Learn the different ways to make your iOS app available for testing.

Setting Up iOS Builds

To run tests on an iOS VM, follow these steps to set up your app as a .app file. Make sure to install the Xcode command line tools.

Generate a simulator build using the xcodebuild command. To create simulator builds, you must build your app for x86 64-bit. The command you run to create the build should look similar to this:

xcodebuild ENABLE_BITCODE=NO -workspace
'/path/to/YourWorkspace.xcworkspace' -scheme 'myScheme' -arch x86_64
-sdk iphonesimulator
ENABLE_BITCODE=NOTurns off bitcode for the build.
-workspaceTakes your .xcworkspace file.
-schemeThis is the build scheme.
Note that you can also use -project myproject.xcodeproj or -target myTarget, depending on your setup.
-arch x86_64Sets the build to 64-bit, which allows it to run on simulators.
If you need to build a 32-bit version, use -arch i386. Apple deprecated 32-bit support in iOS 11, so most builds should be 64-bit. Note that your app must be built with one of these to run on simulators.
-sdk iphonesimulatorSets the sdk to simulator.
If you want a specific SDK, you can list your installed SDKs using the command xcodebuild -showsdks and changing the option to be explicit: -sdk iphonesimulator11.1.

Depending on your setup, you may need to use the option -configuration 'Debug' or -configuration 'Release'. For more information on xcodebuild, see Apple’s developer documentation.



  • Test your app on a local iOS simulator by dragging and dropping the file onto your local Xcode simulator. If it doesn’t work in your local simulator, it won’t work in ours.
  • Zip the .app file. Rainforest supports .zip, .tar and .gz.
  • Make sure the file is not .ipa, which would only work on real devices, whereas .app can be used on simulators.
  • Use lipo tool to confirm that your binary supports x86_64 architecture

Uploading Your Application to Rainforest

After setting up your application for testing, there are 3 options for uploading the app to Rainforest:

  • Uploading in-app
  • Uploading via the CLI
  • Uploading via a direct download link

If your app doesn’t load properly, check out Troubleshooting Mobile Builds.

Uploading Your Mobile App In-App

Rainforest allows mobile app uploads in your Sites and Environments settings.

  1. Click the Settings icon (gear) in the navigation bar, then click Sites.
  2. Select the Apps tab, then click the New Mobile Site link.
  3. Give the app a unique name.
  4. Select the appropriate app type and add any URL. Then, click Done.
  5. Click the Edit icon (pencil) next to the app you added. Then, click the Upload button.

Uploading your mobile app using the UI.

Uploading Your Mobile App via the CLI

To upload your mobile app via the CLI, install the Rainforest command-line interface. For more information, see How to Install the CLI.

  1. After setup, use the following CLI command to view your list of environments:
    rainforest environments --token YOUR_TOKEN
  2. Use this command to view your list of sites:
    rainforest sites --token YOUR_TOKEN
  3. Look up the relevant site ID and environment ID using the Sites and Environments page in Rainforest.
  4. Use this command to upload your app.
    rainforest mobile-upload --token YOUR_TOKEN --site-id 1234 --environment-id 5678 my_app.apk
    Note: Rainforest stores your app in a secure, nonpublic location.
  5. Return to the Settings page to view your newly uploaded app.

Rainforest stores your app in a secure location.

Setting Up Your iOS Application File as a Direct Download Link

Use a direct download link as an alternative to uploading your app via the CLI or in-app.

  1. Generate a simulator build using the xcodebuild command. See Setting Up iOS Builds.
  2. Host your app somewhere that supports direct downloads. The hosted file URL must be a direct download link.
  3. Go to Settings > Sites.
  4. Under Apps, click the New Mobile Site link and set the type to “iOS VM.”
  5. Add the URL for your direct download.

Rainforest automatically downloads and installs your iOS application on our VMs from this URL when you run a mobile test.


Keying in a direct download link.

Adding Multiple Applications

  1. Use the "+ New Mobile Site" button to add another mobile application
  2. Repeat one of the options above to add more applications

If you have any questions, reach out to us at [email protected].