ddp_utils.browser.facade.wait_extras

import ddp_utils.browser.facade.wait_extras

High-level synchronous wait contracts for the neutral browser facade.

class ddp_utils.browser.facade.wait_extras.MutationResult(before: Any, after: Any, element: Any = None)

Bases: object

Describe an observed DOM value change.

Parameters

Name	Type	Description
before	Any	Value observed before the change.
after	Any	Value observed after the change.
element	Any	Related element when available.

Examples

change = browser.wait.text_change(row, timeout=10).

class ddp_utils.browser.facade.wait_extras.NavigationResult(url: str, title: str, ready_state: str)

Bases: object

Describe a completed navigation.

Parameters

Name	Type	Description
url	str	Final URL.
title	str	Final page title.
ready_state	str	Final document readiness state.

Examples

result = browser.wait.navigation(timeout=20).

class ddp_utils.browser.facade.wait_extras.WaitScopeMixin

Bases: object

Implement explicit high-level waits through native events or polling.

Examples

Wait without selecting a provider implementation:

button = browser.wait.clickable("button", timeout=10)

attached(query: Any, *, timeout: float) → BrowserElement

Wait for an attached element.

Parameters

Name	Type	Description
query	Any	Element, CSS selector, mapping, or resolver.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Attached element.

Examples

row = browser.wait.attached("tr.result", timeout=10).

detached(query: Any, *, timeout: float) → bool

Wait for an element to detach.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
bool	True after detachment.

Examples

browser.wait.detached(".spinner", timeout=10).

visible(query: Any, *, timeout: float) → BrowserElement

Wait for visibility.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Visible element.

Examples

button = browser.wait.visible("button", timeout=10).

hidden(query: Any, *, timeout: float) → bool

Wait until a query is absent or hidden.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
bool	True after hiding.

Examples

browser.wait.hidden(".overlay", timeout=10).

enabled(query: Any, *, timeout: float) → BrowserElement

Wait for enabled state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Enabled element.

Examples

submit = browser.wait.enabled("button", timeout=10).

disabled(query: Any, *, timeout: float) → BrowserElement

Wait for disabled state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Disabled element.

Examples

button = browser.wait.disabled("button", timeout=10).

editable(query: Any, *, timeout: float) → BrowserElement

Wait for editable state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Editable element.

Examples

field = browser.wait.editable("input", timeout=10).

readonly(query: Any, *, timeout: float) → BrowserElement

Wait for read-only state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Read-only element.

Examples

field = browser.wait.readonly("input", timeout=10).

clickable(query: Any, *, timeout: float) → BrowserElement

Wait for visible and enabled state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Clickable element.

Examples

button = browser.wait.clickable("button", timeout=10).

checked(query: Any, *, timeout: float) → BrowserElement

Wait for checked state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Checked element.

Examples

box = browser.wait.checked("#consent", timeout=10).

unchecked(query: Any, *, timeout: float) → BrowserElement

Wait for unchecked state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Unchecked element.

Examples

box = browser.wait.unchecked("#consent", timeout=10).

selected(query: Any, *, timeout: float) → BrowserElement

Wait for selected state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Selected element.

Examples

option = browser.wait.selected("option", timeout=10).

unselected(query: Any, *, timeout: float) → BrowserElement

Wait for unselected state.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Unselected element.

Examples

option = browser.wait.unselected("option", timeout=10).

focused(query: Any, *, timeout: float) → BrowserElement

Wait for document focus.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Focused element.

Examples

field = browser.wait.focused("input", timeout=10).

stable(query: Any, *, timeout: float, interval: float = 0.1) → BrowserElement

Wait for stable geometry.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.
interval	float	Observation interval.

Returns

Type	Description
BrowserElement	Stable element.

Examples

row = browser.wait.stable("tr", timeout=10).

text(query: Any, expected: Any, *, match: str = 'exact', case_sensitive: bool = True, timeout: float) → BrowserElement

Wait for visible text.

Parameters

Name	Type	Description
query	Any	Element or query.
expected	Any	Expected text or expression.
match	str	Comparison mode.
case_sensitive	bool	Preserve text case.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Matching element.

Examples

row = browser.wait.text("tr", "Ready", timeout=10).

value(query: Any, expected: Any, *, match: str = 'exact', case_sensitive: bool = True, timeout: float) → BrowserElement

Wait for an element value.

Parameters

Name	Type	Description
query	Any	Element or query.
expected	Any	Expected value.
match	str	Comparison mode.
case_sensitive	bool	Preserve text case.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Matching element.

Examples

field = browser.wait.value("input", "Fulton", timeout=10).

attribute(query: Any, name: str, expected: Any = ANY, *, match: str = 'exact', timeout: float) → BrowserElement

Wait for an attribute value.

Parameters

Name	Type	Description
query	Any	Element or query.
name	str	Attribute name.
expected	Any	Expected value or ANY.
match	str	Comparison mode.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Matching element.

Examples

row = browser.wait.attribute("tr", "data-id", timeout=10).

