Comandos de Rede (Network)

Os comandos de rede fornecem controle abrangente sobre requisições de rede, respostas e comportamento de rede do navegador.

Visão Geral

O módulo de comandos de rede habilita a interceptação de requisições, modificação de respostas, gerenciamento de cookies e capacidades de monitoramento de rede.

pydoll.commands.network_commands

NetworkCommands

Implementation of Chrome DevTools Protocol for the Network domain.

This class provides commands for monitoring and manipulating network activities, enabling detailed inspection and control over HTTP requests and responses. The Network domain exposes comprehensive network-related information including: - Request/response headers and bodies - Resource timing and caching behavior - Cookie management and security details - Network conditions emulation - Traffic interception and modification

The commands allow developers to analyze performance, debug network issues, and test application behavior under various network conditions.

clear_browser_cache `staticmethod`

clear_browser_cache()

Clears browser cache storage.

This command is essential for testing cache behavior and ensuring fresh resource loading. It affects all cached resources including: - CSS/JavaScript files - Images and media assets - API response caching

Use cases: - Testing cache invalidation strategies - Reproducing issues with stale content - Performance benchmarking without cache influence

RETURNS	DESCRIPTION
`Command`	CDP command to clear the entire browser cache TYPE: `ClearBrowserCacheCommand`

clear_browser_cookies `staticmethod`

clear_browser_cookies()

Command to clear all cookies stored in the browser.

This can be beneficial for testing scenarios where you need to simulate a fresh user session without any previously stored cookies that might affect the application's behavior.

RETURNS	DESCRIPTION
`ClearBrowserCookiesCommand`	Command[Response]: A command to clear all cookies in the browser.

delete_cookies `staticmethod`

delete_cookies(name, url=None, domain=None, path=None, partition_key=None)

Deletes browser cookies with matching criteria.

Provides granular control over cookie removal through multiple parameters: - Delete by name only (affects all matching cookies) - Scope deletion using URL, domain, or path - Handle partitioned cookies for privacy-aware applications

PARAMETER	DESCRIPTION
`name`	Name of the cookies to remove (required) TYPE: `str`
`url`	Delete cookies for specific URL (domain/path must match) TYPE: `Optional[str]` DEFAULT: `None`
`domain`	Exact domain for cookie deletion TYPE: `Optional[str]` DEFAULT: `None`
`path`	Exact path for cookie deletion TYPE: `Optional[str]` DEFAULT: `None`
`partition_key`	Partition key attributes for cookie isolation TYPE: `Optional[CookiePartitionKey]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to execute selective cookie deletion TYPE: `ClearCookiesCommand`

disable `staticmethod`

disable()

Stops network monitoring and event reporting.

Preserves network state but stops: - Request/response events - WebSocket message tracking - Loading progress notifications

Use when: - Reducing overhead during non-network operations - Pausing monitoring temporarily - Finalizing network-related tests

RETURNS	DESCRIPTION
`Command`	CDP command to disable network monitoring TYPE: `DisableCommand`

enable `staticmethod`

enable(max_total_buffer_size=None, max_resource_buffer_size=None, max_post_data_size=None)

Enables network monitoring with configurable buffers.

PARAMETER	DESCRIPTION
`max_total_buffer_size`	Total memory buffer for network data (bytes) TYPE: `Optional[int]` DEFAULT: `None`
`max_resource_buffer_size`	Per-resource buffer limit (bytes) TYPE: `Optional[int]` DEFAULT: `None`
`max_post_data_size`	Maximum POST payload to capture (bytes) TYPE: `Optional[int]` DEFAULT: `None`

Recommended settings: - Increase buffers for long-running sessions - Adjust post size for API testing - Monitor memory usage with large buffers

RETURNS	DESCRIPTION
`Command`	CDP command to enable network monitoring TYPE: `EnableCommand`

get_cookies `staticmethod`

get_cookies(urls=None)

Retrieves cookies matching specified URLs.

PARAMETER	DESCRIPTION
`urls`	list of URLs to scope cookie retrieval TYPE: `Optional[list[str]]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command returning cookie details including: - Name, value, and attributes - Security and scope parameters - Expiration and size information TYPE: `GetCookiesCommand`

Usage notes: - Empty URL list returns all cookies - Includes HTTP-only and secure cookies - Shows partitioned cookie status

get_request_post_data `staticmethod`

get_request_post_data(request_id)

Retrieves POST data from a specific network request.

Essential for: - Form submission analysis - API request debugging - File upload monitoring - Security testing

