ddp_utils.browser.facade.advanced

import ddp_utils.browser.facade.advanced

Advanced neutral browser services: events, emulation, logs, tracing, and assertions.

class ddp_utils.browser.facade.advanced.BrowserCapabilities(browser: Any)

Bases: object

Expose structured runtime capability discovery.

Examples

Require network support before a mandatory operation:

browser.capabilities.require("network")

supports(name: str) → bool

Return whether a capability is available.

Parameters

Name	Type	Description
name	str	Capability name.

Returns

Type	Description
bool	Support state.

Examples

if browser.capabilities.supports("cdp"): ....

require(name: str) → CapabilityInfo

Require a capability.

Parameters

Name	Type	Description
name	str	Capability name.

Returns

Type	Description
CapabilityInfo	Supported capability information.

Raises

Exception	Description
UnsupportedCapabilityError	Capability is unavailable.

Examples

browser.capabilities.require("network").

get(name: str) → CapabilityInfo

Return capability information.

Parameters

Name	Type	Description
name	str	Capability name.

Returns

Type	Description
CapabilityInfo	Capability information.

Examples

info = browser.capabilities.get("pdf").

all() → dict[str, CapabilityInfo]

Return every declared capability.

Returns

Type	Description
dict[str, CapabilityInfo]	Mapping by stable capability name.

Examples

capabilities = browser.capabilities.all().

explain(name: str) → str

Return a human-readable support explanation.

Parameters

Name	Type	Description
name	str	Capability name.

Returns

Type	Description
str	Support explanation.

Examples

print(browser.capabilities.explain("cdp")).

class ddp_utils.browser.facade.advanced.BrowserEmulation(browser: Any)

Bases: object

Apply runtime emulation only where the backend can preserve coherence.

Examples

Change the viewport through the active backend:

browser.emulation.viewport(1440, 900)

user_agent(value: str | None = None) → str | CapabilityResult[Any]

Read or override the user agent.

Parameters

Name	Type	Description
value	str | None	Override value; omitted reads the current value.

Returns

Type	Description
str | CapabilityResult[Any]	Current string or structured result.

Examples

current = browser.emulation.user_agent().

locale(value: str | None = None) → str | CapabilityResult[Any]

Read or override browser locale.

Parameters

Name	Type	Description
value	str | None	Locale override; omitted reads current language.

Returns

Type	Description
str | CapabilityResult[Any]	Locale string or result.

Examples

browser.emulation.locale("en-US").

timezone(value: str | None = None) → str | CapabilityResult[Any]

Read or override the timezone.

Parameters

Name	Type	Description
value	str | None	IANA timezone; omitted reads current zone.

Returns

Type	Description
str | CapabilityResult[Any]	Timezone string or result.

Examples

browser.emulation.timezone("America/Chicago").

geolocation(value: Geolocation | dict[str, Any] | None = None) → Geolocation | CapabilityResult[Any]

Read or override geolocation.

Parameters

Name	Type	Description
value	Geolocation | dict[str, Any] | None	Coordinate or mapping; omitted returns the last override.

Returns

Type	Description
Geolocation | CapabilityResult[Any]	Coordinate or result.

Examples

browser.emulation.geolocation({"latitude": 41.7, "longitude": 44.8}).

permissions(origin: str | None = None, values: list[str] | None = None) → CapabilityResult[Any]

Grant or clear origin permissions.

Parameters

Name	Type	Description
origin	str | None	Optional origin.
values	list[str] | None	Permissions; None clears overrides.

Returns

Type	Description
CapabilityResult[Any]	Structured operation result.

Examples

browser.emulation.permissions(values=["geolocation"]).

viewport(width: int | None = None, height: int | None = None) → Viewport

Read or set viewport dimensions.

Parameters

Name	Type	Description
width	int | None	Optional width.
height	int | None	Optional height.

Returns

Type	Description
Viewport	Effective viewport.

Examples

viewport = browser.emulation.viewport(1440, 900).

offline(enabled: bool = True) → CapabilityResult[Any]

Set network offline state.

Parameters

Name	Type	Description
enabled	bool	Desired offline state.

Returns

Type	Description
CapabilityResult[Any]	Structured operation result.

Examples

browser.emulation.offline(True).

media(**options: Any) → CapabilityResult[Any]

