Sahi Documentation

iOS Automation - Getting Started

abstract This section helps you quickly get started with iOS Automation.

Introduction

Sahi iOS testing is available as part of the Sahi Pro Mobile Add-on module. It allows automation of both iOS devices and simulators having iOS version 9.3 and above. It provides the familiar Sahi features and API paradigm available for browser testing. This includes the ability to record and playback scripts, edit scripts using the Editor, run suites etc.

Pre-requisites

Download and Install Sahi Pro Mobile Add-on

You need to install Sahi Pro Mobile Add-on before you can proceed with the Quick Tutorial

Quick Tutorial

This tutorial involves automating a sample app on an iOS simulator. Sahi Pro Mobile Add-on ships with a few iOS Test Apps. We will use SahiTestApp in this tutorial. We will be running the tutorial on iOS 16.4 - iPhone 14 Pro Max Simulator. But this can be run on any Simulator having version iOS 9.3 or above.

  1. Start the Simulator
    Start a simulator explicitly using the Simulator app. We can also start it with start_simulator.sh detailed in Testing on a Simulator. But we will just use the Simulator app for now.
    • Start the Simulator app from the Xcode menu - Xcode -> Open Developer Tool -> Simulator.
    • Start the specific simulator from the Simulator app menu - Hardware->Device->iOS 16.4->iPhone 14 Pro Max
    • Note down the Simulator UUID. This is needed to install SahiTestApp, in the next step.
      • To get the Simulator UUID, open a Terminal shell, and run xcrun simctl list devices
      • You should see output similar to the following. NOTE that the output will have simulators for different iOS versions, and also different OS types like tvOS, watchOS etc.
        NOTE that your Simulator UUIDs will be different.
      • From the output, locate the iOS 16.4 - iPhone 14 Pro Max simulator entry. It looks like this. As you can see, this shows up as Booted.
  2. Install the Test App
    SahiTestApp needs to be installed on the booted Simulator, before we can automate it.
    • Sahi provides a shell script, install_testapps_on_simulator.sh, to install all Sahi iOS test apps in one go.
    • Open a Terminal shell and navigate to <SAHI_INSTALLATION_FOLDER>/userdata/bin/iOS/testapps folder.
    • Type ./install_testapps_on_simulator.sh <SIMULATOR_UUID> where <SIMULATOR_UUID> is the Simulator UUID you noted above.
      Based on the specific xcrun output above, this will look like

      ./install_testapps_on_simulator.sh 26E1E4C9-70D9-42A2-918E-AD5B21DE5D74

      NOTE again that your Simulator UUID will be different.
    • All the test apps should now get installed on your booted simulator.
  3. Now that we have installed SahiTestApp on the Simulator, start up the Sahi Dashboard, and click on the iOS button
  4. This will bring up the iOS Viewer in the default browser.
  5. The Device Info: dropdown lists all the Simulators installed on the Mac machine. The booted Simulator will have a (Booted) suffix.
    If Device Info is not populated automatically, choose the booted Simulator from the dropdown.
  6. Type com.sahipro.ios.test.SahiTestApp in the Application BundleId textbox.
    You will notice that a bunch of suggested apps comes up, but Sahi test apps are not part of the suggestions. So, we need to manually type it the first time. Sahi will remember it from the next time onwards.
  7. Click on Connect Session button.
  8. This will start the SahiTestApp application on the Simulator, and the iOS Viewer will display the screenshot of the application.
  9. Launch the Controller by clicking the Controller button.
  10. Specify a script name (test_ios_sample_app.sah) in the Controller and click on Record button.
    infoNOTE: Throughout this tutorial, we will perform actions on the Viewer which will get recorded in the script.
    infoNOTE: The Viewer has to be in focus for performing any actions.
  11. Click on TEST SAMPLE APPLICATION in the iOS Viewer. The TEST SAMPLE APPLICATION element will be clicked on the device, and the Viewer screenshot will be refreshed. The Login screen is now visible.
  12. Click on Recorded steps tab in the Controller. You can see a bunch of recorded steps. A few steps have been recorded implicitly. Finally the click on TEST SAMPLE APPLICATION has also been recorded.
  13. We are in the Login screen, and we need to automate the User Name and Password text fields.
    IMPORTANT: Automation of text fields needs the Hardware keyboard to be setup correctly. The iOS Simulator sometimes has problems showing the keyboard. To make sure that the keyboard works, click on the User Name textbox in the Simulator (NOT on the Viewer). Check if the keyboard appears. As you can see, the keyboard appears.
    info
    • If you see the keyboard appearing, toggle the keyboard twice by clicking on [Hardware->Keyboard->Toggle Software Keyboard] from the Simulator app menu twice. This will first hide the keyboard and show it again.
    • If you do NOT see the keyboard appearing, toggle the keyboard once by clicking on [Hardware->Keyboard->Toggle Software Keyboard] from the Simulator app menu once. This will simply show the keyboard once.
  14. Proceed with the automation. In the Viewer, click the textbox near the User Name label. You can now see an editable textbox overlaid on the User Name textbox.
  15. Type "test" in the textbox and press the Enter key on your Mac.
  16. The "test" string is sent to the device and the Username textbox is populated with "test". This can be seen from the Viewer screenshot. Also, you can see that a _setValue step has been recorded for the Username textbox.
  17. Click on the Password textbox now. You can see an editable textbox overlaid on the Password textbox.
  18. Type "secret" in the textbox and press the Enter key on your Mac.
  19. The "secret" string is sent to the device and the Password textbox is populated with masked characters. Also, you can see that a _setPassword step has been recorded for the Password textbox.
  20. Click the "Login" button. You are now in the Available Books screen.
  21. Click on the "Quantity" textbox for "Ruby for Rails". An editable textbox shows up with 0 in it. Remove it and enter 3 in the textbox. Press Enter key on your Mac. On the device, the "Quantity" textbox for "Ruby for Rails" is filled with a value 3, as can be seen from the Viewer screenshot.
  22. Repeat the steps for the "Quantity" textbox for "Core Java".
    • Click on the "Quantity" textbox for "Core Java". An editable textbox shows up with 0 in it. Remove it and enter 5 in the textbox. Press Enter key on your Mac.
    • On the device, the "Quantity" textbox for "Core Java" is filled with a value 5. The Viewer shows the filled value.
    • At the end of the above step, the Viewer will look like this. You can see the _setValue step recorded for "Core Java".
  23. Repeat the steps for the "Quantity" textbox for "Python Cookbook".
    • Click on the "Quantity" textbox for "Python Cookbook". An editable textbox shows up with 0 in it. Remove it and enter 4 in the textbox. Press Enter key on your Mac.
    • On the device, the "Quantity" textbox for "Python Cookbook" is filled with a value 4. The Viewer shows the filled value.
    • At the end of the above step, the Viewer will look like this. You can see the _setValue step recorded for "Python Cookbook".
  24. Click on the "ADD TOTAL" button. The Viewer shows the calculated total.
  25. It is time to add assertions on the total. Press the "Ctrl" key and hover your mouse over the calculated total (3300). You will see the appropriate accessor in the Controller - _label("TotalCost")
  26. Click on Assert button in the Controller. The Controller adds a few assertions for _label("TotalCost").
  27. Click on Append button in the Controller. The assertions are appended to the script.
  28. Stop the recording of the script by clicking on the Stop button from Controller.
  29. Check the recorded script by clicking on Editor from controller. The script looks like this.
    _setMode("IOS");
    _mActivateApplication("com.sahipro.ios.test.SahiTestApp", true);
    _click(_label("TEST SAMPLE APPLICATION"));
    _setValue(_textbox("usernameID"), "test");
    _setPassword(_password("passwordID"), "MgkKEQBU");
    _click(_button("Login"));
    _setValue(_textbox("RubyID"), "3");
    _setValue(_textbox("JavaID"), "5");
    _setValue(_textbox("PythonID"), "4");
    _click(_button("ADD TOTAL"));
    _assertExists(_label("TotalCost"));
    _assertVisible(_label("TotalCost"));
    _assertEqual("3300", _getText(_label("TotalCost")));
  30. It is time to playback the script. Click on Playback tab in the Controller. Select the recorded script and select Start Mode:IOS
  31. Click on the Play button. This will start the script execution.
    infoWhen 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.
    You can see the result of the executed script in the Controller itself.
  32. Click the Logs link from Controller Playback tab. This shows the script log report for the playback.
  33. Close the Controller.
  34. Click on Disconnect Session button in the Viewer to disconnect the session.

Further Reading

iOS Automation in Detail
iOS Accessor APIs
Mobile APIs
Working with Multiple Modes in a Single Script