0
# Equality Assertions
1

2
Equality and inequality assertions providing precise comparison testing with support for tolerance-based floating point comparisons and instance reference checks. These functions are essential for verifying expected values and object relationships in tests.
3

4
## Capabilities
5

6
### assertEquals
7

8
Asserts that two values are equal using structural equality.
9

10
```kotlin { .api }
11
/**
12
 * Asserts that the expected and actual values are equal.
13
 * Uses structural equality (equals() method).
14
 * @param expected The expected value
15
 * @param actual The actual value to compare
16
 * @param message Optional message to show if assertion fails
17
 */
18
fun <T> assertEquals(expected: T, actual: T, message: String? = null)
19

20
/**
21
 * Asserts that two Double values are equal within the given absolute tolerance.
22
 * @param expected The expected Double value
23
 * @param actual The actual Double value to compare
24
 * @param absoluteTolerance The maximum allowed difference between the values
25
 * @param message Optional message to show if assertion fails
26
 * @since Kotlin 1.5
27
 */
28
fun assertEquals(expected: Double, actual: Double, absoluteTolerance: Double, message: String? = null)
29

30
/**
31
 * Asserts that two Float values are equal within the given absolute tolerance.
32
 * @param expected The expected Float value
33
 * @param actual The actual Float value to compare
34
 * @param absoluteTolerance The maximum allowed difference between the values
35
 * @param message Optional message to show if assertion fails
36
 * @since Kotlin 1.5
37
 */
38
fun assertEquals(expected: Float, actual: Float, absoluteTolerance: Float, message: String? = null)
39
```
40

41
**Usage Examples:**
42

43
```kotlin
44
import kotlin.test.assertEquals
45

46
@Test
47
fun testEquality() {
48
    // Basic equality
49
    assertEquals(42, 40 + 2)
50
    assertEquals("hello", "hel" + "lo")
51
    assertEquals(listOf(1, 2, 3), mutableListOf(1, 2, 3))
52
    
53
    // With custom messages
54
    assertEquals(100, calculateScore(), "Score calculation should return 100")
55
    
56
    // Floating point equality with tolerance
57
    assertEquals(3.14159, calculatePi(), 0.001, "Pi calculation should be accurate")
58
    assertEquals(2.5f, calculateAverage(), 0.1f, "Average should be close to 2.5")
59
    
60
    // Object equality
61
    val expected = User("Alice", 25)
62
    val actual = createUser("Alice", 25)
63
    assertEquals(expected, actual, "Users should be equal")
64
}
65
```
66

67
### assertNotEquals
68

69
Asserts that two values are not equal using structural equality.
70

71
```kotlin { .api }
72
/**
73
 * Asserts that the illegal and actual values are not equal.
74
 * Uses structural equality (equals() method).
75
 * @param illegal The value that should not match
76
 * @param actual The actual value to compare
77
 * @param message Optional message to show if assertion fails
78
 */
79
fun <T> assertNotEquals(illegal: T, actual: T, message: String? = null)
80

81
/**
82
 * Asserts that two Double values are not equal within the given absolute tolerance.
83
 * @param illegal The Double value that should not match
84
 * @param actual The actual Double value to compare
85
 * @param absoluteTolerance The minimum required difference between the values
86
 * @param message Optional message to show if assertion fails
87
 * @since Kotlin 1.5
88
 */
89
fun assertNotEquals(illegal: Double, actual: Double, absoluteTolerance: Double, message: String? = null)
90

91
/**
92
 * Asserts that two Float values are not equal within the given absolute tolerance.
93
 * @param illegal The Float value that should not match
94
 * @param actual The actual Float value to compare
95
 * @param absoluteTolerance The minimum required difference between the values
96
 * @param message Optional message to show if assertion fails
97
 * @since Kotlin 1.5
98
 */
99
fun assertNotEquals(illegal: Float, actual: Float, absoluteTolerance: Float, message: String? = null)
100
```
101

102
**Usage Examples:**
103

