0
# ZIO Test SBT Integration
1

2
ZIO Test SBT is a test framework integration that enables ZIO Test specifications to be executed by SBT. It provides cross-platform support for JVM, JavaScript, and Native environments, allowing ZIO's functional testing framework to integrate seamlessly with SBT's testing infrastructure.
3

4
## Package Information
5

6
- **Package Name**: zio-test-sbt
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Organization**: dev.zio
10
- **Installation**: Add to `build.sbt`:
11
  ```scala
12
  libraryDependencies += "dev.zio" %% "zio-test-sbt" % "1.0.18" % Test
13
  ```
14

15
## Core Imports
16

17
```scala
18
import zio.test.sbt._
19
```
20

21
For testing framework implementation:
22
```scala
23
import sbt.testing._
24
import zio.test.sbt.{ZTestFramework, ZTestRunner, SendSummary}
25
```
26

27
## Basic Usage
28

29
ZIO Test SBT is primarily used by SBT internally for test execution. To enable it in your project:
30

31
1. Add the dependency to your `build.sbt`
32
2. Configure the test framework:
33

34
```scala
35
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
36
```
37

38
3. Create ZIO Test specifications as usual:
39

40
```scala
41
import zio.test._
42

43
object MySpec extends DefaultRunnableSpec {
44
  def spec = suite("My Tests")(
45
    test("example test") {
46
      assert(1 + 1)(equalTo(2))
47
    }
48
  )
49
}
50
```
51

52
## Architecture
53

54
ZIO Test SBT consists of several key components:
55

56
- **Framework Integration**: `ZTestFramework` implements SBT's `Framework` interface for test discovery
57
- **Task Execution**: `BaseTestTask` and platform-specific implementations handle test execution
58
- **Event System**: `ZTestEvent` reports test results back to SBT
59
- **Cross-Platform Support**: Separate implementations for JVM, JavaScript, and Native platforms
60

61
## Capabilities
62

63
### Framework Integration
64

65
Core SBT test framework implementation that enables test discovery and execution.
66

67
```scala { .api }
68
class ZTestFramework extends Framework {
69
  val name: String
70
  val fingerprints: Array[Fingerprint]
71
  def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
72
}
73
```
74

75
[Framework Integration](./framework.md)
76

77
### Task Execution  
78

79
Base task execution capabilities for running ZIO Test specifications within SBT.
80

81
```scala { .api }
82
abstract class BaseTestTask(
83
  taskDef: TaskDef,
84
  testClassLoader: ClassLoader, 
85
  sendSummary: SendSummary,
86
  args: TestArgs
87
) extends Task {
88
  def execute(eventHandler: EventHandler, loggers: Array[Logger]): Array[Task]
89
}
90
```
91

92
[Task Execution](./task-execution.md)
93

94
### Event Reporting
95

96
Test event generation and reporting system for SBT integration.
97

98
```scala { .api }
99
case class ZTestEvent(
100
  fullyQualifiedName: String,
101
  selector: Selector,
102
  status: Status,
103
  maybeThrowable: Option[Throwable],
104
  duration: Long,
105
  fingerprint: Fingerprint
106
) extends Event
107
```
108

109
[Event Reporting](./event-reporting.md)
110

111
### Cross-Platform Support
112

113
Platform-specific implementations for JVM, JavaScript, and Native environments.
114

115
```scala { .api }
116
// Platform-specific runners
117
class ZMasterTestRunner extends ZTestRunner
118
class ZSlaveTestRunner extends ZTestRunner  
119

120
// Summary serialization for JS/Native
121
object SummaryProtocol {
122
  def serialize(summary: Summary): String
123
  def deserialize(s: String): Option[Summary]
124
}
125
```
126

127
[Cross-Platform Support](./cross-platform.md)
128

129
## Types
130

131
### Core Types
132

133
```scala { .api }
134
// Summary sending effect
135
type SendSummary = URIO[Summary, Unit]
136

137
// Task policy for merging tasks
138
abstract class ZTestTaskPolicy {
139
  def merge(zioTasks: Array[ZTestTask]): Array[Task]
140
}
141

142
// Test discovery fingerprint
143
object RunnableSpecFingerprint extends SubclassFingerprint {
144
  def superclassName(): String
145
  def isModule(): Boolean  
146
  def requireNoArgConstructor(): Boolean
147
}
148
```
149

150
### Platform-Specific Types
151

152
JavaScript and Native platforms include additional types for distributed execution and serialization that are not available on the JVM platform.