0
# Kotlin Test JUnit
1

2
Kotlin Test JUnit is a JUnit adapter library that bridges Kotlin's platform-agnostic kotlin.test library with JUnit 4. It provides seamless integration between Kotlin's multiplatform testing framework and JUnit, enabling developers to write platform-independent test code that runs on the JVM using JUnit's mature testing infrastructure.
3

4
## Package Information
5

6
- **Package Name**: kotlin-test-junit
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  ```kotlin
11
  dependencies {
12
      testImplementation("org.jetbrains.kotlin:kotlin-test-junit:2.2.0")
13
  }
14
  ```
15

16
## Core Imports
17

18
The library provides automatic integration through Kotlin's service loader mechanism, but you can also access components directly:
19

20
```kotlin
21
// For using kotlin.test assertions (automatically uses JUnit when available)
22
import kotlin.test.*
23

24
// For direct access to JUnit integration classes (usually not needed)
25
import kotlin.test.junit.JUnitAsserter
26
import kotlin.test.junit.JUnitContributor
27
```
28

29
## Basic Usage
30

31
The library works transparently with kotlin.test assertions when JUnit is in the classpath:
32

33
```kotlin
34
import kotlin.test.*
35
import org.junit.Test
36

37
class MyTest {
38
    @Test
39
    fun testExample() {
40
        // These kotlin.test assertions automatically delegate to JUnit
41
        assertEquals("expected", "expected")
42
        assertTrue(true)
43
        assertNotNull("not null")
44
    }
45
    
46
    @BeforeTest
47
    fun setup() {
48
        // Setup code - maps to JUnit @Before
49
    }
50
    
51
    @AfterTest  
52
    fun teardown() {
53
        // Teardown code - maps to JUnit @After
54
    }
55
}
56
```
57

58
## Architecture
59

60
The library uses a contributor pattern to automatically register the JUnit asserter when JUnit is available in the classpath. The `JUnitContributor` class implements `AsserterContributor` and provides the `JUnitAsserter` implementation when JUnit is detected.
61

62
## Capabilities
63

64
### Test Annotations
65

66
Maps kotlin.test annotations to their JUnit equivalents for seamless multiplatform testing.
67

68
```kotlin { .api }
69
public actual typealias Test = org.junit.Test
70
public actual typealias Ignore = org.junit.Ignore
71
public actual typealias BeforeTest = org.junit.Before
72
public actual typealias AfterTest = org.junit.After
73
```
74

75
### JUnit Integration
76

77
Provides automatic JUnit asserter registration and detection.
78

79
```kotlin { .api }
80
public class JUnitContributor : AsserterContributor {
81
    override fun contribute(): Asserter?
82
}
83
```
84

85
The `JUnitContributor` automatically detects if JUnit is available in the classpath and provides the `JUnitAsserter` implementation if found. It uses `Class.forName("org.junit.Assert")` to check for JUnit availability.
86

87
### Assertion Implementation
88

89
Implements kotlin.test assertions by delegating to JUnit's Assert class.
90

91
```kotlin { .api }
92
public object JUnitAsserter : Asserter {
93
    override fun assertEquals(message: String?, expected: Any?, actual: Any?)
94
    override fun assertNotEquals(message: String?, illegal: Any?, actual: Any?)
95
    override fun assertSame(message: String?, expected: Any?, actual: Any?)
96
    override fun assertNotSame(message: String?, illegal: Any?, actual: Any?)
97
    override fun assertNotNull(message: String?, actual: Any?)
98
    override fun assertNull(message: String?, actual: Any?)
99
    override fun fail(message: String?): Nothing
100
    @SinceKotlin("1.4")
101
    override fun fail(message: String?, cause: Throwable?): Nothing
102
    
103
    // Note: assertTrue methods are inherited from Asserter interface with default implementations
104
    // that delegate to fail() - no override needed since JUnit does not provide assertTrue directly
105
}
106
```
107

108
**assertEquals**: Asserts that two objects are equal, delegating to `org.junit.Assert.assertEquals`
109
- `message` - Optional assertion failure message
110
- `expected` - Expected value
111
- `actual` - Actual value to compare
112

113
**assertNotEquals**: Asserts that two objects are not equal, delegating to `org.junit.Assert.assertNotEquals`
114
- `message` - Optional assertion failure message  
115
- `illegal` - Value that should not match
116
- `actual` - Actual value to compare
117

118
**assertSame**: Asserts that two objects refer to the same object, delegating to `org.junit.Assert.assertSame`
119
- `message` - Optional assertion failure message
120
- `expected` - Expected object reference
121
- `actual` - Actual object reference to compare
122

