1# Testing Concurrent Code
2 
3Use this when:
4 
5- You are writing async tests.
6- A test is flaky because of task scheduling or actor isolation.
7- You need to replace XCTest waiting APIs or verify deallocation.
8 
9Skip this file if:
10 
11- You mainly need production ownership guidance. Use `actors.md`, `tasks.md`, or `memory-management.md`.
12 
13Jump to:
14 
15- Swift Testing (Recommended)
16- Awaiting Async Callbacks
17- Setup and Teardown
18- Handling Flaky Tests
19- Swift Concurrency Extras
20- XCTest Patterns (Legacy)
21- Memory Management Tests
22- Testing Checklist
23 
24## Recommendation: Use Swift Testing
25 
26**Swift Testing is strongly recommended** for new projects and tests. It provides:
27- Modern Swift syntax with macros
28- Better concurrency support
29- Cleaner test structure
30- More flexible test organization
31 
32XCTest patterns are included for legacy codebases.
33 
34## Swift Testing Basics
35 
36### Simple async test
37 
38```swift
39@Test
40@MainActor
41func emptyQuery() async {
42    let searcher = ArticleSearcher()
43    await searcher.search("")
44    #expect(searcher.results == ArticleSearcher.allArticles)
45}
46```
47 
48**Key differences from XCTest**:
49- `@Test` macro instead of `XCTestCase`
50- `#expect` instead of `XCTAssert`
51- Structs preferred over classes
52- No `test` prefix required
53 
54### Testing with actors
55 
56```swift
57@Test
58@MainActor
59func searchReturnsResults() async {
60    let searcher = ArticleSearcher()
61    await searcher.search("swift")
62    #expect(!searcher.results.isEmpty)
63}
64```
65 
66Mark test with actor if system under test requires it.
67 
68> **Course Deep Dive**: This topic is covered in detail in [Lesson 11.2: Testing concurrent code using Swift Testing](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
69 
70## Awaiting Async Callbacks
71 
72### Using continuations
73 
74When testing unstructured tasks:
75 
76```swift
77@Test
78@MainActor
79func searchTaskCompletes() async {
80    let searcher = ArticleSearcher()
81    
82    await withCheckedContinuation { continuation in
83        _ = withObservationTracking {
84            searcher.results
85        } onChange: {
86            continuation.resume()
87        }
88        
89        searcher.startSearchTask("swift")
90    }
91    
92    #expect(searcher.results.count > 0)
93}
94```
95 
96**Use when**: Testing code that spawns unstructured tasks.
97 
98### Using confirmations
99 
100For structured async code:
101 
102```swift
103@Test
104@MainActor
105func searchTriggersObservation() async {
106    let searcher = ArticleSearcher()
107    
108    await confirmation { confirm in
109        _ = withObservationTracking {
110            searcher.results
111        } onChange: {
112            confirm()
113        }
114        
115        // Must await here for confirmation to work
116        await searcher.search("swift")
117    }
118    
119    #expect(!searcher.results.isEmpty)
120}
121```
122 
123**Critical**: Must `await` async work for confirmation to validate.
124 
125## Setup and Teardown
126 
127### Using init/deinit
128 
129```swift
130@MainActor
131final class DatabaseTests {
132    let database: Database
133    
134    init() async throws {
135        database = Database()
136        await database.prepare()
137    }
138    
139    deinit {
140        // Synchronous cleanup only
141    }
142    
143    @Test
144    func insertsData() async throws {
145        try await database.insert(item)
146        #expect(await database.count() == 1)
147    }
148}
149```
150 
151**Limitation**: `deinit` cannot call async methods.
152 
153### Test Scoping Traits
154 
155For async teardown:
156 
157```swift
158@MainActor
159struct DatabaseTrait: SuiteTrait, TestTrait, TestScoping {
160    func provideScope(
161        for test: Test,
162        testCase: Test.Case?,
163        performing function: () async throws -> Void
164    ) async throws {
165        let database = Database()
166        
167        try await Environment.$database.withValue(database) {
168            await database.prepare()
169            try await function()
170            await database.cleanup() // Async teardown
171        }
172    }
173}
174 
175// Environment for task-local storage
176@MainActor
177struct Environment {
178    @TaskLocal static var database = Database()
179}
180 
181// Apply to suite
182@Suite(DatabaseTrait())
183@MainActor
184final class DatabaseTests {
185    @Test
186    func insertsData() async throws {
187        try await Environment.database.insert(item)
188    }
189}
190 
191// Or apply to individual test
192@Test(DatabaseTrait())
193func specificTest() async throws {
194    // Test code
195}
196```
197 
198**Use when**: Need async cleanup after each test.
199 
200## Handling Flaky Tests
201 
202### Problem: Race conditions
203 
204```swift
205@Test
206@MainActor
207func isLoadingState() async throws {
208    let fetcher = ImageFetcher()
209    
210    let task = Task { try await fetcher.fetch(url) }
211    
212    // ❌ Flaky - may pass or fail
213    #expect(fetcher.isLoading == true)
214    
215    try await task.value
216    #expect(fetcher.isLoading == false)
217}
218```
219 
220**Issue**: Task may complete before we check `isLoading`.
221 
222### Solution: Swift Concurrency Extras
223 
224```swift
225import ConcurrencyExtras
226 
227@Test
228@MainActor
229func isLoadingState() async throws {
230    try await withMainSerialExecutor {
231        let fetcher = ImageFetcher { url in
232            await Task.yield() // Allow test to check state
233            return Data()
234        }
235        
236        let task = Task { try await fetcher.fetch(url) }
237        
238        await Task.yield() // Switch to task
239        
240        #expect(fetcher.isLoading == true) // ✅ Reliable
241        
242        try await task.value
243        #expect(fetcher.isLoading == false)
244    }
245}
246```
247 
248**Add package**: `https://github.com/pointfreeco/swift-concurrency-extras.git`
249 
250> **Course Deep Dive**: This topic is covered in detail in [Lesson 11.3: Using Swift Concurrency Extras by Point-Free](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
251 
252### Serial execution required
253 
254```swift
255@Suite(.serialized)
256@MainActor
257final class ImageFetcherTests {
258    // Tests run serially when using withMainSerialExecutor
259}
260```
261 
262**Critical**: Main serial executor doesn't work with parallel test execution.
263 
264## XCTest Patterns (Legacy)
265 
266### Basic async test
267 
268```swift
269final class ArticleSearcherTests: XCTestCase {
270    @MainActor
271    func testEmptyQuery() async {
272        let searcher = ArticleSearcher()
273        await searcher.search("")
274        XCTAssertEqual(searcher.results, ArticleSearcher.allArticles)
275    }
276}
277```
278 
279### Using expectations
280 
281```swift
282@MainActor
283func testSearchTask() async {
284    let searcher = ArticleSearcher()
285    let expectation = expectation(description: "Search complete")
286    
287    _ = withObservationTracking {
288        searcher.results
289    } onChange: {
290        expectation.fulfill()
291    }
292    
293    searcher.startSearchTask("swift")
294    
295    // Use fulfillment, not wait
296    await fulfillment(of: [expectation], timeout: 10)
297    
298    XCTAssertEqual(searcher.results.count, 1)
299}
300```
301 
302**Critical**: Use `await fulfillment(of:)`, not `wait(for:)` to avoid deadlocks.
303 
304### Setup and teardown
305 
306```swift
307final class DatabaseTests: XCTestCase {
308    override func setUp() async throws {
309        // Async setup
310    }
311    
312    override func tearDown() async throws {
313        // Async teardown
314    }
315}
316```
317 
318Mark as `async throws` to call async methods.
319 
320> **Course Deep Dive**: This topic is covered in detail in [Lesson 11.1: Testing concurrent code using XCTest](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
321 
322### Main serial executor for all tests
323 
324```swift
325final class MyTests: XCTestCase {
326    override func invokeTest() {
327        withMainSerialExecutor {
328            super.invokeTest()
329        }
330    }
331}
332```
333 
334## Common Patterns
335 
336### Testing @MainActor code
337 
338```swift
339@Test
340@MainActor
341func viewModelUpdates() async {
342    let viewModel = ViewModel()
343    await viewModel.loadData()
344    #expect(viewModel.items.count > 0)
345}
346```
347 
348### Testing actors
349 
350```swift
351@Test
352func actorIsolation() async {
353    let store = DataStore()
354    await store.insert(item)
355    let count = await store.count()
356    #expect(count == 1)
357}
358```
359 
360### Testing cancellation
361 
362```swift
363@Test
364func cancellationStopsWork() async throws {
365    let processor = DataProcessor()
366    
367    let task = Task {
368        try await processor.processLargeDataset()
369    }
370    
371    task.cancel()
372    
373    do {
374        try await task.value
375        Issue.record("Should have thrown cancellation error")
376    } catch is CancellationError {
377        // Expected
378    }
379}
380```
381 
382### Testing with delays
383 
384```swift
385@Test
386func debouncedSearch() async throws {
387    try await withMainSerialExecutor {
388        let searcher = DebouncedSearcher()
389        
390        searcher.search("a")
391        await Task.yield()
392        
393        searcher.search("ab")
394        await Task.yield()
395        
396        searcher.search("abc")
397        
398        // Wait for debounce
399        try await Task.sleep(for: .milliseconds(600))
400        
401        #expect(searcher.searchCount == 1) // Only last search executed
402    }
403}
404```
405 
406### Testing task groups
407 
408```swift
409@Test
410func taskGroupProcessesAll() async throws {
411    let processor = BatchProcessor()
412    
413    let results = await withTaskGroup(of: Int.self) { group in
414        for i in 1...5 {
415            group.addTask { await processor.process(i) }
416        }
417        
418        var collected: [Int] = []
419        for await result in group {
420            collected.append(result)
421        }
422        return collected
423    }
424    
425    #expect(results.count == 5)
426}
427```
428 
429## Testing Memory Management
430 
431### Verify deallocation
432 
433```swift
434@Test
435func viewModelDeallocates() async {
436    var viewModel: ViewModel? = ViewModel()
437    weak var weakViewModel = viewModel
438    
439    viewModel?.startWork()
440    viewModel = nil
441    
442    try? await Task.sleep(for: .milliseconds(100))
443    
444    #expect(weakViewModel == nil)
445}
446```
447 
448### Detect retain cycles
449 
450```swift
451@Test
452func noRetainCycle() async {
453    var manager: Manager? = Manager()
454    weak var weakManager = manager
455    
456    manager?.startLongRunningTask()
457    manager = nil
458    
459    #expect(weakManager == nil)
460}
461```
462 
463## Best Practices
464 
4651. **Use Swift Testing for new code** - modern, better concurrency support
4662. **Mark tests with correct isolation** - @MainActor when needed
4673. **Use confirmations over continuations** - when structured concurrency allows
4684. **Serialize tests with main serial executor** - avoid flaky tests
4695. **Test cancellation explicitly** - ensure proper cleanup
4706. **Verify deallocation** - catch retain cycles early
4717. **Use Task.yield() strategically** - control execution in tests
4728. **Avoid sleep in tests** - use continuations/confirmations instead
4739. **Test actor isolation** - verify thread safety
47410. **Keep tests deterministic** - avoid timing dependencies
475 
476## Migration from XCTest
477 
478### XCTest → Swift Testing
479 
480```swift
481// XCTest
482final class MyTests: XCTestCase {
483    func testExample() async {
484        XCTAssertEqual(value, expected)
485    }
486}
487 
488// Swift Testing
489@Suite
490struct MyTests {
491    @Test
492    func example() async {
493        #expect(value == expected)
494    }
495}
496```
497 
498### Expectations → Confirmations
499 
500```swift
501// XCTest
502let expectation = expectation(description: "Done")
503doWork { expectation.fulfill() }
504await fulfillment(of: [expectation])
505 
506// Swift Testing
507await confirmation { confirm in
508    await doWork { confirm() }
509}
510```
511 
512### Setup/Teardown → Traits
513 
514```swift
515// XCTest
516override func setUp() async throws {
517    await prepare()
518}
519 
520// Swift Testing
521struct SetupTrait: TestTrait, TestScoping {
522    func provideScope(
523        for test: Test,
524        testCase: Test.Case?,
525        performing function: () async throws -> Void
526    ) async throws {
527        await prepare()
528        try await function()
529    }
530}
531```
532 
533## Troubleshooting
534 
535### Test hangs
536 
537**Cause**: Waiting for expectation that never fulfills.
538 
539**Solution**: Add timeout, verify observation tracking.
540 
541### Flaky test
542 
543**Cause**: Race condition in unstructured task.
544 
545**Solution**: Use main serial executor + Task.yield().
546 
547### Deadlock
548 
549**Cause**: Using `wait(for:)` in async context.
550 
551**Solution**: Use `await fulfillment(of:)` instead.
552 
553### Confirmation fails
554 
555**Cause**: Not awaiting async work in confirmation block.
556 
557**Solution**: Add `await` before async calls.
558 
559### Actor isolation error
560 
561**Cause**: Test not marked with required actor.
562 
563**Solution**: Add `@MainActor` or appropriate actor to test.
564 
565## Common Mistakes Agents Make
566 
567- **Flaky intermediate-state assertions**: Asserting `isLoading == true` immediately after creating a `Task` is a race condition — the task may not have started yet. Use `withMainSerialExecutor` + `Task.yield()` to control scheduling before asserting intermediate state.
568- **Using `Task.sleep` as a synchronization primitive** in tests instead of deterministic scheduling.
569- **Asserting intermediate state without controlling scheduling**: Always use `withMainSerialExecutor` when you need to observe state between task creation and completion. Note: `withMainSerialExecutor` does not work with parallel test execution — mark the suite `@Suite(.serialized)`.
570- **Reaching into isolated internals** instead of testing public behavior.
571- **Keeping both Swift Testing and XCTest versions** of the same example unless they teach different migration paths.
572 
573## Testing Checklist
574 
575- [ ] Tests marked with correct isolation
576- [ ] Using Swift Testing (recommended)
577- [ ] Async methods properly awaited
578- [ ] Cancellation tested
579- [ ] Memory leaks checked
580- [ ] Race conditions handled
581- [ ] Timeouts appropriate
582- [ ] Flaky tests fixed with serial executor
583- [ ] Actor isolation verified
584- [ ] Cleanup in traits (not deinit)
585 
586## Further Learning
587 
588For advanced testing patterns, real-world examples, and migration strategies:
589- [Swift Testing Documentation](https://developer.apple.com/documentation/testing)
590- [Swift Concurrency Extras](https://github.com/pointfreeco/swift-concurrency-extras)
591- [Swift Concurrency Course](https://www.swiftconcurrencycourse.com)
592 
593