0
# Network Interception & Authentication
1

2
Advanced network traffic interception, request/response manipulation, authentication handling, and user agent override capabilities through the v115Network class.
3

4
## Capabilities
5

6
### Network Domain
7

8
Comprehensive network traffic control including interception, authentication, caching, and user agent management.
9

10
```java { .api }
11
/**
12
 * Network domain for traffic interception and manipulation
13
 * Extends the idealized Network class with CDP v115 specific implementations
14
 */
15
public class v115Network extends Network<AuthRequired, RequestPaused> {
16
    /**
17
     * Creates network domain with DevTools connection
18
     * @param devTools DevTools instance for CDP communication
19
     */
20
    public v115Network(DevTools devTools);
21
    
22
    /**
23
     * Set user agent override for all requests
24
     * @param userAgent UserAgent configuration with optional language and platform
25
     * @return Command to set user agent override
26
     */
27
    protected Command<Void> setUserAgentOverride(UserAgent userAgent);
28
    
29
    /**
30
     * Enable network caching
31
     * @return Command to enable network caching
32
     */
33
    protected Command<Void> enableNetworkCaching();
34
    
35
    /**
36
     * Disable network caching for testing and development
37
     * @return Command to disable network caching
38
     */
39
    protected Command<Void> disableNetworkCaching();
40
    
41
    /**
42
     * Enable fetch domain for all request patterns
43
     * @return Command to enable fetch interception
44
     */
45
    protected Command<Void> enableFetchForAllPatterns();
46
    
47
    /**
48
     * Disable fetch domain and stop request interception
49
     * @return Command to disable fetch interception
50
     */
51
    protected Command<Void> disableFetch();
52
    
53
    /**
54
     * Get authentication required event stream
55
     * @return Event stream for authentication challenges
56
     */
57
    protected Event<AuthRequired> authRequiredEvent();
58
    
59
    /**
60
     * Extract URI from authentication required event
61
     * @param authRequired Authentication event from CDP
62
     * @return URI string that requires authentication
63
     */
64
    protected String getUriFrom(AuthRequired authRequired);
65
    
66
    /**
67
     * Continue request with authentication credentials
68
     * @param authRequired Authentication event to respond to
69
     * @param credentials Username and password for authentication
70
     * @return Command to continue with authentication
71
     */
72
    protected Command<Void> continueWithAuth(AuthRequired authRequired, UsernameAndPassword credentials);
73
    
74
    /**
75
     * Cancel authentication request
76
     * @param authRequired Authentication event to cancel
77
     * @return Command to cancel authentication
78
     */
79
    protected Command<Void> cancelAuth(AuthRequired authRequired);
80
    
81
    /**
82
     * Get request paused event stream for traffic interception
83
     * @return Event stream for paused requests
84
     */
85
    public Event<RequestPaused> requestPausedEvent();
86
    
87
    /**
88
     * Create Selenium HTTP messages from paused request
89
     * @param pausedReq Request paused event from CDP
90
     * @return Either HttpRequest (for requests) or HttpResponse (for responses)
91
     */
92
    public Either<HttpRequest, HttpResponse> createSeMessages(RequestPaused pausedReq);
93
    
94
    /**
95
     * Get request ID from paused request for tracking
96
     * @param pausedReq Request paused event
97
     * @return String request identifier
98
     */
99
    protected String getRequestId(RequestPaused pausedReq);
100
    
101
    /**
102
     * Continue request without any modifications
103
     * @param pausedRequest Request to continue unchanged
104
     * @return Command to continue request
105
     */
106
    protected Command<Void> continueWithoutModification(RequestPaused pausedRequest);
107
    
108
    /**
109
     * Continue request with modifications
110
     * @param pausedReq Original paused request
111
     * @param req Modified HttpRequest to send instead
112
     * @return Command to continue with modified request
113
     */
114
    protected Command<Void> continueRequest(RequestPaused pausedReq, HttpRequest req);
115
    
116
    /**
117
     * Fulfill request with custom response
118
     * @param pausedReq Original paused request
119
     * @param res HttpResponse to return instead of making actual request
120
     * @return Command to fulfill request with response
121
     */
122
    protected Command<Void> fulfillRequest(RequestPaused pausedReq, HttpResponse res);
123
}
124
```
125

126
### User Agent Override
127

128
Set custom user agent strings for browser identification and testing different client environments.
129

130
```java { .api }
131
/**
132
 * Set user agent string (inherited from Network base class)
133
 * @param userAgent Simple user agent string
134
 */
135
public void setUserAgent(String userAgent);
136

137
/**
138
 * Set detailed user agent configuration (inherited from Network base class)
139
 * @param userAgent UserAgent object with language and platform options
140
 */
141
public void setUserAgent(UserAgent userAgent);
142
```
143

144
**Usage Examples:**
145

