Implementation:SeleniumHQ Selenium DevTools Send

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

Overview

Concrete tool for sending typed CDP commands and receiving typed responses provided by the Selenium DevTools Java API.

Description

DevTools.send(Command<X>) is the primary method for executing CDP commands. It delegates to Connection.sendAndWait(), which calls Connection.send() to serialize the command to JSON-RPC format, send it over WebSocket, and wait for the response via a CompletableFuture.

The Connection.send() method assigns an auto-incrementing message ID, registers a CompletableFuture<X> callback keyed by that ID, serializes the message as a JSON object with fields id, method, params, and optionally sessionId, then sends the JSON text over the WebSocket. When a response arrives, the Connection.Listener dispatches it on a background daemon thread: it matches the id field to the registered callback, then either deserializes the "result" using the Command mapper function or completes the future exceptionally with the "error" content.

The Command<X> class has three constructors:

• Command(String method, Map<String, Object> params) -- uses Object.class for deserialization
• Command(String method, Map<String, Object> params, Type typeOfX) -- uses reflection-based deserialization
• Command(String method, Map<String, Object> params, Function<JsonInput, X> mapper) -- uses custom mapper

The doesNotSendResponse() method creates a variant that completes immediately with null, used for fire-and-forget CDP commands.

Usage

Use with domain-specific commands: Network.enable(), Page.captureScreenshot(), DOM.getDocument(), etc. These are generated from the CDP protocol definition JSON files. An overloaded form accepts a Duration timeout for commands that may require extended waiting (default is 30 seconds).

Code Reference

Source Location

• Repository: Selenium
• File: java/src/org/openqa/selenium/devtools/DevTools.java (L94-101)
• File: java/src/org/openqa/selenium/devtools/Command.java (L26-80)
• File: java/src/org/openqa/selenium/devtools/Connection.java (L145-210)

Signature

// DevTools send methods
public class DevTools implements Closeable {
    public <X> X send(Command<X> command);
    public <X> X send(Command<X> command, Duration timeout);
}

// Command class
public class Command<X> {
    public Command(String method, Map<String, Object> params);
    public Command(String method, Map<String, Object> params, Type typeOfX);
    public Command(String method, Map<String, Object> params, Function<JsonInput, X> mapper);
    public String getMethod();
    public Map<String, Object> getParams();
    public boolean getSendsResponse();
    public Command<X> doesNotSendResponse();
}

// Connection send methods
public class Connection implements Closeable {
    public <X> CompletableFuture<X> send(SessionID sessionId, Command<X> command);
    public <X> X sendAndWait(SessionID sessionId, Command<X> command, Duration timeout);
}

Import

import org.openqa.selenium.devtools.DevTools;
import org.openqa.selenium.devtools.Command;

I/O Contract

Inputs

Name	Type	Required	Description
command	Command<X>	Yes	Typed CDP command with method name, params, and result mapper
timeout	Duration	No	Maximum wait time for response (default 30 seconds)

Outputs

Name	Type	Description
result	X	Typed, deserialized CDP response (null for doesNotSendResponse commands)

Exceptions

Exception	Condition
DevToolsException	CDP returns an error response or mapper fails
TimeoutException	Response not received within timeout
IllegalStateException	Thread interrupted while waiting

Usage Examples

import org.openqa.selenium.devtools.DevTools;
import org.openqa.selenium.devtools.v120.network.Network;
import org.openqa.selenium.devtools.v120.page.Page;

DevTools devTools = driver.getDevTools();
devTools.createSession();

// Enable network domain (returns void)
devTools.send(Network.enable(Optional.empty(), Optional.empty(), Optional.empty()));

// Capture screenshot (returns Base64-encoded string)
String screenshot = devTools.send(Page.captureScreenshot(
    Optional.empty(), Optional.empty(), Optional.empty(),
    Optional.empty(), Optional.empty()));

// Send with custom timeout
devTools.send(someSlowCommand, Duration.ofMinutes(2));

Related Pages

Implements Principle

• Principle:SeleniumHQ_Selenium_CDP_Command_Execution