Apply media feature emulation.

Parameters

Name	Type	Description
**options	Any	Media, color-scheme, reduced-motion, or feature values.

Returns

Type	Description
CapabilityResult[Any]	Structured operation result.

Examples

browser.emulation.media(color_scheme="dark").

device(name: str | None = None, **metrics: Any) → CapabilityResult[Any]

Apply explicit device metrics.

Parameters

Name	Type	Description
name	str | None	Optional diagnostic device name.
**metrics	Any	Width, height, scale factor, mobile, and touch metrics.

Returns

Type	Description
CapabilityResult[Any]	Structured operation result.

Examples

browser.emulation.device("tablet", width=1024, height=768).

clear() → CapabilityResult[Any]

Clear runtime emulation overrides where supported.

Returns

Type	Description
CapabilityResult[Any]	Structured operation result.

Examples

browser.emulation.clear().

class ddp_utils.browser.facade.advanced.BrowserEvents(browser: Any)

Bases: object

Provide synchronous events and persistent browser-state watchers.

Parameters

Name	Type	Description
browser	Any	Owning browser facade used for browser-side observation.

Examples

Subscribe to a condition once near the start of business logic:

browser.events.add_watcher(
    name="confirmation",
    when={"css": ".confirmation", "condition": "visible"},
    callback=handle_confirmation,
)

Initialize the event bus and its shared page observer state.

Parameters

Name	Type	Description
browser	Any	Owning browser facade.

Examples

Browser construction installs one event service:

events = BrowserEvents(browser)

on(event: str, callback: Callable[[Any], Any]) → BrowserSubscription

Subscribe to an event.

Parameters

Name	Type	Description
event	str	Stable event name.
callback	Callable[[Any], Any]	Payload callback.

Returns

Type	Description
BrowserSubscription	Removable subscription.

Examples

sub = browser.events.on("project.ready", callback).

once(event: str, callback: Callable[[Any], Any] | None = None, *, timeout: float | None = None) → Any

Run once or synchronously wait for one event.

Parameters

Name	Type	Description
event	str	Stable event name.
callback	Callable[[Any], Any] | None	Optional one-shot callback.
timeout	float | None	Wait timeout when callback is omitted.

Returns

Type	Description
Any	Subscription or emitted payload.

Raises

Exception	Description
TimeoutError	If the event is not emitted before the timeout.

Examples

payload = browser.events.once("ready", timeout=10).

off(subscription_or_event: BrowserSubscription | str, callback: Callable[[Any], Any] | None = None) → None

Remove subscriptions by handle or event/callback.

Parameters

Name	Type	Description
subscription_or_event	BrowserSubscription | str	Subscription or event name.
callback	Callable[[Any], Any] | None	Optional callback filter.

Examples

browser.events.off(subscription).

emit(event: str, payload: Any = None) → None

Emit a normalized event synchronously.

Parameters

Name	Type	Description
event	str	Stable event name.
payload	Any	Optional payload.

Examples

browser.events.emit("project.ready", context).

add_watcher(name: str, *, when: Mapping[str, Any], callback: Callable[[BrowserWatcherEvent], Any], once: bool = False, cooldown: float = 0.0, trigger_existing: bool = True) → BrowserWatcher

Register a page condition whose callback runs at a safe boundary.

Parameters

Name	Type	Description
name	str	Unique application-facing watcher name.
when	Mapping[str, Any]	Serializable DOM condition using css, url, title, all, any, or not; or a normalized network condition under network.
callback	Callable[[BrowserWatcherEvent], Any]	Function receiving the matching watcher event.
once	bool	Remove the watcher before its first callback runs.
cooldown	float	Minimum seconds between false-to-true transitions.
trigger_existing	bool	Emit when the condition is already true.

Returns

Type	Description
BrowserWatcher	Registered watcher handle.

Raises

Exception	Description
BrowserConfigurationError	The name, condition, or cooldown is invalid, or the name is already registered.
TypeError	callback is not callable.
UnsupportedCapabilityError	Browser JavaScript is unavailable.

Examples

Watch one visible confirmation dialog:

watcher = browser.events.add_watcher(
    name="confirmation",
    when={"css": ".confirmation", "condition": "visible"},
    callback=handle_confirmation,
)

Require several page facts at the same time:

