WebElement

pydoll.elements.web_element.WebElement

WebElement(object_id, connection_handler, method=None, selector=None, attributes_list=[])

Bases: FindElementsMixin

DOM element wrapper for browser automation.

Provides comprehensive functionality for element interaction, inspection, and manipulation using Chrome DevTools Protocol commands.

Initialize WebElement wrapper.

PARAMETER	DESCRIPTION
object_id	Unique CDP object identifier for this DOM element. TYPE: str
connection_handler	Connection instance for browser communication. TYPE: ConnectionHandler
method	Search method used to find this element (for debugging). TYPE: Optional[str] DEFAULT: None
selector	Selector string used to find this element (for debugging). TYPE: Optional[str] DEFAULT: None
attributes_list	Flat list of alternating attribute names and values. TYPE: list[str] DEFAULT: []

value property

value

Element's value attribute (for form elements).

class_name property

class_name

Element's CSS class name(s).

id property

id

Element's ID attribute.

tag_name property

tag_name

Element's HTML tag name.

is_enabled property

is_enabled

Whether element is enabled (not disabled).

text async property

text

Visible text content of the element.

bounds async property

bounds

Element's bounding box coordinates.

Returns coordinates in CSS pixels relative to document origin.

inner_html async property

inner_html

Element's HTML content (actually returns outerHTML).

get_bounds_using_js async

get_bounds_using_js()

Get element bounds using JavaScript getBoundingClientRect().

Returns coordinates relative to viewport (alternative to bounds property).

take_screenshot async

take_screenshot(path, quality=100)

Capture screenshot of this element only.

Automatically scrolls element into view before capturing.

get_attribute

get_attribute(name)

Get element attribute value.

Note

Only provides attributes available when element was located. For dynamic attributes, consider using JavaScript execution.

scroll_into_view async

scroll_into_view()

Scroll element into visible viewport.

click_using_js async

click_using_js()

Click element using JavaScript click() method.

RAISES	DESCRIPTION
ElementNotVisible	If element is not visible.
ElementNotInteractable	If element couldn't be clicked.

Note

For elements, uses specialized selection approach. Element is automatically scrolled into view.

click async

click(x_offset=0, y_offset=0, hold_time=0.1)

Click element using simulated mouse events.

PARAMETER	DESCRIPTION
x_offset	Horizontal offset from element center. TYPE: int DEFAULT: 0
y_offset	Vertical offset from element center. TYPE: int DEFAULT: 0
hold_time	Duration to hold mouse button down. TYPE: float DEFAULT: 0.1

RAISES	DESCRIPTION
ElementNotVisible	If element is not visible.

Note

For elements, delegates to specialized JavaScript approach. Element is automatically scrolled into view.

insert_text async

insert_text(text)

Insert text in single operation (faster but less realistic than typing).

Note

Element should already be focused for text to be inserted correctly.

set_input_files async

set_input_files(files)

Set file paths for file input element.

PARAMETER	DESCRIPTION
files	list of absolute file paths to existing files. TYPE: list[str]

RAISES	DESCRIPTION
ElementNotAFileInput	If element is not a file input.

type_text async

type_text(text, interval=0.1)

Type text character by character with realistic timing.

More realistic than insert_text() but slower.

key_down async

key_down(key, modifiers=None)

Send key down event.

Note

Only sends key down without release. Pair with key_up() for complete keypress.

key_up async

key_up(key)

Send key up event (should follow corresponding key_down()).

press_keyboard_key async

press_keyboard_key(key, modifiers=None, interval=0.1)

Press and release keyboard key with configurable timing.

Better for special keys (Enter, Tab, etc.) than type_text().

find async

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: Optional[str] DEFAULT: None
class_name	CSS class name to match. TYPE: Optional[str] DEFAULT: None
name	Element name attribute value. TYPE: Optional[str] DEFAULT: None
tag_name	HTML tag name (e.g., "div", "input"). TYPE: Optional[str] DEFAULT: None
text	Text content to match within element. TYPE: Optional[str] 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
Union[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.

query async

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
Union[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.

find_or_wait_element async

find_or_wait_element(by, value, timeout=0, find_all=False, raise_exc=True)

Core element finding method with optional waiting capability.

Searches for elements with flexible waiting. If timeout specified, repeatedly attempts to find elements with 0.5s delays until success or timeout. Used by higher-level find() and query() methods.

PARAMETER	DESCRIPTION
by	Selector strategy (CSS_SELECTOR, XPATH, ID, etc.). TYPE: By
value	Selector value to locate element(s). TYPE: str
timeout	Maximum seconds to wait (0 = no waiting). 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
Union[WebElement, list[WebElement], None]	WebElement, list[WebElement], or None based on find_all and raise_exc.

RAISES	DESCRIPTION
ElementNotFound	If no elements found with timeout=0 and raise_exc=True.
WaitElementTimeout	If elements not found within timeout and raise_exc=True.