0
# Framework Integration
1
2
Automatic integration with JavaScript testing frameworks, enabling seamless execution of Kotlin/WASM tests in various JavaScript environments without requiring manual configuration.
3
4
## Capabilities
5
6
### Automatic Framework Detection
7
8
The library automatically detects and integrates with popular JavaScript testing frameworks, requiring no manual configuration from developers.
9
10
**Supported Frameworks:**
11
- **Jasmine**: Full integration with describe/it test structure and async Promise support
12
- **Mocha**: Compatible with Mocha's testing patterns and reporting
13
- **Jest**: Seamless integration with Jest test runner and assertion reporting
14
- **TeamCity**: Automatic TeamCity service message format for CI/CD environments
15
16
**Detection Logic:**
17
1. **JavaScript Environment Detection**: Checks for presence of `describe` and `it` functions in the global scope
18
2. **Jasmine-style Frameworks**: If detected, uses Jasmine-compatible adapter with Promise support
19
3. **TeamCity Environment**: Falls back to TeamCity reporting format for CI environments
20
4. **Error Handling**: Converts Kotlin exceptions to JavaScript Error objects for proper framework reporting
21
22
### Usage in Different Environments
23
24
**Jasmine/Mocha/Jest Example:**
25
26
```html
27
<!DOCTYPE html>
28
<html>
29
<head>
30
<title>Kotlin WASM Tests</title>
31
<script src="https://cdnjs.cloudflare.com/ajax/libs/jasmine/3.8.0/jasmine.js"></script>
32
<script src="https://cdnjs.cloudflare.com/ajax/libs/jasmine/3.8.0/jasmine-html.js"></script>
33
<script src="https://cdnjs.cloudflare.com/ajax/libs/jasmine/3.8.0/boot.js"></script>
34
</head>
35
<body>
36
<script src="your-kotlin-wasm-tests.js"></script>
37
<!-- Tests run automatically - no additional setup needed -->
38
</body>
39
</html>
40
```
41
42
**Node.js with Mocha:**
43
44
```bash
45
# Install Mocha
46
npm install --save-dev mocha
47
48
# Run tests - framework detection happens automatically
49
npx mocha your-kotlin-wasm-tests.js
50
```
51
52
**TeamCity Integration:**
53
54
```yaml
55
# TeamCity build configuration
56
# No special setup needed - TeamCity format is detected automatically
57
script: |
58
node your-kotlin-wasm-tests.js
59
# Test results appear in TeamCity test tab automatically
60
```
61
62
### Async Test Support
63
64
Full support for asynchronous testing with JavaScript Promises, including proper error handling and test completion detection.
65
66
**Promise-Based Tests:**
67
68
```kotlin
69
import kotlin.test.*
70
import kotlin.js.Promise
71
72
class AsyncIntegrationTests {
73
@Test
74
fun fetchDataTest(): Promise<*> {
75
return fetchUserData("user123").then { userData ->
76
assertNotNull(userData)
77
assertEquals("user123", userData.id)
78
assertTrue(userData.isActive)
79
}
80
}
81
82
@Test
83
fun errorHandlingTest(): Promise<*> {
84
return fetchUserData("invalid-id")
85
.then {
86
fail("Should have thrown an error for invalid ID")
87
}
88
.catch { error ->
89
// Error is properly converted and reported by the framework
90
assertTrue(error.toString().contains("User not found"))
91
}
92
}
93
94
@Test
95
fun chainedAsyncTest(): Promise<*> {
96
return createUser("newuser@example.com")
97
.then { user ->
98
assertEquals("newuser@example.com", user.email)
99
return@then updateUserProfile(user.id, "John Doe")
100
}
101
.then { updatedUser ->
102
assertEquals("John Doe", updatedUser.name)
103
}
104
}
105
}
106
```
107
108
### Error Reporting Integration
109
110
Seamless error reporting that preserves Kotlin stack traces and exception details in JavaScript testing frameworks.
111
112
**Error Conversion Features:**
113
- **Stack Trace Preservation**: Kotlin stack traces are converted to JavaScript-compatible format
114
- **Exception Message Preservation**: Original Kotlin exception messages are maintained
115
- **Assertion Failure Details**: Clear reporting of expected vs. actual values
116
- **Framework-Specific Formatting**: Error format adapts to the detected testing framework
117
118
**Example Error Output in Jasmine:**
119
120
```
121
AssertionError: Expected <42> but was <43>
122
at assertEquals (kotlin-test.js:123:45)
123
at MyTests.calculateTest (my-tests.kt:15:8)
124
at Object.it (jasmine-adapter.js:67:12)
125
```
126
127
### Configuration Requirements
128
129
**Zero Configuration**: The library requires no manual setup or configuration files. Framework detection and integration happen automatically when tests are executed.
130
131
**Environment Requirements:**
132
- WebAssembly support in the JavaScript runtime
133
- One of the supported testing frameworks (Jasmine, Mocha, Jest, or TeamCity environment)
134
- Standard JavaScript Promise support for async tests
135
136
### Best Practices
137
138
**Framework Compatibility:**
139
- Use standard `@Test`, `@BeforeTest`, `@AfterTest` annotations - they work across all supported frameworks
140
- Return `Promise<*>` from test functions for async operations
141
- Avoid framework-specific APIs in test code to maintain portability
142
143
**Error Handling:**
144
- Let exceptions bubble up naturally - the integration layer handles conversion
145
- Use kotlin.test assertion functions for consistent error reporting
146
- Provide meaningful error messages in assertions for better debugging
147
148
**Performance:**
149
- Framework detection happens only once per test run
150
- Minimal overhead added to test execution
151
- Efficient Promise handling for async test coordination
152
153
This automatic integration ensures that Kotlin/WASM tests run seamlessly in any JavaScript testing environment without requiring developers to learn framework-specific APIs or configuration details.