iOS Predicate

NOTE: iOS predicates are usable in iOS 9.3 and below using the -ios uiautomation locator strategy and they are usable in iOS 10 and above using the -ios predicate string locator strategy

It is worth looking at '-ios uiautomation' search strategy with Predicates. UIAutomation JavaScript API has following methods which can are very useful.

(UIAElement) UIAElementArray.firstWithPredicate(PredicateString predicateString)
(UIAElementArray) UIAElementArray.withPredicate(PredicateString predicateString)

Native JS search strategy (powered by Apple) provides much more flexibility and is like Xpath. Predicates can be used to restrict an elements set to select only those ones for which some condition is true.

'-ios uiautomation' example:

// java
appiumDriver.findElementsByIosUIAutomation("collectionViews()[0].cells().withPredicate(\"ANY staticTexts.isVisible == TRUE\")");

'-ios predicate string' example:

// java
appiumDriver.findElementsByIosNsPredicate("isWDVisible == 1");

- will select only those UIACollectionCell elements that have visible UIAStaticText child elements, and themselves are childs of 1st UIACollectionView element that should be located under the main app window. Here staticTexts() and isVisible() are methods available in UIAElementArray and UIAElement classes respectively. Note that UIAElementArray numbering begins with 0 unlike Xpath where indexes counting starts from 1

Here's a list of available Predicates (mostly taken from Predicates Programming Guide)

Basic Comparisons

= , == - The left-hand expression is equal to the right-hand expression:

tableViews()[1].cells().firstWithPredicate("label == 'Olivia' ")

same in Xpath: /UIATableView[2]/UIATableCell[@label = 'Olivia'][1]

>= , => - The left-hand expression is greater than or equal to the right-hand expression.

<= , =< - The left-hand expression is less than or equal to the right-hand expression.

> - The left-hand expression is greater than the right-hand expression.

< - The left-hand expression is less than the right-hand expression.

!= , <> - The left-hand expression is not equal to the right-hand expression.

BETWEEN - The left-hand expression is between, or equal to either of, the values specified in the right-hand side. The right-hand side is a two value array (an array is required to specify order) giving upper and lower bounds. For example, 1 BETWEEN { 0 , 33 }, or $INPUT BETWEEN { $LOWER, $UPPER }. In Objective-C, you could create a BETWEEN predicate as shown in the following example:

NSPredicate *betweenPredicate =
    [NSPredicate predicateWithFormat: @"attributeName BETWEEN %@", @[@1, @10]];

This creates a predicate that matches ( ( 1 <= attributeValue ) && ( attributeValue <= 10 ) )

Boolean Value Predicates

TRUEPREDICATE - A predicate that always evaluates to TRUE .

FALSEPREDICATE - A predicate that always evaluates to FALSE.

Basic Compound Predicates

AND , && - Logical AND.

OR , || - Logical OR.

NOT , ! - Logical NOT.

String Comparisons

String comparisons are by default case and diacritic sensitive. You can modify an operator using the key characters c and d within square braces to specify case and diacritic insensitivity respectively, for example firstName BEGINSWITH[cd] $FIRST_NAME

BEGINSWITH - The left-hand expression begins with the right-hand expression.

scrollViews()[3].buttons().firstWithPredicate("name BEGINSWITH 'results toggle' ")

same in Xpath: /UIAScrollView[4]/UIAButton[starts-with(@name, 'results toggle')][1]

CONTAINS - The left-hand expression contains the right-hand expression.

tableViews()[1].cells().withPredicate("ANY collectionViews[0].buttons.name CONTAINS 'opera'")

same in Xpath: /UIATableView[2]/UIATableCell[UIACollectionView[1]/UIAButton[contains(@name, 'opera')]]

ENDSWITH - The left-hand expression ends with the right-hand expression.

LIKE - The left hand expression equals the right-hand expression: ? and * are allowed as wildcard characters, where ? matches 1 character and * matches 0 or more characters. In Mac OS X v10.4, wildcard characters do not match newline characters.

