DevTools

from adodbapi.examples.xls_read import driver

DevTools Overview

The dev_tools package is one of the most advanced components of the framework. While the CDP Executors allow you to send individual commands, the DevTools Manager provides a complete, asynchronous environment for monitoring and reacting to browser events across all open tabs, iframes, and workers.

---

The Async Context Pattern

The DevTools manager is designed to be used as an asynchronous context manager. When you enter the context, the framework establishes a bidirectional connection, starts event listeners, and begins tracking targets.

import trio
from osn_selenium.webdrivers.trio_threads.chrome import ChromeWebDriver

async def main():
    driver = ChromeWebDriver(webdriver_path="./chromedriver")
    
    # The manager is accessed via the 'devtools' property of a Trio driver
    async with driver.devtools:
        # While inside this block, DevTools is active
        await trio.sleep(10) 
    # Upon exiting, all listeners and connections are gracefully closed

trio.run(main)

---

Key Capabilities

Multi-Target Management

The manager doesn't just watch the active tab. It can automatically discover and attach to:

• Pages (Tabs and Windows)
• Iframes
• Service Workers / Shared Workers

Every target is represented by a TargetData model, containing its ID, URL, type, and title.

Stealth & Fingerprint Detection

The manager works in tandem with the Anti-Fingerprinting module. It injects detection scripts into every new document and listens for runtime.BindingCalled events. If a website tries to "fingerprint" your browser, the manager logs the attempt, including the specific API used and the JavaScript stacktrace.

---

Configuration

You can fine-tune the manager's behavior using the DevToolsSettings class:

Parameter	Description
new_targets_filter	A list of TargetFilter objects to decide which tabs/iframes to ignore or attach to.
target_background_task	An async function that will be executed automatically for every target the manager attaches to.
domains_settings	Configuration for specific CDP domains (e.g., enabling the Fetch domain with custom patterns).
logger_settings	Detailed control over where and how CDP and Fingerprint logs are saved.

---

The Advanced Logging System

The framework implements a two-tier logging architecture:

1. Main Logger: Aggregates statistics for the entire session. It tracks how many targets are open, the total number of logs, and a summary of intercepted events.
2. Target Logger: Every single tab or iframe gets its own directory (named after the target_id). Inside, you will find:
   • cdp_log.txt: All protocol-level events and commands.
   • fingerprint_log.txt: A detailed history of every attempt the site made to read your browser's identity.

---

Usage Example

This example shows how to use the DevTools manager to automatically inject a custom header into every outgoing request.

import trio
from osn_selenium.dev_tools.domains.fetch import (
    FetchSettings,
    FetchHandlersSettings,
    RequestPausedSettings,
    RequestPausedActionsHandlerSettings,
    RequestPausedActionsSettings,
    ContinueRequestSettings,
    ContinueRequestHandlersSettings
)
from osn_selenium.dev_tools.domains.abstract import ParameterHandler
from osn_selenium.dev_tools.domains_default.fetch import headers_handler, HeaderInstance
from osn_selenium.webdrivers.trio_threads.chrome import ChromeWebDriver

async def main():
    # 1. Define header modification rules
    headers_rules = {
        "X-Custom-Bot-Detection": HeaderInstance(value="Passed", instruction="set"),
        "User-Agent": HeaderInstance(value="Mozilla/5.0 (Stealth)", instruction="set")
    }
    
    # 2. Configure Fetch domain
    fetch_cfg = FetchSettings(
        handlers=FetchHandlersSettings(
            request_paused=RequestPausedSettings(
                actions_handler=RequestPausedActionsHandlerSettings(
                    actions=RequestPausedActionsSettings(
                        continue_request=ContinueRequestSettings(
                            parameters_handlers=ContinueRequestHandlersSettings(
                                headers=ParameterHandler(func=headers_handler, instances=headers_rules)
                            )
                        )
                    )
                )
            )
        )
    )
    
    driver = ChromeWebDriver(webdriver_path="./chromedriver", devtools_settings=fetch_cfg)
    
    # 3. Start driver and enter DevTools context
    async with driver.devtools:
        await trio.sleep(5)
        
        await driver.get("https://httpbin.org/headers")
        # All requests now carry the custom headers!
        await trio.sleep(5)

trio.run(main)

Note on Startup Performance: Currently, initializing the DevTools context takes a few seconds as the framework must establish WebSocket connections, discover all existing targets (tabs/iframes), and inject baseline scripts. This initialization delay is a known current behavior and is scheduled for optimization in future framework updates.