Skip to content
Get Free Trial

Automating iOS Apps - Details

This page describes iOS Automation in detail. If you wish to get a quick start, read iOS Automation - Getting Started.

  • Supports running scripts against a connected iOS device or simulator having version iOS 9.3 and above.
  • iOS Viewer and Controller allow easy interaction with the connected device.
  • Scripts can be recorded from the iOS Viewer and Object spy features are also available.
  • Scripts can be played back from the Controller, Editor, ANT etc.
  • iOS function syntax is similar to Sahi Pro functions used for browser testing.
  • Single script can interact with different modes like Browser, Desktop, Mobile etc.
  • Does not support testing iOS device or simulator below iOS 9.3
  • Does not support distributed run on multiple machines yet.
  • Does not support testing on a remote iOS device yet. The iOS device needs to be connected to the Mac machine.

The iOS simulator can be started in 3 different ways. It is not necessary that the simulator be started up prior to starting an iOS Viewer session or running a script. But it is advisable to explicitly start it beforehand. More details below.

  1. Explicitly start the simulator before running the test.
    This can be done in either of the following ways.
    • Using Simulator app
      • Start the Simulator app from the Xcode menu - Xcode -> Open Developer Tool -> Simulator.
      • Start a specific simulator from the Simulator app menu - Hardware->Device->iOS 16.4->iPhone 14 Pro Max
    • Using start_simulator.sh
      • This is a shell script that one can use to launch a Simulator from the command line.
      • Open a Terminal shell and navigate to <SAHI_INSTALLATION_FOLDER>/userdata/bin/iOS folder.
      • Run ./start_simulator.sh <SIMULATOR_UUID> where <SIMULATOR_UUID> refers to the UUID of the specific simulator.
      • Simulator UUIDs can be obtained by running xcrun simctl list devices on a Terminal shell.When the simulator is started explicitly first, a test will simply run the script in the launched simulator. At the end of the script run, the simulator will remain open.
  2. The Simulator app is open, but the specific simulator is not running (the process is running, but the desired simulator is not running).
    In this case, the test will launch the simulator, run the script and close the simulator.
  3. Simulator app is shut down and no Simulator process is in memory.
    In this case, the script will launch the simulator in the background, run the script and close the simulator. The simulator will remain invisible through the duration of the script since it runs in the background.

Testing on a device involves a few steps first.

  • Device Pre-requisites

    • Devices with iOS versions above iOS 9.3 are supported
    • The device has to be connected to the Mac machine through USB cable throughout the duration of the test.
    • The device needs to be on the same Wi-Fi network as the Mac machine.
    • Screen lock should be removed and display options should be set such that the device does not sleep during the execution of the script.
    • Additionally, follow the below steps for iOS devices with iOS 14 and above:
      • Add property ios.use.sahi.common_domain=true in <Sahi_Installation>/userdata/config/userdata.properties
      • Find the IP of the Mac machine.
      • Configure proxy settings of the mobile device with proxy host as the Mac machine’s IP and port as 9999.
  • Connecting iOS Device in iOS Viewer

    • Start up the iOS Viewer.

    • Choose the iOS Device from Device Info dropdown. Type the application bundle identifier in the Application BundleId textbox.

    • Click on Connect Session button.

    • If the device binary does not exist then It will ask to build the device binary in iOS Viewer.

    • Type the Team ID in the textbox to build the device binary.

    • Click on Build button. iOS Viewer will create a device binary and shows the appropriate result.

    • After the device binary built successfully, click on Connect Session button. This will start the SahiTestApp application on the iOS Device, and the iOS Viewer will display the screenshot of the application.

  • When the device is connected to the Mac for the first time, the user will get an alert on the device asking to Trust this computer. Choose the Trust option.

    Trust this computer

iOS Viewer allows an end user to view the iOS device/simulator screen on a Mac browser. The user can launch the Controller and then identify iOS elements by pressing the Ctrl (⌘ on Mac) key and hovering the mouse over the elements in the Viewer.

