0
# Scala.js Test Interface
1

2
The Scala.js Test Interface provides a standardized API for test frameworks to integrate with SBT and run tests in JavaScript environments compiled by Scala.js. It serves as the bridge between SBT's testing infrastructure and JavaScript-based test execution, enabling test frameworks to define test discovery patterns, execute tests asynchronously, handle test events, and support distributed testing across worker processes.
3

4
## Package Information
5

6
- **Package Name**: org.scala-js:scalajs-test-interface_2.12
7
- **Package Type**: maven
8
- **Language**: Scala (compiles to JavaScript via Scala.js)
9
- **Installation**: Add to `build.sbt`: `libraryDependencies += "org.scala-js" %%% "scalajs-test-interface" % "1.19.0"`
10

11
## Core Imports
12

13
```scala
14
import sbt.testing._
15
```
16

17
For specific components:
18

19
```scala
20
import sbt.testing.{Framework, Runner, Task, TaskDef, Event, EventHandler}
21
import sbt.testing.{Logger, Status, Fingerprint, Selector}
22
```
23

24
## Basic Usage
25

26
```scala
27
import sbt.testing._
28
import scala.scalajs.reflect.annotation.EnableReflectiveInstantiation
29

30
// Implement a test framework
31
@EnableReflectiveInstantiation
32
class MyTestFramework extends Framework {
33
  def name(): String = "MyTestFramework"
34
  
35
  def fingerprints(): Array[Fingerprint] = Array(
36
    new SubclassFingerprint {
37
      def isModule() = false
38
      def superclassName() = "MyTestSuite"
39
      def requireNoArgConstructor() = true
40
    }
41
  )
42
  
43
  def runner(args: Array[String], remoteArgs: Array[String], 
44
            testClassLoader: ClassLoader): Runner = {
45
    new MyTestRunner(args, remoteArgs, testClassLoader)
46
  }
47
  
48
  def slaveRunner(args: Array[String], remoteArgs: Array[String],
49
                 testClassLoader: ClassLoader, send: String => Unit): Runner = {
50
    new MyWorkerRunner(args, remoteArgs, testClassLoader, send)
51
  }
52
}
53

54
// Create and execute test tasks
55
class MyTestRunner(args: Array[String], remoteArgs: Array[String], 
56
                  testClassLoader: ClassLoader) extends Runner {
57
  
58
  def tasks(taskDefs: Array[TaskDef]): Array[Task] = {
59
    taskDefs.map(taskDef => new MyTask(taskDef))
60
  }
61
  
62
  def done(): String = "Tests completed"
63
  
64
  // ... other required methods
65
}
66
```
67

68
## Architecture
69

70
The Scala.js Test Interface is built around several key components:
71

72
- **Framework Discovery**: Test frameworks implement `Framework` trait with fingerprints for test class identification
73
- **Test Execution**: `Runner` manages test lifecycle and creates executable `Task` instances 
74
- **Event System**: `Event` and `EventHandler` provide structured test result reporting
75
- **Worker Architecture**: `slaveRunner` enables distributed testing across JavaScript workers
76
- **Async Support**: Dual `execute` methods support both synchronous and asynchronous (continuation-based) execution
77
- **Serialization**: Task serialization/deserialization enables cross-worker task distribution
78

79
## Capabilities
80

81
### Framework Implementation
82

83
Core interface for implementing test frameworks with support for test discovery, runner creation, and worker-based distributed testing.
84

85
```scala { .api }
86
trait Framework {
87
  def name(): String
88
  def fingerprints(): Array[Fingerprint]
89
  def runner(args: Array[String], remoteArgs: Array[String], 
90
            testClassLoader: ClassLoader): Runner
91
  def slaveRunner(args: Array[String], remoteArgs: Array[String],
92
                 testClassLoader: ClassLoader, send: String => Unit): Runner
93
}
94
```
95

96
[Framework Implementation](./framework.md)
97

98
### Test Execution
99

100
Test execution system providing task creation, lifecycle management, and support for both synchronous and asynchronous JavaScript execution.
101

