About Instrumenting iOS Applications (Legacy)

Applies to TestComplete 15.65, last modified on July 17, 2024
The information below concerns legacy mobile tests that work with mobile devices connected to the local computer. For new mobile tests, we recommend using the newer cloud-compatible approach.

This topic explains how to prepare an iOS application for testing with TestComplete.

Why Preparation Is Needed

The preparation (or instrumentation) of tested iOS applications is mandatory. You cannot test iOS applications without preparing them for TestComplete.

If an application was prepared for TestComplete, the latter recognizes individual controls in that application and provides control-specific methods and properties that help you simulate user actions on controls. This helps you create powerful tests that you can port to various iOS devices easily.

We call instrumented iOS applications white-box or iOS Open Applications (as they are “open” to TestComplete).

You can instrument your tested iOS application in Xcode, in TestComplete UI, in your test scripts.

What Instrumentation Means

To instrument an iOS application, you need to compile it with the TestComplete-agent-static.a library. This library is part of the TestComplete package. You can find it in the <TestComplete>\Bin\Extensions\iOS folder.

In addition, you need certain certificate files for validating the application after you recompile it (see below).


  • During the instrumentation, TestComplete does not change the application’s source code.

  • TestComplete does not change your application in any way, except for signing it with new developer certificate files and compiling in the library. It does not change the binary code of your functions, it does not change resources and text constants in your code. In other words, instrumentation does not change the application’s functionality.

  • Instrumented applications consume a bit more memory on the device due to the library code, which TestComplete adds to them.

  • You cannot undo instrumentation. If you need an uninstrumented version of your application, restore it from the backup copy.

What Are Developer Certificate Files

To run tests against the iOS application, it must be verified as created by a trusted developer and designated to run on the specified test devices. Developed certificates do this.

In Xcode and Xamarin Studio, you can choose what certificates to use (they will use the certificate data stored on your Mac computer). TestComplete does not have access to this data, so you need to export them to instrument the application in TestComplete. For detailed information on these files and the way to obtain them, see Get Certificate Files (Legacy).

Recommended Provisioning Profile

To perform testing with TestComplete, we recommend that you use the iOS App Development profile for your applications. In this case, you will be able to automate the deployment of the tested applications to your iOS devices and launching the applications on them with specific TestComplete scripting methods or keyword-test operations.

If you use a distribution profile, you will be able to use TestComplete methods and keyword-test operations to automate application deployment to your devices. However, you will be unable to launch your tested applications on devices by using specific TestComplete scripting methods and keyword-test operations. You will have to launch the applications manually, or find a way to automate their start.

TestComplete does not support testing iOS applications signed with the App Store profile.

Instrumentation Steps

You can instrument your iOS applications in various ways:

Other Preparatory Actions

In addition to instrumenting the application, you also need to prepare the TestComplete computer and your iOS device. For complete information on these actions, see the other topics of the Testing iOS Applications (Legacy) section.

Known Issues and Limitations

  • After you update TestComplete, you need to reinstrument your iOS applications for the new TestComplete version.
    If you use the current version of TestComplete with applications instrumented for previous TestComplete versions, your device may stop responding. If this happens, restart the device by holding down the power and home buttons for about 10 seconds.

  • We recommend that you update your iTunes to the latest version before running tests on iOS devices. Older versions of iTunes may cause issues in your tests.

  • Xamarin applications built to support both 32-bit and 64-bit platforms will not run on 32-bit platforms if they are instrumented in TestComplete. Instrument such applications manually in Xamarin Studio.

  • You cannot instrument applications downloaded from the App Store.

  • Do not submit TestComplete-enabled builds to the App Store. The TestComplete Agent library uses private APIs, so the applications that use it will be rejected. Create a separate build target for test builds.

Sample Application

TestComplete includes the sample Orders application you can use to learn how to prepare and test iOS applications in TestComplete:

<TestComplete Samples>\Mobile\iOS\Orders\Orders Application

Note: If you do not have the sample, download the TestComplete Samples installation package from the support.smartbear.com/testcomplete/downloads/samples page of our website and run it.

See Also

Preparing iOS Applications (Legacy)
Testing iOS Applications - Overview (Legacy)

Highlight search results