Principle:SeleniumHQ Selenium CDP Command Execution
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, DevTools, Remote_Procedure_Call |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Mechanism for sending typed Chrome DevTools Protocol commands over a WebSocket connection and receiving typed responses.
Description
CDP uses a JSON-RPC-like protocol over WebSocket for command execution. Each command has a method name (e.g., "Network.enable"), a parameters map, and a typed response. Selenium wraps this in a type-safe Command<X> class that includes the method name, parameters map, and a deserialization function (Function<JsonInput, X>). The DevTools.send() method delegates to Connection.sendAndWait(), which serializes the command to JSON, sends it over the WebSocket, waits for the matching response (by auto-incrementing message ID), and deserializes the result to type X.
The Command<X> class also supports a doesNotSendResponse() flag for the special case of CDP commands that do not return a response. For these commands, the future completes immediately with null rather than waiting for a response message.
Usage
Use devTools.send() to execute any CDP command. Domain-specific commands are provided as static factory methods in generated classes (e.g., Network.enable(), Page.captureScreenshot()). This is the core mechanism for all CDP interactions. An overloaded form accepts a Duration timeout for commands that may require extended waiting.
Theoretical Basis
# Pseudocode: CDP Command Execution
1. Construct Command<X> with:
- method: "Domain.method" (e.g., "Network.enable")
- params: Map<String, Object>
- mapper: Function<JsonInput, X> for deserializing response
2. Connection.send() assigns auto-incrementing message ID
3. Registers CompletableFuture callback keyed by message ID
4. Serializes to JSON: { "id": N, "method": "...", "params": {...}, "sessionId": "..." }
5. Sends JSON text over WebSocket
6. WebSocket Listener receives response: { "id": N, "result": {...} }
or error: { "id": N, "error": {...} }
7. Callback is invoked: mapper deserializes "result" to type X
or CompletableFuture completes exceptionally on "error"
8. sendAndWait() blocks on the CompletableFuture with timeout
9. Returns typed result X