Workflow:SeleniumHQ Selenium Chrome DevTools Protocol Integration

Knowledge Sources	Selenium Selenium Documentation Chrome DevTools Protocol
Domains	Browser_Automation, DevTools, Network_Interception
Last Updated	2026-02-11 23:00 GMT

Overview

End-to-end process for connecting to the Chrome DevTools Protocol (CDP) from a Selenium WebDriver session to perform advanced browser operations such as network interception, console log capture, performance monitoring, and low-level DOM manipulation.

Description

This workflow describes how to establish a CDP connection through a Selenium WebDriver session and use it for advanced browser control beyond the standard WebDriver API. The CDP integration enables capabilities like intercepting and modifying network requests, capturing console and JavaScript errors, emulating device conditions (geolocation, network throttling), and accessing performance metrics. Selenium provides both a high-level typed API (with generated domain classes for each CDP version) and a raw command execution interface.

Key outputs:

• A live CDP WebSocket connection to the browser
• Ability to send typed CDP commands and receive responses
• Event listeners for real-time browser events (network, console, DOM)
• Network request/response interception and modification

Scope:

• Applies to Chromium-based browsers (Chrome, Edge) and partially to Firefox
• CDP version matching is automatic via CdpVersionFinder
• Available across Java, Python, Ruby, and JavaScript bindings

Usage

Execute this workflow when you need browser automation capabilities beyond standard WebDriver, such as intercepting HTTP requests to mock API responses, capturing browser console logs for debugging, emulating mobile devices or network conditions, or accessing performance profiling data during test execution.

Execution Steps

Step 1: Establish WebDriver Session

Create a WebDriver session with a Chromium-based browser (Chrome or Edge). The CDP endpoint is automatically exposed through the browser capabilities when a local driver is used.

Key considerations:

• The driver must implement the HasDevTools interface
• CDP access requires a direct connection to the browser (not through Grid without BiDi)
• The webSocketUrl capability in the session response provides the CDP endpoint
• For remote sessions, BiDi (WebDriver BiDi protocol) is the preferred alternative

Step 2: Obtain DevTools Connection

Retrieve a DevTools client object from the driver. This creates or reuses a WebSocket connection to the browser CDP endpoint.

What happens:

• The driver resolves the CDP WebSocket URL from the browser capabilities
• CdpEndpointFinder discovers the endpoint URI from the browser HTTP debug interface
• CdpVersionFinder matches the browser version to the closest available CDP implementation
• A WebSocket connection is established via the Connection class
• The DevTools object wraps this connection with a typed command/event API

Key considerations:

• CDP versions are major-version specific; Selenium ships generated bindings for recent versions
• If no exact version match exists, the closest lower version is used
• The connection supports multiplexed sessions (one per browser target/tab)

Step 3: Create CDP Session

Attach the DevTools client to a specific browser target (tab/page). CDP commands operate within the context of a session attached to a particular target.

What happens:

• The Target domain is queried for available targets via target.getTargets()
• The correct page target is identified by matching the window handle
• A session is attached to the target via target.attachToTarget()
• Auto-attach is configured so new targets are automatically tracked
• Domain-specific setup (clearing logs, enabling domains) is performed

Key considerations:

• Each browser tab/page is a separate CDP target
• A session must be created before sending domain-specific commands
• Creating a session for one target does not affect others

Step 4: Send CDP Commands

Execute CDP commands against the browser using the typed Command API. Commands are serialized to JSON, sent over the WebSocket, and responses are deserialized back to typed Java/Python/Ruby objects.

What happens:

• A Command object specifies the CDP method name and parameters
• The DevTools.send() method serializes the command, assigns a message ID, and sends it
• The response is matched by message ID and deserialized using the Command mapper
• Synchronous send blocks until the response arrives or a timeout is reached

Key considerations:

• Commands are domain-specific (Network, Page, DOM, Runtime, Performance, etc.)
• Each command has typed parameters and return types generated from the CDP protocol spec
• Timeouts should be configured for commands that may take longer (page loads, downloads)
• Errors from the browser are wrapped in DevToolsException

Step 5: Subscribe to CDP Events

Register event listeners to receive real-time notifications from the browser. Events cover network activity, console output, DOM changes, page lifecycle, and more.

What happens:

• Event objects define the CDP event name and a deserialization mapper
• addListener registers a callback (Consumer or BiConsumer with sequence number)
• Events are dispatched asynchronously as the browser sends them over WebSocket
• Multiple listeners can be registered for the same event type
• Listeners are cleared when the session is disconnected

Key considerations:

• Some domains must be explicitly enabled before events are emitted (e.g., Network.enable())
• Event handlers run on the WebSocket reader thread; long-running handlers should offload work
• clearListeners() removes all registered event handlers

Step 6: Intercept Network Traffic

Use the NetworkInterceptor to modify HTTP requests and responses flowing through the browser. This enables mocking API responses, injecting headers, or blocking specific requests.

What happens:

• A NetworkInterceptor is created with a Route that defines matching criteria and response behavior
• The interceptor enables the CDP Fetch domain to pause matching requests
• When a request matches, the route handler can return a modified response or allow it to proceed
• The interceptor implements AutoCloseable for use in try-with-resources blocks

Key considerations:

• NetworkInterceptor uses CDP Fetch domain, not the Network domain
• Routes match requests by URL pattern and can return fully stubbed responses
• Only one interceptor should be active per driver at a time
• Closing the interceptor disables the Fetch domain and resumes normal traffic

Step 7: Disconnect CDP Session

Detach from the CDP target and close the WebSocket connection. This cleans up resources and stops event delivery.

What happens:

• Active domain subscriptions are disabled (Network, Fetch, etc.)
• The session is detached from the target via target.detachFromTarget()
• The WebSocket connection is closed
• Pending command futures are cancelled

Key considerations:

• Always disconnect in test teardown to prevent resource leaks
• The DevTools object can create a new session after disconnecting
• Closing the WebDriver session (quit()) also terminates the CDP connection

GitHub URL

Workflow Repository