To work with objects in an iOS application, you need to instrument it. This topic explains how you can do this from scripts.

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.

Instrumentation Procedure

⇒ 1. Adding an IPA File to Your Test Project as a Tested Application

⇒ 2. Checking if Your Application Is Already Instrumented

⇒ 3. Setting Up Instrumentation Parameters

⇒ 4. Instrumenting Your Application

Setting up Files Used to Instrument the Application

An Example of Full Instrumentation

General Information

Instrumentation is needed to expose internal objects, methods and properties of iOS applications to TestComplete.

To instrument an iOS application, TestComplete recompiles it with the TestComplete-agent-static.a library and new certificates that allow the developers to use the application. This procedure includes the following steps:

Adding your .ipa file to the TestComplete project as a tested application (this is a requirement).
(Optional) Creating a backup copy of your original .ipa file.
Modifying and recompiling the .ipa file using the developer certificates.
Overwriting the original .ipa file with its instrumented version.

You can automate all these operations in your tests by using the methods and properties of the iOSTestedApp object that corresponds to your tested iOS application. See detailed information below.

Instrumentation Requirements

The application you instrument cannot be already instrumented in Xcode. If you try to instrument such an application, it will not work.
To instrument the application, TestComplete uses a number of certificates. You need to get them as described in the Getting Certificate Files topic
TestComplete replaces the existing .ipa file with its instrumented version. So, the user account under which TestComplete is working needs read/write access to this file.

Instrumentation Procedure

1. Adding an IPA File to Your Test Project as a Tested Application

To instrument your iOS application, first, you need to add it to the Tested Applications list of your project. You can do this either manually or by using the TestedApps.AddiOSApp method. After that, you can use the methods and properties of the iOSTestedApp object.

2. Checking if Your Application Is Already Instrumented

Before instrumenting an application, you need to make sure that it has not been instrumented yet. To do this, use the Instrumented property. This property returns true if the application is instrumented and false otherwise.

If the application was instrumented in Xcode, the Instrumented property will return false. Use the uninstrumented version or the version that was instrumented in TestComplete.

If your application was instrumented for an earlier or later TestComplete version, it will not be recognized as Open. You need to use either an uninstrumented application, or an application instrumented for the current TestComplete version. To check if TestComplete can work with your application, use the InstrumentedWithSupportedVersion property. This property returns true if TestComplete can work with the application and false otherwise. If you use both properties, you can create a conditional statement to check if the application can be tested, if it needs to be instrumented or if you need to use a different .ipa file.

JavaScript, JScript

if (!iOSTestedApp.Instrumented)
{
  // Instrument the application
}

if (iOSTestedApp.InstrumentedWithSupportedVersion)
{
  // Launch the application
}
else
{
  // Post an error to the log
}

Python

if not iOSTestedApp.Instrumented:
  # Instrument the application

if (iOSTestedApp.InstrumentedWithSupportedVersion):
  # Launch the application
else:
  # Post an error to the log

VBScript

If not iOSTestedApp.Instrumented Then
  ' Instrument the application
End If

If iOSTestedApp.InstrumentedWithSupportedVersion Then
  ' Launch the application
Else
  ' Post an error to the log
End If

DelphiScript

if not iOSTestedApp.Instrumented then
begin
  // Instrument the application
end;

if iOSTestedApp.InstrumentedWithSupportedVersion then
begin
  // Launch the application
end
else
begin
  // Post an error to the log
end;

C++Script, C#Script

if (!iOSTestedApp["Instrumented"])
{
  // Instrument the application
}

if (iOSTestedApp["InstrumentedWithSupportedVersion"])
{
  // Launch the application
}
else
{
  // Post an error to the log
}

3. Setting Up Instrumentation Parameters

By default, TestComplete backs up the original application file to instrument the application. If you are satisfied with the default settings, you can skip this step.

When TestComplete is instrumenting an application, it creates a backup of the original file in the same folder and names it "FileName_ORIGINAL_BACKUP.ipa". You can change this behavior by using the BackupOriginalIPA and BackupFileName settings.

If you don't want to create a copy of the file, set the BackupOriginalIPA property to false. To make sure that a backup will be created, set the property to true.
To save the backup file to a specific location, pass a string containing the fully qualified path to the BackupFileName property.

Below is an example of how you can set backup settings to save the backup file to the specified folder:

JavaScript, JScript

iOSTestedApp.BackupOriginalIPA = true;
iOSTestedApp.BackupFileName = "C:\\iOS\\apks\\SampleApp_ORIGINAL_BACKUP.ipa";

