Skip to content
Sahi Pro Flowcharts is retired. These pages document the last release (v12) and are no longer updated. Go to the current documentation.Flowcharts is retired. Current docs
Get Free Trial
Sahi Pro Flowcharts is retired. These pages document the last release (v12) and are no longer updated. Go to the current documentation.

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 Record a steps allow easy interaction with the connected device.
  • iOS Inbuilt actions is similar to Sahi Pro Flowcharts Inbuilt Action used for browser testing.
  • Single Flowchart 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 key and hovering the mouse over the elements in the Viewer.

This section details how to use the iOS Viewer.

  1. On the Flowcharts window, click on the dropdown arrow next to Launch and then select Launcher Settings.

    Launcher Settings

  2. Launcher Settings dialog opens.

    Description of the image labeling:

    1. Select the Mode: Android
    2. Now select the device from the Device Info dropdown
      Specify Application Package Name:com.sahipro.SahiTestApp
  3. Click on Launch to launch the Application.

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

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

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

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

  8. When some action is performed from the iOS Viewer the screenshot will be refreshed automatically.

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

  10. Launch the Controller by ALT and double clicking on the IOS Device. 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.

  11. One can now start identifying elements by pressing the CTRL 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 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 rautomating a keyword for normal browser testing.

  1. To automate a Keyword, click on the Keyword from the Sahi Pro Flowcharts page, click on the Automate, click on Start Record button.
  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 Set Value/Set Password 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 Add Step.
  4. The device screenshot will get refreshed after a Controller action is performed. 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 icon 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 Enable web view identification.

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

  2. Press the CTRL key and mouse over the hybrid element.

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

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

  1. On the Automate dialog click on Runbutton.

    Click on Run

  2. The Run Settings dialog opens. Select the Mode IOS, click RUN.

    Run options

  • 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 Set Value 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

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 (Is Visible 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.

iOS Accessor APIs
Mobile APIs