0
# Scala Native Test Interface
1

2
Scala Native Test Interface provides the main entry point for test execution in native Scala applications. This library is primarily intended for use by build tools like sbt and contains a very minimal public API surface - most implementation details are internal to the testing framework infrastructure.
3

4
## Package Information
5

6
- **Package Name**: test-interface_native0.5_3
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: Add to your `build.sbt`:
10
  ```scala
11
  libraryDependencies += "org.scala-native" %%% "test-interface" % "0.5.7"
12
  ```
13

14
## Core Imports
15

16
The primary public interface consists of the main entry point:
17

18
```scala
19
import scala.scalanative.testinterface.TestMain
20
```
21

22
For compatibility with legacy code (deprecated):
23

24
```scala
25
import scala.scalajs.reflect.annotation.EnableReflectiveInstantiation
26
```
27

28
## Basic Usage
29

30
### Test Execution Entry Point
31

32
The primary and essentially only public interface is the main entry point for test runners:
33

34
```scala
35
import scala.scalanative.testinterface.TestMain
36

37
// Main entry point - typically invoked by build tools like sbt
38
// Requires exactly one argument: the server port for RPC communication
39
TestMain.main(Array("8080"))
40
```
41

42
**Important Notes:**
43
- This method is typically called by build tools, not directly by user code
44
- Requires a server port for RPC communication with JVM-based test runners
45
- All other functionality is internal to the testing framework infrastructure
46

47
## Architecture Overview
48

49
The Scala Native Test Interface uses an internal architecture that enables testing in the native environment:
50

51
1. **RPC Communication**: Native test processes communicate with JVM-based test runners
52
2. **Framework Integration**: Internally supports multiple testing frameworks through SBT's testing interface
53
3. **Signal Handling**: Provides internal crash reporting capabilities
54
4. **Distributed Execution**: Enables distribution of test tasks across multiple native processes
55

56
**Note**: All architectural components are internal implementation details and not part of the public API.
57

58
## Public API
59

60
### TestMain
61

62
The main entry point object for native test execution.
63

64
```scala { .api }
65
object TestMain {
66
  def main(args: Array[String]): Unit
67
}
68
```
69

70
**Method: main**
71

72
Initializes and runs the native test execution environment.
73

74
**Parameters:**
75
- `args: Array[String]` - Command line arguments. Expects exactly one argument: the server port number for RPC communication with the JVM test server.
76

77
**Throws:**
78
- `IllegalArgumentException` - If the arguments are invalid (not exactly one argument)
79

80
**Description:**
81
This method serves as the entry point for native test execution. It:
82
1. Validates command line arguments (requires exactly one port argument)
83
2. Establishes RPC connection to the JVM test server on the specified port
84
3. Initializes the internal testing framework infrastructure
85
4. Enters the main test execution loop
86
5. Exits with appropriate status codes
87

88
**Usage:**
89
```scala
90
// Typical invocation by build tools
91
TestMain.main(Array("8080"))  // Connect to test server on port 8080
92
```
93

94
**Environment Variables:**
95
The test execution can be influenced by environment variables (handled internally):
96
- `SCALANATIVE_TEST_DEBUG_SIGNALS` - Controls signal handler setup
97
- `SCALANATIVE_TEST_PREFETCH_DEBUG_INFO` - Controls debug metadata prefetching
98

99
## Compatibility Layer
100

101
### Deprecated Compatibility Types
102

103
The library provides deprecated compatibility types for migration from Scala.js:
104

105
```scala { .api }
106
package scala.scalajs.reflect.annotation {
107
  @deprecated("Use scala.scalanative.reflect.annotation.EnableReflectiveInstantiation instead.", "0.4.0")
108
  type EnableReflectiveInstantiation = scala.scalanative.reflect.annotation.EnableReflectiveInstantiation
109
}
110
```
111

112
**Type: EnableReflectiveInstantiation**
113

114
A deprecated type alias for compatibility with legacy Scala.js code.
115

116
**Deprecation Notice:**
117
- **Since**: 0.4.0
118
- **Replacement**: Use `scala.scalanative.reflect.annotation.EnableReflectiveInstantiation` instead
119
- **Purpose**: Provides migration path for code using the old Scala.js reflection annotation
120

121
**Usage (deprecated):**
122
```scala
123
import scala.scalajs.reflect.annotation.EnableReflectiveInstantiation
124

125
// This is deprecated - use scala.scalanative.reflect.annotation.EnableReflectiveInstantiation instead
126
@EnableReflectiveInstantiation
127
class MyTestClass
128
```
129

130
**Recommended Usage:**
131
```scala
132
import scala.scalanative.reflect.annotation.EnableReflectiveInstantiation
133

134
@EnableReflectiveInstantiation  
135
class MyTestClass
136
```
137

