0
# Event Handling
1

2
JavaScript console monitoring, exception tracking, and runtime event handling with full Chrome DevTools Protocol v110 integration for comprehensive browser event observation.
3

4
## Capabilities
5

6
### Events Domain Wrapper
7

8
High-level wrapper for CDP runtime events providing type-safe access to console events and JavaScript exceptions.
9

10
```java { .api }
11
/**
12
 * Events domain wrapper for CDP v110 runtime events
13
 */
14
public class v110Events extends Events<ConsoleAPICalled, ExceptionThrown> {
15
    /**
16
     * Initialize events domain with DevTools session
17
     * @param devtools Active DevTools session
18
     */
19
    public v110Events(DevTools devtools);
20
}
21
```
22

23
### Runtime Domain Control
24

25
Enable and disable the runtime domain for event monitoring.
26

27
```java { .api }
28
/**
29
 * Enable runtime domain for event monitoring
30
 * @return Command to enable runtime
31
 */
32
protected Command<Void> enableRuntime();
33

34
/**
35
 * Disable runtime domain
36
 * @return Command to disable runtime  
37
 */
38
protected Command<Void> disableRuntime();
39
```
40

41
### Console Event Monitoring
42

43
Monitor JavaScript console API calls including console.log, console.error, console.warn, and other console methods.
44

45
```java { .api }
46
/**
47
 * Get console API called events
48
 * @return Event stream for console API calls
49
 */
50
protected Event<ConsoleAPICalled> consoleEvent();
51

52
/**
53
 * Convert CDP console event to Selenium console event
54
 * @param event CDP console API called event
55
 * @return Selenium console event
56
 */
57
protected ConsoleEvent toConsoleEvent(ConsoleAPICalled event);
58
```
59

60
**Usage Example:**
61

62
```java
63
import org.openqa.selenium.devtools.events.ConsoleEvent;
64
import org.openqa.selenium.devtools.v110.v110Events;
65

66
v110Events events = new v110Events(devTools);
67

68
// Enable runtime for console monitoring
69
devTools.send(events.enableRuntime());
70

71
// Add console listener
72
events.addConsoleListener(consoleEvent -> {
73
    System.out.println("Console Type: " + consoleEvent.getType());
74
    System.out.println("Timestamp: " + consoleEvent.getTimestamp());
75
    System.out.println("Messages: " + consoleEvent.getMessages());
76
});
77

78
// Navigate to page that generates console output
79
driver.get("https://example.com");
80
```
81

82
### Exception Tracking
83

84
Monitor JavaScript exceptions and runtime errors with full stack trace information.
85

86
```java { .api }
87
/**
88
 * Get exception thrown events  
89
 * @return Event stream for JavaScript exceptions
90
 */
91
protected Event<ExceptionThrown> exceptionThrownEvent();
92

93
/**
94
 * Convert CDP exception to JavascriptException
95
 * @param event CDP exception thrown event
96
 * @return JavaScript exception with stack trace
97
 */
98
protected JavascriptException toJsException(ExceptionThrown event);
99
```
100

101
**Usage Example:**
102

103
```java
104
import org.openqa.selenium.JavascriptException;
105
import org.openqa.selenium.devtools.v110.runtime.model.ExceptionThrown;
106

107
// Add exception listener
108
devTools.addListener(events.exceptionThrownEvent(), exceptionEvent -> {
109
    JavascriptException jsException = events.toJsException(exceptionEvent);
110
    System.err.println("JavaScript Error: " + jsException.getMessage());
111
    jsException.printStackTrace();
112
});
113
```
114

115
### High-Level Event Listeners
116

117
Convenient methods for common event monitoring scenarios.
118

119
```java { .api }
120
/**
121
 * Add console event listener with automatic runtime management
122
 * @param consumer Function to handle console events
123
 */
124
public void addConsoleListener(Consumer<ConsoleEvent> consumer);
125

126
/**
127
 * Add JavaScript exception listener  
128
 * @param consumer Function to handle JavaScript exceptions
129
 */
130
public void addJavaScriptExceptionListener(Consumer<JavascriptException> consumer);
131
```
132