property(query: Any, name: str, expected: Any, *, timeout: float) → BrowserElement

Wait for a DOM property.

Parameters

Name	Type	Description
query	Any	Element or query.
name	str	Property name.
expected	Any	Expected value or expression.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Matching element.

Examples

field = browser.wait.property("input", "readOnly", True, timeout=10).

css(query: Any, name: str, expected: Any, *, match: str = 'exact', timeout: float) → BrowserElement

Wait for a computed CSS property.

Parameters

Name	Type	Description
query	Any	Element or query.
name	str	CSS property name.
expected	Any	Expected value.
match	str	Comparison mode.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Matching element.

Examples

row = browser.wait.css("tr", "display", "table-row", timeout=10).

class_name(query: Any, expected: str, *, present: bool = True, timeout: float) → BrowserElement

Wait for CSS class membership.

Parameters

Name	Type	Description
query	Any	Element or query.
expected	str	Class name.
present	bool	Desired membership state.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Matching element.

Examples

row = browser.wait.class_name("tr", "active", timeout=10).

count(query: Any, expected: int, *, timeout: float) → BrowserCollection

Wait for an exact element count.

Parameters

Name	Type	Description
query	Any	Collection or query.
expected	int	Exact count.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserCollection	Matching collection.

Examples

rows = browser.wait.count("tr", 10, timeout=20).

minimum(query: Any, expected: int, *, timeout: float) → BrowserCollection

Wait for a minimum element count.

Parameters

Name	Type	Description
query	Any	Collection or query.
expected	int	Minimum count.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserCollection	Matching collection.

Examples

rows = browser.wait.minimum("tr", 1, timeout=20).

maximum(query: Any, expected: int, *, timeout: float) → BrowserCollection

Wait for a maximum element count.

Parameters

Name	Type	Description
query	Any	Collection or query.
expected	int	Maximum count.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserCollection	Matching collection.

Examples

rows = browser.wait.maximum("tr", 10, timeout=20).

count_change(query: Any, *, from_count: int | None = None, timeout: float) → BrowserCollection

Wait for a collection count change.

Parameters

Name	Type	Description
query	Any	Collection resolver or selector.
from_count	int | None	Baseline; omitted means observe the initial count.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserCollection	Changed collection.

Examples

rows = browser.wait.count_change("tr", timeout=20).

url(expected: Any, *, match: str = 'exact', case_sensitive: bool = True, timeout: float) → str

Wait for the page URL.

Parameters

Name	Type	Description
expected	Any	Expected URL or expression.
match	str	Comparison mode.
case_sensitive	bool	Preserve case.
timeout	float	Deadline in seconds.

Returns

Type	Description
str	Matching URL.

Examples

url = browser.wait.url("/results", match="ends_with", timeout=20).

title(expected: Any, *, match: str = 'exact', case_sensitive: bool = True, timeout: float) → str

Wait for the page title.

Parameters

Name	Type	Description
expected	Any	Expected title or expression.
match	str	Comparison mode.
case_sensitive	bool	Preserve case.
timeout	float	Deadline in seconds.

Returns

Type	Description
str	Matching title.

Examples

title = browser.wait.title("Results", timeout=20).

load_state(state: str = 'load', *, timeout: float) → str

Wait for a document load state.

Parameters

Name	Type	Description
state	str	commit, domcontentloaded, load, or networkidle.
timeout	float	Deadline in seconds.

Returns

Type	Description
str	Requested state.

Examples

browser.wait.load_state("domcontentloaded", timeout=20).

page_ready(*, timeout: float) → bool

Wait until the document is complete.

Parameters

Name	Type	Description
timeout	float	Deadline in seconds.

Returns

Type	Description
bool	True when ready.

Examples

browser.wait.page_ready(timeout=20).

navigation(*, url: str | None = None, wait_until: str = 'load', timeout: float) → NavigationResult

Wait for navigation completion and optional URL.

Parameters

Name	Type	Description
url	str | None	Optional URL glob.
wait_until	str	Load state.
timeout	float	Deadline in seconds.

Returns

Type	Description
NavigationResult	Navigation result.

Examples

result = browser.wait.navigation(url="*/results", timeout=20).

network_idle(*, idle_for: float = 0.5, timeout: float) → bool

Wait for a quiet network interval.

Parameters

Name	Type	Description
idle_for	float	Required quiet duration in seconds.
timeout	float	Deadline in seconds.

Returns

Type	Description
bool	True after the quiet interval.

Examples

browser.wait.network_idle(timeout=20).

request(*, url: str | None = None, method: str | None = None, predicate: Callable[[Any], bool] | None = None, timeout: float) → Any

Wait for a network request.

Parameters

Name	Type	Description
url	str | None	Optional URL glob.
method	str | None	Optional HTTP method.
predicate	Callable[[Any], bool] | None	Optional record predicate.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	Matching normalized network record.

Examples

request = browser.wait.request(url="*/api/*", timeout=20).

