iOS Developer Library

Developer

UIATarget Class Reference

Options
Deployment Target:

On This Page

UIATarget

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable

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 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.

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

    Declaration

    JavaScript

    (UIAHost) host()

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    JavaScript

    (UIATarget) localTarget()

    Availability

    Available in iOS 4.0 and later.

  • Renders your app inactive for the specified duration.

    Declaration

    JavaScript

    (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 App Programming Guide for iOS for details of multitasking and background execution context.

    Availability

    Available in iOS 4.0 and later.

  • Returns an object representing your app.

    Declaration

    JavaScript

    (UIAApplication) frontMostApp()

    Discussion

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

    Availability

    Available in iOS 4.0 and later.

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

  • Returns the device model.

    Declaration

    JavaScript

    (String) model()

    Discussion

    Examples of model strings are iPhone and iPod touch.

    Availability

    Available in iOS 4.0 and later.

  • Returns the device name.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Returns the rectangle surrounding the device’s main screen.

    Declaration

    JavaScript

    (Rect) rect()

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (String) systemName()

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (String) systemVersion()

    Discussion

    An example of a system version string is 1.2.

    Availability

    Available in iOS 4.0 and later.

  • Returns the current orientation of the device.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Changes the device orientation to the specified new deviceOrientation value.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Specifies a change in device’s latitude and longitude.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 5.0 and later.

  • Presses the volume down hardware button.

    Declaration

    JavaScript

    (undefined) clickVolumeDown()

    Availability

    Available in iOS 4.0 and later.

  • Presses the volume up hardware button.

    Declaration

    JavaScript

    (undefined) clickVolumeUp()

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (undefined) holdVolumeDown(Number duration)

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (undefined) holdVolumeUp(Number duration)

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 5.0 and later.

  • Locks the device, using a lock event.

    Declaration

    JavaScript

    (undefined) lock()

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 5.0.

  • Simulates a shake action on the device.

    Declaration

    JavaScript

    (undefined) shake()

    Discussion

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

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (undefined) unlock()

    Discussion

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

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 5.0.

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.

  • Drags from a specified starting screen location to a specified ending screen location, for a specified length of time.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Pinches (performs a pinch-close gesture) from a specified starting screen location to a specified ending screen location, for a specified length of time.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Stretches (performs a pinch-open gesture) from a specified starting screen location to a specified ending screen location, for a specified length of time.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Performs a rotation gesture at the specified location.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 5.0 and later.

  • tap

    Taps the specified element or the specified screen location.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Taps the specified element with the specified options.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

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.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Takes a screen shot of the entire device screen.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Sets a new timeout value.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Returns the current timeout value.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

  • Delays script execution for the specified time.

    Declaration

    JavaScript

    (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.

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    JavaScript

    (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

  • Constant that represents the physical orientation of the device.

    Declaration

    Constants

    • UIA_DEVICE_ORIENTATION_UNKNOWN

      UIA_DEVICE_ORIENTATION_UNKNOWN

      The orientation of the device cannot be determined.

    • UIA_DEVICE_ORIENTATION_PORTRAIT

      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

      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

      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

      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

      UIA_DEVICE_ORIENTATION_FACEUP

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

    • UIA_DEVICE_ORIENTATION_FACEDOWN

      UIA_DEVICE_ORIENTATION_FACEDOWN

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