0
# Events Domain
1

2
Event domain implementation for console events, JavaScript exceptions, and runtime event management. Enables monitoring of browser console output, JavaScript execution errors, and runtime events for debugging and testing purposes.
3

4
## Capabilities
5

6
### Runtime Control
7

8
Enable and disable the Chrome DevTools Runtime domain to receive events.
9

10
```java { .api }
11
public Command<Void> enableRuntime();
12
public Command<Void> disableRuntime();
13
```
14

15
Usage example:
16
```java
17
v111Events events = domains.events();
18

19
// Enable runtime to receive events
20
devTools.send(events.enableRuntime());
21

22
// Later disable when done
23
devTools.send(events.disableRuntime());
24
```
25

26
### Console Event Monitoring
27

28
Monitor browser console API calls (console.log, console.error, etc.) and convert them to Selenium console events.
29

30
```java { .api }
31
public Event<ConsoleAPICalled> consoleEvent();
32
public ConsoleEvent toConsoleEvent(ConsoleAPICalled event);
33
```
34

35
Usage example:
36
```java
37
// Listen for console API calls
38
devTools.addListener(events.consoleEvent(), consoleApiCall -> {
39
    ConsoleEvent consoleEvent = events.toConsoleEvent(consoleApiCall);
40
    
41
    System.out.println("Console " + consoleEvent.getType() + ": " + 
42
                      consoleEvent.getArgs().stream()
43
                          .map(Object::toString)
44
                          .collect(Collectors.joining(" ")));
45
    
46
    // Access timestamp
47
    Instant timestamp = consoleEvent.getTimestamp();
48
    System.out.println("At: " + timestamp);
49
});
50

51
// Page code that will trigger events:
52
// console.log("Hello from page");
53
// console.error("Error occurred");
54
// console.warn("Warning message");
55
```
56

57
### JavaScript Exception Handling
58

59
Monitor JavaScript exceptions thrown in the browser and convert them to Java exceptions.
60

61
```java { .api }
62
public Event<ExceptionThrown> exceptionThrownEvent();
63
public JavascriptException toJsException(ExceptionThrown event);
64
```
65

66
Usage example:
67
```java
68
// Listen for JavaScript exceptions
69
devTools.addListener(events.exceptionThrownEvent(), exceptionThrown -> {
70
    JavascriptException jsException = events.toJsException(exceptionThrown);
71
    
72
    System.err.println("JavaScript Exception: " + jsException.getMessage());
73
    
74
    // Print stack trace
75
    for (StackTraceElement element : jsException.getStackTrace()) {
76
        System.err.println("  at " + element.getMethodName() + 
77
                          " (" + element.getFileName() + ":" + element.getLineNumber() + ")");
78
    }
79
});
80

81
// Page code that will trigger exception:
82
// throw new Error("Something went wrong");
83
// undefinedFunction(); // ReferenceError
84
```
85

86
## Types
87

88
### Console Event Types
89

90
```java { .api }
91
class ConsoleEvent {
92
    public ConsoleEvent(String type, Instant timestamp, List<Object> args, List<RemoteObject> originalArgs);
93
    public String getType();           // "log", "error", "warn", "info", etc.
94
    public Instant getTimestamp();     // When the console call occurred
95
    public List<Object> getArgs();     // Processed argument values
96
    public List<RemoteObject> getOriginalArgs(); // Original CDP RemoteObject arguments
97
}
98

99
class RemoteObject {
100
    public RemoteObject(String type, Object value);
101
    public String getType();           // "string", "number", "boolean", "object", etc.
102
    public Optional<Object> getValue(); // The actual value if primitive
103
}
104
```
105

106
### Exception Types
107

108
```java { .api }
109
class JavascriptException extends RuntimeException {
110
    public JavascriptException(String message);
111
    // Inherits standard exception methods:
112
    // public String getMessage();
113
    // public StackTraceElement[] getStackTrace();
114
    // public void setStackTrace(StackTraceElement[] stackTrace);
115
}
116
```
117

118
### CDP Event Types
119

120
```java { .api }
121
class ConsoleAPICalled {
122
    public ConsoleAPICalled.Type getType();              // Console API type
123
    public List<org.openqa.selenium.devtools.v111.runtime.model.RemoteObject> getArgs(); // Arguments
124
    public Timestamp getTimestamp();                     // CDP timestamp
125
}
126

127
class ExceptionThrown {
128
    public ExceptionDetails getExceptionDetails();       // Exception information
129
}
130

131
class ExceptionDetails {
132
    public String getText();                             // Exception message
133
    public Optional<String> getUrl();                    // Script URL where exception occurred
134
    public int getLineNumber();                          // Line number
135
    public Optional<StackTrace> getStackTrace();         // Stack trace if available
136
    public Optional<org.openqa.selenium.devtools.v111.runtime.model.RemoteObject> getException(); // Exception object
137
}
138

139
class StackTrace {
140
    public List<CallFrame> getCallFrames();             // Stack frames
141
}
142

143
class CallFrame {
144
    public String getFunctionName();                    // Function name
145
    public String getUrl();                             // Script URL
146
    public int getLineNumber();                         // Line number
147
    public int getColumnNumber();                       // Column number
148
}
149
```
150

151
## Error Handling
152

153
The Events domain automatically handles conversion of CDP events to Java-friendly formats:
154

155
- **Missing Stack Traces**: When no stack trace is available, creates a single stack trace element with available information
156
- **Timestamp Conversion**: Converts CDP timestamps to Java `Instant` objects for console events
157
- **Remote Object Processing**: Converts CDP `RemoteObject` instances to simple Java objects where possible
158
- **Exception Message Extraction**: Extracts meaningful error messages from exception details or remote objects
159

160
Example handling missing information:
161
```java
162
devTools.addListener(events.exceptionThrownEvent(), exceptionThrown -> {
163
    JavascriptException jsException = events.toJsException(exceptionThrown);
164
    
165
    // Stack trace will always be available, even if minimal
166
    StackTraceElement[] stackTrace = jsException.getStackTrace();
167
    if (stackTrace.length == 1 && "unknown".equals(stackTrace[0].getMethodName())) {
168
        System.err.println("Exception with limited stack trace information");
169
    }
170
});
171
```