138
## Integration with Build Tools
139

140
### SBT Integration
141

142
The test interface is designed for seamless integration with sbt:
143

144
1. **Automatic Invocation**: sbt automatically calls `TestMain.main` with appropriate port arguments
145
2. **Exit Codes**: The main method uses standard Unix exit codes for success/failure reporting
146
3. **Standard Streams**: Error reporting occurs through standard error streams
147
4. **Test Discovery**: Test discovery and execution are handled through internal RPC communication
148

149
### Command Line Usage
150

151
While primarily intended for build tool usage, the test interface can be invoked directly:
152

153
```bash
154
# Replace 8080 with the actual test server port
155
./my-native-test-binary 8080
156
```
157

158
**Requirements:**
159
- A running JVM test server must be listening on the specified port
160
- The native binary must be compiled with the test interface dependency
161
- Proper test framework implementations must be available at runtime
162

163
## Implementation Notes
164

165
### Internal Architecture
166

167
**Important**: The vast majority of the test interface functionality is implemented as internal APIs not intended for direct use:
168

169
- **Framework Loading**: Test framework discovery and loading (internal)
170
- **RPC Communication**: Message passing between JVM and native processes (internal)  
171
- **Task Management**: Test task serialization and distribution (internal)
172
- **Class Loading**: Compatibility layer for SBT testing interface (internal)
173
- **Signal Handling**: Native crash reporting and debugging (internal)
174

175
### Performance Characteristics
176

177
- **Startup Time**: Optimized for fast startup in native compilation
178
- **Memory Usage**: Minimal memory footprint for test execution overhead
179
- **Network Communication**: Efficient UTF-16BE encoding for RPC messages
180
- **Signal Safety**: Uses only async-signal-safe functions in crash handlers
181

182
### Platform Support
183

184
The test interface supports all platforms supported by Scala Native:
185
- **Linux**: Full support with POSIX signal handling
186
- **macOS**: Full support with BSD-specific optimizations  
187
- **Windows**: Support with Windows-specific signal handling
188
- **BSD Systems**: FreeBSD, OpenBSD, NetBSD with platform-specific network configuration
189

190
## Error Handling
191

192
### Common Errors
193

194
**Invalid Arguments**
195
```
196
IllegalArgumentException: One argument expected
197
```
198
- **Cause**: Incorrect number of command line arguments
199
- **Solution**: Ensure exactly one argument (server port) is provided
200

201
**Connection Errors**
202
- **Cause**: Cannot connect to test server on specified port
203
- **Symptoms**: Process exits with non-zero code
204
- **Solution**: Verify test server is running and port is correct
205

206
**Framework Errors**
207
- **Cause**: Test framework not available or incompatible
208
- **Symptoms**: Runtime errors during test execution
209
- **Solution**: Ensure compatible test framework is on classpath with proper reflection setup
210

211
### Exit Codes
212

213
The test interface follows Unix conventions:
214
- **0**: Successful test execution
215
- **1**: General errors or test failures
216
- **>128**: Fatal signal received (signal number = exit code - 128)
217

218
## Best Practices
219

220
### For Build Tool Authors
221

222
1. **Port Management**: Ensure unique ports for concurrent test executions
223
2. **Process Management**: Properly handle test process lifecycle and cleanup
224
3. **Error Handling**: Parse exit codes appropriately for test result reporting
225
4. **Timeout Handling**: Implement appropriate timeouts for test execution
226

227
### For Test Framework Authors
228

229
While the public API is minimal, test framework authors working with the internal APIs should:
230

231
1. **Reflection Setup**: Ensure proper `@EnableReflectiveInstantiation` annotations
232
2. **Serialization**: Implement proper serialization for custom test data
233
3. **Error Reporting**: Use standard SBT testing interfaces for result result reporting
234
4. **Thread Safety**: Ensure thread-safe implementation for concurrent execution
235

236
## Migration Guide
237

238
### From Scala.js Test Interface
239

240
When migrating from Scala.js to Scala Native test interface:
241

242
1. **Update Dependencies**: Change from Scala.js to Scala Native test interface dependency
243
2. **Reflection Annotations**: Update from `scala.scalajs.reflect.annotation.EnableReflectiveInstantiation` to `scala.scalanative.reflect.annotation.EnableReflectiveInstantiation`
244
3. **Build Configuration**: Update build settings for native compilation
245
4. **Platform Considerations**: Account for native-specific behaviors (signal handling, etc.)
246

247
### API Compatibility
248

249
The public API is intentionally minimal and stable:
250
- **TestMain.main**: Signature and behavior remain consistent across versions
251
- **Deprecated APIs**: Maintained for backward compatibility with clear migration paths
252
- **Internal APIs**: Subject to change without notice (not part of public contract)