ddp_utils.browser.facade.elements¶

import ddp_utils.browser.facade.elements

Backend-neutral single-element facade.

class ddp_utils.browser.facade.elements.BrowserElement(browser: Browser, native: Any)¶

Bases: ElementScopeMixin

Wrap one Selenium element or Playwright locator behind one API.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.
native	Any	Native WebElement or Playwright Locator.

Examples

Use deterministic element operations without backend branching:

field = browser.find("input", attrs={"name": "first_name"})
field.fill("John")

Bind a native element to its owning browser.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.
native	Any	Native WebElement or Locator.

Examples

Adapters wrap backend search results:

element = BrowserElement(browser, native)

property native: Any¶

Return the explicit backend-native element escape hatch.

Returns

Native WebElement or Playwright Locator.

Examples

Use a provider-only feature intentionally:

native = element.native

property browser: Browser¶

Return the owning browser facade.

Returns

Browser facade that created this element.

Examples

Read backend identity from an element:

print(element.browser.descriptor.provider)

property text: str¶

Return visible element text.

Returns

Current visible text, or an empty string when the backend reports no text.

Examples

Compare a result label:

assert element.text == "Completed"

property tag_name: str¶

Return the lowercase HTML tag name.

Returns

Current element tag name.

Examples

Verify a search returned an input:

assert element.tag_name == "input"

property visible: bool¶

Return whether the element is currently visible.

Returns

Backend-observed visibility.

Examples

Guard an optional action:

if element.visible:
    element.click()

property enabled: bool¶

Return whether the element is enabled.

Returns

Backend-observed enabled state.

Examples

Check button actionability:

assert submit.enabled

property selected: bool¶

Return whether a checkbox, radio, or option is selected.

Returns

Backend-observed selection state.

Examples

Verify a checkbox:

assert checkbox.selected

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

Return one HTML attribute.

Parameters

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

Returns

Type	Description
str \| None	Attribute string or `None` when absent.

Examples

Read a download link:

href = element.attribute("href")

property(name: str, default: Any = None) → Any¶

Return one live DOM property.

Parameters

Name	Type	Description
name	str	DOM property name.
default	Any	Value returned when the property is `None`.

Returns

Type	Description
Any	Provider-native serialized property value.

Examples

Read an input value:

value = field.property("value")

javascript(script: str, *args: Any) → Any¶

Execute JavaScript with this element as arguments[0].

Parameters

Name	Type	Description
script	str	JavaScript function body using Selenium-style arguments.
*args	Any	Additional serializable values or facade elements.

Returns

Type	Description
Any	Backend-serialized JavaScript result.

Raises

Exception	Description
UnsupportedCapabilityError	JavaScript is unavailable.

Examples

Read a DOM value relative to this element:

value = field.javascript("return arguments[0].value")

matches(condition: SearchCondition | str) → bool¶

Return whether the element satisfies one observable condition.

Parameters

Name	Type	Description
condition	SearchCondition \| str	Attached, visible, hidden, enabled, disabled, selected, clickable, or editable.

Returns

Type	Description
bool	`True` when the observed condition is satisfied.

Examples

Apply the same condition used by browser.find:

assert element.matches("clickable")

click(*, button: str = 'left', count: int = 1, modifiers: tuple[str, ...] = (), position: tuple[float, float] | None = None, timeout: float | None = None, force: bool = False) → BrowserElement¶

Click the element and report the executed action.

Parameters

Name	Type	Description
button	str	Left, middle, or right mouse button.
count	int	Click count.
modifiers	tuple[str, ...]	Keyboard modifiers held during the click.
position	tuple[float, float] \| None	Optional element-relative `(x, y)` position.
timeout	float \| None	Optional action timeout in seconds.
force	bool	Bypass Playwright actionability checks.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
ElementActionError	The click fails and `required` is true.

Examples

Click a button using the active backend:

browser.find("button", text="Search").click()

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

Clear an editable element.

Parameters

Name	Type	Description
timeout	float \| None	Optional action timeout in seconds.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
ElementActionError	Clearing fails and `required` is true.

Examples

Remove an existing form value:

field.clear()

fill(value: Any, *, timeout: float | None = None) → BrowserElement¶

Replace an editable element value.

Parameters

Name	Type	Description
value	Any	Value converted to text.
timeout	float \| None	Optional action timeout in seconds.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
ElementActionError	Filling fails and `required` is true.

Examples

Replace a search input value:

field.fill("Fulton")

type(text: Any, *, delay: float = 0.0, timeout: float | None = None) → BrowserElement¶

Append text with an optional per-character delay.

Parameters

Name	Type	Description
text	Any	Value converted to text.
delay	float	Delay between characters in seconds.
timeout	float \| None	Optional action timeout in seconds.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
BrowserConfigurationError	Delay is negative.
ElementActionError	Typing fails and `required` is true.

Examples

Type with a human-readable cadence:

field.type("John", delay=0.08)

hover(*, position: tuple[float, float] | None = None, timeout: float | None = None) → BrowserElement¶

Move the pointer over this element.

Parameters

Name	Type	Description
position	tuple[float, float] \| None	Optional element-relative `(x, y)` position.
timeout	float \| None	Optional action timeout in seconds.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
ElementActionError	Hovering fails and `required` is true.

