0
# Test Annotations
1

2
Test annotations for marking functions as tests and controlling test lifecycle. These annotations provide the foundation for organizing and running Kotlin tests in WebAssembly JavaScript environments.
3

4
## Capabilities
5

6
### Test Annotation
7

8
Marks a function as a test case that should be executed by the test framework.
9

10
```kotlin { .api }
11
/**
12
 * Marks a function as a test.
13
 * 
14
 * Only functions of a class are supported as test functions.
15
 * Test functions must have no parameters and return type Unit.
16
 */
17
@Target(AnnotationTarget.FUNCTION)
18
@Retention(AnnotationRetention.RUNTIME)
19
annotation class Test
20
```
21

22
**Usage Example:**
23

24
```kotlin
25
import kotlin.test.*
26

27
class MyTests {
28
    @Test
29
    fun simpleTest() {
30
        assertEquals(4, 2 + 2)
31
    }
32
    
33
    @Test
34
    fun stringTest() {
35
        val message = "Hello, World!"
36
        assertTrue(message.isNotEmpty())
37
        assertContains(message, "World")
38
    }
39
    
40
    @Test
41
    fun asyncTest(): Promise<*> {
42
        return Promise.resolve("async result").then { result ->
43
            assertEquals("async result", result)
44
        }
45
    }
46
}
47
```
48

49
### Before Test Annotation
50

51
Marks a function to be invoked before each test in a test class.
52

53
```kotlin { .api }
54
/**
55
 * Marks a function to be invoked before each test case.
56
 * 
57
 * Only functions of a class are supported as before test functions.
58
 * Before test functions must have no parameters and return type Unit.
59
 */
60
@Target(AnnotationTarget.FUNCTION)
61
@Retention(AnnotationRetention.RUNTIME)
62
annotation class BeforeTest
63
```
64

65
**Usage Example:**
66

67
```kotlin
68
import kotlin.test.*
69

70
class DatabaseTests {
71
    private lateinit var database: TestDatabase
72
    
73
    @BeforeTest
74
    fun setup() {
75
        database = TestDatabase()
76
        database.connect()
77
        database.initializeTestData()
78
    }
79
    
80
    @Test
81
    fun testUserCreation() {
82
        val user = database.createUser("test@example.com")
83
        assertNotNull(user)
84
        assertEquals("test@example.com", user.email)
85
    }
86
    
87
    @Test
88
    fun testUserDeletion() {
89
        val user = database.createUser("delete@example.com")
90
        database.deleteUser(user.id)
91
        assertNull(database.findUser(user.id))
92
    }
93
}
94
```
95

96
### After Test Annotation
97

98
Marks a function to be invoked after each test in a test class.
99

100
```kotlin { .api }
101
/**
102
 * Marks a function to be invoked after each test case.
103
 * 
104
 * Only functions of a class are supported as after test functions.
105
 * After test functions must have no parameters and return type Unit.
106
 */
107
@Target(AnnotationTarget.FUNCTION)
108
@Retention(AnnotationRetention.RUNTIME)
109
annotation class AfterTest
110
```
111

112
**Usage Example:**
113

114
```kotlin
115
import kotlin.test.*
116

117
class FileSystemTests {
118
    private val tempFiles = mutableListOf<String>()
119
    
120
    @Test
121
    fun testFileCreation() {
122
        val fileName = "test-${System.currentTimeMillis()}.txt"
123
        createTestFile(fileName)
124
        tempFiles.add(fileName)
125
        
126
        assertTrue(fileExists(fileName))
127
    }
128
    
129
    @AfterTest
130
    fun cleanup() {
131
        // Clean up any files created during the test
132
        tempFiles.forEach { fileName ->
133
            deleteFile(fileName)
134
        }
135
        tempFiles.clear()
136
    }
137
}
138
```
139

140
### Ignore Annotation
141

142
Marks a test function or test class as ignored, preventing it from being executed.
143

144
```kotlin { .api }
145
/**
146
 * Marks a test or test class as ignored.
147
 * Ignored tests are not executed by the test framework.
148
 * 
149
 * @param value optional reason for ignoring the test
150
 */
151
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
152
@Retention(AnnotationRetention.RUNTIME)
153
annotation class Ignore(val value: String = "")
154
```
155

156
**Usage Examples:**
157

158
```kotlin
159
import kotlin.test.*
160

161
class FeatureTests {
162
    
163
    @Test
164
    fun workingTest() {
165
        assertEquals(2 + 2, 4)
166
    }
167
    
168
    @Ignore("Feature not implemented yet")
169
    @Test
170
    fun futureFeatureTest() {
171
        // This test won't run until @Ignore is removed
172
        fail("This feature is not ready")
173
    }
174
    
175
    @Ignore("Flaky test - investigating")
176
    @Test
177
    fun flakyTest() {
178
        // Temporarily ignored due to intermittent failures
179
        assertTrue(Math.random() > 0.5) // This would be flaky
180
    }
181
}
182

183
@Ignore("Entire class under development")
184
class ExperimentalTests {
185
    
186
    @Test
187
    fun experimentalFeature1() {
188
        // None of these tests will run because the class is ignored
189
        fail("Not ready")
190
    }
191
    
192
    @Test
193
    fun experimentalFeature2() {
194
        fail("Not ready")
195
    }
196
}
197
```
198

199
### Annotation Usage Guidelines
200

201
**Test Lifecycle Order:**
202
1. `@BeforeTest` functions are called before each individual test
203
2. `@Test` function is executed
204
3. `@AfterTest` functions are called after each individual test
205

206
**Class vs Function Ignoring:**
207
- When a class is marked with `@Ignore`, all tests in that class are ignored
208
- When individual functions are marked with `@Ignore`, only those specific tests are ignored
209
- Ignored tests are typically reported as "skipped" by test frameworks
210

211
**Best Practices:**
212
- Use `@BeforeTest` for test setup that needs to be fresh for each test
213
- Use `@AfterTest` for cleanup to prevent test isolation issues
214
- Always provide a reason when using `@Ignore` to help future maintainers
215
- Avoid long-lived ignored tests - either fix them or remove them
216
- Test functions should be focused and test a single concern