0
# Kotlin Test Annotations Common
1

2
Kotlin test annotations for use in common code. Provides common test annotations like @Test, @Ignore, @BeforeTest, and @AfterTest that can be used across different platforms in Kotlin multiplatform projects.
3

4
## Package Information
5

6
- **Package Name**: kotlin-test-annotations-common
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  - Gradle: `implementation("org.jetbrains.kotlin:kotlin-test-annotations-common:2.2.0")`
11
  - Maven: `<dependency><groupId>org.jetbrains.kotlin</groupId><artifactId>kotlin-test-annotations-common</artifactId><version>2.2.0</version></dependency>`
12

13
## Core Imports
14

15
```kotlin
16
import kotlin.test.*
17
```
18

19
Or import specific annotations:
20

21
```kotlin
22
import kotlin.test.Test
23
import kotlin.test.Ignore
24
import kotlin.test.BeforeTest
25
import kotlin.test.AfterTest
26
```
27

28
## Basic Usage
29

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

33
class MyTest {
34

35
    @BeforeTest
36
    fun setup() {
37
        // Setup code that runs before each test
38
    }
39

40
    @Test
41
    fun testSomething() {
42
        // Test implementation
43
    }
44

45
    @Test
46
    fun testAnotherThing() {
47
        // Another test implementation  
48
    }
49

50
    @Ignore
51
    @Test
52
    fun testSkipped() {
53
        // This test will be ignored/skipped
54
    }
55

56
    @AfterTest
57
    fun teardown() {
58
        // Cleanup code that runs after each test
59
    }
60
}
61
```
62

63
## Capabilities
64

65
### Test Marking
66

67
Mark functions as test methods that should be executed by the test framework.
68

69
```kotlin { .api }
70
@Target(AnnotationTarget.FUNCTION)
71
public expect annotation class Test()
72
```
73

74
The `@Test` annotation marks a function as a test that should be executed by the testing framework. This annotation is mapped to platform-specific test annotations:
75
- JVM: Maps to JUnit's `@Test`, JUnit 5's `@Test`, or TestNG's `@Test`
76
- JavaScript: Maps to Jasmine, Mocha, or Jest test functions
77
- Native: Maps to platform-specific testing framework test markers
78

79
### Test Ignoring
80

81
Skip test execution for specific tests or entire test suites.
82

83
```kotlin { .api }
84
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
85
public expect annotation class Ignore()
86
```
87

88
The `@Ignore` annotation can be applied to:
89
- Individual test functions to skip that specific test
90
- Test classes to skip all tests in the class
91

92
When applied, the test framework will skip execution but typically report the test as ignored/skipped.
93

94
### Test Setup
95

96
Execute setup code before each test method.
97

98
```kotlin { .api }
99
@Target(AnnotationTarget.FUNCTION)
100
public expect annotation class BeforeTest()
101
```
102

103
Functions annotated with `@BeforeTest` are executed before each test method in the same class. This is useful for:
104
- Initializing test data
105
- Setting up mock objects
106
- Preparing test environment
107

108
### Test Cleanup
109

110
Execute cleanup code after each test method.
111

112
```kotlin { .api }
113
@Target(AnnotationTarget.FUNCTION)
114
public expect annotation class AfterTest()
115
```
116

117
Functions annotated with `@AfterTest` are executed after each test method in the same class. This is useful for:
118
- Cleaning up resources
119
- Resetting state
120
- Tearing down test environment
121

122
## Platform Mapping
123

124
These annotations are `expect` declarations that map to platform-specific testing frameworks:
125

126
### JVM Platforms
127
- **JUnit 4**: Maps to `@org.junit.Test`, `@org.junit.Ignore`, `@org.junit.Before`, `@org.junit.After`
128
- **JUnit 5**: Maps to `@org.junit.jupiter.api.Test`, `@org.junit.jupiter.api.Disabled`, `@org.junit.jupiter.api.BeforeEach`, `@org.junit.jupiter.api.AfterEach`
129
- **TestNG**: Maps to `@org.testng.annotations.Test`, `@org.testng.annotations.Test(enabled=false)`, `@org.testng.annotations.BeforeMethod`, `@org.testng.annotations.AfterMethod`
130

131
### JavaScript Platforms
132
- **Jasmine/Mocha/Jest**: Maps to `it()`, `xit()` or `it.skip()`, `beforeEach()`, `afterEach()`
133

134
### Native Platforms
135
Maps to the testing framework available on the specific native platform.
136

137
## Usage Notes
138

139
1. **Multiplatform Compatibility**: These annotations work across all Kotlin platforms (JVM, JS, Native)
140
2. **Framework Agnostic**: The same test code works with different testing frameworks
141
3. **Common Module**: These annotations should be used in your `commonMain` or `commonTest` source sets
142
4. **Platform-Specific Implementation**: Each platform provides its own implementation that maps to the appropriate testing framework
143
5. **Execution Order**: `@BeforeTest` methods run before each `@Test` method, and `@AfterTest` methods run after each `@Test` method
144
6. **Class vs Function**: `@Ignore` can be applied to both classes and functions, while other annotations only apply to functions