UI Automation Reference Collection

This collection of documents is the API reference for the UI Automation feature, which allows you to write test scripts to exercise your application’s user interface elements as the application runs on a connected device. 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.

You will need this reference if you want to automate test procedures for your iPhone application.

Accessing and Using User Interface Elements

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(). For example, the first button in the main window of your application might be referenced by index as follows:

UIATarget.localTarget().frontMostApp().mainWindow().buttons()[0]

If that first button is identified in your code as the Edit button, the following would also work:

UIATarget.localTarget().frontMostApp().mainWindow().buttons()["Edit"]

To tap that button, then, the script could use any of these three formats:

• UIATarget.localTarget().frontMostApp().mainWindow().buttons()[0].tap();

• UIATarget.localTarget().frontMostApp().mainWindow().buttons()["Edit"].tap();

• var editButton=UIATarget.localTarget().frontMostApp().mainWindow().buttons()[0];

  editButton.tap();

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:

UIATarget.localTarget().frontMostApp().logElementTree()

Recording Results With the Log

To record data during its tests, the script uses UIALogger class methods to send messages to the Automation instrument running on the host computer. Various methods are available to assist in organizing and analyzing the recorded data. For example, to indicate the initiation of a specified test, use the logStart method:

UIALogger.logStart("Test1");

To end a test and mark it as failed, use the logFail method:

UIALogger.logFail("Failed to foo.");

To send a general-purpose debug message, use the logDebug method:

UIALogger.logDebug("Done with level 3.");

You view the collected data in the detail pane of the Automation instrument, using the facilities of Instruments application.

Handling Alerts

When UI Automation encounters an alert during the execution of your script, it calls your alert handler, passing a reference to the UIAAlert object representing the alert. Your script should handle the alert appropriately and return a value of true, upon which normal script execution continues.

To ensure that alerts don't interfere with testing, the Automation instrument also implements a simple default alert handler. If your script‚Äôs alert handler returns false, this default handler attempts to dismiss the alert by tapping the cancel button, if it exists; otherwise, it taps the default button.

The following code implements a simple alert handler that records a message to the log and returns false, thereby depending on the default handler to dismiss the alert.

var target = UIATarget.localTarget();

target.onAlert = function onAlert(alert) {

    UIALogger.logDebug("There was an alert!");

    return false;

}