RPA accessibility tree selectors: the actual grammar, with operator precedence

What "RPA selector" usually means, and what we mean

When a UiPath developer says selector, they mean the multi-line XML blob the recorder generates: a chain of <wnd>, <ctrl>, and <ui-element> nodes with attributes like aaname, ctrlname, cls, and idx. Power Automate Desktop and Automation Anywhere generate similar structures with their own schemas. They all read from the same Windows UI Automation tree underneath, but they store the path to a control as a long XML document that breaks when the app reflows.

Terminator does not generate selectors for you. You write them, by hand, against the same UI Automation tree (Inspect.exe and Accessibility Insights show you what is in there). What you write is short and structural: one line, prefix:value form, boolean operators where you need them, a descendant chain when you want to scope to a subtree. The selector is data, not code: you can build one at runtime from agent input or workflow parameters, parse it, and pass the AST to the locator engine. The implementation is one Rust file: lines 5 to 56 are the AST, lines 94 to 532 are the parser, and lines 533 onward are tests.

The full grammar, in one table

Every form below is parsed by parse_atomic_selector at selector.rs lines 335 to 472. Substring matching is the default; wildcards (*, ?) are not supported.

The AST: 25 variants in one Rust enum

Every parsed selector is an instance of this enum. The locator engine pattern-matches on it to dispatch to the right UI Automation call. There is nothing else: no hidden config, no string-based fallback inside the engine, no XPath evaluator.

// crates/terminator/src/selector.rs lines 5 to 56
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum Selector {
    Role { role: String, name: Option<String> },
    Id(String),
    Name(String),
    Text(String),
    Path(String),
    NativeId(String),
    Attributes(BTreeMap<String, String>),
    Filter(usize),
    Chain(Vec<Selector>),
    ClassName(String),
    Visible(bool),
    LocalizedRole(String),
    Process(String),
    RightOf(Box<Selector>),
    LeftOf(Box<Selector>),
    Above(Box<Selector>),
    Below(Box<Selector>),
    Near(Box<Selector>),
    Nth(i32),
    Has(Box<Selector>),
    Parent,
    And(Vec<Selector>),
    Or(Vec<Selector>),
    Not(Box<Selector>),
    Invalid(String),
}

Most variants take a value or a sub-selector. Five take another full Selector inside a Box: the four positional anchors and Has. Three take a Vec<Selector>: Chain, And, Or. The other 17 are leaves. Boolean parsers flatten nested And and Or on the way up (lines 290 to 304, 314 to 327), so a chain of three ANDs is one And(Vec[a, b, c]) rather than a deep tree.

Operator precedence is explicit, not whatever the parser felt like

One of the things that makes recorded RPA selectors fragile is that the precedence rules of the underlying matcher are usually undocumented and sometimes inconsistent. Terminator pins precedence in code:

// crates/terminator/src/selector.rs lines 206 to 213
fn operator_precedence(token: &Token) -> i32 {
    match token {
        Token::Or  => 1,
        Token::And => 2,
        Token::Not => 3,
        _ => 0,
    }
}

The shunting-yard loop at lines 216 to 272 reads tokens, pushes operators with this precedence, pops higher-precedence ones to the output queue, and at the end builds the AST. So the rule of thumb is the same as in any C-family language: !a && b || c is ((!a) && b) || c. Wrap with parentheses any time you want a different grouping. The tokenizer at lines 107 to 120 understands parens; the parser at lines 226 to 252 handles them via the operator stack.

The chain >> is split before boolean parsing

This is the part that surprises people. The chain operator >> does not participate in shunting yard. It is split out first, in From<&str>:

// crates/terminator/src/selector.rs lines 478 to 501
impl From<&str> for Selector {
    fn from(s: &str) -> Self {
        let s = s.trim();

        // Handle chained selectors first (>> has highest priority)
        if s.contains(">>") {
            let parts: Vec<&str> = s.split(">>").map(|p| p.trim()).collect();
            if parts.len() > 1 {
                let cleaned_parts: Vec<Selector> = parts
                    .into_iter()
                    .map(|part| {
                        let trimmed = part.trim();
                        if trimmed.starts_with('(') && trimmed.ends_with(')') {
                            let inner = &trimmed[1..trimmed.len() - 1];
                            if !has_unbalanced_parens(inner) {
                                return Selector::from(inner);
                            }
                        }
                        Selector::from(trimmed)
                    })
                    .collect();
                return Selector::Chain(cleaned_parts);
            }
        }
        // ... boolean ops parsed here, AFTER chain split
    }
}

The practical consequence: inside one chain segment, you can use &&, ||, and ! freely and they describe one element. Across chain segments, the boolean ops do not cross. So role:Window && name:Calc >> role:Button && name:Seven parses as find a Window that's also named Calc, then under it find a Button that's also named Seven. The && on each side is local to its own element. That's not how shunting-yard would have it if you fed the whole thing in. Splitting first preserves the developer's left-to-right reading.

The exception is when you wrap a chain step in parentheses. Lines 482 to 497 unwrap balanced outer parens before parsing each step, so (role:Window && name:Calc) >> nativeid:btnSeven is identical to the previous example with one less Button. Use parens for clarity, not for behavior.

The parse pipeline, end to end

Here is what happens when you call desktop.locator("process:notepad >> role:Edit && name:Body") on the selector string. Each arrow is a real function call inside selector.rs.

The tokenizer never sees >>. The shunting-yard parser never sees a chain. Each layer does one job and hands a smaller problem to the next. That is also why the parser is fast in practice: most selectors are one or two chain segments long, and inside a segment the token count rarely exceeds five or six.

A working example, in three SDKs

The same selector grammar works from Rust, Python, and the Node.js bindings, because the parser is in the core crate and every binding routes through it. The locator API surface is also identical: build a locator from a selector, call .first(timeout) or .all(timeout), then act on the element.

// Node.js, identical shape in Python and Rust
const { Desktop } = require('@mediar-ai/terminator');
const desktop = new Desktop();

// 1. Scope every chain to a process. Without this, your selector
//    can match the same role+name in any other running app.
const editor = desktop.locator(
  'process:notepad >> role:Document >> role:Edit'
);

// 2. Boolean ops bind tighter than chain. Parens force the order.
const saveBtn = desktop.locator(
  '(role:Button && name:Save) || (role:MenuItem && name:Save)'
);

// 3. has: takes another full selector as its argument.
const formWithEmail = desktop.locator(
  'role:Group && has:name:Email'
);

// 4. Positional anchors: get the field rightof: a label.
const dobField = desktop.locator(
  'role:Edit && rightof:name:Date Of Birth'
);

// .first() requires a timeout in ms. There is no default.
const el = await editor.first(5000);
await el.typeText('Hello, accessibility tree.');

Coming from UiPath: the mechanical mapping

The UiPath selector format is XML; Terminator's is a single-line expression. They describe the same path through the same UI Automation tree. The mapping for the leaf node:

• aaname='Save' becomes name:Save
• role='button' becomes role:Button
• cls='Edit' becomes classname:Edit
• ctrlname='txtAmount' becomes id:txtAmount or nativeid:txtAmount
• app:exename='notepad.exe' on the outer wnd becomes process:notepad.exe at the start of the chain
• Intermediate <ui-element> nodes become additional >> chain steps in the same order
• idx='3' becomes nth:2 (UiPath idx is 1-based, Terminator nth is 0-based)
• parentid and other UiPath-internal GUIDs are dropped; they don't exist in the underlying tree

A typical 12-line UiPath selector for a Save button in a custom WPF dialog collapses to roughly: process:MyApp.exe >> role:Window && name:Settings >> role:Button && name:Save. Five elements long, no XML, no recorded path. If the dialog reflows, you change the middle chain step instead of regenerating the whole selector.

Common patterns the grammar makes possible

A few patterns that traditional RPA selectors cannot express directly:

• Field by adjacent label. role:Edit && rightof:name:Date Of Birth. Works when the Edit field has no AutomationId and no name of its own. The label does the addressing.
• Form group containing a known field. role:Group && has:name:Email && has:role:Button. Useful for scoping into a specific section of a complex form.
• Negation against ambiguous matches. role:Button && !name:Cancel && !name:Help. Picks the action button that isn't one of the standard exits.
• Sibling lookup via parent. name:Submit && role:Button >> .. >> role:Edit. Grab the Edit field that lives under the same parent as the Submit button, no matter where in the parent it sits.
• Process-scoped wildcards via OR. process:chrome >> (role:Tab && (name:GitHub || name:GitLab)). One selector, multiple acceptable matches inside the same browser process.

None of these are special-cased in the engine. They fall out of the grammar. !, ||, has:, and the positional anchors compose because they all return Selector and the parser handles each one the same way.

What to read next, in source

If you want the full picture of how a selector turns into a UI Automation call, the path through the codebase is:

1. crates/terminator/src/selector.rs for the AST and parser (this guide).
2. crates/terminator/src/locator.rs for the high-level Locator type that wraps a Selector with a timeout, root scope, and .first() / .all() entry points.
3. crates/terminator/src/platforms/ for the platform engines that actually walk the UI Automation tree on Windows. The macOS adapter was deleted on 2025-12-16; if you need the AX path, see the companion guide on the macOS accessibility UI tree.
4. docs/SELECTORS_CHEATSHEET.md for an example-led reference if you prefer copy-paste over grammar.

The full grammar is small enough to memorize. Most of what you write in a real automation is two chain steps: process:something >> role:X && name:Y. The boolean ops, positional anchors, and has: are there for the cases where the recorded path is not stable, which on real desktop apps is most of them.