0
# Event Handling
1

2
Runtime event handling for console messages, JavaScript exceptions, and other browser events. Provides unified access to Chrome's runtime events with proper type conversion to Selenium-compatible formats.
3

4
## Capabilities
5

6
### Console Event Monitoring
7

8
Monitor and capture console messages from the browser including console.log, console.error, console.warn, and other console API calls.
9

10
```java { .api }
11
/**
12
 * Initialize events handler for runtime events
13
 * @param devtools DevTools session instance
14
 */
15
public V105Events(DevTools devtools);
16

17
/**
18
 * Enable runtime domain for event monitoring
19
 * @return Command to enable runtime events
20
 */
21
protected Command<Void> enableRuntime();
22

23
/**
24
 * Disable runtime domain
25
 * @return Command to disable runtime events
26
 */
27
protected Command<Void> disableRuntime();
28

29
/**
30
 * Get console API called event stream
31
 * @return Event stream for console messages
32
 */
33
protected Event<ConsoleAPICalled> consoleEvent();
34

35
/**
36
 * Convert CDP console event to Selenium console event
37
 * @param event CDP console API called event
38
 * @return Selenium-compatible console event
39
 */
40
protected ConsoleEvent toConsoleEvent(ConsoleAPICalled event);
41
```
42

43
**Usage Examples:**
44

45
```java
46
import org.openqa.selenium.devtools.v105.V105Events;
47
import org.openqa.selenium.devtools.events.ConsoleEvent;
48

49
// Initialize events handler
50
V105Events events = new V105Events(devTools);
51

52
// Enable runtime events
53
devTools.send(events.enableRuntime());
54

55
// Listen for console messages
56
events.consoleEvent().addListener(consoleApiCalled -> {
57
    ConsoleEvent event = events.toConsoleEvent(consoleApiCalled);
58
    
59
    System.out.println("Console " + event.getType() + ": " + event.getMessages());
60
    System.out.println("Timestamp: " + event.getTimestamp());
61
});
62

63
// Execute JavaScript that logs to console
64
devTools.send(Runtime.evaluate("console.log('Hello from browser')"));
65
```
66

67
### Exception Handling
68

69
Capture and handle JavaScript exceptions and runtime errors from the browser.
70

71
```java { .api }
72
/**
73
 * Get JavaScript exception thrown event stream
74
 * @return Event stream for JavaScript exceptions
75
 */
76
protected Event<ExceptionThrown> exceptionThrownEvent();
77

78
/**
79
 * Convert CDP exception to Selenium JavaScript exception
80
 * @param event CDP exception thrown event
81
 * @return Selenium JavaScript exception with stack trace
82
 */
83
protected JavascriptException toJsException(ExceptionThrown event);
84
```
85

86
**Usage Examples:**
87

88
```java
89
import org.openqa.selenium.JavascriptException;
90

91
// Listen for JavaScript exceptions
92
events.exceptionThrownEvent().addListener(exceptionThrown -> {
93
    JavascriptException jsException = events.toJsException(exceptionThrown);
94
    
95
    System.err.println("JavaScript Error: " + jsException.getMessage());
96
    
97
    // Print stack trace
98
    for (StackTraceElement element : jsException.getStackTrace()) {
99
        System.err.println("  at " + element.getMethodName() + 
100
                          " (" + element.getFileName() + ":" + element.getLineNumber() + ")");
101
    }
102
});
103

104
// Execute JavaScript that throws an exception
105
devTools.send(Runtime.evaluate("throw new Error('Test exception')"));
106
```
107

108
### Event Lifecycle Management
109

110
Manage the lifecycle of runtime event monitoring with proper cleanup.
111

112
```java { .api }
113
/**
114
 * Events handler extending base Events class
115
 */
116
public class V105Events extends Events<ConsoleAPICalled, ExceptionThrown> {
117
    public V105Events(DevTools devtools);
118
}
119
```
120

121
**Usage Examples:**
122

