UIATarget Class Reference

Availability
Available in iOS 4.0 and later.

Overview

The UIATarget class represents high-level user interface elements of the system under test (SUT)—that is, your app, 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 UI Automation 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.

For an explanation of how to use this class and related classes, see “Automating UI Testing” in Instruments User Guide.

Tasks

Getting the Base Target and Host Objects

Managing Your App

Obtaining Device Property Information

Use these methods to obtain information specific to the device, such as assigned name, device model, and operating-system name and version.

Determining and Changing Device Orientation

Changing the Device Location

Device Controls and Actions

Interacting with the Screen

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.

Capturing Screen Images

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.

Manipulating Timeouts

Miscellaneous

Methods

captureRectWithName

Takes a screen shot of the specified rectangular portion of the device screen.

(undefined) captureRectWithName(Rect rect, String imageName)
Parameters
rect

The rect that defines the area of the screen to capture.

imageName

A string to use as the name for the resultant image file.

Discussion

Your script should treat the rect object as a generic JavaScript object whose properties for origin, x, y, size, width, and height correspond to those of the analogous CGRect Cocoa structure. The rect object has the form {origin:{x:xposition,y:yposition}, size:{width:widthvalue, height:heightvalue}}. The relevant coordinates are screen-relative and are adjusted to account for device orientation.

The image is saved as a file in .PNG graphic format, with the specified name, in the log.

captureScreenWithName

Takes a screen shot of the entire device screen.

(undefined) captureScreenWithName(String imageName)
Parameters
imageName

A string to use as the name for the resultant image file.

Discussion

The image is saved as a file in .PNG graphic format, with the specified name, in the log.

clickVolumeDown

Presses the volume down hardware button.

(undefined) clickVolumeDown()

clickVolumeUp

Presses the volume up hardware button.

(undefined) clickVolumeUp()

deactivateAppForDuration

Renders your app inactive for the specified duration.

(Boolean) deactivateApp(Number duration)
Parameters
duration

The time, in seconds, for the app to remain inactive.

Discussion

Use this method to test shifting your app to and from the background execution context. Note that apps built using iOS 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 App Programming Guide for details of multitasking and background execution context.

delay

Delays script execution for the specified time.

(Boolean) delay(Number timeInterval)
Parameters
timeInterval

The time to delay, in seconds.

Discussion

You can use this method to provide enough time for lengthy operations to complete.

deviceOrientation

Returns the current orientation of the device.

(Number deviceOrientation) deviceOrientation()
Discussion

The returned value is a constant that represents the physical orientation of the device and may be different from the current orientation of your app’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.

doubleTap

Double-taps the specified element or at the specified screen location.

(undefined) doubleTap(Object tapPointObject)
Parameters
tapPointObject

A rect, point, or UIAElement.

Discussion

The rect and point objects 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.

dragFromToForDuration

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)
Parameters
fromPointObject

The rect or point from which the drag action is to begin.

toPointObject

The rect or point at which the drag action is to end.

duration

The length of time, in seconds, between starting and stopping the gesture.

Discussion

The rect and point objects 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.

flickFromTo

Flicks from the specified starting screen location to the specified ending screen location.

(undefined) flickFromTo(fromPointObject, toPointObject)
Parameters
fromPointObject

The rect or point from which the flick action is to begin.

toPointObject

The rect or point at which the flick action is to end.

Discussion

The rect and point objects 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.

frontMostApp

Returns an object representing your app.

(UIAApplication) frontMostApp()
Discussion

This UIAApplication object is the centralized point of control and coordination for your app.

holdVolumeDown

Holds down the volume down hardware button for the specified duration.

(undefined) holdVolumeDown(Number duration)

holdVolumeUp

Presses and holds the volume up hardware button for the specified duration.

(undefined) holdVolumeUp(Number duration)

host

Returns an object representing the machine that is host to the current target.

(UIAHost) host()

localTarget

Returns an object representing the system under test (SUT).

