0
# Asserter System
1

2
The underlying assertion engine that provides the foundation for all assertion functions. The Asserter system enables customizable error handling, test failure reporting, and extensible assertion logic for Kotlin/WASM-JS testing environments.
3

4
## Capabilities
5

6
### Asserter Interface
7

8
The core interface that defines how assertions are processed and how test failures are handled.
9

10
```kotlin { .api }
11
/**
12
 * Provides the foundation for all assertion functions
13
 * Handles test failure reporting and assertion logic
14
 */
15
interface Asserter {
16
    /**
17
     * Fails the current test with the given message
18
     * @param message the failure message
19
     * @throws AssertionError always throws to indicate test failure
20
     */
21
    fun fail(message: String?): Nothing
22
    
23
    /**
24
     * Fails the current test with the given message and underlying cause
25
     * @param message the failure message
26
     * @param cause the underlying cause of the failure
27
     * @throws AssertionError always throws to indicate test failure
28
     */
29
    fun fail(message: String?, cause: Throwable?): Nothing
30
    
31
    /**
32
     * Asserts that the value is true
33
     * @param lazyMessage function that produces failure message if assertion fails
34
     * @param actual the value to check
35
     */
36
    fun assertTrue(lazyMessage: () -> String?, actual: Boolean): Unit
37
    
38
    /**
39
     * Asserts that the value is true with a simple message
40
     * @param message the failure message
41
     * @param actual the value to check
42
     */
43
    fun assertTrue(message: String?, actual: Boolean): Unit
44
    
45
    /**
46
     * Asserts that expected and actual values are equal
47
     * @param message the failure message
48
     * @param expected the expected value
49
     * @param actual the actual value
50
     */
51
    fun assertEquals(message: String?, expected: Any?, actual: Any?): Unit
52
    
53
    /**
54
     * Asserts that illegal and actual values are not equal
55
     * @param message the failure message
56
     * @param illegal the value that actual should not equal
57
     * @param actual the actual value
58
     */
59
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?): Unit
60
    
61
    /**
62
     * Asserts that expected and actual are the same object reference
63
     * @param message the failure message
64
     * @param expected the expected object reference
65
     * @param actual the actual object reference
66
     */
67
    fun assertSame(message: String?, expected: Any?, actual: Any?): Unit
68
    
69
    /**
70
     * Asserts that illegal and actual are not the same object reference
71
     * @param message the failure message
72
     * @param illegal the reference that actual should not be
73
     * @param actual the actual object reference
74
     */
75
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?): Unit
76
    
77
    /**
78
     * Asserts that the value is null
79
     * @param message the failure message
80
     * @param actual the value to check
81
     */
82
    fun assertNull(message: String?, actual: Any?): Unit
83
    
84
    /**
85
     * Asserts that the value is not null
86
     * @param message the failure message
87
     * @param actual the value to check
88
     */
89
    fun assertNotNull(message: String?, actual: Any?): Unit
90
}
91
```
92

93
### Current Asserter Access
94

95
Global property providing access to the currently active asserter instance.
96

97
```kotlin { .api }
98
/**
99
 * The current asserter instance used by all assertion functions
100
 * This property provides access to the active asserter for custom assertion logic
101
 */
102
val asserter: Asserter
103
```
104

105
**Usage Example:**
106

107
```kotlin
108
import kotlin.test.*
109

110
class CustomAssertionTests {
111
    @Test
112
    fun customAssertion() {
113
        // Use the global asserter directly for custom logic
114
        val user = createUser()
115
        if (user.email.isEmpty() || !user.email.contains("@")) {
116
            asserter.fail("User must have a valid email address")
117
        }
118
        
119
        // All standard assertions use this same asserter internally
120
        assertTrue(user.isActive)
121
        assertEquals("John Doe", user.name)
122
    }
123
}
124
```
125

126
### AsserterContributor Interface
127

128
Interface for providing custom asserter implementations that can be contributed to the assertion system.
129

130
```kotlin { .api }
131
/**
132
 * Interface for contributing custom Asserter implementations
133
 * Allows frameworks and libraries to provide specialized assertion behavior
134
 */
135
interface AsserterContributor {
136
    /**
137
     * Returns an Asserter instance or null if not contributing
138
     * @return Asserter instance to use, or null to skip this contributor
139
     */
140
    fun contribute(): Asserter?
141
}
142
```
143

144
**Usage Example:**
145

