Welcome to the Ranorex Support Portal

iOS apps

In this chapter learn how to instrument an iOS app.

Note Icon


For iOS developers: As part of the instrumentation process, the app will be compiled with the Ranorex automation library. This library adds additional functions and permissions to your IPA.

Do NOT publish instrumented apps to the App Store.

Instrumented apps do not work with TestFlight.

In this chapter

Prepare the app and the mobile device

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

Prepare the app

To instrument an iOS app, you will need the IPA file, the associated P12 certificate and password, and the proper 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. We recommend you store a copy of them in a folder on that computer.

Prepare the mobile device

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


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

Instrumentation example

As an example, let’s instrument the KeyPass app. The KeyPass app is available under the GNU General Public License. For information regarding the copyright holder and the license agreement, go to https://keepass.info/help/v1/license.html.

In the previous section of the instrumentation process, the IPA, the P12 certificate and the mobile provisioning profile were stored in the folder iOS app testing on the computer where Ranorex Studio is installed on.

Select technology

  1. Start the Instrumentation Wizard and confirm the Windows security dialog.

  2. Select iOS and click Next.

Specify IPA and settings

  1. Do not change the default setting Instrument & deploy custom IPA, this instruments and deploys the app to the mobile device. Click Next.

  2. Click Browse… and browse the IPA file.

  3. Add the provisioning profile and the p12 file by clicking Browse… The provisioning profile and the p12 file can be obtained from the Apple Developer portal.

  4. Enter the password for the p12 file and click Next.

  1. The app has been instrumented successfully.

Configure Manually

  1. Click Settings.

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

  1. Custom Options

  • CollectionCapacity: Sets the maximum number of collection list items.
  • PickerCapacity: Sets the maximum number of picker list items.
  1. Customization

  • CodeDirectoryVersion: Sets code directory version for IPA. Use the drop-down list to select an option.
  • Entitlements file: The path to optional entitlement customized file. Look for codesign entitlements file usage for more details.
  1. Instrumentation mode

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


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.


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.

Note Icon


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 see the app has been instrumented correctly if it appears for selection when creating a mobile test.



Get the latest test automation information right in your mailbox.


© 2024 Ranorex GmbH. All Rights Reserved