Python

iOSTestedApp.BackupOriginalIPA = True;
iOSTestedApp.BackupFileName = "C:\\iOS\\apks\\SampleApp_ORIGINAL_BACKUP.ipa";

VBScript

iOSTestedApp.BackupOriginalIPA = true
iOSTestedApp.BackupFileName = "C:\iOS\apks\SampleApp_ORIGINAL_BACKUP.ipa"

DelphiScript

iOSTestedApp.BackupOriginalIPA := true;
iOSTestedApp.BackupFileName := 'C:\iOS\apks\SampleApp_ORIGINAL_BACKUP.ipa';

C++Script, C#Script

iOSTestedApp["BackupOriginalIPA"] = true;
iOSTestedApp["BackupFileName"] = "C:\\iOS\\apks\\SampleApp_ORIGINAL_BACKUP.ipa";

Setting up Files Used to Instrument the Application

TestComplete uses developer certificate files to instrument the application. You need to provide the path to the following files:

Apple WWDR file
Developer certificate file
PEM file
Provisioning profile file

To learn more about these files and the way to get them, see Getting Certificate Files Below is an example of how you can set the path to these files:

JavaScript, JScript

iOSTestedApp.UseCustomCertificate = true;
iOSTestedApp.AppleWWDRCAPath = "C:\\iOS\\AppleWWDRCA.cer";
iOSTestedApp.DeveloperCertPath = "C:\\iOS\\Certificates.cer";
iOSTestedApp.DeveloperPemPath = "C:\\iOS\\Certificates.pem";
iOSTestedApp.ProvisioningPath = "C:\\iOS\\iOS_Provisioning_Profile.mobileprovision";

Python

iOSTestedApp.UseCustomCertificate = True;
iOSTestedApp.AppleWWDRCAPath = "C:\\iOS\\AppleWWDRCA.cer";
iOSTestedApp.DeveloperCertPath = "C:\\iOS\\Certificates.cer";
iOSTestedApp.DeveloperPemPath = "C:\\iOS\\Certificates.pem";
iOSTestedApp.ProvisioningPath = "C:\\iOS\\iOS_Provisioning_Profile.mobileprovision";

VBScript

iOSTestedApp.UseCustomCertificate = true
iOSTestedApp.AppleWWDRCAPath = "C:\iOS\AppleWWDRCA.cer"
iOSTestedApp.DeveloperCertPath = "C:\iOS\Certificates.cer"
iOSTestedApp.DeveloperPemPath = "C:\iOS\Certificates.pem"
iOSTestedApp.ProvisioningPath = "C:\iOS\iOS_Provisioning_Profile.mobileprovision"

DelphiScript

iOSTestedApp.UseCustomCertificate := true;
iOSTestedApp.AppleWWDRCAPath := 'C:\iOS\AppleWWDRCA.cer';
iOSTestedApp.DeveloperCertPath := 'C:\iOS\Certificates.cer';
iOSTestedApp.DeveloperPemPath := 'C:\iOS\Certificates.pem';
iOSTestedApp.ProvisioningPath := 'C:\iOS\iOS_Provisioning_Profile.mobileprovision';

C++Script, C#Script

iOSTestedApp["UseCustomCertificate"] = true;
iOSTestedApp["AppleWWDRCAPath"] = "C:\\iOS\\AppleWWDRCA.cer";
iOSTestedApp["DeveloperCertPath"] = "C:\\iOS\\Certificates.cer";
iOSTestedApp["DeveloperPemPath"] = "C:\\iOS\\Certificates.pem";
iOSTestedApp["ProvisioningPath"] = "C:\\iOS\\iOS_Provisioning_Profile.mobileprovision";

4. Instrumenting Your Application

To instrument an application, use the Instrument method. The method recompiles your application and overwrites the original .ipa file with its instrumented version. There is no need to pass any parameters to it. The method uses the values you assigned to the properties of the iOSTestedApp object:

JavaScript, JScript

...
// Setting properties
...
iOSTestedApp.Instrument();
...

Python

...
# Setting properties
...
iOSTestedApp.Instrument();
...

VBScript

...
' Setting properties
...
iOSTestedApp.Instrument()
...

DelphiScript

...
// Setting properties
...
iOSTestedApp.Instrument();
...

C++Script, C#Script

...
// Setting properties
...
iOSTestedApp["Instrument"]();
...

An Example of Full Instrumentation

The sample code below demonstrates how to add a new iOS application to the list of tested applications, specify the application’s properties and run the application.

