| Availability | Available in iOS 4.0 and later. |
The UIATarget class represents high-level user interface elements of the system under test (SUT)—that is, your application, the iOS, and the connected device on which they’re running. Your test scripts, written in JavaScript and running in conjunction with the UI Automation instrument, use this class and related UIA classes to exercise the SUT and log results.
For the sake of simplicity and consistency with other Apple documentation, this document describes device operations and user interface actions as though they were performed by a user. In practice, the Automation instrument simulates these operations and actions.
Use these methods to obtain information specific to the device such as assigned name, device model, and operating-system name and version.
The rect and point objects used with these screen interaction methods have properties for origin, size, x, y, height, and width corresponding to the analogous CGRect, CGPoint, and CGSize Cocoa structures. Your script should treat methods with rect, point, or size arguments or return types as JavaScript objects with those properties defined. The relevant coordinates are screen-relative and are adjusted to account for device orientation.
tap
doubleTap
touchAndHold
tapWithOptions
dragFromToForDuration
flickFromTo
pinchOpenFromToForDuration
pinchCloseFromToForDuration
These methods allow you to record the appearance of the screen (or some portion of it). Such images can be helpful in tracking progress in a test and in diagnosing problems.
Takes a screen shot of the specified rectangular portion of the device screen.
(undefined) captureRectWithName(Rect rect, String imageName)
The rect that defines the area of the screen to capture.
A string to use as the name for the resultant image file.
The image is saved as a file in .PNG graphic format, with the specified name, in the log.
Takes a screen shot of the entire device screen.
(undefined) captureScreenWithName(String imageName)
A string to use as the name for the resultant image file.
The image is saved as a file in .PNG graphic format, with the specified name, in the log.
Renders your application inactive for the specified duration.
(Boolean) deactivateApp(Number duration)
The time, in seconds, for the application to remain inactive.
Use this method to test shifting your application to and from the background execution context. Note that applications built using iPhone SDK 4.0 or later and running in iOS 4.0 and later aren’t necessarily terminated when the user presses the Home button. See iOS Application Programming Guide for details of multitasking and background execution context.
Delays script execution for the specified time.
(Boolean) delay(Number timeInterval)
The time to delay, in seconds.
You can use this method to provide enough time for lengthy operations to complete.
Returns the current orientation of the device.
(Number deviceOrientation) deviceOrientation()
The returned value is a constant that represents the physical orientation of the device and may be different from the current orientation of your application’s user interface. The possible values are as follows:
UIA_DEVICE_ORIENTATION_UNKNOWN
UIA_DEVICE_ORIENTATION_PORTRAIT
UIA_DEVICE_ORIENTATION_PORTRAIT_UPSIDEDOWN
UIA_DEVICE_ORIENTATION_LANDSCAPELEFT
UIA_DEVICE_ORIENTATION_LANDSCAPERIGHT
UIA_DEVICE_ORIENTATION_FACEUP
UIA_DEVICE_ORIENTATION_FACEDOWN
See the Constants section for descriptions of these values.
Double-taps the specified element or at the specified screen location.
(undefined) doubleTap(Object tapPointObject)
A rect, point, or UIAElement.
Drags from a specified starting screen location to a specified ending screen location, for a specified length of time.
(undefined) dragFromToForDuration(fromPointObject, toPointObject, Number duration)
The rect or point from which the drag action is to begin.
The rect or point at which the drag action is to end.
The length of time, in seconds, between starting and stopping the gesture.
Flicks from the specified starting screen location to the specified ending screen location.
(undefined) flickFromTo(fromPointObject, toPointObject)
The rect or point from which the flick action is to begin.
The rect or point at which the flick action is to end.
Returns an object representing your application.
(UIAApplication) frontMostApp()
This UIAApplication object is the centralized point of control and coordination for your application.
Holds down the Volume down hardware button for the specified duration.
(undefined) holdVolumeDown(Number duration)
Presses and holds the Volume up hardware button for the specified duration.
(undefined) holdVolumeUp(Number duration)
This class method returns a UIATarget object representing the system under test (SUT).
(UIATarget) localTarget()
Returns the device model.
(String) model()
Examples of model strings are iPhone and iPod touch.
Returns the device name.
(String) name()
The device name is an arbitrary string specified for the device by the user. On an iPhone, for example, you can see the name on the device in the General > About settings or in iTunes on the Summary > iPhone tab.
Pinches (performs a pinch-close gesture) from a specified starting screen location to a specified ending screen location, for a specified length of time.
(undefined) pinchCloseFromToForDuration(fromPointObject, toPointObject, Number duration)
The rect or point from which the pinch-close action is to begin.
The rect or point at which the stretch pinch-close action is to end.
The length of time, in seconds, between starting and stopping the gesture.
Stretches (performs a pinch-open gesture) from a specified starting screen location to a specified ending screen location, for a specified length of time.
(undefined) pinchOpenFromToForDuration(fromPointObject, toPointObject, Number duration)
The rect or point from which the pinch-open action is to begin.
The rect or point at which the pinch-open action is to end.
The length of time, in seconds, between starting and stopping the gesture.
Retrieves the previous timeout value from a stack, restores it as the current timeout value, and returns it.
(Number) popTimeout()
The timeout value last stored on the stack with pushTimeout.
Use this method to revert to the previous grace period duration.
If an object representing a UI element becomes available within the grace period, an attempt is made to instantiate that object from information retained by the instrument.
Stores the current timeout value on a stack and sets a new timeout value.
(undefined) pushTimeout(timeoutValue)
The length of the grace period, in seconds.
This method, in conjunction with popTimeout, allows you to temporarily change the duration of the grace period for object resolution.
If an object representing a UI element becomes available within the grace period, an attempt is made to instantiate that object from information retained by the instrument.
Changes the device orientation to the specified new deviceOrientation value.
(undefined) setDeviceOrientation(Number deviceOrientation)
The specified deviceOrientation value must be one of the following constants:
UIA_DEVICE_ORIENTATION_UNKNOWN
UIA_DEVICE_ORIENTATION_PORTRAIT
UIA_DEVICE_ORIENTATION_PORTRAIT_UPSIDEDOWN
UIA_DEVICE_ORIENTATION_LANDSCAPELEFT
UIA_DEVICE_ORIENTATION_LANDSCAPERIGHT
UIA_DEVICE_ORIENTATION_FACEUP
UIA_DEVICE_ORIENTATION_FACEDOWN
See the Constants section for descriptions of these values.
Sets a new timeout value.
(undefined) setTimeout(Number timeout)
A number representing the length of the grace period, in seconds.
The timeout value establishes a grace period for object resolution. If an object representing a UI element becomes available within the grace period, an attempt is made to instantiate that object from information retained by the instrument.
Returns the current version of the operating system running on the device.
(String) systemVersion()
An example of a system version string is 1.2.
Taps the specified element or the specified screen location.
(undefined) tap(Object tapPointObject)
A rect, point, or UIAElement.
Taps the specified element or at the specified screen location with the specified options.
(undefined) tapWithOptions(Object tapPointObject, Object options)
A rect, point, or UIAElement.
Characteristics that you provide to specify the type of tap gesture to perform.
Returns the current timeout value.
(Number) timeout()
The timeout value establishes a grace period for object resolution. If an object representing a UI element becomes available within the grace period, an attempt is made to instantiate that object from information retained by the instrument.
Touches the specified element or at the specified screen location and holds for the specified duration.
(undefined) touchAndHold(Object tapPointObject, Number duration)
A rect, point, or UIAElement.
The length of time, in seconds, to hold the touch.
Unlocks the device using an unlock event followed by a drag of the slider.
(undefined) unlock()
Simulating passcode entry is currently unsupported. Set the Settings > General > Passcode Lock feature to Off prior to running your tests.
Called by UI Automation to allow your script to respond to alerts.
(Boolean) onAlert(UIAAlert alert)
An object representing the alert encountered.
Return true if successful. Return false to cause the default alert handler to run.
Your onAlert handler is called if an alert is encountered at any time during the execution of the script. If you do not have a declared onAlert handler, the UI Automation default alert handler runs instead.
This default handler simply attempts to dismiss the alert by first tapping the cancel button, if it exists, then tapping the default button, if one is identifiable. If the alert is still not dismissed, an exception is thrown.
Returning false from your own handler also causes the default handler to run. For cursory tests, the script handler might just log an alert message and return false to let the default handler dismiss the alert.
Last updated: 2010-05-27