0
# Framework Integration
1

2
Core SBT framework implementation that enables ZIO Test to be recognized and executed by SBT. This provides the primary entry point for test discovery and execution across all supported platforms.
3

4
## Capabilities
5

6
### ZTestFramework
7

8
The main framework class that implements SBT's `Framework` interface, serving as the entry point for ZIO Test integration.
9

10
```scala { .api }
11
/**
12
 * Main SBT framework implementation for ZIO Test integration
13
 * Provides framework identification, test discovery, and runner creation
14
 */
15
final class ZTestFramework extends Framework {
16
  /** Framework display name with ANSI formatting */
17
  val name: String
18
  
19
  /** Array of fingerprints for test discovery, contains ZioSpecFingerprint */
20
  val fingerprints: Array[Fingerprint]
21
  
22
  /**
23
   * Creates a test runner for the specified platform
24
   * @param args Test execution arguments
25
   * @param remoteArgs Remote execution arguments  
26
   * @param testClassLoader ClassLoader for loading test classes
27
   * @return Platform-specific test runner: ZTestRunnerJVM (JVM), ZMasterTestRunnerJS (JS), ZMasterTestRunner (Native)
28
   */
29
  def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
30
  
31
  /**
32
   * Creates a slave runner for distributed execution (JS and Native platforms only)
33
   * @param args Test execution arguments
34
   * @param remoteArgs Remote execution arguments
35
   * @param testClassLoader ClassLoader for loading test classes
36
   * @param send Function for sending test summaries to master process
37
   * @return Slave runner for distributed execution
38
   */
39
  def slaveRunner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader, send: String => Unit): Runner
40
}
41
```
42

43
**Usage Example:**
44

45
```scala
46
// SBT automatically discovers and instantiates the framework
47
// In build.sbt:
48
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")
49

50
// The framework is then used by SBT to:
51
// 1. Discover ZIO test specifications using ZioSpecFingerprint
52
// 2. Create appropriate runners for the target platform
53
// 3. Execute tests and report results
54
```
55

56
### Platform-Specific Runner Creation
57

58
The framework creates different runners based on the target platform:
59

60
**JVM Platform:**
61
```scala { .api }
62
// Returns ZTestRunnerJVM for full-featured JVM execution
63
def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): ZTestRunnerJVM
64
```
65

66
**JavaScript Platform:**
67
```scala { .api }  
68
// Returns ZMasterTestRunnerJS for single-process execution
69
def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
70

71
/**
72
 * Creates a slave runner for distributed JavaScript execution
73
 * @param send Function for sending test summaries to master process
74
 * @return ZSlaveTestRunnerJS for distributed execution
75
 */
76
def slaveRunner(
77
  args: Array[String], 
78
  remoteArgs: Array[String], 
79
  testClassLoader: ClassLoader,
80
  send: String => Unit
81
): Runner
82
```
83

84
**Native Platform:**
85
```scala { .api }
86
// Returns ZMasterTestRunner for single-process native execution  
87
def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
88

89
/**
90
 * Creates a slave runner for distributed native execution
91
 * @param send Function for sending test summaries to master process
92
 * @return ZSlaveTestRunner for distributed execution
93
 */
94
def slaveRunner(
95
  args: Array[String],
96
  remoteArgs: Array[String], 
97
  testClassLoader: ClassLoader,
98
  send: String => Unit
99
): Runner
100
```
101

102
### Framework Properties
103

104
The framework provides consistent identification across all platforms:
105

106
```scala { .api }
107
// Framework display name with ANSI underline formatting
108
val name: String = s"${Console.UNDERLINED}ZIO Test${Console.RESET}"
109

110
// Single fingerprint for discovering ZIOSpecAbstract implementations
111
val fingerprints: Array[Fingerprint] = Array(ZioSpecFingerprint)
112
```
113

114
The framework name includes ANSI escape codes for enhanced display in terminal output, providing visual distinction in SBT's test framework listing.
115

116
### Integration Flow
117

118
1. **Discovery**: SBT loads `ZTestFramework` class from classpath
119
2. **Registration**: Framework registers `ZioSpecFingerprint` for test discovery
120
3. **Runner Creation**: Framework creates platform-appropriate runner instance
121
4. **Execution**: Runner handles test discovery, execution, and result reporting
122

123
The framework abstraction allows ZIO Test to integrate seamlessly with SBT's testing infrastructure while maintaining platform-specific optimizations and capabilities.