133
## CDP Domain Classes
134

135
### Runtime Domain
136

137
Direct access to CDP Runtime domain for low-level runtime operations.
138

139
```java { .api }
140
import org.openqa.selenium.devtools.v110.runtime.Runtime;
141

142
/**
143
 * Enable runtime domain
144
 */
145
public static Command<Void> enable();
146

147
/**
148
 * Disable runtime domain
149
 */
150
public static Command<Void> disable();
151

152
/**
153
 * Console API called event
154
 */
155
public static Event<ConsoleAPICalled> consoleAPICalled();
156

157
/**
158
 * Exception thrown event
159
 */
160
public static Event<ExceptionThrown> exceptionThrown();
161
```
162

163
## Model Classes
164

165
### Console Event Models
166

167
```java { .api }
168
import org.openqa.selenium.devtools.v110.runtime.model.*;
169
import org.openqa.selenium.devtools.events.ConsoleEvent;
170

171
/**
172
 * CDP console API called event
173
 */
174
public class ConsoleAPICalled {
175
    /**
176
     * Console API type (log, error, warn, etc.)
177
     */
178
    ConsoleAPICalledType getType();
179
    
180
    /**
181
     * Console arguments as remote objects
182
     */
183
    List<RemoteObject> getArgs();
184
    
185
    /**
186
     * Event timestamp
187
     */
188
    Timestamp getTimestamp();
189
    
190
    /**
191
     * Execution context ID
192
     */
193
    Optional<ExecutionContextId> getExecutionContextId();
194
}
195

196
/**
197
 * Console API call types
198
 */
199
public enum ConsoleAPICalledType {
200
    LOG, DEBUG, INFO, ERROR, WARNING, DIR, DIRXML, TABLE, TRACE, 
201
    CLEAR, STARTGROUP, STARTGROUPCOLLAPSED, ENDGROUP, ASSERT, 
202
    PROFILE, PROFILEEND, COUNT, TIMEEND
203
}
204

205
/**
206
 * Selenium console event (high-level)
207
 */
208
public class ConsoleEvent {
209
    String getType();
210
    Instant getTimestamp();
211
    List<Object> getMessages();
212
    List<RemoteObject> getRawMessages();
213
}
214
```
215

216
### Exception Event Models
217

218
```java { .api }
219
/**
220
 * CDP exception thrown event
221
 */
222
public class ExceptionThrown {
223
    /**
224
     * Exception details with stack trace
225
     */
226
    ExceptionDetails getExceptionDetails();
227
    
228
    /**
229
     * Event timestamp
230
     */
231
    Timestamp getTimestamp();
232
}
233

234
/**
235
 * JavaScript exception details
236
 */
237
public class ExceptionDetails {
238
    /**
239
     * Exception message text
240
     */
241
    String getText();
242
    
243
    /**
244
     * Source URL where exception occurred
245
     */
246
    Optional<String> getUrl();
247
    
248
    /**
249
     * Line number in source
250
     */
251
    Integer getLineNumber();
252
    
253
    /**
254
     * Column number in source  
255
     */
256
    Integer getColumnNumber();
257
    
258
    /**
259
     * Exception object details
260
     */
261
    Optional<RemoteObject> getException();
262
    
263
    /**
264
     * Stack trace information
265
     */
266
    Optional<StackTrace> getStackTrace();
267
}
268

269
/**
270
 * JavaScript stack trace
271
 */
272
public class StackTrace {
273
    /**
274
     * Stack frame descriptions
275
     */
276
    String getDescription();
277
    
278
    /**
279
     * Individual call frames
280
     */
281
    List<CallFrame> getCallFrames();
282
}
283

284
/**
285
 * Individual stack frame
286
 */
287
public class CallFrame {
288
    /**
289
     * Function name
290
     */
291
    String getFunctionName();
292
    
293
    /**
294
     * Source URL
295
     */
296
    String getUrl();
297
    
298
    /**
299
     * Line number
300
     */
301
    Integer getLineNumber();
302
    
303
    /**
304
     * Column number
305
     */
306
    Integer getColumnNumber();
307
}
308
```
309

