0
# DevTools Protocol
1

2
The Chrome DevTools Protocol (CDP) integration allows direct communication with Chrome's debugging interface for advanced browser control, performance monitoring, and debugging capabilities.
3

4
## CDP Command Execution
5

6
### Execute CDP Command
7

8
Execute Chrome DevTools Protocol commands directly.
9

10
```java { .api }
11
public Map<String, Object> executeCdpCommand(String commandName, Map<String, Object> parameters);
12
```
13

14
**Parameters:**
15
- `commandName` (String): CDP command name following the format "Domain.method"
16
- `parameters` (Map<String, Object>): Command parameters as key-value pairs
17

18
**Returns:** Map<String, Object> - Command response data
19

20
**Usage Example:**
21
```java
22
import java.util.Map;
23
import java.util.HashMap;
24

25
ChromiumDriver driver = new ChromiumDriver(commandExecutor, capabilities, "chrome");
26

27
// Take a screenshot using CDP
28
Map<String, Object> result = driver.executeCdpCommand("Page.captureScreenshot", Map.of(
29
    "format", "png",
30
    "quality", 100
31
));
32
String screenshotData = (String) result.get("data");
33

34
// Get performance metrics
35
Map<String, Object> metrics = driver.executeCdpCommand("Performance.getMetrics", Map.of());
36

37
// Enable network domain and capture requests
38
driver.executeCdpCommand("Network.enable", Map.of());
39
driver.executeCdpCommand("Network.setCacheDisabled", Map.of("cacheDisabled", true));
40
```
41

42
## Common CDP Commands
43

44
### Page Domain
45

46
Control page-level operations:
47

48
```java
49
// Navigate to URL
50
driver.executeCdpCommand("Page.navigate", Map.of("url", "https://example.com"));
51

52
// Reload page
53
driver.executeCdpCommand("Page.reload", Map.of("ignoreCache", true));
54

55
// Get page layout metrics
56
Map<String, Object> layout = driver.executeCdpCommand("Page.getLayoutMetrics", Map.of());
57

58
// Add script to evaluate on new document
59
driver.executeCdpCommand("Page.addScriptToEvaluateOnNewDocument", Map.of(
60
    "source", "console.log('Page loaded');"
61
));
62
```
63

64
### Runtime Domain
65

66
JavaScript execution and console interaction:
67

68
```java
69
// Evaluate JavaScript expression
70
Map<String, Object> result = driver.executeCdpCommand("Runtime.evaluate", Map.of(
71
    "expression", "document.title",
72
    "returnByValue", true
73
));
74

75
// Enable runtime notifications
76
driver.executeCdpCommand("Runtime.enable", Map.of());
77

78
// Call function on object
79
driver.executeCdpCommand("Runtime.callFunctionOn", Map.of(
80
    "functionDeclaration", "function() { return this.tagName; }",
81
    "objectId", "node-id"
82
));
83
```
84

85
### Network Domain
86

87
Monitor and control network activity:
88

89
```java
90
// Enable network tracking
91
driver.executeCdpCommand("Network.enable", Map.of());
92

93
// Set user agent override
94
driver.executeCdpCommand("Network.setUserAgentOverride", Map.of(
95
    "userAgent", "Custom User Agent 1.0"
96
));
97

98
// Block URLs matching patterns
99
driver.executeCdpCommand("Network.setBlockedURLs", Map.of(
100
    "urls", Arrays.asList("*analytics*", "*tracking*")
101
));
102

103
// Clear browser cache
104
driver.executeCdpCommand("Network.clearBrowserCache", Map.of());
105
```
106

107
### Performance Domain
108

109
Performance monitoring and metrics:
110

111
```java
112
// Enable performance metrics collection
113
driver.executeCdpCommand("Performance.enable", Map.of());
114

115
// Get current metrics
116
Map<String, Object> metrics = driver.executeCdpCommand("Performance.getMetrics", Map.of());
117

118
// Disable performance monitoring
119
driver.executeCdpCommand("Performance.disable", Map.of());
120
```
121

122
### Security Domain
123

124
Security-related operations:
125

126
```java
127
// Enable security notifications
128
driver.executeCdpCommand("Security.enable", Map.of());
129

130
// Set ignore certificate errors
131
driver.executeCdpCommand("Security.setIgnoreCertificateErrors", Map.of(
132
    "ignore", true
133
));
134
```
135

136
### DOM Domain
137

138
DOM manipulation and inspection:
139

140
```java
141
// Get document root
142
Map<String, Object> doc = driver.executeCdpCommand("DOM.getDocument", Map.of());
143

144
// Query selector
145
Map<String, Object> element = driver.executeCdpCommand("DOM.querySelector", Map.of(
146
    "nodeId", 1,
147
    "selector", "#myElement"
148
));
149

150
// Get element attributes
151
Map<String, Object> attrs = driver.executeCdpCommand("DOM.getAttributes", Map.of(
152
    "nodeId", 123
153
));
154
```
155

156
## DevTools Integration
157

158
### Access DevTools Instance
159

160
Get the DevTools instance for advanced operations:
161

162
```java { .api }
163
public Optional<DevTools> maybeGetDevTools();
164
```
165

