This article explains how to instrument an iOS app using source code in Xcode by integrating the Ranorex automation library into a dedicated test target.
If you don’t need source-level control, use the standard iOS instrumentation workflow instead.
Important notes
- Re-instrument after updates: Whenever you update Ranorex Studio (for example, new automation libraries or a newer RxServiceApp), re-instrument your apps, otherwise automation may not work as intended.
- Do not ship instrumented apps: Instrumented apps are for testing only. Do not submit them to the App Store (and they don’t work with TestFlight).
Prerequisites
- A Mac with Xcode and your app’s source project.
- Download the automation lib from the Mobile Download Archive on your Mac
- If you want Ranorex to start/stop your app from Ranorex Studio / RxServiceApp, you must configure the required URL scheme (explained below).
Instrument your app in Xcode
Note: The file size of Ranorex Automation Library is about 30 megabytes. This does not automatically make your app 30 megabytes bigger since it is a universal library, and only the parts essential for your app will dynamically be added when compiling it.
- 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.
Rename the new target and update the related names manually (Xcode doesn’t update all references automatically), including:- the target name
- the target’s .plist file name and references
- the target’s product name
- the scheme name
- Add the previously downloaded automation lib to your newly created target.
Choose the lib file and specify the target, i.e., where the lib will be added
- After doing this, the automation lib will be listed in the Linked Binary With Libraries list in the Build Phases pane of the test target.
- Add the CFNetwork framework to the list.
Add CFNetwork.framework
Added automation lib and network framework - On older iOS versions (the original guidance mentions iOS 8.3), you may also need IOKit.framework.
- In the Build Settings pane of the test, add the switches
-ObjC-all_loadto the option Other Linker Flags.
Set the switches ‘-ObjC’ and ‘-all_load’ - Under the Info tab, add a Bundle display name key (CFBundleDisplayName).
- Insert the URL schema in the application settings to open the instrumented IPA from RxServices or Ranorex Studio. For more information, review the iOS Service App page. Below is an example of a schema:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLName</key>
<string>ranorex.your.application.name</string>
<key>CFBundleURLSchemes</key>
<array>
<string>ranorex.your.application.name</string>
</array>
</dict>
</array>Attention: If a designer implements the existing Apple API, which restricts any schema from running the application, the instrumented IPA does not run within RxServices and Ranorex Studio.
- Run the RxServices IPA, put it into the background, and next, run the instrumented IPA and put it in the background as well. This makes the application recognizable by the RxServices IPA.
The new IPAs should be displayed in the list of available IPAs in the RxServices application and in Ranorex Studio.
After performing these steps, your project can be built using the newly created target and scheme for your iOS devices as well as simulators.
Note: If you see the debug output RxAutomationEngine init in the console pane, your app has been instrumented successfully.
Successfully instrumented app
Note: Because the Ranorex automation lib uses non-public APIs, make sure that you do not submit a Ranorex instrumented app to the app store, as your app might be rejected and you might be banned from submitting apps to the app store for a period of time.
To add your device via Wi-Fi, the application under test must be started on your iOS device or simulator.
The development provisioning profile should be used for testing your app and not the distribution provisioning profile.
To improve the object recognition of your app under the test set, use the accessibility label attribute of your controls. Due to restrictions in the Apple API, it may occur that the instrumented IPA is not able to run from Ranorex Studio, while the RxServices application is in the background mode. It is recommended to perform any test while the instrumented IPA is in the foreground.