0
# Event Handling
1

2
Event conversion and handling system that translates ZIO test execution events into SBT's event format for proper reporting and integration with build tools and IDEs.
3

4
## Capabilities
5

6
### ZTestEvent
7

8
SBT event implementation that represents the results of ZIO test execution, providing all necessary information for test reporting and IDE integration.
9

10
```scala { .api }
11
/**
12
 * SBT event implementation for ZIO test results
13
 * Converts ZIO test execution results into SBT's event format
14
 */
15
final case class ZTestEvent(
16
  fullyQualifiedName0: String,
17
  selector0: Selector,
18
  status0: Status,
19
  maybeThrowable: Option[Throwable],
20
  duration0: Long,
21
  fingerprint0: Fingerprint
22
) extends Event {
23
  /** Get test execution duration in milliseconds */
24
  def duration(): Long
25
  
26
  /** Get test fingerprint for identification */
27
  def fingerprint(): Fingerprint
28
  
29
  /** Get fully qualified name of test class */
30
  def fullyQualifiedName(): String
31
  
32
  /** Get test selector identifying specific test case */
33
  def selector(): Selector
34
  
35
  /** Get test execution status (Success, Failure, Ignored, etc.) */
36
  def status(): Status
37
  
38
  /** Get optional throwable for failed tests, wrapped in OptionalThrowable */
39
  def throwable(): OptionalThrowable
40
}
41
```
42

43
### ZTestEvent Companion Object
44

45
Factory methods for creating SBT events from ZIO test execution results.
46

47
```scala { .api }
48
object ZTestEvent {
49
  /**
50
   * Converts ZIO test execution event to SBT event
51
   * @param test ZIO test execution event containing results
52
   * @param taskDef SBT task definition for the test
53
   * @param renderer Test result renderer for formatting failure messages
54
   * @return SBT Event instance for reporting
55
   */
56
  def convertEvent(test: ExecutionEvent.Test[_], taskDef: TaskDef, renderer: TestRenderer): Event
57
  
58
  /**
59
   * Converts ZIO test result to SBT status
60
   * @param test ZIO test execution event
61
   * @return SBT Status (Success, Failure, Ignored)
62
   */
63
  private def statusFrom(test: ExecutionEvent.Test[_]): Status
64
}
65
```
66

67
**Usage Example:**
68

69
```scala
70
// Convert ZIO test event to SBT event
71
val sbtEvent = ZTestEvent.convertEvent(zioTestEvent, taskDef, renderer)
72

73
// The converted event contains:
74
// - Test name and selector for identification
75
// - Success/failure status with optional failure details
76
// - Execution duration for performance reporting  
77
// - Formatted failure messages with ANSI colors for terminal display
78
```
79

80
### ZTestEventHandlerSbt
81

82
Event handler that processes ZIO test execution events and reports them to SBT's event handling system.
83

84
```scala { .api }
85
/**
86
 * Handles ZIO test events and reports to SBT
87
 * Ensures proper test result reporting and build failure detection
88
 */
89
class ZTestEventHandlerSbt(
90
  eventHandler: EventHandler, 
91
  taskDef: TaskDef, 
92
  renderer: TestRenderer
93
) extends ZTestEventHandler {
94
  /** Semaphore for thread-safe event handling */
95
  val semaphore: Semaphore
96
  
97
  /**
98
   * Process execution events and report to SBT
99
   * @param event ZIO test execution event to handle
100
   * @return ZIO effect for event processing
101
   */
102
  def handle(event: ExecutionEvent): UIO[Unit]
103
}
104
```
105

106
### Event Processing
107

108
The event handler processes different types of ZIO test events:
109

110
**Test Execution Events:**
111
```scala { .api }
112
// Handles completed test cases (success, failure, ignored)
113
case ExecutionEvent.Test(_, _, _, _, _, _, _) =>
114
  val zTestEvent = ZTestEvent.convertEvent(evt, taskDef, renderer)
115
  semaphore.withPermit(ZIO.succeed(eventHandler.handle(zTestEvent)))
116
```
117

118
**Runtime Failure Events:**
119
```scala { .api }
120
// Handles runtime failures (exceptions, fiber failures, etc.)
121
case ExecutionEvent.RuntimeFailure(_, _, failure, _) =>
122
  val zTestEvent = ZTestEvent(
123
    taskDef.fullyQualifiedName(),
124
    taskDef.selectors().head,
125
    Status.Failure,
126
    cause.dieOption,
127
    annotations.get(TestAnnotation.timing).toMillis,
128
    ZioSpecFingerprint
129
  )
130
  semaphore.withPermit(ZIO.succeed(eventHandler.handle(zTestEvent)))
131
```
132

133
**Other Events:**
134
```scala { .api }
135
// These events are processed but don't generate SBT events
136
case ExecutionEvent.TestStarted(_, _, _, _, _) => ZIO.unit
137
case ExecutionEvent.SectionStart(_, _, _) => ZIO.unit  
138
case ExecutionEvent.SectionEnd(_, _, _) => ZIO.unit
139
case ExecutionEvent.TopLevelFlush(_) => ZIO.unit
140
```
141

142
### Status Conversion
143

144
ZIO test results are converted to SBT status values:
145

146
```scala { .api }
147
// Success cases
148
case Right(TestSuccess.Succeeded(_)) => Status.Success
149

150
// Ignored/skipped tests  
151
case Right(TestSuccess.Ignored(_)) => Status.Ignored
152

153
// Failed tests (assertions, exceptions, etc.)
154
case Left(_) => Status.Failure
155
```
156

157
### Failure Message Formatting
158

159
Failed tests include formatted failure messages with ANSI colors:
160

161
```scala { .api }
162
val status = statusFrom(test)
163
val maybeThrowable = status match {
164
  case Status.Failure =>
165
    // Includes ANSI colors for terminal display
166
    val failureMsg = renderer
167
      .render(test, true)
168
      .mkString("\n")
169
    Some(new Exception(failureMsg))
170
  case _ => None
171
}
172
```
173

174
### Thread Safety
175

176
Event handling is thread-safe through semaphore-based synchronization:
177

178
```scala { .api }
179
// Ensures only one event is processed at a time
180
val semaphore = Semaphore.unsafe.make(1L)(Unsafe.unsafe)
181

182
// All event handling goes through the semaphore
183
semaphore.withPermit(ZIO.succeed(eventHandler.handle(zTestEvent)))
184
```
185

186
### Integration Benefits
187

188
The event handling system provides:
189

190
- **IDE Integration**: Proper event reporting enables IDE test runners to display results
191
- **Build Tool Integration**: SBT can properly report test failures and halt builds
192
- **Parallel Execution**: Thread-safe handling supports concurrent test execution
193
- **Rich Formatting**: ANSI color support for enhanced terminal output
194
- **Performance Tracking**: Duration reporting for test performance analysis