0
# Scala.js JUnit Test Runtime
1

2
Scala.js JUnit Test Runtime provides the complete JUnit 4 testing framework implementation for Scala.js applications. It enables developers to write and run JUnit-based tests that are compiled with Scala.js and executed in JavaScript environments, bridging the gap between Java's JUnit testing patterns and JavaScript runtime execution.
3

4
## Package Information
5

6
- **Package Name**: scalajs-junit-test-runtime
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.scala-js" %%% "scalajs-junit-test-runtime" % "1.19.0"`
10

11
## Core Imports
12

13
```scala
14
import org.junit._
15
import org.junit.Assert._
16
import org.junit.Assume._
17
import org.hamcrest.CoreMatchers._
18
import org.hamcrest.MatcherAssert._
19
import org.junit.runner.RunWith
20
import org.junit.runners.JUnit4
21
import org.scalajs.junit.JUnitFramework
22
```
23

24
## Basic Usage
25

26
```scala
27
import org.junit._
28
import org.junit.Assert._
29

30
class MyTest {
31
  @Test
32
  def testBasicAssertion(): Unit = {
33
    val result = 2 + 2
34
    assertEquals(4, result)
35
    assertTrue(result > 0)
36
  }
37
  
38
  @Test
39
  def testWithHamcrest(): Unit = {
40
    import org.hamcrest.CoreMatchers._
41
    val name = "Alice"
42
    assertThat(name, is(notNullValue()))
43
    assertThat(name.length, is(5))
44
  }
45
  
46
  @Before
47
  def setUp(): Unit = {
48
    // Setup code before each test
49
  }
50
  
51
  @After  
52
  def tearDown(): Unit = {
53
    // Cleanup code after each test
54
  }
55
}
56
```
57

58
## Architecture
59

60
The Scala.js JUnit Test Runtime is organized around several key components:
61

62
- **JUnit Core API**: Complete implementation of JUnit 4 assertion and assumption methods
63
- **Lifecycle Management**: Full support for @Test, @Before, @After, @BeforeClass, @AfterClass annotations
64
- **Hamcrest Integration**: Core matcher library for expressive test assertions
65
- **Scala.js Runtime**: SBT testing framework integration for JavaScript execution
66
- **Exception Handling**: Enhanced error reporting with stack trace filtering and comparison diffs
67
- **Test Discovery**: Automatic test detection and execution via SBT testing framework
68

69
## Capabilities
70

71
### Core Assertions
72

73
Fundamental assertion methods for test validation including equality, null checks, boolean conditions, and exception testing.
74

75
```scala { .api }
76
object Assert {
77
  def assertTrue(condition: Boolean): Unit
78
  def assertTrue(message: String, condition: Boolean): Unit
79
  def assertFalse(condition: Boolean): Unit
80
  def assertFalse(message: String, condition: Boolean): Unit
81
  def assertEquals(expected: Any, actual: Any): Unit
82
  def assertEquals(message: String, expected: Any, actual: Any): Unit
83
  def assertEquals(expected: Int, actual: Int): Unit
84
  def assertEquals(message: String, expected: Int, actual: Int): Unit
85
  def assertEquals(expected: Long, actual: Long): Unit
86
  def assertEquals(message: String, expected: Long, actual: Long): Unit
87
  def assertEquals(expected: Double, actual: Double, delta: Double): Unit
88
  def assertEquals(message: String, expected: Double, actual: Double, delta: Double): Unit
89
  def assertEquals(expected: Float, actual: Float, delta: Float): Unit
90
  def assertEquals(message: String, expected: Float, actual: Float, delta: Float): Unit
91
  def assertNotEquals(unexpected: Any, actual: Any): Unit
92
  def assertNotEquals(message: String, unexpected: Any, actual: Any): Unit
93
  def assertNull(obj: Any): Unit
94
  def assertNull(message: String, obj: Any): Unit
95
  def assertNotNull(obj: Any): Unit
96
  def assertNotNull(message: String, obj: Any): Unit
97
  def assertSame(expected: Any, actual: Any): Unit
98
  def assertSame(message: String, expected: Any, actual: Any): Unit
99
  def assertNotSame(unexpected: Any, actual: Any): Unit
100
  def assertNotSame(message: String, unexpected: Any, actual: Any): Unit
101
  def assertThrows[T <: Throwable](expectedThrowable: Class[T], runnable: ThrowingRunnable): T
102
  def assertThrows[T <: Throwable](message: String, expectedThrowable: Class[T], runnable: ThrowingRunnable): T
103
  def assertThat[T](actual: T, matcher: Matcher[T]): Unit
104
  def assertThat[T](reason: String, actual: T, matcher: Matcher[T]): Unit
105
  def fail(): Unit
106
  def fail(message: String): Unit
107
}
108
```
109

110
[Core Assertions](./core-assertions.md)
111

112
### Hamcrest Matchers  
113

114
Expressive matcher library for readable and composable test assertions with type safety and detailed failure messages.
115

