0
# JVM Platform Support
1

2
Full-featured JVM test runner with advanced debugging capabilities, signal handling, and comprehensive SBT integration features. This provides the most complete ZIO Test SBT integration experience.
3

4
## Capabilities
5

6
### ZTestRunnerJVM
7

8
The primary JVM test runner that provides full-featured test execution with advanced debugging and development features.
9

10
```scala { .api }
11
/**
12
 * JVM-specific test runner with full SBT integration
13
 * Provides advanced debugging, signal handling, and comprehensive test execution
14
 */
15
final class ZTestRunnerJVM(
16
  val args: Array[String], 
17
  val remoteArgs: Array[String], 
18
  testClassLoader: ClassLoader
19
) extends Runner {
20
  /** Test output renderer (mutable for configuration) */
21
  var renderer: TestRenderer
22
  
23
  /** Optional shutdown hook for cleanup (mutable) */
24
  var shutdownHook: Option[() => Unit]
25
  
26
  /** Thread-safe storage for test summaries */
27
  val summaries: AtomicReference[Vector[Summary]]
28
  
29
  /**
30
   * Create test tasks from discovered test definitions
31
   * @param defs Array of SBT task definitions
32
   * @return Array of executable test tasks
33
   */
34
  def tasks(defs: Array[TaskDef]): Array[Task]
35
  
36
  /**
37
   * Complete test execution and return formatted results
38
   * Handles summary aggregation, result formatting, and cleanup
39
   * @return Formatted test results string
40
   */
41
  def done(): String
42
  
43
  /**
44
   * Create summary sender for test result collection
45
   * @param trace Implicit trace for ZIO effect tracking
46
   * @return SendSummary effect for collecting test results
47
   */
48
  def sendSummary(implicit trace: Trace): SendSummary
49
  
50
  /**
51
   * Internal method for creating test tasks with full ZIO integration
52
   * @param defs Array of SBT task definitions
53
   * @param console ZIO Console service
54
   * @param trace Implicit trace for effect tracking
55
   * @return Array of ZTestTask instances with full type information
56
   */
57
  private[sbt] def tasksZ(
58
    defs: Array[TaskDef], 
59
    console: zio.Console
60
  )(implicit trace: Trace): Array[ZTestTask[TestOutput]]
61
}
62
```
63

64
### ZTestTask (JVM)
65

66
JVM-specific test task implementation with signal handler support and enhanced debugging capabilities.
67

68
```scala { .api }
69
/**
70
 * JVM-specific test task with signal handler support
71
 * Provides enhanced debugging and development features
72
 */
73
final class ZTestTask[T](
74
  taskDef: TaskDef,
75
  testClassLoader: ClassLoader,
76
  sendSummary: SendSummary,
77
  testArgs: TestArgs,
78
  spec: ZIOSpecAbstract,
79
  runtime: zio.Runtime[T],
80
  console: zio.Console
81
) extends BaseTestTask(taskDef, testClassLoader, sendSummary, testArgs, spec, runtime, console) {
82
  /**
83
   * Run test with signal handler installation
84
   * Provides fiber dumping on system signals for debugging
85
   * @param eventHandlerZ ZIO test event handler
86
   * @param trace Implicit trace for effect tracking
87
   * @return ZIO effect for test execution
88
   */
89
  private[zio] def run(eventHandlerZ: ZTestEventHandler)(implicit trace: Trace): ZIO[Any, Throwable, Unit]
90
  
91
  /**
92
   * Install signal handlers for debugging support
93
   * Provides fiber dumping capabilities on system signals
94
   * @param trace Implicit trace for effect tracking
95
   */
96
  private def installSignalHandlers()(implicit trace: Trace): Unit
97
}
98
```
99

100
### ZTestTask Companion Object
101

102
Factory methods for creating JVM test tasks.
103

104
```scala { .api }
105
object ZTestTask {
106
  /** Thread-safe flag for signal handler installation */
107
  private val installedSignals: AtomicBoolean
108
  
109
  /**
110
   * Create a JVM test task instance
111
   * @param taskDef SBT task definition
112
   * @param testClassLoader ClassLoader for loading test classes
113
   * @param sendSummary Summary collection effect
114
   * @param args Parsed test arguments
115
   * @param runtime ZIO runtime for test execution
116
   * @param console Console service for output
117
   * @return Configured ZTestTask instance
118
   */
119
  def apply[T](
120
    taskDef: TaskDef,
121
    testClassLoader: ClassLoader,
122
    sendSummary: SendSummary,
123
    args: TestArgs,
124
    runtime: zio.Runtime[T],
125
    console: zio.Console
126
  ): ZTestTask[T]
127
}
128
```
129

