0
# Console Events and JavaScript Exceptions
1

2
The events domain provides real-time monitoring of browser console output and JavaScript runtime exceptions, essential for debugging and monitoring web application behavior during automation.
3

4
## Capabilities
5

6
### V101Events
7

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

10
```java { .api }
11
/**
12
 * Handles console events and JavaScript exceptions for CDP version 101
13
 * Extends Events with ConsoleAPICalled and ExceptionThrown event types
14
 */
15
public class V101Events extends Events<ConsoleAPICalled, ExceptionThrown> {
16
    
17
    /**
18
     * Creates a new events handler instance
19
     * @param devtools DevTools instance for CDP communication
20
     */
21
    public V101Events(DevTools devtools);
22
}
23
```
24

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

27
```java { .api }
28
/**
29
 * Add a listener for console API calls (console.log, console.warn, etc.)
30
 * @param listener Consumer that receives ConsoleEvent objects
31
 */
32
public void addConsoleListener(Consumer<ConsoleEvent> listener);
33

34
/**
35
 * Add a listener for JavaScript exceptions and runtime errors
36
 * @param listener Consumer that receives JavascriptException objects
37
 */
38
public void addJavascriptExceptionListener(Consumer<JavascriptException> listener);
39

40
/**
41
 * Disable the events domain and clear all listeners
42
 * Stops receiving console and exception events
43
 */
44
public void disable();
45
```
46

47
**Usage Examples:**
48

49
```java
50
import org.openqa.selenium.devtools.v101.V101Events;
51
import org.openqa.selenium.devtools.events.ConsoleEvent;
52
import org.openqa.selenium.JavascriptException;
53

54
// Create events handler
55
V101Events events = new V101Events(devTools);
56

57
// Listen for console messages
58
events.addConsoleListener(event -> {
59
    System.out.println("Console " + event.getType() + ": " + 
60
                      String.join(" ", event.getMessages()));
61
    System.out.println("Timestamp: " + event.getTimestamp());
62
    System.out.println("Arguments: " + event.getArgs());
63
});
64

65
// Listen for JavaScript exceptions
66
events.addJavascriptExceptionListener(exception -> {
67
    System.err.println("JavaScript Error: " + exception.getMessage());
68
    exception.printStackTrace();
69
});
70

71
// Navigate to page that will generate console output
72
driver.get("https://example.com");
73

74
// Execute JavaScript that will trigger events
75
driver.executeScript("console.log('Hello from browser'); console.warn('Warning message');");
76
driver.executeScript("throw new Error('Test exception');");
77

78
// Clean up when done
79
events.disable();
80
```
81

82
### ConsoleEvent
83

84
Represents a browser console event (console.log, console.warn, console.error, etc.).
85

86
```java { .api }
87
/**
88
 * Represents a browser console API call event
89
 * Contains the console message type, timestamp, and arguments
90
 */
91
public class ConsoleEvent {
92
    
93
    /**
94
     * Get the type of console call (log, warn, error, info, debug, etc.)
95
     * @return Console call type as string
96
     */
97
    public String getType();
98
    
99
    /**
100
     * Get the timestamp when the console event occurred
101
     * @return Instant representing the event time
102
     */
103
    public Instant getTimestamp();
104
    
105
    /**
106
     * Get the raw arguments passed to the console method
107
     * @return List of objects representing console arguments
108
     */
109
    public List<Object> getArgs();
110
    
111
    /**
112
     * Get formatted string messages from the console call
113
     * @return List of formatted message strings
114
     */
115
    public List<String> getMessages();
116
}
117
```
118

119
**Console Event Types:**
120

121
- `"log"` - console.log() calls
122
- `"warn"` - console.warn() calls  
123
- `"error"` - console.error() calls
124
- `"info"` - console.info() calls
125
- `"debug"` - console.debug() calls
126
- `"trace"` - console.trace() calls
127
- `"dir"` - console.dir() calls
128
- `"table"` - console.table() calls
129

130
**Usage Example:**
131

132
```java
133
events.addConsoleListener(event -> {
134
    switch (event.getType()) {
135
        case "error":
136
            System.err.println("❌ Error: " + String.join(" ", event.getMessages()));
137
            break;
138
        case "warn":
139
            System.out.println("⚠️ Warning: " + String.join(" ", event.getMessages()));
140
            break;
141
        case "log":
142
        case "info":
143
            System.out.println("ℹ️ Info: " + String.join(" ", event.getMessages()));
144
            break;
145
        default:
146
            System.out.println("📝 " + event.getType() + ": " + String.join(" ", event.getMessages()));
147
    }
148
});
149
```
150