This section details how to use the iOS Viewer.

  1. The user can launch iOS Viewer directly from Sahi Dashboard by clicking iOS button. This brings up the iOS Viewer in the system’s default browser. If the user wants to launch iOS Viewer in a different browser, one can open that Sahi browser from the Dashboard and click on the iOS Viewer link to bring up the iOS Viewer in that browser.

    iOS Viewer

  2. Device Info: shows the list of devices connected to the Mac machine and simulators installed on the machine. If you are connecting to a Simulator, you may want to start the simulator first. Refer to Testing on a Simulator for details.

    Application BundleId: The user needs to choose an application to start the Viewer session with. This application needs to be available on the device/simulator. One can choose an application from the dropdown or enter a new application bundle id, ex: com.mycompany.myapp. When entering the app bundle id, one can give a name to it as well, like this, in brackets - com.mycompany.myapp (MyApp).

  3. If you are connecting to a device, ensure that it is connected to the Mac machine through a USB cable.
    Ensure that the device and the Mac machine are connected to the same Wi-Fi network.

  4. Click on Connect Session. If the connection is successful, you will see three buttons Disconnect Session, Controller and Refresh. You will see also the device screenshot. If you encounter connection errors, refer to the connection troubleshooting section.

    iOS Viewer

  5. When some action is performed from the iOS Viewer or from the Controller, the screenshot will be refreshed automatically. However, any actions performed through the Evaluate Expression box in the Controller will not cause a screenshot refresh. Click on the Refresh button manually to refresh the screenshot.

  6. One can interact with the device from the iOS Viewer itself without launching the Controller.

  7. Launch the Controller by clicking on the Controller button. This will bring up the Controller. This is exactly the same as a normal browser Controller, except that it is configured to interact with an iOS session.

  8. One can now start identifying elements by pressing the Ctrl (⌘ on Mac) key and hovering the mouse over elements on the Viewer screenshot. One will notice the Accessor textbox on the Controller, showing the accessor for the element. The Alternatives dropdown displays the alternatives for the accessor.
    The image shows the Accessor and Alternatives for the “Privacy & Security” label element. The Viewer shows the highlighted element.

    iOS Viewer and Controller

For connfiguring the iOS devices/simulators, do the following:

  1. Click All Settings on the Dashboard. The All Settings window opens.

  2. Click Sahi Pro Settings. The Sahi Pro Settings page opens.

    The Sahi Pro Dashboard with the All Settings window open, Sahi Pro Settings and the All Settings button highlighted

In the menu on the left, open Browsers And Devices and click iOS Device Definitions (ios_devices.xml).

<iOSDevices>
<!-- iPhone device with 2 capacity-->
<iOSDevice>
<name>iPhone</name>
<displayName>iPhone X</displayName>
<deviceId>XXXX</deviceId>
<deviceId>YYYY</deviceId>
<type>simulator</type>
</iOSDevice>
</iOSDevices>
ElementValue
nameKey by which this iOSDevice will be referred. This can be any value without spaces.
displayNameBetter name displayed in iOS Viewer.
deviceIdId of the device, multiple Id can be added under same name.
you can get the Device Id by executing below command

For MacOS 12 onwards, use this command:
xcrun xctrace list devices
For MacOS 11 and earlier, use this command:
instruments -s devices
typeType should be either simulator or device

There are a few reasons for connection issues that one may face, especially with a device. The error alerts will have useful information about what went wrong.

  • If you connect to a device and the device binary does not exist, you will get an error indicating the same in iOS Viewer. Refer to Testing on a Device for building the device binary.
  • The connection can also fail if the device is on a different network than the desktop, or is not able to connect to the desktop.

This is similar to recording a Sahi script for normal browser testing.

  1. To record a script, launch the Controller from the iOS Viewer page, choose a script to record and press Record.
  2. Actions done from the iOS Viewer page are recorded automatically.
    • Hovering the mouse over a textbox will overlay a textbox where one can type text in. After typing the text, press Enter or click outside the textbox. This will send the text content to the device. The _setValue/_setPassword step will get recorded automatically.
    • The user can click on any other element. This will click the element on the device. The _click step will get recorded automatically.
  3. Steps can also be recorded from the Controller. One can use Click, Set, Assert, choose Other Actions, Test an expression from Evaluate Expression to perform an action on the Device. But one will need to record these steps explicitly by clicking on Append.
  4. The device screenshot will get refreshed after a Controller action is performed, except when it is from the Evaluate Expression box, in which case an explicit refresh is required. The user can continue to interact with the changing screen from the Viewer itself. If the device screenshot is not refreshed correctly, click on the Refresh button manually to reflect the current screenshot.
  • iOS Device must be connected on the same network in which Sahi Pro is running.
  • Configure the proxy in iOS Device.

