DOM

This domain exposes DOM read/write operations. Each DOM Node is represented with its mirror object that has an id. This id can be used to get additional information on the Node, resolve it into the JavaScript object wrapper, etc. It is important that client receives DOM events only for the nodes that are known to the client. Backend keeps track of the nodes that were sent to the client and never sends the same node twice. It is client’s responsibility to collect information about the nodes that were sent to the client.<p>Note that iframe owner elements will return corresponding document elements as their child nodes.</p>

Types

Generally, you do not need to instantiate CDP types yourself. Instead, the API creates objects for you as return values from commands, and then you can use those objects as arguments to other commands.

class cdp.dom.NodeId

Unique DOM node identifier.

class cdp.dom.BackendNodeId

Unique DOM node identifier used to reference a node that may not have been pushed to the front-end.

class cdp.dom.BackendNode(node_type, node_name, backend_node_id)

Backend node with a friendly name.

node_name = None

Node’s nodeName.

node_type = None

Node’s nodeType.

class cdp.dom.PseudoType

Pseudo element type.

AFTER = 'after'
BACKDROP = 'backdrop'
BEFORE = 'before'
FIRST_LETTER = 'first-letter'
FIRST_LINE = 'first-line'
FIRST_LINE_INHERITED = 'first-line-inherited'
INPUT_LIST_BUTTON = 'input-list-button'
RESIZER = 'resizer'
SCROLLBAR = 'scrollbar'
SCROLLBAR_BUTTON = 'scrollbar-button'
SCROLLBAR_CORNER = 'scrollbar-corner'
SCROLLBAR_THUMB = 'scrollbar-thumb'
SCROLLBAR_TRACK = 'scrollbar-track'
SCROLLBAR_TRACK_PIECE = 'scrollbar-track-piece'
SELECTION = 'selection'
class cdp.dom.ShadowRootType

Shadow root type.

CLOSED = 'closed'
OPEN_ = 'open'
USER_AGENT = 'user-agent'
class cdp.dom.Node(node_id, backend_node_id, node_type, node_name, local_name, node_value, parent_id=None, child_node_count=None, children=None, attributes=None, document_url=None, base_url=None, public_id=None, system_id=None, internal_subset=None, xml_version=None, name=None, value=None, pseudo_type=None, shadow_root_type=None, frame_id=None, content_document=None, shadow_roots=None, template_content=None, pseudo_elements=None, imported_document=None, distributed_nodes=None, is_svg=None)

DOM interaction is implemented in terms of mirror objects that represent the actual DOM nodes. DOMNode is a base node mirror type.

attributes = None

Attributes of the Element node in the form of flat array [name1, value1, name2, value2].

backend_node_id = None

The BackendNodeId for this node.

base_url = None

Base URL that Document or FrameOwner node uses for URL completion.

child_node_count = None

Child count for Container nodes.

children = None

Child nodes of this node when requested with children.

content_document = None

Content document for frame owner elements.

distributed_nodes = None

Distributed nodes for given insertion point.

document_url = None

Document URL that Document or FrameOwner node points to.

frame_id = None

Frame ID for frame owner elements.

imported_document = None

Import document for the HTMLImport links.

internal_subset = None

DocumentType’s internalSubset.

is_svg = None

Whether the node is SVG.

local_name = None

Node’s localName.

name = None

Attr’s name.

node_id = None

Node identifier that is passed into the rest of the DOM messages as the nodeId. Backend will only push node with given id once. It is aware of all requested nodes and will only fire DOM events for nodes known to the client.

node_name = None

Node’s nodeName.

node_type = None

Node’s nodeType.

node_value = None

Node’s nodeValue.

parent_id = None

The id of the parent node if any.

pseudo_elements = None

Pseudo elements associated with this node.

pseudo_type = None

Pseudo element type for this node.

public_id = None

DocumentType’s publicId.

shadow_root_type = None

Shadow root type.

