0
# Basic Assertions
1

2
Core assertion functions for verifying boolean conditions, equality, and identity comparisons. These are the most commonly used assertions in Kotlin Test.
3

4
## Capabilities
5

6
### Boolean Assertions
7

8
#### assertTrue Function
9

10
Asserts that a Boolean expression or lambda returns true.
11

12
```kotlin { .api }
13
/**
14
 * Asserts that the expression is true with an optional message
15
 * @param actual - Boolean value to check
16
 * @param message - Optional custom failure message
17
 */
18
fun assertTrue(actual: Boolean, message: String? = null)
19

20
/**
21
 * Asserts that the given block returns true
22
 * @param message - Optional custom failure message
23
 * @param block - Lambda that should return true
24
 */
25
inline fun assertTrue(message: String? = null, block: () -> Boolean)
26
```
27

28
**Usage Examples:**
29

30
```kotlin
31
import kotlin.test.*
32

33
@Test
34
fun testTrueAssertions() {
35
    // Direct boolean check
36
    assertTrue(5 > 3)
37
    assertTrue(true, "This should always pass")
38
    
39
    // Lambda form
40
    assertTrue("List should not be empty") { 
41
        listOf(1, 2, 3).isNotEmpty() 
42
    }
43
    
44
    // With calculation
45
    val result = calculateValue()
46
    assertTrue(result > 0, "Result should be positive: $result")
47
}
48
```
49

50
#### assertFalse Function
51

52
Asserts that a Boolean expression or lambda returns false.
53

54
```kotlin { .api }
55
/**
56
 * Asserts that the expression is false with an optional message
57
 * @param actual - Boolean value to check
58
 * @param message - Optional custom failure message
59
 */
60
fun assertFalse(actual: Boolean, message: String? = null)
61

62
/**
63
 * Asserts that the given block returns false
64
 * @param message - Optional custom failure message
65
 * @param block - Lambda that should return false
66
 */
67
inline fun assertFalse(message: String? = null, block: () -> Boolean)
68
```
69

70
**Usage Examples:**
71

72
```kotlin
73
@Test
74
fun testFalseAssertions() {
75
    // Direct boolean check
76
    assertFalse(5 < 3)
77
    assertFalse(false, "This should always pass")
78
    
79
    // Lambda form
80
    assertFalse("List should be empty") { 
81
        emptyList<Int>().isNotEmpty() 
82
    }
83
    
84
    // With string operations
85
    val text = "hello"
86
    assertFalse(text.contains("world"), "Text should not contain 'world'")
87
}
88
```
89

90
### Equality Assertions
91

92
#### assertEquals Function
93

94
Asserts that two values are equal using the `equals` method.
95

96
```kotlin { .api }
97
/**
98
 * Asserts that the expected value is equal to the actual value
99
 * @param expected - Expected value
100
 * @param actual - Actual value to compare
101
 * @param message - Optional custom failure message
102
 */
103
fun <T> assertEquals(expected: T, actual: T, message: String? = null)
104

105
/**
106
 * Asserts that doubles are equal within an absolute tolerance
107
 * @param expected - Expected double value
108
 * @param actual - Actual double value
109
 * @param absoluteTolerance - Maximum allowed difference
110
 * @param message - Optional custom failure message
111
 */
112
fun assertEquals(expected: Double, actual: Double, absoluteTolerance: Double, message: String? = null)
113

114
/**
115
 * Asserts that floats are equal within an absolute tolerance
116
 * @param expected - Expected float value
117
 * @param actual - Actual float value
118
 * @param absoluteTolerance - Maximum allowed difference
119
 * @param message - Optional custom failure message
120
 */
121
fun assertEquals(expected: Float, actual: Float, absoluteTolerance: Float, message: String? = null)
122
```
123

124
**Usage Examples:**
125

126
```kotlin
127
@Test
128
fun testEquality() {
129
    // Basic equality
130
    assertEquals(42, 6 * 7)
131
    assertEquals("hello", "he" + "llo")
132
    
133
    // Collections
134
    assertEquals(listOf(1, 2, 3), mutableListOf(1, 2, 3))
135
    
136
    // With message
137
    val userName = getUserName()
138
    assertEquals("admin", userName, "User should be admin")
139
    
140
    // Floating point with tolerance
141
    assertEquals(0.1 + 0.2, 0.3, 0.0001, "Floating point addition")
142
    assertEquals(3.14f, calculatePi(), 0.01f, "Pi approximation")
143
}
144
```
145

146
#### assertNotEquals Function
147

148
Asserts that two values are not equal.
149

