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)