ddp_utils.browser.facade.element_extras

import ddp_utils.browser.facade.element_extras

Complete backend-neutral element contracts shared by every provider.

class ddp_utils.browser.facade.element_extras.BrowserScope(browser: Any, root: BrowserElement)

Bases: object

Expose browser searches below a non-element DOM scope.

Examples

Search inside an open shadow root:

submit = host.shadow_root().find("button", text="Submit")

Bind a browser and searchable root.

Parameters

Name	Type	Description
browser	Any	Owning browser facade.
root	BrowserElement	Element-like root accepted by provider search APIs.

Examples

scope = host.shadow_root().

find(tag: str | None = None, **filters: Any) → BrowserElement | None

Find one descendant.

Parameters

Name	Type	Description
tag	str | None	Optional tag name.
**filters	Any	Browser structured-search filters.

Returns

Type	Description
BrowserElement | None	First matching element or None.

Examples

button = scope.find("button").

find_all(tag: str | None = None, **filters: Any) → BrowserCollection

Find all descendants.

Parameters

Name	Type	Description
tag	str | None	Optional tag name.
**filters	Any	Browser structured-search filters.

Returns

Type	Description
BrowserCollection	Matching collection.

Examples

links = scope.find_all("a").

class ddp_utils.browser.facade.element_extras.ElementScopeMixin

Bases: object

Implement the extended element facade without provider leakage.

Examples

Use inherited backend-neutral operations:

element.scroll_into_view().click()

select_one(css: str, **filters: Any) → BrowserElement | None

Find one CSS descendant.

Parameters

Name	Type	Description
css	str	CSS selector.
**filters	Any	Condition, timeout, and required controls.

Returns

Type	Description
BrowserElement | None	First descendant or None.

Examples

button = card.select_one("button.open").

select(css: str, **filters: Any) → BrowserCollection

Find all CSS descendants.

Parameters

Name	Type	Description
css	str	CSS selector.
**filters	Any	Condition and cardinality controls.

Returns

Type	Description
BrowserCollection	Matching descendants.

Examples

rows = table.select("tbody > tr").

double_click(*, timeout: float | None = None, **options: Any) → BrowserElement

Double-click the element.

Parameters

Name	Type	Description
timeout	float | None	Optional action timeout.
**options	Any	Provider-neutral click options supported by Playwright.

Returns

Type	Description
BrowserElement	This element.

Examples

row.double_click(timeout=5).

right_click(*, timeout: float | None = None, **options: Any) → BrowserElement

Open the element context menu.

Parameters

Name	Type	Description
timeout	float | None	Optional action timeout.
**options	Any	Additional Playwright click options.

Returns

Type	Description
BrowserElement	This element.

Examples

row.right_click().

press(key: str, *, timeout: float | None = None) → BrowserElement

Press one key or key chord on the element.

Parameters

Name	Type	Description
key	str	Provider key name or Selenium key value.
timeout	float | None	Optional action timeout.

Returns

Type	Description
BrowserElement	This element.

Examples

field.press("Enter").

focus(*, timeout: float | None = None) → BrowserElement

Move document focus to the element.

Parameters

Name	Type	Description
timeout	float | None	Optional action timeout.

Returns

Type	Description
BrowserElement	This element.

Examples

field.focus().

blur() → BrowserElement

Remove document focus from the element.

Returns

Type	Description
BrowserElement	This element.

Examples

field.blur().

tap(*, timeout: float | None = None) → BrowserElement

Tap the element using touch semantics where supported.

Parameters

Name	Type	Description
timeout	float | None	Optional action timeout.

Returns

Type	Description
BrowserElement	This element.

Examples

mobile_button.tap().

scroll_into_view(*, align: str = 'nearest', timeout: float | None = None) → BrowserElement

Scroll until the element is inside the viewport.

Parameters

Name	Type	Description
align	str	CSS block alignment.
timeout	float | None	Optional action timeout.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
BrowserConfigurationError	If align is not "start", "center", "end" or "nearest".

Examples

footer.scroll_into_view(align="end").

drag_to(target: BrowserElement, *, timeout: float | None = None, **options: Any) → BrowserElement

Drag this element to another element.

Parameters