Examples

Reveal a hover menu:

menu.hover()

check(*, timeout: float | None = None, force: bool = False) → BrowserElement¶

Ensure a checkbox or radio is selected.

Parameters

Name	Type	Description
timeout	float \| None	Optional action timeout in seconds.
force	bool	Bypass Playwright actionability checks.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
ElementActionError	Selection fails and `required` is true.

Examples

Select a checkbox idempotently:

checkbox.check()

uncheck(*, timeout: float | None = None, force: bool = False) → BrowserElement¶

Ensure a checkbox is not selected.

Parameters

Name	Type	Description
timeout	float \| None	Optional action timeout in seconds.
force	bool	Bypass Playwright actionability checks.

Returns

Type	Description
BrowserElement	This element.

Raises

Exception	Description
ElementActionError	Deselection fails and `required` is true.

Examples

Clear an optional checkbox idempotently:

checkbox.uncheck()

select_option(*, value: str | None = None, label: str | None = None, index: int | None = None, timeout: float | None = None) → SelectedOption¶

Select one native select option by value, label, or index.

Parameters

Name	Type	Description
value	str \| None	Option value.
label	str \| None	Visible option label.
index	int \| None	Zero-based option index.
timeout	float \| None	Optional action timeout in seconds.

Returns

Type	Description
SelectedOption	Selected option description.

Raises

Exception	Description
ElementActionError	The selector count is not one or selection fails.

Examples

Select a court by visible label:

dropdown.select_option(label="Fulton")

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

Restore a facade-hidden element and verify that it is visible.

Parameters

Name	Type	Description
timeout	float \| None	Optional visibility verification deadline.

Returns

Type	Description
BrowserElement	This visible element.

Raises

Exception	Description
ElementActionError	The element remains hidden and `required` is true.

Examples

Restore an element previously hidden through this facade:

element.show()

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

Hide an existing visible element and verify the result.

Parameters

Name	Type	Description
timeout	float \| None	Optional hidden-state verification deadline.

Returns

Type	Description
BrowserElement	This hidden element.

Raises

Exception	Description
ElementActionError	The element remains visible and `required` is true.

Examples

Hide an obstructing overlay:

overlay.hide()

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

Find one descendant using the browser’s structured search contract.

Parameters

Name	Type	Description
tag	str \| None	Optional descendant tag name.
**filters	Any	Keyword filters accepted by `Browser.find`.

Returns

Type	Description
BrowserElement \| None \| Any	Descendant element, `None`, or unsupported capability result.

Examples

Find a row-local action button:

button = row.find("button", text="Open")

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

Find all descendants using the browser’s structured search contract.

Parameters

Name	Type	Description
tag	str \| None	Optional descendant tag name.
**filters	Any	Keyword filters accepted by `Browser.find_all`.

Returns

Type	Description
BrowserCollection \| Any	Browser collection or unsupported capability result.

Examples

Find every link inside a result card:

links = card.find_all("a")

class ddp_utils.browser.facade.elements.ElementQuery(name: str | None = None, attrs: Mapping[str, ~typing.Any]=<factory>, text: str | Pattern[str] | ValueMatch | None = None, match: MatchMode | str = MatchMode.EXACT, case_sensitive: bool = True, condition: SearchCondition | str = SearchCondition.ATTACHED)¶

Bases: object

Structured criteria for BeautifulSoup-like DOM search syntax.

Parameters

Name	Type	Description
name	str \| None	Optional HTML tag name. `None` means any tag.
attrs	Mapping[str, Any]	Attribute names mapped to values or `ValueMatch` objects. `True` means that the attribute must exist.
text	str \| Pattern[str] \| ValueMatch \| None	Optional visible-text value or independent `ValueMatch`.
match	MatchMode \| str	Default comparison mode for scalar text and attribute values.
case_sensitive	bool	Default case policy for scalar values.
condition	SearchCondition \| str	Required observable element state.

Examples

Find a visible link whose text contains a case-insensitive phrase:

query = ElementQuery(
    name="a",
    text="case details",
    match="contains",
    case_sensitive=False,
    condition="visible",
)

property candidate_selector: str¶

Return a safe broad CSS selector for backend candidate discovery.

Returns

Tag plus attribute-presence selector. Value matching remains in the neutral filter to preserve identical semantics across backends.

Examples

Narrow candidates before applying a contains comparison:

assert ElementQuery("a", {"href": "/"}).candidate_selector == "a[href]"

text_matcher() → ValueMatch | None¶

Return the normalized text matcher when text was requested.

Returns

Type	Description
ValueMatch \| None	Independent or default-derived matcher; otherwise `None`.

Examples

Obtain the default-derived matcher:

matcher = ElementQuery(text="Submit").text_matcher()

attribute_matcher(value: Any) → ValueMatch | None¶

Normalize one attribute value requirement.

Parameters

Name	Type	Description
value	Any	Scalar, compiled pattern, `ValueMatch`, or existence flag.

Returns

Type	Description
ValueMatch \| None	Value matcher, or `None` when only existence is required.

Examples

Convert a scalar using the query defaults:

matcher = query.attribute_matcher("button")