iOS apps

In this chapter learn how to instrument an iOS app.

tipp 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

    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

    Start the Instrumentation Wizard and confirm the Windows security dialog.

    Select iOS and click Next.

    Specify IPA and settings

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

    Click Browse… and browse the IPA file.

    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.

    Enter the password for the p12 file and click Next.

    The app has been instrumented successfully.

    Configure Manually

    Click Settings.
    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.


    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.

    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
    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:

    The instrumented app appears in the Ranorex Service App.

    The instrumented app appears on your device’s home screen.

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