Skip to main content

Function: resolveLocator()

function resolveLocator(frame, selectorString): Locator;

Defined in: packages/uimatch-core/src/adapters/playwright/locator-resolver.ts:50

Resolves a selector string with optional prefix to a Playwright Locator.

Supported prefixes:

  • role:button[name="View docs"] → getByRole('button', { name: 'View docs' })
  • role:button[name=/docs/i][exact] → getByRole with regex name and exact option
  • role:heading[level=1] → getByRole('heading', { level: 1 })
  • role:button[pressed=true|selected=true|checked=true] → Boolean state options
  • testid:accordion-item → getByTestId('accordion-item')
  • text:"Continue" or text:'Continue' → getByText('Continue', { exact: true })
  • text:"Continue"[exact] or text:/Continue/i[exact] → Explicit exact match
  • text:/Continue/i → getByText(/Continue/i)
  • xpath://div[@class="header"] → locator('xpath=//div[@class="header"]')
  • css:.bg-white → locator('.bg-white')
  • dompath:__self__ > :nth-child(2) → locator for child element (use after initial capture)
  • No prefix → assumes CSS selector (backward compatible)
  • CSS pseudo-classes (:root, :has(), etc.) → treated as CSS selectors

Unknown prefixes:

  • With UIMATCH_SELECTOR_STRICT=true → throws error (strict mode for CI)
  • Otherwise → fallback to CSS selector (lenient mode for interactive use)

Parameters​

frame​

Frame

Target frame

selectorString​

string

Selector with optional prefix

Returns​

Locator

Playwright Locator

Throws​

Error when prefix is unknown and UIMATCH_SELECTOR_STRICT=true