0
# Runtime Events & Exception Handling
1

2
Comprehensive event handling for console messages, JavaScript exceptions, and runtime events with idealized conversion and filtering capabilities through the v115Events class.
3

4
## Capabilities
5

6
### Events Domain
7

8
Handles runtime events including console API calls and JavaScript exceptions with automatic conversion to idealized event types.
9

10
```java { .api }
11
/**
12
 * Runtime events handler providing console and exception event processing
13
 * Extends the idealized Events class with CDP v115 specific implementations
14
 */
15
public class v115Events extends Events<ConsoleAPICalled, ExceptionThrown> {
16
    /**
17
     * Creates events domain with DevTools connection
18
     * @param devtools DevTools instance for CDP communication
19
     */
20
    public v115Events(DevTools devtools);
21
    
22
    /**
23
     * Enable runtime domain for event collection
24
     * @return Command to enable runtime domain
25
     */
26
    protected Command<Void> enableRuntime();
27
    
28
    /**
29
     * Disable runtime domain and stop event collection
30
     * @return Command to disable runtime domain
31
     */
32
    protected Command<Void> disableRuntime();
33
    
34
    /**
35
     * Get console API called event stream
36
     * @return Event stream for console API calls
37
     */
38
    protected Event<ConsoleAPICalled> consoleEvent();
39
    
40
    /**
41
     * Get exception thrown event stream  
42
     * @return Event stream for JavaScript exceptions
43
     */
44
    protected Event<ExceptionThrown> exceptionThrownEvent();
45
    
46
    /**
47
     * Convert CDP console event to idealized ConsoleEvent
48
     * @param event CDP console API called event
49
     * @return Idealized console event with converted timestamp and arguments
50
     */
51
    protected ConsoleEvent toConsoleEvent(ConsoleAPICalled event);
52
    
53
    /**
54
     * Convert CDP exception event to JavascriptException
55
     * @param event CDP exception thrown event  
56
     * @return JavascriptException with stack trace and message
57
     */
58
    protected JavascriptException toJsException(ExceptionThrown event);
59
}
60
```
61

62
### Console Event Listening
63

64
Add listeners for console messages with automatic event conversion and filtering.
65

66
```java { .api }
67
/**
68
 * Add console event listener (inherited from Events base class)
69
 * @param listener Consumer to handle console events
70
 */
71
public void addConsoleListener(Consumer<ConsoleEvent> listener);
72
```
73

74
**Usage Examples:**
75

76
```java
77
import org.openqa.selenium.devtools.v115.v115Events;
78
import org.openqa.selenium.devtools.events.ConsoleEvent;
79

80
// Create events domain
81
v115Events events = new v115Events(devTools);
82

83
// Listen to all console events
84
events.addConsoleListener(event -> {
85
    System.out.println("Console Event:");
86
    System.out.println("  Type: " + event.getType());
87
    System.out.println("  Timestamp: " + event.getTimestamp());
88
    System.out.println("  Messages: " + String.join(", ", event.getMessages()));
89
    System.out.println("  Args: " + event.getArgs().size() + " arguments");
90
});
91

92
// Navigate to trigger console events
93
driver.get("https://example.com");
94
driver.executeScript("console.log('Hello from JavaScript!');");
95
driver.executeScript("console.warn('Warning message');");
96
driver.executeScript("console.error('Error message');");
97
```
98

99
### JavaScript Exception Handling
100

101
Monitor and handle JavaScript runtime exceptions with detailed stack trace information.
102

103
```java { .api }
104
/**
105
 * Add JavaScript exception listener (inherited from Events base class)
106
 * @param listener Consumer to handle JavaScript exceptions
107
 */
108
public void addJavascriptExceptionListener(Consumer<JavascriptException> listener);
109
```
110

111
**Usage Examples:**
112

113
```java
114
import org.openqa.selenium.JavascriptException;
115

116
// Listen to JavaScript exceptions
117
events.addJavascriptExceptionListener(exception -> {
118
    System.err.println("JavaScript Exception: " + exception.getMessage());
119
    
120
    // Print stack trace
121
    for (StackTraceElement element : exception.getStackTrace()) {
122
        System.err.println("  at " + element.getClassName() + "." + 
123
                          element.getMethodName() + 
124
                          "(" + element.getFileName() + ":" + 
125
                          element.getLineNumber() + ")");
126
    }
127
});
128

129
// Execute JavaScript that throws an exception
130
driver.executeScript("throw new Error('Something went wrong!');");
131
```
132

133
### Event Domain Control
134

135
Enable and disable runtime event collection as needed.
136

137
```java { .api }
138
/**
139
 * Disable event listening (inherited from Events base class)
140
 * Stops runtime domain and clears all listeners
141
 */
142
public void disable();
143
```
144

145
**Usage Examples:**
146

147
```java
148
// Events are automatically enabled when listeners are added
149
events.addConsoleListener(event -> { /* handle */ });
150

151
// Manually disable when done
152
events.disable();
153
```
154

155
## Event Conversion Details
156

157
### Console Event Conversion
158

159
The `toConsoleEvent` method performs comprehensive conversion from CDP events to idealized ConsoleEvent objects:
160

161
```java
162
// CDP ConsoleAPICalled -> ConsoleEvent conversion includes:
163
// - Timestamp conversion from CDP Timestamp to Java Instant
164
// - Argument conversion from CDP RemoteObject to idealized RemoteObject  
165
// - Type string preservation (log, warn, error, info, debug, etc.)
166
// - Message extraction and formatting
167
```
168

169
### Exception Conversion
170

171
The `toJsException` method creates JavascriptException instances with full context:
172

173
```java
174
// CDP ExceptionThrown -> JavascriptException conversion includes:
175
// - Message extraction from exception details or remote object description
176
// - Stack trace construction from CDP CallFrame information
177
// - Line number and URL preservation
178
// - Function name mapping when available
179
// - Fallback stack trace element creation for incomplete data
180
```
181

182
## Supported Console Event Types
183

184
The events system handles all standard console API types:
185

186
- **log** - Standard console.log() calls
187
- **warn** - Warning messages via console.warn()
188
- **error** - Error messages via console.error()  
189
- **info** - Information messages via console.info()
190
- **debug** - Debug messages via console.debug()
191
- **trace** - Stack traces via console.trace()
192
- **dir** - Object inspection via console.dir()
193
- **dirxml** - DOM element inspection via console.dirxml()
194
- **table** - Tabular data via console.table()
195
- **clear** - Console clearing via console.clear()
196
- **group** - Console grouping via console.group()
197
- **groupEnd** - Console group ending via console.groupEnd()
198

199
## Error Handling
200

201
### Missing Stack Traces
202

203
When CDP exception events lack stack trace information, the system creates fallback stack trace elements using available details:
204

205
```java
206
// Fallback stack trace creation
207
StackTraceElement element = new StackTraceElement(
208
    "unknown",                              // className
209
    "unknown",                              // methodName  
210
    details.getUrl().orElse("unknown"),     // fileName
211
    details.getLineNumber()                 // lineNumber
212
);
213
```
214

215
### Timestamp Conversion Errors
216

217
Console event timestamps are converted with error handling for malformed CDP timestamps:
218

219
```java
220
// Safe timestamp conversion with current time fallback
221
private long fromCdpTimestamp(Timestamp timestamp) {
222
    try {
223
        return Long.parseLong(timestamp.toString());
224
    } catch (NumberFormatException e) {
225
        return System.currentTimeMillis();
226
    }
227
}
228
```