Name	Type	Description
target	BrowserElement	Destination element.
timeout	float | None	Optional action timeout.
**options	Any	Additional Playwright drag options.

Returns

Type	Description
BrowserElement	This element.

Examples

card.drag_to(column).

set_checked(value: bool, *, timeout: float | None = None, force: bool = False) → BrowserElement

Set checkbox or radio state idempotently.

Parameters

Name	Type	Description
value	bool	Desired checked state.
timeout	float | None	Optional action timeout.
force	bool	Bypass Playwright actionability checks.

Returns

Type	Description
BrowserElement	This element.

Examples

consent.set_checked(True).

select_options(*, values: Sequence[str] | None = None, labels: Sequence[str] | None = None, indexes: Sequence[int] | None = None, timeout: float | None = None) → list[SelectedOption]

Select multiple native options.

Parameters

Name	Type	Description
values	Sequence[str] | None	Option values.
labels	Sequence[str] | None	Visible labels.
indexes	Sequence[int] | None	Zero-based indexes.
timeout	float | None	Optional action timeout.

Returns

Type	Description
list[SelectedOption]	Selected option descriptions.

Raises

Exception	Description
BrowserConfigurationError	If not exactly one selector collection is supplied.

Examples

selected = courts.select_options(values=["fulton", "dekalb"]).

clear_selection() → BrowserElement

Clear every selected option in a multi-select element.

Returns

Type	Description
BrowserElement	This element.

Examples

courts.clear_selection().

upload(files: str | Path | Iterable[str | Path], *, timeout: float | None = None) → BrowserElement

Assign local files to a file input.

Parameters

Name	Type	Description
files	str | Path | Iterable[str | Path]	One path or an iterable of paths.
timeout	float | None	Optional action timeout.

Returns

Type	Description
BrowserElement	This element.

Examples

upload.upload(["a.pdf", "b.pdf"]).

submit(*, timeout: float | None = None) → BrowserElement

Submit the nearest form.

Parameters

Name	Type	Description
timeout	float | None	Reserved action timeout.

Returns

Type	Description
BrowserElement	This element.

Examples

field.submit().

screenshot(path: str | Path | None = None, **options: Any) → bytes | Path

Capture this element.

Parameters

Name	Type	Description
path	str | Path | None	Optional destination path.
**options	Any	Provider screenshot options.

Returns

Type	Description
bytes | Path	PNG bytes or absolute destination path.

Raises

Exception	Description
BrowserConfigurationError	If options are passed for a Selenium element, whose screenshots accept none.

Examples

image = row.screenshot("row.png").

dispatch(event_type: str, event_init: dict[str, Any] | None = None) → BrowserElement

Dispatch a DOM event on the element.

Parameters

Name	Type	Description
event_type	str	DOM event type.
event_init	dict[str, Any] | None	Event constructor options.

Returns

Type	Description
BrowserElement	This element.

Examples

field.dispatch("change", {"bubbles": True}).

wait_for(*, timeout: float, **conditions: Any) → BrowserElement | None

Wait until this element satisfies all supplied conditions.

Parameters

Name	Type	Description
timeout	float	Deadline in seconds.
**conditions	Any	Boolean property expectations such as visible=True.

Returns

Type	Description
BrowserElement | None	This element when accepted, otherwise timeout raises.

Examples

button.wait_for(timeout=10, visible=True, enabled=True).

highlight(*, color: str = 'red', duration: float | None = None) → BrowserElement

Draw a temporary outline around the element.

Parameters

Name	Type	Description
color	str	CSS outline color.
duration	float | None	Optional restoration delay in seconds.

Returns

Type	Description
BrowserElement	This element.

Examples

row.highlight(color="lime", duration=1).

flash(*, color: str = 'yellow', loops: int = 2) → BrowserElement

Flash the element background for diagnostics.

Parameters

Name	Type	Description
color	str	Temporary CSS background color.
loops	int	Number of flashes.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
BrowserConfigurationError	If loops is less than 1.

Examples

button.flash(loops=3).

property text_content: str | None

Return raw DOM text content.

Returns

Text content or None.

Examples

raw = element.text_content.

property inner_html: str

Return serialized child markup.

Returns

Inner HTML.

Examples

markup = element.inner_html.

property outer_html: str

Return serialized element markup.

Returns

Outer HTML.

