0
# Event Reporting
1

2
The event reporting system converts ZIO Test execution results into SBT-compatible events for integration with SBT's testing infrastructure.
3

4
## ZTestEvent
5

6
Represents individual test execution events that are reported to SBT.
7

8
```scala { .api }
9
case class ZTestEvent(
10
  fullyQualifiedName: String,
11
  selector: Selector,
12
  status: Status,
13
  maybeThrowable: Option[Throwable],
14
  duration: Long,
15
  fingerprint: Fingerprint
16
) extends Event {
17
  def throwable(): OptionalThrowable
18
}
19
```
20

21
### Properties
22

23
- `fullyQualifiedName: String` - Fully qualified name of the test class
24
- `selector: Selector` - SBT selector identifying the specific test
25
- `status: Status` - Test execution status (Success, Failure, Ignored)
26
- `maybeThrowable: Option[Throwable]` - Optional exception if test failed
27
- `duration: Long` - Test execution duration in milliseconds
28
- `fingerprint: Fingerprint` - Test discovery fingerprint
29

30
### Methods
31

32
#### throwable()
33

34
Returns the throwable wrapped in SBT's `OptionalThrowable`.
35

36
**Returns:** `OptionalThrowable` - SBT wrapper for optional exceptions
37

38
## Platform Variations
39

40
### JVM/JavaScript-JVM Implementation
41

42
```scala { .api }
43
case class ZTestEvent(
44
  fullyQualifiedName: String,
45
  selector: Selector, 
46
  status: Status,
47
  maybeThrowable: Option[Throwable],
48
  duration: Long,
49
  fingerprint: Fingerprint
50
) extends Event
51
```
52

53
### Native Implementation
54

55
```scala { .api }
56
case class ZTestEvent(
57
  fullyQualifiedName0: String,
58
  selector0: Selector,
59
  status0: Status, 
60
  maybeThrowable: Option[Throwable],
61
  duration0: Long,
62
  fingerprint0: Fingerprint
63
) extends Event {
64
  def fullyQualifiedName(): String
65
  def selector(): Selector
66
  def status(): Status
67
  def duration(): Long  
68
  def fingerprint(): Fingerprint
69
}
70
```
71

72
The Native implementation explicitly overrides all `Event` interface methods.
73

74
## Event Creation
75

76
### ZTestEvent.from()
77

78
Creates test events from ZIO Test execution results.
79

80
```scala { .api }
81
object ZTestEvent {
82
  def from[E](
83
    executedSpec: ExecutedSpec[E],
84
    fullyQualifiedName: String,
85
    fingerprint: Fingerprint
86
  ): Seq[ZTestEvent]
87
}
88
```
89

90
**Parameters:**
91
- `executedSpec: ExecutedSpec[E]` - Executed ZIO Test specification
92
- `fullyQualifiedName: String` - Fully qualified test class name
93
- `fingerprint: Fingerprint` - Test discovery fingerprint
94

95
**Returns:** `Seq[ZTestEvent]` - Sequence of test events, one per individual test
96

97
### Event Conversion Logic
98

99
The `from` method traverses the executed specification tree and creates events:
100

101
1. **Labeled tests** - Extracts test labels for selectors
102
2. **Test results** - Converts ZIO Test results to SBT status
103
3. **Exceptions** - Maps test failures to appropriate throwable types
104
4. **Timing** - Extracts execution duration from test annotations
105

106
```scala
107
// Internal status conversion
108
private def toStatus[E](result: Either[TestFailure[E], TestSuccess]) = result match {
109
  case Left(_)                         => Status.Failure
110
  case Right(TestSuccess.Succeeded(_)) => Status.Success  
111
  case Right(TestSuccess.Ignored)      => Status.Ignored
112
}
113

114
// Internal exception conversion
115
private def toThrowable[E](
116
  spec: ExecutedSpec[E],
117
  label: Option[String], 
118
  result: Either[TestFailure[E], TestSuccess]
119
) = result.left.toOption.map {
120
  case TestFailure.Assertion(_) => new AssertionError(render(spec, label))
121
  case TestFailure.Runtime(_)   => new RuntimeException(render(spec, label))
122
}
123
```
124

125
## SBT Integration
126

127
Events are reported to SBT through the event handler:
128

129
```scala
130
// In BaseTestTask.run()
131
val events = ZTestEvent.from(spec, taskDef.fullyQualifiedName(), taskDef.fingerprint())
132
ZIO.foreach(events)(e => ZIO.effect(eventHandler.handle(e)))
133
```
134

135
## Usage Example
136

137
```scala
138
// Events are created automatically during test execution
139
import zio.test._
140
import zio.test.sbt._
141

142
// When this spec runs:
143
object MySpec extends DefaultRunnableSpec {
144
  def spec = suite("My Suite")(
145
    test("successful test") {
146
      assert(1 + 1)(equalTo(2))
147
    },
148
    test("failing test") {
149
      assert(1 + 1)(equalTo(3))
150
    }
151
  )
152
}
153

154
// ZIO Test SBT creates events like:
155
// ZTestEvent(
156
//   fullyQualifiedName = "MySpec",
157
//   selector = TestSelector("successful test"), 
158
//   status = Status.Success,
159
//   maybeThrowable = None,
160
//   duration = 5,
161
//   fingerprint = RunnableSpecFingerprint
162
// )
163
//
164
// ZTestEvent(
165
//   fullyQualifiedName = "MySpec",
166
//   selector = TestSelector("failing test"),
167
//   status = Status.Failure, 
168
//   maybeThrowable = Some(AssertionError(...)),
169
//   duration = 12,
170
//   fingerprint = RunnableSpecFingerprint  
171
// )
172
```
173

174
## Error Handling
175

176
The event system handles different types of test failures:
177

178
- **Assertion failures** - Converted to `AssertionError`
179
- **Runtime exceptions** - Converted to `RuntimeException`  
180
- **Test output** - Rendered using `DefaultTestReporter` with ANSI codes stripped
181

182
All error messages include the full test context and failure details for debugging.