shadow_roots = None

Shadow root list for given element host.

system_id = None

DocumentType’s systemId.

template_content = None

Content document fragment for template elements.

value = None

Attr’s value.

xml_version = None

Document’s XML version in case of XML documents.

class cdp.dom.RGBA(r, g, b, a=None)

A structure holding an RGBA color.

a = None

The alpha component, in the [0-1] range (default: 1).

b = None

The blue component, in the [0-255] range.

g = None

The green component, in the [0-255] range.

r = None

The red component, in the [0-255] range.

class cdp.dom.Quad

An array of quad vertices, x immediately followed by y for each point, points clock-wise.

class cdp.dom.BoxModel(content, padding, border, margin, width, height, shape_outside=None)

Box model.

border = None

Border box

content = None

Content box

height = None

Node height

margin = None

Margin box

padding = None

Padding box

shape_outside = None

Shape outside coordinates

width = None

Node width

class cdp.dom.ShapeOutsideInfo(bounds, shape, margin_shape)

CSS Shape Outside details.

bounds = None

Shape bounds

margin_shape = None

Margin shape bounds

shape = None

Shape coordinate details

class cdp.dom.Rect(x, y, width, height)

Rectangle.

height = None

Rectangle height

width = None

Rectangle width

x = None

X coordinate

y = None

Y coordinate

Commands

Each command is a generator function. The return type Generator[x, y, z] indicates that the generator yields arguments of type x, it must be resumed with an argument of type y, and it returns type z. In this library, types x and y are the same for all commands, and z is the return type you should pay attention to. For more information, see Getting Started: Commands.

cdp.dom.collect_class_names_from_subtree(node_id)

Collects class names for the node with given id and all of it’s child nodes.

EXPERIMENTAL

Parameters:node_id (NodeId) – Id of the node to collect class names.
Return type:Generator[Dict[str, Any], Dict[str, Any], List[str]]
Returns:Class name list.
cdp.dom.copy_to(node_id, target_node_id, insert_before_node_id=None)

Creates a deep copy of the specified node and places it into the target container before the given anchor.

EXPERIMENTAL

Parameters:
  • node_id (NodeId) – Id of the node to copy.
  • target_node_id (NodeId) – Id of the element to drop the copy into.
  • insert_before_node_id (Optional[NodeId]) – (Optional) Drop the copy before this node (if absent, the copy becomes the last child of `targetNodeId`).
Return type:

Generator[Dict[str, Any], Dict[str, Any], NodeId]

Returns:

Id of the node clone.

cdp.dom.describe_node(node_id=None, backend_node_id=None, object_id=None, depth=None, pierce=None)

Describes node given its id, does not require domain to be enabled. Does not start tracking any objects, can be used for automation.

Parameters:
  • node_id (Optional[NodeId]) – (Optional) Identifier of the node.
  • backend_node_id (Optional[BackendNodeId]) – (Optional) Identifier of the backend node.
  • object_id (Optional[RemoteObjectId]) – (Optional) JavaScript object id of the node wrapper.
  • depth (Optional[int]) – (Optional) The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
  • pierce (Optional[bool]) – (Optional) Whether or not iframes and shadow roots should be traversed when returning the subtree (default is false).
Return type:

Generator[Dict[str, Any], Dict[str, Any], Node]

Returns:

Node description.

cdp.dom.disable()

Disables DOM agent for the given page.

Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.discard_search_results(search_id)

Discards search results from the session with the given id. getSearchResults should no longer be called for that search.

EXPERIMENTAL

Parameters:search_id (str) – Unique search session identifier.
Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.enable()

Enables DOM agent for the given page.

Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.focus(node_id=None, backend_node_id=None, object_id=None)

Focuses the given element.

Parameters:
  • node_id (Optional[NodeId]) – (Optional) Identifier of the node.
  • backend_node_id (Optional[BackendNodeId]) – (Optional) Identifier of the backend node.
  • object_id (Optional[RemoteObjectId]) – (Optional) JavaScript object id of the node wrapper.
Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