123
**assertNotSame**: Asserts that two objects do not refer to the same object, delegating to `org.junit.Assert.assertNotSame`
124
- `message` - Optional assertion failure message
125
- `illegal` - Object reference that should not match
126
- `actual` - Actual object reference to compare
127

128
**assertNotNull**: Asserts that an object is not null, delegating to `org.junit.Assert.assertNotNull`
129
- `message` - Optional assertion failure message (if null, defaults to "actual value is null")
130
- `actual` - Object to check for non-null
131
- Note: When message is null, the implementation provides the default message "actual value is null"
132

133
**assertNull**: Asserts that an object is null, delegating to `org.junit.Assert.assertNull`
134
- `message` - Optional assertion failure message (if null, defaults to "actual value is not null")
135
- `actual` - Object to check for null
136
- Note: When message is null, the implementation provides the default message "actual value is not null"
137

138
**fail**: Fails a test with an optional message, delegating to `org.junit.Assert.fail`
139
- `message` - Optional failure message
140
- Returns: `Nothing` (always throws AssertionError)
141
- Implementation: Calls `Assert.fail(message)` and includes fallback throw if needed
142

143
**fail**: Fails a test with an optional message and cause, delegating to `org.junit.Assert.fail` (available since Kotlin 1.4)
144
- `message` - Optional failure message
145
- `cause` - Optional exception cause
146
- Returns: `Nothing` (always throws AssertionError with cause)
147
- Implementation: Calls `Assert.fail(message)`, catches AssertionError, calls `initCause(cause)`, then rethrows
148

149
## Types
150

151
```kotlin { .api }
152
/**
153
 * Checks applicability and provides Asserter instance
154
 */
155
interface AsserterContributor {
156
    /**
157
     * Provides [Asserter] instance or `null` depends on the current context.
158
     * @return asserter instance or null if it is not applicable now
159
     */
160
    fun contribute(): Asserter?
161
}
162

163
/**
164
 * Platform-specific assertion implementation interface from kotlin.test
165
 */
166
interface Asserter {
167
    /** Fails the current test with the specified message */
168
    fun fail(message: String?): Nothing
169
    
170
    /** Fails the current test with the specified message and cause exception (since Kotlin 1.4) */
171
    fun fail(message: String?, cause: Throwable?): Nothing
172
    
173
    /** Asserts that the specified value is `true` (has default implementation that calls fail) */
174
    fun assertTrue(lazyMessage: () -> String?, actual: Boolean): Unit
175
    
176
    /** Asserts that the specified value is `true` (has default implementation) */
177
    fun assertTrue(message: String?, actual: Boolean): Unit
178
    
179
    /** Asserts that the specified values are equal (has default implementation using assertTrue) */
180
    fun assertEquals(message: String?, expected: Any?, actual: Any?): Unit
181
    
182
    /** Asserts that the specified values are not equal (has default implementation using assertTrue) */
183
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?): Unit
184
    
185
    /** Asserts that the specified values are the same instance (has default implementation using assertTrue) */
186
    fun assertSame(message: String?, expected: Any?, actual: Any?): Unit
187
    
188
    /** Asserts that the specified values are not the same instance (has default implementation using assertTrue) */
189
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?): Unit
190
    
191
    /** Asserts that the specified value is `null` (has default implementation using assertTrue) */
192
    fun assertNull(message: String?, actual: Any?): Unit
193
    
194
    /** Asserts that the specified value is not `null` (has default implementation using assertTrue) */
195
    fun assertNotNull(message: String?, actual: Any?): Unit
196
}
197
```
198

199
Note: These interfaces are defined in the `kotlin.test` module, which this library depends on and extends.
200

201
## Integration Details
202

203
The library integrates with kotlin.test through the Java Service Provider Interface (SPI). The `JUnitContributor` is automatically discovered and registered via the `META-INF/services/kotlin.test.AsserterContributor` file, enabling automatic JUnit support when both kotlin-test-junit and JUnit are present in the classpath.
204

205
When JUnit is detected, all kotlin.test assertion functions (`assertEquals`, `assertTrue`, etc.) automatically delegate to the corresponding JUnit assertions, providing seamless integration between Kotlin's multiplatform test APIs and JUnit's JVM-specific testing infrastructure.
206

207
## Module Structure
208

209
The library provides two main packages through its module exports:
210

211
- **`kotlin.test.junit`** - Contains the main integration classes (`JUnitContributor`, `JUnitAsserter`)
212
- **`kotlin.test.junit.annotations`** - Contains the annotation type aliases (physically defined in `kotlin.test` package but exported to this package via `@JvmPackageName("kotlin.test.junit.annotations")`)
213

214
The module declares transitive dependencies on `kotlin.stdlib`, `kotlin.test`, and `junit`, and provides the `AsserterContributor` service implementation.