Skip to main content
Selectors are used in two places:
  • element-based taps
  • visibility assertions

​
Selector resolution

If a target string has no prefix, Visor treats it as an accessibility identifier. Example:
This resolves the same way as:

​
Supported selector prefixes

​
How text= works

text= performs an exact match against common text-like attributes. Visor builds an XPath selector that checks whether the provided value equals any of these attributes:
  • text
  • content-desc
  • label
  • name
  • value
Use text~= when you intentionally want substring matching across those same attributes. In mapped execution, broad numeric contains targets such as text~=$100 are only treated as live/current-screen taps; they are not used to route to an off-screen destination.

​
Section-relative mapped targets

Use first-in-section= when the request is relative to a visible section rather than a specific label. Example:
With mapped execution enabled, Visor routes to a screen containing that section heading and taps the first safe tappable item below it by source geometry. It skips section headings, See all controls, bottom navigation, back controls, static text, images, form fields, and hidden or zero-size elements.

​
Choosing the right selector type

Use selectors in this order when possible:
  1. accessibility identifiers
  2. stable ids
  3. platform-specific selectors
  4. XPath
  5. coordinates
This order matters because stable semantic selectors are easier to maintain and reason about.

​
Coordinate taps

Coordinates are appropriate when:
  • there is no reliable selector
  • the target is a canvas-like region or custom-drawn control
  • you need a specific screen location rather than an element
Coordinate inputs can be absolute or normalized.

​
Assertion targets use the same syntax

The visible assertion uses the same target parser as tap. That means these assertion targets are valid:
  • Increment
  • accessibility=Increment
  • text=Checkout
  • text~=Settings
  • id=primary-cta
  • xpath=//*[@text='Checkout']
  • uiautomator=new UiSelector().text("OK")
  • predicate=label == 'Done'
  • classchain=**/XCUIElementTypeButton[`label == "Done"`]

​
Known tradeoffs

Important tradeoffs in the current selector system:
  • plain text defaults to accessibility ids, not visible text
  • text~= is intentionally broad and may over-match
  • first-in-section= needs mapped execution and source geometry for the section item
  • XPath is flexible but tends to be the least stable option
  • coordinate taps are sensitive to layout shifts and device differences