JavaScript, JScript

function AddiOSApplication()
{

  // Sets the current device
  Mobile.SetCurrent("MyDevice");

  // Adds the iOS application from the package and obtains its index in the list of tested applications
  var ind = TestedApps.AddiOSApp("C:\\iOS\\ipas\\SampleApp.ipa");

  // Obtains the added tested application by its index and specifies its properties
  var iOSTestedApp = TestedApps.Items(ind);
  iOSTestedApp.DeployOnStart = true;
  iOSTestedApp.Launch = true;

  // Checks if the applications is instrumented
  if (!iOSTestedApp.Instrumented)
  {
    // Sets up backup parameters
    iOSTestedApp.BackupOriginalIPA = true;
    iOSTestedApp.BackupFileName = "C:\\iOS\\ipas\\SampleApp_ORIGINAL_BACKUP.ipa";
    // Sets up paths to certificate files
    iOSTestedApp.AppleWWDRCAPath = "C:\\iOS\\AppleWWDRCA.cer";
    iOSTestedApp.DeveloperCertPath = "C:\\iOS\\Certificates.cer";
    iOSTestedApp.DeveloperPemPath = "C:\\iOS\\Certificates.pem";
    iOSTestedApp.ProvisioningPath = "C:\\iOS\\iOS_Provisioning_Profile.mobileprovision";
    iOSTestedApp.Instrument();
  }

  // Checks if TestComplete can work with the instrumented application
  if (iOSTestedApp.InstrumentedWithSupportedVersion)
  {
    // Launches the application
    iOSTestedApp.Run();
  }
  else
  {
    // Posts an error to the log
    Log.Error("Please use uninstrumented application or application instrumented for the current TestComplete version");
  }
}

Python

def AddiOSApplication():

  # Sets the current device
  Mobile.SetCurrent("MyDevice")

  # Adds the iOS application from the package 
  # and obtains its index in the list of tested applications
  ind = TestedApps.AddiOSApp("C:\\iOS\\ipas\\SampleApp.ipa")

  # Obtains the added tested application by its index 
  # and specifies its properties
  iOSTestedApp = TestedApps.Items(ind)
  iOSTestedApp.DeployOnStart = True
  iOSTestedApp.Launch = True
  
  # Checks if the applications is instrumented
  if not iOSTestedApp.Instrumented:
    # Sets up backup parameters
    iOSTestedApp.BackupOriginalIPA = True
    iOSTestedApp.BackupFileName = "C:\\iOS\\ipas\\SampleApp_ORIGINAL_BACKUP.ipa"
    # Sets up paths to certificate files
    iOSTestedApp.AppleWWDRCAPath = "C:\\iOS\\AppleWWDRCA.cer"
    iOSTestedApp.DeveloperCertPath = "C:\\iOS\\Certificates.cer"
    iOSTestedApp.DeveloperPemPath = "C:\\iOS\\Certificates.pem"
    iOSTestedApp.ProvisioningPath = "C:\\iOS\\iOS_Provisioning_Profile.mobileprovision"
    # Instruments the application
    iOSTestedApp.Instrument()

  # Checks if TestComplete can work with the instrumented application
  if iOSTestedApp.InstrumentedWithSupportedVersion:
    # Launches the application
    iOSTestedApp.Run()
  else:
    # Posts an error to the log
    Log.Error("Please use uninstrumented application or application \
      instrumented for the current TestComplete version")

VBScript

Sub AddiOSApplication

  ' Sets the current device
  Mobile.SetCurrent("MyDevice")

  ' Adds the iOS application from the package and obtains its index in the list of tested applications
  ind = TestedApps.AddiOSApp("C:\iOS\ipas\SampleApp.ipa")

  ' Obtains the added tested application by its index and specifies its properties
  Set iOSTestedApp = TestedApps.Items(ind)
  iOSTestedApp.DeployOnStart = True
  iOSTestedApp.Launch = True

  ' Checks if the applications is instrumented
  If not iOSTestedApp.Instrumented Then
    ' Sets up backup parameters
    iOSTestedApp.BackupOriginalIPA = true
    iOSTestedApp.BackupFileName = "C:\iOS\ipas\SampleApp_ORIGINAL_BACKUP.ipa"
    ' Sets up paths to certificate files
    iOSTestedApp.AppleWWDRCAPath = "C:\iOS\AppleWWDRCA.cer"
    iOSTestedApp.DeveloperCertPath = "C:\iOS\Certificates.cer"
    iOSTestedApp.DeveloperPemPath = "C:\iOS\Certificates.pem"
    iOSTestedApp.ProvisioningPath = "C:\iOS\iOS_Provisioning_Profile.mobileprovision"
    ' Instruments the application
    iOSTestedApp.Instrument()
  End If

  ' Checks if TestComplete can work with the instrumented application
  If iOSTestedApp.InstrumentedWithSupportedVersion Then
    ' Launches the application
    iOSTestedApp.Run()
  Else
    ' Posts an error to the log
    Log.Error("Please use uninstrumented application or application instrumented for the current TestComplete version")
  End If
