0
# Kotlin Test WebAssembly JS
1

2
Kotlin Test WebAssembly JS provides comprehensive testing functionality for WebAssembly applications targeting JavaScript environments. This library enables developers to write unit tests for Kotlin/Wasm code using familiar kotlin.test APIs with automatic integration to popular JavaScript testing frameworks like Jasmine, Mocha, Jest, and TeamCity.
3

4
## Package Information
5

6
- **Package Name**: kotlin-test-wasm-js
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Coordinates**: `org.jetbrains.kotlin:kotlin-test-wasm-js:2.2.0`
10

11
## Core Imports
12

13
```kotlin
14
import kotlin.test.*
15
```
16

17
For test annotations and all assertion functions:
18

19
```kotlin
20
import kotlin.test.Test
21
import kotlin.test.BeforeTest
22
import kotlin.test.AfterTest
23
import kotlin.test.Ignore
24
import kotlin.test.assertEquals
25
import kotlin.test.assertTrue
26
import kotlin.test.assertFalse
27
import kotlin.test.assertNull
28
import kotlin.test.assertNotNull
29
import kotlin.test.assertContains
30
import kotlin.test.assertFails
31
import kotlin.test.fail
32
```
33

34
For async testing with JavaScript Promises:
35

36
```kotlin
37
import kotlin.js.Promise
38
```
39

40
## Basic Usage
41

42
```kotlin
43
import kotlin.test.*
44
import kotlin.js.Promise
45

46
class BasicTests {
47
    
48
    @BeforeTest
49
    fun setup() {
50
        // Setup code runs before each test
51
    }
52
    
53
    @Test
54
    fun equalityAssertions() {
55
        assertEquals(4, 2 + 2)
56
        assertEquals("hello", "hello")
57
        assertEquals(3.14, 3.14, 0.01) // With tolerance for floats
58
    }
59
    
60
    @Test
61
    fun booleanAssertions() {
62
        assertTrue(5 > 3)
63
        assertFalse(listOf<String>().isNotEmpty())
64
    }
65
    
66
    @Test
67
    fun nullAssertions() {
68
        val value: String? = "test"
69
        assertNotNull(value) // Returns non-null value
70
        assertEquals("test", value) // value is now smart-cast to String
71
        
72
        assertNull(null)
73
    }
74
    
75
    @Test 
76
    fun collectionAssertions() {
77
        val list = listOf(1, 2, 3)
78
        assertContains(list, 2)
79
        assertContentEquals(listOf(1, 2, 3), list)
80
    }
81
    
82
    @Test
83
    fun exceptionAssertions() {
84
        assertFails {
85
            throw RuntimeException("Error")
86
        }
87
        
88
        val exception = assertFailsWith<IllegalArgumentException> {
89
            throw IllegalArgumentException("Invalid argument")
90
        }
91
        assertEquals("Invalid argument", exception.message)
92
    }
93
    
94
    @Test
95
    fun asyncTestWithPromise(): Promise<*> {
96
        return Promise.resolve(42).then { result ->
97
            assertEquals(42, result)
98
        }
99
    }
100
    
101
    @Ignore("Test is disabled")
102
    @Test
103
    fun ignoredTest() {
104
        fail("This test should not run")
105
    }
106
    
107
    @AfterTest
108
    fun cleanup() {
109
        // Cleanup code runs after each test
110
    }
111
}
112
```
113

114
## Architecture
115

116
Kotlin Test WASM-JS provides a complete testing solution with three main layers:
117

118
- **Test Annotations**: `@Test`, `@BeforeTest`, `@AfterTest`, `@Ignore` for marking test functions and lifecycle methods
119
- **Assertion Engine**: Comprehensive assertion functions for all common testing scenarios with the `Asserter` interface providing the foundation
120
- **Framework Integration**: Automatic detection and integration with JavaScript testing frameworks, supporting both synchronous and asynchronous tests with Promise handling
121
- **WASM-Specific Features**: Optimized assertion processing and error handling designed for WebAssembly environments
122

123
## Capabilities
124

125
### Test Annotations
126

127
Annotations for marking test functions and controlling test lifecycle, providing the foundation for organizing and running tests.
128

129
```kotlin { .api }
130
@Target(AnnotationTarget.FUNCTION)
131
@Retention(AnnotationRetention.RUNTIME)
132
annotation class Test
133

134
@Target(AnnotationTarget.FUNCTION)
135
@Retention(AnnotationRetention.RUNTIME) 
136
annotation class BeforeTest
137

138
@Target(AnnotationTarget.FUNCTION)
139
@Retention(AnnotationRetention.RUNTIME)
140
annotation class AfterTest
141

142
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
143
@Retention(AnnotationRetention.RUNTIME)
144
annotation class Ignore(val value: String = "")
145
```
146

147
[Test Annotations](./annotations.md)
148

149
### Core Assertions
150

151
Essential assertion functions for verifying test conditions, covering equality, boolean, null, and type checks.
152

153
```kotlin { .api }
154
fun <T> assertEquals(expected: T, actual: T, message: String? = null)
155
fun assertEquals(expected: Double, actual: Double, absoluteTolerance: Double, message: String? = null)
156
fun assertEquals(expected: Float, actual: Float, absoluteTolerance: Float, message: String? = null)
157
fun assertTrue(actual: Boolean, message: String? = null)
158
fun assertFalse(actual: Boolean, message: String? = null)
159
fun <T : Any> assertNotNull(actual: T?, message: String? = null): T
160
fun assertNull(actual: Any?, message: String? = null)
161
fun <T> assertSame(expected: T, actual: T, message: String? = null)
162
fun <T> assertNotSame(illegal: T, actual: T, message: String? = null)
163
```
164

