Skip to main content

Atomic Step with relativeTo Option

The relativeTo option allows you to ground an element relative to a stable reference element on the page.

How It Works​

  • The grounding agent grounds both the target element and the reference element (specified in relativeTo)
  • The resulting locator structure is: <reference_element_locator>.locator('xpath=<relative_xpath_from_reference_to_target>')
  • The target description is independent from relativeTo — if you want the agent to know the target is near the reference, mention it explicitly in the target description

When to Use​

Use relativeTo when:

  • A step is not stable (grounding agent sometimes works, sometimes fails)
  • You can identify a stable, easy-to-locate reference element nearby

Example​

await Heal.leftClick(
  'the submit icon under the Example Domain header',
  { relativeTo: 'the Example Domain header' }
);

This generates a locator like:

getByRole('heading', { name: 'Example Domain' }).locator('xpath=../p[2]/a')

Another Example​

await Heal.fill(
  'the quantity input next to the Add to Cart button',
  '5',
  { relativeTo: 'the Add to Cart button' }
);