0
# Framework Integration
1

2
The framework integration layer provides the core SBT integration that enables ZIO test discovery and execution within SBT's testing infrastructure. It implements SBT's `Framework` interface to register ZIO Test as a test framework.
3

4
## Capabilities
5

6
### ZTestFramework
7

8
Main entry point for SBT test framework integration. This class is automatically discovered by SBT and used to create test runners.
9

10
```scala { .api }
11
/**
12
 * Main SBT framework implementation for ZIO Test integration
13
 * Discovered automatically by SBT's framework detection mechanism
14
 */
15
final class ZTestFramework extends sbt.testing.Framework {
16
  /** Framework display name with ANSI formatting - evaluates to "ZIO Test" with underlining */
17
  override val name: String
18

19
  /** Array of fingerprints for test discovery - contains RunnableSpecFingerprint */
20
  val fingerprints: Array[sbt.testing.Fingerprint]
21

22
  /** 
23
   * Creates a test runner for the current platform
24
   * @param args Command line arguments passed to the test framework
25
   * @param remoteArgs Remote arguments for distributed testing
26
   * @param testClassLoader ClassLoader for loading test classes
27
   * @return Platform-appropriate test runner instance
28
   */
29
  override def runner(
30
    args: Array[String], 
31
    remoteArgs: Array[String], 
32
    testClassLoader: ClassLoader
33
  ): sbt.testing.Runner
34
}
35
```
36

37
**Platform Variations:**
38

39
The framework has platform-specific implementations with slightly different capabilities:
40

41
**JVM Platform:**
42
- Returns `ZTestRunner` instance
43
- Simple single-process execution model
44
- Direct integration with SBT's test interface
45

46
**JavaScript/Native Platforms:**
47
- Supports both master (`ZMasterTestRunner`) and slave (`ZSlaveTestRunner`) runners
48
- Additional `slaveRunner` method for distributed execution
49
- Requires serialization for inter-process communication
50

51
```scala { .api }
52
// Additional method available on JS/Native platforms
53
override def slaveRunner(
54
  args: Array[String],
55
  remoteArgs: Array[String], 
56
  testClassLoader: ClassLoader,
57
  send: String => Unit
58
): sbt.testing.Runner
59
```
60

61
**Usage Example:**
62

63
```scala
64
// Automatic registration in build.sbt
65
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
66

67
// The framework is used automatically by SBT - no direct usage required
68
// When you run 'sbt test', SBT will:
69
// 1. Discover ZTestFramework via reflection
70
// 2. Call runner() to create a test runner  
71
// 3. Use the runner to discover and execute ZIO test specifications
72
```
73

74
### RunnableSpecFingerprint
75

76
SBT fingerprint that identifies ZIO test specifications for automatic discovery. This tells SBT which classes should be treated as ZIO tests.
77

78
```scala { .api }
79
/**
80
 * Fingerprint for discovering ZIO test specifications
81
 * Identifies classes extending zio.test.AbstractRunnableSpec
82
 */
83
object RunnableSpecFingerprint extends sbt.testing.SubclassFingerprint {
84
  /** 
85
   * Returns the base class name that test specs must extend
86
   * @return "zio.test.AbstractRunnableSpec" 
87
   */
88
  def superclassName(): String
89

90
  /** 
91
   * Indicates that targets are Scala objects (not classes)
92
   * @return true - ZIO specs are typically objects
93
   */
94
  def isModule(): Boolean
95

96
  /** 
97
   * Whether discovered classes must have no-arg constructors
98
   * @return false - ZIO specs don't require no-arg constructors
99
   */
100
  def requireNoArgConstructor(): Boolean
101
}
102
```
103

104
**Discovery Process:**
105

106
1. SBT scans the classpath for classes/objects matching the fingerprint
107
2. Finds all objects extending `zio.test.AbstractRunnableSpec`
108
3. Creates `TaskDef` instances for each discovered specification
109
4. Passes these to the test runner for execution
110

111
**Example ZIO Test Specification:**
112

113
```scala
114
import zio.test._
115

116
// This object will be discovered by RunnableSpecFingerprint
117
object MyTestSpec extends DefaultRunnableSpec {
118
  def spec = suite("My Tests")(
119
    test("addition works") {
120
      assert(2 + 2)(equalTo(4))
121
    },
122
    test("subtraction works") {
123
      assert(5 - 3)(equalTo(2))
124
    }
125
  )
126
}
127
```
128

129
## Framework Registration
130

131
The framework integrates with SBT through standard framework registration mechanisms:
132

133
**Automatic Registration:**
134
```scala
135
// In build.sbt - registers ZIO Test as a test framework
136
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
137
```
138

139
**Framework Discovery Process:**
140
1. SBT loads the framework class via reflection
141
2. Creates an instance of `ZTestFramework`
142
3. Calls `fingerprints` to get test discovery patterns
143
4. Uses fingerprints to scan for test specifications
144
5. Calls `runner()` to create a test runner when tests need to be executed
145

146
**Integration with SBT Commands:**
147
- `sbt test` - Runs all discovered ZIO tests
148
- `sbt testOnly MySpec` - Runs specific ZIO test specifications  
149
- `sbt testQuick` - Runs tests that have changed
150
- IDE integration - Framework enables ZIO test running in IDEs like IntelliJ IDEA