Examples

markup = element.outer_html.

property value: Any

Return the live element value.

Returns

Provider-serialized value.

Examples

assert field.value == "Fulton".

property tag: str

Return the lowercase tag name.

Returns

Tag name.

Examples

assert field.tag == "input".

property attrs: dict[str, str | None]

Return all HTML attributes.

Returns

Attribute mapping.

Examples

identifier = element.attrs.get("id").

property classes: tuple[str, ...]

Return CSS classes.

Returns

Ordered class tuple.

Examples

assert "active" in element.classes.

property role: str | None

Return explicit or computed ARIA role.

Returns

Role or None.

Examples

assert button.role == "button".

property label: str | None

Return accessible label text when available.

Returns

Label or None.

Examples

print(field.label).

property bounding_box: Rect | None

Return the current element rectangle.

Returns

Rectangle or None when not rendered.

Examples

box = element.bounding_box.

property hidden: bool

Return whether the element is hidden.

Returns

Inverse visibility.

Examples

if overlay.hidden: ....

property disabled: bool

Return whether the element is disabled.

Returns

Inverse enabled state.

Examples

assert submit.disabled.

property readonly: bool

Return whether editing is read-only.

Returns

Read-only state.

Examples

assert not field.readonly.

property editable: bool

Return whether text input is currently editable.

Returns

Combined visible, enabled, and read-only state.

Examples

assert field.editable.

property checked: bool

Return checkbox or radio checked state.

Returns

Checked state.

Examples

assert consent.checked.

property focused: bool

Return whether the element owns document focus.

Returns

Focus state.

Examples

assert field.focused.

property stable: bool

Return whether the element rectangle remains unchanged briefly.

Returns

True when two immediate geometry samples match.

Examples

browser.wait.stable(button, timeout=5).

get(name: str, default: Any = None) → str | None

Return an attribute with a default.

Parameters

Name	Type	Description
name	str	Attribute name.
default	Any	Value returned when absent.

Returns

Type	Description
str | None	Attribute value or default.

Examples

kind = element.get("type", "text").

css(name: str) → str

Return one computed CSS property.

Parameters

Name	Type	Description
name	str	CSS property name.

Returns

Type	Description
str	Computed value.

Examples

color = element.css("color").

parent() → BrowserElement | None

Return the parent element.

Returns

Type	Description
BrowserElement | None	Parent element or None.

Examples

container = field.parent().

children(*, timeout: float | None = None) → BrowserCollection

Return direct element children.

Parameters

Name	Type	Description
timeout	float | None	Optional wait for at least one child.

Returns

Type	Description
BrowserCollection	Child collection.

Examples

items = list_element.children().

siblings(*, before: bool | None = None, after: bool | None = None) → BrowserCollection

Return sibling elements.

Parameters

Name	Type	Description
before	bool | None	Include only preceding siblings when true.
after	bool | None	Include only following siblings when true.

Returns

Type	Description
BrowserCollection	Sibling collection.

Examples

later = row.siblings(after=True).

shadow_root() → BrowserScope | CapabilityResult[Any]

Return an open shadow-root search scope.

Returns

Type	Description
BrowserScope | CapabilityResult[Any]	Search scope or structured unsupported result.

Raises

Exception	Description
ElementActionError	If the element has no open shadow root.

Examples

button = host.shadow_root().find("button").

content_frame() → BrowserFrame | None

Return the frame hosted by this iframe element.

Returns

Type	Description
BrowserFrame | None	Frame descriptor or None.

Examples

frame = iframe.content_frame().

class ddp_utils.browser.facade.element_extras.Rect(x: float, y: float, width: float, height: float)

Bases: object

Describe an element rectangle in CSS pixels.

Parameters

Name	Type	Description
x	float	Left document coordinate.
y	float	Top document coordinate.
width	float	Rectangle width.
height	float	Rectangle height.

Examples

center_x = element.bounding_box.x + element.bounding_box.width / 2.

class ddp_utils.browser.facade.element_extras.SelectedOption(value: str, label: str, index: int)

Bases: object

Describe one selected HTML option.

Parameters

Name	Type	Description
value	str	Option value.
label	str	Visible label.
index	int	Zero-based option index.

Examples

selected = dropdown.select_option(label="Fulton").