0
# Runtime Events
1

2
Runtime events handling and console monitoring capabilities for Chrome DevTools Protocol v138. Enables capturing JavaScript exceptions, console messages, and runtime diagnostics with full event conversion support.
3

4
## Capabilities
5

6
### Events Handler
7

8
Main events handler providing runtime event management and console API integration.
9

10
```java { .api }
11
/**
12
 * Runtime events and console handling for CDP v138
13
 * @param devtools DevTools connection for event communication
14
 */
15
public class v138Events extends Events<ConsoleAPICalled, ExceptionThrown> {
16
    public v138Events(DevTools devtools);
17
    
18
    // Public API methods inherited from Events base class
19
    public void addConsoleListener(Consumer<ConsoleEvent> listener);
20
    public void addJavascriptExceptionListener(Consumer<JavascriptException> listener);
21
    public void disable();
22
}
23
```
24

25
**Usage Example:**
26

27
```java
28
import org.openqa.selenium.devtools.v138.v138Events;
29
import org.openqa.selenium.devtools.DevTools;
30
import java.util.function.Consumer;
31

32
v138Events events = new v138Events(devTools);
33

34
// Use public API methods for event handling
35
events.addConsoleListener(console -> {
36
    System.out.println("Console " + console.getType() + ": " + 
37
        console.getArgs().get(0));
38
});
39

40
events.addJavascriptExceptionListener(exception -> {
41
    System.err.println("JavaScript Error: " + exception.getMessage());
42
});
43
```
44

45
### Public Event Listener Methods
46

47
High-level methods for registering event listeners without dealing with raw CDP events.
48

49
```java { .api }
50
/**
51
 * Add listener for console events (console.log, console.error, etc.)
52
 * @param listener Consumer that receives ConsoleEvent objects
53
 */
54
public void addConsoleListener(Consumer<ConsoleEvent> listener);
55

56
/**
57
 * Add listener for JavaScript exceptions
58
 * @param listener Consumer that receives JavascriptException objects
59
 */
60
public void addJavascriptExceptionListener(Consumer<JavascriptException> listener);
61

62
/**
63
 * Disable all event monitoring and clean up resources
64
 */
65
public void disable();
66
```
67

68
**Usage Example:**
69

70
```java
71
v138Events events = new v138Events(devTools);
72

73
// Add console listener - automatically handles event conversion
74
events.addConsoleListener(console -> {
75
    System.out.printf("[%s] %s: %s%n",
76
        console.getTimestamp(),
77
        console.getType(),
78
        console.getArgs().get(0));
79
});
80

81
// Add exception listener
82
events.addJavascriptExceptionListener(exception -> {
83
    System.err.println("JS Exception: " + exception.getMessage());
84
    exception.printStackTrace();
85
});
86

87
// Navigate and generate events
88
driver.get("https://example.com");
89
driver.executeScript("console.log('Test message'); throw new Error('Test error');");
90

91
// Clean up when done
92
events.disable();
93
```
94

95
### Runtime Domain Control
96

97
Enables and disables the Runtime domain for event reception.
98

99
```java { .api }
100
/**
101
 * Enable Runtime domain to start receiving events
102
 * @return Command to enable runtime domain
103
 */
104
@Override
105
protected Command<Void> enableRuntime();
106

107
/**
108
 * Disable Runtime domain to stop receiving events
109
 * @return Command to disable runtime domain
110
 */
111
@Override
112
protected Command<Void> disableRuntime();
113
```
114

115
### Console Event Stream
116

117
Provides access to console API events from the browser runtime.
118

119
```java { .api }
120
/**
121
 * Stream of console API events (console.log, console.error, etc.)
122
 * @return Event stream for console API calls
123
 */
124
@Override
125
protected Event<ConsoleAPICalled> consoleEvent();
126
```
127

128
**Usage Example:**
129