tableViews()[0].cells().firstWithPredicate("name LIKE '*Total: $*' ")

same in Xpath: /UIATableView[1]/UIATableCell[matches(@name, '.*Total: \$.*')][1]

MATCHES - The left hand expression equals the right hand expression using a regex -style comparison according to ICU v3 (for more details see the ICU User Guide for Regular Expressions).

tableViews().firstWithPredicate("value MATCHES '.*of 7' ")

same in Xpath: /UIATableView[matches(@value, '.*of 7')][1]

Aggregate Operations

ANY , SOME - Specifies any of the elements in the following expression. For example ANY children.age < 18 .

tableViews()[0].cells().firstWithPredicate("SOME staticTexts.name = 'red'").staticTexts().withName('red')

same in Xpath: /UIATableView[1]/UIATableCell[UIAStaticText/@name = 'red'][1]/UIAStaticText[@name = 'red']

ALL - Specifies all of the elements in the following expression. For example ALL children.age < 18 .

NONE - Specifies none of the elements in the following expression. For example, NONE children.age < 18 . This is logically equivalent to NOT (ANY ...) .

IN - Equivalent to an SQL IN operation, the left-hand side must appear in the collection specified by the right-hand side. For example, name IN { 'Ben', 'Melissa', 'Matthew' } . The collection may be an array, a set, or a dictionary—in the case of a dictionary, its values are used.

array[index] - Specifies the element at the specified index in the array.

array[FIRST] - Specifies the first element in the array.

array[LAST] - Specifies the last element in the array.

array[SIZE] - Specifies the size of the array

elements()[0].tableViews()[0].cells().withPredicate("staticTexts[SIZE] > 2")
same in Xpath: /*[1]/UIATableView[1]/UIATableCell[count(UIAStaticText) > 2]

Identifiers

C style identifier - Any C style identifier that is not a reserved word.

#symbol - Used to escape a reserved word into a user identifier.

[\]{octaldigit}{3} - Used to escape an octal number ( \ followed by 3 octal digits).

[\][xX]{hexdigit}{2} - Used to escape a hex number ( \x or \X followed by 2 hex digits).

[\][uU]{hexdigit}{4} - Used to escape a Unicode number ( \u or \U followed by 4 hex digits).

Literals

Single and double quotes produce the same result, but they do not terminate each other. For example, "abc" and 'abc' are identical, whereas "a'b'c" is equivalent to a space-separated concatenation of a, 'b', c.

FALSE , NO - Logical false.

TRUE , YES - Logical true.

NULL , NIL - A null value.

SELF - Represents the object being evaluated.

"text" - A character string.

'text' - A character string.

Comma-separated literal array - For example, { 'comma', 'separated', 'literal', 'array' } .

Standard integer and fixed-point notations - For example, 1 , 27 , 2.71828 , 19.75 .

Floating-point notation with exponentiation - For example, 9.2e-5 .

0x - Prefix used to denote a hexadecimal digit sequence.

0o - Prefix used to denote an octal digit sequence.

0b - Prefix used to denote a binary digit sequence.

Reserved Words

The following words are reserved:

AND, OR, IN, NOT, ALL, ANY, SOME, NONE, LIKE, CASEINSENSITIVE, CI, MATCHES, CONTAINS, BEGINSWITH, ENDSWITH, BETWEEN, NULL, NIL, SELF, TRUE, YES, FALSE, NO, FIRST, LAST, SIZE, ANYKEY, SUBQUERY, CAST, TRUEPREDICATE, FALSEPREDICATE

Appium predicate helpers

Appium has helpers for predicate search in app.js:

Here's a Ruby example:

# Ruby example
text = 'Various uses'
predicate = "name contains[c] '#{text}' || label contains[c] '#{text}' || value contains[c] '#{text}'"
element = execute_script(%Q(au.mainApp().getFirstWithPredicate("#{predicate}");))

puts element.name # Buttons, Various uses of UIButton