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

warning Note: From Sahi Pro v9.0.1, _connectDevice and _selectDevice executes implicitly if the start mode is iOS. No need to write these APIs in the script.
To execute these APIs explicitly from the script, pass connectDeviceInternal=false as extra parameter in Playback settings. Refer here for more details.

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. 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.
  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).
    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.
  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.
  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.
    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.
  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 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.
warningNote: While evaluating any line of code from the Evaluate expression box, make sure Sahi-IOS is selected in the Controller.
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 Disconnect Session 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.

Recording a Script

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.
infoFor more details on Controller, refer to Sahi Controller and Java Controller.

Recording 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 visible below Refresh button.
  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 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"), "http://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();
info NOTE: To identify/record the hybrid element as native, uncheck the checkbox in iOS Viewer.

Playback

From the Controller

Once a script is recorded, it can be played back from the Controller Playback tab itself.
infoNote: When the script is being played back from the Controller, you cannot see the playback happening on the iOS Viewer. The iOS Viewer does not get refreshed during playback.

From the Editor

User can playback a script/suite/scenario from the Editor as well.
  1. Choose the script/suite/scenario from the Editor and click on the Playback button.
  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 playback the script.
infoRefer to Editor Playback for more details on playback from the Editor.

Via ANT Target

User can generate an ANT target from the Editor for a script/suite/scenario and playback using ANT.
  1. Choose the script/suite/scenario from the Editor and click on the Playback button.
  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.
infoRefer to Playback via ANT for more details on playback via ANT

Automating System Dialogs

System dialogs in iOS are not visible to the automation APIs, so they cannot be automated by normal Sahi APIs. 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()

Known Issues

Demo Scripts

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

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 (_isVisible($el) 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.

helperFunctions.sah

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

More Info

iOS Accessor APIs
Mobile APIs