130
```java
131
// Listen for all console events
132
devTools.addListener(events.consoleEvent(), event -> {
133
    ConsoleEvent converted = events.toConsoleEvent(event);
134
    System.out.printf("[%s] %s: %s%n", 
135
        converted.getTimestamp(),
136
        converted.getType(),
137
        converted.getArgs().get(0));
138
});
139

140
// Now console.log calls in browser will trigger the listener
141
driver.executeScript("console.log('Hello from browser!');");
142
```
143

144
### Exception Event Stream
145

146
Provides access to JavaScript exception events from the browser runtime.
147

148
```java { .api }
149
/**
150
 * Stream of JavaScript exception events
151
 * @return Event stream for unhandled exceptions
152
 */
153
@Override
154
protected Event<ExceptionThrown> exceptionThrownEvent();
155
```
156

157
**Usage Example:**
158

159
```java
160
// Listen for JavaScript exceptions
161
devTools.addListener(events.exceptionThrownEvent(), event -> {
162
    JavascriptException jsException = events.toJsException(event);
163
    System.err.println("JavaScript Error: " + jsException.getMessage());
164
    jsException.printStackTrace();
165
});
166

167
// Now unhandled JavaScript errors will trigger the listener
168
driver.executeScript("throw new Error('Test exception');");
169
```
170

171
### Event Conversion
172

173
Converts raw CDP events to Selenium-compatible event objects.
174

175
```java { .api }
176
/**
177
 * Convert CDP ConsoleAPICalled to Selenium ConsoleEvent
178
 * @param event Raw CDP console event
179
 * @return Selenium-compatible console event
180
 */
181
@Override
182
protected ConsoleEvent toConsoleEvent(ConsoleAPICalled event);
183

184
/**
185
 * Convert CDP ExceptionThrown to JavascriptException
186
 * @param event Raw CDP exception event
187
 * @return Java exception with stack trace
188
 */
189
@Override
190
protected JavascriptException toJsException(ExceptionThrown event);
191
```
192

193
## Event Types
194

195
### ConsoleEvent Structure
196

197
```java { .api }
198
class ConsoleEvent {
199
    String getType();           // "log", "error", "warn", "info", etc.
200
    Instant getTimestamp();     // When the event occurred
201
    List<Object> getArgs();     // Console arguments as RemoteObjects
202
    List<Object> getRawArgs();  // Original CDP arguments
203
}
204
```
205

206
### JavascriptException Structure
207

208
JavaScript exceptions are converted to standard Java exceptions with reconstructed stack traces:
209

210
```java { .api }
211
class JavascriptException extends RuntimeException {
212
    String getMessage();        // Exception message or description
213
    StackTraceElement[] getStackTrace(); // Reconstructed JavaScript stack
214
}
215
```
216

217
## Runtime Event Monitoring
218

219
Complete example of runtime event monitoring setup:
220

221
```java
222
import org.openqa.selenium.chrome.ChromeDriver;
223
import org.openqa.selenium.devtools.DevTools;
224
import org.openqa.selenium.devtools.v138.v138Events;
225

226
ChromeDriver driver = new ChromeDriver();
227
DevTools devTools = driver.getDevTools();
228
devTools.createSession();
229

230
v138Events events = new v138Events(devTools);
231

232
// Enable runtime events
233
devTools.send(events.enableRuntime());
234

235
// Monitor console output
236
devTools.addListener(events.consoleEvent(), event -> {
237
    ConsoleEvent console = events.toConsoleEvent(event);
238
    System.out.printf("[Console %s] %s%n", 
239
        console.getType(), 
240
        console.getArgs().get(0));
241
});
242

243
// Monitor JavaScript exceptions
244
devTools.addListener(events.exceptionThrownEvent(), event -> {
245
    JavascriptException jsError = events.toJsException(event);
246
    System.err.println("JavaScript Exception: " + jsError.getMessage());
247
});
248

249
// Navigate and execute JavaScript
250
driver.get("https://example.com");
251
driver.executeScript("console.log('Page loaded'); console.error('Test error');");
252

253
// Clean up
254
devTools.send(events.disableRuntime());
255
devTools.close();
256
driver.quit();
257
```