0
# Runtime Events and Console Handling
1

2
Handles runtime events like console API calls, JavaScript exceptions, and provides conversion utilities for Selenium's event system. This domain enables monitoring of browser runtime behavior and console activity.
3

4
## Capabilities
5

6
### V102Events Class
7

8
Main class for handling runtime events and console operations. Extends the idealized Events interface to provide v102-specific implementations for console monitoring and exception handling.
9

10
```java { .api }
11
/**
12
 * Handles runtime events like console API calls and exceptions
13
 */
14
public class V102Events extends Events<ConsoleAPICalled, ExceptionThrown> {
15
    /**
16
     * Creates a new V102Events instance with the specified DevTools connection
17
     * @param devtools DevTools connection instance (required)
18
     */
19
    public V102Events(DevTools devtools);
20
    
21
    /**
22
     * Enables the Runtime domain for receiving events
23
     * @return Command to enable runtime domain
24
     */
25
    protected Command<Void> enableRuntime();
26
    
27
    /**
28
     * Disables the Runtime domain to stop receiving events
29
     * @return Command to disable runtime domain
30
     */
31
    protected Command<Void> disableRuntime();
32
    
33
    /**
34
     * Returns the console API called event for monitoring console activity
35
     * @return Event for console API calls
36
     */
37
    protected Event<ConsoleAPICalled> consoleEvent();
38
    
39
    /**
40
     * Returns the exception thrown event for monitoring JavaScript exceptions
41
     * @return Event for exception notifications
42
     */
43
    protected Event<ExceptionThrown> exceptionThrownEvent();
44
    
45
    /**
46
     * Converts CDP console event to Selenium console event
47
     * @param event CDP console API called event
48
     * @return Selenium ConsoleEvent with converted data
49
     */
50
    protected ConsoleEvent toConsoleEvent(ConsoleAPICalled event);
51
    
52
    /**
53
     * Converts CDP exception event to Selenium JavaScript exception
54
     * @param event CDP exception thrown event
55
     * @return JavascriptException with stack trace and message
56
     */
57
    protected JavascriptException toJsException(ExceptionThrown event);
58
}
59
```
60

61
**Usage Examples:**
62

63
```java
64
import org.openqa.selenium.chrome.ChromeDriver;
65
import org.openqa.selenium.devtools.DevTools;
66
import org.openqa.selenium.devtools.v102.V102Domains;
67
import org.openqa.selenium.devtools.events.ConsoleEvent;
68
import org.openqa.selenium.JavascriptException;
69

70
// Setup
71
ChromeDriver driver = new ChromeDriver();
72
DevTools devTools = driver.getDevTools();
73
devTools.createSession();
74
V102Domains domains = new V102Domains(devTools);
75

76
// Enable events domain
77
domains.events().enable();
78

79
// Listen for console events
80
devTools.addListener(domains.events().consoleEvent(), (consoleEvent) -> {
81
    System.out.println("Console: " + consoleEvent.getType() + " - " + consoleEvent.getMessages());
82
});
83

84
// Listen for JavaScript exceptions
85
devTools.addListener(domains.events().exceptionThrownEvent(), (exceptionEvent) -> {
86
    JavascriptException jsException = domains.events().toJsException(exceptionEvent);
87
    System.out.println("JS Exception: " + jsException.getMessage());
88
});
89

90
// Navigate to page that will generate console output
91
driver.get("https://example.com");
92

93
// Execute JavaScript that logs to console
94
driver.executeScript("console.log('Hello from JavaScript');");
95
driver.executeScript("console.error('This is an error');");
96

97
// Cleanup
98
domains.events().disable();
99
```
100

101
### Event Conversion Methods
102

103
The V102Events class provides sophisticated conversion methods that transform low-level CDP events into Selenium's standardized event format.
104

105
#### Console Event Conversion
106

