ShadowRoot

Consulta dentro de um shadow root, incluindo os fechados, com seletores CSS. Saiba mais em Navegação no DOM.

pydoll.elements.shadow_root.ShadowRoot

ShadowRoot(object_id, connection_handler, mode=OPEN, host_element=None)

Bases: FindElementsMixin

Shadow root wrapper for shadow DOM traversal.

Provides element finding capabilities within shadow DOM boundaries using query() with CSS selectors. Use query() instead of find() — find() and XPath are not supported inside shadow roots.

Usage

shadow_host = await tab.find(id='my-component') shadow_root = await shadow_host.get_shadow_root() button = await shadow_root.query('#internal-button') await button.click()

Initialize shadow root wrapper.

PARAMETER	DESCRIPTION
object_id	CDP object ID for the shadow root node. TYPE: str
connection_handler	Browser connection for CDP commands. TYPE: ConnectionHandler
mode	Shadow root mode (open, closed, or user-agent). TYPE: ShadowRootType DEFAULT: OPEN
host_element	Reference to the shadow host element. TYPE: WebElement | None DEFAULT: None

mode property

mode

Shadow root mode (open, closed, or user-agent).

host_element property

host_element

Reference to the shadow host element, if available.

inner_html async

inner_html()

HTML content of the shadow root.

find async

find(id: str | None = ..., class_name: str | None = ..., name: str | None = ..., tag_name: str | None = ..., text: str | None = ..., timeout: int = ..., find_all: Literal[False] = False, raise_exc: Literal[True] = True, **attributes) -> WebElement

find(id: str | None = ..., class_name: str | None = ..., name: str | None = ..., tag_name: str | None = ..., text: str | None = ..., timeout: int = ..., find_all: Literal[False] = False, raise_exc: Literal[False] = False, **attributes) -> WebElement | None

find(id: str | None = ..., class_name: str | None = ..., name: str | None = ..., tag_name: str | None = ..., text: str | None = ..., timeout: int = ..., find_all: Literal[True] = True, raise_exc: Literal[True] = True, **attributes) -> list[WebElement]

find(id: str | None = ..., class_name: str | None = ..., name: str | None = ..., tag_name: str | None = ..., text: str | None = ..., timeout: int = ..., find_all: Literal[True] = True, raise_exc: Literal[False] = False, **attributes) -> list[WebElement] | None

find(id: str | None = ..., class_name: str | None = ..., name: str | None = ..., tag_name: str | None = ..., text: str | None = ..., timeout: int = ..., find_all: bool = ..., raise_exc: bool = ..., **attributes) -> WebElement | list[WebElement] | None

find(id=None, class_name=None, name=None, tag_name=None, text=None, timeout=0, find_all=False, raise_exc=True, **attributes)

Find element(s) using combination of common HTML attributes.

Flexible element location using standard attributes. Multiple attributes can be combined for specific selectors (builds XPath when multiple specified).

PARAMETER	DESCRIPTION
id	Element ID attribute value. TYPE: str | None DEFAULT: None
class_name	CSS class name to match. TYPE: str | None DEFAULT: None
name	Element name attribute value. TYPE: str | None DEFAULT: None
tag_name	HTML tag name (e.g., "div", "input"). TYPE: str | None DEFAULT: None
text	Text content to match within element. TYPE: str | None DEFAULT: None
timeout	Maximum seconds to wait for elements to appear. TYPE: int DEFAULT: 0
find_all	If True, returns all matches; if False, first match only. TYPE: bool DEFAULT: False
raise_exc	Whether to raise exception if no elements found. TYPE: bool DEFAULT: True
**attributes	Additional HTML attributes to match. TYPE: dict[str, str] DEFAULT: {}

RETURNS	DESCRIPTION
WebElement | list[WebElement] | None	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ValueError	If no search criteria provided.
ElementNotFound	If no elements found and raise_exc=True.
WaitElementTimeout	If timeout specified and no elements appear in time.
NotImplementedError	If called on a ShadowRoot (use query() with CSS instead).

query async

query(expression: str, timeout: int = ..., find_all: Literal[False] = False, raise_exc: Literal[True] = True) -> WebElement

query(expression: str, timeout: int = ..., find_all: Literal[False] = False, raise_exc: Literal[False] = False) -> WebElement | None

query(expression: str, timeout: int = ..., find_all: Literal[True] = True, raise_exc: Literal[True] = True) -> list[WebElement]

query(expression: str, timeout: int = ..., find_all: Literal[True] = True, raise_exc: Literal[False] = False) -> list[WebElement] | None

query(expression: str, timeout: int = ..., find_all: bool = ..., raise_exc: bool = ...) -> WebElement | list[WebElement] | None

query(expression, timeout=0, find_all=False, raise_exc=True)

Find element(s) using raw CSS selector or XPath expression.

Direct access using CSS or XPath syntax. Selector type automatically determined based on expression pattern.

PARAMETER	DESCRIPTION
expression	Selector expression (CSS, XPath, ID with #, class with .). TYPE: str
timeout	Maximum seconds to wait for elements to appear. TYPE: int DEFAULT: 0
find_all	If True, returns all matches; if False, first match only. TYPE: bool DEFAULT: False
raise_exc	Whether to raise exception if no elements found. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
WebElement | list[WebElement] | None	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ElementNotFound	If no elements found and raise_exc=True.
WaitElementTimeout	If timeout specified and no elements appear in time.
NotImplementedError	If called with XPath on a ShadowRoot.

query_script async

query_script(function_declaration, arguments=None, execution_context_id=None)

Run a JavaScript function that returns elements and wrap them as WebElements.

The function runs with the search root bound to this (document on a Tab, the frame document on an iframe element, the element itself on a WebElement, the root on a ShadowRoot) in the same execution context and iframe routing that query() uses. It may return a single Element, a NodeList, an array of Elements, or null.

PARAMETER	DESCRIPTION
function_declaration	JavaScript function source, e.g. function(tag) { return this.querySelectorAll(tag); }. TYPE: str
arguments	CDP call arguments passed positionally to the function. TYPE: list[CallArgument] | None DEFAULT: None
execution_context_id	Run in this execution context of the frame (for example an isolated world created with Page.createIsolatedWorld) with this bound to that context's document. Ignored when the root is a non-iframe element, whose object id already fixes the context. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
list[WebElement]	WebElements for every element the function returned, in return order.

RAISES	DESCRIPTION
ScriptException	If the function throws or fails to compile.
CommandFailed	If the browser rejects the command itself.

execute_command async

execute_command(command, timeout=60)

Send a raw CDP command through this object's session.

The command is routed exactly like the object's own operations: a Tab sends it to the page session, a WebElement inside an out-of-process iframe sends it to that frame's session. Build commands with the factories in pydoll.commands or pass a plain {'method': ..., 'params': ...} dict for methods pydoll does not wrap.

PARAMETER	DESCRIPTION
command	CDP command to send. TYPE: Command[T_CommandParams, T_CommandResponse]
timeout	Seconds to wait for the browser's answer. TYPE: int DEFAULT: 60

RETURNS	DESCRIPTION
T_CommandResponse	The browser's response, with the domain result under 'result'.

RAISES	DESCRIPTION
CommandFailed	If the browser answers with an error.
CommandExecutionTimeout	If no answer arrives within timeout.