130
### Advanced Features
131

132
**Signal Handler Support:**
133

134
The JVM runner installs signal handlers for debugging support:
135

136
```scala { .api }
137
// Installs signal handlers for fiber dumping
138
private def installSignalHandlers()(implicit trace: Trace): Unit = {
139
  val dumpFibers = () => Runtime.default.unsafe.run(Fiber.dumpAll)
140
  
141
  if (System.os.isWindows) {
142
    Platform.addSignalHandler("INT", dumpFibers)    // Ctrl+C on Windows
143
  } else {
144
    Platform.addSignalHandler("INFO", dumpFibers)   // SIGINFO on Unix
145
    Platform.addSignalHandler("USR1", dumpFibers)   // SIGUSR1 on Unix
146
  }
147
}
148
```
149

150
**Runtime Management:**
151

152
```scala { .api }
153
// Creates scoped runtime with proper lifecycle management
154
val runtime: Runtime.Scoped[TestOutput] = 
155
  zio.Runtime.unsafe.fromLayer(sharedLayer)(Trace.empty, Unsafe.unsafe)
156

157
// Registers shutdown hook for cleanup
158
shutdownHook = Some(() => runtime.unsafe.shutdown()(Unsafe.unsafe))
159
```
160

161
**Test Argument Processing:**
162

163
```scala { .api }
164
// Parses and processes test arguments
165
val testArgs = TestArgs.parse(args)
166

167
// Configures renderer based on arguments
168
renderer = testArgs.testRenderer
169

170
// Creates shared output layer for all tests
171
val sharedTestOutputLayer = ExecutionEventPrinter.live(console, testArgs.testEventRenderer) >>> TestOutput.live
172
```
173

174
### Test Execution Flow
175

176
1. **Initialization**: Runner parses arguments, creates runtime, installs signal handlers
177
2. **Task Creation**: Converts SBT `TaskDef` instances to `ZTestTask` instances
178
3. **Spec Loading**: Uses reflection to load ZIO test specifications from classpath
179
4. **Runtime Setup**: Creates shared ZIO runtime with test environment and output layers
180
5. **Execution**: Runs tests with full ZIO effect system support
181
6. **Event Handling**: Converts ZIO events to SBT events for reporting
182
7. **Cleanup**: Shuts down runtime and executes cleanup hooks
183

184
### Summary Processing
185

186
The JVM runner provides comprehensive summary processing:
187

188
```scala { .api }
189
def done(): String = {
190
  val allSummaries = summaries.get
191
  val total = allSummaries.map(_.total).sum
192
  val ignore = allSummaries.map(_.ignore).sum
193
  
194
  val compositeSummary = allSummaries.foldLeft(Summary.empty)(_.add(_))
195
  val renderedSummary = renderer.renderSummary(compositeSummary)
196
  
197
  val renderedResults = 
198
    if (allSummaries.nonEmpty && total != ignore)
199
      colored(renderedSummary)
200
    else if (ignore > 0)  
201
      s"${Console.YELLOW}All eligible tests are currently ignored ${Console.RESET}"
202
    else
203
      s"${Console.YELLOW}No tests were executed${Console.RESET}"
204
      
205
  // Print results directly to work around SBT forked JVM issues
206
  if (allSummaries.nonEmpty) println(renderedResults)
207
  
208
  shutdownHook.foreach(_.apply())
209
  "Completed tests"
210
}
211
```
212

213
### Platform Advantages
214

215
The JVM platform provides several advantages:
216

217
- **Full Debugging Support**: Signal handlers enable fiber dumping for debugging hung tests
218
- **Advanced Runtime Features**: Complete ZIO runtime with all features available
219
- **Comprehensive Error Reporting**: Full stack traces and detailed error information
220
- **IDE Integration**: Rich integration with IntelliJ IDEA, VS Code, and other IDEs
221
- **Performance Monitoring**: Detailed timing and performance metrics
222
- **Resource Management**: Proper lifecycle management with shutdown hooks