0
# Network Interception and Authentication
1

2
The network domain provides comprehensive control over HTTP traffic including request/response interception, authentication handling, user agent manipulation, and caching control for advanced testing scenarios.
3

4
## Capabilities
5

6
### V101Network
7

8
Main network handler that extends the base Network class with version-specific CDP implementations.
9

10
```java { .api }
11
/**
12
 * Network interception, authentication, and traffic manipulation for CDP version 101
13
 * Extends Network with AuthRequired and RequestPaused event types
14
 */
15
public class V101Network extends Network<AuthRequired, RequestPaused> {
16
    
17
    /**
18
     * Creates a new network handler instance
19
     * @param devTools DevTools instance for CDP communication
20
     */
21
    public V101Network(DevTools devTools);
22
}
23
```
24

25
**Inherited Methods from Network Base Class:**
26

27
```java { .api }
28
/**
29
 * Set a simple user agent string override
30
 * @param userAgent User agent string to use for all requests
31
 */
32
public void setUserAgent(String userAgent);
33

34
/**
35
 * Set a comprehensive user agent configuration with additional properties
36
 * @param userAgent UserAgent object with user agent, accept language, and platform
37
 */
38
public void setUserAgent(UserAgent userAgent);
39

40
/**
41
 * Add an authentication handler for HTTP basic/digest authentication
42
 * @param whenThisMatches Predicate to match URIs that need authentication
43
 * @param useTheseCredentials Supplier providing credentials when needed
44
 */
45
public void addAuthHandler(Predicate<URI> whenThisMatches, Supplier<Credentials> useTheseCredentials);
46

47
/**
48
 * Set up traffic interception with a custom filter
49
 * @param filter Filter implementation to intercept and modify requests/responses
50
 */
51
public void interceptTrafficWith(Filter filter);
52

53
/**
54
 * Enable traffic interception for all requests and responses
55
 * Prepares the network domain for traffic monitoring
56
 */
57
public void prepareToInterceptTraffic();
58

59
/**
60
 * Remove traffic interception and reset to normal network behavior
61
 */
62
public void resetNetworkFilter();
63

64
/**
65
 * Disable the network domain and clean up all interception and auth handlers
66
 */
67
public void disable();
68
```
69

70
### UserAgent Configuration
71

72
```java { .api }
73
/**
74
 * User agent configuration with support for additional browser properties
75
 * Immutable builder pattern for constructing user agent overrides
76
 */
77
public class UserAgent {
78
    
79
    /**
80
     * Create a user agent configuration with the specified user agent string
81
     * @param userAgent The user agent string to use
82
     */
83
    public UserAgent(String userAgent);
84
    
85
    /**
86
     * Add accept language preference to the user agent configuration
87
     * @param acceptLanguage Accept-Language header value (e.g., "en-US,en;q=0.9")
88
     * @return New UserAgent instance with accept language set
89
     */
90
    public UserAgent acceptLanguage(String acceptLanguage);
91
    
92
    /**
93
     * Add platform information to the user agent configuration
94
     * @param platform Platform string (e.g., "Windows", "MacOS", "Linux")
95
     * @return New UserAgent instance with platform set
96
     */
97
    public UserAgent platform(String platform);
98
    
99
    /**
100
     * Get the user agent string
101
     * @return The configured user agent string
102
     */
103
    public String userAgent();
104
    
105
    /**
106
     * Get the accept language configuration
107
     * @return Optional accept language string
108
     */
109
    public Optional<String> acceptLanguage();
110
    
111
    /**
112
     * Get the platform configuration
113
     * @return Optional platform string
114
     */
115
    public Optional<String> platform();
116
}
117
```
118

119
**Usage Examples:**
120