123
```java
124
// Initialize and enable events
125
V105Events events = new V105Events(devTools);
126
devTools.send(events.enableRuntime());
127

128
// Set up multiple event listeners
129
events.consoleEvent().addListener(this::handleConsoleEvent);
130
events.exceptionThrownEvent().addListener(this::handleException);
131

132
// Execute test code
133
devTools.send(Runtime.evaluate("console.log('Starting test'); throw new Error('Test error');"));
134

135
// Clean up when done
136
devTools.send(events.disableRuntime());
137

138
private void handleConsoleEvent(ConsoleAPICalled event) {
139
    ConsoleEvent consoleEvent = events.toConsoleEvent(event);
140
    // Handle console message
141
}
142

143
private void handleException(ExceptionThrown event) {
144
    JavascriptException exception = events.toJsException(event);
145
    // Handle JavaScript exception
146
}
147
```
148

149
## Types
150

151
### Core Event Types
152

153
```java { .api }
154
// Events handler implementation
155
public class V105Events extends Events<ConsoleAPICalled, ExceptionThrown> {
156
    public V105Events(DevTools devtools);
157
}
158

159
// Selenium console event
160
public class ConsoleEvent {
161
    ConsoleEvent(String type, Instant timestamp, List<Object> messages);
162
    
163
    String getType();
164
    Instant getTimestamp();
165
    List<Object> getMessages();
166
}
167

168
// Selenium JavaScript exception
169
public class JavascriptException extends RuntimeException {
170
    JavascriptException(String message);
171
    
172
    String getMessage();
173
    StackTraceElement[] getStackTrace();
174
    void setStackTrace(StackTraceElement[] stackTrace);
175
}
176
```
177

178
### CDP Event Types
179

180
```java { .api }
181
// CDP console API called event
182
public class ConsoleAPICalled {
183
    ConsoleAPICalled.Type getType();
184
    Timestamp getTimestamp();
185
    List<RemoteObject> getArgs();
186
}
187

188
// Console message types
189
public enum ConsoleAPICalled.Type {
190
    LOG, DEBUG, INFO, ERROR, WARNING, DIR, DIRXML, TABLE, TRACE, 
191
    CLEAR, STARTGROUP, STARTGROUPCOLLAPSED, ENDGROUP, ASSERT, 
192
    PROFILE, PROFILEEND, COUNT, TIMEEND
193
}
194

195
// CDP exception thrown event
196
public class ExceptionThrown {
197
    ExceptionDetails getExceptionDetails();
198
    Timestamp getTimestamp();
199
}
200

201
// Exception details
202
public class ExceptionDetails {
203
    String getText();
204
    int getLineNumber();
205
    int getColumnNumber();
206
    Optional<String> getUrl();
207
    Optional<StackTrace> getStackTrace();
208
    Optional<RemoteObject> getException();
209
}
210

211
// Stack trace information
212
public class StackTrace {
213
    List<CallFrame> getCallFrames();
214
    Optional<String> getDescription();
215
}
216

217
// Call frame in stack trace
218
public class CallFrame {
219
    String getFunctionName();
220
    String getUrl();
221
    int getLineNumber();
222
    int getColumnNumber();
223
}
224
```
225

226
### Remote Object Types
227

228
```java { .api }
229
// JavaScript remote object
230
public class RemoteObject {
231
    RemoteObject.Type getType();
232
    Optional<Object> getValue();
233
    Optional<String> getDescription();
234
}
235

236
// Remote object types
237
public enum RemoteObject.Type {
238
    OBJECT, FUNCTION, UNDEFINED, STRING, NUMBER, BOOLEAN, SYMBOL, BIGINT
239
}
240

241
// Idealized remote object for Selenium
242
public class org.openqa.selenium.devtools.idealized.runtime.model.RemoteObject {
243
    RemoteObject(String type, Object value);
244
    
245
    String getType();
246
    Object getValue();
247
}
248
```
249

250
### Timestamp Types
251

252
```java { .api }
253
// CDP timestamp
254
public class Timestamp {
255
    Timestamp(Number timestamp);
256
    
257
    Number toJson();
258
    String toString();
259
}
260
```