0
# ZIO Test SBT
1

2
ZIO Test SBT provides a comprehensive SBT test framework integration for ZIO Test, enabling seamless execution of ZIO-based tests within SBT build environments. It offers cross-platform support for JVM, JavaScript, and Scala Native platforms through a unified test interface implementation.
3

4
## Package Information
5

6
- **Package Name**: zio-test-sbt_3
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Group ID**: dev.zio
10
- **Installation**: `libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19"`
11

12
## Core Imports
13

14
```scala
15
import zio.test.sbt._
16
```
17

18
For SBT framework usage:
19

20
```scala
21
import zio.test.sbt.ZTestFramework
22
```
23

24
For event handling:
25

26
```scala
27
import zio.test.sbt.{ZTestEvent, ZTestEventHandlerSbt}
28
```
29

30
## Basic Usage
31

32
ZIO Test SBT is primarily configured through SBT's test framework mechanism. In your `build.sbt`:
33

34
```scala
35
// Enable ZIO Test framework
36
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
37

38
// Your ZIO test specifications
39
libraryDependencies += "dev.zio" %% "zio-test" % "2.1.19" % Test
40
libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19" % Test
41
```
42

43
Example ZIO test specification that works with this framework:
44

45
```scala
46
import zio.test._
47
import zio.test.Assertion._
48

49
object MyZIOSpec extends ZIOSpecDefault {
50
  def spec = suite("MyTests")(
51
    test("example test") {
52
      assert(1 + 1)(equalTo(2))
53
    }
54
  )
55
}
56
```
57

58
## Architecture
59

60
ZIO Test SBT is built around the SBT Testing Interface with several key components:
61

62
- **Framework Integration**: `ZTestFramework` implements SBT's `Framework` interface, providing discovery and runner creation
63
- **Test Discovery**: `ZioSpecFingerprint` enables SBT to find ZIO test specifications in the classpath  
64
- **Platform-Specific Runners**: Separate implementations for JVM, JavaScript, and Native platforms handle test execution
65
- **Event System**: Converts ZIO test events to SBT events for proper integration with build tools and IDEs
66
- **Cross-Platform Design**: Shared abstractions with platform-specific optimizations for each target environment
67

68
## Capabilities
69

70
### Framework Integration
71

72
Core SBT framework implementation that enables ZIO Test to be recognized and executed by SBT, providing the primary entry point for test discovery and execution.
73

74
```scala { .api }
75
final class ZTestFramework extends Framework {
76
  val name: String
77
  val fingerprints: Array[Fingerprint]
78
  def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
79
}
80
```
81

82
[Framework Integration](./framework-integration.md)
83

84
### Test Discovery
85

86
Test specification discovery mechanism that allows SBT to identify ZIO test classes and convert them into executable test tasks.
87

88
```scala { .api }
89
object ZioSpecFingerprint extends SubclassFingerprint {
90
  def superclassName(): String
91
  def isModule(): Boolean  
92
  def requireNoArgConstructor(): Boolean
93
}
94
```
95

96
[Test Discovery](./test-discovery.md)
97

98
### Event Handling
99

100
Event conversion and handling system that translates ZIO test execution events into SBT's event format for proper reporting and integration.
101

102
```scala { .api }
103
final case class ZTestEvent(
104
  fullyQualifiedName0: String,
105
  selector0: Selector,
106
  status0: Status,
107
  maybeThrowable: Option[Throwable],
108
  duration0: Long,
109
  fingerprint0: Fingerprint
110
) extends Event
111

112
class ZTestEventHandlerSbt(
113
  eventHandler: EventHandler, 
114
  taskDef: TaskDef, 
115
  renderer: TestRenderer
116
) extends ZTestEventHandler {
117
  def handle(event: ExecutionEvent): UIO[Unit]
118
}
119
```
120

121
[Event Handling](./event-handling.md)
122

123
### JVM Platform Support
124

125
Full-featured JVM test runner with advanced debugging capabilities, signal handling, and comprehensive SBT integration features.
126

