iOS apps

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

To begin with the instrumentation of your iOS app, follow these previous steps:

Export your iOS app

Create the distribution certificate and the provisioning profile

1. Create a distribution certificate from your Apple Developer Portal: https://developer.apple.com/account/resources/certificates/list
2. Under the devices section, add the device you want to test on: https://developer.apple.com/account/resources/devices/list
3. Create an ad-hoc Provisioning Profile, and make sure you select the device UUID you just added in step 1, and also that the linked Certificate is the one you just created in step 2.: https://developer.apple.com/account/resources/profiles/list

Export the IPA using 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.
   

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.

In the left panel, select the login Keychain, then navigate to the My Certificates tab. Next, select both the certificate and its associated identity.

Right click on both, then select “Export 2 items…”

Continue exporting and set a password, you will need it in the instrumentation process.

Instrument your app using the instrumentation wizard

1. Go to Ranorex, 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. In the next dialog, select the device you have previously added as an endpoint. Please make sure that it is connected to the machine running Ranorex via cable, and click Next.
   
5. In the next screen, select the “mobile app testing” tab. Select the previously generated IPA, certificate, and provisioning profile. Set the password and click “Next”.
   
6. The instrumentation process will start, and if everything goes well, you should see the next screen. There will appear some warnings, but those are expected and harmless.
   

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.
   
   
   

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

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

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

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