Skip to content

feat(uiautomator2-server): add a class chain query parser - #173

Open
mykola-mokhnach wants to merge 3 commits into
mainfrom
feat/class-chain-chain-parser
Open

mykola-mokhnach wants to merge 3 commits into
mainfrom
feat/class-chain-chain-parser

Conversation

@mykola-mokhnach

@mykola-mokhnach mykola-mokhnach commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Second part of phase 1 of the class chain locator plan: the class chain parser. It follows #170 (predicate parser) and is parser and AST only, so there is no behaviour change. The evaluator and the -android class chain strategy come next.

Grammar

chain  := ["**/"] step ( "/" | "/**/" ) step )*
step   := ".." filter*                            // parent
        | ("^" | ">" | "<" | "~") type filter* [position]
        | type filter* [position]
type   := "*" | className
filter := "[`" predicate "`]" | "[$" predicate "$]"

Same shape as WebDriverAgent's FBClassChainQueryParser:

  • **/ at the start or /**/ between steps makes the next step a descendant lookup, a plain / means direct children.
  • [pred] filters the candidates themselves, [$pred$] keeps candidates that have a matching descendant. The filters keep their source order.
  • Filters must come before the position. The position is 1-based, negative counts from the end, 0 is invalid, and it can be set once.
  • A doubled ` or $ inside a predicate stands for the character itself.
  • No whitespace outside predicates, like in WDA.

Axes beyond WDA, so fromParent and sibling lookups have an equivalent. They are steps after a plain /:

Step Selects Position 1 is
.. the parent (filters only, no class name or position) the parent
^T ancestors of type T the nearest ancestor
>T following siblings the nearest one
<T preceding siblings the nearest one
~T siblings of type T on both sides, never the node itself (not a negation) the first in document order

They are rejected right after **/ or /**/, but a descendant step can follow them (../**/T). Example: **/*[`text == 'Price'`]/>android.widget.TextView[1].

Differences from WDA:

  • Class names are exact Android names (android.widget.Button, Outer$Inner), checked as dotted Java identifiers. There are no short names and no XCUIElementTypeAny, only *.
  • Predicates are parsed eagerly by PredicateParser, so an unknown attribute or a malformed value fails at parse time, with the predicate's own reason.
  • It is a hand-written scannerless recursive-descent parser like PredicateParser, not WDA's token state machine.

AST

  • ClassChain is an immutable list of ChainStep. Its toString() is a canonical form that parses back to the same chain.
  • ChainStep holds getAxis() (CHILD, DESCENDANT, PARENT, ANCESTOR, FOLLOWING_SIBLING, PRECEDING_SIBLING, SIBLING; isDescendant() is a shortcut), getClassName() (null for *), getFilters() (scope SELF or DESCENDANT plus a PredicateNode) and getPosition().

Errors

ClassChainSyntaxException extends InvalidSelectorException: Cannot parse class chain query '<q>'. <reason> at position N (0-based). A predicate error is reported as Invalid predicate: <reason> at the exact position in the query, also when the predicate contains doubled markers. The PredicateSyntaxException is chained as the cause.

Tests

30 tests in ClassChainParserTests: the valid and invalid vectors of WDA's FBClassChainTests, plus the axes, $ and dotted class names, escapes, the canonical round trip, error positions and immutability. The full server unit suite passes.

Parses `**/Type[`pred`][$descendant pred$][n]/Type...` into an immutable
ClassChain of ChainSteps, reusing PredicateParser for the predicates.
Parser and AST only, nothing uses it yet.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
mykola-mokhnach and others added 2 commits November 21, 2026 21:29
…lass chains

Map predicate error offsets back to the query when doubled markers were
collapsed, chain the predicate exception as the cause, accept
supplementary-plane identifier characters in class names, and tidy the
Javadoc and line lengths.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…lass chains

`..` selects the parent, `^T` ancestors, `>T`/`<T` following/preceding
siblings and `~T` all siblings. Positions count along the axis.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@mykola-mokhnach

mykola-mokhnach commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor Author

Locator examples, to give a feel for the grammar. Nothing here runs yet: the parser is not wired to a strategy, and -android class chain is the proposed strategy name.

Everyday lookups

Goal Legacy -android uiautomator Class chain
By text new UiSelector().text("Login") **/*[`text == 'Login'`]
By resource id .resourceId("com.app:id/submit") **/*[`resource-id == 'com.app:id/submit'`]
By content description .description("Back") **/*[`content-desc == 'Back'`]
Class plus text contains, case-insensitive .className("android.widget.Button").textContains("sign") (case-sensitive only) **/android.widget.Button[`text CONTAINS[c] 'sign'`]
Several conditions .className(...).clickable(true).enabled(true) **/android.widget.Button[`enabled == true AND clickable == true`]
Regex .textMatches("Item \\d+") **/*[`text MATCHES 'Item \\d+'`]
Third TextView .className(...).instance(2) **/android.widget.TextView[3]
Last TextView not possible **/android.widget.TextView[-1]

Structure

# direct children only, no deep search: the second row of a known list
**/androidx.recyclerview.widget.RecyclerView[`resource-id == 'com.app:id/list'`]/android.widget.LinearLayout[2]

# the switch inside the row that has the label "Wi-Fi" (descendant predicate)
**/android.widget.LinearLayout[$text == 'Wi-Fi'$]/**/android.widget.Switch

# only clickable rows that contain that label, then the first one
**/android.widget.LinearLayout[$text == 'Wi-Fi'$][`clickable == true`][1]

Axes

# the value next to a label (nearest following sibling)
**/*[`text == 'Price'`]/>android.widget.TextView[1]

# the parent of a button
**/*[`resource-id == 'com.app:id/ok'`]/..

# fromParent equivalent: other things inside the same container as the button
**/*[`resource-id == 'com.app:id/ok'`]/../**/android.widget.TextView

# nearest scrollable container above an element
**/*[`text == 'Wi-Fi'`]/^android.widget.ScrollView[1]

# all sibling Buttons, before and after the node (not the node itself)
**/*[`text == 'Save'`]/~android.widget.Button

Beyond what XPath or UiSelector do well

# numbers, not strings: wide, short elements
**/*[`bounds.width > 500 AND bounds.height < 200`]

# either of two classes, with a wildcard
**/*[`class IN {'android.widget.Button', 'android.widget.ImageButton'} AND text LIKE[c] 'save*'`]

# boolean attributes also take 1/0 and YES/NO
**/*[`checked == 1 AND NOT (enabled == NO)`]

# null check: original-text is nil when the node has no text at all
**/android.widget.TextView[`original-text == nil`]

Notes

  • There are no short class names: Button does not mean android.widget.Button.
  • Class names in the chain must be dotted Java identifiers (with $ for inner classes). A node that reports an unusual name can still be matched with **/*[`class == 'the.odd-name'`].
  • Axis symbols (.., ^, >, <, ~) are only recognised at the start of a step, where a class name cannot start with them, so they cannot clash with class names.
  • A backslash in a predicate string must be doubled (\d is written \\d), and doubled again in Java source.

@eglitise

Copy link
Copy Markdown
Contributor

The axes look like a very powerful addition! They are a little unclear to me though, so I'd like some clarification:

# the value next to a label (nearest following sibling)
**/*[`text == 'Price'`]/>android.widget.TextView[1]

I assume this would this find the first android.widget.TextView among all following siblings of **/*[`text == 'Price'`]?
Basically, **/*[`text == 'Price'`] and android.widget.TextView are siblings?

# nearest scrollable container above an element
**/*[`text == 'Wi-Fi'`]/^android.widget.ScrollView[1]

Would this iterate up the tree starting from **/*[`text == 'Wi-Fi'`], checking all of the node's parent until it finds android.widget.ScrollView, or reaches the root node?

# any sibling except the node itself
**/*[`text == 'Save'`]/~android.widget.Button

This is the most confusing one to me. Does it select all siblings of **/*[`text == 'Save'`] that are not android.widget.Button?

Regarding this exclusion axis, I'm not sure about using the tilde symbol (~) - I feel like perhaps an exclamation point (!) would be more intuitive, as this would be similar to its use in systems like regex?

Also, can the path chain continue after a request with an axis? e.g.

# the first button that precedes the first textview that succeeds a label
**/*[`text == 'Price'`]/>android.widget.TextView[1]/<android.widget.Button[1]

@mykola-mokhnach

Copy link
Copy Markdown
Contributor Author

@eglitise thanks, these are fair questions and my wording in the examples was sloppy. In order:

  1. >android.widget.TextView[1] - yes. The siblings of a node are the other children of the same parent. > looks at the ones after it in document order, and [1] is the nearest one that is an android.widget.TextView. So the label and the TextView share a parent.

  2. ^android.widget.ScrollView[1] - yes. It walks up from the node: parent, grandparent and so on up to the root, and [1] is the nearest ScrollView. If there is none, the step matches nothing (it is not an error).

  3. ~android.widget.Button - it is not an exclusion, and the comment in my example ("any sibling except the node itself") was misleading. ~T means "siblings of type T on either side" (the union of <T and >T), and the node itself is never included. So it selects all sibling Buttons, before and after the Save node, not "siblings that are not Buttons".
    On !: in the predicates !, != and NOT already mean negation, so I would rather not reuse it for "either side". Negation stays in the predicate:
    **/*[`text == 'Save'`]/~*[`NOT class == 'android.widget.Button'`] selects the siblings that are not Buttons. If ~ is still not intuitive after this, I am open to another symbol or a named form. CSS uses ~ for following siblings only, which may add to the confusion.

  4. Chaining - yes, any step can follow any step, and each step runs for every node the previous step returned. Your example is valid:
    **/*[`text == 'Price'`]/>android.widget.TextView[1]/<android.widget.Button[1]
    Positions on < and ^ count nearest first, so <android.widget.Button[1] is the closest Button before that TextView among its siblings (not the first Button in the parent).

Equivalent XPath

The XPath below is written for the XPath 2.0 engine. enforceXPath1 switches to 1.0, which has no lower-case(), matches() or parenthesized steps.

The axes:

# next to a label
**/*[`text == 'Price'`]/>android.widget.TextView[1]
//*[@text='Price']/following-sibling::android.widget.TextView[1]

# nearest scroll container above
**/*[`text == 'Wi-Fi'`]/^android.widget.ScrollView[1]
//*[@text='Wi-Fi']/ancestor::android.widget.ScrollView[1]

# all sibling Buttons, both sides
**/*[`text == 'Save'`]/~android.widget.Button
//*[@text='Save']/(preceding-sibling::android.widget.Button | following-sibling::android.widget.Button)

# siblings that are not Buttons
**/*[`text == 'Save'`]/~*[`NOT class == 'android.widget.Button'`]
//*[@text='Save']/(preceding-sibling::* | following-sibling::*)[not(@class='android.widget.Button')]

# your chained example
**/*[`text == 'Price'`]/>android.widget.TextView[1]/<android.widget.Button[1]
//*[@text='Price']/following-sibling::android.widget.TextView[1]/preceding-sibling::android.widget.Button[1]

# parent, and the fromParent equivalent
**/*[`resource-id == 'com.app:id/ok'`]/..
//*[@resource-id='com.app:id/ok']/..

**/*[`resource-id == 'com.app:id/ok'`]/../**/android.widget.TextView
//*[@resource-id='com.app:id/ok']/..//android.widget.TextView
The rest of the examples from the earlier comment
**/*[`text == 'Login'`]
//*[@text='Login']

**/*[`resource-id == 'com.app:id/submit'`]
//*[@resource-id='com.app:id/submit']

**/*[`content-desc == 'Back'`]
//*[@content-desc='Back']

**/android.widget.Button[`text CONTAINS[c] 'sign'`]
//android.widget.Button[contains(lower-case(@text), 'sign')]

**/android.widget.Button[`enabled == true AND clickable == true`]
//android.widget.Button[@enabled='true' and @clickable='true']

# MATCHES is a full match in the class chain, `matches()` in XPath is not anchored
**/*[`text MATCHES 'Item \\d+'`]
//*[matches(@text, '^Item \d+$')]

**/android.widget.TextView[3]
(//android.widget.TextView)[3]

**/android.widget.TextView[-1]
(//android.widget.TextView)[last()]

**/androidx.recyclerview.widget.RecyclerView[`resource-id == 'com.app:id/list'`]/android.widget.LinearLayout[2]
//androidx.recyclerview.widget.RecyclerView[@resource-id='com.app:id/list']/android.widget.LinearLayout[2]

# [$...$] needs a matching descendant
**/android.widget.LinearLayout[$text == 'Wi-Fi'$]/**/android.widget.Switch
//android.widget.LinearLayout[.//*[@text='Wi-Fi']]//android.widget.Switch

**/android.widget.LinearLayout[$text == 'Wi-Fi'$][`clickable == true`][1]
(//android.widget.LinearLayout[.//*[@text='Wi-Fi'] and @clickable='true'])[1]

**/*[`class IN {'android.widget.Button', 'android.widget.ImageButton'} AND text LIKE[c] 'save*'`]
//*[@class=('android.widget.Button', 'android.widget.ImageButton') and starts-with(lower-case(@text), 'save')]

**/*[`checked == 1 AND NOT (enabled == NO)`]
//*[@checked='true' and not(@enabled='false')]

**/android.widget.TextView[`original-text == nil`]
//android.widget.TextView[not(@original-text)]

Two examples have no practical XPath equivalent or need a check:

  • **/*[`bounds.width > 500 AND bounds.height < 200`]: XPath only sees @bounds as the string [l,t][r,b], so a numeric comparison would need string parsing.
  • original-text == nil: the not(@original-text) form assumes a null value is left out of the XML. I have not confirmed that yet, so the e2e tests should cover it.

In XPath, class names with $ are normalized in tag names, so for inner classes use //*[@class='Outer$Inner'].

@eglitise

Copy link
Copy Markdown
Contributor

Thanks for the clarification, it's a lot more clear to me now. I agree that the exclamation point symbol does not make sense for this usecase. The tilde symbol isn't particularly intuitive still, but I also can't think of any other symbol available on a standard keyboard that would work better.

pos += 2; // "[" and the marker
StringBuilder text = new StringBuilder();
// source index of each predicate character, so errors point into the query
int[] sourceIndex = new int[source.length() + 1];

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we translate the predicate offset only when PredicateParser.parse throws? Each filter allocates an int[] sized to the entire query, so total allocation grows quadratically for chains with many short filters. Saving the predicate start and scanning past doubled markers on error would preserve the reported offsets and avoid allocating the array on successful parses.

@Override
public String toString() {
String marker = String.valueOf(scope.getMarker());
String escaped = predicate.toString().replace(marker, marker + marker);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we add a round-trip test at the predicate depth limit? For example, TRUEPREDICATE AND followed by 63 copies of NOT and a final TRUEPREDICATE parses at depth 64. The logical predicate formatter then adds outer parentheses around the AND, so reparsing the serialized filter reaches depth 65 and fails. Omitting redundant parentheses at the filter root would preserve the round trip for this case.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants