iOS Developer Library

Developer

UIAElement Class Reference

Options
Deployment Target:

On This Page

UIAElement

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

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable
  • Returns the screen position to tap for the specified element.

    Declaration

    JavaScript

    (Point) hitpoint()

  • Returns the position of the object on the main screen.

    Declaration

    JavaScript

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

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

    Declaration

    JavaScript

    (UIAElementArray) activityIndicators()

  • Returns an object representing an activity view.

    Declaration

    JavaScript

    (UIAActivityView) activityView()

  • Returns an array containing the parents of the specified object.

    Declaration

    JavaScript

    (UIAElementArray) ancestry()

  • Returns an array of buttons contained by the specified object.

    Declaration

    JavaScript

    (UIAElementArray) buttons()

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

    Declaration

    JavaScript

    (UIAElementArray collectionViews()

  • Returns an array of elements contained by the specified object.

    Declaration

    JavaScript

    (UIAElementArray) elements()

  • Returns an array of images contained by the specified object.

    Declaration

    JavaScript

    (UIAElementArray) images()

  • Returns an array of links contained by the specified object.

    Declaration

    JavaScript

    (UIAElementArray) links()

  • Returns the app’s navigation bar.

    Declaration

    JavaScript

    (UIAElement) navigationBar()

    Discussion

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

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

    Declaration

    JavaScript

    (UIAElementArray) navigationBars()

    Discussion

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

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

    Declaration

    JavaScript

    (UIAElementArray) pageIndicators()

  • Returns the parent of the specified element.

    Declaration

    JavaScript

    (UIAElement) parent()

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

    Declaration

    JavaScript

    (UIAElementArray) pickers()

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

    Declaration

    JavaScript

    (UIAPopover) popover()

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

    Declaration

    JavaScript

    (UIAElementArray) progressIndicators()

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

    Declaration

    JavaScript

    (UIAElementArray) scrollViews()

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

    Declaration

    JavaScript

    (UIAElementArray) searchBars()

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

    Declaration

    JavaScript

    (UIAElementArray) secureTextFields()

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

    Declaration

    JavaScript

    (UIAElementArray) segmentedControls()

  • Returns an array of sliders contained by the specified object.

    Declaration

    JavaScript

    (UIAElementArray) sliders()

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

    Declaration

    JavaScript

    (UIAElementArray) staticTexts()

  • Returns an array of switches contained by the specified object.

    Declaration

    JavaScript

    (UIAElementArray) switches()

  • Returns the specified tab bar.

    Declaration

    JavaScript

    (UIAElement) tabBar()

    Discussion

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

  • Returns an array of tab bars contained by this object.

    Declaration

    JavaScript

    (UIAElementArray) tabBars()

    Discussion

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

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

    Declaration

    JavaScript

    (UIAElementArray) tableViews()

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

    Declaration

    JavaScript

    (UIAElementArray) textFields()

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

    Declaration

    JavaScript

    (UIAElementArray) textViews()

  • Returns the specified toolbar.

    Declaration

    JavaScript

    (UIAElement) toolbar()

    Discussion

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

  • Returns an array of toolbars contained by this object.

    Declaration

    JavaScript

    (UIAElementArray) toolbars()

    Discussion

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

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

    Declaration

    JavaScript

    (UIAElementArray) webViews()

  • Double-taps the specified element.

    Declaration

    JavaScript

    (undefined) doubleTap()

  • Drags within the bounds of an element.

    Declaration

    JavaScript

    (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});

  • Flicks within the bounds of an element.

    Declaration

    JavaScript

    (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}});

  • Perform a rotation gesture centered on the specified element.

    Declaration

    JavaScript

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

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

    Declaration

    JavaScript

    (undefined) scrollToVisible()

    Discussion

    Use this method with tables and web views.

  • tap

    Taps the specified element.

    Declaration

    JavaScript

    (undefined) tap()

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

    Declaration

    JavaScript

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

  • Touches the specified element and holds for the specified duration.

    Declaration

    JavaScript

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

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

    Declaration

    JavaScript

    (undefined) twoFingerTap()

  • Returns the specified element’s current validity status.

    Declaration

    JavaScript

    (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

  • Determines whether the specified element receives keyboard input.

    Declaration

    JavaScript

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

  • Determines whether the specified element is enabled.

    Declaration

    JavaScript

    (Number) isEnabled()

    Return Value

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

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

    Declaration

    JavaScript

    (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

  • Determines whether the specified element is visible on the screen.

    Declaration

    JavaScript

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

  • Waits for the specified element to become invalid.

    Declaration

    JavaScript

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

  • Returns a string containing the label attribute of the element.

    Declaration

    JavaScript

    (String) label()

    Discussion

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

  • Returns a string containing the name attribute of the element.

    Declaration

    JavaScript

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

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

    Declaration

    JavaScript

    (String) value()

    Discussion

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

  • Returns an element whose name attribute matches a specified string.

    Declaration

    JavaScript

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

  • Returns the element matching the specified criteria.

    Declaration

    JavaScript

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

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

    Declaration

    JavaScript

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

  • Logs information about the specified element.

    Declaration

    JavaScript

    (undefined) logElement()

    Discussion

    This method can be used with any element.

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

    Declaration

    JavaScript

    (undefined) logElementTree()

    Discussion

    This method can be used with any element.