browser.events.add_watcher(
    name="login",
    when={"all": [
        {"css": "form.login", "condition": "visible"},
        {"css": "input[name='password']", "condition": "present"},
    ]},
    callback=handle_login,
)

Observe every failed request through the same safe queue:

browser.events.add_watcher(
    name="request-failed",
    when={"network": {"event": "failure"}},
    callback=handle_failure,
)

remove_watcher(watcher_or_name: BrowserWatcher | str) → bool

Remove one watcher by handle, identifier, or unique name.

Parameters

Name	Type	Description
watcher_or_name	BrowserWatcher | str	Watcher handle, identifier, or registered name.

Returns

Type	Description
bool	True when a registered watcher was removed.

Examples

Remove by handle or stable application name:

browser.events.remove_watcher(watcher)
browser.events.remove_watcher("confirmation")

get_watchers() → tuple[BrowserWatcher, ...]

Return an immutable snapshot of active watchers.

Returns

Type	Description
tuple[BrowserWatcher, …]	Active watchers in registration order.

Examples

Inspect registered application conditions:

names = [watcher.name for watcher in browser.events.get_watchers()]

clear_watchers() → int

Remove every watcher and clear queued matches.

Returns

Type	Description
int	Number of watchers removed.

Examples

Remove project-owned watchers during teardown:

removed = browser.events.clear_watchers()

safe_point(*, watchers: Iterable[str] | None = None, max_events: int | None = None) → list[BrowserWatcherEvent]

Deliver queued watcher callbacks in the current browser thread.

Parameters

Name	Type	Description
watchers	Iterable[str] | None	Optional watcher names or identifiers to deliver. Other queued events remain available for a later safe point.
max_events	int | None	Optional positive delivery limit.

Returns

Type	Description
list[BrowserWatcherEvent]	Events whose callbacks completed during this call.

Raises

Exception	Description
ValueError	max_events is not positive.
Exception	A watcher callback fails. Callback failures deliberately propagate to business logic.

Examples

Process every pending event:

delivered = browser.events.safe_point()

Process at most one CAPTCHA-related event:

delivered = browser.events.safe_point(
    watchers={"captcha"},
    max_events=1,
)

close() → None

Release watcher and subscription state idempotently.

Examples

Browser teardown closes its owned event service:

browser.events.close()

class ddp_utils.browser.facade.advanced.BrowserExpect(browser: Any)

Bases: object

Expose assertion-style wrappers around BrowserWait.

Examples

Assert semantic state without backend-specific assertions:

browser.expect.visible("button[type=submit]", timeout=10)

