ddp_utils.browser.facade.network

import ddp_utils.browser.facade.network

Backend-neutral network observation and request-control facade.

class ddp_utils.browser.facade.network.BrowserNetwork(browser: Browser)

Bases: object

Observe network traffic and expose honest interception capabilities.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Start collection and wait for one API response:

browser.network.start()
browser.go(url)
record = browser.network.wait_response("*/api/search*")

Bind an initially inactive network journal to one browser.

Parameters

Name	Type	Description
browser	Browser	Owning browser facade.

Examples

Browser creates this service once:

network = BrowserNetwork(browser)

property available: bool

Return whether the backend supports network observation.

Returns

Declared network capability.

Examples

Guard optional traffic capture:

if browser.network.available:
    browser.network.start()

property active: bool

Return whether collection is active.

Returns

True after start() and before stop().

Examples

Avoid duplicate start operations:

if not browser.network.active:
    browser.network.start()

records(**filters: Any) → list[NetworkRecord]

Return captured records matching optional fields.

Parameters

Name	Type	Description
**filters	Any	URL/pattern, method, status, resource type, MIME type, failed state, or predicate criteria.

Returns

Type	Description
list[NetworkRecord]	Detached records list in observation order.

Examples

Preserve the current journal:

snapshot = browser.network.records(status=200)

requests(**filters: Any) → list[NetworkRecord]

Return observed requests matching optional fields.

Parameters

Name	Type	Description
**filters	Any	Criteria accepted by records().

Returns

Type	Description
list[NetworkRecord]	Same normalized records as records.

Examples

Count outgoing requests:

count = len(browser.network.requests(method="POST"))

responses(**filters: Any) → list[NetworkRecord]

Return completed responses matching optional fields.

Parameters

Name	Type	Description
**filters	Any	Criteria accepted by records().

Returns

Type	Description
list[NetworkRecord]	Completed response records.

Examples

Inspect all HTTP statuses:

statuses = [item.status for item in browser.network.responses()]

start() → BrowserNetwork

Start network observation idempotently.

Returns

Type	Description
BrowserNetwork	This service for fluent use.

Raises

Exception	Description
UnsupportedCapabilityError	Network observation is unavailable.
BrowserError	Provider listener setup fails.

Examples

Start before navigation:

browser.network.start().clear()

stop() → None

Stop observation while preserving collected records.

Examples

Freeze the journal before exporting it:

browser.network.stop()

clear() → BrowserNetwork

Discard collected records and return this service.

Returns

Type	Description
BrowserNetwork	This service.

Examples

Begin a clean transaction capture:

browser.network.clear()

poll() → int

Import pending Selenium performance-log events.

Returns

Type	Description
int	Number of provider log entries consumed. Playwright returns zero because its events are delivered synchronously.

Examples

Pull events after a long Selenium command:

browser.network.poll()

find(**filters: Any) → NetworkRecord | None

Return the first captured record matching optional fields.

Parameters

Name	Type	Description
**filters	Any	Criteria accepted by records().

Returns

Type	Description
NetworkRecord | None	First matching record, otherwise None.

Examples

Find successful JSON API calls:

record = browser.network.find(url="*/api/*", status=200)

wait_request(*, timeout: float, **filters: Any) → NetworkRecord

Wait for a matching request.

Parameters

Name	Type	Description
timeout	float	Deadline in seconds.
**filters	Any	Criteria accepted by requests().

Returns

Type	Description
NetworkRecord	First matching request.

Raises

Exception	Description
WaitTimeoutError	No request matches before the deadline.

Examples

Wait for a search submission:

request = browser.network.wait_request(url="*/search*", timeout=20)

wait_response(*, timeout: float, **filters: Any) → NetworkRecord

Wait for a matching completed response.

Parameters

Name	Type	Description
timeout	float	Deadline in seconds.
**filters	Any	Criteria accepted by responses().

Returns

Type	Description
NetworkRecord	First matching response.

Raises

Exception	Description
WaitTimeoutError	No response matches before the deadline.

Examples

Wait for the result API:

response = browser.network.wait_response(url="*/results*", timeout=20)

json_responses(**filters: Any) → list[Any]

Decode matching JSON response bodies.

Parameters

Name	Type	Description
**filters	Any	Criteria accepted by responses().

Returns

Type	Description
list[Any]	Successfully decoded JSON values.

Examples

Inspect all API JSON responses:

api = browser.network.json_responses(url="*/api/*")

body(record: NetworkRecord, *, decode: bool = True) → Any

Read a response body while its provider handle remains valid.

Parameters

Name	Type	Description
record	NetworkRecord	Response record.
decode	bool	Decode JSON and text MIME types when true.

Returns

Type	Description
Any	Bytes, decoded text/JSON, or structured unsupported result.

Examples

Decode a captured JSON response:

payload = browser.network.body(record)

headers(record: NetworkRecord) → dict[str, str]

Return normalized request or response headers.

Parameters

Name	Type	Description
record	NetworkRecord	Network record.

Returns

Type	Description
dict[str, str]	Detached lowercase-key header mapping.

Examples

Read response content type:

content_type = browser.network.headers(record).get("content-type")

route(pattern: str, handler: Callable[[Any], Any], *, times: int | None = None) → CapabilityResult[str]

Install Playwright request interception for a URL pattern.

Parameters

Name	Type	Description
pattern	str	Playwright URL glob.
handler	Callable[[Any], Any]	Native route callback.
times	int | None	Optional maximum number of routed requests.

Returns

Type	Description
CapabilityResult[str]	Installed pattern or soft unsupported result.

Examples

Fulfil a deterministic test endpoint:

browser.network.route("**/health", handler)

unroute(pattern: str, handler: Callable[[Any], Any] | None = None) → None

