0
# ZIO Test SBT
1
2
ZIO Test SBT provides SBT test framework integration for ZIO, enabling developers to run ZIO-based test suites through SBT's standard testing infrastructure. It includes test task implementations that bridge ZIO's asynchronous, effect-based testing model with SBT's test interface, supporting cross-compilation for JVM, JavaScript (Scala.js), and Native platforms.
3
4
## Package Information
5
6
- **Package Name**: zio-test-sbt
7
- **Package Type**: Maven
8
- **Group ID**: dev.zio
9
- **Artifact ID**: zio-test-sbt_sjs1_3
10
- **Version**: 1.0.18
11
- **Language**: Scala
12
- **Platforms**: JVM, JavaScript (Scala.js), Native (Scala Native)
13
- **Installation**: Add to `build.sbt`:
14
```scala
15
libraryDependencies += "dev.zio" %% "zio-test-sbt" % "1.0.18"
16
```
17
18
## Core Imports
19
20
```scala { .api }
21
import zio.test.sbt._
22
```
23
24
Platform-specific imports:
25
```scala { .api }
26
// For SBT framework registration (automatically handled)
27
import zio.test.sbt.ZTestFramework
28
29
// For custom test tasks or runners
30
import zio.test.sbt.{ZTestRunner, BaseTestTask, ZTestEvent}
31
32
// For summary handling and communication
33
import zio.test.sbt.{SendSummary, SummaryProtocol}
34
```
35
36
## Basic Usage
37
38
ZIO Test SBT integrates automatically with SBT's testing infrastructure. Users typically don't interact with the API directly, but register the framework in their build configuration:
39
40
```scala
41
// In build.sbt
42
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
43
44
// Your ZIO test specifications
45
import zio.test._
46
47
object MySpec extends DefaultRunnableSpec {
48
def spec = suite("MySpec")(
49
test("example test") {
50
assert(2 + 2)(equalTo(4))
51
}
52
)
53
}
54
```
55
56
The framework automatically discovers and executes ZIO test specifications when running `sbt test`.
57
58
## Architecture
59
60
ZIO Test SBT is built around several key components that work together to bridge ZIO's effect system with SBT's testing infrastructure:
61
62
- **Framework Layer**: `ZTestFramework` serves as the entry point for SBT integration, implementing SBT's `Framework` interface
63
- **Runner Layer**: Platform-specific runners (`ZTestRunner`, `ZMasterTestRunner`, `ZSlaveTestRunner`) handle test discovery and execution coordination
64
- **Task Layer**: `BaseTestTask` and platform-specific task implementations execute individual test specifications within the ZIO runtime
65
- **Event System**: `ZTestEvent` converts ZIO test results into SBT-compatible events for reporting and IDE integration
66
- **Communication Layer**: `SendSummary` and `SummaryProtocol` handle result transmission, especially for distributed execution on JS/Native platforms
67
68
## Capabilities
69
70
### Framework Integration
71
72
Core SBT framework integration that enables ZIO test discovery and execution within SBT's testing infrastructure.
73
74
```scala { .api }
75
class ZTestFramework extends sbt.testing.Framework {
76
val name: String
77
val fingerprints: Array[sbt.testing.Fingerprint]
78
def runner(
79
args: Array[String],
80
remoteArgs: Array[String],
81
testClassLoader: ClassLoader
82
): sbt.testing.Runner
83
}
84
```
85
86
[Framework Integration](./framework-integration.md)
87
88
### Test Execution
89
90
Test execution system that runs ZIO test specifications and handles platform-specific execution models.
91
92
```scala { .api }
93
abstract class BaseTestTask(
94
taskDef: sbt.testing.TaskDef,
95
testClassLoader: ClassLoader,
96
sendSummary: SendSummary,
97
args: zio.test.TestArgs
98
) extends sbt.testing.Task {
99
def execute(
100
eventHandler: sbt.testing.EventHandler,
101
loggers: Array[sbt.testing.Logger]
102
): Array[sbt.testing.Task]
103
}
104
105
class ZTestRunner(
106
args: Array[String],
107
remoteArgs: Array[String],
108
testClassLoader: ClassLoader
109
) extends sbt.testing.Runner {
110
def tasks(defs: Array[sbt.testing.TaskDef]): Array[sbt.testing.Task]
111
def done(): String
112
}
113
```
114
115
[Test Execution](./test-execution.md)
116
117
### Event Handling and Reporting
118
119
Event system that converts ZIO test results into SBT-compatible events for reporting, IDE integration, and test result visualization.
120
121
```scala { .api }
122
case class ZTestEvent(
123
fullyQualifiedName: String,
124
selector: sbt.testing.Selector,
125
status: sbt.testing.Status,
126
maybeThrowable: Option[Throwable],
127
duration: Long,
128
fingerprint: sbt.testing.Fingerprint
129
) extends sbt.testing.Event
130
131
object ZTestEvent {
132
def from[E](
133
executedSpec: zio.test.ExecutedSpec[E],
134
fullyQualifiedName: String,
135
fingerprint: sbt.testing.Fingerprint
136
): Seq[ZTestEvent]
137
}
138
```
139
140
[Event Handling](./event-handling.md)
141
142
### Cross-Platform Communication
143
144
Communication system for handling test result transmission across different platforms, with serialization support for JavaScript and Native platforms.
145
146
```scala { .api }
147
type SendSummary = zio.URIO[zio.test.Summary, Unit]
148
149
object SendSummary {
150
def fromSend(send: zio.test.Summary => Unit): SendSummary
151
def fromSendM(send: zio.test.Summary => zio.UIO[Unit]): SendSummary
152
def noop: SendSummary
153
}
154
155
object SummaryProtocol {
156
def serialize(summary: zio.test.Summary): String
157
def deserialize(s: String): Option[zio.test.Summary]
158
}
159
```
160
161
[Cross-Platform Communication](./cross-platform-communication.md)
162
163
## Types
164
165
```scala { .api }
166
// Type alias for summary transmission
167
type SendSummary = zio.URIO[zio.test.Summary, Unit]
168
169
// Fingerprint for ZIO test discovery
170
object RunnableSpecFingerprint extends sbt.testing.SubclassFingerprint {
171
def superclassName(): String
172
def isModule(): Boolean
173
def requireNoArgConstructor(): Boolean
174
}
175
176
// Task execution policy interface
177
abstract class ZTestTaskPolicy {
178
def merge(zioTasks: Array[ZTestTask]): Array[sbt.testing.Task]
179
}
180
181
// Default task policy implementation
182
class ZTestTaskPolicyDefaultImpl extends ZTestTaskPolicy {
183
def merge(zioTasks: Array[ZTestTask]): Array[sbt.testing.Task]
184
}
185
```