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.
Kinds
| Kind | Fields | Example | Browser | Phone | Computer |
|---|---|---|---|---|---|
css | selector | { "kind": "css", "selector": "#login" } | Yes | ||
xpath | selector | { "kind": "xpath", "selector": "//form//button" } | Yes | ||
playwright | selector | { "kind": "playwright", "selector": "li:has-text('Pro') >> nth=0" } | Yes | ||
ref | ref | { "kind": "ref", "ref": "e5" } | Yes | Yes | |
role | role, name, exact, states | { "kind": "role", "role": "checkbox", "name": "Remember me" } | Yes | Needs the tree | Yes |
text | value, exact | { "kind": "text", "value": "Sign in" } | Yes | Yes | Yes |
label | value, exact | { "kind": "label", "value": "Email" } | Yes | Yes | |
placeholder | value, exact | { "kind": "placeholder", "value": "Search" } | Yes | ||
altText | value, exact | { "kind": "altText", "value": "Company logo" } | Yes | Yes | |
title | value, exact | { "kind": "title", "value": "Close" } | Yes | Yes | |
testId | value | { "kind": "testId", "value": "submit" } | Yes | Yes | |
query | query | { "kind": "query", "query": "the search icon" } | Yes | ||
axNode | nodeId | { "kind": "axNode", "nodeId": "<from a tree read>" } | Needs the tree | Yes | |
and | selectors | { "kind": "and", "selectors": [ {...}, {...} ] } | Yes | Yes | Yes |
or | selectors | { "kind": "or", "selectors": [ {...}, {...} ] } | Yes | Yes | |
domNode | nodeId |
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:
{ "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:| Field | Meaning |
|---|---|
within | Search inside the element another selector finds. |
has | Keep matches containing an element another selector finds. |
nth | Pick one match: zero-based, or -1 for the last. |
Strictness
Actions and single-element reads must resolve to exactly one target. A selector that matches several fails withActionTimeout, 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.
| Strategy | Resolves with | Browser | Phone |
|---|---|---|---|
auto | The default. On a browser, dom. On a phone, the accessibility tree when it has one, vision otherwise. | Yes | Yes |
dom | The page’s own selector engines. | Yes | |
accessibility | The accessibility tree only. | Needs the tree | |
vision | The screen only: OCR for text, a vision model for query. | Yes |
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.