AXAndroidNode
| Field | Type | Required | Description |
|---|---|---|---|
className | string | No | |
viewIdResourceName | string | No | |
packageName | string | No | |
text | string | No | |
contentDescription | string | No | |
hintText | string | No |
AXAndroidWindow
| Field | Type | Required | Description |
|---|---|---|---|
packageName | string | No | The package that owns the window, when known. |
windowType | integer | Yes | AccessibilityWindowInfo.getType(). |
AXNode
CDP’s AXNode plus bounds, windowId and actions. The role value, property names and actions are platform-scoped (“<platform>.button”, “<platform>.disabled”): controls on different platforms are different things with different capabilities. name, value and bounds are plain. nodeId is an opaque string, stable while the element lives. bounds are window pixels (the space screenshots use).
| Field | Type | Required | Description |
|---|---|---|---|
nodeId | string | Yes | Opaque; stable while the element lives. Never parse it. |
ignored | boolean | Yes | |
role | AXValue | Yes | |
name | AXValue | No | |
description | AXValue | No | |
value | AXValue | No | |
properties | AXProperty[] | No | |
parentId | string | No | |
childIds | string[] | Yes | |
bounds | Bbox | Yes | |
windowId | string | Yes | |
actions | string[] | Yes | Platform-scoped actions the node supports, e.g. “<platform>.scroll”. |
platform | AXNodePlatform | No | Native attributes, keyed by platform. Not portable. A phone session sets android, a computer session windows; a browser session omits the bag. |
AXNodePlatform
Native attributes, keyed by platform. Not portable. A phone session sets android, a computer session windows; a browser session omits the bag.
| Field | Type | Required | Description |
|---|---|---|---|
android | AXAndroidNode | No | |
windows | AXWindowsNode | No | A node’s UI Automation attributes: the automation id (what testId selectors match on a computer), the window class, the UI framework and the owning process. |
AXProperty
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Platform-scoped CDP property name, e.g. “<platform>.focusable”, “<platform>.disabled”, “<platform>.checked”. |
value | AXValue | Yes |
AXValue
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | CDP AXValueType, e.g. “role”, “computedString”, “boolean”. A role value is platform-scoped (“<platform>.button”). |
value | any | No | A string, boolean or number. |
AXWindow
| Field | Type | Required | Description |
|---|---|---|---|
windowId | string | Yes | |
title | string | No | |
type | string | Yes | Platform-scoped window type. “<platform>.application” is a window showing app content; locators need one to resolve against the tree. |
focused | boolean | Yes | |
bounds | Bbox | Yes | |
rootId | string | No | |
platform | AXWindowPlatform | No | A window’s native attributes, keyed by platform. Not portable. |
AXWindowPlatform
A window’s native attributes, keyed by platform. Not portable.
| Field | Type | Required | Description |
|---|---|---|---|
android | AXAndroidWindow | No |
AXWindowsNode
A node’s UI Automation attributes: the automation id (what testId selectors match on a computer), the window class, the UI framework and the owning process.
| Field | Type | Required | Description |
|---|---|---|---|
automationId | string | No | |
className | string | No | |
frameworkId | string | No | |
pid | integer | No |
Bbox
| Field | Type | Required | Description |
|---|---|---|---|
x | integer | Yes | |
y | integer | Yes | |
width | integer | Yes | |
height | integer | Yes |
Cookie
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
value | string | Yes | |
domain | string | Yes | |
path | string | Yes | |
expiresMs | integer | No | Epoch-ms; absent for a session cookie. |
httpOnly | boolean | Yes | |
secure | boolean | Yes | |
sameSite | string | No | One of strict, lax, none. |
partitionKey | CookiePartitionKey | No | A partitioned (CHIPS) cookie’s partition, as the browser reports it. |
CookiePartitionKey
A partitioned (CHIPS) cookie’s partition, as the browser reports it.
| Field | Type | Required | Description |
|---|---|---|---|
topLevelSite | string | Yes | |
hasCrossSiteAncestor | boolean | Yes |
DOMNode
| Field | Type | Required | Description |
|---|---|---|---|
nodeId | string | Yes | Opaque DOM node id, scoped to the tab, frame and document. Never parse it. Fails with StaleNode once the node is gone, or when sent with another frame’s frameId; it never matches a different node. |
nodeType | integer | Yes | The DOM nodeType (1 element, 3 text, 8 comment, 9 document, 11 fragment). |
nodeName | string | Yes | |
localName | string | No | |
nodeValue | string | No | The value of a text or comment node. |
attributes | NameValue[] | No | |
childCount | integer | Yes | The real child count, whatever the read returned. |
children | DOMNode[] | No | |
contentFrameId | string | No | On an iframe or frame element: the frame it shows, for frameId. |
shadowRoots | DOMNode[] | No | The element’s open shadow roots. Closed roots are never opened. |
shadowRootType | string | No | Set on a shadow root node. One of open. |
DeviceInfo
| Field | Type | Required | Description |
|---|---|---|---|
deviceId | string | Yes | |
platform | string | Yes | OS family of the session. |
formFactor | string | Yes | Physical class of the session. |
inputModalities | string[] | Yes | Interaction classes the session accepts, e.g. [“keyboard”, “pointer”]. A client sizes behavior from this, not from platform. |
model | string | No | Best-effort; empty when the descriptor lookup has not succeeded. |
osVersion | string | No | Best-effort; empty when unknown. |
screenWidth | integer | Yes | Width of the live-view frame: the space screenshots, Screen.observe boxes and window-pixel coordinates use. In a browser session that is Chrome’s window. |
screenHeight | integer | Yes | Height of the live-view frame. screenWidth by screenHeight and frame are the same numbers. |
viewport | Size | No | The page’s viewport in CSS pixels, as measured; a request can be clamped. Browser sessions only. |
devicePixelRatio | number | No | Device pixels per CSS pixel, fixed for the session. Browser sessions only. |
window | Bbox | No | Chrome’s visible window on the monitor, exactly what the live view shows (not the OS window bounds, which include invisible resize borders), in monitor pixels. Browser sessions only. |
frame | Size | No | The live-view frame’s size: the size of window, and the same numbers as screenWidth by screenHeight. Browser sessions only. |
monitor | Size | No | The display Chrome runs on, in pixels; pages see it as screen.width and screen.height. Browser sessions only. |
DisplayMode
| Field | Type | Required | Description |
|---|---|---|---|
width | integer | Yes | |
height | integer | Yes |
ElementPosition
Where on the target to act, in CSS pixels from its padding box’s top-left, as Playwright’s position. Omitted means the center.
| Field | Type | Required | Description |
|---|---|---|---|
x | integer | Yes | |
y | integer | Yes |
FileInfo
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
path | string | Yes | |
isDir | boolean | Yes | |
size | integer | Yes | |
modifiedMs | integer | Yes |
FrameInfo
| Field | Type | Required | Description |
|---|---|---|---|
frameId | string | Yes | Opaque frame id for frameId on the envelope. |
parentFrameId | string | No | Absent for the main frame. |
targetId | string | Yes | Opaque tab id, stable while the tab is open. Never parse it. |
url | string | Yes | |
name | string | No | |
crossOrigin | boolean | Yes | The frame is from another origin than its parent. |
NameValue
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
value | string | Yes |
NetworkAction
What a rule does, tagged by type. Each type takes only its own fields; setRules refuses any other, so a rule never silently does something else. No action may set or remove host, any HTTP/2 pseudo-header (:path, :method, :scheme, :authority) or the hop-by-hop and framing headers (x-dcp-network-forbidden-headers), and header names must be HTTP tokens: the destination, path and method change only through url and method, and a rewritten url must be an absolute http or https URL. continue sends the request on, optionally with url and method changed (request stage only) and headers set or removed (request headers at the request stage, response headers at the response stage). A rewritten url is checked against egress policy again and matched against the request rules once more, never in a loop. fulfill answers without the origin (at the response stage it replaces the body): status, headers, and one of body, bodyBase64 and fileId. abort refuses: mode forbidden answers 403, reset resets the stream. pause holds the request, or the response before its body is forwarded, until Network.continuePaused or timeoutMs (10 s by default), then runs defaultAction. record is continue plus storing the request and response bodies in Files, up to 10 MiB each, counted against the organization’s Files quota; it is a request-stage action.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | One of continue, fulfill, abort, pause, record. |
url | string | No | |
method | string | No | |
setHeaders | NameValue[] | No | |
removeHeaders | string[] | No | |
status | integer | No | |
headers | NameValue[] | No | |
body | string | No | |
bodyBase64 | string | No | |
fileId | string | No | |
mode | string | No | One of forbidden, reset. |
timeoutMs | integer | No | |
defaultAction | NetworkAction | No | What a rule does, tagged by type. Each type takes only its own fields; setRules refuses any other, so a rule never silently does something else. No action may set or remove host, any HTTP/2 pseudo-header (:path, :method, :scheme, :authority) or the hop-by-hop and framing headers (x-dcp-network-forbidden-headers), and header names must be HTTP tokens: the destination, path and method change only through url and method, and a rewritten url must be an absolute http or https URL. continue sends the request on, optionally with url and method changed (request stage only) and headers set or removed (request headers at the request stage, response headers at the response stage). A rewritten url is checked against egress policy again and matched against the request rules once more, never in a loop. fulfill answers without the origin (at the response stage it replaces the body): status, headers, and one of body, bodyBase64 and fileId. abort refuses: mode forbidden answers 403, reset resets the stream. pause holds the request, or the response before its body is forwarded, until Network.continuePaused or timeoutMs (10 s by default), then runs defaultAction. record is continue plus storing the request and response bodies in Files, up to 10 MiB each, counted against the organization’s Files quota; it is a request-stage action. |
NetworkMatch
Every field given must match. url is a glob as in Playwright (* within a path segment, ** across segments, ? one character, {a,b} either), urlRegex an RE2 expression; give at most one. Both match the full URL, query included, fragment excluded. A redirect is two requests: response rules see the 3xx (its status and Location), and the follow-up request is matched again at the request stage; both hops share one requestId in records.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | No | |
urlRegex | string | No | |
method | string | No | |
resourceTypes | string[] | No | One of document, iframe, script, style, image, font, media, manifest, worker, fetch, websocket, other. |
stage | string | No | One of request, response. Default "request". |
statusMin | integer | No | Response stage only. |
statusMax | integer | No | Response stage only. |
NetworkRecord
| Field | Type | Required | Description |
|---|---|---|---|
requestId | string | Yes | Opaque; the same for every hop of one redirect chain. |
method | string | Yes | |
url | string | Yes | |
resourceType | string | Yes | The browser’s own resource type: a document in the main frame is document and in a child frame iframe; stylesheets are style; images image; fonts font; media and text tracks media; scripts script, or worker for a worker’s main script; XHR, fetch and event-source requests fetch; WebSocket handshakes websocket; manifests manifest; anything else (preflights, pings, prefetches, reports, signed exchanges) other. One of document, iframe, script, style, image, font, media, manifest, worker, fetch, websocket, other. |
requestHeaders | NameValue[] | Yes | |
status | integer | No | |
responseHeaders | NameValue[] | No | |
timestampMs | integer | Yes | When the browser sent it, epoch-ms. |
ruleId | string | No | |
pauseSkipped | boolean | No | A pause rule matched while 50 requests were already held. |
requestBodyFileId | string | No | |
responseBodyFileId | string | No | |
requestBodyTruncated | boolean | No | |
responseBodyTruncated | boolean | No |
NetworkRecordEntry
| Field | Type | Required | Description |
|---|---|---|---|
seq | integer | Yes | |
kind | string | Yes | One of request, response. |
record | NetworkRecord | Yes |
NetworkRule
| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | Your own label, echoed as ruleId in records. |
match | NetworkMatch | Yes | Every field given must match. url is a glob as in Playwright (* within a path segment, ** across segments, ? one character, {a,b} either), urlRegex an RE2 expression; give at most one. Both match the full URL, query included, fragment excluded. A redirect is two requests: response rules see the 3xx (its status and Location), and the follow-up request is matched again at the request stage; both hops share one requestId in records. |
action | NetworkAction | Yes | What a rule does, tagged by type. Each type takes only its own fields; setRules refuses any other, so a rule never silently does something else. No action may set or remove host, any HTTP/2 pseudo-header (:path, :method, :scheme, :authority) or the hop-by-hop and framing headers (x-dcp-network-forbidden-headers), and header names must be HTTP tokens: the destination, path and method change only through url and method, and a rewritten url must be an absolute http or https URL. continue sends the request on, optionally with url and method changed (request stage only) and headers set or removed (request headers at the request stage, response headers at the response stage). A rewritten url is checked against egress policy again and matched against the request rules once more, never in a loop. fulfill answers without the origin (at the response stage it replaces the body): status, headers, and one of body, bodyBase64 and fileId. abort refuses: mode forbidden answers 403, reset resets the stream. pause holds the request, or the response before its body is forwarded, until Network.continuePaused or timeoutMs (10 s by default), then runs defaultAction. record is continue plus storing the request and response bodies in Files, up to 10 MiB each, counted against the organization’s Files quota; it is a request-stage action. |
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.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | |
title | string | Yes | |
snapshot | string | No | Page.ariaSnapshot with refs and compact, its first 20000 characters (observe snapshot). |
totalChars | integer | No | The whole snapshot’s length in characters. |
nextOffset | integer | No | Where the rest of the snapshot starts, for Page.ariaSnapshot offset; absent when it is whole. |
settled | boolean | Yes | False when the page was still changing when it was read: read it again, or call Page.waitForSettled. |
ObserveIcon
| Field | Type | Required | Description |
|---|---|---|---|
bbox | Bbox | No | |
confidence | number | No |
ObserveText
| Field | Type | Required | Description |
|---|---|---|---|
text | string | No | |
bbox | Bbox | No | |
confidence | number | No |
Point
A position in window pixels (the space screenshots use), (0, 0) at the top-left of the browser window. A point outside the window (negative, x at or past screenWidth, or y at or past screenHeight, from Device.info) fails with InvalidArgs.
| Field | Type | Required | Description |
|---|---|---|---|
x | integer | Yes | |
y | integer | Yes |
ProcessInfo
| Field | Type | Required | Description |
|---|---|---|---|
pid | integer | Yes | |
parentPid | integer | Yes | |
name | string | Yes |
ScriptException
| Field | Type | Required | Description |
|---|---|---|---|
message | string | Yes | |
stack | string | No |
Selector
One way of finding a target, tagged by kind. Each kind reads only its own fields. The DOM kinds (css, xpath, role, text, label, testId, placeholder, altText, title, playwright) resolve with Playwright’s selector engine at x-dcp-playwright-version, matching as page.locator and the getBy methods do there; playwright reads selector, a Playwright selector string taken verbatim (text=…, :has-text(), >>, nth=) using only the engines in x-dcp-playwright-engines. Any other engine answers StrategyUnavailable naming it: internal:control=enter-frame (frames are chosen with frameId), and _react and _vue (the engine runs in an isolated world and can’t read framework internals). css and xpath read selector. role reads role, name and states (exact applies to name). text, label, testId, placeholder, altText and title read value (substring and case-insensitive unless exact); testId matches data-testid unless the session configures another attribute. domNode and axNode read nodeId, an opaque reference from an earlier read that fails with StaleNode once gone and never matches a different element. query reads query, natural language for the model resolver; no other kind ever becomes a model prompt. and and or read selectors. within (inside a match), has (containing a match) and nth (zero-based in reading order, or -1 for the last match) refine any kind. Actions are strict: a selector that matches more than one target fails unless nth picks one. A kind the executor does not serve answers StrategyUnavailable, never an approximate match. role and states are platform-scoped: qualified (“<platform>.button”) or bare (“button”, the tree’s own platform). ref reads ref, a ref from the latest Page.ariaSnapshot with refs (“e5”); one whose element left the page, or that no snapshot gave, fails at once with StaleNode, so take a new snapshot.
| Field | Type | Required | Description |
|---|---|---|---|
kind | string | Yes | How a Selector finds its target. One of css, xpath, role, text, label, testId, placeholder, altText, title, domNode, axNode, query, and, or, playwright, ref. |
selector | string | No | The CSS or XPath query, or the Playwright selector string (kinds css, xpath and playwright). |
role | string | No | Accessibility role, qualified (“<platform>.button”) or bare (“button”). |
name | string | No | Accessible name (kind role). |
states | string[] | No | Required element states (kind role). |
value | string | No | The text, label, test id, placeholder, alt text or title to match. |
exact | boolean | No | |
nodeId | string | No | An opaque DOM or accessibility node reference (kinds domNode and axNode); never parse it. |
query | string | No | Natural-language description of the target (kind query). |
selectors | Selector[] | No | The selectors an and / or combines. |
within | Selector | No | Which element: a selector object tagged by kind. See Selectors. |
has | Selector | No | Which element: a selector object tagged by kind. See Selectors. |
nth | integer | No | Pick the nth match in reading order, zero-based; -1 is the last. From -1 to 2147483647. |
ref | string | No | A ref from Page.ariaSnapshot with refs, such as “e5”, or on a computer a node id from Accessibility.getFullAXTree, such as “u16.2t8q.4” (kind ref). |
Size
| Field | Type | Required | Description |
|---|---|---|---|
width | integer | Yes | |
height | integer | Yes |
TargetInfo
| Field | Type | Required | Description |
|---|---|---|---|
targetId | string | Yes | Opaque tab id, stable while the tab is open. Never parse it. |
url | string | Yes | |
title | string | Yes | |
active | boolean | Yes | The tab is in front. |
current | boolean | Yes | Target-scoped calls without a targetId go to this tab. |
openerId | string | No | The tab whose page opened this one, for popups and target=_blank links. |
TextMatch
One Page.findText match, with the text around it.
| Field | Type | Required | Description |
|---|---|---|---|
offset | integer | Yes | Where the match starts in the whole text, in characters; Page.getText’s offset. |
text | string | Yes | The match with contextChars characters either side, cut at a word, ”…” marking a cut. |
WindowInfo
| Field | Type | Required | Description |
|---|---|---|---|
windowId | string | Yes | Opaque; valid while the window exists. |
title | string | Yes | |
process | string | Yes | The image name, such as notepad.exe. |
pid | integer | Yes | |
bounds | Bbox | Yes | The visible frame in screen pixels, without the invisible resize borders. |
state | string | Yes | One of normal, minimized, maximized. |
focused | boolean | Yes |