107
```java { .api }
108
/**
109
 * Converts CDP console event to Selenium console event
110
 * Handles timestamp conversion and argument processing
111
 * @param event CDP ConsoleAPICalled event with raw data
112
 * @return ConsoleEvent with processed arguments and timestamp
113
 */
114
protected ConsoleEvent toConsoleEvent(ConsoleAPICalled event);
115
```
116

117
The conversion process:
118
1. Extracts timestamp from CDP event and converts to milliseconds
119
2. Processes console arguments into RemoteObject instances
120
3. Creates Selenium ConsoleEvent with converted data
121
4. Preserves console call type (log, error, warn, etc.)
122

123
#### Exception Conversion
124

125
```java { .api }
126
/**
127
 * Converts CDP exception event to Selenium JavaScript exception
128
 * Builds stack trace from CDP exception details
129
 * @param event CDP ExceptionThrown event
130
 * @return JavascriptException with message and stack trace
131
 */
132
protected JavascriptException toJsException(ExceptionThrown event);
133
```
134

135
The conversion process:
136
1. Extracts exception message from CDP exception details
137
2. Builds Java stack trace from CDP stack trace information
138
3. Handles cases with missing stack trace data
139
4. Creates JavascriptException with proper stack trace elements
140

141
## CDP Protocol Classes
142

143
The V102Events class interacts with several generated CDP protocol classes:
144

145
### Runtime Domain Classes
146

147
```java { .api }
148
// Generated CDP runtime classes (available at runtime)
149
class Runtime {
150
    static Command<Void> enable();
151
    static Command<Void> disable();
152
    static Event<ConsoleAPICalled> consoleAPICalled();
153
    static Event<ExceptionThrown> exceptionThrown();
154
}
155

156
// Console event data
157
class ConsoleAPICalled {
158
    String getType();
159
    Timestamp getTimestamp();
160
    List<RemoteObject> getArgs();
161
}
162

163
// Exception event data
164
class ExceptionThrown {
165
    ExceptionDetails getExceptionDetails();
166
}
167

168
class ExceptionDetails {
169
    String getText();
170
    Optional<String> getUrl();
171
    int getLineNumber();
172
    Optional<StackTrace> getStackTrace();
173
    Optional<RemoteObject> getException();
174
}
175

176
class StackTrace {
177
    List<CallFrame> getCallFrames();
178
}
179

180
// Timestamp representation
181
class Timestamp {
182
    JsonElement toJson();
183
}
184
```
185

186
### Integration with Selenium Event System
187

188
```java { .api }
189
// Selenium event classes
190
class ConsoleEvent {
191
    ConsoleEvent(String type, Instant timestamp, List<Object> messages);
192
    String getType();
193
    Instant getTimestamp();
194
    List<Object> getMessages();
195
}
196

197
class JavascriptException extends RuntimeException {
198
    JavascriptException(String message);
199
    void setStackTrace(StackTraceElement[] stackTrace);
200
}
201

202
// Remote object representation
203
class RemoteObject {
204
    RemoteObject(String type, Object value);
205
    String getType();
206
    Object getValue();
207
}
208
```
209

210
## Event Monitoring Patterns
211

212
### Console Monitoring
213

214
```java
215
// Monitor all console activity
216
devTools.addListener(domains.events().consoleEvent(), (event) -> {
217
    ConsoleEvent consoleEvent = domains.events().toConsoleEvent(event);
218
    switch (consoleEvent.getType()) {
219
        case "log":
220
            System.out.println("LOG: " + consoleEvent.getMessages());
221
            break;
222
        case "error":
223
            System.err.println("ERROR: " + consoleEvent.getMessages());
224
            break;
225
        case "warn":
226
            System.out.println("WARN: " + consoleEvent.getMessages());
227
            break;
228
    }
229
});
230
```
231

232
### Exception Monitoring
233

234
```java
235
// Monitor JavaScript exceptions
236
devTools.addListener(domains.events().exceptionThrownEvent(), (event) -> {
237
    JavascriptException exception = domains.events().toJsException(event);
238
    System.err.println("JavaScript Exception: " + exception.getMessage());
239
    exception.printStackTrace();
240
});
241
```