0
# ZIO Test SBT
1

2
ZIO Test SBT provides SBT test framework integration for ZIO tests, enabling developers to run ZIO-based test suites within the SBT build tool ecosystem. It implements the SBT test interface standard to seamlessly integrate ZIO's functional testing capabilities with SBT's testing infrastructure.
3

4
## Package Information
5

6
- **Package Name**: zio-test-sbt_2.13
7
- **Package Type**: Maven
8
- **Organization**: dev.zio
9
- **Language**: Scala
10
- **Cross-Platform**: JVM, JavaScript (Scala.js), Native (Scala Native)
11
- **Installation**: `libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19"`
12

13
## Core Imports
14

15
```scala
16
import zio.test.sbt._
17
import zio.test.sbt.ZTestFramework
18
import zio.test.sbt.ZioSpecFingerprint
19
```
20

21
## Basic Usage
22

23
ZIO Test SBT is primarily used by SBT build tool automatically when running tests. It doesn't require direct usage in most cases - you simply configure it in your `build.sbt`:
24

25
```scala
26
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
27
```
28

29
For advanced usage scenarios involving custom test runners or event handling:
30

31
```scala
32
import zio.test.sbt._
33

34
// Create a custom summary sender
35
val summaryHandler: SendSummary = SendSummary.fromSend { summary =>
36
  println(s"Tests completed: ${summary.total}, Failed: ${summary.fail}")
37
}
38

39
// Custom event handling for integration scenarios
40
val customHandler = new ZTestEventHandlerSbt(eventHandler, taskDef, renderer)
41
```
42

43
## Architecture
44

45
ZIO Test SBT bridges ZIO's functional test framework with SBT's imperative test interface through several key components:
46

47
- **Framework Interface**: `ZTestFramework` implements SBT's Framework interface
48
- **Test Discovery**: `ZioSpecFingerprint` enables SBT to find ZIO test classes
49
- **Test Execution**: Platform-specific runners manage the ZIO test lifecycle
50
- **Event Translation**: Converts ZIO test events to SBT-compatible formats
51
- **Cross-Platform Support**: Unified API across JVM, JavaScript, and Native platforms
52

53
## Capabilities
54

55
### SBT Framework Integration
56

57
Implements the SBT test framework interface for ZIO test discovery and execution.
58

59
```scala { .api }
60
class ZTestFramework extends sbt.testing.Framework {
61
  val name: String
62
  val fingerprints: Array[sbt.testing.Fingerprint]
63
  def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): sbt.testing.Runner
64
}
65

66
object ZioSpecFingerprint extends sbt.testing.SubclassFingerprint {
67
  def superclassName(): String
68
  def isModule(): Boolean
69
  def requireNoArgConstructor(): Boolean
70
}
71
```
72

73
[SBT Framework Integration](./sbt-framework.md)
74

75
### Test Runners
76

77
Platform-specific test runners that execute ZIO tests within the SBT ecosystem.
78

79
```scala { .api }
80
// JVM Runner
81
class ZTestRunnerJVM(
82
  args: Array[String], 
83
  remoteArgs: Array[String], 
84
  testClassLoader: ClassLoader
85
) extends sbt.testing.Runner {
86
  def tasks(defs: Array[sbt.testing.TaskDef]): Array[sbt.testing.Task]
87
  def done(): String
88
}
89

90
// Cross-platform base task
91
abstract class BaseTestTask[T](
92
  taskDef: sbt.testing.TaskDef,
93
  testClassLoader: ClassLoader,
94
  sendSummary: SendSummary,
95
  args: zio.test.TestArgs,
96
  spec: zio.test.ZIOSpecAbstract,
97
  runtime: zio.Runtime[T],
98
  console: zio.Console
99
) extends sbt.testing.Task
100
```
101

102
[Test Runners](./test-runners.md)
103

104
### Event Handling
105

106
Converts ZIO test execution events to SBT-compatible event formats.
107

108
```scala { .api }
109
case class ZTestEvent(
110
  fullyQualifiedName0: String,
111
  selector0: sbt.testing.Selector,
112
  status0: sbt.testing.Status,
113
  maybeThrowable: Option[Throwable],
114
  duration0: Long,
115
  fingerprint0: sbt.testing.Fingerprint
116
) extends sbt.testing.Event
117

118
class ZTestEventHandlerSbt(
119
  eventHandler: sbt.testing.EventHandler,
120
  taskDef: sbt.testing.TaskDef,
121
  renderer: zio.test.render.TestRenderer
122
) extends zio.test.ZTestEventHandler {
123
  def handle(event: zio.test.ExecutionEvent): zio.UIO[Unit]
124
}
125
```
126

127
[Event Handling](./event-handling.md)
128

129
### Cross-Platform Support
130

131
Specialized implementations for JavaScript and Native platforms with summary protocols.
132

133
```scala { .api }
134
// Summary protocol for JS/Native inter-process communication
135
object SummaryProtocol {
136
  def serialize(summary: zio.test.Summary): String
137
  def deserialize(s: String): Option[zio.test.Summary]
138
  def escape(token: String): String
139
  def unescape(token: String): String
140
}
141

142
// Platform-specific runners
143
class ZMasterTestRunnerJS(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader)
144
class ZSlaveTestRunnerJS(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader, sendSummary: SendSummary)
145
```
146

147
[Cross-Platform Support](./cross-platform.md)
148

149
## Types
150

151
```scala { .api }
152
// Type alias for summary sending operations  
153
type SendSummary = zio.URIO[zio.test.Summary, Unit]
154

155
object SendSummary {
156
  def fromSend(send: zio.test.Summary => Unit): SendSummary
157
  def fromSendZIO(send: zio.test.Summary => zio.UIO[Unit]): SendSummary
158
  def noop: SendSummary
159
}
160

161
// Summary type from zio.test package
162
case class Summary(
163
  success: Int,
164
  fail: Int, 
165
  ignore: Int,
166
  failureDetails: String,
167
  duration: zio.Duration = zio.Duration.Zero
168
) {
169
  def add(that: Summary): Summary
170
  def add(executionEvent: zio.test.ExecutionEvent)(implicit trace: zio.Trace): Summary
171
  def status: Summary.Status
172
  def total: Int
173
  def timed(start: java.time.Instant, end: java.time.Instant): Summary
174
}
175

176
object Summary {
177
  val empty: Summary
178
  
179
  sealed trait Status
180
  object Success extends Status
181
  object Failure extends Status
182
}
183
```
184

185
## Error Handling
186

187
ZIO Test SBT handles various error scenarios:
188

189
- **ClassNotFoundException**: When test classes cannot be loaded
190
- **Runtime Failures**: ZIO runtime failures are converted to SBT failure events
191
- **Signal Handling**: JVM implementation includes signal handlers for fiber dumping
192
- **Cancellation**: Proper cleanup via cancellable futures and shutdown hooks