UIAElementArray Class Reference

Overview

The UIAElementArray class supports operations with arrays containing multiple UIAElement objects. You can search the array by name or key/value pairs, or by custom criteria that you specify using a predicate. For detailed information about using predicates, see Predicates Programming Guide.

UIAElementArray supports the traditional shorthand syntax for accessing items in native JavaScript objects:

It is important to note one potentially confusing limitation in using bracket references by element name. If the name of an element happened to be a number, JavaScript would interpret that name as an index, likely yielding incorrect results. For example, consider this array:

var elements = ["DoIt", "Cancel", "1"];

If you attempt to access the third element by name with the bracket reference syntax:

elements()["1"]

it is actually treated as a reference to the first element, yielding the first element (named “DoIt”) instead. In cases where this problem might occur, you should use the dot reference syntax instead:

elements().firstWithName("1")

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

Tasks

Working With Arrays

Properties

length

Returns the number of user interface elements in the array.

(Number) length

Methods

firstWithName

Returns the first element in the array with this name.

(UIAElement) firstWithName(String name)
Parameters
name

A string whose value is the name of the element match on.

firstWithPredicate

Returns the first element in the array matching the given criteria.

(UIAElement) firstWithPredicate(PredicateString predicateString)
Parameters
predicateString

A predicate specifying the criteria to match.

Discussion

For detailed information about predicate matching, see Predicate Programming Guide.

firstWithValueForKey

Returns the first element in the array with a value that matches the property key.

(UIAElement) firstWithValueForKey(NotTyped value, String key)

toArray

Converts the array into a standard JavaScript array.

(Array) toArray()

withName

Returns all elements in the array with this name.

(UIAElementArray) withName(String name)

withPredicate

Returns all elements in the array matching the given.

(UIAElementArray) withPredicate(PredicateString predicateString)
Discussion

Predicate matching follows the same rules as NSPredicate.

withValueForKey

Returns all elements in the array with a value that matches the property key.

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

Constants

UIAElementNil

Constants
UIAElementNil

Returned by a function with return type UIAElement or UIAElementArray if the requested element is not available after the timeout grace period you specify. This mechanism allows your scripting expressions to complete even if an intermediate function in the expression fails temporarily during the grace period. For example, the following code does not raise an exception if the navigation bar does not exist; instead it returns UIAElementNil.

var backButton = UIATarget.localTarget().frontMostApp().navigationBar().buttons()["Back"];
if (backButton.isValid()) {
    backButton.tap();
} else {
    UIALogger.logError("Could not find 'Back' button!");
}