Remove a previously installed Playwright route.

Parameters

Name	Type	Description
pattern	str	Original URL glob.
handler	Callable[[Any], Any] | None	Original callback, or the tracked callback when omitted.

Examples

Restore ordinary requests:

browser.network.unroute("**/health")

abort(route: Any, *, reason: str = 'failed') → CapabilityResult[Any]

Abort a native Playwright route.

Parameters

Name	Type	Description
route	Any	Native route supplied to a route handler.
reason	str	Playwright abort reason.

Returns

Type	Description
CapabilityResult[Any]	Structured successful operation result.

Examples

Block one request inside a handler:

browser.network.abort(route, reason="blockedbyclient")

static continue_request(route: Any, **overrides: Any) → None

Continue a native route with optional overrides.

Parameters

Name	Type	Description
route	Any	Native route supplied to a handler.
**overrides	Any	URL, method, headers, or post data overrides.

Examples

Add a request header:

browser.network.continue_request(route, headers=headers)

fulfill(route: Any, *, status: int = 200, headers: Mapping[str, str] | None = None, body: str | bytes | None = None, json: Any = None) → CapabilityResult[Any]

Fulfil a native route with a synthetic response.

Parameters

Name	Type	Description
route	Any	Native route supplied to a handler.
status	int	HTTP status code.
headers	Mapping[str, str] | None	Optional response headers.
body	str | bytes | None	Optional response body.
json	Any	Optional JSON-compatible payload.

Returns

Type	Description
CapabilityResult[Any]	Structured successful operation result.

Examples

Return a JSON result:

browser.network.fulfill(route, json={"ok": True})

block(patterns: str | Iterable[str]) → CapabilityResult[tuple[str, ...]]

Block matching requests through Playwright routing.

Parameters

Name	Type	Description
patterns	str | Iterable[str]	One URL glob or iterable of globs.

Returns

Type	Description
CapabilityResult[tuple[str, …]]	Installed block patterns or soft unsupported result.

Examples

Block analytics during a deterministic test:

browser.network.block("**/analytics/**")

set_headers(headers: Mapping[str, str]) → None

Set additional HTTP headers for future requests.

Parameters

Name	Type	Description
headers	Mapping[str, str]	Header mapping.

Raises

Exception	Description
UnsupportedCapabilityError	Backend has no supported transport.

Examples

Add a trace correlation header:

browser.network.set_headers({"X-Run": guid})

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

Enable or disable offline emulation.

Parameters

Name	Type	Description
enabled	bool	Desired offline state.

Returns

Type	Description
CapabilityResult[Any]	Structured operation result.

Examples

Test a disconnected error state:

browser.network.set_offline(True)

throttle(*, latency: float = 0, download: float = -1, upload: float = -1, offline: bool = False) → CapabilityResult[Any]

Apply Chromium network throttling through CDP.

Parameters

Name	Type	Description
latency	float	Added latency in milliseconds.
download	float	Download bytes per second.
upload	float	Upload bytes per second.
offline	bool	Whether to disable networking.

Returns

Type	Description
CapabilityResult[Any]	Structured operation result.

Raises

Exception	Description
UnsupportedCapabilityError	CDP is unavailable.

Examples

Emulate a slow connection:

browser.network.throttle(latency=100, download=50000, upload=20000)

clear_throttle() → None

Restore Chromium network emulation to unrestricted throughput.

Examples

Clear a previous throttle:

browser.network.clear_throttle()

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

Subscribe to normalized request, response, or failure events.

Parameters

Name	Type	Description
event	str	Normalized event name.
callback	Callable[[NetworkRecord], Any]	Callable receiving a NetworkRecord.

Returns

Type	Description
BrowserSubscription	Removable subscription.

Raises

Exception	Description
BrowserError	If the event is not "request", "response" or "failure".

Examples

Observe every response:

subscription = browser.network.on("response", print)

off(subscription: BrowserSubscription) → None

Remove a normalized network subscription idempotently.

Parameters

Name	Type	Description
subscription	BrowserSubscription	Value returned by on().

Examples

Stop a temporary listener:

browser.network.off(subscription)

export_har(path: str) → str

Export collected records as a compact HAR-compatible JSON file.

Parameters

Name	Type	Description
path	str	Destination path.

Returns

Type	Description
str	Destination path.

Examples

Save captured metadata for diagnostics:

browser.network.export_har("run.har")

close() → None

Remove listeners and routes without discarding diagnostics.

Examples

Browser invokes this during lifecycle cleanup:

browser.network.close()

class ddp_utils.browser.facade.network.NetworkRecord(request_id: str, url: str, method: str = 'GET', request_headers: dict[str, str]=<factory>, request_body: Any = None, status: int | None = None, response_headers: dict[str, str]=<factory>, mime_type: str | None = None, resource_type: str | None = None, started_at: float = <factory>, finished_at: float | None = None, failed: bool = False, failure: str | None = None, native_request: Any = None, native_response: Any = None)

Bases: object

Represent one normalized request/response lifecycle.

Parameters

Name	Type	Description
request_id	str	Provider request identifier.
url	str	Requested URL.
method	str	HTTP method.
request_headers	dict[str, str]	Outgoing headers.
request_body	Any	Optional outgoing payload.
status	int | None	HTTP response status when received.
response_headers	dict[str, str]	Incoming headers.
mime_type	str | None	Response MIME type when known.
resource_type	str | None	Provider resource type.
started_at	float	Unix timestamp when observed.
finished_at	float | None	Unix timestamp when completed.
failed	bool	Whether the request failed.
failure	str | None	Provider failure text.
native_request	Any	Native request escape hatch.
native_response	Any	Native response escape hatch.

Examples

Inspect a JSON response without backend branching:

print(record.status, record.url)