0
# Event Handling
1

2
The v129Events class provides comprehensive console and exception event handling from the Chrome DevTools Protocol. It captures console messages, JavaScript exceptions, and converts them to Selenium-compatible event objects.
3

4
## Capabilities
5

6
### Events Domain
7

8
Core events domain for console and exception handling.
9

10
```java { .api }
11
/**
12
 * Events domain for console and exception handling
13
 * @param devtools - DevTools instance for protocol communication
14
 */
15
public class v129Events extends Events<ConsoleAPICalled, ExceptionThrown> {
16
    public v129Events(DevTools devtools);
17
}
18
```
19

20
### Runtime Domain Control
21

22
Enable and disable the Runtime domain for event capture.
23

24
```java { .api }
25
/**
26
 * Enables the Runtime domain to start receiving events
27
 * @return Command to enable Runtime domain
28
 */
29
protected Command<Void> enableRuntime();
30

31
/**
32
 * Disables the Runtime domain to stop receiving events
33
 * @return Command to disable Runtime domain
34
 */
35
protected Command<Void> disableRuntime();
36
```
37

38
### Console Event Handling
39

40
Capture and process console API calls from the browser.
41

42
```java { .api }
43
/**
44
 * Event fired when console API is called (console.log, console.error, etc.)
45
 * @return Event for console API calls
46
 */
47
protected Event<ConsoleAPICalled> consoleEvent();
48

49
/**
50
 * Converts CDP console event to Selenium ConsoleEvent
51
 * @param event - ConsoleAPICalled event from CDP
52
 * @return ConsoleEvent with processed timestamp and arguments
53
 */
54
protected ConsoleEvent toConsoleEvent(ConsoleAPICalled event);
55
```
56

57
### Exception Event Handling
58

59
Capture and process JavaScript exceptions from the browser.
60

61
```java { .api }
62
/**
63
 * Event fired when a JavaScript exception is thrown
64
 * @return Event for JavaScript exceptions
65
 */
66
protected Event<ExceptionThrown> exceptionThrownEvent();
67

68
/**
69
 * Converts CDP exception event to JavascriptException
70
 * @param event - ExceptionThrown event from CDP
71
 * @return JavascriptException with stack trace and error details
72
 */
73
protected JavascriptException toJsException(ExceptionThrown event);
74
```
75

76
**Usage Examples:**
77

78
```java
79
import org.openqa.selenium.devtools.v129.v129Events;
80
import org.openqa.selenium.devtools.DevTools;
81
import org.openqa.selenium.devtools.events.ConsoleEvent;
82
import org.openqa.selenium.JavascriptException;
83

84
// Create events domain
85
DevTools devTools = driver.getDevTools();
86
v129Events events = new v129Events(devTools);
87

88
// Enable runtime for event capture
89
devTools.send(events.enableRuntime());
90

91
// Listen for console events
92
devTools.addListener(events.consoleEvent(), consoleEvent -> {
93
    ConsoleEvent seleniumEvent = events.toConsoleEvent(consoleEvent);
94
    System.out.println("Console " + seleniumEvent.getType() + ": " + 
95
                      seleniumEvent.getMessages());
96
});
97

98
// Listen for JavaScript exceptions
99
devTools.addListener(events.exceptionThrownEvent(), exceptionEvent -> {
100
    JavascriptException jsException = events.toJsException(exceptionEvent);
101
    System.err.println("JavaScript Error: " + jsException.getMessage());
102
    jsException.printStackTrace();
103
});
104

105
// Navigate to trigger events
106
driver.get("https://example.com");
107

108
// Execute JavaScript that generates console output
109
driver.executeScript("console.log('Hello from JavaScript');");
110
driver.executeScript("console.error('This is an error message');");
111

112
// Execute JavaScript that throws an exception
113
try {
114
    driver.executeScript("throw new Error('Test exception');");
115
} catch (Exception e) {
116
    // Exception will also be captured by DevTools listener
117
}
118

119
// Cleanup
120
devTools.send(events.disableRuntime());
121
```
122

123
### Advanced Event Processing
124

125
```java
126
// Filter console events by type
127
devTools.addListener(events.consoleEvent(), consoleEvent -> {
128
    ConsoleEvent event = events.toConsoleEvent(consoleEvent);
129
    switch (event.getType()) {
130
        case "log":
131
            // Handle regular log messages
132
            break;
133
        case "error":
134
            // Handle error messages
135
            break;
136
        case "warn":
137
            // Handle warning messages
138
            break;
139
        case "debug":
140
            // Handle debug messages
141
            break;
142
    }
143
});
144

145
// Extract stack trace from exceptions
146
devTools.addListener(events.exceptionThrownEvent(), exceptionEvent -> {
147
    JavascriptException jsException = events.toJsException(exceptionEvent);
148
    
149
    // Get stack trace elements
150
    StackTraceElement[] stackTrace = jsException.getStackTrace();
151
    for (StackTraceElement element : stackTrace) {
152
        System.out.println("  at " + element.getMethodName() + 
153
                          " (" + element.getFileName() + ":" + element.getLineNumber() + ")");
154
    }
155
});
156
```
157

158
## Types
159

160
### Console Event Types
161

162
```java { .api }
163
// From v129.runtime.model package
164
import org.openqa.selenium.devtools.v129.runtime.model.ConsoleAPICalled;
165
import org.openqa.selenium.devtools.v129.runtime.model.ExceptionThrown;
166
import org.openqa.selenium.devtools.v129.runtime.model.ExceptionDetails;
167
import org.openqa.selenium.devtools.v129.runtime.model.StackTrace;
168

169
// Selenium event types
170
import org.openqa.selenium.devtools.events.ConsoleEvent;
171
import org.openqa.selenium.JavascriptException;
172
```
173

174
### Console Event Structure
175

176
```java { .api }
177
// ConsoleEvent from Selenium
178
class ConsoleEvent {
179
    public ConsoleEvent(
180
        String type,
181
        Instant timestamp,
182
        List<Object> messages,
183
        List<RemoteObject> args
184
    );
185
    
186
    public String getType();
187
    public Instant getTimestamp();
188
    public List<Object> getMessages();
189
    public List<RemoteObject> getArgs();
190
}
191
```
192

193
### Exception Details
194

195
```java { .api }
196
// ExceptionDetails from CDP
197
class ExceptionDetails {
198
    public String getText();
199
    public Optional<String> getUrl();
200
    public int getLineNumber();
201
    public Optional<StackTrace> getStackTrace();
202
    public Optional<RemoteObject> getException();
203
}
204

205
// StackTrace from CDP
206
class StackTrace {
207
    public List<CallFrame> getCallFrames();
208
}
209

210
// CallFrame from CDP
211
class CallFrame {
212
    public String getFunctionName();
213
    public String getUrl();
214
    public int getLineNumber();
215
    public int getColumnNumber();
216
}
217
```
218

219
### Remote Object Types
220

221
```java { .api }
222
// RemoteObject for console arguments
223
import org.openqa.selenium.devtools.idealized.runtime.model.RemoteObject;
224

225
class RemoteObject {
226
    public RemoteObject(String type, Object value);
227
    public String getType();
228
    public Optional<Object> getValue();
229
    public Optional<String> getDescription();
230
}
231
```