0
# Kotlin Test Common
1

2
Kotlin Test Common provides a comprehensive set of platform-agnostic test assertions and utilities for Kotlin multiplatform projects. This module enables developers to write tests that work consistently across JVM, JavaScript, Native, and other Kotlin compilation targets with a unified API for assertions, test annotations, and testing framework integration.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlin:kotlin-test-common
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-common:2.2.0")
13
  }
14
  ```
15

16
## Core Imports
17

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

22
For specific functions:
23

24
```kotlin
25
import kotlin.test.assertEquals
26
import kotlin.test.assertTrue
27
import kotlin.test.assertNotNull
28
import kotlin.test.assertFails
29
```
30

31
## Basic Usage
32

33
```kotlin
34
import kotlin.test.*
35

36
class MyTest {
37
    @Test
38
    fun testBasicAssertions() {
39
        // Boolean assertions
40
        assertTrue(5 > 3)
41
        assertFalse(2 > 5)
42
        
43
        // Equality assertions
44
        assertEquals(10, 5 + 5)
45
        assertNotEquals(10, 3 + 3)
46
        
47
        // Null assertions
48
        val result: String? = computeSomething()
49
        assertNotNull(result)
50
        assertEquals("expected", result)
51
    }
52
    
53
    @Test
54
    fun testExceptionHandling() {
55
        // Assert that a block throws an exception
56
        assertFails {
57
            throw IllegalArgumentException("Invalid input")
58
        }
59
        
60
        // Assert specific exception type
61
        assertFailsWith<IllegalArgumentException> {
62
            validateInput(null)
63
        }
64
    }
65
    
66
    @Test
67
    fun testCollections() {
68
        val numbers = listOf(1, 2, 3, 4, 5)
69
        
70
        // Collection content equality
71
        assertContentEquals(numbers, listOf(1, 2, 3, 4, 5))
72
        
73
        // Collection contains
74
        assertContains(numbers, 3)
75
        assertContains(1..10, 5)
76
    }
77
}
78
```
79

80
## Architecture
81

82
Kotlin Test Common is built around several key components:
83

84
- **Assertion Functions**: Comprehensive set of type-safe assertion functions covering equality, null checks, type checks, and collection operations
85
- **Asserter Interface**: Pluggable assertion backend that allows integration with different testing frameworks (JUnit, TestNG, etc.)
86
- **Test Annotations**: Platform-agnostic test annotations (@Test, @BeforeTest, @AfterTest, @Ignore) that map to appropriate platform-specific frameworks
87
- **Multiplatform Support**: Expect/actual declarations enable consistent behavior across all Kotlin compilation targets
88
- **Error Reporting**: Structured error messages with optional custom messages for failed assertions
89

90
## Capabilities
91

92
### Boolean Assertions
93

94
Core boolean assertion functions for testing true/false conditions with optional custom messages.
95

96
```kotlin { .api }
97
fun assertTrue(actual: Boolean, message: String? = null)
98
fun assertTrue(message: String? = null, block: () -> Boolean)
99
fun assertFalse(actual: Boolean, message: String? = null)
100
fun assertFalse(message: String? = null, block: () -> Boolean)
101
```
102

103
[Boolean Assertions](./boolean-assertions.md)
104

105
### Equality Assertions
106

107
Equality and inequality assertions with support for tolerance-based floating point comparisons and instance reference checks.
108

109
```kotlin { .api }
110
fun <T> assertEquals(expected: T, actual: T, message: String? = null)
111
fun assertEquals(expected: Double, actual: Double, absoluteTolerance: Double, message: String? = null)
112
fun assertEquals(expected: Float, actual: Float, absoluteTolerance: Float, message: String? = null)
113
fun <T> assertNotEquals(illegal: T, actual: T, message: String? = null)
114
fun <T> assertSame(expected: T, actual: T, message: String? = null)
115
fun <T> assertNotSame(illegal: T, actual: T, message: String? = null)
116
```
117

118
[Equality Assertions](./equality-assertions.md)
119

120
### Type and Null Assertions
121

122
Type checking and null safety assertions with smart cast support and contract-based APIs.
123

124
```kotlin { .api }
125
inline fun <reified T> assertIs(value: Any?, message: String? = null): T
126
inline fun <reified T> assertIsNot(value: Any?, message: String? = null)
127
fun <T : Any> assertNotNull(actual: T?, message: String? = null): T
128
fun <T : Any, R> assertNotNull(actual: T?, message: String? = null, block: (T) -> R): R
129
fun assertNull(actual: Any?, message: String? = null)
130
```
131

132
[Type and Null Assertions](./type-null-assertions.md)
133

134
### Collection and Array Assertions
135

136
Content equality and membership testing for collections, arrays, ranges, maps, and strings with support for all Kotlin types.
137

138
```kotlin { .api }
139
fun <T> assertContains(iterable: Iterable<T>, element: T, message: String? = null)
140
fun <T> assertContains(array: Array<T>, element: T, message: String? = null)
141
fun <T> assertContentEquals(expected: Iterable<T>?, actual: Iterable<T>?, message: String? = null)
142
fun <T> assertContentEquals(expected: Array<T>?, actual: Array<T>?, message: String? = null)
143
fun assertContains(range: IntRange, value: Int, message: String? = null)
144
fun <K, V> assertContains(map: Map<K, V>, key: K, message: String? = null)
145
```
146

147
[Collection and Array Assertions](./collection-assertions.md)
148

149
### Exception Testing
150

151
Exception assertion functions for testing error conditions with support for specific exception types and cause chains.
152

153
```kotlin { .api }
154
fun assertFails(block: () -> Unit): Throwable
155
fun assertFails(message: String?, block: () -> Unit): Throwable
156
inline fun <reified T : Throwable> assertFailsWith(message: String? = null, block: () -> Unit): T
157
fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, block: () -> Unit): T
158
```
159

160
[Exception Testing](./exception-testing.md)
161

162
### Test Utilities
163

164
Core utility functions for test execution and expectation validation.
165

166
```kotlin { .api }
167
fun <T> expect(expected: T, block: () -> T)
168
fun <T> expect(expected: T, message: String?, block: () -> T)
169
fun fail(message: String? = null): Nothing
170
fun fail(message: String? = null, cause: Throwable? = null): Nothing
171
fun todo(block: () -> Unit)
172
```
173

174
[Test Utilities](./test-utilities.md)
175

176
### Test Framework Integration
177

178
Core interfaces and utilities for integrating with different testing frameworks across platforms.
179

180
```kotlin { .api }
181
interface Asserter {
182
    fun fail(message: String?): Nothing
183
    fun fail(message: String?, cause: Throwable?): Nothing
184
    fun assertTrue(message: String?, actual: Boolean)
185
    fun assertEquals(message: String?, expected: Any?, actual: Any?)
186
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?)
187
    fun assertSame(message: String?, expected: Any?, actual: Any?)
188
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?)
189
    fun assertNull(message: String?, actual: Any?)
190
    fun assertNotNull(message: String?, actual: Any?)
191
}
192

193
var asserter: Asserter
194
```
195

196
[Framework Integration](./framework-integration.md)
197

198
### Test Annotations
199

200
Platform-agnostic test annotations that map to appropriate testing frameworks on each Kotlin compilation target.
201

202
```kotlin { .api }
203
@Target(AnnotationTarget.FUNCTION)
204
annotation class Test
205

206
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
207
annotation class Ignore
208

209
@Target(AnnotationTarget.FUNCTION)
210
annotation class BeforeTest
211

212
@Target(AnnotationTarget.FUNCTION)
213
annotation class AfterTest
214
```
215

216
[Test Annotations](./test-annotations.md)