166
**Returns:** Optional<DevTools> - DevTools instance if available
167

168
**Usage Example:**
169
```java
170
import org.openqa.selenium.devtools.DevTools;
171

172
Optional<DevTools> devToolsOpt = driver.maybeGetDevTools();
173
if (devToolsOpt.isPresent()) {
174
    DevTools devTools = devToolsOpt.get();
175
    devTools.createSession();
176
    
177
    // Use DevTools API instead of raw CDP
178
    devTools.send(org.openqa.selenium.devtools.v85.network.Network.enable(
179
        Optional.empty(), Optional.empty(), Optional.empty()
180
    ));
181
}
182
```
183

184
## BiDi Protocol Support
185

186
### Access BiDi Instance
187

188
Get WebDriver BiDi instance for modern protocol support:
189

190
```java { .api }
191
public Optional<BiDi> maybeGetBiDi();
192
```
193

194
**Returns:** Optional<BiDi> - BiDi instance if available
195

196
**Usage Example:**
197
```java
198
import org.openqa.selenium.bidi.BiDi;
199

200
Optional<BiDi> biDiOpt = driver.maybeGetBiDi();
201
if (biDiOpt.isPresent()) {
202
    BiDi biDi = biDiOpt.get();
203
    // Use BiDi protocol features
204
}
205
```
206

207
## Advanced CDP Examples
208

209
### Network Request Interception
210

211
```java
212
// Enable network domain
213
driver.executeCdpCommand("Network.enable", Map.of());
214

215
// Set request interception
216
driver.executeCdpCommand("Network.setRequestInterception", Map.of(
217
    "patterns", Arrays.asList(Map.of(
218
        "urlPattern", "*",
219
        "resourceType", "Document",
220
        "interceptionStage", "HeadersReceived"
221
    ))
222
));
223

224
// Continue intercepted request
225
driver.executeCdpCommand("Network.continueInterceptedRequest", Map.of(
226
    "interceptionId", "interceptionId",
227
    "rawResponse", "modifiedResponseData"
228
));
229
```
230

231
### Cookie Management
232

233
```java
234
// Get all cookies
235
Map<String, Object> cookies = driver.executeCdpCommand("Network.getAllCookies", Map.of());
236

237
// Set cookie
238
driver.executeCdpCommand("Network.setCookie", Map.of(
239
    "name", "test_cookie",
240
    "value", "test_value",
241
    "domain", "example.com",
242
    "path", "/",
243
    "secure", true,
244
    "httpOnly", false
245
));
246

247
// Delete cookies
248
driver.executeCdpCommand("Network.deleteCookies", Map.of(
249
    "name", "test_cookie",
250
    "domain", "example.com"
251
));
252
```
253

254
### Console Message Handling
255

256
```java
257
// Enable runtime to receive console messages
258
driver.executeCdpCommand("Runtime.enable", Map.of());
259

260
// Console messages will be available through CDP events
261
// Note: Event handling requires DevTools API or custom event listeners
262
```
263

264
## Types and Constants
265

266
```java { .api }
267
// Command constant for CDP execution
268
public static final String EXECUTE_CDP = "executeCdpCommand";
269

270
// DevTools connection and session management
271
public class DevTools {
272
    public void createSession();
273
    public void createSessionIfThereIsNotOne();
274
    public <T> T send(Command<T> command);
275
}
276

277
// BiDi protocol support
278
public class BiDi {
279
    // BiDi protocol methods
280
}
281
```
282

283
## Error Handling
284

285
Common exceptions when using CDP:
286

287
- **WebDriverException**: When CDP command execution fails
288
- **ConnectionFailedException**: When DevTools connection cannot be established
289
- **IllegalArgumentException**: When invalid command names or parameters are provided
290
- **BiDiException**: When BiDi protocol operations fail
291

292
**Usage Example with Error Handling:**
293
```java
294
try {
295
    Map<String, Object> result = driver.executeCdpCommand("Page.captureScreenshot", Map.of(
296
        "format", "png"
297
    ));
298
    String screenshot = (String) result.get("data");
299
} catch (WebDriverException e) {
300
    System.err.println("CDP command failed: " + e.getMessage());
301
}
302
```
303

304
## Best Practices
305

306
1. **DevTools API Preference**: Use the high-level DevTools API when available instead of raw CDP commands
307
2. **Error Handling**: Always handle potential connection failures and command errors
308
3. **Domain Enabling**: Enable relevant CDP domains before using their commands
309
4. **Resource Cleanup**: Disable domains when no longer needed to reduce overhead
310
5. **Version Compatibility**: CDP commands may vary between Chrome versions; test thoroughly
311
6. **Performance Impact**: Be mindful that extensive CDP usage can impact browser performance
312
7. **Security**: Be cautious when disabling security features through CDP commands
313

314
## CDP Command Reference
315

316
For complete CDP command documentation, refer to:
317
- [Chrome DevTools Protocol Documentation](https://chromedevtools.github.io/devtools-protocol/)
318
- Selenium's DevTools API for type-safe command execution
319
- Chrome version-specific CDP documentation for compatibility