0
# Kotlin Test TestNG
1

2
Kotlin Test TestNG provides seamless integration between Kotlin's multiplatform test framework (kotlin.test) and TestNG. It enables Kotlin tests to use familiar kotlin.test APIs while running on TestNG, bridging the gap between multiplatform test code and TestNG's advanced features like parameterized tests, test groups, and parallel execution.
3

4
## Package Information
5

6
- **Package Name**: kotlin-test-testng
7
- **Package Type**: Maven
8
- **Language**: Kotlin
9
- **Group ID**: org.jetbrains.kotlin
10
- **Installation**: `implementation("org.jetbrains.kotlin:kotlin-test-testng:1.9.25")`
11

12
## Core Imports
13

14
```kotlin
15
import kotlin.test.testng.TestNGAsserter
16
import kotlin.test.testng.TestNGContributor
17
```
18

19
For annotation imports (automatically available when using kotlin.test):
20

21
```kotlin
22
import kotlin.test.*
23
```
24

25
## Basic Usage
26

27
```kotlin
28
import kotlin.test.*
29

30
class MyTestNGTest {
31
    @Test
32
    fun basicAssertionTest() {
33
        assertEquals("Expected value", "actual value")
34
        assertTrue(true)
35
        assertNotNull("some value")
36
    }
37

38
    @BeforeTest
39
    fun setUp() {
40
        // Setup code before each test
41
    }
42

43
    @AfterTest
44
    fun tearDown() {
45
        // Cleanup code after each test
46
    }
47

48
    @Ignore
49
    @Test
50
    fun ignoredTest() {
51
        // This test will be ignored
52
    }
53
}
54
```
55

56
## Architecture
57

58
Kotlin Test TestNG operates through a service provider pattern:
59

60
- **TestNGContributor**: Service provider that automatically detects TestNG availability and contributes the TestNGAsserter
61
- **TestNGAsserter**: Implements kotlin.test assertion methods by delegating to TestNG's Assert class
62
- **Annotation Mappings**: Type aliases that map kotlin.test annotations to their TestNG equivalents
63
- **Automatic Discovery**: The kotlin.test framework automatically discovers and uses TestNG support when available
64

65
## Capabilities
66

67
### Service Provider Integration
68

69
Automatic TestNG detection and asserter contribution for the kotlin.test framework.
70

71
```kotlin { .api }
72
/**
73
 * Provides TestNGAsserter if org.testng.Assert is found in the classpath.
74
 */
75
class TestNGContributor : AsserterContributor {
76
    /**
77
     * Provides TestNGAsserter instance if TestNG is available, null otherwise.
78
     * @return TestNGAsserter instance or null if TestNG is not in classpath
79
     */
80
    fun contribute(): Asserter?
81
}
82
```
83

84
### TestNG Assertion Implementation
85

86
Complete kotlin.test assertion implementation using TestNG's Assert class.
87

88
```kotlin { .api }
89
/**
90
 * Implements kotlin.test assertions by delegating them to org.testng.Assert class.
91
 */
92
object TestNGAsserter : Asserter {
93
    /**
94
     * Asserts that the specified values are equal.
95
     * @param message the message to report if the assertion fails
96
     * @param expected the expected value
97
     * @param actual the actual value
98
     */
99
    fun assertEquals(message: String?, expected: Any?, actual: Any?)
100

101
    /**
102
     * Asserts that the specified values are not equal.
103
     * @param message the message to report if the assertion fails
104
     * @param illegal the value that should not equal actual
105
     * @param actual the actual value
106
     */
107
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?)
108

109
    /**
110
     * Asserts that the specified values are the same instance.
111
     * @param message the message to report if the assertion fails
112
     * @param expected the expected instance
113
     * @param actual the actual instance
114
     */
115
    fun assertSame(message: String?, expected: Any?, actual: Any?)
116

117
    /**
118
     * Asserts that the specified values are not the same instance.
119
     * @param message the message to report if the assertion fails
120
     * @param illegal the instance that should not be the same as actual
121
     * @param actual the actual instance
122
     */
123
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?)
124

125
    /**
126
     * Asserts that the specified value is not null.
127
     * @param message the message to report if the assertion fails
128
     * @param actual the value to check for null
129
     */
130
    fun assertNotNull(message: String?, actual: Any?)
131

132
    /**
133
     * Asserts that the specified value is null.
134
     * @param message the message to report if the assertion fails
135
     * @param actual the value to check for null
136
     */
137
    fun assertNull(message: String?, actual: Any?)
138

139
    /**
140
     * Fails the current test with the specified message.
141
     * @param message the message to report
142
     */
143
    fun fail(message: String?): Nothing
144

145
    /**
146
     * Fails the current test with the specified message and cause exception.
147
     * @param message the message to report
148
     * @param cause the exception to set as the root cause of the reported failure
149
     * @since Kotlin 1.4
150
     */
151
    fun fail(message: String?, cause: Throwable?): Nothing
152
}
153
```
154

