DOM Commands

DOM commands provide comprehensive functionality for interacting with the Document Object Model of web pages.

Overview

The DOM commands module is one of the most important modules in Pydoll, providing all the functionality needed to find, interact with, and manipulate HTML elements on web pages.

pydoll.commands.dom_commands

DomCommands

Implementation of Chrome DevTools Protocol for the DOM domain.

This class provides commands for interacting with the Document Object Model (DOM) in the browser, enabling access and manipulation of the element structure in a web page. The DOM domain in Chrome DevTools Protocol exposes operations for reading and writing to the DOM, which is fundamental for browser automation, testing, and debugging.

Each DOM element is represented by a mirror object with a unique ID. This ID can be used to gather additional information about the node, resolve it into JavaScript object wrappers, manipulate attributes, and perform various other operations on the DOM structure.

describe_node `staticmethod`

describe_node(node_id=None, backend_node_id=None, object_id=None, depth=None, pierce=None)

Describes a DOM node identified by its ID without requiring domain to be enabled.

The describe_node command is particularly useful in scenarios where you need to quickly gather information about a specific element without subscribing to DOM change events, making it more lightweight for isolated element inspection operations.

PARAMETER	DESCRIPTION
`node_id`	Identifier of the node known to the client. TYPE: `Optional[int]` DEFAULT: `None`
`backend_node_id`	Identifier of the backend node used internally by the browser. TYPE: `Optional[int]` DEFAULT: `None`
`object_id`	JavaScript object id of the node wrapper. TYPE: `Optional[str]` DEFAULT: `None`
`depth`	Maximum depth at which children should be retrieved (default is 1). Use -1 for the entire subtree or provide an integer greater than 0. TYPE: `Optional[int]` DEFAULT: `None`
`pierce`	Whether iframes and shadow roots should be traversed when returning the subtree (default is false). TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns detailed information about the requested node. TYPE: `Command[DescribeNodeResponse]`

disable `staticmethod`

disable()

Disables DOM agent for the current page.

Disabling the DOM domain stops the CDP from sending DOM-related events and prevents further DOM manipulation operations until the domain is enabled again. This can be important for optimizing performance when you're done with DOM operations and want to minimize background processing.

RETURNS	DESCRIPTION
`Command`	CDP command to disable the DOM domain. TYPE: `Command[Response]`

enable `staticmethod`

enable(include_whitespace=None)

Enables DOM agent for the current page.

Enabling the DOM domain is a prerequisite for receiving DOM events and using most DOM manipulation methods. The DOM events include changes to the DOM tree structure, attribute modifications, and many others. Without enabling this domain first, many DOM operations would fail or provide incomplete information.