116
```scala { .api }
117
object CoreMatchers {
118
  def is[T](value: T): Matcher[T]
119
  def is[T](matcher: Matcher[T]): Matcher[T]
120
  def not[T](matcher: Matcher[T]): Matcher[T]
121
  def nullValue(): Matcher[AnyRef]
122
  def notNullValue(): Matcher[AnyRef]
123
  def instanceOf[T](typ: Class[_]): Matcher[T]
124
  def any[T](typ: Class[T]): Matcher[T]
125
}
126

127
trait Matcher[T] {
128
  def matches(actual: AnyRef): Boolean
129
  def describeTo(description: Description): Unit
130
}
131
```
132

133
[Hamcrest Matchers](./hamcrest-matchers.md)
134

135
### Test Lifecycle Annotations
136

137
Annotations for controlling test execution flow including setup, teardown, and test identification.
138

139
```scala { .api }
140
class Test(expected: Class[_ <: Throwable] = classOf[Test.None], timeout: Long = 0L) 
141
  extends StaticAnnotation
142

143
object Test {
144
  final class None private () extends Throwable
145
}
146

147
class Before extends StaticAnnotation  
148
class After extends StaticAnnotation
149
class BeforeClass extends StaticAnnotation
150
class AfterClass extends StaticAnnotation
151
class Ignore(value: String = "") extends StaticAnnotation
152
class Rule extends StaticAnnotation
153
class ClassRule extends StaticAnnotation
154
```
155

156
[Test Lifecycle](./test-lifecycle.md)
157

158
### Assumptions and Conditional Testing
159

160
Assumption methods for conditional test execution that skip tests when preconditions are not met.
161

162
```scala { .api }
163
object Assume {
164
  def assumeTrue(b: Boolean): Unit
165
  def assumeTrue(message: String, b: Boolean): Unit
166
  def assumeFalse(b: Boolean): Unit
167
  def assumeNotNull(objects: AnyRef*): Unit
168
  def assumeThat[T](actual: T, matcher: Matcher[T]): Unit
169
  def assumeNoException(e: Throwable): Unit
170
}
171
```
172

173
[Test Assumptions](./test-assumptions.md)
174

175
### Array Assertions
176

177
Specialized assertion methods for comparing arrays with support for different element types and floating-point precision.
178

179
```scala { .api }
180
object Assert {
181
  def assertArrayEquals(expecteds: Array[AnyRef], actuals: Array[AnyRef]): Unit
182
  def assertArrayEquals(expecteds: Array[Boolean], actuals: Array[Boolean]): Unit
183
  def assertArrayEquals(expecteds: Array[Int], actuals: Array[Int]): Unit
184
  def assertArrayEquals(expecteds: Array[Double], actuals: Array[Double], delta: Double): Unit
185
  def assertArrayEquals(expecteds: Array[Float], actuals: Array[Float], delta: Float): Unit
186
}
187
```
188

189
[Array Assertions](./array-assertions.md)
190

191
### Test Runners and Framework Integration
192

193
Runner framework for custom test execution strategies and SBT testing framework integration.
194

195
```scala { .api }
196
class JUnitFramework extends Framework {
197
  val name: String
198
  def fingerprints(): Array[Fingerprint]
199
  def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
200
}
201

202
class RunWith(value: Class[_ <: Runner]) extends StaticAnnotation
203
```
204

205
[Test Runners](./test-runners.md)
206

207
### Exception Handling and Error Reporting
208

209
Enhanced exception classes for detailed test failure reporting with string comparisons and assumption violations.
210

211
```scala { .api }
212
class ComparisonFailure(message: String, expected: String, actual: String) extends AssertionError {
213
  def getExpected(): String
214
  def getActual(): String  
215
}
216

217
class AssumptionViolatedException(message: String) extends RuntimeException
218
```
219

220
[Exception Handling](./exception-handling.md)
221

222
## Types
223

224
### Core Test Types
225

226
```scala { .api }
227
trait ThrowingRunnable {
228
  def run(): Unit
229
}
230

231
class OptionalThrowable(throwable: Throwable = null) {
232
  def isPresent: Boolean
233
  def get(): Throwable
234
}
235
```
236

237
### Framework Integration Types
238

239
```scala { .api }
240
trait Framework {
241
  def name: String
242
  def fingerprints(): Array[Fingerprint]
243
  def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
244
  def slaveRunner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader, send: String => Unit): Runner
245
}
246

247
abstract class Runner {
248
  def done(): String
249
  def tasks(taskDefs: Array[TaskDef]): Array[Task]
250
}
251

252
abstract class ParentRunner[T](testClass: Class[_]) extends Runner
253

254
class BlockJUnit4ClassRunner(testClass: Class[_]) extends ParentRunner[FrameworkMethod]
255

256
final class JUnit4(klass: Class[_]) extends BlockJUnit4ClassRunner
257

258
trait Task {
259
  def taskDef(): TaskDef
260
  def execute(eventHandler: EventHandler, loggers: Array[Logger]): Array[Task]
261
}
262

263
trait TaskDef {
264
  def fullyQualifiedName(): String
265
  def fingerprint(): Fingerprint
266
  def explicitlySpecified(): Boolean
267
  def selectors(): Array[Selector]
268
}
269

270
trait Fingerprint {
271
  def requireNoArgConstructor(): Boolean
272
  def isModule(): Boolean
273
}
274

275
trait AnnotatedFingerprint extends Fingerprint {
276
  def annotationName(): String
277
}
278

279
class FrameworkMethod
280
```