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

​
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

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.
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:
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.