165
[Core Assertions](./assertions.md)
166

167
### Collection Assertions
168

169
Specialized assertion functions for validating collection contents, array equality, and element containment across all Kotlin collection types.
170

171
```kotlin { .api }
172
fun <T> assertContains(iterable: Iterable<T>, element: T, message: String? = null)
173
fun <T> assertContains(array: Array<T>, element: T, message: String? = null)
174
fun <T> assertContentEquals(expected: Iterable<T>?, actual: Iterable<T>?, message: String? = null)
175
fun <T> assertContentEquals(expected: Array<T>?, actual: Array<T>?, message: String? = null)
176
fun assertContains(charSequence: CharSequence, char: Char, ignoreCase: Boolean = false, message: String? = null)
177
fun <K, V> assertContains(map: Map<K, V>, key: K, message: String? = null)
178
```
179

180
[Collection Assertions](./assertions.md)
181

182
### Exception Assertions
183

184
Functions for testing exception behavior and validating error conditions in test code.
185

186
```kotlin { .api }
187
inline fun assertFails(block: () -> Any?): Throwable
188
inline fun assertFails(message: String?, block: () -> Any?): Throwable
189
inline fun <reified T : Throwable> assertFailsWith(message: String? = null, block: () -> Any?): T
190
inline fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, message: String?, block: () -> Any?): T
191
```
192

193
[Exception Assertions](./assertions.md)
194

195
### Asserter System
196

197
The underlying assertion engine that provides the foundation for all assertion functions, with customizable error handling and reporting.
198

199
```kotlin { .api }
200
interface Asserter {
201
    fun fail(message: String?): Nothing
202
    fun fail(message: String?, cause: Throwable?): Nothing
203
    fun assertTrue(lazyMessage: () -> String?, actual: Boolean): Unit
204
    fun assertEquals(message: String?, expected: Any?, actual: Any?): Unit
205
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?): Unit
206
    fun assertNotNull(message: String?, actual: Any?): Unit
207
}
208

209
val asserter: Asserter
210
```
211

212
[Asserter System](./asserter-system.md)
213

214
### Framework Integration
215

216
Automatic integration with JavaScript testing frameworks including Jasmine, Mocha, Jest, and TeamCity with seamless Promise support for async tests.
217

218
```kotlin { .api }
219
// Tests automatically work in any supported JavaScript testing framework
220
class MyTests {
221
    @Test
222
    fun syncTest() {
223
        assertEquals(4, 2 + 2)
224
    }
225
    
226
    @Test
227
    fun asyncTest(): Promise<*> {
228
        return Promise.resolve(42).then { result ->
229
            assertEquals(42, result)
230
        }
231
    }
232
}
233
```
234

235
[Framework Integration](./framework-integration.md)
236

237
## Types
238

239
```kotlin { .api }
240
/**
241
 * Test annotation marking a function as a test case
242
 */
243
@Target(AnnotationTarget.FUNCTION)
244
@Retention(AnnotationRetention.RUNTIME)
245
annotation class Test
246

247
/**
248
 * Test annotation marking a function to run before each test
249
 */
250
@Target(AnnotationTarget.FUNCTION)
251
@Retention(AnnotationRetention.RUNTIME) 
252
annotation class BeforeTest
253

254
/**
255
 * Test annotation marking a function to run after each test
256
 */
257
@Target(AnnotationTarget.FUNCTION)
258
@Retention(AnnotationRetention.RUNTIME)
259
annotation class AfterTest
260

261
/**
262
 * Annotation marking a test or test class as ignored
263
 * @param value optional reason for ignoring the test
264
 */
265
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
266
@Retention(AnnotationRetention.RUNTIME)
267
annotation class Ignore(val value: String = "")
268

269
/**
270
 * Interface providing the foundation for all assertion functions
271
 * Handles test failures and assertion logic
272
 */
273
interface Asserter {
274
    /**
275
     * Fails the current test with the given message
276
     */
277
    fun fail(message: String?): Nothing
278
    
279
    /**
280
     * Fails the current test with the given message and cause
281
     */
282
    fun fail(message: String?, cause: Throwable?): Nothing
283
    
284
    /**
285
     * Asserts that the value is true
286
     */
287
    fun assertTrue(lazyMessage: () -> String?, actual: Boolean): Unit
288
    fun assertTrue(message: String?, actual: Boolean): Unit
289
    
290
    /**
291
     * Asserts that expected and actual values are equal
292
     */
293
    fun assertEquals(message: String?, expected: Any?, actual: Any?): Unit
294
    
295
    /**
296
     * Asserts that illegal and actual values are not equal
297
     */
298
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?): Unit
299
    
300
    /**
301
     * Asserts that expected and actual are the same reference
302
     */
303
    fun assertSame(message: String?, expected: Any?, actual: Any?): Unit
304
    
305
    /**
306
     * Asserts that illegal and actual are not the same reference
307
     */
308
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?): Unit
309
    
310
    /**
311
     * Asserts that the value is null
312
     */
313
    fun assertNull(message: String?, actual: Any?): Unit
314
    
315
    /**
316
     * Asserts that the value is not null
317
     */
318
    fun assertNotNull(message: String?, actual: Any?): Unit
319
}
320

321
/**
322
 * Interface for contributing custom Asserter implementations
323
 */
324
interface AsserterContributor {
325
    /**
326
     * Returns an Asserter instance or null if not contributing
327
     */
328
    fun contribute(): Asserter?
329
}
330
```