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
```