310
### Remote Object Models
311

312
```java { .api }
313
/**
314
 * JavaScript remote object representation
315
 */
316
public class RemoteObject {
317
    /**
318
     * Object type (object, function, undefined, string, number, boolean, symbol, bigint)
319
     */
320
    RemoteObjectType getType();
321
    
322
    /**
323
     * Object subtype (array, null, node, regexp, date, map, set, etc.)
324
     */
325
    Optional<RemoteObjectSubtype> getSubtype();
326
    
327
    /**
328
     * Object value (for primitive types)
329
     */
330
    Optional<Object> getValue();
331
    
332
    /**
333
     * String description of object
334
     */
335
    Optional<String> getDescription();
336
    
337
    /**
338
     * Object ID for further operations
339
     */
340
    Optional<RemoteObjectId> getObjectId();
341
}
342

343
/**
344
 * Idealized remote object (Selenium wrapper)
345
 */
346
public class org.openqa.selenium.devtools.idealized.runtime.model.RemoteObject {
347
    String getType();
348
    Object getValue();
349
}
350
```
351

352
### Timestamp Models
353

354
```java { .api }
355
/**
356
 * CDP timestamp representation
357
 */
358
public class Timestamp {
359
    /**
360
     * Convert to JSON number
361
     */
362
    Number toJson();
363
    
364
    /**
365
     * String representation
366
     */
367
    String toString();
368
}
369
```
370

371
## Advanced Usage Examples
372

373
### Comprehensive Console Monitoring
374

375
```java
376
v110Events events = new v110Events(devTools);
377
devTools.send(events.enableRuntime());
378

379
// Monitor all console activity with detailed information
380
events.addConsoleListener(event -> {
381
    String logLevel = event.getType();
382
    Instant timestamp = event.getTimestamp();
383
    List<Object> messages = event.getMessages();
384
    
385
    System.out.printf("[%s] %s: %s%n", 
386
        timestamp, logLevel, messages);
387
        
388
    // Access raw CDP objects for detailed inspection
389
    List<RemoteObject> rawMessages = event.getRawMessages();
390
    for (RemoteObject obj : rawMessages) {
391
        if (obj.getType().toString().equals("object")) {
392
            System.out.println("Object details: " + obj.getDescription());
393
        }
394
    }
395
});
396
```
397

398
### Exception Monitoring with Stack Traces
399

400
```java
401
devTools.addListener(events.exceptionThrownEvent(), exceptionEvent -> {
402
    ExceptionDetails details = exceptionEvent.getExceptionDetails();
403
    
404
    System.err.println("Exception: " + details.getText());
405
    System.err.println("Location: " + details.getUrl().orElse("unknown") + 
406
                       ":" + details.getLineNumber());
407
    
408
    // Process stack trace
409
    details.getStackTrace().ifPresent(stackTrace -> {
410
        System.err.println("Stack trace:");
411
        for (CallFrame frame : stackTrace.getCallFrames()) {
412
            System.err.printf("  at %s (%s:%d:%d)%n",
413
                frame.getFunctionName(),
414
                frame.getUrl(), 
415
                frame.getLineNumber(),
416
                frame.getColumnNumber());
417
        }
418
    });
419
});
420
```
421

422
## Error Handling
423

424
Event monitoring operations may encounter various error conditions:
425

426
```java  
427
import org.openqa.selenium.devtools.DevToolsException;
428

429
// Handle runtime enablement failures
430
try {
431
    devTools.send(events.enableRuntime());
432
} catch (DevToolsException e) {
433
    System.err.println("Failed to enable runtime domain: " + e.getMessage());
434
}
435

436
// Handle event listener failures
437
events.addConsoleListener(event -> {
438
    try {
439
        // Process console event
440
        processConsoleEvent(event);
441
    } catch (Exception e) {
442
        System.err.println("Error processing console event: " + e.getMessage());
443
    }
444
});
445
```