UIAElement Class Reference

Overview

The UIAElement class is the superclass for all user interface elements in the context of the Automation instrument for automating user interface testing of iOS apps.

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

Tasks

Determining Element Positioning

Determining and Manipulating Element Hierarchy

Gestures and Actions

These methods allow you to effect the common gestures and actions a user can perform through the user interface. Options are available for use with some of these methods to give you flexibility in defining and varying the attributes of the gesture or action to be performed.

Determining Element State

Use these methods to determine whether an element is still valid.

Identifying Elements

Logging Element Information

Methods

activityIndicators

Returns an array of the activity indicators contained by the specified object.

(UIAElementArray) activityIndicators()

activityView

Returns an object representing an activity view.

(UIAActivityView) activityView()

ancestry

Returns an array containing the parents of the specified object.

(UIAElementArray) ancestry()

buttons

Returns an array of buttons contained by the specified object.

(UIAElementArray) buttons()

checkIsValid

Returns the specified element’s current validity status.

(Boolean) checkIsValid()
Discussion

Use this method to determine whether the user interface element represented by the specified UIAElement currently exists. You should use checkIsValid, for example, if you’re referencing an element after having performed some action that may have changed the UI state of that element in some way. This requires a call to the underlying Accessibility framework to ensure the validity of the result.

See Also
  • isValid

collectionViews

Returns an array of collection views contained by the specified object.