102
```scala { .api }
103
trait Runner {
104
  def tasks(taskDefs: Array[TaskDef]): Array[Task]
105
  def done(): String
106
  def remoteArgs(): Array[String]
107
  def args: Array[String]
108
  def receiveMessage(msg: String): Option[String]
109
  def serializeTask(task: Task, serializer: TaskDef => String): String
110
  def deserializeTask(task: String, deserializer: String => TaskDef): Task
111
}
112

113
trait Task {
114
  def tags(): Array[String]
115
  def execute(eventHandler: EventHandler, loggers: Array[Logger]): Array[Task]
116
  def execute(eventHandler: EventHandler, loggers: Array[Logger],
117
             continuation: Array[Task] => Unit): Unit
118
  def taskDef(): TaskDef
119
}
120
```
121

122
[Test Execution](./execution.md)
123

124
### Test Discovery
125

126
Test discovery system using fingerprints to identify test classes through annotations or inheritance patterns.
127

128
```scala { .api }
129
trait Fingerprint
130

131
trait AnnotatedFingerprint extends Fingerprint {
132
  def isModule(): Boolean
133
  def annotationName(): String
134
}
135

136
trait SubclassFingerprint extends Fingerprint {
137
  def isModule(): Boolean
138
  def superclassName(): String
139
  def requireNoArgConstructor(): Boolean
140
}
141
```
142

143
[Test Discovery](./discovery.md)
144

145
### Event Handling
146

147
Event system for reporting test results, progress, and metadata with support for different test selection patterns.
148

149
```scala { .api }
150
trait Event {
151
  def fullyQualifiedName(): String
152
  def fingerprint(): Fingerprint
153
  def selector(): Selector
154
  def status(): Status
155
  def throwable(): OptionalThrowable
156
  def duration(): Long
157
}
158

159
trait EventHandler {
160
  def handle(event: Event): Unit
161
}
162
```
163

164
[Event Handling](./events.md)
165

166
### Logging System
167

168
Thread-safe logging interface supporting multiple log levels and ANSI color codes for user-facing messages.
169

170
```scala { .api }
171
trait Logger {
172
  def ansiCodesSupported(): Boolean
173
  def error(msg: String): Unit
174
  def warn(msg: String): Unit
175
  def info(msg: String): Unit
176
  def debug(msg: String): Unit
177
  def trace(t: Throwable): Unit
178
}
179
```
180

181
[Logging System](./logging.md)
182

183
## Types
184

185
### Core Types
186

187
```scala { .api }
188
final class TaskDef private (
189
  _fullyQualifiedName: String,
190
  _fingerprint: Fingerprint,
191
  _explicitlySpecified: Boolean,
192
  _selectors: Array[Selector]
193
) extends Serializable {
194
  def fullyQualifiedName(): String
195
  def fingerprint(): Fingerprint
196
  def explicitlySpecified(): Boolean
197
  def selectors(): Array[Selector]
198
}
199

200
final class OptionalThrowable(exception: Throwable) extends Serializable {
201
  def this()
202
  def isDefined(): Boolean
203
  def isEmpty(): Boolean
204
  def get(): Throwable
205
}
206
```
207

208
### Status Enumeration
209

210
```scala { .api }
211
class Status private (name: String, ordinal: Int) extends Enum[Status](name, ordinal)
212

213
object Status {
214
  final val Success: Status
215
  final val Error: Status
216
  final val Failure: Status
217
  final val Skipped: Status
218
  final val Ignored: Status
219
  final val Canceled: Status
220
  final val Pending: Status
221
  
222
  def values(): Array[Status]
223
  def valueOf(name: String): Status
224
}
225
```
226

227
### Selector Types
228

229
```scala { .api }
230
abstract sealed class Selector
231

232
final class SuiteSelector extends Selector with Serializable
233

234
final class TestSelector(testName: String) extends Selector with Serializable {
235
  def testName(): String
236
}
237

238
final class NestedSuiteSelector(suiteId: String) extends Selector with Serializable {
239
  def suiteId(): String
240
}
241

242
final class NestedTestSelector(suiteId: String, testName: String) extends Selector with Serializable {
243
  def suiteId(): String
244
  def testName(): String
245
}
246

247
final class TestWildcardSelector(testWildcard: String) extends Selector with Serializable {
248
  def testWildcard(): String
249
}
250
```