0
# iOS UIKit Testing
1

2
Comprehensive testing infrastructure for iOS UIKit applications with Compose integration, providing test setup, content management, and UI synchronization capabilities.
3

4
## Capabilities
5

6
### Test Environment Setup
7

8
Creates and manages the iOS UIKit testing environment with proper app delegate setup and window management.
9

10
```kotlin { .api }
11
/**
12
 * Runs a UIKit instrumented test with proper setup and teardown
13
 * @param testBlock - Test code block to execute within UIKitInstrumentedTest context
14
 */
15
internal fun runUIKitInstrumentedTest(testBlock: UIKitInstrumentedTest.() -> Unit)
16
```
17

18
**Usage Example:**
19

20
```kotlin
21
runUIKitInstrumentedTest {
22
    setContent {
23
        Column {
24
            Text("Welcome to iOS!")
25
            Button(onClick = { /* action */ }) {
26
                Text("Click me")
27
            }
28
        }
29
    }
30
    
31
    waitForIdle()
32
    tap(DpOffset(100.dp, 200.dp))
33
}
34
```
35

36
### Content Management
37

38
Functions for setting and managing Compose content within the iOS UIKit test environment.
39

40
```kotlin { .api }
41
/**
42
 * Sets Compose content in the test environment
43
 * @param configure - Configuration block for ComposeUIViewController setup
44
 * @param content - Composable content to display
45
 */
46
fun UIKitInstrumentedTest.setContent(
47
    configure: ComposeUIViewControllerConfiguration.() -> Unit = {},
48
    content: @Composable () -> Unit
49
)
50

51
/**
52
 * Sets content with accessibility synchronization enabled
53
 * @param content - Composable content to display with accessibility support
54
 */
55
fun UIKitInstrumentedTest.setContentWithAccessibilityEnabled(content: @Composable () -> Unit)
56
```
57

58
### UI Synchronization
59

60
Synchronization utilities for waiting on UI state changes and ensuring test stability.
61

62
```kotlin { .api }
63
/**
64
 * Waits for the UI to become idle (no pending animations or state changes)
65
 * @param timeoutMillis - Maximum time to wait in milliseconds (default: 500)
66
 * @throws AssertionError if UI doesn't become idle within timeout
67
 */
68
fun UIKitInstrumentedTest.waitForIdle(timeoutMillis: Long = 500)
69

70
/**
71
 * Waits until a specific condition is met
72
 * @param conditionDescription - Description of what condition is being waited for
73
 * @param timeoutMillis - Maximum time to wait in milliseconds (default: 5,000)  
74
 * @param condition - Function that returns true when condition is satisfied
75
 * @throws AssertionError if condition is not met within timeout
76
 */
77
fun UIKitInstrumentedTest.waitUntil(
78
    conditionDescription: String? = null,
79
    timeoutMillis: Long = 5_000,
80
    condition: () -> Boolean
81
)
82

83
/**
84
 * Introduces a delay using NSRunLoop for precise timing control
85
 * @param timeoutMillis - Duration to delay in milliseconds
86
 */
87
fun UIKitInstrumentedTest.delay(timeoutMillis: Long)
88

89
/**
90
 * Tears down the test environment and cleans up resources
91
 */
92
fun UIKitInstrumentedTest.tearDown()
93
```
94

95
**Usage Examples:**
96

97
```kotlin
98
// Wait for animations to complete
99
waitForIdle()
100

101
// Wait for specific condition
102
waitUntil { 
103
    findNodeWithLabel("Loading...") == null 
104
}
105

106
// Introduce controlled delay
107
delay(500)
108
```
109

110
### Test Environment Properties
111

112
Properties providing information about the test environment and device characteristics.
113

114
```kotlin { .api }
115
/**
116
 * Screen density for coordinate conversion between dp and pixels
117
 */
118
val UIKitInstrumentedTest.density: Density
119

120
/**
121
 * Screen size in density-independent pixels
122
 */
123
val UIKitInstrumentedTest.screenSize: DpSize
124
```
125

126
**Usage Example:**
127

128
```kotlin
129
runUIKitInstrumentedTest {
130
    val centerX = screenSize.width / 2
131
    val centerY = screenSize.height / 2
132
    val centerPosition = DpOffset(centerX, centerY)
133
    
134
    tap(centerPosition)
135
}
136
```
137

138
### Mock App Delegate
139

140
Mock app delegate implementation for test environment setup and window management.
141

142
```kotlin { .api }
143
/**
144
 * Mock app delegate for iOS testing environment
145
 * Handles window creation and app lifecycle events
146
 */
147
class MockAppDelegate {
148
    val window: UIWindow?
149
    
150
    fun application(
151
        application: UIApplication,
152
        didFinishLaunchingWithOptions: Map<UIApplicationLaunchOptionsKey, Any>?
153
    ): Boolean
154
}
155
```
156

157
## Error Handling
158

159
The testing framework includes comprehensive error handling:
160

161
- **TimeoutException**: Thrown when `waitForIdle()` or `waitUntil()` operations exceed specified timeout
162
- **IllegalStateException**: Thrown when attempting to interact with UI before content is set
163
- **Test Assertion Failures**: Standard test framework assertion failures for accessibility tree validation
164

165
**Example Error Handling:**
166

167
```kotlin
168
runUIKitInstrumentedTest {
169
    setContent { Text("Test") }
170
    
171
    try {
172
        waitUntil(timeoutMillis = 1000) {
173
            findNodeWithLabel("NonExistent") != null
174
        }
175
    } catch (e: TimeoutException) {
176
        // Handle timeout gracefully
177
        println("Expected element not found within timeout")
178
    }
179
}
180
```
181

182
## Integration Notes
183

184
- **UIKit Integration**: Seamlessly integrates with UIKit's touch event system and accessibility framework
185
- **Compose Runtime**: Fully compatible with Compose runtime and state management
186
- **iOS Simulator**: Optimized for ARM64 iOS simulator environment
187
- **Thread Safety**: All operations are designed to work with iOS main thread requirements