PARAMETER	DESCRIPTION
`request_id`	Unique identifier for the network request TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command that returns: - Raw POST data content - Multipart form data (excluding file contents) - Content encoding information TYPE: `GetRequestPostDataCommand`

Note: Large POST bodies may be truncated based on buffer settings

get_response_body `staticmethod`

get_response_body(request_id)

Retrieves the full content of a network response.

Supports various content types: - Text-based resources (HTML, CSS, JSON) - Base64-encoded binary content (images, media) - Gzip/deflate compressed responses

PARAMETER	DESCRIPTION
`request_id`	Unique network request identifier TYPE: `str`

Important considerations: - Response must be available in browser memory - Large responses may require streaming approaches - Sensitive data should be handled securely

RETURNS	DESCRIPTION
`Command`	CDP command returning response body and encoding details TYPE: `GetResponseBodyCommand`

set_cache_disabled `staticmethod`

set_cache_disabled(cache_disabled)

Controls browser's cache mechanism.

Use cases: - Testing resource update behavior - Forcing fresh content loading - Performance impact analysis - Cache-busting scenarios

PARAMETER	DESCRIPTION
`cache_disabled`	True to disable caching, False to enable TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	CDP command to modify cache behavior TYPE: `SetCacheDisabledCommand`

Note: Affects all requests until re-enabled

set_cookie `staticmethod`

set_cookie(name, value, url=None, domain=None, path=None, secure=None, http_only=None, same_site=None, expires=None, priority=None, same_party=None, source_scheme=None, source_port=None, partition_key=None)

Creates or updates a cookie with specified attributes.

Comprehensive cookie control supporting: - Session and persistent cookies - Security attributes (Secure, HttpOnly) - SameSite policies - Cookie partitioning - Priority levels

PARAMETER	DESCRIPTION
`name`	Cookie name TYPE: `str`
`value`	Cookie value TYPE: `str`
`url`	Target URL for the cookie TYPE: `Optional[str]` DEFAULT: `None`
`domain`	Cookie domain scope TYPE: `Optional[str]` DEFAULT: `None`
`path`	Cookie path scope TYPE: `Optional[str]` DEFAULT: `None`
`secure`	Require HTTPS TYPE: `Optional[bool]` DEFAULT: `None`
`http_only`	Prevent JavaScript access TYPE: `Optional[bool]` DEFAULT: `None`
`same_site`	Cross-site access policy TYPE: `Optional[CookieSameSite]` DEFAULT: `None`
`expires`	Expiration timestamp TYPE: `Optional[float]` DEFAULT: `None`
`priority`	Cookie priority level TYPE: `Optional[CookiePriority]` DEFAULT: `None`
`same_party`	First-Party Sets flag TYPE: `Optional[bool]` DEFAULT: `None`
`source_scheme`	Cookie source context TYPE: `Optional[CookieSourceScheme]` DEFAULT: `None`
`source_port`	Source port restriction TYPE: `Optional[int]` DEFAULT: `None`
`partition_key`	Storage partition key TYPE: `Optional[CookiePartitionKey]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command that returns success status TYPE: `SetCookieCommand`

Security considerations: - Use secure flag for sensitive data - Consider SameSite policies - Be aware of cross-site implications

set_cookies `staticmethod`

set_cookies(cookies)

Sets multiple cookies in a single operation.

Efficient for: - Batch cookie operations - Session state restoration - Testing multiple authentication states - Cross-domain cookie setup

PARAMETER	DESCRIPTION
`cookies`	list of cookie parameters including name, value, and attributes TYPE: `list[SetCookieParams]`

RETURNS	DESCRIPTION
`Command`	CDP command for bulk cookie setting TYPE: `SetCookiesCommand`

Performance note: - More efficient than multiple set_cookie calls - Consider memory impact with large batches

set_extra_http_headers `staticmethod`

set_extra_http_headers(headers)

Applies custom HTTP headers to all subsequent requests.

Enables advanced scenarios: - A/B testing with custom headers - Authentication bypass for testing - Content negotiation simulations - Security header validation

PARAMETER	DESCRIPTION
`headers`	list of key-value header pairs TYPE: `list[HeaderEntry]`

Security notes: - Headers are applied browser-wide - Sensitive headers (e.g., Authorization) persist until cleared - Use with caution in shared environments

RETURNS	DESCRIPTION
`Command`	CDP command to set global HTTP headers TYPE: `SetExtraHTTPHeadersCommand`

set_useragent_override `staticmethod`

set_useragent_override(user_agent, accept_language=None, platform=None, user_agent_metadata=None)

Overrides the browser's User-Agent string.

Use cases: - Device/browser simulation - Compatibility testing - Content negotiation - Bot detection bypass

PARAMETER	DESCRIPTION
`user_agent`	Complete User-Agent string TYPE: `str`
`accept_language`	Language preference header TYPE: `Optional[str]` DEFAULT: `None`
`platform`	Platform identifier TYPE: `Optional[str]` DEFAULT: `None`
`user_agent_metadata`	Detailed UA metadata TYPE: `Optional[UserAgentMetadata]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to override user agent TYPE: `SetUserAgentOverrideCommand`

