0
# Kotlin Test JUnit 5
1

2
Kotlin Test JUnit 5 provides seamless integration between the Kotlin multiplatform test framework and JUnit 5, enabling developers to use kotlin.test assertions and annotations with JUnit 5's testing infrastructure. It serves as a bridge that maps kotlin.test annotations to their JUnit 5 equivalents and implements kotlin.test assertions using JUnit 5's assertion engine.
3

4
## Package Information
5

6
- **Package Name**: kotlin-test-junit5
7
- **Package Type**: maven (Gradle/Maven)
8
- **Language**: Kotlin (JVM)
9
- **Group ID**: org.jetbrains.kotlin
10
- **Artifact ID**: kotlin-test-junit5
11
- **Installation**: 
12
  - Gradle: `testImplementation("org.jetbrains.kotlin:kotlin-test-junit5:2.2.0")`
13
  - Maven: Add dependency with groupId `org.jetbrains.kotlin`, artifactId `kotlin-test-junit5`, version `2.2.0`
14

15
## Core Imports
16

17
```kotlin
18
import kotlin.test.*
19
```
20

21
The integration happens automatically through service provider mechanism. When JUnit 5 is detected in the classpath, kotlin.test assertions will delegate to JUnit 5's assertion engine.
22

23
## Basic Usage
24

25
```kotlin
26
import kotlin.test.*
27

28
class MyTest {
29
    @Test
30
    fun testExample() {
31
        val result = 2 + 2
32
        assertEquals(4, result)
33
        assertTrue(result > 0)
34
        assertNotNull(result)
35
    }
36
    
37
    @BeforeTest
38
    fun setup() {
39
        // Setup before each test
40
    }
41
    
42
    @AfterTest
43
    fun cleanup() {
44
        // Cleanup after each test
45
    }
46
    
47
    @Test
48
    @Ignore
49
    fun skippedTest() {
50
        // This test will be skipped
51
    }
52
}
53
```
54

55
## Architecture
56

57
Kotlin Test JUnit 5 works through several key components:
58

59
- **Annotation Mapping**: Type aliases that map kotlin.test annotations to JUnit 5 annotations
60
- **Asserter Implementation**: `JUnit5Asserter` object that delegates kotlin.test assertions to JUnit 5 assertions
61
- **Service Provider**: `JUnit5Contributor` that automatically registers the asserter when JUnit 5 is available
62
- **Classpath Detection**: Runtime detection of JUnit 5 availability without hard dependencies
63

64
## Capabilities
65

66
### Test Annotations
67

68
Maps kotlin.test annotations to their JUnit 5 equivalents for seamless integration.
69

70
```kotlin { .api }
71
/**
72
 * Marks a function as a test - maps to org.junit.jupiter.api.Test
73
 */
74
public actual typealias Test = org.junit.jupiter.api.Test
75

76
/**
77
 * Marks a test or suite as ignored - maps to org.junit.jupiter.api.Disabled  
78
 */
79
public actual typealias Ignore = org.junit.jupiter.api.Disabled
80

81
/**
82
 * Marks a function to be invoked before each test - maps to org.junit.jupiter.api.BeforeEach
83
 */
84
public actual typealias BeforeTest = org.junit.jupiter.api.BeforeEach
85

86
/**
87
 * Marks a function to be invoked after each test - maps to org.junit.jupiter.api.AfterEach
88
 */
89
public actual typealias AfterTest = org.junit.jupiter.api.AfterEach
90
```
91

92
### Assertion Engine Integration
93

94
Provides JUnit 5 assertion engine integration through the `JUnit5Asserter` object.
95

96
```kotlin { .api }
97
/**
98
 * JUnit 5 assertion engine implementation for kotlin.test
99
 * Delegates all kotlin.test assertions to org.junit.jupiter.api.Assertions
100
 * Note: assertTrue methods are available through inherited default implementation
101
 */
102
public object JUnit5Asserter : Asserter {
103
    /**
104
     * Asserts that the specified values are equal
105
     * @param message the message to report if the assertion fails
106
     * @param expected the expected value
107
     * @param actual the actual value
108
     */
109
    override fun assertEquals(message: String?, expected: Any?, actual: Any?)
110
    
111
    /**
112
     * Asserts that the specified values are not equal
113
     * @param message the message to report if the assertion fails
114
     * @param illegal the value that should not equal actual
115
     * @param actual the actual value
116
     */
117
    override fun assertNotEquals(message: String?, illegal: Any?, actual: Any?)
118
    
119
    /**
120
     * Asserts that the specified values are the same instance
121
     * @param message the message to report if the assertion fails
122
     * @param expected the expected reference
123
     * @param actual the actual reference
124
     */
125
    override fun assertSame(message: String?, expected: Any?, actual: Any?)
126
    
127
    /**
128
     * Asserts that the specified values are not the same instance
129
     * @param message the message to report if the assertion fails
130
     * @param illegal the reference that should not be the same as actual
131
     * @param actual the actual reference
132
     */
133
    override fun assertNotSame(message: String?, illegal: Any?, actual: Any?)
134
    
135
    /**
136
     * Asserts that the specified value is not null
137
     * @param message the message to report if the assertion fails
138
     * @param actual the value to check
139
     */
140
    override fun assertNotNull(message: String?, actual: Any?)
141
    
142
    /**
143
     * Asserts that the specified value is null
144
     * @param message the message to report if the assertion fails
145
     * @param actual the value to check
146
     */
147
    override fun assertNull(message: String?, actual: Any?)
148
    
149
    /**
150
     * Fails the current test with the specified message
151
     * @param message the message to report
152
     */
153
    override fun fail(message: String?): Nothing
154
    
155
    /**
156
     * Fails the current test with the specified message and cause
157
     * Available since Kotlin 1.4
158
     * @param message the message to report
159
     * @param cause the exception to set as the root cause
160
     */
161
    override fun fail(message: String?, cause: Throwable?): Nothing
162
}
163
```
164

