0
# Kotlin Test
1

2
Kotlin Test is a comprehensive multiplatform testing framework that provides a unified API for writing tests across all Kotlin platforms (JVM, JavaScript, Native, WASM). It offers platform-agnostic test annotations and assertion functions that work consistently across different target platforms, enabling developers to write tests once and run them everywhere.
3

4
## Package Information
5

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

16
## Core Imports
17

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

22
For specific imports:
23

24
```kotlin
25
import kotlin.test.Test
26
import kotlin.test.BeforeTest
27
import kotlin.test.AfterTest
28
import kotlin.test.assertEquals
29
import kotlin.test.assertTrue
30
import kotlin.test.assertFails
31
```
32

33
## Basic Usage
34

35
```kotlin
36
import kotlin.test.*
37

38
class SimpleTest {
39
    @Test
40
    fun testBasicAssertions() {
41
        val expected = 42
42
        val actual = 6 * 7
43
        
44
        assertEquals(expected, actual)
45
        assertTrue(actual > 0)
46
        assertNotNull(actual)
47
    }
48
    
49
    @Test
50
    fun testExceptionHandling() {
51
        assertFails {
52
            throw IllegalArgumentException("Test exception")
53
        }
54
        
55
        val exception = assertFailsWith<IllegalArgumentException> {
56
            throw IllegalArgumentException("Specific exception")
57
        }
58
        assertEquals("Specific exception", exception.message)
59
    }
60
    
61
    @BeforeTest
62
    fun setup() {
63
        // Setup code before each test
64
    }
65
    
66
    @AfterTest
67
    fun teardown() {
68
        // Cleanup code after each test
69
    }
70
}
71
```
72

73
## Architecture
74

75
Kotlin Test is built around several key components:
76

77
- **Multiplatform Core**: Common API that works across all Kotlin platforms
78
- **Test Annotations**: Platform-agnostic annotations for test lifecycle management
79
- **Assertion System**: Rich set of assertion functions with optional custom messages
80
- **Asserter Interface**: Pluggable assertion backend allowing integration with different test frameworks
81
- **Platform Adapters**: Specific implementations for JUnit, JUnit 5, TestNG, and JavaScript frameworks
82

83
## Capabilities
84

85
### Test Annotations
86

87
Platform-agnostic annotations for marking test functions and lifecycle methods. These annotations are mapped to platform-specific equivalents automatically.
88

89
```kotlin { .api }
90
@Target(AnnotationTarget.FUNCTION)
91
annotation class Test
92

93
@Target(AnnotationTarget.FUNCTION)
94
annotation class BeforeTest
95

96
@Target(AnnotationTarget.FUNCTION)
97
annotation class AfterTest
98

99
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
100
annotation class Ignore
101
```
102

103
[Test Annotations](./annotations.md)
104

105
### Basic Assertions
106

107
Core assertion functions for verifying boolean conditions, equality, and identity comparisons.
108

109
```kotlin { .api }
110
fun assertTrue(actual: Boolean, message: String? = null)
111
fun assertFalse(actual: Boolean, message: String? = null)
112

113
fun <T> assertEquals(expected: T, actual: T, message: String? = null)
114
fun <T> assertNotEquals(illegal: T, actual: T, message: String? = null)
115

116
fun <T> assertSame(expected: T, actual: T, message: String? = null)
117
fun <T> assertNotSame(illegal: T, actual: T, message: String? = null)
118
```
119

120
[Basic Assertions](./basic-assertions.md)
121

122
### Type and Null Assertions
123

124
Assertions for type checking and null safety validation.
125

126
```kotlin { .api }
127
inline fun <reified T> assertIs(value: Any?, message: String? = null): T
128
inline fun <reified T> assertIsNot(value: Any?, message: String? = null)
129

130
fun <T : Any> assertNotNull(actual: T?, message: String? = null): T
131
fun assertNull(actual: Any?, message: String? = null)
132
```
133

134
[Type and Null Assertions](./type-null-assertions.md)
135

136
### Collection and Content Assertions
137

138
Comprehensive assertions for working with collections, arrays, and content comparison.
139

140
```kotlin { .api }
141
fun <T> assertContains(iterable: Iterable<T>, element: T, message: String? = null)
142
fun <T> assertContains(array: Array<T>, element: T, message: String? = null)
143
fun <K, V> assertContains(map: Map<K, V>, key: K, message: String? = null)
144
fun assertContains(charSequence: CharSequence, char: Char, ignoreCase: Boolean = false, message: String? = null)
145

146
fun <T> assertContentEquals(expected: Iterable<T>?, actual: Iterable<T>?, message: String? = null)
147
fun <T> assertContentEquals(expected: Array<T>?, actual: Array<T>?, message: String? = null)
148
```
149

150
[Collection and Content Assertions](./collection-assertions.md)
151

152
### Exception and Failure Testing
153

154
Assertions for testing exception handling and failure scenarios.
155

156
```kotlin { .api }
157
fun fail(message: String? = null): Nothing
158
fun fail(message: String? = null, cause: Throwable? = null): Nothing
159

160
inline fun assertFails(block: () -> Unit): Throwable
161
inline fun <reified T : Throwable> assertFailsWith(message: String? = null, block: () -> Unit): T
162

163
inline fun <T> expect(expected: T, block: () -> T)
164

165
fun todo(block: () -> Unit)
166
```
167

168
[Exception and Failure Testing](./exception-testing.md)
169

170
### Asserter Interface
171

172
The core assertion interface that can be customized for different testing frameworks and platforms.
173

174
```kotlin { .api }
175
interface Asserter {
176
    fun fail(message: String?): Nothing
177
    fun fail(message: String?, cause: Throwable?): Nothing
178
    fun assertTrue(message: String?, actual: Boolean): Unit
179
    fun assertEquals(message: String?, expected: Any?, actual: Any?): Unit
180
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?): Unit
181
    fun assertSame(message: String?, expected: Any?, actual: Any?): Unit
182
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?): Unit
183
    fun assertNull(message: String?, actual: Any?): Unit
184
    fun assertNotNull(message: String?, actual: Any?): Unit
185
}
186

187
val asserter: Asserter
188
```
189

190
[Asserter Interface](./asserter.md)
191

192
## Types
193

194
```kotlin { .api }
195
interface AsserterContributor {
196
    fun contribute(): Asserter?
197
}
198

199
object DefaultAsserter : Asserter
200
```