Building Your iOS App for Simulator Testing

To test your iOS application on TestMu AI iOS Simulators, your app must be built specifically for the iOS Simulator platform. A build intended for a physical iPhone will not work on the Simulator, even if the CPU architecture matches. This guide walks you through creating a Simulator-compatible build and verifying it before uploading.

Why Simulator Builds Are Different

iOS apps are compiled with a Mach-O platform identifier that tells the system where the binary is meant to run:

Platform ID	Platform Name	Target
2	iphoneos	Physical iOS devices
7	iphonesimulator	iOS Simulator

Even when the CPU architecture (e.g., arm64) matches between device and Simulator builds, the two platforms link against different system libraries. The Simulator will reject a device build, typically resulting in an immediate crash.

Common Mistake

Building your app for a physical device (e.g., selecting Any iOS Device in Xcode) and then uploading it to the Simulator will cause an immediate crash with errors like "App quit unexpectedly." You must build targeting the iOS Simulator SDK.

Prerequisites

• Xcode installed on a Mac (macOS 13 or later recommended)
• Your iOS project source code
• A TestMu AI account with access to iOS Simulator testing

Method 1: Building via Xcode (UI)

This is the most common method. Xcode handles the platform switching automatically based on the Run Destination you select.

Step 1: Open your project (.xcodeproj or .xcworkspace) in Xcode.

Step 2: Click the scheme selector in the top toolbar. In the destination dropdown, choose a specific Simulator (e.g., iPhone 15 Pro) from the iOS Simulators section.

Step 3: Press Cmd + B or go to Product > Build to build the application.

Step 4: Locate the generated .app file:

• In the Project Navigator, expand the Products folder and right-click the .app file.
• Select Show in Finder to open its location.
• Alternatively, go to File > Project Settings > Derived Data to find the build output.

Step 5: Compress the .app file into a .zip archive:

• Right-click the .app file in Finder and select Compress.

The resulting .zip file is ready to upload to TestMu AI for Simulator testing.

Method 2: Building via Command Line (xcodebuild)

If you use a CI/CD pipeline or prefer the terminal, use xcodebuild with the -sdk iphonesimulator flag.

Step 1: Open Terminal and navigate to your project directory.

Step 2: Run the following build command:

xcodebuild -project YourProject.xcodeproj \
           -scheme YourScheme \
           -configuration Debug \
           -sdk iphonesimulator \
           -arch arm64 \
           build

tip

If your project uses a workspace (e.g., with CocoaPods), replace -project YourProject.xcodeproj with -workspace YourProject.xcworkspace.

Key flags explained:

Flag	Description
-sdk iphonesimulator	Targets the iOS Simulator platform (Platform 7) instead of physical devices
-arch arm64	Builds for the arm64 architecture (required for modern Mac hardware)
-configuration Debug	Uses the Debug build configuration (recommended for testing)

Step 3: Locate the .app output from the Derived Data directory. You can find the path in the build output, or use:

xcodebuild -project YourProject.xcodeproj \
           -scheme YourScheme \
           -configuration Debug \
           -sdk iphonesimulator \
           -arch arm64 \
           -showBuildSettings | grep "BUILT_PRODUCTS_DIR"

Step 4: Compress the .app into a .zip file:

cd /path/to/build/output/
zip -r YourApp.zip YourApp.app

The .zip file is now ready for upload.

Verifying Your Build

Before uploading, verify that your .app is targeting the correct platform using the vtool command.

Step 1: Run the following command:

vtool -show-build YourApp.app/YourApp

Replace the second YourApp with the actual binary name inside the .app bundle.

Step 2: Check the output:

• Correct (Simulator build):

  platform: IOSSIMULATOR

  or platform 7

• Incorrect (Device build):

  platform: IOS

  or platform 2

If the platform shows IOS or platform 2, the build is for physical devices and will not work on the Simulator. Rebuild using one of the methods above.

Alternative Verification

You can also use otool to check the architecture:

lipo -info YourApp.app/YourApp

This displays the architectures included in the binary (e.g., arm64).

Uploading to TestMu AI

Once you have a verified Simulator build (.zip containing the .app):

1. Log in to your TestMu AI account.
2. Navigate to App Testing > iOS Simulators.
3. Upload the .zip file containing your .app build.
4. Select the desired Simulator device and iOS version.
5. Start your testing session.

Key Xcode Build Settings

If your build still targets the wrong platform, check these settings in Xcode under Build Settings:

Setting	Value for Simulator
Architectures	$(ARCHS_STANDARD)
Base SDK	iOS
Supported Platforms	iOS Simulator
Validate Built Product	No (for Debug/Simulator builds)

Troubleshooting

App crashes immediately on the Simulator

Your .app is likely built for physical devices (Platform 2). Verify the platform using vtool as described above, and rebuild targeting the Simulator SDK.

"No .app found inside zip" error

Ensure you are compressing the .app bundle directly into a .zip file. The .app should be at the root level of the archive, not nested inside additional folders.

Build fails with architecture errors

Ensure the -arch arm64 flag is set. Your Simulator build must include the arm64 architecture.

---

That's all! In case you have any questions or need any additional information, you could reach out at our 24X7 Chat Support or mail us directly at [email protected].