iOS Apps Instrumentation

Before you instrument and deploy an app for automation with Ranorex Studio, complete the following preparations.

Prepare the app

To instrument an iOS app, you need:

• IPA file
• The associated .p12 certificate and password
• The appropriate mobile provisioning profile

Make sure you can access the IPA, .p12, and mobile provisioning profile files from the computer on which Ranorex Studio is installed. It is recommended to store copies of these files in a folder on that computer.

Prepare the mobile device

Before you begin:

• Apply the required device settings
• Connect the device to the computer on which Ranorex Studio is installed
• Start the Ranorex Service App on the device.

Note: You can instrument and then immediately deploy the app to your mobile device with the Instrumentation Wizard. If you want to do so, you must connect the mobile device to your computer via USB (recommended).

Export the IPA using Xcode

Before you instrument the app in Ranorex Studio, export the IPA in Xcode.

1. In Xcode, select Any iOS Device (arm64) as a destination in the top bar:
2. Make sure you have selected the right provisioning profile under the General tab.
   
3. Select Product > Archive.
4. Once archived, click Distribute App located on the top right of the window.
   
5. On the next screen, select Release testing, and click Distribute.
   
6. Finally, on the last screen, click Export, and select a folder for the IPA to be saved.
   

Create the distribution certificate and provisioning profile

Create the signing assets required for instrumentation in the Apple Developer Portal.

1. Create a distribution certificate in the Apple Developer Portal.
2. Under Devices, add the device you want to test on.
3. Create an ad hoc provisioning profile, and make sure it includes:
   • The device UUID you added
   • The certificate you created.

Get your certificate in p12 format

The certificate must be in .p12 format. To export it in this format, open the Keychain Access app on macOS.

1. Open Keychain Access on macOS.
2. In the left panel, select the login keychain and open My Certificates.
3. Select both the certificate and its associated identity.
   
4. Right-click on both, then select Export 2 items…
   
5. Continue exporting and set a password; you will need it in the instrumentation process.

Instrument your app using the instrumentation wizard

Use the Instrumentation Wizard to instrument and deploy your app.

1. In Ranorex Studio, click Tools, and select Instrumentation Wizard.
   
2. On the next screen, select Instrument a mobile device and click Next.
   
3. On the next screen, select iOS, then click Next.
   
4. Select the device you previously added as an endpoint. Make sure it is connected to the computer via cable, then click Next.
   
5. Open the Mobile app testing tab and select the IPA, certificate, and provisioning profile, then enter the password and click Next.

6. The instrumentation process will start, and if everything goes well, you should see the next screen. There will be some warnings, but those are expected and harmless.

   Important: Starting from Ranorex 12.4.1, elevated privileges (e.g., Run as Administrator) are no longer required to run the Instrumentation Wizard.
   Re-instrumentation is required after upgrading to Ranorex 12.4.1. Even if they appear instrumented in the Instrumentation Wizard, the new method requires fresh instrumentation.

Manual Instrumentation

You can integrate instrumentation directly into your app's source code with manual instrumentation, eliminating the need for the Instrumentation Wizard described above.

1. Download the automation lib from the Mobile Download Archive on your Mac.
2. Open the XCode project of your application under test.
3. To avoid shipping an instrumented app to your customers it is recommended to create a separate target for your app under test. You should select the project file and duplicate the existing target.
   
4. Rename the newly created target.
   

5. Add the previously downloaded automation lib to your newly created target by dragging and dropping it into your project.

   Note: As XCode does not automatically update all necessary files, you have to rename them manually. You will have to alter the target itself, the targets .plist file (in the workspace as well as in Build Settings > Packaging), the targets’ project name (Build Settings > Packaging), and the scheme's name (Product > Manage Schemes).

1. Click Settings.
2. In the Settings window, configure the options for the instrumentation according to your needs.
   

Custom Options

• CollectionCapacity: Sets the maximum number of collection list items.
• PickerCapacity: Sets the maximum number of picker list items.
• Customization
• CodeDirectoryVersion: Sets code directory version for IPA. Use the drop-down list to select an option.
• Entitlements file: The path to the optional entitlement customized file. Look for codesign entitlements file usage for more details.

Instrumentation mode

• Resign only: When set to True, Ranorex will perform only changing the signature of the chosen IPA. By default, it should be set to False.
• Skip deployment: When set to True, Ranorex will not perform the deployment process. It means that Ranorex will not attempt to upload the chosen IPA file to the chosen endpoint. It may be useful if one wants to deploy the IPA using another device. By default, this option should be set to False
• Skip instrumentation: When set to True, Ranorex will not perform the default instrumentation process for the chosen IPA file, including the signing of the IPA. This option may be useful for deploying any IPA. By default, the value for this option is False.

Note: If the process fails, please first check you’ve applied the device settings correctly and connected the device properly. A common problem is also that another program is consuming too many resources, slowing down instrumentation to the point of a timeout error. Either close all other programs or increase the Instrumentation timeout in the settings.

Result

If the app has been instrumented and deployed correctly, you will see the following on your device:

1. The instrumented app appears in the Ranorex Service App.
2. The instrumented app appears on your device’s home screen.

Attention: After instrumenting and deploying the iOS app for the first time, start the app manually once. Otherwise, it will not be visible within the Ranorex Service App.

In Ranorex Studio, you can verify that the app has been instrumented correctly by checking if it appears in the selection list when creating a mobile test.