150
```kotlin { .api }
151
/**
152
 * Asserts that the actual value is not equal to the illegal value
153
 * @param illegal - Value that should not match
154
 * @param actual - Actual value to compare
155
 * @param message - Optional custom failure message
156
 */
157
fun <T> assertNotEquals(illegal: T, actual: T, message: String? = null)
158

159
/**
160
 * Asserts that doubles are not equal within an absolute tolerance
161
 * @param illegal - Double value that should not match
162
 * @param actual - Actual double value
163
 * @param absoluteTolerance - Tolerance for comparison
164
 * @param message - Optional custom failure message
165
 */
166
fun assertNotEquals(illegal: Double, actual: Double, absoluteTolerance: Double, message: String? = null)
167

168
/**
169
 * Asserts that floats are not equal within an absolute tolerance
170
 * @param illegal - Float value that should not match
171
 * @param actual - Actual float value
172
 * @param absoluteTolerance - Tolerance for comparison
173
 * @param message - Optional custom failure message
174
 */
175
fun assertNotEquals(illegal: Float, actual: Float, absoluteTolerance: Float, message: String? = null)
176
```
177

178
**Usage Examples:**
179

180
```kotlin
181
@Test
182
fun testInequality() {
183
    // Basic inequality
184
    assertNotEquals(0, 5)
185
    assertNotEquals("hello", "world")
186
    
187
    // Different object instances
188
    assertNotEquals(listOf(1, 2), listOf(3, 4))
189
    
190
    // With message
191
    val sessionId = generateSessionId()
192
    assertNotEquals("", sessionId, "Session ID should not be empty")
193
    
194
    // Floating point with tolerance
195
    assertNotEquals(0.1, 0.2, 0.05, "Values should be different")
196
}
197
```
198

199
### Identity Assertions
200

201
#### assertSame Function
202

203
Asserts that two references point to the same object instance (using `===`).
204

205
```kotlin { .api }
206
/**
207
 * Asserts that expected and actual refer to the same instance
208
 * @param expected - Expected object reference
209
 * @param actual - Actual object reference
210
 * @param message - Optional custom failure message
211
 */
212
fun <T> assertSame(expected: T, actual: T, message: String? = null)
213
```
214

215
**Usage Examples:**
216

217
```kotlin
218
@Test
219
fun testSameInstance() {
220
    val list = mutableListOf(1, 2, 3)
221
    val sameList = list
222
    
223
    // Same reference
224
    assertSame(list, sameList)
225
    
226
    // Singleton pattern
227
    val singleton1 = MySingleton.getInstance()
228
    val singleton2 = MySingleton.getInstance()
229
    assertSame(singleton1, singleton2, "Singleton should return same instance")
230
}
231
```
232

233
#### assertNotSame Function
234

235
Asserts that two references do not point to the same object instance.
236

237
```kotlin { .api }
238
/**
239
 * Asserts that illegal and actual do not refer to the same instance
240
 * @param illegal - Object reference that should not match
241
 * @param actual - Actual object reference
242
 * @param message - Optional custom failure message
243
 */
244
fun <T> assertNotSame(illegal: T, actual: T, message: String? = null)
245
```
246

247
**Usage Examples:**
248

249
```kotlin
250
@Test
251
fun testDifferentInstances() {
252
    val list1 = mutableListOf(1, 2, 3)
253
    val list2 = mutableListOf(1, 2, 3)
254
    
255
    // Different instances (even with same content)
256
    assertNotSame(list1, list2)
257
    
258
    // Object creation
259
    val obj1 = createNewObject()
260
    val obj2 = createNewObject()
261
    assertNotSame(obj1, obj2, "Factory should create different instances")
262
}
263
```
264

265
## Common Patterns
266

267
### Chaining Assertions
268

269
```kotlin
270
@Test
271
fun testMultipleAssertions() {
272
    val result = processData("input")
273
    
274
    // Multiple assertions on the same result
275
    assertTrue(result.isNotEmpty(), "Result should not be empty")
276
    assertEquals("processed", result.status)
277
    assertNotEquals(0, result.timestamp)
278
}
279
```
280

281
### Custom Error Messages
282

283
```kotlin
284
@Test
285
fun testWithCustomMessages() {
286
    val user = authenticateUser("testuser", "password")
287
    
288
    assertNotNull(user, "User authentication should succeed")
289
    assertEquals("testuser", user.username, "Username should match input")
290
    assertTrue(user.isActive, "User should be active after authentication")
291
}
292
```
293

294
### Testing Edge Cases
295

296
```kotlin
297
@Test
298
fun testEdgeCases() {
299
    // Empty values
300
    assertEquals("", "".trim())
301
    assertTrue(emptyList<Int>().isEmpty())
302
    
303
    // Boundary values
304
    assertEquals(Int.MAX_VALUE, Int.MAX_VALUE)
305
    assertEquals(0.0, -0.0) // Special case for doubles
306
    
307
    // Floating point precision
308
    val calculated = 0.1 + 0.1 + 0.1
309
    assertEquals(0.3, calculated, 0.0001)
310
}