Page methods, browser sessions serve 17, phone sessions 0 and computer sessions 17. A method marked not served answers StrategyUnavailable on that kind of session; check the handshake’s capabilities before relying on one.
Page.navigate
Browser: served
Phone: not served
Computer: served
Takes targetId
Go to url and return once the new document reaches waitUntil (load by default). status is the HTTP status when the page exposes it. navigationId names the new document; it is null for a same-document navigation (a fragment or history.pushState change). A URL that becomes a download returns navigated false with a null navigationId. A response with a body is a loaded page, error status included (status 404); a failure Chrome reports, including an HTTP error with an empty body (net::ERR_HTTP_RESPONSE_CODE_FAILURE), fails with NavigationFailed. url must use a scheme in x-dcp-navigation-schemes, or be exactly about:blank; any other (chrome:, file:, devtools:, view-source:, javascript: and the rest) fails with InvalidArgs naming the scheme.
| 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. |
url | string | Yes | |
waitUntil | string | No | A document’s load state: domContentLoaded (the HTML is parsed), load (the load event fired), networkIdle (no network activity for 500 ms after load), settled (domContentLoaded, then load for at most 5 s, then the DOM unchanged for 300 ms, as Page.waitForSettled; use it before reading a page, including single-page apps and pages whose ads keep load from firing). A page that never stops changing counts as settled at the cap instead of failing. Page.getInfo never reports settled. One of load, domContentLoaded, networkIdle, settled. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
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 |
|---|---|---|
observed | Observation | The page right after the action, for a call with observe. It is read once the DOM has gone 300 ms unchanged, or after 1.5 s at most. |
url | string | The URL after redirects. |
status | integer | The HTTP status, when the page exposes it. |
navigationId | string | null | The new document’s NavigationId; null for a same-document navigation, a download, or no navigation. |
navigated | boolean | False when nothing navigated (no history entry, or the URL became a download). |
settled | boolean | For waitUntil settled: false when the page was still changing when the 5 s cap ran out. Absent for other load states. |
Page.reload
Browser: served
Phone: not served
Computer: served
Takes targetId
Reload the current document; results and failures as Page.navigate.
| 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. |
waitUntil | string | No | A document’s load state: domContentLoaded (the HTML is parsed), load (the load event fired), networkIdle (no network activity for 500 ms after load), settled (domContentLoaded, then load for at most 5 s, then the DOM unchanged for 300 ms, as Page.waitForSettled; use it before reading a page, including single-page apps and pages whose ads keep load from firing). A page that never stops changing counts as settled at the cap instead of failing. Page.getInfo never reports settled. One of load, domContentLoaded, networkIdle, settled. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
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 |
|---|---|---|
observed | Observation | The page right after the action, for a call with observe. It is read once the DOM has gone 300 ms unchanged, or after 1.5 s at most. |
url | string | The URL after redirects. |
status | integer | The HTTP status, when the page exposes it. |
navigationId | string | null | The new document’s NavigationId; null for a same-document navigation, a download, or no navigation. |
navigated | boolean | False when nothing navigated (no history entry, or the URL became a download). |
settled | boolean | For waitUntil settled: false when the page was still changing when the 5 s cap ran out. Absent for other load states. |
Page.goBack
Browser: served
Phone: not served
Computer: served
Takes targetId
Go back one history entry. With no entry to go back to, returns navigated false; it is not an error.
| 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. |
waitUntil | string | No | A document’s load state: domContentLoaded (the HTML is parsed), load (the load event fired), networkIdle (no network activity for 500 ms after load), settled (domContentLoaded, then load for at most 5 s, then the DOM unchanged for 300 ms, as Page.waitForSettled; use it before reading a page, including single-page apps and pages whose ads keep load from firing). A page that never stops changing counts as settled at the cap instead of failing. Page.getInfo never reports settled. One of load, domContentLoaded, networkIdle, settled. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
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 |
|---|---|---|
observed | Observation | The page right after the action, for a call with observe. It is read once the DOM has gone 300 ms unchanged, or after 1.5 s at most. |
url | string | The URL after redirects. |
status | integer | The HTTP status, when the page exposes it. |
navigationId | string | null | The new document’s NavigationId; null for a same-document navigation, a download, or no navigation. |
navigated | boolean | False when nothing navigated (no history entry, or the URL became a download). |
settled | boolean | For waitUntil settled: false when the page was still changing when the 5 s cap ran out. Absent for other load states. |
Page.goForward
Browser: served
Phone: not served
Computer: served
Takes targetId
Go forward one history entry. With no entry to go forward to, returns navigated false; it is not an error.
| 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. |
waitUntil | string | No | A document’s load state: domContentLoaded (the HTML is parsed), load (the load event fired), networkIdle (no network activity for 500 ms after load), settled (domContentLoaded, then load for at most 5 s, then the DOM unchanged for 300 ms, as Page.waitForSettled; use it before reading a page, including single-page apps and pages whose ads keep load from firing). A page that never stops changing counts as settled at the cap instead of failing. Page.getInfo never reports settled. One of load, domContentLoaded, networkIdle, settled. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
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 |
|---|---|---|
observed | Observation | The page right after the action, for a call with observe. It is read once the DOM has gone 300 ms unchanged, or after 1.5 s at most. |
url | string | The URL after redirects. |
status | integer | The HTTP status, when the page exposes it. |
navigationId | string | null | The new document’s NavigationId; null for a same-document navigation, a download, or no navigation. |
navigated | boolean | False when nothing navigated (no history entry, or the URL became a download). |
settled | boolean | For waitUntil settled: false when the page was still changing when the 5 s cap ran out. Absent for other load states. |
Page.waitForLoad
Browser: served
Phone: not served
Computer: served
Takes targetId
Wait until a document reaches state (load by default): the document navigationId names, or the current one. A document that already reached the state answers at once, networkIdle included. Fails with NavigationFailed (reason “superseded”) when a later navigation replaces the one waited for, and ActionTimeout when timeoutMs runs out. Navigation an action starts is not waited for unless this is called.
| Param | Type | Required | Description |
|---|---|---|---|
state | string | No | A document’s load state: domContentLoaded (the HTML is parsed), load (the load event fired), networkIdle (no network activity for 500 ms after load), settled (domContentLoaded, then load for at most 5 s, then the DOM unchanged for 300 ms, as Page.waitForSettled; use it before reading a page, including single-page apps and pages whose ads keep load from firing). A page that never stops changing counts as settled at the cap instead of failing. Page.getInfo never reports settled. One of load, domContentLoaded, networkIdle, settled. |
navigationId | string | No | The document to wait for. Omitted means the current document. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
| Field | Type | Description |
|---|---|---|
url | string | |
state | string | A document’s load state: domContentLoaded (the HTML is parsed), load (the load event fired), networkIdle (no network activity for 500 ms after load), settled (domContentLoaded, then load for at most 5 s, then the DOM unchanged for 300 ms, as Page.waitForSettled; use it before reading a page, including single-page apps and pages whose ads keep load from firing). A page that never stops changing counts as settled at the cap instead of failing. Page.getInfo never reports settled. One of load, domContentLoaded, networkIdle, settled. |
navigationId | string | null | The document that reached the state. |
Page.waitForSettled
Browser: served
Phone: not served
Computer: served
Takes targetId
Wait until the page has gone quietMs without a change a reader would see (a node added or removed, text edited, or an element shown, hidden, opened or a control’s state changed; style and class churn from animations doesn’t count), which is when a single-page app has finished rendering what it loaded. A page that keeps changing (a ticker, a carousel) answers settled false when timeoutMs runs out; that is not an error. A navigation mid-wait starts the wait again in the new document within the same budget.
| Param | Type | Required | Description |
|---|---|---|---|
quietMs | integer | No | How long the DOM must go unchanged. Omitted or 0 means 300. From 0 to 10000. Default 300. |
timeoutMs | integer | No | Budget in milliseconds. Omitted or 0 means 5000. On expiry the call answers settled false. From 0 to 120000. Default 5000. |
| Field | Type | Description |
|---|---|---|
settled | boolean | False when the DOM was still changing when timeoutMs ran out. |
elapsedMs | integer | How long the wait took. |
Page.getInfo
Browser: served
Phone: not served
Computer: served
Takes targetId
The tab’s URL, title, furthest load state and current document.
| Field | Type | Description |
|---|---|---|
targetId | string | Opaque tab id, stable while the tab is open. Never parse it. |
url | string | |
title | string | |
loadState | string | The furthest state the current document has reached; absent before it starts loading. One of load, domContentLoaded, networkIdle, settled. |
navigationId | string | null | The current document’s NavigationId. |
Page.evaluate
Browser: served
Phone: not served
Computer: served
Takes targetId
Run expression (a function body or an arrow function, called with args) in world: isolated by default, sharing the page’s DOM but not its JavaScript variables, where the page can’t see it; or main, the page’s own context, which can read the page’s JavaScript and which the page can observe. Returns value, the JSON result, or exception when the script threw or returned something JSON can’t carry (a DOM node, a function, a cycle, a BigInt: “result is not serializable”). A script’s own error is a result, not a DCP error. A result over 1 MiB fails with InvalidArgs naming the limit. Running past timeoutMs fails with ActionTimeout, but a promise the script started keeps running in the page; there is no cancellation. Clients don’t re-send it on their own; pass idempotencyKey when a re-send after a reconnect must not run it twice. A script that navigates returns before the new page loads; call Page.waitForLoad.
| Param | Type | Required | Description |
|---|---|---|---|
expression | string | Yes | |
args | any[] | No | JSON values passed to the expression, in order. |
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. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
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 |
Page.addInitScript
Browser: not served
Phone: not served
Computer: not served
Takes targetId
Run source in world (isolated by default, or main) in every new document of this tab, before the page’s own scripts, until removed.
| Param | Type | Required | Description |
|---|---|---|---|
source | string | Yes | |
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". |
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 |
|---|---|---|
scriptId | string |
Page.removeInitScript
Browser: not served
Phone: not served
Computer: not served
Takes targetId
Stop running an init script.
| Param | Type | Required | Description |
|---|---|---|---|
scriptId | string | Yes | |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
{}.
Page.setContent
Browser: served
Phone: not served
Computer: served
Takes targetId
Replace the tab’s document with html and return once it reaches waitUntil (load by default). Every node id from the old document is stale.
| Param | Type | Required | Description |
|---|---|---|---|
html | string | Yes | |
waitUntil | string | No | A document’s load state: domContentLoaded (the HTML is parsed), load (the load event fired), networkIdle (no network activity for 500 ms after load), settled (domContentLoaded, then load for at most 5 s, then the DOM unchanged for 300 ms, as Page.waitForSettled; use it before reading a page, including single-page apps and pages whose ads keep load from firing). A page that never stops changing counts as settled at the cap instead of failing. Page.getInfo never reports settled. One of load, domContentLoaded, networkIdle, settled. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
{}.
Page.setDialogPolicy
Browser: served
Phone: not served
Computer: served
Takes targetId
How this tab answers alert, confirm, prompt and beforeunload dialogs: dismiss, accept (with promptText for prompts) or hold (leave it open for Page.handleDialog). type limits the policy to one dialog type. The defaults are dismiss for alert, confirm and prompt, and accept for beforeunload, so leaving a page never stalls. While a held dialog is open, an action on the page fails at once with DialogOpen.
| Param | Type | Required | Description |
|---|---|---|---|
action | string | Yes | One of dismiss, accept, hold. |
type | string | No | One of alert, confirm, prompt, beforeunload. |
promptText | string | No | The text an accepted prompt answers with. |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
{}.
Page.waitForDialog
Browser: served
Phone: not served
Computer: served
Takes targetId
The open dialog, or the next one. With afterSeq, only dialogs opened after it count; without, an open dialog answers at once. Dialogs the policy answered are returned too, with their state. Fails with EventsExpired or ActionTimeout as Target.waitForTarget does.
| Param | Type | Required | Description |
|---|---|---|---|
afterSeq | integer | No | Only events after this event-log position count (a response’s seq). The log keeps each category for its own window (events: 1000 entries or 5 minutes; network records: 5000 entries or 2 minutes). One older than the window of the category the wait reads fails with EventsExpired; re-read state instead. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
| Field | Type | Description |
|---|---|---|
dialogId | string | Opaque; pass it to Page.handleDialog. |
type | string | One of alert, confirm, prompt, beforeunload. |
message | string | |
defaultPrompt | string | |
url | string | The page that opened it. |
state | string | One of open, accepted, dismissed. |
Page.handleDialog
Browser: served
Phone: not served
Computer: served
Takes targetId
Accept or dismiss an open dialog, with promptText for a prompt. dialogId is required; an unknown or already answered dialog fails with InvalidArgs.
| Param | Type | Required | Description |
|---|---|---|---|
dialogId | string | Yes | |
accept | boolean | Yes | |
promptText | string | No | |
idempotencyKey | string | No | Makes a re-send after a reconnect safe: a repeated key returns the recorded response without acting again. See Idempotency keys. |
{}.
Page.waitForDownload
Browser: served
Phone: not served
Computer: served
Takes targetId
The next download this tab started, once it has finished: saved in the guest’s Downloads folder (filename; read the bytes with Browser.readDownload) or failed (failureReason). With afterSeq, only downloads started after it count; without, only ones started after this call. There is no save dialog.
| Param | Type | Required | Description |
|---|---|---|---|
afterSeq | integer | No | Only events after this event-log position count (a response’s seq). The log keeps each category for its own window (events: 1000 entries or 5 minutes; network records: 5000 entries or 2 minutes). One older than the window of the category the wait reads fails with EventsExpired; re-read state instead. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
| Field | Type | Description |
|---|---|---|
downloadId | string | |
url | string | |
filename | string | The name it was saved under in the guest’s Downloads folder; a clash gets a suffix, never an overwrite. |
state | string | One of completed, failed. |
fileId | string | The Files library id of a completed download (not set yet). |
sizeBytes | integer | |
failureReason | string |
Page.waitForFunction
Browser: served
Phone: not served
Computer: served
Takes targetId
Run expression with args in world every pollingMs (every animation frame by default) until it returns a truthy value, then return that value. A throw ends the wait with exception, as Page.evaluate. ActionTimeout when timeoutMs runs out.
| Param | Type | Required | Description |
|---|---|---|---|
expression | string | Yes | |
args | any[] | No | JSON values passed to the expression, in order. |
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". |
pollingMs | integer | No | Omitted or 0 polls every animation frame. |
timeoutMs | integer | No | Budget in milliseconds. 0 or omitted means 30000; at most 120000. Running out is ActionTimeout. |
| Field | Type | Description |
|---|---|---|
value | any | The JSON result; null is a value. |
exception | ScriptException |
Page.ariaSnapshot
Browser: served
Phone: not served
Computer: served
Takes targetId
The accessibility tree of the document body, or of the one element locator resolves to, as Playwright’s aria snapshot: YAML lines of role, accessible name and state. A snapshot longer than maxChars (20000 by default, up to 200000) is cut at a line, ends with a marker line and returns nextOffset: call again with offset to read on. compact drops unnamed wrapper nodes, often a fifth or more of the lines on real pages. ActionTimeout when a given locator doesn’t resolve to one element within timeoutMs. With refs, it is Playwright’s snapshot for AI: every element a pointer can reach is tagged [ref=eN] (and [cursor=pointer] where it shows one), hidden elements are included, and a ref selector acts on a tagged element. A ref keeps naming its element across snapshots while the element is on the page. Refs cover the main frame; an iframe shows as one node.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | No | Which element: a selector object tagged by kind. See Selectors. |
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. |
refs | boolean | No | Tag each element a pointer can reach with [ref=eN], for ref selectors. |
compact | boolean | No | Shorten the snapshot for an agent to read, keeping every element, ref, name and state: unnamed generic and rowgroup wrappers go and their children lift a level; a row, cell or list item with children drops its name (its children’s text again); [cursor=pointer] tags go; links on the page’s own origin show their path. About half the size on a table-heavy page. |
maxChars | integer | No | Most characters to return; 20000 when 0 or omitted. From 0 to 200000. |
offset | integer | No | Characters to skip first: a cut snapshot’s nextOffset, to read the rest. |
| Field | Type | Description |
|---|---|---|
snapshot | string | Playwright’s aria snapshot as YAML text, at most maxChars characters from offset, plus a marker line when cut. |
totalChars | integer | The whole snapshot’s length in characters, after compact. |
nextOffset | integer | Where the rest starts when this part was cut (pass it as offset); absent at the end. |
Page.getText
Browser: served
Phone: not served
Computer: served
Takes targetId
The visible text of the document body, or of the one element locator resolves to, as near-markdown for reading: headings as #, links as [text](url), images as ![alt], list items as ”- ”, table rows as cells joined with ” | ”, buttons as [button: text]. Hidden content, scripts and form fields’ values are left out. Paged as Page.ariaSnapshot: at most maxChars (20000 by default, up to 200000), cut at a line with nextOffset to read on. Main frame only. ActionTimeout when a given locator doesn’t resolve to one element within timeoutMs.
| Param | Type | Required | Description |
|---|---|---|---|
locator | Selector | No | Which element: a selector object tagged by kind. See Selectors. |
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. |
maxChars | integer | No | Most characters to return; 20000 when 0 or omitted. From 0 to 200000. |
offset | integer | No | Characters to skip first: a cut read’s nextOffset, to read the rest. |
| Field | Type | Description |
|---|---|---|
text | string | The text from offset, at most maxChars characters, plus a marker line when cut. |
totalChars | integer | The whole text’s length in characters. |
nextOffset | integer | Where the rest starts when this part was cut (pass it as offset); absent at the end. |
Page.findText
Browser: served
Phone: not served
Computer: served
Takes targetId
Find query in the text Page.getText reads (the document body, or the one element locator resolves to) and return the first maxMatches matches in page order, each with contextChars characters either side (cut at a word, ”…” marking a cut) and its offset: pass offset to Page.getText to read on from a match. A plain query matches case-insensitively and any whitespace in it matches any run of whitespace on the page; regex takes an RE2 regular expression. totalMatches counts every match, past maxMatches too, and truncated says some were left out. Main frame only. InvalidArgs for an empty query or a bad regular expression; ActionTimeout when a given locator doesn’t resolve to one element within timeoutMs.
| Param | Type | Required | Description |
|---|---|---|---|
query | string | Yes | The text to find; an RE2 regular expression when regex is set. |
regex | boolean | No | Read query as an RE2 regular expression instead of literal text. |
caseSensitive | boolean | No | Match case exactly; matching ignores case by default. |
contextChars | integer | No | Characters of text to keep either side of each match; 200 when 0 or omitted. From 0 to 2000. |
maxMatches | integer | No | Most matches to return; 10 when 0 or omitted. From 0 to 100. |
locator | Selector | No | Which element: a selector object tagged by kind. See Selectors. |
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. |
| Field | Type | Description |
|---|---|---|
matches | TextMatch[] | The first maxMatches matches, in page order. |
totalMatches | integer | Every match in the text, past maxMatches too. |
truncated | boolean | More than maxMatches matched; only the first maxMatches are in matches. |
totalChars | integer | The searched text’s length in characters. |