Locator methods, browser sessions serve 22, phone sessions 7 and computer sessions 23. A method marked not served answers StrategyUnavailable on that kind of session; check the handshake’s capabilities before relying on one.
Locator.fill
Browser: served
Phone: served
Computer: served
Takes targetId
Resolve the locator on the current screen, wait until the target is attached, visible, enabled and editable (terms as Locator.click defines them), focus it, then type text into it, all on the session in one round trip. Fails with ActionTimeout when the target never becomes actionable within timeoutMs. When it reads the screen (strategy vision, or no accessibility tree), it also fails with ActionTimeout when the locator matches several elements on a settled screen; the message lists them, and nth picks one.
| Param | Type | Required | Description |
|---|---|---|---|
observe | string | No | Return the page’s state after the action in the same reply: url (its URL and title) or snapshot (those and the first part of Page.ariaSnapshot with refs and compact). It waits up to 5 seconds for a navigation the action started. One of url, snapshot. |
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
force | boolean | No | Skip the actionability checks (Playwright’s force). |
text | string | Yes | |
input | string | No | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.press
Browser: served
Phone: served
Computer: served
Takes targetId
Press a key, as Keyboard.keyPress does. With a locator, the target is resolved, waited for and focused first, and fails as Locator.fill does on several matches; without one, the key goes to whatever has focus.
| Param | Type | Required | Description |
|---|---|---|---|
observe | string | No | Return the page’s state after the action in the same reply: url (its URL and title) or snapshot (those and the first part of Page.ariaSnapshot with refs and compact). It waits up to 5 seconds for a navigation the action started. One of url, snapshot. |
locator | Selector | No | Which element: a selector object tagged by kind. See Selectors. |
key | string | Yes | A named key, or a single printable character. Playwright’s spellings of named keys (“Enter”, “ArrowDown”, “PageUp”) are accepted too. |
modifiers | string[] | No | Modifier keys to hold. A session that cannot hold modifiers answers StrategyUnavailable. One of ctrl, shift, alt, meta. |
input | string | No | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.click
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve the locator, wait until the target is attached, visible, stable, enabled and receives events, then click it. Fails as Locator.fill does on timeout or several matches. Actionability terms: attached (in the document), visible (rendered with a non-empty box), stable (not moving between two frames), enabled (not disabled), editable (not read-only), receives events (not covered by another element at the point the action lands).
| Param | Type | Required | Description |
|---|---|---|---|
observe | string | No | Return the page’s state after the action in the same reply: url (its URL and title) or snapshot (those and the first part of Page.ariaSnapshot with refs and compact). It waits up to 5 seconds for a navigation the action started. One of url, snapshot. |
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
force | boolean | No | Skip the actionability checks (Playwright’s force). |
trial | boolean | No | Run the actionability checks without acting (Playwright’s trial). |
position | ElementPosition | No | Where on the target to act, in CSS pixels from its padding box’s top-left, as Playwright’s position. Omitted means the center. |
button | string | No | The mouse button to use. One of left, right, middle. Default "left". |
clickCount | integer | No | Clicks in quick succession; 2 is a double click. Omitted means 1. Default 1. |
modifiers | string[] | No | Modifier keys to hold. A session that cannot hold modifiers answers StrategyUnavailable. One of ctrl, shift, alt, meta. |
input | string | No | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.hover
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve the locator, wait until the target is attached, visible, stable and receives events (terms as Locator.click defines them), then move the pointer over it.
| Param | Type | Required | Description |
|---|---|---|---|
observe | string | No | Return the page’s state after the action in the same reply: url (its URL and title) or snapshot (those and the first part of Page.ariaSnapshot with refs and compact). It waits up to 5 seconds for a navigation the action started. One of url, snapshot. |
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
force | boolean | No | Skip the actionability checks (Playwright’s force). |
trial | boolean | No | Run the actionability checks without acting (Playwright’s trial). |
position | ElementPosition | No | Where on the target to act, in CSS pixels from its padding box’s top-left, as Playwright’s position. Omitted means the center. |
input | string | No | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.selectOption
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve a select element, wait until it is attached, visible and enabled (terms as Locator.click defines them), then choose the options matching values or labels (one of the two). Choosing several needs a multiple select. Works on select elements only: any other target, such as a custom dropdown, fails with InvalidArgs (use Locator.click).
| Param | Type | Required | Description |
|---|---|---|---|
observe | string | No | Return the page’s state after the action in the same reply: url (its URL and title) or snapshot (those and the first part of Page.ariaSnapshot with refs and compact). It waits up to 5 seconds for a navigation the action started. One of url, snapshot. |
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
force | boolean | No | Skip the actionability checks (Playwright’s force). |
values | string[] | No | Option values to choose. |
labels | string[] | No | Option labels (visible text) to choose. |
input | string | No | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.setChecked
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve a checkbox or radio button, wait as Locator.click does, and make its checked state match checked, clicking it only when it does not already.
| Param | Type | Required | Description |
|---|---|---|---|
observe | string | No | Return the page’s state after the action in the same reply: url (its URL and title) or snapshot (those and the first part of Page.ariaSnapshot with refs and compact). It waits up to 5 seconds for a navigation the action started. One of url, snapshot. |
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
force | boolean | No | Skip the actionability checks (Playwright’s force). |
trial | boolean | No | Run the actionability checks without acting (Playwright’s trial). |
checked | boolean | Yes | |
input | string | No | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.scrollIntoView
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve the locator, wait until the target is attached and stable (terms as Locator.click defines them), then scroll until it is in view.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.setInputFiles
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve a file input, wait only until it is attached (file inputs are often hidden), and set its files, replacing any already chosen: uploads names files staged with Browser.stageUpload; fileIds names Files library files (not served yet). An empty list clears it.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
uploads | string[] | No | Names of files staged with Browser.stageUpload. |
fileIds | string[] | No | IDs of files in the organization’s Files library. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.waitFor
Browser: served
Phone: served
Computer: served
Takes targetId
Block on the session until the locator reaches the requested state (visible by default), re-resolving against each fresh frame. One call replaces a client-side polling loop.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
state | string | No | The state to wait for; visible by default. attached and detached wait for the target to be in or out of the document, visible or not. enabled needs the accessibility tree or the DOM (vision cannot tell). One of visible, hidden, enabled, attached, detached. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.boundingBox
Browser: served
Phone: served
Computer: served
Takes targetId
Wait until the locator resolves, then return the target’s bounds: window pixels, or the page’s CSS pixels with space viewport (as Playwright’s boundingBox).
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
space | string | No | The space a call’s coordinates and returned bounds are in. screen is the desktop’s pixels from its top-left: the only space in a computer session, and its default there. In a browser session window (the default) is window pixels. viewport is the page’s CSS pixels from the main frame viewport’s top-left, as Playwright’s page.mouse and boundingBox use; under it a point outside the viewport fails with InvalidArgs. One of window, viewport, screen. Default "window". |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.getAttribute
Browser: served
Phone: not served
Computer: served
Takes targetId
Wait until the locator resolves, then return the named DOM attribute (null when absent).
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
name | string | No | The attribute getAttribute reads; ignored by the other reads. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
value | string | null | What the method reads; null when the target has none (an absent attribute). |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.textContent
Browser: served
Phone: not served
Computer: served
Takes targetId
Wait until the locator resolves, then return its DOM text content, including text that is not rendered.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
name | string | No | The attribute getAttribute reads; ignored by the other reads. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
value | string | null | What the method reads; null when the target has none (an absent attribute). |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.innerText
Browser: served
Phone: not served
Computer: served
Takes targetId
Wait until the locator resolves, then return its rendered text, as the browser computes innerText.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
name | string | No | The attribute getAttribute reads; ignored by the other reads. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
value | string | null | What the method reads; null when the target has none (an absent attribute). |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.inputValue
Browser: served
Phone: not served
Computer: served
Takes targetId
Wait until the locator resolves, then return a form control’s current value, which can differ from its value attribute.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
name | string | No | The attribute getAttribute reads; ignored by the other reads. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
value | string | null | What the method reads; null when the target has none (an absent attribute). |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.accessibleName
Browser: not served
Phone: served
Computer: served
Takes targetId
Wait until the locator resolves through the accessibility tree, then return its computed accessible name.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
name | string | No | The attribute getAttribute reads; ignored by the other reads. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
value | string | null | What the method reads; null when the target has none (an absent attribute). |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.count
Browser: served
Phone: served
Computer: served
Takes targetId
Count the targets matching the locator on the current screen, zero included. Never waits.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
count | integer | |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.evaluate
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve the locator, wait until the target is attached, then call expression with the element and args in world, as Page.evaluate. Results, limits, timeouts and idempotencyKey are as Page.evaluate; it also reports how the element was found.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
expression | string | Yes | Called with the element first, then args. |
args | any[] | No | JSON values passed to the expression, in order. |
all | boolean | No | Call expression once with an array of every match (empty when none) instead of the one element, without waiting, as Playwright’s evaluateAll. |
world | string | No | Where a script runs. isolated shares the page’s DOM but not its JavaScript, and the page can’t see it. main is the page’s own context: it can read the page’s variables and call its functions, and the page can observe the script, so use it only when a call needs page JavaScript. One of isolated, main. Default "isolated". |
awaitPromise | boolean | No | Default true. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
value | any | The JSON result; null is a value. |
exception | ScriptException | |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.dispatchEvent
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve the locator, wait until the target is attached, then dispatch an event of type on it with eventInit. A programmatic event, not input: it skips the page’s real input handling, so use Locator.click for a click.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
type | string | Yes | The event type, e.g. “click” or “input”. |
eventInit | object | No | The event’s init dictionary. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.innerHTML
Browser: served
Phone: not served
Computer: served
Takes targetId
Wait until the locator resolves, then return the target’s inner HTML.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
name | string | No | The attribute getAttribute reads; ignored by the other reads. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
value | string | null | What the method reads; null when the target has none (an absent attribute). |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
Locator.getStates
Browser: served
Phone: not served
Computer: served
Takes targetId
The target’s states, as Playwright’s isVisible, isEnabled, isEditable, isChecked and isFocused read them. Waits until the target is attached, unless noWait, which answers at once with attached false when nothing matches. Strict like the actions, noWait included: several matches fail as Locator.fill does unless nth picks one. checked is null for a target that can’t be checked. isHidden is not visible, and a target that isn’t attached counts as hidden.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
noWait | boolean | No | |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
attached | boolean | |
visible | boolean | |
enabled | boolean | |
editable | boolean | |
checked | boolean | null | |
focused | boolean | |
tookMs | integer |
Locator.focus
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve the locator, wait until attached, then focus the target as script does.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.blur
Browser: served
Phone: not served
Computer: served
Takes targetId
Resolve the locator, wait until attached, then remove focus from the target.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.dragTo
Browser: served
Phone: not served
Computer: served
Takes targetId
Press on the source, move to the target, and release, each waited for as Locator.click waits. Positions are as Locator.click’s position. The pointer moves through intermediate points under either input, so pages that drag on pointer events work as well as HTML5 drag and drop.
| Param | Type | Required | Description |
|---|---|---|---|
observe | string | No | Return the page’s state after the action in the same reply: url (its URL and title) or snapshot (those and the first part of Page.ariaSnapshot with refs and compact). It waits up to 5 seconds for a navigation the action started. One of url, snapshot. |
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
force | boolean | No | Skip the actionability checks (Playwright’s force). |
trial | boolean | No | Run the actionability checks without acting (Playwright’s trial). |
target | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
sourcePosition | ElementPosition | No | Where on the target to act, in CSS pixels from its padding box’s top-left, as Playwright’s position. Omitted means the center. |
targetPosition | ElementPosition | No | Where on the target to act, in CSS pixels from its padding box’s top-left, as Playwright’s position. Omitted means the center. |
input | string | No | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |
Locator.tap
Browser: not served
Phone: served
Computer: not served
The phone’s pointer action: resolve the locator, wait until the target is actionable, then tap its centre. Fails with ActionTimeout when the target never becomes actionable within timeoutMs. Browsers answer Locator.click instead.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | Yes | Which element: a selector object tagged by kind. See Selectors. |
strategy | string | No | Which resolver finds the target: auto, dom, vision or accessibility. Browsers serve dom (and auto, which means dom); phones serve auto, vision and accessibility. See Strategies. |
timeoutMs | integer | No | Budget for the whole call in milliseconds, auto-wait included. 0 or omitted means 5000; at most 60000. Running out is ActionTimeout. |
ocrEngine | string | No | Phones only: the OCR tier for the vision resolver, free or premium. Omitted means the default. |
model | string | No | Phones only: the model the vision resolver and natural-language queries use. Omitted means the default. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
| Field | Type | Description |
|---|---|---|
navigated | boolean | A navigation the action started committed before it returned (click and press wait up to 10 s for one that starts within 150 ms, as Playwright does). |
observed | Observation | The page right after the action, for a call with observe. |
resolvedBy | string | How the target was resolved: dom (the page’s DOM), a11y (an accessibility tree), ocr (text read from a screenshot), vlm (a point a vision model grounded on a screenshot), or model (a model picked one element from the page’s or desktop’s candidates, for kind query). One of dom, a11y, ocr, vlm, model. |
bounds | Bbox | |
tookMs | integer | End-to-end time on the session, auto-wait included. |
modelName | string | The model that resolved the target when resolvedBy is vlm. |
input | string | How the input reaches the page. Browsers serve os (the default), real operating system input; simulated answers StrategyUnavailable. |