In this article, learn how to instrument your iOS app for automation with Ranorex Studio.
Prepare the app and the mobile device
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.
Export the IPA using Xcode
Before you instrument the app in Ranorex Studio, export the IPA in Xcode.
- In Xcode, select Any iOS Device (arm64) as a destination in the top bar:
-
Make sure you have selected the right provisioning profile under the General tab.
- Select Product > Archive.
- Once archived, click Distribute App located on the top right of the window.
- On the next screen, select Release testing, and click Distribute.
- 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.
- Create a distribution certificate in the Apple Developer Portal.
- Under Devices, add the device you want to test on.
- 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.
- Open Keychain Access on macOS.
- In the left panel, select the login keychain and open My Certificates.
- 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
Use the Instrumentation Wizard to instrument and deploy your app.
- In Ranorex Studio, click Tools, and select Instrumentation Wizard.
- On the next screen, select Instrument a mobile device and click Next.
- On the next screen, select iOS, then click Next.
- Select the device you previously added as an endpoint. Make sure it is connected to the computer via cable, then click Next.
- Open the Mobile app testing tab and select the IPA, certificate, and provisioning profile, then enter the password and click Next.
-
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.
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.
- Download the automation lib from the Mobile Download Archive on your Mac.
- Open the XCode project of your application under test.
- 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.
- Rename the newly created target.
-
Add the previously downloaded automation lib to your newly created target by dragging and dropping it into your project.
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.
- 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.
Result
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.
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.