cdp.dom.get_attributes(node_id)

Returns attributes for the specified node.

Parameters:node_id (NodeId) – Id of the node to retrieve attibutes for.
Return type:Generator[Dict[str, Any], Dict[str, Any], List[str]]
Returns:An interleaved array of node attribute names and values.
cdp.dom.get_box_model(node_id=None, backend_node_id=None, object_id=None)

Returns boxes for the given node.

Parameters:
  • node_id (Optional[NodeId]) – (Optional) Identifier of the node.
  • backend_node_id (Optional[BackendNodeId]) – (Optional) Identifier of the backend node.
  • object_id (Optional[RemoteObjectId]) – (Optional) JavaScript object id of the node wrapper.
Return type:

Generator[Dict[str, Any], Dict[str, Any], BoxModel]

Returns:

Box model for the node.

cdp.dom.get_content_quads(node_id=None, backend_node_id=None, object_id=None)

Returns quads that describe node position on the page. This method might return multiple quads for inline nodes.

EXPERIMENTAL

Parameters:
  • node_id (Optional[NodeId]) – (Optional) Identifier of the node.
  • backend_node_id (Optional[BackendNodeId]) – (Optional) Identifier of the backend node.
  • object_id (Optional[RemoteObjectId]) – (Optional) JavaScript object id of the node wrapper.
Return type:

Generator[Dict[str, Any], Dict[str, Any], List[Quad]]

Returns:

Quads that describe node layout relative to viewport.

cdp.dom.get_document(depth=None, pierce=None)

Returns the root DOM node (and optionally the subtree) to the caller.

Parameters:
  • depth (Optional[int]) – (Optional) The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
  • pierce (Optional[bool]) – (Optional) Whether or not iframes and shadow roots should be traversed when returning the subtree (default is false).
Return type:

Generator[Dict[str, Any], Dict[str, Any], Node]

Returns:

Resulting node.

cdp.dom.get_file_info(object_id)

Returns file information for the given File wrapper.

EXPERIMENTAL

Parameters:object_id (RemoteObjectId) – JavaScript object id of the node wrapper.
Return type:Generator[Dict[str, Any], Dict[str, Any], str]
Returns:
cdp.dom.get_flattened_document(depth=None, pierce=None)

Returns the root DOM node (and optionally the subtree) to the caller.

Parameters:
  • depth (Optional[int]) – (Optional) The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
  • pierce (Optional[bool]) – (Optional) Whether or not iframes and shadow roots should be traversed when returning the subtree (default is false).
Return type:

Generator[Dict[str, Any], Dict[str, Any], List[Node]]

Returns:

Resulting node.

cdp.dom.get_frame_owner(frame_id)

Returns iframe node that owns iframe with the given domain.

EXPERIMENTAL

Parameters:frame_id (FrameId) –
Return type:Generator[Dict[str, Any], Dict[str, Any], Tuple[BackendNodeId, Optional[NodeId]]]
Returns:A tuple with the following items:
  1. backendNodeId - Resulting node.
  2. nodeId - (Optional) Id of the node at given coordinates, only when enabled and requested document.
cdp.dom.get_node_for_location(x, y, include_user_agent_shadow_dom=None)

Returns node id at given location. Depending on whether DOM domain is enabled, nodeId is either returned or not.

EXPERIMENTAL

Parameters:
  • x (int) – X coordinate.
  • y (int) – Y coordinate.
  • include_user_agent_shadow_dom (Optional[bool]) – (Optional) False to skip to the nearest non-UA shadow root ancestor (default: false).
Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[BackendNodeId, Optional[NodeId]]]

Returns:

A tuple with the following items:

  1. backendNodeId - Resulting node.
  2. nodeId - (Optional) Id of the node at given coordinates, only when enabled and requested document.

