ddp_utils.browser.results

import ddp_utils.browser.results

Structured success, action, and capability results.

class ddp_utils.browser.results.CapabilityResult(supported: bool, capability: str, backend: str, value: T | None = None, reason: str | None = None, details: dict[str, ~typing.Any]=<factory>)

Bases: Generic[T]

Represent a supported value or a precise unsupported capability.

Parameters

Name	Type	Description
supported	bool	Whether the capability is available.
capability	str	Stable capability identifier.
backend	str	Concrete backend identifier.
value	T | None	Capability value when supported.
reason	str | None	Explanation when unsupported.
details	dict[str, Any]	Additional structured diagnostics.

Examples

Return a soft negative CDP result for native process mode:

result = CapabilityResult.unsupported(
    "cdp",
    backend="native",
    reason="Attach through an automation technology first.",
)

classmethod available(capability: str, *, backend: str, value: T, details: dict[str, Any] | None = None) → CapabilityResult[T]

Create a successful capability result.

Parameters

Name	Type	Description
capability	str	Stable capability identifier.
backend	str	Concrete backend identifier.
value	T	Available capability value.
details	dict[str, Any] | None	Optional structured diagnostics.

Returns

Type	Description
CapabilityResult[T]	Supported capability result containing value.

Examples

Publish an active CDP facade:

result = CapabilityResult.available(
    "cdp", backend="playwright-chromium", value=cdp
)

classmethod unsupported(capability: str, *, backend: str, reason: str, details: dict[str, Any] | None = None) → CapabilityResult[T]

Create a structured unsupported-capability result.

Parameters

Name	Type	Description
capability	str	Stable capability identifier.
backend	str	Concrete backend identifier.
reason	str	Human-readable explanation.
details	dict[str, Any] | None	Optional structured diagnostics.

Returns

Type	Description
CapabilityResult[T]	Unsupported capability result with no value.

Examples

Explain why a native session has no DOM access:

result = CapabilityResult.unsupported(
    "dom",
    backend="native",
    reason="Native process mode is not attached.",
)

require() → T

Return the value or raise the corresponding typed capability error.

Returns

Type	Description
T	The supported capability value.

Raises

Exception	Description
UnsupportedCapabilityError	The capability is unsupported.

Examples

Require a network facade only where it is available:

network = browser.capabilities.get("network").require()

class ddp_utils.browser.results.ActionResult(success: bool, value: T | None = None, changed: bool = False, verified: bool = False, error: BrowserError | None = None, details: dict[str, ~typing.Any]=<factory>)

Bases: Generic[T]

Represent an action and its verified postcondition.

Parameters

Name	Type	Description
success	bool	Whether the documented action completed successfully.
value	T | None	Optional action result value.
changed	bool	Whether the operation changed observable state.
verified	bool	Whether the postcondition was verified.
error	BrowserError | None	Typed failure captured for non-required operation mode.
details	dict[str, Any]	Structured evidence and backend diagnostics.

Examples

Report a verified element visibility change:

result = ActionResult(
    success=True,
    value=element,
    changed=True,
    verified=True,
)

require() → T | None

Return the action value or raise its captured failure.

Returns

Type	Description
T | None	The optional successful action value.

Raises

Exception	Description
BrowserError	The action failed. The captured typed error is re-raised when present; otherwise a generic browser error is created.

Examples

Convert a soft action result into required behavior:

element = browser.human.click(button).require()

class ddp_utils.browser.results.CollectionActionResult(items: tuple[ActionResult[T], ...])

Bases: Generic[T]

Aggregate ordered per-element action results.

Parameters

Name	Type	Description
items	tuple[ActionResult[T], ...]	Ordered results corresponding to the source collection.

Examples

Verify that every collection element was hidden:

result = collection.hide()
assert result.success

property success: bool

Return whether every collection action succeeded.

Returns

True when every item succeeded, including an empty collection.

Examples

Branch on the aggregate result:

if not result.success:
    inspect(result.failures)

property failures: tuple[ActionResult[T], ...]

Return only failed item results in source order.

Returns

Tuple containing every failed action result.

Examples

Log per-element failures without losing successful results:

for failure in result.failures:
    log(failure.error)