121
```java
122
import org.openqa.selenium.devtools.v101.V101Network;
123
import org.openqa.selenium.devtools.idealized.Network.UserAgent;
124
import org.openqa.selenium.UsernameAndPassword;
125

126
// Create network handler
127
V101Network network = new V101Network(devTools);
128

129
// Simple user agent override
130
network.setUserAgent("Mozilla/5.0 (compatible; TestBot/1.0)");
131

132
// Comprehensive user agent configuration
133
UserAgent customAgent = new UserAgent("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36")
134
    .acceptLanguage("en-US,en;q=0.9,es;q=0.8")
135
    .platform("Win32");
136
network.setUserAgent(customAgent);
137

138
// Authentication for specific domains
139
network.addAuthHandler(
140
    uri -> uri.getHost().equals("secure.example.com"),
141
    () -> new UsernameAndPassword("testuser", "testpass")
142
);
143

144
// Traffic interception
145
network.interceptTrafficWith(request -> {
146
    System.out.println("Intercepting: " + request.getUri());
147
    
148
    // Modify request headers
149
    request.addHeader("X-Test-Header", "automation");
150
    
151
    // Continue with modified request
152
    return next -> {
153
        HttpResponse response = next.execute(request);
154
        System.out.println("Response status: " + response.getStatus());
155
        return response;
156
    };
157
});
158

159
// Enable interception
160
network.prepareToInterceptTraffic();
161

162
// Navigate and monitor traffic
163
driver.get("https://example.com");
164

165
// Clean up
166
network.disable();
167
```
168

169
### Authentication Handling
170

171
```java { .api }
172
/**
173
 * Username and password credentials for HTTP authentication
174
 */
175
public class UsernameAndPassword implements Credentials {
176
    public UsernameAndPassword(String username, String password);
177
    public String username();
178
    public String password();
179
}
180
```
181

182
**Authentication Patterns:**
183

184
```java
185
// Pattern 1: Domain-specific authentication
186
network.addAuthHandler(
187
    uri -> uri.getHost().endsWith(".internal.company.com"),
188
    () -> new UsernameAndPassword("internal-user", "internal-pass")
189
);
190

191
// Pattern 2: Path-based authentication
192
network.addAuthHandler(
193
    uri -> uri.getPath().startsWith("/admin/"),
194
    () -> new UsernameAndPassword("admin", "admin-password")
195
);
196

197
// Pattern 3: Multiple authentication schemes
198
network.addAuthHandler(
199
    uri -> uri.getHost().equals("api.service1.com"),
200
    () -> new UsernameAndPassword("service1-key", "service1-secret")
201
);
202

203
network.addAuthHandler(
204
    uri -> uri.getHost().equals("api.service2.com"),
205
    () -> new UsernameAndPassword("service2-user", "service2-pass")
206
);
207

208
// Pattern 4: Dynamic credential lookup
209
network.addAuthHandler(
210
    uri -> uri.getHost().contains("test"),
211
    () -> {
212
        // Look up credentials from configuration or external source
213
        String host = getCurrentHost(); // Your implementation
214
        return credentialStore.getCredentials(host);
215
    }
216
);
217
```
218

219
### Traffic Interception
220

221
```java { .api }
222
/**
223
 * Filter interface for intercepting and modifying HTTP traffic
224
 */
225
public interface Filter {
226
    /**
227
     * Intercept and potentially modify an HTTP request
228
     * @param request The HTTP request being made
229
     * @return Function that executes the request and returns the response
230
     */
231
    Function<Function<HttpRequest, HttpResponse>, HttpResponse> filter(HttpRequest request);
232
}
233

234
/**
235
 * HTTP request representation for interception
236
 */
237
public interface HttpRequest {
238
    String getMethod();
239
    String getUri();
240
    Map<String, List<String>> getHeaders();
241
    Optional<InputStream> getContent();
242
    void addHeader(String name, String value);
243
    void setHeader(String name, String value);
244
    void removeHeader(String name);
245
}
246

247
/**
248
 * HTTP response representation for interception
249
 */
250
public interface HttpResponse {
251
    int getStatus();
252
    Map<String, List<String>> getHeaders();
253
    Optional<InputStream> getContent();
254
    void addHeader(String name, String value);
255
    void setHeader(String name, String value);
256
}
257
```
258