cdp.dom.get_outer_html(node_id=None, backend_node_id=None, object_id=None)

Returns node’s HTML markup.

Parameters:
  • node_id (Optional[NodeId]) – (Optional) Identifier of the node.
  • backend_node_id (Optional[BackendNodeId]) – (Optional) Identifier of the backend node.
  • object_id (Optional[RemoteObjectId]) – (Optional) JavaScript object id of the node wrapper.
Return type:

Generator[Dict[str, Any], Dict[str, Any], str]

Returns:

Outer HTML markup.

cdp.dom.get_relayout_boundary(node_id)

Returns the id of the nearest ancestor that is a relayout boundary.

EXPERIMENTAL

Parameters:node_id (NodeId) – Id of the node.
Return type:Generator[Dict[str, Any], Dict[str, Any], NodeId]
Returns:Relayout boundary node id for the given node.
cdp.dom.get_search_results(search_id, from_index, to_index)

Returns search results from given fromIndex to given toIndex from the search with the given identifier.

EXPERIMENTAL

Parameters:
  • search_id (str) – Unique search session identifier.
  • from_index (int) – Start index of the search result to be returned.
  • to_index (int) – End index of the search result to be returned.
Return type:

Generator[Dict[str, Any], Dict[str, Any], List[NodeId]]

Returns:

Ids of the search result nodes.

cdp.dom.hide_highlight()

Hides any highlight.

Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.highlight_node()

Highlights DOM node.

Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.highlight_rect()

Highlights given rectangle.

Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.mark_undoable_state()

Marks last undoable state.

EXPERIMENTAL

Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.move_to(node_id, target_node_id, insert_before_node_id=None)

Moves node into the new container, places it before the given anchor.

Parameters:
  • node_id (NodeId) – Id of the node to move.
  • target_node_id (NodeId) – Id of the element to drop the moved node into.
  • insert_before_node_id (Optional[NodeId]) – (Optional) Drop node before this one (if absent, the moved node becomes the last child of `targetNodeId`).
Return type:

Generator[Dict[str, Any], Dict[str, Any], NodeId]

Returns:

New id of the moved node.

Searches for a given string in the DOM tree. Use getSearchResults to access search results or cancelSearch to end this search session.

EXPERIMENTAL

Parameters:
  • query (str) – Plain text or query selector or XPath search query.
  • include_user_agent_shadow_dom (Optional[bool]) – (Optional) True to search in user agent shadow DOM.
Return type:

Generator[Dict[str, Any], Dict[str, Any], Tuple[str, int]]

Returns:

A tuple with the following items:

  1. searchId - Unique search session identifier.
  2. resultCount - Number of search results.

cdp.dom.push_node_by_path_to_frontend(path)

Requests that the node is sent to the caller given its path. // FIXME, use XPath

EXPERIMENTAL

Parameters:path (str) – Path to node in the proprietary format.
Return type:Generator[Dict[str, Any], Dict[str, Any], NodeId]
Returns:Id of the node for given path.
cdp.dom.push_nodes_by_backend_ids_to_frontend(backend_node_ids)

Requests that a batch of nodes is sent to the caller given their backend node ids.

EXPERIMENTAL

Parameters:backend_node_ids (List[BackendNodeId]) – The array of backend node ids.
Return type:Generator[Dict[str, Any], Dict[str, Any], List[NodeId]]
Returns:The array of ids of pushed nodes that correspond to the backend ids specified in backendNodeIds.
cdp.dom.query_selector(node_id, selector)

Executes querySelector on a given node.

Parameters:
  • node_id (NodeId) – Id of the node to query upon.
  • selector (str) – Selector string.
Return type:

Generator[Dict[str, Any], Dict[str, Any], NodeId]

Returns:

Query selector result.

cdp.dom.query_selector_all(node_id, selector)

Executes querySelectorAll on a given node.

Parameters:
  • node_id (NodeId) – Id of the node to query upon.
  • selector (str) – Selector string.