For recording iOS application which contains Webview (Hybrid contents), open the application in iOS Viewer and go to the screen which contains webview.
If the screen is displaying hybrid contents then there will be one checkbox visible below Refresh button.

  1. Check the checkbox to identify/record hybrid elements as Web.

  2. Press the Ctrl (⌘ on Mac) key and mouse over the hybrid element.

  3. Element’s accessor will be displayed in Sahi Controller.

  4. To record the hybrid app, perform the actions directly from iOS Device.

  5. Sample script will look like this

    _setMode("IOS");
    _mActivateApplication("com.sahipro.ios.test.SahiTestApp", true);
    _setAccessorIgnoreCase(true);
    _click(_button("Test Web View"));
    _setValue(_textbox("webViewTextFieldID"), "https://sahitest.com/demo/responsiveTestPage.htm");
    _click(_button("GO"));
    // _mStartWebContext will change the mode to IOS_WEBVIEW
    _mStartWebContext();
    _click(_heading4("Sales"));
    // _mStopWebContext will revert back the mode to IOS
    _mStopWebContext();

Once a script is recorded, you can run it from the Controller itself, with Run.

    1. Choose the script.
    2. Select the Start Mode:iOS.
    3. You can leave the Start URL blank. This is not used.
    4. Click on Play to execute the script.
    5. Click on Logs to view the logs of the executed script.

User can run a script/suite/scenario from the Editor as well.

  1. Choose the script/suite/scenario from the Editor and click Run.
  2. Select the Start Mode:iOS.
  3. You do not need to choose any browser.
  4. Choose a device to execute a script from IOS Device: dropdown.
  5. You can leave the Start URL blank. This is not used.
  6. Press Run to run the script.

User can generate an ANT target from the Editor for a script/suite/scenario and run using ANT.

  1. Choose the script/suite/scenario from the Editor and click Run.
  2. Select the Start Mode:iOS.
  3. You do not need to choose any browser.
  4. Choose a device to execute a script from IOS Device: dropdown.
  5. You can leave the Start URL blank. This is not used.
  6. Press Create ANT Target to generate the ANT target.

System dialogs in iOS are not visible to the automation APIs, so they cannot be automated by normal Sahi functions. For example, one cannot induce a click on an Allow button in the system dialog.

They are automated through a special flow.

  1. Before one expects a system dialog, one needs to setup the expectation by using _iExpectSystemDialog API. Pass the expected message and the accessor of the button to click.
  2. Perform actions that bring up the system dialog.
  3. In order to trigger the system dialog automation flow, one needs to interact with the app. Use _iInteractWithApp() for the same. If the expected message and the actual message match, and the button accessor is available, it will be clicked, and the dialog will be dismissed.
  4. One can check the message of the last dialog shown, by using _iLastSystemDialog()
  5. Finally, the last system dialog message can be cleared using _iClearLastSystemDialog()
  • Issues with automating text fields

    This issue occurs on some iOS simulators. If there are multiple text fields in an app, automation of setting values may fail after a certain number of fields. The keyboard will not come up after the first few successful steps.

    To solve this, first ensure that the Hardware keyboard is setup correctly. The iOS Simulator sometimes has problems showing the keyboard. To make sure that the keyboard works, click on on any text field in the Simulator. Check if the keyboard appears.

    After this, the text fields automation will succeed. Do the same if there are other keyboard problems.

  • In the iOS Viewer, keyboard dimensions come up in Portrait orientation in Landscape mode.

    To record any keys, record in Portrait mode.

  • In a webview, a textbox or password field may need an extra _click before the _setValue step.

  • Issues With System Dialogs

    • If an app requires the Location permission, and Location is not turned ON in Settings, the system dialog will show a button to launch Settings. Unfortunately clicking on Settings button will launch the Settings app and cause the current app to be deactivated. This eventually causes _iInteractWithApp() to fail. So such a dialog cannot be automated. Or in other words, any dialog button that causes invocation of a different app cannot be automated.

    • If one wishes to automate clicking the “Don’t Allow” button, note that the character between n and t is NOT a single quote. Either use a regular expression /Don.*Allow/ or use the exact specific character, as shown in userdata/scripts/sahitests/ios/systemdialogs/systemDialog1.sah - testCalendarSystemDialogSpecialCharacters method.

    • System dialogs may not get automated on iOS 9