259
**Traffic Interception Patterns:**
260

261
```java
262
// Pattern 1: Request modification
263
network.interceptTrafficWith(request -> {
264
    // Add custom headers to all requests
265
    request.addHeader("X-Automation-Tool", "Selenium");
266
    request.addHeader("X-Test-Run-ID", testRunId);
267
    
268
    return next -> next.execute(request);
269
});
270

271
// Pattern 2: Response inspection and modification
272
network.interceptTrafficWith(request -> {
273
    return next -> {
274
        HttpResponse response = next.execute(request);
275
        
276
        // Log response details
277
        System.out.println("Response from " + request.getUri() + ": " + response.getStatus());
278
        
279
        // Could modify response headers or content here
280
        if (response.getStatus() >= 400) {
281
            System.err.println("HTTP Error: " + response.getStatus());
282
        }
283
        
284
        return response;
285
    };
286
});
287

288
// Pattern 3: Conditional interception
289
network.interceptTrafficWith(request -> {
290
    if (request.getUri().contains("/api/")) {
291
        // Only intercept API calls
292
        request.addHeader("Authorization", "Bearer " + getApiToken());
293
        
294
        return next -> {
295
            long startTime = System.currentTimeMillis();
296
            HttpResponse response = next.execute(request);
297
            long duration = System.currentTimeMillis() - startTime;
298
            
299
            System.out.println("API call to " + request.getUri() + 
300
                             " took " + duration + "ms, status: " + response.getStatus());
301
            return response;
302
        };
303
    } else {
304
        // Pass through non-API requests unchanged
305
        return next -> next.execute(request);
306
    }
307
});
308

309
// Pattern 4: Request blocking or stubbing
310
network.interceptTrafficWith(request -> {
311
    if (request.getUri().contains("analytics") || request.getUri().contains("tracking")) {
312
        // Block analytics/tracking requests
313
        return next -> createMockResponse(200, "OK");
314
    }
315
    
316
    if (request.getUri().contains("/slow-endpoint")) {
317
        // Mock slow endpoints for faster testing
318
        return next -> createMockResponse(200, "{\"data\": \"mocked\"}");
319
    }
320
    
321
    return next -> next.execute(request);
322
});
323
```
324

325
### Network Caching Control
326

327
```java { .api }
328
/**
329
 * Enable network caching (default browser behavior)
330
 * Allows the browser to cache responses according to HTTP cache headers
331
 */
332
protected Command<Void> enableNetworkCaching();
333

334
/**
335
 * Disable network caching for all requests
336
 * Forces fresh requests for all resources, useful for testing
337
 */  
338
protected Command<Void> disableNetworkCaching();
339
```
340

341
**Usage Example:**
342

343
```java
344
// Disable caching for consistent test results
345
network.send(network.disableNetworkCaching());
346

347
// Run tests that need fresh data
348
driver.get("https://api.example.com/data");
349

350
// Re-enable caching if needed
351
network.send(network.enableNetworkCaching());
352
```
353

354
### CDP Protocol Types
355

356
The underlying CDP protocol types used by the network domain:
357