Return type:

Generator[Dict[str, Any], Dict[str, Any], List[NodeId]]

Returns:

Query selector result.

cdp.dom.redo()

Re-does the last undone action.

EXPERIMENTAL

Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.remove_attribute(node_id, name)

Removes attribute with given name from an element with given id.

Parameters:
  • node_id (NodeId) – Id of the element to remove attribute from.
  • name (str) – Name of the attribute to remove.
Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

cdp.dom.remove_node(node_id)

Removes node with given id.

Parameters:node_id (NodeId) – Id of the node to remove.
Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.request_child_nodes(node_id, depth=None, pierce=None)

Requests that children of the node with given id are returned to the caller in form of setChildNodes events where not only immediate children are retrieved, but all children down to the specified depth.

Parameters:
  • node_id (NodeId) – Id of the node to get children for.
  • depth (Optional[int]) – (Optional) The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree or provide an integer larger than 0.
  • pierce (Optional[bool]) – (Optional) Whether or not iframes and shadow roots should be traversed when returning the sub-tree (default is false).
Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

cdp.dom.request_node(object_id)

Requests that the node is sent to the caller given the JavaScript node object reference. All nodes that form the path from the node to the root are also sent to the client as a series of setChildNodes notifications.

Parameters:object_id (RemoteObjectId) – JavaScript object id to convert into node.
Return type:Generator[Dict[str, Any], Dict[str, Any], NodeId]
Returns:Node id for given object.
cdp.dom.resolve_node(node_id=None, backend_node_id=None, object_group=None, execution_context_id=None)

Resolves the JavaScript node object for a given NodeId or BackendNodeId.

Parameters:
  • node_id (Optional[NodeId]) – (Optional) Id of the node to resolve.
  • backend_node_id (Optional[BackendNodeId]) – (Optional) Backend identifier of the node to resolve.
  • object_group (Optional[str]) – (Optional) Symbolic group name that can be used to release multiple objects.
  • execution_context_id (Optional[ExecutionContextId]) – (Optional) Execution context in which to resolve the node.
Return type:

Generator[Dict[str, Any], Dict[str, Any], RemoteObject]

Returns:

JavaScript object wrapper for given node.

cdp.dom.set_attribute_value(node_id, name, value)

Sets attribute for an element with given id.

Parameters:
  • node_id (NodeId) – Id of the element to set attribute for.
  • name (str) – Attribute name.
  • value (str) – Attribute value.
Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

cdp.dom.set_attributes_as_text(node_id, text, name=None)

Sets attributes on element with given id. This method is useful when user edits some existing attribute value and types in several attribute name/value pairs.

Parameters:
  • node_id (NodeId) – Id of the element to set attributes for.
  • text (str) – Text with a number of attributes. Will parse this text using HTML parser.
  • name (Optional[str]) – (Optional) Attribute name to replace with new attributes derived from text in case text parsed successfully.
Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

cdp.dom.set_file_input_files(files, node_id=None, backend_node_id=None, object_id=None)

Sets files for the given file input element.

Parameters:
  • files (List[str]) – Array of file paths to set.
  • node_id (Optional[NodeId]) – (Optional) Identifier of the node.
  • backend_node_id (Optional[BackendNodeId]) – (Optional) Identifier of the backend node.
  • object_id (Optional[RemoteObjectId]) – (Optional) JavaScript object id of the node wrapper.
Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

cdp.dom.set_inspected_node(node_id)

Enables console to refer to the node with given id via $x (see Command Line API for more details $x functions).

EXPERIMENTAL

Parameters:node_id (NodeId) – DOM node id to be accessible by means of $x command line API.
Return type:Generator[Dict[str, Any], Dict[str, Any], None]
cdp.dom.set_node_name(node_id, name)

Sets node name for a node with given id.

Parameters:
  • node_id (NodeId) – Id of the node to set name for.
  • name (str) – New node’s name.
