Automating iOS Apps - Details

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

Features

Limitations

Testing on a Simulator

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.
info NOTE: The script run can be quite slow if the simulator was not launched explicitly before the start of the test, since the simulator startup is part of the script run time.

Testing on a Device

Testing on a device involves a few steps first.

iOS Viewer

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.

  2. Launcher Settings dialog opens.

    3. 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.
  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).
    info NOTE: If the viewer session is connected successfully, the application bundle id will be stored in app history so that the next time the user can simply choose it from the dropdown list. Typing MyApp will bring up the com.mycompany.myapp (MyApp) option.
    infoNote: if device list doesn't contains the connected device, then click on the refresh button next to devices dropdown.
  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.
  8. When some action is performed from the iOS Viewer the screenshot will be refreshed automatically.
    infoAt times, the screenshot will not show the latest device state, particularly when the app is fetching some data from the network. In such cases, press the Refresh button to refresh the screenshot.
  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.
info A few things to note...
  • If the app orientation changes from portrait to landscape or vice versa, do a manual refresh by clicking on the Refresh button, to view the screenshot correctly.
  • If you resize the iOS Viewer page, do a manual refresh by clicking on the Refresh button, to view the screenshot correctly.
  • Disconnect the session by clicking on power off icon before you disconnect the device from the Mac machine.
  • Closing the iOS Viewer browser does NOT disconnect the session. So always disconnect the session before closing the browser. If you fail to do so and open the iOS Viewer again, it will show the session to be in a connected state.

Configure iOS Devices/Simulators

For connfiguring the iOS devices/simulators, do the following:
  1. Click on the All Settings button on the Dashboard. It will open up all Settings dialog.
  2. Click on the Sahi Pro Settings button. It will open up Configure Sahi Pro page.
Click on ios_devices.xml on the left. It will open up Configure Sahi Pro page.

iOSDevice Node

<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
infoFor example, Two devices are configured under iPhone. For parallel playback of data driven suite on this two devices, select iPhone as iOS Device from editor (or specify iPhone as iOSDevice in ANT target). Scripts will be distributed in two devices.

Troubleshooting connection issues

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.

Automating a keyword

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.

Automating Hybrid App

Pre-requisites

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.
info NOTE: To identify/record the hybrid element as native, uncheck the checkbox in iOS Viewer.

Playback

  1. On the Automate dialog click on Runbutton.
  2. The Run Settings dialog opens. Select the Mode IOS, click RUN.
    3. infoWhen the flow is being played back, you CANNOT see the playback happening on the IOS Viewer. The IOS Viewer does not get refreshed during playback.

Known Issues

Test Apps

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

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

Test App Bundle Ids

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.

Appendix

This section contains information on miscellaneous topics.

Element Identification - Suggestions

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.
infoHence we only display visible elements in the Controller Accessor and Alternatives.
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.
infoThe Accessor shows the smallest possible visible element at a point, while the alternate candidates contain those elements that are smaller than or equal in size to the Accessor.

Viewer - Starting or activating a new app

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.

More Info

iOS Accessor APIs
Mobile APIs