(UIAElementArray collectionViews()

doubleTap

Double-taps the specified element.

(undefined) doubleTap()

dragInsideWithOptions

Drags within the bounds of an element.

(undefined) dragInsideWithOptions(Object options)
Parameters
options

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

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. The default value for touch-and-hold gestures (such as drag, pinch open, and pinch close) is 1.

startOffset

The first offset to use for a multiple-point gesture. The default value is {x:0.0, y:0.0}. See the discussion for details.

endOffset

The last offset to use for a multiple-point gesture. The default value is {x:0.0, y:0.0}. See the discussion for details.

Discussion

You can use offsets to achieve finer precision in specifying the hitpoint within the rect for the specified element. The offset comprises a pair of x and y values, each ranging from 0.0 to 1.0. These values represent, respectively, relative horizontal and vertical positions within the rect, with {x:0.0, y:0.0} as the top left and {x:1.0, y:1.0} as the bottom right. Thus, {x:0.3, y:0.6} specifies a position just below and to the left of center, and {x:1.0, y:0.5} specifies a position centered vertically at the far right.

This example performs a slow drag within the target element from left edge to right edge, just below the top:

target.dragInsideWithOptions({startOffset:{x:0.0, y:0.1}, endOffset:{x:1.0, y:0.1}, duration:1.5});

elements

Returns an array of elements contained by the specified object.

(UIAElementArray) elements()

flickInsideWithOptions

Flicks within the bounds of an element.

(undefined) flickInsideWithOptions(Object options)
Parameters
options

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

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.

startOffset

The first offset to use for a multiple-point gesture. The default value is {x:0.0, y:0.0}. See the discussion for details.

endOffset

The last offset to use for a multiple-point gesture. The default value is {x:0.0, y:0.0}. See the discussion for details.

Discussion

You can use offsets to achieve finer precision in specifying the hitpoint within the rect for the specified element. The offset comprises a pair of x and y values, each ranging from 0.0 to 1.0. These values represent, respectively, relative horizontal and vertical positions within the rect, with {x:0.0, y:0.0} as the top left and {x:1.0, y:1.0} as the bottom right. Thus, {x:0.3, y:0.6} specifies a position just below and to the left of center, and {x:1.0, y:0.5} specifies a position centered vertically at the far right.

This example performs a flick just above the bottom edge of the target element, from center to right edge:

target.flickInsideWithOptions({startOffset:{x:0.5, y:0.9}, endOffset:{x:1.0, y:0.9}});

hasKeyboardFocus

Determines whether the specified element receives keyboard input.

(Number) hasKeyboardFocus()
Return Value

Returns 1 if the specified element is the receiver of keyboard input, 0 if not. If the status is not available, it returns null.

hitpoint

Returns the screen position to tap for the specified element.

(Point) hitpoint()

images

Returns an array of images contained by the specified object.

(UIAElementArray) images()

isEnabled

Determines whether the specified element is enabled.

(Number) isEnabled()
Return Value

Returns 1 if the specified element is enabled, 0 if not. If the status is not available, it returns null.

isValid

Returns the specified element’s validity status as of the most recent access.

(Boolean) isValid()
Discussion

Use this method to determine whether the user interface element represented by the specified UIAElement existed as of the last attempt to access it. To be certain that the element exists, use checkIsValid instead.

See Also
  • checkIsValid

isVisible

Determines whether the specified element is visible on the screen.

(Number) isVisible()
Return Value

Returns 1 if the user interface element represented by the specified element is visible on screen, 0 if not. If the status is not available, it returns null.

label

Returns a string containing the label attribute of the element.

(String) label()
Discussion

This method always returns the label attribute string. (Contrast with the name method.)

links

Returns an array of links contained by the specified object.

(UIAElementArray) links()

logElement

Logs information about the specified element.

(undefined) logElement()
Discussion

This method can be used with any element.

logElementTree

Logs information about the specified element and all of its subelements.

(undefined) logElementTree()
Discussion

This method can be used with any element.

name

Returns a string containing the name attribute of the element.

(String) name()
Discussion

The element name is derived from the accessibility attribute of the underlying view. If an identifier attribute string is specified, that string is used as the name; otherwise, the label attribute string is used as the name. Contrast with the label method.

For more information, see UIAccessibilityIdentification Protocol Reference.

navigationBar

Returns the app’s navigation bar.

(UIAElement) navigationBar()
Discussion

This method has been moved up to this class from the UIAWindow Class.

navigationBars

Returns an array of navigation bar objects contained by this object.

(UIAElementArray) navigationBars()
Discussion

This method has been moved up to this class from the UIAWindow Class.

pageIndicators

Returns an array of page indicators contained by the specified object.

(UIAElementArray) pageIndicators()

parent

Returns the parent of the specified element.

(UIAElement) parent()

pickers

Returns an array of picker objects contained by the specified object.

(UIAElementArray) pickers()

popover

Returns the popover object associated with the specified object, if one exists.

(UIAPopover) popover()

progressIndicators

Returns an array of progress indicators contained by the specified object.

(UIAElementArray) progressIndicators()

rect

Returns the position of the object on the main screen.

(Rect) rect()
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.

rotateWithOptions

Perform a rotation gesture centered on the specified element.

(undefined) rotateWithOptions(Object options)
Parameters
options

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

centerOffset

The offset to use for the center of the rotate gesture. The default offset value is {x:0.0, y:0.0}.

duration

The length of hold time for the specified gesture, in seconds. 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.

scrollToVisible

Scrolls until the specified element is visible in a container view.

(undefined) scrollToVisible()
Discussion

Use this method with tables and web views.

scrollViews

Returns an array of scroll views contained by the specified object.

(UIAElementArray) scrollViews()

searchBars

Returns an array of search bars contained by the specified object.

(UIAElementArray) searchBars()

secureTextFields

Returns an array of secure text fields contained by the specified object.

(UIAElementArray) secureTextFields()

segmentedControls

Returns an array of segmented controls contained by the specified object.

(UIAElementArray) segmentedControls()

sliders

Returns an array of sliders contained by the specified object.

(UIAElementArray) sliders()

staticTexts

Returns an array of static texts contained by the specified object.

(UIAElementArray) staticTexts()

switches

Returns an array of switches contained by the specified object.

(UIAElementArray) switches()

tabBar

Returns the specified tab bar.

(UIAElement) tabBar()
Discussion

This method has been moved up to this class from the UIAWindow Class.

tabBars

Returns an array of tab bars contained by this object.

(UIAElementArray) tabBars()
Discussion

This method has been moved up to this class from the UIAWindow Class.

tableViews

Returns an array of table views contained by the specified object.

(UIAElementArray) tableViews()

tap

Taps the specified element.

(undefined) tap()

tapWithOptions

Performs the specified gesture on the specified element using a dictionary to specify gesture attributes.

(undefined) tapWithOptions(Object options)
Parameters
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. The default value for touch-and-hold gestures (such as drag, pinch open, and pinch close) is 1.

tapOffset

The offset to use for the specified tap gesture. The default offset value is {x:0.0, y:0.0}. See the discussion for details.

Discussion

For example, you could specify a triple tap with two fingers at the center of the screen (on an iPhone in portrait orientation), as follows:

element.tapWithOptions({touchCount:2, tapCount:3});

element.tapWithOptions({touchCount:2, tapCount:3, tapOffset:{x:0.75, y:0.25}});

You can use offsets to achieve finer precision in specifying the hitpoint within the rect for the specified element. The offset comprises a pair of x and y values, each ranging from 0.0 to 1.0. These values represent, respectively, relative horizontal and vertical positions within the rect, with {x:0.0, y:0.0} as the top left and {x:1.0, y:1.0} as the bottom right. Thus, {x:0.3, y:0.6} specifies a position just below and to the left of center, and {x:1.0, y:0.5} specifies a position centered vertically at the far right.

textFields

Returns an array of text fields contained by the specified object.

(UIAElementArray) textFields()

textViews

Returns an array of text views contained by the specified object.

(UIAElementArray) textViews()

toolbar

Returns the specified toolbar.

(UIAElement) toolbar()
Discussion

This method has been moved up to this class from the UIAWindow Class.

toolbars

Returns an array of toolbars contained by this object.

(UIAElementArray) toolbars()
Discussion

This method has been moved up to this class from the UIAWindow Class.

touchAndHold

Touches the specified element and holds for the specified duration.

(undefined) touchAndHold(Number duration)
Parameters
duration

The length of time to hold the touch on the element, in seconds.The default duration value for a tap is 0. The default value for touch-and-hold gestures (such as drag, pinch open, and pinch close) is 1.

twoFingerTap

Performs a two-finger (two-touch) tap on this element.

(undefined) twoFingerTap()

value

Returns a string containing a value attribute specific to the type of element.

(String) value()
Discussion

For example, a switch has a value of 1 for ON an 0 for OFF.

waitForInvalid

Waits for the specified element to become invalid.

(Boolean) waitForInvalid()
Discussion

Waits for the user interface element represented by the specified UIAElement to become invalid. Uses the current timeout value for the wait time interval.

webViews

Returns an array of web views contained by the specified object.

(UIAElementArray) webViews()

withName

Returns an element whose name attribute matches a specified string.

(UIAElement) withName(String name)
Parameters
name

A string containing the name to test for.

Discussion

Tests if the name attribute of the element has the given string value. If the match fails, the test is retried until the current timeout expires.

withPredicate

Returns the element matching the specified criteria.

(UIAElement) withPredicate(PredicateString predicateString)
Parameters
predicateString

A string specifying the match criteria.

Discussion

Uses the specified predicate string to test for a match. If the match fails, the test is retried until the current timeout expires. See Predicate Programming Guide for information about using predicates.

withValueForKey

Returns the element containing the specified property with the specified value.

(UIAElement) withValueForKey(NotTyped value, String key)
Parameters
value

A string specifying the value that the specified property, if it exists, should match.

key

A string specifying the property to test for.

Discussion

Tests if the element has a specified property with the specified value. If the match fails, the test is retried until the current timeout expires.