358
```java { .api }
359
/**
360
 * CDP Fetch.authRequired event data
361
 * Triggered when HTTP authentication is required
362
 */
363
public class AuthRequired {
364
    public RequestId getRequestId();
365
    public Request getRequest();
366
    public AuthChallenge getAuthChallenge();
367
}
368

369
/**
370
 * CDP Fetch.requestPaused event data  
371
 * Triggered when a request is intercepted and paused
372
 */
373
public class RequestPaused {
374
    public RequestId getRequestId();
375
    public Request getRequest();
376
    public Optional<String> getFrameId();
377
    public ResourceType getResourceType();
378
    public Optional<Integer> getResponseStatusCode();
379
    public Optional<String> getResponseErrorReason();
380
    public Optional<List<HeaderEntry>> getResponseHeaders();
381
}
382

383
/**
384
 * CDP authentication challenge information
385
 */
386
public class AuthChallenge {
387
    public String getSource(); // "Server" or "Proxy"
388
    public String getOrigin();
389
    public String getScheme(); // "Basic" or "Digest"
390
    public String getRealm();
391
}
392

393
/**
394
 * CDP HTTP header entry
395
 */
396
public class HeaderEntry {
397
    public HeaderEntry(String name, String value);
398
    public String getName();
399
    public String getValue();
400
}
401

402
/**
403
 * CDP request pattern for interception
404
 */
405
public class RequestPattern {
406
    public RequestPattern(Optional<String> urlPattern, Optional<ResourceType> resourceType, Optional<RequestStage> requestStage);
407
    public Optional<String> getUrlPattern();
408
    public Optional<ResourceType> getResourceType();
409
    public Optional<RequestStage> getRequestStage();
410
}
411
```
412

413
### Fetch Domain Commands
414

415
The V101Network class internally uses these CDP Fetch domain commands:
416

417
```java { .api }
418
// Fetch domain commands for traffic interception
419
public static Command<Void> Fetch.enable(Optional<List<RequestPattern>> patterns, Optional<Boolean> handleAuthRequests);
420
public static Command<Void> Fetch.disable();
421
public static Command<Void> Fetch.continueRequest(RequestId requestId, Optional<String> url, Optional<String> method, Optional<String> postData, Optional<List<HeaderEntry>> headers, Optional<Boolean> interceptResponse);
422
public static Command<Void> Fetch.fulfillRequest(RequestId requestId, Integer responseCode, Optional<List<HeaderEntry>> responseHeaders, Optional<String> binaryResponseHeaders, Optional<String> body, Optional<String> responsePhrase);
423
public static Command<Void> Fetch.continueWithAuth(RequestId requestId, AuthChallengeResponse authChallengeResponse);
424
public static Command<GetResponseBodyResponse> Fetch.getResponseBody(RequestId requestId);
425
public static Event<AuthRequired> Fetch.authRequired();
426
public static Event<RequestPaused> Fetch.requestPaused();
427

428
// Network domain commands for configuration
429
public static Command<Void> Network.setUserAgentOverride(String userAgent, Optional<String> acceptLanguage, Optional<String> platform, Optional<Object> userAgentMetadata);
430
public static Command<Void> Network.setCacheDisabled(Boolean cacheDisabled);
431
```
432

433
## Advanced Usage Patterns
434

435
### Performance Monitoring
436

437
```java
438
// Monitor network performance and identify slow requests
439
network.interceptTrafficWith(request -> {
440
    return next -> {
441
        long startTime = System.nanoTime();
442
        HttpResponse response = next.execute(request);
443
        long duration = System.nanoTime() - startTime;
444
        long durationMs = duration / 1_000_000;
445
        
446
        if (durationMs > 5000) { // Log requests taking > 5 seconds
447
            System.out.println("Slow request detected: " + request.getUri() + 
448
                             " took " + durationMs + "ms");
449
        }
450
        
451
        return response;
452
    };
453
});
454
```
455

456
### Request/Response Logging
457

458
```java
459
// Comprehensive request/response logging for debugging
460
network.interceptTrafficWith(request -> {
461
    System.out.println(">>> REQUEST: " + request.getMethod() + " " + request.getUri());
462
    request.getHeaders().forEach((name, values) -> 
463
        System.out.println(">>> " + name + ": " + String.join(", ", values)));
464
    
465
    return next -> {
466
        HttpResponse response = next.execute(request);
467
        
468
        System.out.println("<<< RESPONSE: " + response.getStatus());
469
        response.getHeaders().forEach((name, values) ->
470
            System.out.println("<<< " + name + ": " + String.join(", ", values)));
471
        
472
        return response;
473
    };
474
});
475
```