Automating iOS User Interface Testing with UIAutomation

Posted in Apple, mobile, QA by AltF on November 14, 2010

Update: 25 June 2011
iOS 5 now supports recording these user interactions in UIAutomation which means no need to write these scripts manually.

Apple included Automated Testing support in iOS 4.0 which lets you automate testing of your iOS applications by scripting touch events. It allows you to write test scripts to exercise your application’s user interface elements as the application runs on a connected device or simulator. You write the tests in JavaScript to the UI Automation API, which simulates user interaction with the application as it runs and returns log information to the host computer.

In a nutshell:
– Automates UIKit based applications.
– Works on all iOS devices (iPhone, iPod Touch, iPad) and simulator.
– JavaScript automation scripts.
– Integrated in Instruments.
– Accessibility based.

Step 1 – Getting Started.
– Make sure that you have the latest iOS SDK (4.0+) installed | iOS SDK
– Familiarize yourself with Instruments | Instruments User Guide

Step 2 – Preparing your application.
Ensure accessibility is enabled and all the UI controls and views in your application are tagged with unique accessibility labels which makes it easy to access them in our test scripts. Using Interface Builder, you can set an element’s accessibility status and provide custom content for the label.

Step 3 – Writing test scripts.
In essence, your test script is an ordered set of commands, each of which accesses a user interface element in your application to perform a user action on it or to use the information associated within it. All the user interface elements in your application are represented to the script through an ordered hierarchy of objects defined by the UIAElements class and its subclasses.
To reach a specified UI element, the script simply calls down the element hierarchy, starting with the top level target object obtained by calling UIATarget.localTarget() The control hierarchy looks like:

var target = UIATarget.localTarget();
var application = UIATarget.localTarget().frontMostApp();
var window = UIATarget.localTarget().frontMostApp().mainWindow();

For example, if your application has a table view in the main window the hierarchy should looks like:
• Target application ■ Main window ■ View

Similarly, within a view there are elements:
• Target application ■ Main window ■ View ■ Element

And to access the child elements within an element:
• Target application ■ Main window ■ View ■ Element ■ Child element

The Automation instrument maintains a complete element hierarchy that represents your application’s user interface. To view that hierarchy, use the logElementTree method to write an outline of it to the log:

Once you are able to access the elements you can perform various actions on it. I’ll show you how to simulate basic touch events.

Tapping buttons:
Example: If you want to tap on the Add button on the top navigation bar. (Note that the navigation bar is outside the main window, hence we access it via:)

Scrolling to an element:
Example: If your main application is an address book app, with the main window consisting of a tableview with elements in it. You can simply scroll to a particular element:
window.tableViews()[0].scrollToElementWithName("John Appleseed");

You can write a few assertion functions to verify if the expected results matches the actual results. You can log the results based on pass/fail. Simple example:

var testName = "Test Case 1";
UIALogger.logMessage("Assert Text - Check if element 5 is John Appleseed");
var expected = "John Appleseed";
var actual = window.tableViews()[0].cells()[5].elements()[5].name());
if (expected = actual) {
else {

Step 4 – Executing the test.
– Once you are ready with the test script. Compile your app in the debug mode and create a simulator build.
– Launch Instruments and select Automation from iOS Simulator templates.
– Select your target application from “Choose Target” option on the top.
– Select the test script from “Choose Script” option on the left window.
– Hit the red record button once done. It will fire up the simulator with your target app and start executing the tests.

– If you are facing any issues running UIAutomation on the iPad, refer UIAutomation on iPad

API Documentation

Tagged with: , , , , , , ,

12 Responses

Subscribe to comments with RSS.

    • Anonymous said, on November 30, 2010 at 10:23 am

      Can you please let us know how to handle alerts with an example. It was not clear on the apple site..

      Thanks in advance


  1. shoucal said, on November 15, 2010 at 9:55 am

    Hi AltF , can we change the elements value? how?

  2. altf said, on November 15, 2010 at 10:38 am

    hi shoucal, do you mean setting values to some text field? you can do that by –

    var name = “blah”;

  3. UIAutomation on iPad « altf said, on November 17, 2010 at 10:43 am

    […] to my previous post “Automating iOS User Interface Testing with UIAutomation” for getting started with […]

  4. Hash#05 said, on December 8, 2010 at 6:31 pm

    Hey AltF, do we need to set the accessibility for views that were on the sub windows from the Login screen? Currently, I am only able to get the elements from the Login screen using logElementTree and not the elements from the next screen after that though an accessibility is set of the existing elements. Can you just let me know how we get all these with a sample?

  5. altf said, on January 20, 2011 at 4:55 pm

    Hi Hash#05, a simple trick is to do a logElementTree after you access the login window view. I’ll shed more details in my next post.

  6. iwanttotest said, on June 10, 2011 at 7:35 am

    how will I start with the java test script? 😦 i want my apple application experience automation testing.. my test scripts are all written in numbers/excel.

  7. […] Altf also has an article on this here . I will be using Adi’s article as reference to explain the […]

  8. […] covered how to write UIAutomation tests in my previous posts (here and here) and also how to distribute stable build over the air (here). You can run your tests from […]

  9. ipad 2 cases said, on July 30, 2012 at 2:06 am

    Do you mind if I quote a couple of your articles as long as I provide credit
    and sources back to your webpage? My blog is in the exact same area of interest as yours
    and my visitors would truly benefit from some of the information you provide
    here. Please let me know if this okay with you. Many thanks!

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: