Selectors

A selector is how you tell the bot which element to act on: this button, that field, that cell. It is the most important concept in browser (Browser) and desktop (Desktop) automation: without a good selector, the activity doesn’t know where to click or what to read, and the bot fails.

The good news is that you almost never write a selector by hand: you capture it by pointing with the mouse with UI Discover. This page explains what a selector is and how it is built, so you understand what you capture, know how to adjust it when a page changes and build selectors that don’t break over time.

What problem does it solve?

A web page or a window has no “fixed coordinates”: a button moves if the window is resized, if a notice appears above it or if the app is updated. Pointing by coordinates (click on pixel 320,540) is fragile: the first time something moves, the bot clicks in the wrong place.

A selector, instead, identifies the element by what it is, not by where it is: “the button whose text is Save”, “the field whose id is user”. That way the bot finds it even if it moved.

Anatomy of a selector

A selector is a hierarchy of nodes, from the window or the browser (the root) down to the specific element you want to interact with (the leaf). Each node is a level of that hierarchy and has a type and some attributes.

Node type	Represents	Example attributes
wnd	An operating system window (the app, the browser)	process, title, cls
webctrl	A web element (inside the browser)	tag, id, aaname, name, type, idx
frame	An iframe (a page embedded in another)	src, name, idx
ctrl	A native desktop control (button, field, list…)	controlType, automationId, name, idx

In the Selector explorer you see those nodes as cards: the last one (the element) is the target, and the previous ones (context) are its ancestors, which help locate it without ambiguity.

A selector also stores two auxiliary pieces of data that are captured automatically and act as a safety net (explained in How it finds the element):

• CSS fallback: a CSS selector for the element.
• XPath: the absolute path of the element in the document.

The attributes

An attribute is a clue to identify the element. You don’t need all of them: the fewer and the more stable, the better. These are the ones a selector can use:

Attribute	Meaning	Context
process	Window executable (chrome.exe, notepad.exe)	window
title	Window or page title	window
cls	CSS class (web) or Win32 window class	both
tag	HTML tag (BUTTON, INPUT, TABLE, TR, TD…)	web
id	The HTML element’s id attribute — the most stable	web
aaname	Accessible name: the visible text or the aria-label of the element	web
name	The HTML name attribute (very stable in forms)	web
type	The type attribute (submit, text, checkbox…)	web
href	Link destination	web
src	Source of a frame or image	web
idx	1-based index among siblings of the same type (tiebreaker)	both
controlType	UIA control type (Button, Edit, List…)	desktop
automationId	The control’s AutomationId — the most stable on desktop	desktop
name	Accessible name of the desktop control	desktop

The golden rule

Always prefer stable and unique attributes: id (web) and automationId (desktop). If they don’t exist, use name, aaname or aria-label. Leave idx (the position) and the XPath as a last resort: they are the first to break when the page changes.

Matching modes: the value of an attribute

This is the part that makes a selector robust or fragile. The value of any attribute can be written in four ways, and choosing well is what keeps the bot from breaking when the text changes. In the Selector explorer you pick the form from a list (equals, contains, starts with, wildcard, regular expression) instead of typing the notation.

Mode	How it is written	Matches…	Example
Literal	The text as is	Exact match (case-insensitive)	user
Wildcard	With * at the start, the end or both	Any text at the * position	Order * matches Order 1024
Expression	{{ expression }} inside the value	Whatever the expression returns at run time	row-{{ index }}
Regex	Between slashes /pattern/	The regular expression pattern	/^Order-\d+$/

A real case makes it clearer:

• An invoice whose title is “Order 1024” today and “Order 1025” tomorrow. If you capture the literal Order 1024, the selector works once and fails the next day. Change the value to Order * and it works every time.
• In a loop over rows, the idx attribute can carry an expression: {{ row + 1 }}. That way the same activity points to row 1, 2, 3… as the loop advances. This is what turns a static selector into a dynamic one.

Dynamic selectors are very powerful

Since the value accepts expressions, a single selector can go through a table, open the nth result of a search or select an element whose name depends on a variable. Combine it with a For Loop and a single flow processes dozens of elements. See Expressions.

How it finds the element (resolution order)

When the activity runs, Zoan Automation tries to locate the element with strategies from the most stable to the most fragile, and keeps the first one that works. Knowing this order helps you understand why a selector is good or bad — and it is exactly what the Validate button in UI Discover measures.

In the browser, the order for each node is:

1. id → the most stable.
2. data-testid → stable in modern apps.
3. name → very stable in forms.
4. aria-label → precise and language-independent.
5. placeholder → for fields without a label.
6. aaname (text / accessible name).
7. The node’s CSS (tag + cls + type).
8. CSS fallback (the safety net captured when pointing).
9. Absolute XPath → last resort, fragile when the structure changes.

What the Validate colors mean

When you validate a selector in UI Discover, the result tells you which route found the element — and that predicts its reliability:

• 🟢 Green: found through the semantic route (id, name, aria-label, text…). It is the same result you’ll get at run time. Robust.
• 🟠 Orange: found only by CSS. It works, but it may fail if the classes change. It is worth recapturing.
• 🟣 Purple: found only by XPath. It is the last-resort net; it is fragile. Recapture looking for more stable attributes.
• 🔴 Red: not found. The page isn’t loaded, it changed, or the selector is wrong.

Always aim for green selectors.

On the desktop the logic is similar, giving priority to the control’s automationId and name over its position.

Anchors: when the element has nothing of its own

Sometimes the target element has no unique attributes: a field with no id, no name, no label — just a blank box next to the text “Last name”. Or there are several identical ones, like the Edit button of each row of a table. How do you tell the bot which one?

With an anchor: you locate the target relative to a reference element that can be identified. “The field next to the Last name label”, “the Edit of the row that says sales@company.com”.

When you capture an anchor, the Designer saves where it was relative to the target. At run time, the robot finds the anchor and picks, among the candidates, the one in that same position relative to it. A cell or a row is used as an anchor by its text, in whatever row or position it is, and that text can come from a variable with {{ }}.

Each anchor has a maximum distance in pixels: if no candidate is within that radius, the anchor doesn’t apply. You capture and tune anchors in the Selector explorer, node by node like the target.

Fixed relations

An anchor also accepts a fixed relation in its JSON (right_of, left_of, below, above, nearest) instead of the captured position. It is useful when you write the selector by hand; when capturing you don’t need it.

Tip

Anchors are the tool for forms without associated labels and tables whose cells have no identifier. Before falling back on idx (pure position), ask yourself whether there is a nearby, stable text you can use as an anchor.

Fragile selector warnings

You don’t have to wait for the robot to fail on another machine to learn that a selector is fragile. While you design, the Problems panel flags with “Fragile selector: it may fail on another machine” the selectors that depend on something that changes from one computer or one run to another, and tells you what to do in each case:

The selector depends on…	Suggestion
The position on screen (a desktop control with no id or name)	Add an anchor (a nearby text) in the selector editor.
An id the page generates on its own	Capture it again, or use its text, label or name instead of the id.
A text that looks like data (a date, an amount, an email)	Replace the part that changes with * (for example Order *).
A style class that changes between versions or states	Capture it again or add an anchor.
Its position among similar ones	Add an anchor.
An absolute XPath	Capture it again so it is identified by its text, label or name.
In SAP, the connection and session number or a visible row of a table	Follow the warning’s suggestion.

Warnings don’t block running or publishing. A click on the warning takes you to the activity and the selector field.

Best practices for robust selectors

1. Capture, don’t write. Use UI Discover: point and click. Only adjust by hand what is needed.
2. Less is more. Remove attributes that don’t add uniqueness. A unique id is enough; adding cls, idx and position only makes it more fragile.
3. Prioritize what is stable: id / automationId > name / aria-label / aaname > classes > idx / XPath.
4. Use wildcards for text that changes. Any number, date or reference in a value → turn it into * or a regex.
5. Act on the Problems warnings. A fragile selector works on your computer and fails on the robot’s.
6. Use anchors, not positions. Before setting idx, look for a stable nearby text.
7. Check on the real screen. The Selector explorer tells you how many elements the selector finds; go for 1 match or for the anchor to decide.
8. Repair after a redesign. If the target application is updated, Find what changed tells you which attribute changed and repairs it keeping your adjustments.

Next steps

• UI Discover: the tool to capture selectors by pointing with the mouse.
• Selector explorer: to tune and repair selectors with the screen in view.
• Browser: activities that use selectors on web pages.
• Desktop: activities that use selectors in Windows applications.
• Expressions: to build dynamic attribute values.