127
```scala { .api }
128
final class ZTestRunnerJVM(
129
  args: Array[String], 
130
  remoteArgs: Array[String], 
131
  testClassLoader: ClassLoader
132
) extends Runner {
133
  def tasks(defs: Array[TaskDef]): Array[Task]
134
  def done(): String
135
}
136
```
137

138
[JVM Platform Support](./jvm-platform.md)
139

140
### JavaScript Platform Support
141

142
Lightweight JavaScript test runner with master/slave architecture for distributed test execution and inter-process communication through serialized summaries.
143

144
```scala { .api }
145
sealed abstract class ZTestRunnerJS(
146
  args: Array[String],
147
  remoteArgs: Array[String], 
148
  testClassLoader: ClassLoader,
149
  runnerType: String
150
) extends Runner
151

152
final class ZMasterTestRunnerJS extends ZTestRunnerJS
153
final class ZSlaveTestRunnerJS extends ZTestRunnerJS
154
```
155

156
[JavaScript Platform Support](./js-platform.md)
157

158
### Native Platform Support
159

160
Scala Native test runner optimized for native compilation with efficient memory usage and native-specific execution patterns.
161

162
```scala { .api }
163
sealed abstract class ZTestRunnerNative(
164
  args: Array[String],
165
  remoteArgs: Array[String],
166
  testClassLoader: ClassLoader, 
167
  runnerType: String
168
) extends Runner
169

170
final class ZMasterTestRunner extends ZTestRunnerNative
171
final class ZSlaveTestRunner extends ZTestRunnerNative  
172
```
173

174
[Native Platform Support](./native-platform.md)
175

176
## Types
177

178
### SendSummary
179

180
Type alias for summary handling operations.
181

182
```scala { .api }
183
type SendSummary = URIO[Summary, Unit]
184

185
object SendSummary {
186
  def fromSend(send: Summary => Unit): SendSummary
187
  def fromSendZIO(send: Summary => UIO[Unit]): SendSummary  
188
  def noop: SendSummary
189
}
190
```
191

192
### BaseTestTask
193

194
Abstract base class for all platform-specific test tasks, providing shared functionality for test execution and SBT integration.
195

196
```scala { .api }
197
abstract class BaseTestTask[T](
198
  taskDef0: TaskDef,
199
  testClassLoader: ClassLoader,
200
  sendSummary: SendSummary,
201
  args: TestArgs,
202
  spec: ZIOSpecAbstract,
203
  runtime: zio.Runtime[T],
204
  console: Console
205
) extends Task {
206
  def taskDef(): TaskDef
207
  def execute(eventHandler: EventHandler, loggers: Array[Logger]): Array[Task]
208
  def tags(): Array[String]
209
  
210
  /**
211
   * Creates the shared test layer with environment and scope
212
   * @param trace Implicit trace for ZIO effect tracking
213
   * @return ZLayer providing TestEnvironment, ZIOAppArgs, and Scope
214
   */
215
  protected def sharedFilledTestLayer(implicit trace: Trace): ZLayer[Any, Nothing, TestEnvironment with ZIOAppArgs with Scope]
216
  
217
  /**
218
   * Internal method to run the test with event handling
219
   * @param eventHandlerZ ZIO Test event handler for test execution
220
   * @param trace Implicit trace for ZIO effect tracking
221
   * @return ZIO effect representing test execution
222
   */
223
  private[zio] def run(eventHandlerZ: ZTestEventHandler)(implicit trace: Trace): ZIO[Any, Throwable, Unit]
224
}
225
```
226

227
### SummaryProtocol
228

229
Serialization protocol for test summaries in distributed execution environments (JavaScript and Native platforms).
230

231
```scala { .api }
232
object SummaryProtocol {
233
  def serialize(summary: Summary): String
234
  def deserialize(s: String): Option[Summary]
235
  def escape(token: String): String
236
  def unescape(token: String): String
237
}
238
```