146
```kotlin
147
import kotlin.test.*
148

149
class CustomAsserterContributor : AsserterContributor {
150
    override fun contribute(): Asserter? {
151
        return if (isTestEnvironment()) {
152
            CustomTestAsserter()
153
        } else {
154
            null // Use default asserter
155
        }
156
    }
157
}
158

159
class CustomTestAsserter : Asserter {
160
    override fun fail(message: String?): Nothing {
161
        // Custom failure handling - e.g., enhanced logging
162
        logTestFailure(message)
163
        throw AssertionError(message)
164
    }
165
    
166
    override fun fail(message: String?, cause: Throwable?): Nothing {
167
        logTestFailure(message, cause)
168
        throw AssertionError(message, cause)
169
    }
170
    
171
    override fun assertTrue(lazyMessage: () -> String?, actual: Boolean) {
172
        if (!actual) {
173
            fail(lazyMessage())
174
        }
175
    }
176
    
177
    override fun assertTrue(message: String?, actual: Boolean) {
178
        if (!actual) {
179
            fail(message ?: "Expected true but was false")
180
        }
181
    }
182
    
183
    override fun assertEquals(message: String?, expected: Any?, actual: Any?) {
184
        if (expected != actual) {
185
            fail(message ?: "Expected <$expected> but was <$actual>")
186
        }
187
    }
188
    
189
    // ... implement other assertion methods
190
}
191
```
192

193
### WASM-Specific Assertion Features
194

195
WebAssembly-specific interfaces and functionality for optimized assertion processing.
196

197
```kotlin { .api }
198
/**
199
 * WASM-specific assertion result interface for enhanced assertion processing
200
 * Provides structured information about assertion outcomes
201
 */
202
interface AssertionResult {
203
    /**
204
     * Whether the assertion passed or failed
205
     */
206
    val result: Boolean
207
    
208
    /**
209
     * The expected value in the assertion
210
     */
211
    val expected: Any?
212
    
213
    /**
214
     * The actual value in the assertion
215
     */
216
    val actual: Any?
217
    
218
    /**
219
     * Lazy evaluation of the failure message
220
     */
221
    val lazyMessage: () -> String?
222
}
223
```
224

225
### Assertion Function Integration
226

227
How high-level assertion functions integrate with the Asserter system:
228

229
**Example Internal Implementation:**
230

231
```kotlin
232
// This shows how assertion functions use the asserter system internally
233
fun <T> assertEquals(expected: T, actual: T, message: String?) {
234
    asserter.assertEquals(message, expected, actual)
235
}
236

237
fun assertTrue(actual: Boolean, message: String?) {
238
    asserter.assertTrue(message, actual)
239
}
240

241
inline fun assertTrue(message: String?, block: () -> Boolean) {
242
    asserter.assertTrue(message, block())
243
}
244

245
fun fail(message: String?): Nothing {
246
    asserter.fail(message)
247
}
248
```
249

250
### Error Message Formatting
251

252
The Asserter system handles consistent error message formatting across all assertion types:
253

254
**Standard Message Patterns:**
255
- Equality failures: `"Expected <expected> but was <actual>"`
256
- Boolean failures: `"Expected true but was false"`
257
- Null failures: `"Expected null but was <actual>"`
258
- Custom messages: User-provided message takes precedence
259

260
**Custom Message Examples:**
261

262
```kotlin
263
import kotlin.test.*
264

265
class MessageFormattingTests {
266
    @Test 
267
    fun customMessages() {
268
        val user = User("John", 25)
269
        
270
        assertEquals("User name should match", "Jane", user.name) 
271
        // Failure: "User name should match"
272
        
273
        assertTrue("User should be adult") { user.age >= 18 }
274
        // Success: no message needed
275
        
276
        assertNotNull(user.email, "User must have email configured")
277
        // Failure: "User must have email configured"
278
    }
279
}
280
```
281

282
### Framework Integration
283

284
The Asserter system seamlessly integrates with JavaScript testing frameworks through automatic adapter detection:
285

286
- **Jasmine/Mocha/Jest**: Assertions throw JavaScript-compatible errors that are properly reported by the test framework
287
- **TeamCity**: Assertion failures are formatted as TeamCity service messages for CI integration
288
- **Custom Frameworks**: Can provide custom Asserter implementations via AsserterContributor
289

290
**Environment Detection:**
291

292
```kotlin
293
// The system automatically detects the testing environment and configures
294
// the appropriate asserter for optimal integration:
295

296
// In Jasmine/Mocha/Jest environments:
297
// - Assertion failures become JavaScript Error objects
298
// - Stack traces are preserved and properly formatted
299
// - Async test failures are handled through Promise rejection
300

301
// In TeamCity environments: 
302
// - Failures are reported as ##teamcity[testFailed] messages
303
// - Test lifecycle is tracked with proper flow IDs
304
// - Error details are escaped for TeamCity parsing
305
```
306

307
This system provides a flexible, extensible foundation for all testing assertions while maintaining compatibility with various JavaScript testing environments and frameworks.