Skip to main content

​
Overview

A selector tells the executor which DOM element to interact with. Selectors use multiple fields as fallback strategies — the executor tries each in priority order until a match is found.

​
Selector fields

FieldTypePriorityDescription
idstring1Element id attribute (most reliable)
ariaLabelstring2aria-label attribute
dataTestIdstring3data-testid attribute
dataAttributesRecord<string, string>4Other data-* attributes
cssSelectorstring5CSS selector
xPathstring6XPath expression
labelTextstring7Associated <label> text
innerTextstring8Element inner text (max 200 chars)
placeholderstring9placeholder attribute
namestring10name attribute
rectobject11Position-based fallback (last resort)
tagNamestring—HTML tag name (always present, used for filtering)
rolestring—ARIA role attribute
inputTypestring—type attribute of <input> elements

​
Resolution pipeline

The executor resolves selectors through a 6-stage pipeline:
1

Deterministic resolution

Tries each selector field in priority order (id → ariaLabel → … → name). No AI needed.
2

AI selector resolution

If deterministic resolution fails, AI analyzes the current page snapshot to find the target element.
3

Smart retry (3x)

Retries with increasing timeouts, waiting for DOM changes between attempts.
4

Scroll recovery

Scrolls the page to locate off-screen elements.
5

Agent Fallback

AI agent explores alternative paths to reach the target element. Requires Pro+ plan.
6

Vision Fallback

Takes a screenshot and uses vision AI to locate the element visually. Requires Pro+ plan.

​
Example

action:
  type: click
  selector:
    tagName: button
    id: "submit-btn"
    ariaLabel: "Submit form"
    innerText: "Submit"
    role: "button"
In this example, the executor will:
  1. Try #submit-btn first
  2. Fall back to [aria-label="Submit form"] if the id is not found
  3. Fall back to matching innerText if aria-label fails
  4. Use role and tagName as additional filters throughout

​
rect (position fallback)

Used as a last-resort deterministic strategy. Coordinates are relative to the viewport. 
selector:
  tagName: button
  rect:
    x: 150
    y: 300
    width: 120
    height: 40
FieldTypeDescription
xnumberX coordinate
ynumberY coordinate
widthnumberElement width
heightnumberElement height
Position-based selectors are fragile — they break when the layout changes. Prefer semantic selectors (id, ariaLabel, dataTestId) whenever possible.

​
dataAttributes

Match elements by custom data-* attributes: 
selector:
  tagName: div
  dataAttributes:
    row-id: "42"
    status: "active"
This matches <div data-row-id="42" data-status="active">.

​
Best practices

  1. Prefer stable identifiers — id, dataTestId, and ariaLabel survive UI redesigns better than CSS selectors or XPath.
  2. Avoid rect — Position selectors break on any layout change. Only use them when no semantic selector exists.
  3. Keep innerText short — Long text matches are brittle. The field is capped at 200 characters.
  4. Enable selector cache — For repeated executions, --enable-selector-cache persists successful resolutions across runs.