0
# ZIO Test SBT
1
2
ZIO Test SBT provides seamless integration between the ZIO Test framework and SBT (Simple Build Tool), enabling developers to run ZIO-based tests within standard SBT build environments. It implements the standard SBT test interface protocol to bridge ZIO's fiber-based testing model with SBT's test execution framework, supporting cross-platform compilation for JVM, Scala.js, and Scala Native targets.
3
4
The package includes platform-specific runners, event handling systems, and distributed execution support for JavaScript and Native platforms, while providing advanced features like signal handling and shared runtime management on the JVM.
5
6
## Package Information
7
8
- **Package Name**: zio-test-sbt
9
- **Package Type**: maven
10
- **Language**: Scala 3
11
- **Installation**: Add to your `build.sbt`:
12
```scala
13
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
14
libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19" % Test
15
```
16
17
## Core Imports
18
19
```scala
20
import zio.test.sbt._
21
```
22
23
For ZIO Test specs that work with this framework:
24
25
```scala
26
import zio.test._
27
import zio.test.sbt.ZTestFramework
28
import sbt.testing._
29
```
30
31
For platform-specific implementations:
32
33
```scala
34
// JVM platform
35
import zio.test.sbt.{ZTestRunnerJVM, ZTestTask}
36
37
// JavaScript platform
38
import zio.test.sbt.{ZMasterTestRunnerJS, ZSlaveTestRunnerJS}
39
40
// Scala Native platform
41
import zio.test.sbt.{ZMasterTestRunner, ZSlaveTestRunner}
42
```
43
44
## Basic Usage
45
46
ZIO Test SBT works automatically once configured in your build. SBT will discover and run your ZIO test specs:
47
48
```scala
49
// Your test spec
50
object MySpec extends ZIOSpecDefault {
51
def spec = suite("MySpec")(
52
test("simple test") {
53
assertTrue(1 + 1 == 2)
54
},
55
test("async test") {
56
for {
57
result <- ZIO.succeed(42)
58
} yield assertTrue(result == 42)
59
}
60
)
61
}
62
```
63
64
Run tests using standard SBT commands:
65
```bash
66
sbt test # Run all tests
67
sbt testOnly MySpec # Run specific test class
68
sbt testQuick # Run only failed tests
69
```
70
71
## Architecture
72
73
ZIO Test SBT is built around the SBT test interface architecture:
74
75
- **Test Framework**: `ZTestFramework` implements SBT's `Framework` interface for test discovery
76
- **Test Fingerprinting**: `ZioSpecFingerprint` tells SBT how to identify ZIO test classes
77
- **Test Runners**: Platform-specific runners (`ZTestRunnerJVM`, `ZTestRunnerJS`, `ZTestRunnerNative`) manage test execution lifecycle
78
- **Test Tasks**: `ZTestTask` and `BaseTestTask` execute individual test suites and report results
79
- **Event Handling**: `ZTestEventHandlerSbt` and `ZTestEvent` bridge ZIO test events to SBT's reporting system
80
- **Cross-Platform**: Shared base classes with JVM, JavaScript, and Scala Native specific implementations
81
82
## Capabilities
83
84
### Test Framework Integration
85
86
Core framework classes that integrate ZIO Test with SBT's test discovery and execution system.
87
88
```scala { .api }
89
class ZTestFramework extends Framework {
90
val name: String
91
val fingerprints: Array[Fingerprint]
92
def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
93
}
94
95
object ZioSpecFingerprint extends SubclassFingerprint {
96
def superclassName(): String
97
def isModule(): Boolean
98
def requireNoArgConstructor(): Boolean
99
}
100
```
101
102
[Framework Integration](./framework-integration.md)
103
104
### JVM Test Execution
105
106
JVM-specific test runner implementation with advanced features like signal handling and shared runtime management.
107
108
```scala { .api }
109
class ZTestRunnerJVM(
110
val args: Array[String],
111
val remoteArgs: Array[String],
112
testClassLoader: ClassLoader
113
) extends Runner {
114
def tasks(defs: Array[TaskDef]): Array[Task]
115
def done(): String
116
}
117
118
class ZTestTask[T](
119
taskDef: TaskDef,
120
testClassLoader: ClassLoader,
121
sendSummary: SendSummary,
122
testArgs: TestArgs,
123
spec: ZIOSpecAbstract,
124
runtime: zio.Runtime[T],
125
console: zio.Console
126
) extends BaseTestTask
127
```
128
129
[JVM Execution](./jvm-execution.md)
130
131
### Cross-Platform Test Execution
132
133
JavaScript and Scala Native test runners with distributed execution support for running tests across multiple processes or workers.
134
135
```scala { .api }
136
// JavaScript Platform
137
class ZMasterTestRunnerJS(
138
args: Array[String],
139
remoteArgs: Array[String],
140
testClassLoader: ClassLoader
141
) extends ZTestRunnerJS
142
143
class ZSlaveTestRunnerJS(
144
args: Array[String],
145
remoteArgs: Array[String],
146
testClassLoader: ClassLoader,
147
sendSummary: SendSummary
148
) extends ZTestRunnerJS
149
150
// Scala Native Platform
151
class ZMasterTestRunner(
152
args: Array[String],
153
remoteArgs: Array[String],
154
testClassLoader: ClassLoader
155
) extends ZTestRunnerNative
156
157
class ZSlaveTestRunner(
158
args: Array[String],
159
remoteArgs: Array[String],
160
testClassLoader: ClassLoader,
161
sendSummary: SendSummary
162
) extends ZTestRunnerNative
163
```
164
165
[Cross-Platform Execution](./cross-platform-execution.md)
166
167
### Event Handling and Reporting
168
169
Event handling system that converts ZIO test events to SBT-compatible events for proper test result reporting and integration.
170
171
```scala { .api }
172
class ZTestEventHandlerSbt(
173
eventHandler: EventHandler,
174
taskDef: TaskDef,
175
renderer: TestRenderer
176
) extends ZTestEventHandler {
177
def handle(event: ExecutionEvent): UIO[Unit]
178
}
179
180
case class ZTestEvent(
181
fullyQualifiedName0: String,
182
selector0: Selector,
183
status0: Status,
184
maybeThrowable: Option[Throwable],
185
duration0: Long,
186
fingerprint0: Fingerprint
187
) extends Event
188
```
189
190
[Event Handling](./event-handling.md)
191
192
## Types
193
194
```scala { .api }
195
// Package-level type aliases and utilities
196
type SendSummary = URIO[Summary, Unit]
197
198
object SendSummary {
199
def fromSend(send: Summary => Unit): SendSummary
200
def fromSendZIO(send: Summary => UIO[Unit]): SendSummary
201
def noop: SendSummary
202
}
203
204
// Base test task shared across all platforms
205
abstract class BaseTestTask(
206
taskDef0: TaskDef,
207
val testClassLoader: ClassLoader,
208
val sendSummary: SendSummary,
209
val args: TestArgs,
210
val spec: ZIOSpecAbstract,
211
val runtime: zio.Runtime[_],
212
val console: Console
213
) extends Task {
214
final def taskDef(): TaskDef = taskDef0
215
def execute(eventHandler: EventHandler, loggers: Array[Logger]): Array[Task]
216
def tags(): Array[String] = Array.empty
217
218
/** Platform-agnostic test execution */
219
private[zio] def run(eventHandlerZ: ZTestEventHandler): ZIO[Any, Throwable, Unit]
220
}
221
222
// Serialization for cross-platform execution (JS/Native only)
223
object SummaryProtocol {
224
/** Serializes Summary to tab-separated string for cross-process communication */
225
def serialize(summary: Summary): String
226
227
/** Deserializes tab-separated string back to Summary */
228
def deserialize(s: String): Option[Summary]
229
230
/** Escapes tab characters in tokens for safe serialization */
231
private def escape(token: String): String
232
233
/** Unescapes tab characters from deserialized tokens */
234
private def unescape(token: String): String
235
}
236
```