(UIATarget) localTarget()

lock

Locks the device, using a lock event.

(undefined) lock()
Special Considerations

This method, and its counterpart, unlock, are deprecated. Use lockForDuration instead.

lockForDuration

Locks the device, using a lock event, for the specified duration.

(undefined) lockForDuration(Number duration)
Parameters
Duration

The length of time, in seconds, for the lock to persist.

Discussion

This method replaces the deprecated lock and unlock methods.

model

Returns the device model.

(String) model()
Discussion

Examples of model strings are iPhone and iPod touch.

name

Returns the device name.

(String) name()
Discussion

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.

pinchCloseFromToForDuration

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)
Parameters
fromPointObject

The rect or point from which the pinch-close action is to begin.

toPointObject

The rect or point at which the pinch-close action is to end.

duration

The length of time, in seconds, between starting and stopping the gesture.

Discussion

The rect and point objects 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.

pinchOpenFromToForDuration

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)
Parameters
fromPointObject

The rect or point from which the pinch-open action is to begin.

toPointObject

The rect or point at which the pinch-open action is to end.

duration

The length of time, in seconds, between starting and stopping the gesture.

Discussion

The rect and point objects 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.

popTimeout

Retrieves the previous timeout value from a stack, restores it as the current timeout value, and returns it.

(Number) popTimeout()
Return Value

The timeout value last stored on the stack with pushTimeout.

Discussion

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.

pushTimeout

Stores the current timeout value on a stack and sets a new timeout value.

(undefined) pushTimeout(timeoutValue)
Parameters
timeout

The length of the grace period, in seconds.

Discussion

This method, in conjunction with popTimeout, allows you to temporarily change the duration of the grace period for object resolution. This code changes the timeout period to 2 seconds before attempting to access an element, then restores the previous timeout period.

target = UIATarget.localTarget();
 
target.pushTimeout(2);
    // attempt element access
target.popTimeout();

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.

rect

Returns the rectangle surrounding the device’s main screen.

(Rect) rect()

rotateWithOptions

Performs a rotation gesture at the specified location.

(undefined) rotateWithOptions(Object location, Object options)
Parameters
location

The point object at center of the rotation gesture, with properties for x and y, corresponding to the analogous CGPoint Cocoa structure. The relevant coordinates are screen-relative and are adjusted to account for device orientation.

options

A dictionary that specifies characteristics of the rotation gesture. Valid keys are as follows:

duration

The length of hold time, in seconds, for the specified gesture. The default duration value is 1.

radius

The distance in points from the center to the edge of the circular path.

rotation

The length of rotation in radians. The default is pi (π).

touchCount

The number of touches to use in the specified gesture (effectively, the number of fingers a user would use to make the specified gesture.) Valid values are 1 to 5. The default is 2.

Discussion

This gesture is generated such that each touch is equidistant from the others.

setDeviceOrientation

Changes the device orientation to the specified new deviceOrientation value.

(undefined) setDeviceOrientation(Number deviceOrientation)
Discussion

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.

setLocation

Specifies a change in device’s latitude and longitude.

(boolean) setLocation(coordinates)
Parameters
coordinates

A dictionary that specifies the new location. Valid keys are as follows:

latitude

The latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator.

longitude

The longitude in degrees. Measurements are relative to the zero meridian, with positive values extending east of the meridian and negative values extending west of the meridian.

setLocationWithOptions

Specifies a change in the device’s latitude, longitude, and other characteristics.

(boolean) setLocationWithOptions(coordinates, options)
Parameters
coordinates

A dictionary that specifies the new location. Valid keys are as follows:

latitude

The latitude in degrees. Positive values indicate latitudes north of the equator. Negative values indicate latitudes south of the equator.

longitude

The longitude in degrees. Measurements are relative to the zero meridian, with positive values extending east of the meridian and negative values extending west of the meridian.

options

A dictionary that specifies additional characteristics of the location change. Valid keys are as follows:

altitude

