0
# Network Operations
1

2
Network traffic monitoring, request/response interception, and authentication handling for Chrome DevTools Protocol v138. Essential for API testing, performance monitoring, and request modification with full HTTP message support.
3

4
## Capabilities
5

6
### Network Handler
7

8
Main network handler providing traffic monitoring and interception capabilities.
9

10
```java { .api }
11
/**
12
 * Network monitoring and interception for CDP v138
13
 * @param devTools DevTools connection for network communication
14
 */
15
public class v138Network extends Network<AuthRequired, RequestPaused> {
16
    private static final Logger LOG = Logger.getLogger(v138Network.class.getName());
17
    
18
    public v138Network(DevTools devTools);
19
    
20
    // Public API methods inherited from Network base class
21
    public void disable();
22
    public void setUserAgent(String userAgent);
23
    public void setUserAgent(UserAgent userAgent);
24
    public void addAuthHandler(Predicate<URI> uriPredicate, Supplier<Credentials> credentials);
25
    public void resetNetworkFilter();
26
    public void interceptTrafficWith(Filter filter);
27
    public void prepareToInterceptTraffic();
28
}
29
```
30

31
**Usage Example:**
32

33
```java
34
import org.openqa.selenium.devtools.v138.v138Network;
35
import org.openqa.selenium.devtools.DevTools;
36
import org.openqa.selenium.devtools.idealized.Network.UserAgent;
37

38
v138Network network = new v138Network(devTools);
39

40
// Set custom user agent using public API
41
network.setUserAgent("MyBot/1.0 (Linux; x86_64)");
42

43
// Prepare for traffic interception
44
network.prepareToInterceptTraffic();
45

46
// Add authentication handler
47
network.addAuthHandler(
48
    uri -> uri.getHost().contains("secure-api.com"),
49
    () -> new Credentials("username", "password")
50
);
51
```
52

53
### Public Network API Methods
54

55
High-level methods for network configuration and traffic management without dealing with raw CDP commands.
56

57
```java { .api }
58
/**
59
 * Set user agent string for all requests
60
 * @param userAgent User agent string to use
61
 */
62
public void setUserAgent(String userAgent);
63

64
/**
65
 * Set user agent with full configuration options
66
 * @param userAgent UserAgent object with string, language, and platform
67
 */
68
public void setUserAgent(UserAgent userAgent);
69

70
/**
71
 * Add authentication handler for protected resources
72
 * @param uriPredicate Predicate to match URIs requiring authentication
73
 * @param credentials Supplier providing credentials when needed
74
 */
75
public void addAuthHandler(Predicate<URI> uriPredicate, Supplier<Credentials> credentials);
76

77
/**
78
 * Prepare network domain for traffic interception
79
 */
80
public void prepareToInterceptTraffic();
81

82
/**
83
 * Intercept network traffic with custom filter
84
 * @param filter Filter to apply to intercepted traffic
85
 */
86
public void interceptTrafficWith(Filter filter);
87

88
/**
89
 * Reset all network filters and configurations
90
 */
91
public void resetNetworkFilter();
92

93
/**
94
 * Disable network monitoring and clean up resources
95
 */
96
public void disable();
97
```
98

99
**Usage Example:**
100

101
```java
102
v138Network network = new v138Network(devTools);
103

104
// Set mobile user agent
105
network.setUserAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)");
106

107
// Set up authentication for API endpoints
108
network.addAuthHandler(
109
    uri -> uri.getPath().startsWith("/api/"),
110
    () -> new Credentials("api-key", "secret-token")
111
);
112

113
// Prepare for request modification
114
network.prepareToInterceptTraffic();
115

116
// Add custom filter for specific domains
117
Filter domainFilter = new Filter() {
118
    @Override
119
    public boolean test(HttpRequest request) {
120
        return request.getUri().contains("example.com");
121
    }
122
};
123
network.interceptTrafficWith(domainFilter);
124

125
// Navigate - authentication and filtering will be applied
126
driver.get("https://example.com/api/data");
127

128
// Clean up when done
129
network.resetNetworkFilter();
130
network.disable();
131
```
132

133
### User Agent Override
134

135
Controls the browser's user agent string and related headers.
136

137
```java { .api }
138
/**
139
 * Override the browser's user agent string
140
 * @param userAgent UserAgent configuration with string, language, and platform
141
 * @return Command to set user agent override
142
 */
143
@Override
144
protected Command<Void> setUserAgentOverride(UserAgent userAgent);
145
```
146

147
**Usage Example:**
148

149
```java
150
// Create custom user agent
151
UserAgent mobileUA = new UserAgent(
152
    "Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15",
153
    "en-US,en;q=0.9",
154
    "iPhone"
155
);
156

157
// Apply the override
158
devTools.send(network.setUserAgentOverride(mobileUA));
159

160
// All subsequent requests will use the mobile user agent
161
driver.get("https://example.com");
162
```
163

