Implementation:SeleniumHQ Selenium HasDevTools GetDevTools

Knowledge Sources	Selenium Selenium DevTools
Domains	Browser_Automation, DevTools, WebSocket
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for obtaining a DevTools client from a WebDriver session provided by the Selenium Java library.

Description

The HasDevTools.getDevTools() default method calls maybeGetDevTools() and throws DevToolsException if the result is empty. The actual connection logic lives in ChromiumDriver.maybeGetDevTools(), which delegates to SeleniumCdpConnection.create() for WebSocket establishment and CdpVersionFinder for protocol version matching.

SeleniumCdpConnection.create() first attempts to extract the se:cdp capability directly as a URI. If not present, it falls back to CdpEndpointFinder.getReportedUri(), which reads the debuggerAddress from goog:chromeOptions (Chrome) or ms:edgeOptions (Edge), constructs an HTTP URI, and queries /json/version to find the webSocketDebuggerUrl.

CdpVersionFinder loads CdpInfo implementations via ServiceLoader and matches the browser's major version. It tries for an exact match first, then falls back to the nearest lower version within a fudge factor of 5. The matching CdpInfo provides the Domains factory for the DevTools instance.

Usage

Call getDevTools() on a ChromeDriver or EdgeDriver instance after creating a session. The returned DevTools object is the entry point for all CDP operations. Use maybeGetDevTools() if you want to handle the absence of CDP support gracefully without exceptions.

Code Reference

Source Location

• Repository: Selenium
• File: java/src/org/openqa/selenium/devtools/HasDevTools.java (L22-30)
• File: java/src/org/openqa/selenium/devtools/SeleniumCdpConnection.java (L32-132)
• File: java/src/org/openqa/selenium/devtools/CdpEndpointFinder.java (L38-133)
• File: java/src/org/openqa/selenium/devtools/CdpVersionFinder.java (L33-156)

Signature

// HasDevTools interface
public interface HasDevTools {
    default DevTools getDevTools() {
        return maybeGetDevTools()
            .orElseThrow(() -> new DevToolsException("Unable to create DevTools connection"));
    }
    Optional<DevTools> maybeGetDevTools();
}

// SeleniumCdpConnection factory
public class SeleniumCdpConnection extends Connection {
    public static Optional<Connection> create(WebDriver driver, ClientConfig clientConfig);
    public static Optional<Connection> create(Capabilities capabilities, ClientConfig clientConfig);
    public static Optional<Connection> create(
        HttpClient.Factory clientFactory, Capabilities capabilities, ClientConfig clientConfig);
}

// CdpEndpointFinder
public class CdpEndpointFinder {
    public static HttpClient getHttpClient(
        HttpClient.Factory clientFactory, URI reportedUri, ClientConfig clientConfig);
    public static Optional<URI> getCdpEndPoint(HttpClient client);
    public static Optional<URI> getReportedUri(Capabilities caps);
    public static Optional<URI> getReportedUri(String capabilityKey, Capabilities caps);
}

// CdpVersionFinder
public class CdpVersionFinder {
    public CdpVersionFinder();
    public CdpVersionFinder(int versionFudgeFactor, Collection<CdpInfo> infos);
    public Optional<CdpInfo> match(Map<String, Object> versionJson);
    public Optional<CdpInfo> match(String browserVersion);
}

Import

import org.openqa.selenium.devtools.HasDevTools;
import org.openqa.selenium.devtools.DevTools;
import org.openqa.selenium.devtools.SeleniumCdpConnection;
import org.openqa.selenium.devtools.CdpEndpointFinder;
import org.openqa.selenium.devtools.CdpVersionFinder;

I/O Contract

Inputs

Name	Type	Required	Description
capabilities	Capabilities	Yes (internal)	Session capabilities containing "se:cdp" or browser-specific debuggerAddress
clientConfig	ClientConfig	No	HTTP/WebSocket client configuration; defaults to ClientConfig.defaultConfig()

Outputs

Name	Type	Description
DevTools	DevTools	CDP client wrapping WebSocket connection, matched to correct protocol version
(via maybeGetDevTools)	Optional<DevTools>	Empty if CDP connection cannot be established

Usage Examples

import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.devtools.DevTools;

ChromeDriver driver = new ChromeDriver();

// getDevTools() handles all connection establishment:
// 1. Finds CDP WebSocket URL from "se:cdp" capability
// 2. Matches CDP protocol version via CdpVersionFinder
// 3. Opens WebSocket via SeleniumCdpConnection
DevTools devTools = driver.getDevTools();

// Create a CDP session on the current page target
devTools.createSession();

// Ready for CDP commands
// ...

devTools.close();
driver.quit();

Safe Check with maybeGetDevTools

import org.openqa.selenium.devtools.HasDevTools;
import org.openqa.selenium.devtools.DevTools;
import java.util.Optional;

if (driver instanceof HasDevTools) {
    Optional<DevTools> maybeDevTools = ((HasDevTools) driver).maybeGetDevTools();
    maybeDevTools.ifPresent(devTools -> {
        devTools.createSession();
        // CDP operations...
        devTools.close();
    });
}

Related Pages

Implements Principle

• Principle:SeleniumHQ_Selenium_DevTools_Connection_Establishment