Selectors are the backbone of every RTILA X project. They tell the browser engine exactly which element to read or interact with. RTILA X uses a consistent type=value format so you always know what kind of selector you are writing.

CSS Selectors

The most common selector type and the default choice for stable demo markup:

css=div.product-card
css=#search-input
css=.product-title

CSS selectors are concise, readable, and work extremely well with deterministic HTML. Use IDs for unique elements and semantic class names for repeating containers. Avoid brittle selectors such as very long generated class chains or nth-child fragments unless no better option exists.

XPath Selectors

XPath is useful when you need positional or text-aware selection:

xpath=//h1
xpath=//div[contains(@class, 'product')]
xpath=//button[text()='Add to Cart']

XPath is more powerful but also slower and more fragile than CSS. Use it only when CSS cannot express the relationship you need, such as selecting an element by its text content or navigating complex table structures.

Text Selectors

Text selectors locate visible text directly:

text=Click Me
text=Read More

They are most useful for clicking links or buttons where the accessible name is more stable than the markup. Keep text selectors short and exact. They match visible text by default, not hidden text.

Variable Selectors

Variable selectors reference content that was already extracted earlier in the same run:

variable=product_url
variable=first_name

This allows multi-step automation to reuse extracted values as navigation targets or form input without hardcoding them.

Fallback Chains

RTILA X supports fallback selector chains by specifying multiple selectors in a single comma-separated selector string. The engine splits the string on commas and tries each selector in order using Playwright’s locator.or() method. There is no fallback_selectors parameter.

Example project JSON setting:

{
  "command": "click",
  "params": {
    "selector": "css=#login-btn,css=.login-button,text=Sign In"
  }
}

Fallback chains are useful for login forms, cookie banners, and A/B test pages where the same user action may appear under different markup.

Shadow DOM Piercing

Shadow DOM hides elements from normal CSS selectors. RTILA X can pierce shadow boundaries when you supply a chain that reaches through the shadow root. The exact syntax depends on the command, but the key principle is to identify the shadow host first and then traverse the shadow tree with additional selectors.

The Shadow DOM scenario on the learning site demonstrates a counter inside an open shadow root. Practice by extracting the visible value using a shadow-aware selector.

Iframe Selectors

Iframe content lives in a separate document. Before extracting from an iframe, use a frame-aware selector or switch context to the iframe element. A stable approach is to locate the iframe with css=iframe[id='demo-frame'] and then target the contents within that frame using a command that supports frame context.

Selector Strategy Best Practices

• Prefer id and data-* attributes over generated class names.
• Use semantic class names such as .product-card rather than framework-generated hashes.
• Start with CSS, escalate to XPath only when necessary.
• Use text selectors for actions based on accessible names.
• Add wait_for_selector before clicking, filling, or extracting.
• Test every selector against the LIVE DEMO HTML on the scenario page.
• Keep selector chains short and descriptive.

Try It Yourself

Visit the Basic Navigation scenarios numbered 6, 12, 13, and 14. Each one exercises a different selector strategy: CSS extraction, fallback chains, Shadow DOM, and iframe handling. Compare your output with the expected output section.