PARAMETER	DESCRIPTION
`include_whitespace`	Whether to include whitespace-only text nodes in the children array of returned Nodes. Allowed values: "none", "all". TYPE: `Optional[IncludeWhitespace]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to enable the DOM domain. TYPE: `Command[Response]`

focus `staticmethod`

focus(node_id=None, backend_node_id=None, object_id=None)

Focuses the given element.

The focus command is crucial for simulating realistic user interactions, as many events (like keyboard input) require that an element has focus first. It's also important for testing proper tab order and keyboard accessibility of web pages.

PARAMETER	DESCRIPTION
`node_id`	Identifier of the node to focus. TYPE: `Optional[int]` DEFAULT: `None`
`backend_node_id`	Identifier of the backend node to focus. TYPE: `Optional[int]` DEFAULT: `None`
`object_id`	JavaScript object id of the node wrapper. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to focus on the specified element. TYPE: `Command[Response]`

get_attributes `staticmethod`

get_attributes(node_id)

Returns attributes for the specified node.

Attribute information is essential in web testing and automation because attributes often contain crucial information about element state, behavior, and metadata. This command provides an efficient way to access all attributes of an element without parsing HTML or using JavaScript evaluation.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to retrieve attributes for. TYPE: `int`

RETURNS	DESCRIPTION
`Command`	CDP command that returns an interleaved array of node attribute names and values [name1, value1, name2, value2, ...]. TYPE: `Command[GetAttributesResponse]`

get_box_model `staticmethod`

get_box_model(node_id=None, backend_node_id=None, object_id=None)

Returns box model information for the specified node.

The box model is a fundamental concept in CSS that describes how elements are rendered with content, padding, borders, and margins. This command provides detailed information about these dimensions and coordinates, which is invaluable for spatial analysis and precision interactions with elements on the page.

PARAMETER	DESCRIPTION
`node_id`	Identifier of the node. TYPE: `Optional[int]` DEFAULT: `None`
`backend_node_id`	Identifier of the backend node. TYPE: `Optional[int]` DEFAULT: `None`
`object_id`	JavaScript object id of the node wrapper. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the box model for the node, including coordinates for content, padding, border, and margin boxes. TYPE: `Command[GetBoxModelResponse]`

get_document `staticmethod`

get_document(depth=None, pierce=None)

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

This is typically the first command called when interacting with the DOM, as it provides access to the document's root node. From this root, you can traverse to any other element on the page. This command implicitly enables DOM domain events for the current target, making it a good starting point for DOM interaction.

PARAMETER	DESCRIPTION
`depth`	Maximum depth at which children should be retrieved (default is 1). Use -1 for the entire subtree or provide an integer greater than 0. TYPE: `Optional[int]` DEFAULT: `None`
`pierce`	Whether iframes and shadow roots should be traversed when returning the subtree (default is false). TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the root DOM node. TYPE: `Command[GetDocumentResponse]`

get_node_for_location `staticmethod`

get_node_for_location(x, y, include_user_agent_shadow_dom=None, ignore_pointer_events_none=None)

Returns node id at given location on the page.

This command is particularly useful for bridging the gap between visual/pixel-based information and the DOM structure. It allows you to convert screen coordinates to actual DOM elements, which is essential for creating inspection tools or for testing spatially-oriented interactions.

PARAMETER	DESCRIPTION
`x`	X coordinate relative to the main frame's viewport. TYPE: `int`
`y`	Y coordinate relative to the main frame's viewport. TYPE: `int`
`include_user_agent_shadow_dom`	Whether to include nodes in user agent shadow roots. TYPE: `Optional[bool]` DEFAULT: `None`
`ignore_pointer_events_none`	Whether to ignore pointer-events:none and test elements underneath them. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the node at the given location, including frame information when available. TYPE: `Command[GetNodeForLocationResponse]`

get_outer_html `staticmethod`

get_outer_html(node_id=None, backend_node_id=None, object_id=None)

Returns node's HTML markup, including the node itself and all its children.

This command provides a way to access the complete HTML representation of an element, making it valuable for when you need to extract, analyze, or verify HTML content. It's more comprehensive than just getting text content as it preserves the full markup structure including tags, attributes, and child elements.

PARAMETER	DESCRIPTION
`node_id`	Identifier of the node. TYPE: `Optional[int]` DEFAULT: `None`
`backend_node_id`	Identifier of the backend node. TYPE: `Optional[int]` DEFAULT: `None`
`object_id`	JavaScript object id of the node wrapper. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the outer HTML markup of the node. TYPE: `Command[GetOuterHTMLResponse]`

hide_highlight `staticmethod`

hide_highlight()

Hides any DOM element highlight.

This command is particularly useful in automation workflows where multiple elements are highlighted in sequence, and you need to clear previous highlights before proceeding to the next element to avoid visual clutter or interference.

RETURNS	DESCRIPTION
`Command`	CDP command to hide DOM element highlights. TYPE: `Command[Response]`

highlight_node `staticmethod`

highlight_node()

Highlights DOM node.

Highlighting nodes is especially valuable during development and debugging sessions to visually confirm which elements are being selected by selectors or coordinates.

RETURNS	DESCRIPTION
`Command`	CDP command to highlight a DOM node. TYPE: `Command[Response]`

highlight_rect `staticmethod`

highlight_rect()

Highlights given rectangle.

Unlike node highlighting, rectangle highlighting allows highlighting arbitrary regions of the page, which is useful for highlighting computed areas or regions that don't correspond directly to DOM elements.

RETURNS	DESCRIPTION
`Command`	CDP command to highlight a rectangular area. TYPE: `Command[Response]`

move_to `staticmethod`

move_to(node_id, target_node_id, insert_before_node_id=None)

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

This command allows for more complex DOM restructuring than simple attribute or content changes. It's particularly useful when testing applications that involve rearranging elements, such as sortable lists, kanban boards, or drag-and-drop interfaces.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to move. TYPE: `int`
`target_node_id`	Id of the element to drop the moved node into. TYPE: `int`
`insert_before_node_id`	Drop node before this one (if absent, the moved node becomes the last child of target_node_id). TYPE: `Optional[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to move a node, returning the new id of the moved node. TYPE: `Command[MoveToResponse]`

query_selector `staticmethod`

query_selector(node_id, selector)

Executes querySelector on a given node.

This method is one of the most fundamental tools for element location, allowing the use of standard CSS selectors to find elements in the DOM. Unlike JavaScript's querySelector, this can be executed on any node (not just document), enabling scoped searches within specific sections of the page.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to query upon. TYPE: `int`
`selector`	CSS selector string. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the first element matching the selector. TYPE: `Command[QuerySelectorResponse]`

query_selector_all `staticmethod`

query_selector_all(node_id, selector)

Executes querySelectorAll on a given node.

This method extends querySelector by returning all matching elements rather than just the first one. This is essential for operations that need to process multiple elements, such as extracting data from tables, lists, or grids, or verifying that the correct number of elements are present.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to query upon. TYPE: `int`
`selector`	CSS selector string. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command that returns all elements matching the selector. TYPE: `Command[QuerySelectorAllResponse]`

remove_attribute `staticmethod`

remove_attribute(node_id, name)

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

This command allows direct manipulation of element attributes without using JavaScript in the page context. It's useful for testing how elements behave when specific attributes are removed or for preparing elements for specific test conditions.

PARAMETER	DESCRIPTION
`node_id`	Id of the element to remove attribute from. TYPE: `int`
`name`	Name of the attribute to remove. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command to remove the specified attribute. TYPE: `Command[Response]`

remove_node `staticmethod`

remove_node(node_id)

Removes node with given id.

This command allows direct removal of DOM elements, which can be useful when testing how an application responds to missing elements or when simplifying a page for focused testing scenarios.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to remove. TYPE: `int`

RETURNS	DESCRIPTION
`Command`	CDP command to remove the specified node. TYPE: `Command[Response]`

request_child_nodes `staticmethod`

request_child_nodes(node_id, depth=None, pierce=None)

Requests that children of the node with given id are returned to the caller.

This method is particularly useful when dealing with large DOM trees, as it allows for more efficient exploration by loading children on demand rather than loading the entire tree at once. Child nodes are returned as setChildNodes events.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to get children for. TYPE: `int`
`depth`	The maximum depth at which children should be retrieved, defaults to 1. Use -1 for the entire subtree. TYPE: `Optional[int]` DEFAULT: `None`
`pierce`	Whether or not iframes and shadow roots should be traversed. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to request child nodes. TYPE: `Command[Response]`

request_node `staticmethod`

request_node(object_id)

Requests that the node is sent to the caller given the JavaScript node object reference.

This method bridges the gap between JavaScript objects in the page context and the CDP's node representation system, allowing automation to work with elements that might only be available as JavaScript references (e.g., from event handlers).

PARAMETER	DESCRIPTION
`object_id`	JavaScript object id to convert into a Node. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the Node id for the given object. TYPE: `Command[RequestNodeResponse]`

resolve_node `staticmethod`

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.

This method provides the opposite functionality of requestNode - instead of getting a CDP node from a JavaScript object, it gets a JavaScript object from a CDP node. This enables executing JavaScript operations on nodes identified through CDP.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to resolve. TYPE: `Optional[int]` DEFAULT: `None`
`backend_node_id`	Backend id of the node to resolve. TYPE: `Optional[int]` DEFAULT: `None`
`object_group`	Symbolic group name that can be used to release multiple objects. TYPE: `Optional[str]` DEFAULT: `None`
`execution_context_id`	Execution context in which to resolve the node. TYPE: `Optional[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns a JavaScript object wrapper for the node. TYPE: `Command[ResolveNodeResponse]`

scroll_into_view_if_needed `staticmethod`

scroll_into_view_if_needed(node_id=None, backend_node_id=None, object_id=None, rect=None)

Scrolls the specified node into view if not already visible.

This command is crucial for reliable web automation, as it ensures elements are actually visible in the viewport before attempting interactions. Modern websites often use lazy loading and have long scrollable areas, making this command essential for working with elements that may not be initially visible.

PARAMETER	DESCRIPTION
`node_id`	Identifier of the node. TYPE: `Optional[int]` DEFAULT: `None`
`backend_node_id`	Identifier of the backend node. TYPE: `Optional[int]` DEFAULT: `None`
`object_id`	JavaScript object id of the node wrapper. TYPE: `Optional[str]` DEFAULT: `None`
`rect`	Optional rect to scroll into view, relative to the node bounds. TYPE: `Optional[Rect]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to scroll the element into view. TYPE: `Command[Response]`

set_attributes_as_text `staticmethod`

set_attributes_as_text(node_id, text, name=None)

Sets attribute for an element with given id, using text representation.

This command allows for more complex attribute manipulation than set_attribute_value, as it accepts a text representation that can potentially define multiple attributes or include special formatting. It's particularly useful when trying to replicate exactly how attributes would be defined in HTML source code.

PARAMETER	DESCRIPTION
`node_id`	Id of the element to set attribute for. TYPE: `int`
`text`	Text with a new attribute value. TYPE: `str`
`name`	Attribute name to replace with new text value. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to set an attribute as text. TYPE: `Command[Response]`

set_attribute_value `staticmethod`

set_attribute_value(node_id, name, value)

Sets attribute for element with given id.

This command provides direct control over element attributes without using JavaScript, which is essential for testing how applications respond to attribute changes or for setting up specific test conditions by controlling element attributes directly.

PARAMETER	DESCRIPTION
`node_id`	Id of the element to set attribute for. TYPE: `int`
`name`	Attribute name. TYPE: `str`
`value`	Attribute value. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command to set an attribute value. TYPE: `Command[Response]`

set_file_input_files `staticmethod`

set_file_input_files(files, node_id=None, backend_node_id=None, object_id=None)

Sets files for the given file input element.

This command solves one of the most challenging automation problems: working with file inputs. It bypasses the OS-level file dialog that normally appears when clicking a file input, allowing automated tests to provide files programmatically.

PARAMETER	DESCRIPTION
`files`	list of file paths to set. TYPE: `list[str]`
`node_id`	Identifier of the node. TYPE: `Optional[int]` DEFAULT: `None`
`backend_node_id`	Identifier of the backend node. TYPE: `Optional[int]` DEFAULT: `None`
`object_id`	JavaScript object id of the node wrapper. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to set files for a file input element. TYPE: `Command[Response]`

set_node_name `staticmethod`

set_node_name(node_id, name)

Sets node name for a node with given id.

This command allows changing the actual tag name of an element, which can be useful for testing how applications handle different types of elements or for testing the impact of semantic HTML choices on accessibility and behavior.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to set name for. TYPE: `int`
`name`	New node name. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the new node id after the name change. TYPE: `Command[SetNodeNameResponse]`

set_node_value `staticmethod`

set_node_value(node_id, value)

Sets node value for a node with given id.

This command is particularly useful for updating the content of text nodes and comments, allowing direct manipulation of text content without changing the surrounding HTML structure.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to set value for. TYPE: `int`
`value`	New node value. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command to set a node's value. TYPE: `Command[Response]`

set_outer_html `staticmethod`

set_outer_html(node_id, outer_html)

Sets node HTML markup, replacing existing one.

This is one of the most powerful DOM manipulation commands, as it allows completely replacing an element and all its children with new HTML. This is useful for making major structural changes to the page or for testing how applications handle dynamically inserted content.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to set outer HTML for. TYPE: `int`
`outer_html`	HTML markup to set. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command to set the outer HTML of a node. TYPE: `Command[Response]`

collect_class_names_from_subtree `staticmethod`

collect_class_names_from_subtree(node_id)

Collects class names for the node with given id and all of its children.

This method is valuable for understanding the styling landscape of a page, especially in complex applications where multiple CSS frameworks might be in use or where classes are dynamically applied.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to collect class names for. TYPE: `int`

RETURNS	DESCRIPTION
`Command`	CDP command that returns a list of all unique class names in the subtree. TYPE: `Command[CollectClassNamesFromSubtreeResponse]`

copy_to `staticmethod`

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.

Unlike move_to, this command creates a copy of the node, leaving the original intact. This is useful when you want to duplicate content rather than move it, such as when testing how multiple instances of the same component behave.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to copy. TYPE: `int`
`target_node_id`	Id of the element to drop the copy into. TYPE: `int`
`insert_before_node_id`	Drop the copy before this node (if absent, the copy becomes the last child of target_node_id). TYPE: `Optional[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the id of the new copy. TYPE: `Command[CopyToResponse]`

discard_search_results `staticmethod`

discard_search_results(search_id)

Discards search results from the session with the given id.

This method helps manage resources when performing multiple searches during a session, allowing explicit cleanup of search results that are no longer needed.

PARAMETER	DESCRIPTION
`search_id`	Unique search session identifier. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command to discard search results. TYPE: `Command[Response]`

get_anchor_element `staticmethod`

get_anchor_element(node_id, anchor_specifier=None)

Finds the closest ancestor node that is an anchor element for the given node.

This method is useful when working with content inside links or when you need to find the enclosing link element for text or other elements. This helps in cases where you might locate text but need to find the actual link around it.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to search for an anchor around. TYPE: `int`
`anchor_specifier`	Optional specifier for anchor tag properties. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the anchor element node information. TYPE: `Command[GetAnchorElementResponse]`

get_container_for_node `staticmethod`

get_container_for_node(node_id, container_name=None, physical_axes=None, logical_axes=None, queries_scroll_state=None)

Finds a containing element for the given node based on specified parameters.

This method helps in understanding the structural and layout context of elements, particularly in complex layouts using CSS features like flexbox, grid, or when dealing with scrollable containers.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to find the container for. TYPE: `int`
`container_name`	Name of the container to look for (e.g., 'scrollable', 'flex'). TYPE: `Optional[str]` DEFAULT: `None`
`physical_axes`	Physical axes to consider (Horizontal, Vertical, Both). TYPE: `Optional[PhysicalAxes]` DEFAULT: `None`
`logical_axes`	Logical axes to consider (Inline, Block, Both). TYPE: `Optional[LogicalAxes]` DEFAULT: `None`
`queries_scroll_state`	Whether to query scroll state or not. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns information about the containing element. TYPE: `Command[GetContainerForNodeResponse]`

get_content_quads `staticmethod`

get_content_quads(node_id=None, backend_node_id=None, object_id=None)

Returns quads that describe node position on the page.

This method provides detailed geometric information about an element's position on the page, accounting for any transformations, rotations, or other CSS effects. This is more precise than getBoxModel for complex layouts.

PARAMETER	DESCRIPTION
`node_id`	Identifier of the node. TYPE: `Optional[int]` DEFAULT: `None`
`backend_node_id`	Identifier of the backend node. TYPE: `Optional[int]` DEFAULT: `None`
`object_id`	JavaScript object id of the node wrapper. TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the quads describing the node position. TYPE: `Command[GetContentQuadsResponse]`

get_detached_dom_nodes `staticmethod`

get_detached_dom_nodes()

Returns information about detached DOM tree elements.

This method is primarily useful for debugging memory issues related to the DOM, as detached DOM nodes (nodes no longer in the document but still referenced in JavaScript) are a common cause of memory leaks in web applications.

RETURNS	DESCRIPTION
`Command`	CDP command that returns information about detached DOM nodes. TYPE: `Command[GetDetachedDomNodesResponse]`

get_element_by_relation `staticmethod`

get_element_by_relation(node_id, relation)

Retrieves an element related to the given one in a specified way.

This method provides a way to find elements based on their relationships to other elements, such as finding the next focusable element after a given one. This is useful for simulating keyboard navigation or for analyzing element relationships.

PARAMETER	DESCRIPTION
`node_id`	Id of the reference node. TYPE: `int`
`relation`	Type of relationship (e.g., nextSibling, previousSibling, firstChild). TYPE: `ElementRelation`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the related element node. TYPE: `Command[GetElementByRelationResponse]`

get_file_info `staticmethod`

get_file_info(object_id)

Returns file information for the given File object.

This method is useful when working with file inputs and the File API, providing access to file metadata like name, size, and MIME type for files selected in file input elements or created programmatically.

PARAMETER	DESCRIPTION
`object_id`	JavaScript object id of the File object to get info for. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command that returns file information. TYPE: `Command[GetFileInfoResponse]`

get_frame_owner `staticmethod`

get_frame_owner(frame_id)

Returns iframe element that owns the given frame.

This method is essential when working with pages that contain iframes, as it allows mapping between frame IDs (used in CDP) and the actual iframe elements in the parent document.

PARAMETER	DESCRIPTION
`frame_id`	Id of the frame to get the owner element for. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the frame owner element. TYPE: `Command[GetFrameOwnerResponse]`

get_nodes_for_subtree_by_style `staticmethod`

get_nodes_for_subtree_by_style(node_id, computed_styles, pierce=None)

Finds nodes with a given computed style in a subtree.

This method allows finding elements based on their computed styles rather than just structure or attributes. This is powerful for testing visual aspects of a page or for finding elements that match specific visual criteria.

PARAMETER	DESCRIPTION
`node_id`	Node to start the search from. TYPE: `int`
`computed_styles`	list of computed style properties to match against. TYPE: `list[CSSComputedStyleProperty]`
`pierce`	Whether or not iframes and shadow roots should be traversed. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns nodes matching the specified styles. TYPE: `Command[GetNodesForSubtreeByStyleResponse]`

get_node_stack_traces `staticmethod`

get_node_stack_traces(node_id)

Gets stack traces associated with a specific node.

This method is powerful for debugging, as it reveals the JavaScript execution paths that led to the creation of specific DOM elements, helping developers understand the relationship between their code and the resulting DOM structure.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to get stack traces for. TYPE: `int`

RETURNS	DESCRIPTION
`Command`	CDP command that returns stack traces related to the node. TYPE: `Command[GetNodeStackTracesResponse]`

get_querying_descendants_for_container `staticmethod`

get_querying_descendants_for_container(node_id)

Returns the querying descendants for container.

This method is particularly useful for working with CSS Container Queries, helping to identify which descendant elements are affected by or querying a particular container element.

PARAMETER	DESCRIPTION
`node_id`	Id of the container node to find querying descendants for. TYPE: `int`

RETURNS	DESCRIPTION
`Command`	CDP command that returns querying descendant information. TYPE: `Command[GetQueryingDescendantForContainerResponse]`

get_relayout_boundary `staticmethod`

get_relayout_boundary(node_id)

Returns the root of the relayout boundary for the given node.

This method helps in understanding layout performance by identifying the boundary of layout recalculations when a particular element changes. This is valuable for optimizing rendering performance.

PARAMETER	DESCRIPTION
`node_id`	Id of the node to find relayout boundary for. TYPE: `int`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the relayout boundary node. TYPE: `Command[GetRelayoutBoundaryResponse]`

get_search_results `staticmethod`

get_search_results(search_id, from_index, to_index)

Returns search results from given fromIndex to given toIndex from a search.

This method is used in conjunction with performSearch to retrieve search results in batches, which is essential when dealing with large result sets that might be inefficient to transfer all at once.

PARAMETER	DESCRIPTION
`search_id`	Unique search session identifier from performSearch. TYPE: `str`
`from_index`	Start index to retrieve results from. TYPE: `int`
`to_index`	End index to retrieve results to (exclusive). TYPE: `int`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the requested search results. TYPE: `Command[GetSearchResultsResponse]`

get_top_layer_elements `staticmethod`

get_top_layer_elements()

Returns all top layer elements in the document.

This method is valuable for working with modern web UIs that make extensive use of overlays, modals, dropdowns, and other elements that need to appear above the normal document flow.

RETURNS	DESCRIPTION
`Command`	CDP command that returns the top layer element information. TYPE: `Command[GetTopLayerElementsResponse]`

mark_undoable_state `staticmethod`

mark_undoable_state()

Marks last undoable state.

This method helps in managing DOM manipulation state, allowing the creation of savepoints that can be reverted to with the undo command. This is useful for complex sequences of DOM operations that should be treated as a unit.

RETURNS	DESCRIPTION
`Command`	CDP command to mark the current state as undoable. TYPE: `Command[Response]`

perform_search `staticmethod`

perform_search(query, include_user_agent_shadow_dom=None)

Searches for a given string in the DOM tree.

This method initiates a search across the DOM tree, supporting plain text, CSS selectors, or XPath expressions. It's a powerful way to find elements or content across the entire document without knowing the exact structure.

PARAMETER	DESCRIPTION
`query`	Plain text or query selector or XPath search query. TYPE: `str`
`include_user_agent_shadow_dom`	True to include user agent shadow DOM in the search. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns search results identifier and count. TYPE: `Command[PerformSearchResponse]`

push_node_by_path_to_frontend `staticmethod`

push_node_by_path_to_frontend(path)

Requests that the node is sent to the caller given its path.

This method provides an alternative way to reference nodes when node IDs aren't available, using path expressions instead. This can be useful when integrating with systems that identify elements by path rather than by ID.

PARAMETER	DESCRIPTION
`path`	Path to node in the proprietary format. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command that returns the node id for the node. TYPE: `Command[PushNodeByPathToFrontendResponse]`

push_nodes_by_backend_ids_to_frontend `staticmethod`

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.

This method allows for efficient batch processing when you have multiple backend node IDs and need to convert them to frontend node IDs for further operations.

PARAMETER	DESCRIPTION
`backend_node_ids`	The array of backend node ids. TYPE: `list[int]`

RETURNS	DESCRIPTION
`Command`	CDP command that returns an array of node ids. TYPE: `Command[PushNodesByBackendIdsToFrontendResponse]`

redo `staticmethod`

redo()

Re-does the last undone action.

This method works in conjunction with undo and markUndoableState to provide a transactional approach to DOM manipulations, allowing for stepping back and forth through a sequence of changes.

RETURNS	DESCRIPTION
`Command`	CDP command to redo the last undone action. TYPE: `Command[Response]`

set_inspected_node `staticmethod`

set_inspected_node(node_id)

Enables console to refer to the node with given id via $x command line API.

This method creates a bridge between automated testing/scripting and manual console interaction, making it easy to reference specific nodes in the console for debugging or experimentation.

PARAMETER	DESCRIPTION
`node_id`	DOM node id to be accessible by means of $x command line API. TYPE: `int`

RETURNS	DESCRIPTION
`Command`	CDP command to set the inspected node. TYPE: `Command[Response]`

set_node_stack_traces_enabled `staticmethod`

set_node_stack_traces_enabled(enable)

Sets if stack traces should be captured for Nodes.

This method enables or disables the collection of stack traces when DOM nodes are created, which can be extremely valuable for debugging complex applications to understand where and why specific DOM elements are being created.

PARAMETER	DESCRIPTION
`enable`	Enable or disable stack trace collection. TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	CDP command to enable or disable node stack traces. TYPE: `Command[Response]`

undo `staticmethod`

undo()

Undoes the last performed action.

This method works in conjunction with redo and markUndoableState to provide transactional control over DOM manipulations, allowing for reverting changes when needed.

RETURNS	DESCRIPTION
`Command`	CDP command to undo the last performed action. TYPE: `Command[Response]`

Usage

DOM commands are used extensively by the WebElement class and element finding methods:

from pydoll.commands.dom_commands import query_selector, get_attributes
from pydoll.connection.connection_handler import ConnectionHandler

# Find element and get its attributes
connection = ConnectionHandler()
node_id = await query_selector(connection, selector="#username")
attributes = await get_attributes(connection, node_id=node_id)

Key Functionality

The DOM commands module provides functions for:

Element Finding

query_selector() - Find single element by CSS selector
query_selector_all() - Find multiple elements by CSS selector
get_document() - Get the document root node

Element Interaction

click_element() - Click on elements
focus_element() - Focus elements
set_attribute_value() - Set element attributes
get_attributes() - Get element attributes

Element Information

get_box_model() - Get element positioning and dimensions
describe_node() - Get detailed element information
get_outer_html() - Get element HTML content

DOM Manipulation

remove_node() - Remove elements from DOM
set_node_value() - Set element values
request_child_nodes() - Get child elements

High-Level APIs

While these commands provide powerful low-level access, most users should use the higher-level WebElement class methods like click(), type_text(), and get_attribute() which use these commands internally.

DOM Commands

Overview

pydoll.commands.dom_commands

DomCommands

describe_node staticmethod

disable staticmethod

enable staticmethod

focus staticmethod

get_attributes staticmethod

get_box_model staticmethod

get_document staticmethod

get_node_for_location staticmethod

get_outer_html staticmethod

hide_highlight staticmethod

highlight_node staticmethod

highlight_rect staticmethod

move_to staticmethod

query_selector staticmethod

query_selector_all staticmethod

remove_attribute staticmethod

remove_node staticmethod

request_child_nodes staticmethod

request_node staticmethod

resolve_node staticmethod

scroll_into_view_if_needed staticmethod

set_attributes_as_text staticmethod

set_attribute_value staticmethod

set_file_input_files staticmethod

set_node_name staticmethod

set_node_value staticmethod

set_outer_html staticmethod

collect_class_names_from_subtree staticmethod

copy_to staticmethod

discard_search_results staticmethod

get_anchor_element staticmethod

get_container_for_node staticmethod

get_content_quads staticmethod

get_detached_dom_nodes staticmethod

get_element_by_relation staticmethod

get_file_info staticmethod

get_frame_owner staticmethod

get_nodes_for_subtree_by_style staticmethod

get_node_stack_traces staticmethod

get_querying_descendants_for_container staticmethod

get_relayout_boundary staticmethod

get_search_results staticmethod

get_top_layer_elements staticmethod

mark_undoable_state staticmethod

perform_search staticmethod

push_node_by_path_to_frontend staticmethod

push_nodes_by_backend_ids_to_frontend staticmethod

redo staticmethod

set_inspected_node staticmethod

set_node_stack_traces_enabled staticmethod

undo staticmethod