164
### Network Caching Control
165

166
Enables or disables the browser's network cache for testing scenarios.
167

168
```java { .api }
169
/**
170
 * Enable network caching for improved performance
171
 * @return Command to enable network cache
172
 */
173
@Override
174
protected Command<Void> enableNetworkCaching();
175

176
/**
177
 * Disable network caching to force fresh requests
178
 * @return Command to disable network cache
179
 */
180
@Override
181
protected Command<Void> disableNetworkCaching();
182
```
183

184
### Request Interception Control
185

186
Manages request interception for modification and analysis.
187

188
```java { .api }
189
/**
190
 * Enable fetch interception for all request patterns
191
 * @return Command to enable request interception
192
 */
193
@Override
194
protected Command<Void> enableFetchForAllPatterns();
195

196
/**
197
 * Disable fetch interception to restore normal operation
198
 * @return Command to disable request interception
199
 */
200
@Override
201
protected Command<Void> disableFetch();
202
```
203

204
### Authentication Event Handling
205

206
Handles HTTP authentication challenges with credential provision.
207

208
```java { .api }
209
/**
210
 * Stream of authentication required events
211
 * @return Event stream for authentication challenges
212
 */
213
@Override
214
protected Event<AuthRequired> authRequiredEvent();
215

216
/**
217
 * Extract URI from authentication challenge
218
 * @param authRequired Authentication challenge event
219
 * @return URI string requiring authentication
220
 */
221
@Override
222
protected String getUriFrom(AuthRequired authRequired);
223

224
/**
225
 * Continue request with provided credentials
226
 * @param authRequired Authentication challenge event
227
 * @param credentials Username and password for authentication
228
 * @return Command to provide credentials
229
 */
230
@Override
231
protected Command<Void> continueWithAuth(AuthRequired authRequired, 
232
                                       UsernameAndPassword credentials);
233

234
/**
235
 * Cancel authentication and fail the request
236
 * @param authRequired Authentication challenge event
237
 * @return Command to cancel authentication
238
 */
239
@Override
240
protected Command<Void> cancelAuth(AuthRequired authRequired);
241
```
242

243
**Usage Example:**
244

245
```java
246
import org.openqa.selenium.UsernameAndPassword;
247

248
// Listen for authentication challenges
249
devTools.addListener(network.authRequiredEvent(), authEvent -> {
250
    String uri = network.getUriFrom(authEvent);
251
    System.out.println("Authentication required for: " + uri);
252
    
253
    // Provide credentials automatically
254
    UsernameAndPassword creds = new UsernameAndPassword("user", "pass");
255
    devTools.send(network.continueWithAuth(authEvent, creds));
256
});
257

258
// Enable interception to catch auth requests
259
devTools.send(network.enableFetchForAllPatterns());
260

261
// Navigate to protected resource
262
driver.get("https://httpbin.org/basic-auth/user/pass");
263
```
264

265
### Request Interception and Modification
266

267
Intercepts and modifies HTTP requests and responses in real-time.
268

269
```java { .api }
270
/**
271
 * Stream of paused request events for interception
272
 * @return Event stream for intercepted requests
273
 */
274
@Override
275
public Event<RequestPaused> requestPausedEvent();
276

277
/**
278
 * Create Selenium HTTP messages from paused request
279
 * @param pausedReq Intercepted request/response data
280
 * @return Either HttpRequest or HttpResponse for processing
281
 */
282
@Override
283
public Either<HttpRequest, HttpResponse> createSeMessages(RequestPaused pausedReq);
284

285
/**
286
 * Check if paused request has error response
287
 * @param pausedReq Intercepted request data
288
 * @return true if request failed with error
289
 */
290
@Override
291
protected boolean hasErrorResponse(RequestPaused pausedReq);
292

293
/**
294
 * Extract request ID for correlation
295
 * @param pausedReq Intercepted request data  
296
 * @return String request identifier
297
 */
298
@Override
299
protected String getRequestId(RequestPaused pausedReq);
300
```
301

302
### Request Continuation Control
303

304
Controls how intercepted requests are processed and forwarded.
305

306
```java { .api }
307
/**
308
 * Continue request without any modifications
309
 * @param pausedRequest Intercepted request to continue
310
 * @return Command to continue unmodified
311
 */
312
@Override
313
protected Command<Void> continueWithoutModification(RequestPaused pausedRequest);
314

315
/**
316
 * Continue request with modifications
317
 * @param pausedReq Intercepted request
318
 * @param req Modified HttpRequest to send
319
 * @return Command to continue with modifications
320
 */
321
@Override
322
protected Command<Void> continueRequest(RequestPaused pausedReq, HttpRequest req);
323

324
/**
325
 * Fulfill request with custom response
326
 * @param pausedReq Intercepted request
327
 * @param res Custom HttpResponse to return
328
 * @return Command to fulfill with custom response
329
 */
330
@Override
331
protected Command<Void> fulfillRequest(RequestPaused pausedReq, HttpResponse res);
332
```
333

