Instrumenting iOS Applications in Xcode

Applies to TestExecute 15.40, last modified on May 21, 2024

This topic describes how to prepare iOS applications in Xcode 9 - 12.3 for testing.

Do not submit instrumented applications to the App Store. Instrumented applications use private APIs and will be rejected. Create a separate build configuration for test builds.

We recommend instrumenting your applications in TestComplete UI instead of Xcode. To learn how to do it, please see the TestComplete documentation.

Supported Applications

Information in this topic applies to Objective-C and Swift iOS applications created in Xcode 9 - 12.3.


  • A Mac computer with Xcode 9 - 12.3, iOS SDK and an iOS development license.

  • Access to a Windows computer with TestComplete installed.

1. Add Test Devices to the Application Provisioning Profile

If you have the iOS Developer Program (not the iOS Developer Enterprise Program), your application can run only on test devices specified in the provisioning profile for the application. You need to add the test devices to the provisioning profile before you build the application. For instructions, see Registering iOS Devices for Testing.

2. Create a Build Target for Testing

To keep your release builds intact, create a new build target for test builds:

  1. Open your application project in Xcode.

  2. Select the project in the Navigator area to view the list of targets.

  3. Right-click the target you want to test and select Duplicate from the context menu.

    iOS testing with TestComplete: Duplicating the build target in Xcode

    Xcode will make a copy of this target with the name App_Name copy.

  4. Rename the new target to App_Name TestComplete or similar to mark it as a test-only build.

  5. Rename the target’s scheme, settings and associated files to match the new target name:

    • From Xcode menu, select Product > Scheme > Manage Schemes and rename the scheme from App_Name copy to App_Name TestComplete.

    • In the project navigator, rename the App_Name copy-Info.plist file to App_Name TestComplete.plist.

    • In the target’s Build Settings, under the Packaging section:

      • Set Info.plist File to App_Name TestComplete.plist.

      • Set Product Name to App_Name TestComplete.

3. Add the TestComplete Agent Library to Your Project

You need to compile your iOS application with the TestComplete Agent library.

If your application was prepared for testing with an earlier version of the TestComplete Agent library, it will be unavailable to newer versions TestComplete. To avoid this issue, recompile the application with the library that is shipped with your current TestComplete version.

To add the library to your project, do the following:

  1. On a Windows computer with TestComplete installed, find the following file:


    Copy or send this file to your Mac.

  2. From Xcode menu, select File > Add Files to App_Name.

  3. In the dialog that appears, select the libTestComplete-agent-static.a file.

  4. In the Add to targets list, select only your test build target and unselect the other targets.

    iOS testing with TestComplete: Adding TestComplete Agent library to Xcode project

    Click the image to enlarge it.

  5. Click Add.

4. Change Build Settings

To configure the build settings for test builds:

  1. In Xcode, select your project in the Navigator area.

  2. Select the App_Name TestComplete target to view its settings.

  3. Switch to the Build Settings page.

  4. Under the Linking section, set Other Linker Flags setting to -all_load -ObjC.

    iOS testing with TestComplete: Setting target linker flags

    Click the image to enlarge it.

  5. (Only if you use Xcode 8 and later) Under the Build Settings section, set the Enable Bitcode setting to No.

5. Create an IPA File

An IPA file is an iOS application archive file that contains the application. You need to create an IPA file to distribute your application to testers or automatically install it on a device from tests.

The first time you create an IPA file, configure the archiving settings to archive the release (not debug) version of your application:

  1. In Xcode, select Edit Scheme from the Scheme toolbar menu.

    iOS testing  with TestComplete: Editing scheme in Xcode
  2. Select App_Name TestComplete from the Scheme menu at the top of the dialog.

  3. Select Archive in the left column.

  4. Set Build Configuration to Release and click Close.

    iOS testing with TestComplete: Archive settings in Xcode

    Click the image to enlarge it.

To create an IPA file:

  1. From the Scheme toolbar menu in Xcode, select the App_Name TestComplete scheme. In the submenu, select either iOS Device or the connected device’s name.

    iOS testing with TestComplete: Selecting build configuration in Xcode
  2. From Xcode menu, select Product > Archive and follow the instructions to complete the process.

    Xcode will display the created archive in the Archives organizer.

  3. Select the created archive and click Export.

  4. In the subsequent dialog, select one of the following options:

    • Save for Development Deployment (available in Xcode 8 and later), or
    • Save for Ad Hoc Deployment, or
    • Save for Enterprise Deployment

    The option to choose depends on the developer program you have:

    • If you have the iOS Developer Program (not the iOS Developer Enterprise Program), select Save for Development Deployment. This way you will be able to run your iOS application from TestExecute.

      To use the Enterprise option, you need to have the iOS Developer Enterprise Program.

    • If you have the iOS Developer Enterprise Program, you can select any of these options. We recommend that you choose Save for Development Deployment.

  5. Xcode will display the production provisioning profile it chose for your .ipa file. Click Save to complete the file creation.

    If Xcode chose an incorrect profile, cancel the file creation dialog and modify your certificates and provisioning profile settings in Apple’s Member Center, the Keychain Access application on your Mac and Xcode Preferences > Accounts dialog.

Deploying the IPA File to Device

You can either deploy the IPA file to your device manually, or configure TestComplete to automatically install it on devices as part of tests. To do this:

  1. Copy or send the IPA file from your Mac to the TestComplete computer.

  2. Add this IPA file as a tested application to your TestComplete project.

  3. Configure your TestComplete project to deploy the application to the test device during the test run automatically.

To learn how to do it, see the Deploying iOS Applications to Devices section in the TestComplete documentation.

Other Preparatory Actions

Before you can test your iOS application with TestComplete, you also need to configure the TestComplete computer. For more information, see Preparing Test Computers for iOS Testing.

See Also

Preparing iOS Applications
Preparing Test Computers for iOS Testing
Preparing iOS Devices

Highlight search results