Principle:SeleniumHQ Selenium DevTools Connection Establishment
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, DevTools, WebSocket |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Process of discovering the CDP endpoint URL, establishing a WebSocket connection, and matching the correct CDP protocol version for the connected browser.
Description
CDP communication uses WebSocket connections to a browser's debugging endpoint. Establishing this connection requires three steps: finding the WebSocket URL (from session capabilities or by querying the browser's HTTP debug endpoint), matching the CDP protocol version (each Chrome version maps to a specific CDP version), and opening the WebSocket connection. Selenium handles this through CdpEndpointFinder (URL discovery), CdpVersionFinder (version matching via ServiceLoader), and SeleniumCdpConnection (connection factory).
The URL discovery has two strategies:
- Extract the se:cdp capability directly from session capabilities
- Fall back to CdpEndpointFinder.getReportedUri() which reads the debuggerAddress from goog:chromeOptions (Chrome) or ms:edgeOptions (Edge), then queries /json/version on that address to find the webSocketDebuggerUrl
Version matching uses CdpVersionFinder which loads CdpInfo implementations via ServiceLoader. It extracts the browser major version from the "Browser" field in the version JSON (e.g., "Chrome/120.0.6099.71" yields major version 120) and finds the nearest matching CdpInfo, allowing a configurable fudge factor (default 5 versions) for approximate matches.
Usage
This principle is invoked automatically when calling driver.getDevTools(). Understanding it is important for debugging CDP connection failures, version mismatches, or custom CDP endpoint configurations.
Theoretical Basis
# Pseudocode: CDP Connection Establishment
1. Extract "se:cdp" URL from session capabilities
OR extract debuggerAddress from "goog:chromeOptions" / "ms:edgeOptions"
and query http://HOST:PORT/json/version for "webSocketDebuggerUrl"
2. Create HttpClient for the CDP endpoint URI
3. Use CdpVersionFinder to find matching CdpInfo:
- Loads CdpInfo implementations via ServiceLoader
- Extracts major version from "Browser" field (e.g., "Chrome/120.0..." -> 120)
- Selects exact match, or nearest lower version within fudge factor of 5
4. Create WebSocket connection to CDP URL via Connection constructor
5. Return SeleniumCdpConnection wrapping the WebSocket