104
```kotlin
105
import kotlin.test.assertNotEquals
106

107
@Test
108
fun testInequality() {
109
    // Basic inequality
110
    assertNotEquals(0, 1 + 1)
111
    assertNotEquals("hello", "world")
112
    assertNotEquals(listOf(1, 2, 3), listOf(3, 2, 1))
113
    
114
    // With custom messages
115
    assertNotEquals(0, generateRandomNumber(), "Random number should not be zero")
116
    
117
    // Floating point inequality with tolerance
118
    assertNotEquals(0.0, calculateNonZeroValue(), 0.001, "Value should be significantly non-zero")
119
    assertNotEquals(1.0f, calculateRatio(), 0.1f, "Ratio should not be close to 1.0")
120
}
121
```
122

123
### assertSame
124

125
Asserts that two references point to the same object instance.
126

127
```kotlin { .api }
128
/**
129
 * Asserts that expected and actual are the same instance (reference equality).
130
 * Uses identity equality (=== operator).
131
 * @param expected The expected object reference
132
 * @param actual The actual object reference to compare
133
 * @param message Optional message to show if assertion fails
134
 */
135
fun <T> assertSame(expected: T, actual: T, message: String? = null)
136
```
137

138
**Usage Examples:**
139

140
```kotlin
141
import kotlin.test.assertSame
142

143
@Test
144
fun testSameInstance() {
145
    // Singleton pattern testing
146
    val instance1 = DatabaseConnection.getInstance()
147
    val instance2 = DatabaseConnection.getInstance()
148
    assertSame(instance1, instance2, "Should return same singleton instance")
149
    
150
    // Object reference testing
151
    val originalList = mutableListOf(1, 2, 3)
152
    val returnedList = processListInPlace(originalList)
153
    assertSame(originalList, returnedList, "Should return the same list instance")
154
    
155
    // String interning
156
    val str1 = "hello"
157
    val str2 = "hello"
158
    assertSame(str1, str2, "String literals should be interned")
159
}
160
```
161

162
### assertNotSame
163

164
Asserts that two references do not point to the same object instance.
165

166
```kotlin { .api }
167
/**
168
 * Asserts that illegal and actual are not the same instance (reference inequality).
169
 * Uses identity equality (=== operator).
170
 * @param illegal The object reference that should not match
171
 * @param actual The actual object reference to compare
172
 * @param message Optional message to show if assertion fails
173
 */
174
fun <T> assertNotSame(illegal: T, actual: T, message: String? = null)
175
```
176

177
**Usage Examples:**
178

179
```kotlin
180
import kotlin.test.assertNotSame
181

182
@Test
183
fun testDifferentInstances() {
184
    // Copy operations should create new instances
185
    val original = User("Alice", 25)
186
    val copy = original.copy()
187
    assertNotSame(original, copy, "Copy should create a new instance")
188
    
189
    // Factory methods should create new instances
190
    val config1 = Configuration.create()
191
    val config2 = Configuration.create()
192
    assertNotSame(config1, config2, "Factory should create new instances")
193
    
194
    // List copying
195
    val originalList = listOf(1, 2, 3)
196
    val copiedList = originalList.toList()
197
    assertNotSame(originalList, copiedList, "toList() should create new instance")
198
}
199
```
200

201
## Error Handling
202

203
Equality assertion functions will throw an `AssertionError` when comparisons fail:
204

205
- **assertEquals**: Throws when values are not equal (or not within tolerance for floating point)
206
- **assertNotEquals**: Throws when values are equal (or within tolerance for floating point)  
207
- **assertSame**: Throws when references are not identical
208
- **assertNotSame**: Throws when references are identical
209

210
Error messages include the expected and actual values for debugging:
211

212
```kotlin
213
// This will throw: AssertionError: Expected <42>, actual <43>.
214
assertEquals(42, 43)
215

216
// This will throw: AssertionError: Expected not same but was same: <User(name=Alice)>
217
assertNotSame(user1, user1)
218
```