exists(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that an element becomes attached.

Parameters

Name	Type	Description
*args	Any	One element, selector, tag name, mapping, or resolver.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	The element does not appear before the deadline.

Examples

browser.expect.exists("button", text="Search").

absent(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that an element becomes detached.

Parameters

Name	Type	Description
*args	Any	One element query.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	The element remains attached.

Examples

browser.expect.absent("div", attrs={"class": "spinner"}).

visible(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that an element becomes visible.

Parameters

Name	Type	Description
*args	Any	One element query.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	Visibility is not reached.

Examples

browser.expect.visible("button", text="Search").

hidden(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that an element becomes hidden or absent.

Parameters

Name	Type	Description
*args	Any	One element query.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	The element remains visible.

Examples

browser.expect.hidden(".overlay").

enabled(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that an element becomes enabled.

Parameters

Name	Type	Description
*args	Any	One element query.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	Enabled state is not reached.

Examples

browser.expect.enabled("button", text="Continue").

disabled(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that an element becomes disabled.

Parameters

Name	Type	Description
*args	Any	One element query.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	Disabled state is not reached.

Examples

browser.expect.disabled("button", text="Submit").

editable(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that an element becomes editable.

Parameters

Name	Type	Description
*args	Any	One element query.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	Editable state is not reached.

Examples

browser.expect.editable("input", attrs={"name": "last_name"}).

checked(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that a checkbox or radio becomes checked.

Parameters

Name	Type	Description
*args	Any	One element query.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	Checked state is not reached.

Examples

browser.expect.checked("input", attrs={"name": "consent"}).

selected(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that an option becomes selected.

Parameters

Name	Type	Description
*args	Any	One element query.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Structured search options used with a tag name.

Raises

Exception	Description
AssertionError	Selected state is not reached.

Examples

browser.expect.selected("option", text="Fulton").

text(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert element text using an explicit match mode.

Parameters

Name	Type	Description
*args	Any	Element query and expected text.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Match mode and case options.

Raises

Exception	Description
AssertionError	Text does not match before the deadline.

Examples

browser.expect.text("h1", "Results", match="contains").

value(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert an input value.

Parameters

Name	Type	Description
*args	Any	Element query and expected value.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Match mode and case options.

Raises

Exception	Description
AssertionError	Value does not match before the deadline.

Examples

browser.expect.value("input", "Fulton").

attribute(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert an element attribute.

Parameters

Name	Type	Description
*args	Any	Element query, attribute name, and expected value.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Match options.

Raises

Exception	Description
AssertionError	Attribute does not match before the deadline.

Examples

browser.expect.attribute("a", "href", "/", match="starts_with").

property(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert a DOM property.

Parameters

Name	Type	Description
*args	Any	Element query, property name, and expected value.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Property comparison options.

Raises

Exception	Description
AssertionError	Property does not match before the deadline.

Examples

browser.expect.property("input", "readOnly", True).

css(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert a computed CSS value.

Parameters

Name	Type	Description
*args	Any	Element query, CSS property, and expected value.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Match options.

Raises

Exception	Description
AssertionError	CSS value does not match before the deadline.

Examples

browser.expect.css("div", "display", "block").

count(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert the number of matching elements.

Parameters

Name	Type	Description
*args	Any	Element query and expected count.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Count-wait options.

Raises

Exception	Description
AssertionError	Count does not match before the deadline.

Examples

browser.expect.count("tr.result", 10).

url(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert the active page URL.

Parameters

Name	Type	Description
*args	Any	Expected URL value.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Match mode and case options.

Raises

Exception	Description
AssertionError	URL does not match before the deadline.

Examples

browser.expect.url("/results", match="ends_with").

title(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert the active page title.

Parameters

Name	Type	Description
*args	Any	Expected title value.
timeout	float | None	Optional deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Match mode and case options.

Raises

Exception	Description
AssertionError	Title does not match before the deadline.

Examples

browser.expect.title("Results").

no_js_errors(*args: Any, timeout: float | None = None, message: str | None = None, **kwargs: Any) → None

Assert that no JavaScript errors were captured.

Parameters

Name	Type	Description
*args	Any	Reserved for forward-compatible filters.
timeout	float | None	Optional observation deadline in seconds.
message	str | None	Optional assertion message.
**kwargs	Any	Reserved for forward-compatible filters.

Raises

Exception	Description
AssertionError	One or more JavaScript errors were captured.

Examples

browser.expect.no_js_errors().

class ddp_utils.browser.facade.advanced.BrowserLogs(browser: Any)

Bases: object

Collect normalized console, page-error, browser, and performance logs.

Examples

Inspect JavaScript errors after a workflow:

errors = browser.logs.javascript_errors()

console(**filters: Any) → list[ConsoleEntry]

Return console entries matching optional fields.

Parameters

Name	Type	Description
**filters	Any	level, text, or predicate.

Returns

Type	Description
list[ConsoleEntry]	Matching entries.

Examples

errors = browser.logs.console(level="error").

javascript_errors() → list[PageError]

Return uncaught JavaScript errors.

Returns

Type	Description
list[PageError]	Page errors in observation order.

Examples

assert not browser.logs.javascript_errors().

browser(**filters: Any) → list[LogEntry]

Return WebDriver browser logs.

Parameters

Name	Type	Description
**filters	Any	Optional level, text, or predicate filters.

Returns

Type	Description
list[LogEntry]	Matching normalized entries.

Examples

entries = browser.logs.browser(level="SEVERE").

performance(**filters: Any) → CapabilityResult[Any]

Return WebDriver performance log entries when enabled.

Parameters

Name	Type	Description
**filters	Any	Optional text or predicate filters.

Returns

Type	Description
CapabilityResult[Any]	Structured result containing normalized entries.

Examples

result = browser.logs.performance().

clear() → None

Clear collected facade logs.

Examples

browser.logs.clear().

on_console(callback: Callable[[ConsoleEntry], Any]) → BrowserSubscription

Subscribe to console entries.

Parameters

Name	Type	Description
callback	Callable[[ConsoleEntry], Any]	Entry callback.

Returns

Type	Description
BrowserSubscription	Removable subscription.

Examples

sub = browser.logs.on_console(print).

on_error(callback: Callable[[PageError], Any]) → BrowserSubscription

Subscribe to page errors.

Parameters

Name	Type	Description
callback	Callable[[PageError], Any]	Error callback.

Returns

Type	Description
BrowserSubscription	Removable subscription.

Examples

sub = browser.logs.on_error(print).

class ddp_utils.browser.facade.advanced.BrowserTracing(browser: Any)

Bases: object

Control provider tracing with honest capability results.

Examples

Save a Playwright trace around one workflow:

browser.tracing.start(screenshots=True)
browser.tracing.stop("trace.zip")

property available: bool

Return whether provider tracing is available.

Returns

Support state.

Examples

if browser.tracing.available: ....

start(**options: Any) → CapabilityResult[Any]

Start tracing.

Parameters

Name	Type	Description
**options	Any	Provider trace options.

Returns

Type	Description
CapabilityResult[Any]	Structured result.

Examples

browser.tracing.start(screenshots=True).

start_chunk(**options: Any) → CapabilityResult[Any]

Start a trace chunk.

Parameters

Name	Type	Description
**options	Any	Provider chunk options.

Returns

Type	Description
CapabilityResult[Any]	Structured result.

Examples

browser.tracing.start_chunk(title="search").

stop_chunk(path: str | Path | None = None) → CapabilityResult[Any]

Stop and optionally save the active chunk.

Parameters

Name	Type	Description
path	str | Path | None	Optional trace destination.

Returns

Type	Description
CapabilityResult[Any]	Structured result.

Examples

browser.tracing.stop_chunk("search.zip").

stop(path: str | Path | None = None) → CapabilityResult[Any]

Stop tracing and optionally save it.

Parameters

Name	Type	Description
path	str | Path | None	Optional trace destination.

Returns

Type	Description
CapabilityResult[Any]	Structured result.

Examples

browser.tracing.stop("trace.zip").

class ddp_utils.browser.facade.advanced.CapabilityInfo(name: str, supported: bool, backend: str, reason: str | None = None)

Bases: object

Describe one runtime browser capability.

Parameters

Name	Type	Description
name	str	Stable capability name.
supported	bool	Whether it is available.
backend	str	Concrete backend name.
reason	str | None	Unsupported explanation.

Examples

info = browser.capabilities.get("cdp").

class ddp_utils.browser.facade.advanced.ConsoleEntry(level: str, text: str, native: Any = None)

Bases: object

Represent one normalized console message.

Parameters

Name	Type	Description
level	str	Console level.
text	str	Rendered message text.
native	Any	Provider-native message.

Examples

errors = browser.logs.console(level="error").

class ddp_utils.browser.facade.advanced.Geolocation(latitude: float, longitude: float, accuracy: float = 0.0)

Bases: object

Represent a geographic coordinate.

Parameters

Name	Type	Description
latitude	float	Latitude in degrees.
longitude	float	Longitude in degrees.
accuracy	float	Accuracy radius in metres.

Examples

browser.emulation.geolocation(Geolocation(41.7, 44.8)).

class ddp_utils.browser.facade.advanced.LogEntry(level: str, message: str, timestamp: float | None = None, native: Any = None)

Bases: object

Represent one browser-driver log entry.

Parameters

Name	Type	Description
level	str	Log severity.
message	str	Log message.
timestamp	float | None	Provider timestamp.
native	Any	Original mapping.

Examples

entries = browser.logs.browser(level="SEVERE").

class ddp_utils.browser.facade.advanced.PageError(message: str, native: Any = None)

Bases: object

Represent one uncaught page error.

Parameters

Name	Type	Description
message	str	Error message.
native	Any	Provider-native error.

Examples

errors = browser.logs.javascript_errors().

class ddp_utils.browser.facade.advanced.Viewport(width: int, height: int)

Bases: object

Represent viewport dimensions.

Parameters

Name	Type	Description
width	int	Width in CSS pixels.
height	int	Height in CSS pixels.

Examples

browser.emulation.viewport(1440, 900).