334
## Complete Network Interception Example
335

336
```java
337
import org.openqa.selenium.chrome.ChromeDriver;
338
import org.openqa.selenium.devtools.DevTools;
339
import org.openqa.selenium.devtools.v138.v138Network;
340
import org.openqa.selenium.remote.http.HttpRequest;
341
import org.openqa.selenium.remote.http.HttpResponse;
342
import org.openqa.selenium.internal.Either;
343

344
ChromeDriver driver = new ChromeDriver();
345
DevTools devTools = driver.getDevTools();
346
devTools.createSession();
347

348
v138Network network = new v138Network(devTools);
349

350
// Disable cache for testing
351
devTools.send(network.disableNetworkCaching());
352

353
// Enable request interception
354
devTools.send(network.enableFetchForAllPatterns());
355

356
// Intercept and modify requests
357
devTools.addListener(network.requestPausedEvent(), pausedReq -> {
358
    String requestId = network.getRequestId(pausedReq);
359
    
360
    // Check if this is a request or response
361
    Either<HttpRequest, HttpResponse> message = network.createSeMessages(pausedReq);
362
    
363
    if (message.isLeft()) {
364
        // Handle request modification
365
        HttpRequest request = message.left();
366
        System.out.println("Intercepted request: " + request.getUri());
367
        
368
        if (request.getUri().contains("/api/")) {
369
            // Add custom header to API requests
370
            request.addHeader("X-Custom-Header", "Modified-by-DevTools");
371
            devTools.send(network.continueRequest(pausedReq, request));
372
        } else {
373
            // Continue other requests unchanged
374
            devTools.send(network.continueWithoutModification(pausedReq));
375
        }
376
        
377
    } else {
378
        // Handle response modification
379
        HttpResponse response = message.right();
380
        System.out.println("Intercepted response: " + response.getStatus());
381
        
382
        if (response.getStatus() == 404) {
383
            // Replace 404s with custom response
384
            HttpResponse customResponse = new HttpResponse();
385
            customResponse.setStatus(200);
386
            customResponse.setContent(utf8String("Custom 404 replacement content"));
387
            customResponse.addHeader("Content-Type", "text/html");
388
            
389
            devTools.send(network.fulfillRequest(pausedReq, customResponse));
390
        } else {
391
            // Continue other responses unchanged
392
            devTools.send(network.continueWithoutModification(pausedReq));
393
        }
394
    }
395
});
396

397
// Handle authentication automatically
398
devTools.addListener(network.authRequiredEvent(), authEvent -> {
399
    String uri = network.getUriFrom(authEvent);
400
    
401
    if (uri.contains("secure-api")) {
402
        // Provide credentials for secure API
403
        UsernameAndPassword creds = new UsernameAndPassword("apikey", "secret");
404
        devTools.send(network.continueWithAuth(authEvent, creds));
405
    } else {
406
        // Cancel auth for other requests
407
        devTools.send(network.cancelAuth(authEvent));
408
    }
409
});
410

411
// Navigate and trigger network activity
412
driver.get("https://httpbin.org/get");
413
driver.get("https://httpbin.org/status/404");
414

415
// Clean up
416
devTools.send(network.disableFetch());
417
devTools.close();
418
driver.quit();
419
```
420

421
## Types
422

423
```java { .api }
424
// User agent configuration
425
class UserAgent {
426
    String userAgent();      // User agent string
427
    String acceptLanguage(); // Language preferences  
428
    String platform();       // Platform identifier
429
}
430

431
// Network authentication
432
class AuthRequired {
433
    AuthChallenge getAuthChallenge(); // Authentication challenge details
434
    RequestId getRequestId();         // Request requiring auth
435
}
436

437
class AuthChallenge {
438
    String getOrigin();   // Origin requiring authentication
439
    String getScheme();   // Authentication scheme (Basic, Digest, etc.)
440
    String getRealm();    // Authentication realm
441
}
442

443
// Request interception
444
class RequestPaused {
445
    RequestId getRequestId();                    // Unique request identifier
446
    Request getRequest();                        // Request details
447
    Optional<Integer> getResponseStatusCode();   // Response status if available
448
    Optional<List<HeaderEntry>> getResponseHeaders(); // Response headers if available
449
    Optional<ErrorReason> getResponseErrorReason(); // Error reason if failed
450
}
451
```