The height, in meters, relative to sea level. Positive values indicate altitudes above sea level. Negative values indicate altitudes below sea level.

horizontalAccuracy

The radius, in meters, of the horizontal circle of uncertainty centered at the specified location. Negative values are invalid.

verticalAccuracy

The radius, in meters, of the horizontal circle of uncertainty centered at the specified location. Negative values are invalid.

course

The direction in which the device is moving, regardless of the device orientation.

speed

The speed, in meters per second, at which the device is moving.

setTimeout

Sets a new timeout value.

(undefined) setTimeout(Number timeout)
Parameters
timeout

A number representing the length,in seconds, of the grace period.

Discussion

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.

shake

Simulates a shake action on the device.

(undefined) shake()
Discussion

The shake action triggers a UIEvent of type UIEventSubtypeMotionShake, but does not affect the accelerometer itself.

systemName

Returns the name of the operating system running on the device.

(String) systemName()

systemVersion

Returns the current version of the operating system running on the device.

(String) systemVersion()
Discussion

An example of a system version string is 1.2.

tap

Taps the specified element or the specified screen location.

(undefined) tap(Object tapPointObject)
Parameters
tapPointObject

A rect, point, or UIAElement.

Discussion

The rect and point objects 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.

tapWithOptions

Taps the specified element with the specified options.

(undefined) tapWithOptions(Object tapPointObject, Object options)
Parameters
tapPointObject

A rect, point, or UIAElement.

options

A dictionary that specifies characteristics of the gesture. Valid keys are as follows:

tapCount

The number of taps that compose the specified gesture. The default value is 1 (single tap).

touchCount

The number of touches to use in the specified gesture. (Effectively, the number of fingers a user would use to make the specified gesture.) The default touch count value is 1.

duration

The length of hold time for the specified gesture. The default duration value for a tap is 0.

Discussion

The rect and point objects 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.

timeout

Returns the current timeout value.

(Number) timeout()
Discussion

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.

touchAndHold

Touches the specified element, or the specified screen location, and holds for the specified duration.

(undefined) touchAndHold(Object tapPointObject, Number duration)
Parameters
tapPointObject

A rect, point, or UIAElement.

duration

The length of time, in seconds, to hold the touch.

Discussion

The rect and point objects 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.

unlock

Unlocks the device using an unlock event followed by a drag of the slider.

(undefined) unlock()
Discussion

Simulating passcode entry is currently unsupported. Set the Settings > General > Passcode Lock feature to Off prior to running your tests.

Special Considerations

This method, and its counterpart, lock, are deprecated. Use lockForDuration instead.

Event Handlers by Task

Handling Alerts



Event Handlers

onAlert

Called by UI Automation to allow your script to respond to alerts.

(Boolean) onAlert(UIAAlert alert)
Parameters
alert

An object representing the alert encountered.

Return Value

Returns true if successful. Returns false to cause the default alert handler to run.

Discussion

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 attempts to dismiss the alert by first tapping the cancel button, if the button 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 only log an alert message and return false to let the default handler dismiss the alert.

Constants

Constants
UIA_DEVICE_ORIENTATION_UNKNOWN

The orientation of the device cannot be determined.

UIA_DEVICE_ORIENTATION_PORTRAIT

The device is in portrait mode, with the device upright and the home button at the bottom.

UIA_DEVICE_ORIENTATION_PORTRAIT_UPSIDEDOWN

The device is in portrait mode but upside down, with the device upright and the home button at the top.

UIA_DEVICE_ORIENTATION_LANDSCAPELEFT

The device is in landscape mode, with the device upright and the home button on the right side.

UIA_DEVICE_ORIENTATION_LANDSCAPERIGHT

The device is in landscape mode, with the device upright and the home button on the left side.

UIA_DEVICE_ORIENTATION_FACEUP

The device is parallel to the ground with the screen facing upward.

UIA_DEVICE_ORIENTATION_FACEDOWN

The device is parallel to the ground with the screen facing downward.