response(*, url: str | None = None, status: int | None = None, predicate: Callable[[Any], bool] | None = None, timeout: float) → Any

Wait for a network response.

Parameters

Name	Type	Description
url	str | None	Optional URL glob.
status	int | None	Optional status code.
predicate	Callable[[Any], bool] | None	Optional record predicate.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	Matching normalized network record.

Examples

response = browser.wait.response(url="*/api/*", status=200, timeout=20).

websocket(*, url: str | None = None, predicate: Callable[[Any], bool] | None = None, timeout: float) → Any

Wait for a WebSocket network record.

Parameters

Name	Type	Description
url	str | None	Optional URL glob.
predicate	Callable[[Any], bool] | None	Optional record predicate.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	Matching normalized record.

Examples

socket = browser.wait.websocket(url="wss://*", timeout=20).

popup(*, predicate: Callable[[Any], bool] | None = None, timeout: float) → Any

Wait for a popup page.

Parameters

Name	Type	Description
predicate	Callable[[Any], bool] | None	Optional page predicate.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	New browser page descriptor.

Examples

popup = browser.wait.popup(timeout=20).

new_page(*, predicate: Callable[[Any], bool] | None = None, timeout: float) → Any

Wait for a new top-level page.

Parameters

Name	Type	Description
predicate	Callable[[Any], bool] | None	Optional page predicate.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	New page descriptor.

Examples

page = browser.wait.new_page(timeout=20).

dialog(*, kind: str | None = None, text: str | None = None, timeout: float) → Any

Wait for a JavaScript dialog.

Parameters

Name	Type	Description
kind	str | None	Optional dialog kind.
text	str | None	Optional text fragment.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	Dialog descriptor.

Examples

dialog = browser.wait.dialog(kind="confirm", timeout=20).

download(*, predicate: Callable[[Any], bool] | None = None, timeout: float) → Any

Wait for a started download.

Parameters

Name	Type	Description
predicate	Callable[[Any], bool] | None	Optional download predicate.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	Download descriptor.

Examples

download = browser.wait.download(timeout=30).

file_chooser(*, timeout: float) → Any

Wait for a Playwright file chooser event.

Parameters

Name	Type	Description
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	Native file chooser.

Raises

Exception	Description
UnsupportedCapabilityError	Selenium has no passive equivalent.

Examples

chooser = browser.wait.file_chooser(timeout=10).

console(*, level: str | None = None, text: str | None = None, predicate: Callable[[Any], bool] | None = None, timeout: float) → Any

Wait for a console entry.

Parameters

Name	Type	Description
level	str | None	Optional console level.
text	str | None	Optional text fragment.
predicate	Callable[[Any], bool] | None	Optional entry predicate.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	Matching console entry.

Examples

entry = browser.wait.console(level="error", timeout=20).

page_error(*, predicate: Callable[[Any], bool] | None = None, timeout: float) → Any

Wait for an uncaught page error.

Parameters

Name	Type	Description
predicate	Callable[[Any], bool] | None	Optional error predicate.
timeout	float	Deadline in seconds.

Returns

Type	Description
Any	Matching page error.

Examples

error = browser.wait.page_error(timeout=20).

dom_change(query: Any = None, *, timeout: float, stable_for: float | None = None) → MutationResult

Wait for HTML or element markup to change.

Parameters

Name	Type	Description
query	Any	Optional element query; omitted observes the page HTML.
timeout	float	Deadline in seconds.
stable_for	float | None	Optional post-change stability interval.

Returns

Type	Description
MutationResult	Mutation result.

Examples

change = browser.wait.dom_change("#results", timeout=20).

text_change(query: Any, *, from_value: Any = None, timeout: float) → MutationResult

Wait for visible text to change.

Parameters

Name	Type	Description
query	Any	Element or query.
from_value	Any	Baseline; omitted reads current text.
timeout	float	Deadline in seconds.

Returns

Type	Description
MutationResult	Mutation result.

Examples

change = browser.wait.text_change("#status", timeout=20).

attribute_change(query: Any, name: str, *, from_value: Any = ANY, timeout: float) → MutationResult

Wait for an attribute to change.

Parameters

Name	Type	Description
query	Any	Element or query.
name	str	Attribute name.
from_value	Any	Baseline or ANY to read it initially.
timeout	float	Deadline in seconds.

Returns

Type	Description
MutationResult	Mutation result.

Examples

change = browser.wait.attribute_change(row, "class", timeout=20).

children_change(query: Any, *, timeout: float) → MutationResult

Wait for a direct child count change.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
MutationResult	Mutation result.

Examples

change = browser.wait.children_change(list_element, timeout=20).

animation_end(query: Any, *, timeout: float) → BrowserElement

Wait until CSS animation and geometry settle.

Parameters

Name	Type	Description
query	Any	Element or query.
timeout	float	Deadline in seconds.

Returns

Type	Description
BrowserElement	Stable element.

Examples

panel = browser.wait.animation_end(".panel", timeout=10).