Refer to demo scripts in <SAHI_INSTALLATION_FOLDER>/userdata/scripts/sahitests/ios folder.

A few iOS Test Apps have been bundled with the Sahi Pro Mobile Engine. The demo scripts make use of these test apps.

To install these tests apps on your simulator, do the following.

  • Start the specific simulator explicitly using the Simulator app or start_simulator.sh, as explained in Testing on a Simulator.

  • Open a Terminal shell and navigate to <SAHI_INSTALLATION_FOLDER>/userdata/bin/iOS/testapps

  • Type ./install_testapps_on_simulator.sh <SIMULATOR_UUID> and press Enter.

    <SIMULATOR_UUID> refers to the UUID of the specific simulator. Simulator UUIDs can be obtained by running xcrun simctl list devices on a Terminal shell.

    This will install all the test apps on the specific simulator.

Since they are test apps, their bundle ids have not been added to the apps history out of the box. Hence one will need to explicitly type in the testapp bundle id while connecting the Viewer session.

Here is the list of the Test App bundle ids.

  • SahiTestApp - com.sahipro.ios.test.SahiTestApp
  • SahiTestApp2 - com.sahipro.ios.test.SahiTestApp2
  • LoginApp - com.sahipro.ios.test.LoginApp
  • NearApp - com.sahipro.ios.test.NearApp
  • GroceryApp - com.sahipro.ios.test.GroceryApp
  • SpecialCharactersApp - com.sahipro.ios.test.SpecialCharactersApp
  • FirstApp - com.sahipro.ios.test.FirstApp
  • SecondApp - com.sahipro.ios.test.SecondApp

This section contains information on miscellaneous topics.

  • Prefer using a direct text accessor for best performance. For example: _button(“Login”).
  • Prefer using a direct text accessor that does not change. For example, value is not a good choice for _textbox, since it can change. So _textbox(“johndoe”) is not a good accessor.
  • If a direct text accessor is not available, use an index accessor provided it does not change. Otherwise, prefer a relational (_in, _near) or positional (_rightOf, _leftOf…) accessor.
  • _rightOf may be faster than _near in many cases.
  • _parentNode() may be useful too.

Element Identification - Notes on Alternate Candidates

Section titled “Element Identification - Notes on Alternate Candidates”

In iOS testing, an element is considered visible (_isVisible($el) will return true) if it is hittable. Clicking on an element that is not hittable causes internal test failures.

However, there are times when one wants to check the text of a non hittable element or whether it is selected, etc. In order to do so, the user will need the identifier for the element. To facilitate this, we show the identifiers of all possible alternate candidates, in the Controller result section.

Accessor with alternate candidates

In iOS testing, interacting with any element requires the app which contains the element, to be in the foreground and activated.
There are two scenarios when one would want to activate a new app.

  1. When the app itself launches a new app on some interaction
  2. One wishes to explicitly launch a new app since the testcase requires interacting with more than one app.

In either case, before one can interact with the new app, it has to be activated.

  • App launches new app internally
    • Automatic activation - if the new app is part of the app history that Sahi stores, it will be activated automatically.
    • If Sahi is not yet aware of the new app, the user will receive an alert indicating the app needs to be activated by specifying the application bundle id. Enter the app bundle id and click on Start/Activate app in the Viewer.
  • Explicit launch of app
    Enter the app bundle id and click on Start/Activate app in the Viewer. If the app is in the background, it will just be activated. Else it will be launched newly.

<SAHI_INSTALLATION_FOLDER>/userdata/scripts/sahitests/iOS/helperFunctions.sah lists a few helper functions that are useful in a Sahi script.

iOS Accessor functions
Mobile functions