Return type:

Generator[Dict[str, Any], Dict[str, Any], NodeId]

Returns:

New node’s id.

cdp.dom.set_node_value(node_id, value)

Sets node value for a node with given id.

Parameters:
  • node_id (NodeId) – Id of the node to set value for.
  • value (str) – New node’s value.
Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

cdp.dom.set_outer_html(node_id, outer_html)

Sets node HTML markup, returns new node id.

Parameters:
  • node_id (NodeId) – Id of the node to set markup for.
  • outer_html (str) – Outer HTML markup to set.
Return type:

Generator[Dict[str, Any], Dict[str, Any], None]

cdp.dom.undo()

Undoes the last performed action.

EXPERIMENTAL

Return type:Generator[Dict[str, Any], Dict[str, Any], None]

Events

Generally, you do not need to instantiate CDP events yourself. Instead, the API creates events for you and then you use the event’s attributes.

class cdp.dom.AttributeModified(node_id, name, value)

Fired when Element’s attribute is modified.

name = None

Attribute name.

node_id = None

Id of the node that has changed.

value = None

Attribute value.

class cdp.dom.AttributeRemoved(node_id, name)

Fired when Element’s attribute is removed.

name = None

A ttribute name.

node_id = None

Id of the node that has changed.

class cdp.dom.CharacterDataModified(node_id, character_data)

Mirrors DOMCharacterDataModified event.

character_data = None

New text value.

node_id = None

Id of the node that has changed.

class cdp.dom.ChildNodeCountUpdated(node_id, child_node_count)

Fired when Container’s child node count has changed.

child_node_count = None

New node count.

node_id = None

Id of the node that has changed.

class cdp.dom.ChildNodeInserted(parent_node_id, previous_node_id, node)

Mirrors DOMNodeInserted event.

node = None

Inserted node data.

parent_node_id = None

Id of the node that has changed.

previous_node_id = None

If of the previous siblint.

class cdp.dom.ChildNodeRemoved(parent_node_id, node_id)

Mirrors DOMNodeRemoved event.

node_id = None

Id of the node that has been removed.

parent_node_id = None

Parent id.

class cdp.dom.DistributedNodesUpdated(insertion_point_id, distributed_nodes)

EXPERIMENTAL

Called when distrubution is changed.

distributed_nodes = None

Distributed nodes for given insertion point.

insertion_point_id = None

Insertion point where distrubuted nodes were updated.

class cdp.dom.DocumentUpdated

Fired when Document has been totally updated. Node ids are no longer valid.

class cdp.dom.InlineStyleInvalidated(node_ids)

EXPERIMENTAL

Fired when Element’s inline style is modified via a CSS property modification.

node_ids = None

Ids of the nodes for which the inline styles have been invalidated.

class cdp.dom.PseudoElementAdded(parent_id, pseudo_element)

EXPERIMENTAL

Called when a pseudo element is added to an element.

parent_id = None

Pseudo element’s parent element id.

pseudo_element = None

The added pseudo element.

class cdp.dom.PseudoElementRemoved(parent_id, pseudo_element_id)

EXPERIMENTAL

Called when a pseudo element is removed from an element.

parent_id = None

Pseudo element’s parent element id.

pseudo_element_id = None

The removed pseudo element id.

class cdp.dom.SetChildNodes(parent_id, nodes)

Fired when backend wants to provide client with the missing DOM structure. This happens upon most of the calls requesting node ids.

nodes = None

Child nodes array.

parent_id = None

Parent node id to populate with children.

class cdp.dom.ShadowRootPopped(host_id, root_id)

EXPERIMENTAL

Called when shadow root is popped from the element.

host_id = None

Host element id.

root_id = None

Shadow root id.

class cdp.dom.ShadowRootPushed(host_id, root)

EXPERIMENTAL

Called when shadow root is pushed into the element.

host_id = None

Host element id.

root = None

Shadow root.