165
### Service Provider Integration
166

167
Automatic registration system that enables JUnit 5 integration when available.
168

169
```kotlin { .api }
170
/**
171
 * Provides JUnit5Asserter if org.junit.jupiter.api.Assertions class is found in the classpath
172
 * Registered as a service provider for kotlin.test.AsserterContributor
173
 */
174
public class JUnit5Contributor : AsserterContributor {
175
    /**
176
     * Provides asserter instance or null if JUnit 5 is not available
177
     * @return JUnit5Asserter if JUnit 5 is in classpath, null otherwise
178
     */
179
    override fun contribute(): Asserter?
180
}
181
```
182

183
## Types
184

185
### Base Interfaces
186

187
These interfaces are defined in the kotlin.test framework and implemented by this library:
188

189
```kotlin { .api }
190
/**
191
 * Abstracts the logic for performing assertions
192
 * Specific implementations can use different testing frameworks
193
 */
194
public interface Asserter {
195
    /**
196
     * Fails the current test with the specified message
197
     */
198
    fun fail(message: String?): Nothing
199
    
200
    /**
201
     * Fails the current test with the specified message and cause exception
202
     * Available since Kotlin 1.4
203
     */
204
    fun fail(message: String?, cause: Throwable?): Nothing
205
    
206
    /**
207
     * Asserts that the specified value is true
208
     * @param lazyMessage function to return a message to report if the assertion fails
209
     */
210
    fun assertTrue(lazyMessage: () -> String?, actual: Boolean): Unit
211
    
212
    /**
213
     * Asserts that the specified value is true
214
     * @param message the message to report if the assertion fails
215
     */
216
    fun assertTrue(message: String?, actual: Boolean): Unit
217
    
218
    /**
219
     * Asserts that the specified values are equal
220
     */
221
    fun assertEquals(message: String?, expected: Any?, actual: Any?)
222
    
223
    /**
224
     * Asserts that the specified values are not equal
225
     */
226
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?)
227
    
228
    /**
229
     * Asserts that the specified values are the same instance
230
     */
231
    fun assertSame(message: String?, expected: Any?, actual: Any?)
232
    
233
    /**
234
     * Asserts that the specified values are not the same instance
235
     */
236
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?)
237
    
238
    /**
239
     * Asserts that the specified value is null
240
     */
241
    fun assertNull(message: String?, actual: Any?)
242
    
243
    /**
244
     * Asserts that the specified value is not null
245
     */
246
    fun assertNotNull(message: String?, actual: Any?)
247
}
248

249
/**
250
 * Checks applicability and provides Asserter instance
251
 */
252
public interface AsserterContributor {
253
    /**
254
     * Provides Asserter instance or null depends on the current context
255
     * @return asserter instance or null if it is not applicable now
256
     */
257
    fun contribute(): Asserter?
258
}
259
```
260

261
## Dependencies
262

263
- **Compile-only**: `org.junit.jupiter:junit-jupiter-api:5.0.0+`
264
- **Runtime**: `org.junit.jupiter:junit-jupiter-engine` (for test execution)
265
- **Runtime**: `org.junit.platform:junit-platform-launcher` (for test discovery)
266
- **Transitive**: `kotlin-test` (parent kotlin test framework)
267

268
## Integration Notes
269

270
- **Automatic Detection**: The library automatically detects JUnit 5 presence via classpath reflection
271
- **No Hard Dependencies**: Uses compile-only dependency on JUnit 5 API to avoid version conflicts
272
- **Service Provider**: Registers via Java SPI (`META-INF/services/kotlin.test.AsserterContributor`)
273
- **Module System**: Provides Java 9+ module support with proper exports and service declarations
274
- **Thread Safety**: The asserter implementation is thread-safe and works in parallel test execution