End Sub

DelphiScript

procedure AddiOSApplication();
var
  ind, iOSTestedApp;
begin

  // Sets the current device
  Mobile.SetCurrent('MyDevice');

  // Adds the iOS application from the package and obtains its index in the list of tested applications
  ind := TestedApps.AddiOSApp('C:\iOS\ipas\SampleApp.ipa');

  // Obtains the added tested application by its index and specifies its launch properties
  iOSTestedApp := TestedApps.Items[ind];
  iOSTestedApp.DeployOnStart := true;
  iOSTestedApp.Launch := true;

  // Checks if the applications is instrumented
  if not iOSTestedApp.Instrumented then
  begin
    // Sets up backup parameters
    iOSTestedApp.BackupOriginalIPA := true;
    iOSTestedApp.BackupFileName := 'C:\iOS\ipas\SampleApp_ORIGINAL_BACKUP.ipa';
    // Sets up paths to certificate files
    iOSTestedApp.AppleWWDRCAPath := 'C:\iOS\AppleWWDRCA.cer';
    iOSTestedApp.DeveloperCertPath := 'C:\iOS\Certificates.cer';
    iOSTestedApp.DeveloperPemPath := 'C:\iOS\Certificates.pem';
    iOSTestedApp.ProvisioningPath := 'C:\iOS\iOS_Provisioning_Profile.mobileprovision';
    // Instruments the application
    iOSTestedApp.Instrument();
  end;

  // Checks if TestComplete can work with the instrumented application
  if iOSTestedApp.InstrumentedWithSupportedVersion then
    // Launches the application
    iOSTestedApp.Run()
  else
    // Posts an error to the log
    Log.Error('Please use uninstrumented application or application instrumented for the current TestComplete version');
end;

C++Script, C#Script

function AddiOSApplication()
{

  // Sets the current device
  Mobile["SetCurrent"]("MyDevice");

  // Adds the iOS application from the package and obtains its index in the list of tested applications
  var ind = TestedApps["AddiOSApp"]("C:\\iOS\\ipas\\SampleApp.ipa");

  // Obtains the added tested application by its index and specifies its properties
  var iOSTestedApp = TestedApps["Items"](ind);
  iOSTestedApp["DeployOnStart"] = true;
  iOSTestedApp["Launch"] = true;

  // Checks if the applications is instrumented
  if (!iOSTestedApp["Instrumented"])
  {
    // Sets up backup parameters
    iOSTestedApp["BackupOriginalIPA"] = true;
    iOSTestedApp["BackupFileName"] = "C:\\iOS\\ipas\\SampleApp_ORIGINAL_BACKUP.ipa";
    // Sets up paths to certificate files
    iOSTestedApp["AppleWWDRCAPath"] = "C:\\iOS\\AppleWWDRCA.cer";
    iOSTestedApp["DeveloperCertPath"] = "C:\\iOS\\Certificates.cer";
    iOSTestedApp["DeveloperPemPath"] = "C:\\iOS\\Certificates.pem";
    iOSTestedApp["ProvisioningPath"] = "C:\\iOS\\iOS_Provisioning_Profile.mobileprovision";
    // Instruments the application
    iOSTestedApp["Instrument"]();
  }

  // Checks if TestComplete can work with the instrumented application
  if (iOSTestedApp["InstrumentedWithSupportedVersion"])
  {
    // Launches the application
    iOSTestedApp["Run"]();
  }
  else
  {
    // Posts an error to the log
    Log["Error"]("Please use uninstrumented application or application instrumented for the current TestComplete version");
  }
}

Instrumenting iOS Applications From Scripts

General Information

Instrumentation Requirements

Instrumentation Procedure

1. Adding an IPA File to Your Test Project as a Tested Application

2. Checking if Your Application Is Already Instrumented

3. Setting Up Instrumentation Parameters

Setting up Files Used to Instrument the Application

4. Instrumenting Your Application

An Example of Full Instrumentation

See Also