151
### JavascriptException
152

153
Represents a JavaScript runtime exception that occurred in the browser.
154

155
```java { .api }
156
/**
157
 * Represents a JavaScript exception that occurred in the browser
158
 * Extends RuntimeException with additional browser-specific information
159
 */
160
public class JavascriptException extends RuntimeException {
161
    
162
    /**
163
     * Creates a JavaScript exception with the specified message
164
     * @param message Exception message from the browser
165
     */
166
    public JavascriptException(String message);
167
    
168
    /**
169
     * Get the exception message
170
     * @return Exception message string
171
     */
172
    public String getMessage();
173
    
174
    /**
175
     * Get the stack trace elements from the browser
176
     * @return Array of StackTraceElement objects representing the browser stack
177
     */
178
    public StackTraceElement[] getStackTrace();
179
}
180
```
181

182
**Usage Example:**
183

184
```java
185
events.addJavascriptExceptionListener(exception -> {
186
    System.err.println("JavaScript Exception occurred:");
187
    System.err.println("Message: " + exception.getMessage());
188
    
189
    System.err.println("Browser Stack Trace:");
190
    for (StackTraceElement element : exception.getStackTrace()) {
191
        System.err.println("  at " + element.getMethodName() + 
192
                          " (" + element.getFileName() + ":" + element.getLineNumber() + ")");
193
    }
194
});
195
```
196

197
### CDP Protocol Event Types
198

199
The underlying CDP protocol event types that are converted to the higher-level ConsoleEvent and JavascriptException objects:
200

201
```java { .api }
202
/**
203
 * CDP Runtime.consoleAPICalled event data
204
 * Raw event data from the Chrome DevTools Protocol
205
 */
206
public class ConsoleAPICalled {
207
    public ConsoleAPIType getType();
208
    public List<RemoteObject> getArgs();
209
    public Timestamp getTimestamp();
210
    public Optional<ExecutionContextId> getExecutionContextId();
211
    public Optional<StackTrace> getStackTrace();
212
}
213

214
/**
215
 * CDP Runtime.exceptionThrown event data
216
 * Raw event data from the Chrome DevTools Protocol
217
 */
218
public class ExceptionThrown {
219
    public Timestamp getTimestamp();
220
    public ExceptionDetails getExceptionDetails();
221
}
222

223
/**
224
 * CDP exception details containing error information
225
 */
226
public class ExceptionDetails {
227
    public Integer getExceptionId();
228
    public String getText();
229
    public Integer getLineNumber();
230
    public Integer getColumnNumber();
231
    public Optional<String> getUrl();
232
    public Optional<StackTrace> getStackTrace();
233
    public Optional<RemoteObject> getException();
234
}
235
```
236

237
### Runtime Commands
238

239
The V101Events class internally uses these CDP Runtime domain commands:
240

241
```java { .api }
242
// From org.openqa.selenium.devtools.v101.runtime.Runtime
243
public static Command<Void> enable();
244
public static Command<Void> disable();
245
public static Event<ConsoleAPICalled> consoleAPICalled();
246
public static Event<ExceptionThrown> exceptionThrown();
247
```
248

249
## Event Processing Pipeline
250

251
**Internal Event Processing:**
252

253
1. **Enable Runtime**: Events handler enables the CDP Runtime domain
254
2. **Event Subscription**: Subscribes to `Runtime.consoleAPICalled` and `Runtime.exceptionThrown` events
255
3. **Event Conversion**: Converts CDP events to Selenium's ConsoleEvent and JavascriptException objects
256
4. **Listener Notification**: Notifies registered listeners with converted events
257
5. **Cleanup**: Disable clears listeners and disables the Runtime domain
258

259
**Error Handling:**
260

261
```java
262
// Robust event handling with error recovery
263
events.addConsoleListener(event -> {
264
    try {
265
        processConsoleEvent(event);
266
    } catch (Exception e) {
267
        System.err.println("Error processing console event: " + e.getMessage());
268
    }
269
});
270

271
events.addJavascriptExceptionListener(exception -> {
272
    try {
273
        logJavaScriptError(exception);
274
        // Could potentially recover or ignore certain types of JS errors
275
    } catch (Exception e) {
276
        System.err.println("Error processing JS exception: " + e.getMessage());
277
    }
278
});
279
```
280

281
**Performance Considerations:**
282

283
```java
284
// Efficient filtering of console events
285
events.addConsoleListener(event -> {
286
    // Only process error and warning events for performance
287
    if ("error".equals(event.getType()) || "warn".equals(event.getType())) {
288
        processImportantEvent(event);
289
    }
290
});
291
```