Instrumenting iOS Applications in Xcode (Legacy)

Supported Applications

Requirements

1. Add Test Devices to the Application Provisioning Profile

2. Create a Build Target for Testing

3. Add the TestComplete Agent Library to Your Project

4. Change Build Settings

5. Create an IPA File

Deploying the IPA File to Device

Other Preparatory Actions

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.

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 (Legacy).

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.

   

   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’s 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.

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:

   <TestComplete>\Bin\Extensions\iOS\libTestComplete-agent-static.a

   Copy or send this file to your Mac.

2. From Xcode’s 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.

   

   Click the image to enlarge it.

5. Click Add.

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.

   

   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.

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.

   

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.

   

   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.

   

2. From Xcode’s 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 TestComplete.

     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’s Preferences > Accounts dialog.

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 the project settings to automatically deploy the application to the test device during the test run.

For more information, see Deploying iOS Applications to Devices (Legacy).

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