Windows XPath accessibility - Reference - Reference tables for the strategies, axes, predicates, and attribute names supported when you write a Windows accessibility XPath.

Automation 360

Reference tables for the strategies, axes, predicates, and attribute names supported when you write a Windows accessibility XPath.

Supported strategies

A strategy is a pattern for identifying an element. Choose the most robust strategy available for the target control.

Strategy XPath form When to use Example Robustness
Named element /Role[@name='X'] Element has a unique, stable accessible name /Button[@name='OK'] Most robust
Named descendant //Role[@name='X'] Stable name but hierarchy depth varies between sessions //Button[@name='Submit'] Most robust
AutomationId (UIA only) //Role[@automationid='id'] Developer-assigned ID is present and stable //Edit[@automationid='txtSearch'] Most robust
Named ancestor anchor /Group[@name='C']//Role[n] Target has no stable name but lives inside a named container /Group[@name='Toolbar']//Button[2] Most robust
Class-based /Role[@class='X'] Target node: name is empty but class is unique among same-role siblings /Document[@class='Chrome_RenderWidgetHostHWND'] Conditional
Contains name //Role[contains(@name,'X')] Name contains a known substring but varies (dynamic suffixes) //Button[contains(@name,'Save')] Conditional
Text equality //Role[.='X'] Full visible text of the element is the stable identifier //StaticText[.='Hello World'] Conditional
Regex name //Role[matches(@name,'pattern')] Name follows a predictable pattern (for example, generated row labels) //Edit[matches(@name,'Row \d+')] Conditional
Preceding-sibling anchor preceding-sibling::Role[@name='L'] Target has no stable name; a sibling before it does preceding-sibling::Text[@name='Username'] Conditional
Following-sibling anchor following-sibling::Role[@name='L'] Target has no stable name; a sibling after it does following-sibling::Button[@name='Cancel'] Conditional
Parent navigation ../Role[@name='X'] Need to step up one level, then select a sibling ../Button[@name='Apply'] Conditional
Attribute filter and positional //Role[@name='X'][n] Multiple elements share the same name; select the n-th one //ListItem[@name='Item'][3] Conditional
Positional /Role[n] No name, no unique class; position is currently stable /Pane[1]/Pane[2] Fragile
Descendant-axis shortcut //Role[n] Stable role and position anywhere in the tree //Table[1] Fragile

Supported axes

An axis controls the direction of traversal from the current node. All axes are supported by both MSAA and UIA engines.

Axis Syntax Behavior Example
Child /Role Direct children of the current node only. This is the default axis. /Button[@name='OK']
Descendant //Role All descendants at any depth, searched depth-first left-to-right. //Button[@name='OK']
Parent ../Role Navigate one level up to the parent, then continue the remaining steps from there. ../Button[@name='Apply']
Following sibling following-sibling::Role Siblings after the current node in the same parent, in document order. Position [1] is the immediately next sibling. following-sibling::Button[@name='Cancel']
Following following::Role All nodes after the current node in document order: following siblings, their subtrees, and ancestors' following siblings. following::Edit[1]
Preceding sibling preceding-sibling::Role Siblings before the current node, closest first. Position [1] is the immediately preceding sibling. preceding-sibling::Text[@name='Label']
Preceding preceding::Role All nodes before the current node in reverse document order (deepest last-child first). preceding::Button[1]
Warning: preceding-sibling position direction: [1] means the closest preceding sibling, not the first one in the parent. This is the opposite of the visual left-to-right order — preceding-sibling::Button[1] is the button immediately before the current node.
Example: Sibling relationship diagram
  Parent node
  |-- Button "First"       (preceding-sibling[2] from "Third")
  |-- Button "Second"      (preceding-sibling[1] from "Third", closest)
  |-- Button "Third"       (current node, the step being resolved)
  |-- Button "Fourth"      (following-sibling[1] from "Third", closest)
  \-- Button "Fifth"       (following-sibling[2] from "Third")

Supported predicates

Note: All attribute value comparisons are case-insensitive (for example, @name='submit' matches a button labeled "Submit"). matches() regex is also case-insensitive.

Attribute predicates

Form What it tests Example
@attr='val' Attribute equals val exactly [@name='Submit']
@attr Attribute is non-empty (existence check) [@automationid]
contains(@attr,'val') Attribute contains val as a substring [contains(@name,'Save')]
starts-with(@attr,'val') Attribute begins with val [starts-with(@class,'ui-')]
ends-with(@attr,'val') Attribute ends with val [ends-with(@name,'Button')]
matches(@attr,'regex') Attribute matches a .NET regular expression [matches(@name,'Row \d+')]

Text and name predicates

These test the element's accessible name, which is equivalent to @name.

Form What it tests Example
.='val' Element name equals val [.='OK']
text()='val' Element name equals val (alias) [text()='OK']
contains(.,'val') Element name contains val [contains(.,'Save')]
contains(text(),'val') Element name contains val (alias) [contains(text(),'Save')]

Positional predicates

Warning: Position counts among same-role siblings only. Button[2] is the second Button, not the second child of the parent. All positions are 1-based — [1] is the first.
Form Selects Example
N The N-th same-role sibling (1-based) [2]
position()=N The N-th same-role sibling (explicit form) [position()=3]
last() The last same-role sibling [last()]
last()-N The (count minus N)-th same-role sibling [last()-1]

Boolean compound predicates

Form Behavior Example
pred1 and pred2 Both conditions must match [@name='A' and @class='B']
pred1 or pred2 Either condition must match [@name='A' or @name='B']
not(pred) Inner predicate must not match [not(@name='hidden')]

Two-predicate form

When two sets of square brackets appear on a step, the second predicate applies to the subset produced by the first, not to all same-role siblings.

Button[@name='Save'][2]
  Step 1: filter all Button children by @name='Save'  -> [SaveDraft, SaveFinal]
  Step 2: take position [2] within that filtered set   -> SaveFinal
Note: This means Button[@name='Save'][2] finds the second button named Save, not the second button overall that happens to be named Save. This is standard XPath semantics.

Quick reference

Strategies at a glance

Form Example
//Role[@name='X'] //Button[@name='Submit']
//Role[@automationid='id'] //Edit[@automationid='txtSearch']
//Group[@name='C']//Role[@name='X'] //Group[@name='Toolbar']//Button[@name='Save']
//Role[contains(@name,'X')] //Button[contains(@name,'Save')]
//Role[@name='X'][n] //Button[@name='Delete'][2]
/Role[@class='X'] /Document[@class='Chrome_RenderWidgetHostHWND']
/Role[n] /Pane[1]/Pane[2]

Axes

Syntax Direction
/Role Direct child
//Role Any descendant (depth-first search)
../Role Up one level, then step
following-sibling::Role Siblings after current, [1] is nearest
following::Role All nodes after in document order
preceding-sibling::Role Siblings before current, [1] is nearest
preceding::Role All nodes before in reverse order

Predicates cheat sheet

Form Matches when…
[@name='X'] Accessible name equals X (case-insensitive)
[@automationid='id'] AutomationId equals id (UIA only)
[contains(@name,'X')] Name contains substring X
[starts-with(@name,'X')] Name starts with X
[ends-with(@name,'X')] Name ends with X
[matches(@name,'regex')] Name matches a .NET regular expression
[.='X'] Visible text equals X
[N] N-th among same-role siblings (1-based)
[last()] Last among same-role siblings
[pred1 and pred2] Both predicates match
[pred1 or pred2] Either predicate matches
[not(pred)] Predicate does not match
[pred1][N] N-th element matching pred1 (two-predicate form)