Every Locator method takes a locator: a selector object tagged by kind. On a browser, matching uses Playwright’s own selector engine, run in the page, so selectors match as page.locator() and the getBy methods do in Playwright. On a phone, a selector resolves against the accessibility tree, the screen’s text (OCR), or a vision model, depending on its kind and the strategy. On a computer, a call that names no targetId resolves against the desktop’s UI Automation tree (native apps); one that names a page’s goes to the browser.
{ "kind": "role", "role": "button", "name": "Sign in" }

Kinds

KindFieldsExampleBrowserPhoneComputer
cssselector{ "kind": "css", "selector": "#login" }Yes
xpathselector{ "kind": "xpath", "selector": "//form//button" }Yes
playwrightselector{ "kind": "playwright", "selector": "li:has-text('Pro') >> nth=0" }Yes
refref{ "kind": "ref", "ref": "e5" }YesYes
rolerole, name, exact, states{ "kind": "role", "role": "checkbox", "name": "Remember me" }YesNeeds the treeYes
textvalue, exact{ "kind": "text", "value": "Sign in" }YesYesYes
labelvalue, exact{ "kind": "label", "value": "Email" }YesYes
placeholdervalue, exact{ "kind": "placeholder", "value": "Search" }Yes
altTextvalue, exact{ "kind": "altText", "value": "Company logo" }YesYes
titlevalue, exact{ "kind": "title", "value": "Close" }YesYes
testIdvalue{ "kind": "testId", "value": "submit" }YesYes
queryquery{ "kind": "query", "query": "the search icon" }Yes
axNodenodeId{ "kind": "axNode", "nodeId": "<from a tree read>" }Needs the treeYes
andselectors{ "kind": "and", "selectors": [ {...}, {...} ] }YesYesYes
orselectors{ "kind": "or", "selectors": [ {...}, {...} ] }YesYes
domNodenodeId
A kind a session doesn’t serve answers StrategyUnavailable, never an approximate match. Text kinds match a case-insensitive substring unless exact is true. testId matches data-testid. playwright takes a Playwright selector string verbatim: CSS, text=, xpath=, >> chains, :has-text(), :visible, nth=. ref acts on an element by the ref a snapshot gave it. Call Page.ariaSnapshot with refs: true and every element a pointer can reach comes tagged [ref=eN], as in Playwright’s snapshot for AI:
- textbox "Username" [ref=e7]
- button "Log in" [ref=e9] [cursor=pointer]
Then { "kind": "ref", "ref": "e9" } clicks the button. A ref keeps naming its element across snapshots, and across actions, for as long as the element stays on the page. Once it leaves (a navigation, a re-render), the ref fails at once with StaleNode: take a new snapshot. Refs cover the main frame. On a phone, query is natural language for a vision model, and the only kind that ever becomes a model prompt. role and states are platform-scoped: bare ("button") or qualified ("android.button"). axNode pins one node from an earlier accessibility read and fails with StaleNode once that node is gone. On a computer, role takes UI Automation’s control types (button, edit, checkbox, combobox, menuitem, listitem, window…), bare or as "windows.button"; textbox, link and radio work too. testId matches the automation id, title the help text, text the name or a field’s value, and ref and axNode a node id from Accessibility.getFullAXTree. Scope a search to one window with within: { "kind": "role", "role": "button", "name": "Seven", "within": { "kind": "role", "role": "window", "name": "Calculator" } }. Actions bring the window to the front and use the OS mouse and keyboard.

Refining

Any selector can carry:
FieldMeaning
withinSearch inside the element another selector finds.
hasKeep matches containing an element another selector finds.
nthPick one match: zero-based, or -1 for the last.
{
  "kind": "role", "role": "button", "name": "Delete",
  "within": { "kind": "css", "selector": "tr", "has": { "kind": "text", "value": "invoice-42" } }
}
Selectors nest at most 4 levels.

Strictness

Actions and single-element reads must resolve to exactly one target. A selector that matches several fails with ActionTimeout, and the message says how many matched: at once on a browser, and on a phone once the screen has settled. Pick one with nth (in reading order) or narrow the selector. Locator.count counts every match and never waits.

Strategies

strategy picks the resolver. A pinned resolver that can’t serve the selector answers StrategyUnavailable; it never falls back to another.
StrategyResolves withBrowserPhone
autoThe default. On a browser, dom. On a phone, the accessibility tree when it has one, vision otherwise.YesYes
domThe page’s own selector engines.Yes
accessibilityThe accessibility tree only.Needs the tree
visionThe screen only: OCR for text, a vision model for query.Yes
Every Locator result says which resolver found the target in resolvedBy: dom, a11y (the tree), ocr or vlm (a vision model, named in modelName). On a phone, ocrEngine picks the OCR tier (free or premium) and model pins the model; browsers ignore both. Phones don’t serve force. See Selector for the full schema.