Testing considerations: - Affects all subsequent requests - May impact server-side behavior - Consider mobile/desktop differences

clear_accepted_encodings_override `staticmethod`

clear_accepted_encodings_override()

Restores default content encoding acceptance.

Effects: - Resets compression preferences - Restores default Accept-Encoding header - Allows server-chosen encoding

Use when: - Testing encoding fallbacks - Debugging compression issues - Resetting after encoding tests

RETURNS	DESCRIPTION
`Command`	CDP command to clear encoding overrides TYPE: `ClearAcceptedEncodingsOverrideCommand`

enable_reporting_api `staticmethod`

enable_reporting_api(enabled)

Controls the Reporting API functionality.

Features: - Network error reporting - Deprecation notices - CSP violation reports - CORS issues

PARAMETER	DESCRIPTION
`enabled`	True to enable, False to disable TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	CDP command to configure Reporting API TYPE: `EnableReportingApiCommand`

Note: Requires browser support for Reporting API

search_in_response_body `staticmethod`

search_in_response_body(request_id, query, case_sensitive=False, is_regex=False)

Searches for content within response bodies.

Powerful for: - Content verification - Security scanning - Data extraction - Response validation

PARAMETER	DESCRIPTION
`request_id`	Target response identifier TYPE: `str`
`query`	Search string or pattern TYPE: `str`
`case_sensitive`	Match case sensitivity TYPE: `bool` DEFAULT: `False`
`is_regex`	Use regular expression matching TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Command`	CDP command returning match results TYPE: `SearchInResponseBodyCommand`

Performance tip: - Use specific queries for large responses - Consider regex complexity

set_blocked_urls `staticmethod`

set_blocked_urls(urls)

Blocks specified URLs from loading.

Key features: - Pattern-based URL blocking - Resource type filtering - Network request prevention - Error simulation

PARAMETER	DESCRIPTION
`urls`	list of URL patterns to block Supports wildcards and pattern matching TYPE: `list[str]`

RETURNS	DESCRIPTION
`Command`	CDP command to set URL blocking rules TYPE: `SetBlockedURLsCommand`

Common applications: - Ad/tracker blocking simulation - Resource loading control - Error handling testing - Network isolation testing

set_bypass_service_worker `staticmethod`

set_bypass_service_worker(bypass)

Controls Service Worker interception of network requests.

Use cases: - Testing direct network behavior - Bypassing offline functionality - Debug caching issues - Performance comparison

PARAMETER	DESCRIPTION
`bypass`	True to skip Service Worker, False to allow TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	CDP command to configure Service Worker behavior TYPE: `SetBypassServiceWorkerCommand`

Impact: - Affects offline capabilities - Changes caching behavior - Modifies push notifications

get_certificate `staticmethod`

get_certificate(origin)

Retrieves SSL/TLS certificate information for a domain.

Provides: - Certificate chain details - Validation status - Expiration information - Issuer details

PARAMETER	DESCRIPTION
`origin`	Target domain for certificate inspection TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command returning certificate data TYPE: `GetCertificateCommand`

Security applications: - Certificate validation - SSL/TLS verification - Security assessment - Chain of trust verification

get_response_body_for_interception `staticmethod`

get_response_body_for_interception(interception_id)

Retrieves response body from an intercepted request.

Essential for: - Response modification - Content inspection - Security testing - API response validation

PARAMETER	DESCRIPTION
`interception_id`	Identifier for intercepted request TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command providing intercepted response content TYPE: `GetResponseBodyForInterceptionCommand`

Note: - Must be used with interception enabled - Supports streaming responses - Handles various content types

set_accepted_encodings `staticmethod`

set_accepted_encodings(encodings)

Specifies accepted content encodings for requests.

Controls: - Compression algorithms - Transfer encoding - Content optimization

PARAMETER	DESCRIPTION
`encodings`	list of accepted encoding methods (gzip, deflate, br, etc.) TYPE: `list[ContentEncoding]`

RETURNS	DESCRIPTION
`Command`	CDP command to set encoding preferences TYPE: `SetAcceptedEncodingsCommand`

Performance implications: - Affects bandwidth usage - Impacts response time - Changes server behavior

set_attach_debug_stack `staticmethod`

set_attach_debug_stack(enabled)

Enables/disables debug stack attachment to requests.

Debug features: - Stack trace collection - Request origin tracking - Initialization context - Call site identification

PARAMETER	DESCRIPTION
`enabled`	True to attach debug info, False to disable TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	CDP command to configure debug stack attachment TYPE: `SetAttachDebugStackCommand`

Performance note: - May impact performance when enabled - Useful for development/debugging - Consider memory usage

set_cookie_controls `staticmethod`

set_cookie_controls(enable_third_party_cookie_restriction, disable_third_party_cookie_metadata=None, disable_third_party_cookie_heuristics=None)

Configures third-party cookie handling policies.

Privacy features: - Cookie access control - Third-party restrictions - Tracking prevention - Privacy policy enforcement

PARAMETER	DESCRIPTION
`enable_third_party_cookie_restriction`	Enable restrictions TYPE: `bool`
`disable_third_party_cookie_metadata`	Skip metadata checks TYPE: `Optional[bool]` DEFAULT: `None`
`disable_third_party_cookie_heuristics`	Disable detection logic TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to set cookie control policies TYPE: `SetCookieControlsCommand`

Security implications: - Affects cross-site tracking - Changes authentication behavior - Impacts embedded content

stream_resource_content `staticmethod`

stream_resource_content(request_id)

Enables streaming of response content.

Useful for: - Large file downloads - Progressive loading - Memory optimization - Real-time processing

PARAMETER	DESCRIPTION
`request_id`	Target request identifier TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command to initiate content streaming TYPE: `StreamResourceContentCommand`

Best practices: - Monitor memory usage - Handle stream chunks efficiently - Consider error recovery

take_response_body_for_interception_as_stream `staticmethod`

take_response_body_for_interception_as_stream(interception_id)

Creates a stream for intercepted response body.

Applications: - Large response handling - Content modification - Bandwidth optimization - Progressive processing

PARAMETER	DESCRIPTION
`interception_id`	Intercepted response identifier TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command returning stream handle TYPE: `TakeResponseBodyForInterceptionAsStreamCommand`

Stream handling: - Supports chunked transfer - Manages memory efficiently - Enables real-time processing

emulate_network_conditions `staticmethod`

emulate_network_conditions(offline, latency, download_throughput, upload_throughput, connection_type=None, packet_loss=None, packet_queue_length=None, packet_reordering=None)

Emulates custom network conditions for realistic testing scenarios.

Simulates various network profiles including: - Offline mode - High-latency connections - Bandwidth throttling - Unreliable network characteristics

PARAMETER	DESCRIPTION
`offline`	Simulate complete network disconnection TYPE: `bool`
`latency`	Minimum latency in milliseconds (round-trip time) TYPE: `float`
`download_throughput`	Max download speed (bytes/sec, -1 to disable) TYPE: `float`
`upload_throughput`	Max upload speed (bytes/sec, -1 to disable) TYPE: `float`
`connection_type`	Network connection type (cellular, wifi, etc.) TYPE: `Optional[ConnectionType]` DEFAULT: `None`
`packet_loss`	Simulated packet loss percentage (0-100) TYPE: `Optional[float]` DEFAULT: `None`
`packet_queue_length`	Network buffer size simulation TYPE: `Optional[int]` DEFAULT: `None`
`packet_reordering`	Enable packet order randomization TYPE: `Optional[bool]` DEFAULT: `None`

Typical use cases: - Testing progressive loading states - Validating offline-first functionality - Performance optimization under constrained networks

RETURNS	DESCRIPTION
`Command`	CDP command to activate network emulation TYPE: `EmulateNetworkConditionsCommand`

get_security_isolation_status `staticmethod`

get_security_isolation_status(frame_id=None)

Retrieves security isolation information.

Provides: - CORS status - Cross-origin isolation - Security context - Frame isolation

PARAMETER	DESCRIPTION
`frame_id`	Optional frame to check TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command returning isolation status TYPE: `GetSecurityIsolationStatusCommand`

Security aspects: - Cross-origin policies - Iframe security - Site isolation - Content protection

load_network_resource `staticmethod`

load_network_resource(url, options, frame_id=None)

Loads a network resource with specific options.

Features: - Custom request configuration - Resource loading control - Frame-specific loading - Error handling

PARAMETER	DESCRIPTION
`url`	Resource URL to load TYPE: `str`
`options`	Loading configuration TYPE: `LoadNetworkResourceOptions`
`frame_id`	Target frame context TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	CDP command to load resource TYPE: `LoadNetworkResourceCommand`

Usage considerations: - Respects CORS policies - Handles authentication - Manages redirects - Supports streaming

replay_xhr `staticmethod`

replay_xhr(request_id)

Replays an XHR request.

Applications: - Request debugging - Response testing - Race condition analysis - API verification

PARAMETER	DESCRIPTION
`request_id`	XHR request to replay TYPE: `str`

RETURNS	DESCRIPTION
`Command`	CDP command to replay XHR TYPE: `ReplayXHRCommand`

Note: - Maintains original headers - Preserves request body - Updates timestamps - Creates new request ID

Uso

Os comandos de rede são usados para cenários avançados como interceptação de requisições e monitoramento de rede:

from pydoll.commands.network_commands import enable, set_request_interception
from pydoll.connection.connection_handler import ConnectionHandler

# Habilitar monitoramento de rede
connection = ConnectionHandler()
await enable(connection)

# Habilitar interceptação de requisições
await set_request_interception(connection, patterns=[{"urlPattern": "*"}])

Funcionalidades Principais

O módulo de comandos de rede fornece funções para:

Gerenciamento de Requisições

enable() / disable() - Habilitar/desabilitar monitoramento de rede
set_request_interception() - Interceptar e modificar requisições
continue_intercepted_request() - Continuar ou modificar requisições interceptadas
get_request_post_data() - Obter dados do corpo (body) da requisição

Manipulação de Respostas

get_response_body() - Obter conteúdo da resposta
fulfill_request() - Fornecer respostas customizadas
fail_request() - Simular falhas de rede

Gerenciamento de Cookies

get_cookies() - Obter cookies do navegador
set_cookies() - Definir cookies do navegador
delete_cookies() - Deletar cookies específicos
clear_browser_cookies() - Limpar todos os cookies

Controle de Cache

clear_browser_cache() - Limpar cache do navegador
set_cache_disabled() - Desabilitar cache do navegador
get_response_body_for_interception() - Obter respostas em cache

Segurança & Cabeçalhos

set_user_agent_override() - Sobrescrever user agent
set_extra_http_headers() - Adicionar cabeçalhos customizados
emulate_network_conditions() - Simular condições de rede

Casos de Uso Avançados

Interceptação de Requisição

# Interceptar e modificar requisições
await set_request_interception(connection, patterns=[
    {"urlPattern": "*/api/*", "requestStage": "Request"}
])

# Lidar com requisição interceptada
async def handle_request(request):
    if "api/login" in request.url:
        # Modificar cabeçalhos da requisição
        headers = request.headers.copy()
        headers["Authorization"] = "Bearer token"
        await continue_intercepted_request(
            connection, 
            request_id=request.request_id,
            headers=headers
        )

Simulação de Resposta (Mocking)

# Simular (mockar) respostas de API
await fulfill_request(
    connection,
    request_id=request_id,
    response_code=200,
    response_headers={"Content-Type": "application/json"},
    body='{"status": "success"}'
)

Impacto na Performance

A interceptação de rede pode impactar a performance de carregamento da página. Use seletivamente e desabilite quando não for necessário.

Comandos de Rede (Network)

Visão Geral

pydoll.commands.network_commands

NetworkCommands

clear_browser_cache staticmethod

clear_browser_cookies staticmethod

delete_cookies staticmethod

disable staticmethod

enable staticmethod

get_cookies staticmethod

get_request_post_data staticmethod

get_response_body staticmethod

set_cache_disabled staticmethod

set_cookie staticmethod

set_cookies staticmethod

set_extra_http_headers staticmethod

set_useragent_override staticmethod

clear_accepted_encodings_override staticmethod

enable_reporting_api staticmethod

search_in_response_body staticmethod

set_blocked_urls staticmethod

set_bypass_service_worker staticmethod

get_certificate staticmethod

get_response_body_for_interception staticmethod

set_accepted_encodings staticmethod

set_attach_debug_stack staticmethod

set_cookie_controls staticmethod

stream_resource_content staticmethod

take_response_body_for_interception_as_stream staticmethod

emulate_network_conditions staticmethod

get_security_isolation_status staticmethod

load_network_resource staticmethod

replay_xhr staticmethod

Uso