146
```java
147
import org.openqa.selenium.devtools.v115.v115Network;
148
import org.openqa.selenium.devtools.idealized.Network.UserAgent;
149

150
// Create network domain
151
v115Network network = new v115Network(devTools);
152

153
// Simple user agent override
154
network.setUserAgent("CustomBot/1.0");
155

156
// Detailed user agent with language and platform
157
UserAgent customAgent = new UserAgent(
158
    "Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15",
159
    Optional.of("en-US,en;q=0.9"),
160
    Optional.of("iPhone")
161
);
162
network.setUserAgent(customAgent);
163

164
// Navigate with custom user agent
165
driver.get("https://httpbin.org/user-agent");
166

167
// Verify user agent was set
168
String userAgentCheck = (String) driver.executeScript(
169
    "return navigator.userAgent;"
170
);
171
System.out.println("Active User Agent: " + userAgentCheck);
172
```
173

174
### Network Caching Control
175

176
Control browser caching behavior for testing and development scenarios.
177

178
**Usage Examples:**
179

180
```java
181
// Disable caching for testing fresh requests
182
network.disableNetworkCaching();
183
driver.get("https://example.com/api/data");
184

185
// Re-enable caching for performance
186
network.enableNetworkCaching();
187
driver.get("https://example.com/static/resources");
188
```
189

190
### Authentication Handling
191

192
Automatically handle HTTP authentication challenges with credentials.
193

194
```java { .api }
195
/**
196
 * Add authentication handler (inherited from Network base class)
197
 * @param whenThisMatches Predicate to match URIs that need authentication
198
 * @param useTheseCredentials Supplier providing credentials for matched URIs
199
 */
200
public void addAuthHandler(Predicate<URI> whenThisMatches, Supplier<Credentials> useTheseCredentials);
201
```
202

203
**Usage Examples:**
204

205
```java
206
import java.net.URI;
207
import java.util.function.Predicate;
208
import java.util.function.Supplier;
209
import org.openqa.selenium.Credentials;
210

211
// Add authentication for specific domains
212
network.addAuthHandler(
213
    uri -> uri.getHost().equals("secure.example.com"),
214
    () -> new Credentials("username", "password")
215
);
216

217
// Add authentication for API endpoints
218
network.addAuthHandler(
219
    uri -> uri.getPath().startsWith("/api/"),
220
    () -> new Credentials("api_user", "api_key_123")
221
);
222

223
// Navigate to protected resources - authentication handled automatically
224
driver.get("https://secure.example.com/protected");
225
driver.get("https://api.example.com/api/users");
226
```
227

228
### Traffic Interception
229

230
Intercept and modify network requests and responses for testing and monitoring.
231

232
```java { .api }
233
/**
234
 * Intercept traffic with custom filter (inherited from Network base class)
235
 * @param filter Filter implementation for request/response handling
236
 */
237
public void interceptTrafficWith(Filter filter);
238

239
/**
240
 * Reset network filter and stop interception (inherited from Network base class)
241
 */
242
public void resetNetworkFilter();
243
```
244

245
**Usage Examples:**
246

247
```java
248
import org.openqa.selenium.remote.http.HttpRequest;
249
import org.openqa.selenium.remote.http.HttpResponse;
250
import org.openqa.selenium.remote.http.Filter;
251

252
// Create custom traffic filter
253
Filter loggingFilter = Filter.chain(
254
    (req, next) -> {
255
        System.out.println("Request: " + req.getMethod() + " " + req.getUri());
256
        
257
        // Modify request headers
258
        req.addHeader("X-Custom-Header", "Modified-by-Selenium");
259
        
260
        HttpResponse response = next.execute(req);
261
        
262
        System.out.println("Response: " + response.getStatus() + " for " + req.getUri());
263
        
264
        // Modify response if needed
265
        if (req.getUri().toString().contains("/api/")) {
266
            response.addHeader("X-API-Response", "true");
267
        }
268
        
269
        return response;
270
    }
271
);
272

273
// Start intercepting traffic
274
network.interceptTrafficWith(loggingFilter);
275

276
// Navigate with interception active
277
driver.get("https://example.com");
278
driver.get("https://example.com/api/data");
279

280
// Stop interception
281
network.resetNetworkFilter();
282
```
283

284
### Request/Response Manipulation
285

286
Advanced request and response manipulation using low-level CDP events.
287

288
**Usage Examples:**
289