155
### Test Annotations
156

157
Kotlin.test annotation mappings to TestNG equivalents, enabling cross-platform test code.
158

159
```kotlin { .api }
160
/**
161
 * Maps kotlin.test @Test to TestNG @Test annotation
162
 */
163
typealias Test = org.testng.annotations.Test
164

165
/**
166
 * Maps kotlin.test @Ignore to TestNG @Ignore annotation
167
 */
168
typealias Ignore = org.testng.annotations.Ignore
169

170
/**
171
 * Maps kotlin.test @BeforeTest to TestNG @BeforeMethod annotation
172
 */
173
typealias BeforeTest = org.testng.annotations.BeforeMethod
174

175
/**
176
 * Maps kotlin.test @AfterTest to TestNG @AfterMethod annotation
177
 */
178
typealias AfterTest = org.testng.annotations.AfterMethod
179
```
180

181
## Types
182

183
```kotlin { .api }
184
/**
185
 * Interface for contributing assertion implementations to kotlin.test framework
186
 */
187
interface AsserterContributor {
188
    /**
189
     * Provides Asserter instance or null depending on the current context
190
     * @return asserter instance or null if not applicable
191
     */
192
    fun contribute(): Asserter?
193
}
194

195
/**
196
 * Interface defining assertion methods for kotlin.test framework
197
 */
198
interface Asserter {
199
    fun fail(message: String?): Nothing
200
    fun fail(message: String?, cause: Throwable?): Nothing // @SinceKotlin("1.4")
201
    fun assertEquals(message: String?, expected: Any?, actual: Any?)
202
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?)
203
    fun assertSame(message: String?, expected: Any?, actual: Any?)
204
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?)
205
    fun assertNull(message: String?, actual: Any?)
206
    fun assertNotNull(message: String?, actual: Any?)
207
}
208
```
209

210
## Usage Examples
211

212
### Basic Test Class
213

214
```kotlin
215
import kotlin.test.*
216

217
class UserServiceTest {
218
    private lateinit var userService: UserService
219
    
220
    @BeforeTest
221
    fun setUp() {
222
        userService = UserService()
223
    }
224
    
225
    @Test
226
    fun `should create user with valid data`() {
227
        val user = userService.createUser("Alice", "alice@example.com")
228
        
229
        assertNotNull(user)
230
        assertEquals("Alice", user.name)
231
        assertEquals("alice@example.com", user.email)
232
    }
233
    
234
    @Test
235
    fun `should throw exception for invalid email`() {
236
        assertFailsWith<IllegalArgumentException> {
237
            userService.createUser("Bob", "invalid-email")
238
        }
239
    }
240
    
241
    @AfterTest
242
    fun tearDown() {
243
        userService.cleanup()
244
    }
245
}
246
```
247

248
### Integration with TestNG Features
249

250
```kotlin
251
import kotlin.test.*
252
import org.testng.annotations.DataProvider
253

254
class CalculatorTest {
255
    
256
    @DataProvider(name = "additionData")
257
    fun additionDataProvider(): Array<Array<Any>> {
258
        return arrayOf(
259
            arrayOf(1, 2, 3),
260
            arrayOf(-1, 1, 0),
261
            arrayOf(0, 0, 0)
262
        )
263
    }
264
    
265
    @Test(dataProvider = "additionData")
266
    fun `should add numbers correctly`(a: Int, b: Int, expected: Int) {
267
        val result = Calculator.add(a, b)
268
        assertEquals(expected, result)
269
    }
270
    
271
    @Test(groups = ["unit"])
272
    fun `should multiply correctly`() {
273
        assertEquals(6, Calculator.multiply(2, 3))
274
    }
275
}
276
```