290
```java
291
import org.openqa.selenium.devtools.Event;
292
import org.openqa.selenium.devtools.v115.fetch.model.RequestPaused;
293
import org.openqa.selenium.remote.http.HttpRequest;
294
import org.openqa.selenium.remote.http.HttpResponse;
295

296
// Listen for paused requests
297
Event<RequestPaused> requestPaused = network.requestPausedEvent();
298
devTools.addListener(requestPaused, pausedReq -> {
299
    try {
300
        String requestId = network.getRequestId(pausedReq);
301
        
302
        // Create Selenium HTTP objects
303
        Either<HttpRequest, HttpResponse> either = network.createSeMessages(pausedReq);
304
        
305
        if (either.isLeft()) {
306
            // Handle request
307
            HttpRequest request = either.left();
308
            System.out.println("Intercepted request to: " + request.getUri());
309
            
310
            // Modify request
311
            if (request.getUri().toString().contains("/slow-endpoint")) {
312
                // Replace slow endpoint with fast mock
313
                HttpResponse mockResponse = new HttpResponse();
314
                mockResponse.setStatus(200);
315
                mockResponse.setContent(utf8String("{\"data\": \"mocked\"}"));
316
                mockResponse.addHeader("Content-Type", "application/json");
317
                
318
                devTools.send(network.fulfillRequest(pausedReq, mockResponse));
319
            } else {
320
                // Continue with original request
321
                devTools.send(network.continueWithoutModification(pausedReq));
322
            }
323
        } else {
324
            // Handle response
325
            HttpResponse response = either.right();
326
            System.out.println("Intercepted response: " + response.getStatus());
327
            
328
            // Always continue responses
329
            devTools.send(network.continueWithoutModification(pausedReq));
330
        }
331
    } catch (Exception e) {
332
        System.err.println("Error handling request: " + e.getMessage());
333
        devTools.send(network.continueWithoutModification(pausedReq));
334
    }
335
});
336

337
// Enable interception
338
devTools.send(network.enableFetchForAllPatterns());
339

340
// Navigate with interception active
341
driver.get("https://example.com/slow-page");
342
```
343

344
## Advanced Patterns
345

346
### API Mocking
347

348
Replace API calls with mock responses for testing:
349

350
```java
351
// Set up API mocking filter
352
Filter apiMockFilter = (req, next) -> {
353
    String uri = req.getUri().toString();
354
    
355
    if (uri.contains("/api/users")) {
356
        // Return mock user data
357
        HttpResponse mockResponse = new HttpResponse();
358
        mockResponse.setStatus(200);
359
        mockResponse.setContent(utf8String("""
360
            {
361
                "users": [
362
                    {"id": 1, "name": "Mock User 1"},
363
                    {"id": 2, "name": "Mock User 2"}
364
                ]
365
            }
366
        """));
367
        mockResponse.addHeader("Content-Type", "application/json");
368
        return mockResponse;
369
    }
370
    
371
    return next.execute(req);
372
};
373

374
network.interceptTrafficWith(apiMockFilter);
375
```
376

377
### Request Timing Analysis
378

379
Monitor and analyze request timing:
380

381
```java
382
Map<String, Long> requestTimes = new ConcurrentHashMap<>();
383

384
Filter timingFilter = (req, next) -> {
385
    String url = req.getUri().toString();
386
    long startTime = System.currentTimeMillis();
387
    
388
    HttpResponse response = next.execute(req);
389
    
390
    long duration = System.currentTimeMillis() - startTime;
391
    requestTimes.put(url, duration);
392
    
393
    System.out.println("Request to " + url + " took " + duration + "ms");
394
    
395
    return response;
396
};
397

398
network.interceptTrafficWith(timingFilter);
399
```
400

401
### Error Injection
402

403
Inject network errors for resilience testing:
404

405
```java
406
Filter errorInjectionFilter = (req, next) -> {
407
    String uri = req.getUri().toString();
408
    
409
    // Simulate 50% failure rate for specific endpoints
410
    if (uri.contains("/flaky-service") && Math.random() < 0.5) {
411
        HttpResponse errorResponse = new HttpResponse();
412
        errorResponse.setStatus(500);
413
        errorResponse.setContent(utf8String("Simulated server error"));
414
        return errorResponse;
415
    }
416
    
417
    return next.execute(req);
418
};
419

420
network.interceptTrafficWith(errorInjectionFilter);
421
```
422

423
## Error Handling
424

425
### Authentication Timeout
426

427
Authentication challenges have timeouts and can be cancelled:
428

429
```java
430
// Handle authentication with timeout
431
CompletableFuture<Void> authFuture = CompletableFuture.runAsync(() -> {
432
    // Set up auth handler with timeout logic
433
    network.addAuthHandler(
434
        uri -> uri.getHost().equals("slow-auth.example.com"),
435
        () -> {
436
            // Simulate slow credential lookup
437
            try {
438
                Thread.sleep(2000);
439
                return new Credentials("user", "pass");
440
            } catch (InterruptedException e) {
441
                Thread.currentThread().interrupt();
442
                throw new RuntimeException("Auth interrupted");
443
            }
444
        }
445
    );
446
});
447

448
try {
449
    authFuture.get(5, TimeUnit.SECONDS);
450
} catch (TimeoutException e) {
451
    System.err.println("Authentication setup timed out");
452
}
453
```
454

455
### Request Interception Errors
456

457
Handle errors in request interception gracefully:
458

459
```java
460
devTools.addListener(requestPaused, pausedReq -> {
461
    try {
462
        // Process request
463
        processInterceptedRequest(pausedReq);
464
    } catch (Exception e) {
465
        System.err.println("Error processing request: " + e.getMessage());
466
        // Always continue to avoid hanging
467
        devTools.send(network.continueWithoutModification(pausedReq));
468
    }
469
});
470
```
471

472
### Network Domain Cleanup
473

474
Properly disable network features when done:
475

476
```java
477
// Disable all network interception
478
network.resetNetworkFilter();
479
network.disable();
480
```