Testing Combine Publishers in iOS: Patterns for Reactive Code

Testing Combine Publishers in iOS: Patterns for Reactive Code

Combine is Apple's reactive framework for Swift. Testing Combine pipelines requires tools for collecting emissions over time, controlling schedulers, and asserting on async sequences without callback soup. This guide covers the practical patterns for reliable Combine tests.

The Core Challenge

Combine publishers emit values asynchronously. A test that creates a publisher and immediately asserts on its output will see nothing—the emissions haven't arrived yet. You need synchronization.

Three strategies:

  1. XCTestExpectation — classic callback synchronization
  2. Collecting with sink — gather all emissions, assert after publisher completes
  3. Scheduler injection — use ImmediateScheduler to make async code synchronous in tests

Strategy 1: XCTestExpectation

import Combine
import XCTest

class UserViewModelTests: XCTestCase {
    var cancellables = Set<AnyCancellable>()
    
    override func tearDown() {
        cancellables.removeAll()
    }
    
    func testLoadUserPublishesName() {
        let mockRepo = MockUserRepository()
        mockRepo.stubbedUser = User(id: "1", name: "Alice")
        let vm = UserViewModel(repository: mockRepo)
        
        let expectation = expectation(description: "Name published")
        
        vm.$userName
            .dropFirst()  // Skip initial empty value
            .sink { name in
                XCTAssertEqual(name, "Alice")
                expectation.fulfill()
            }
            .store(in: &cancellables)
        
        vm.loadUser(id: "1")
        
        waitForExpectations(timeout: 2)
    }
}

Strategy 2: Collecting Emissions

For publishers that emit multiple values and then complete:

extension Publisher {
    /// Collects all emissions synchronously (for publishers that complete)
    func collectOutput() throws -> [Output] {
        var output: [Output] = []
        var completion: Subscribers.Completion<Failure>?
        
        let semaphore = DispatchSemaphore(value: 0)
        
        let cancellable = self
            .collect()
            .sink(
                receiveCompletion: { c in
                    completion = c
                    semaphore.signal()
                },
                receiveValue: { values in
                    output = values
                }
            )
        
        _ = semaphore.wait(timeout: .now() + 5)
        _ = cancellable  // Retain
        
        if case .failure(let error) = completion {
            throw error
        }
        return output
    }
}

// Usage
func testSearchEmitsResultsInOrder() throws {
    let searchService = SearchService()
    
    let results = try searchService
        .search(query: "swift")
        .collectOutput()
    
    XCTAssertEqual(results.count, 3)
    XCTAssertEqual(results[0].title, "Swift Programming Language")
}

Strategy 3: Scheduler Injection

The most powerful pattern for unit tests. Inject a scheduler so you can control time:

// SearchViewModel.swift
class SearchViewModel: ObservableObject {
    @Published var searchText = ""
    @Published var results: [SearchResult] = []
    @Published var isLoading = false
    
    private let searchService: SearchServiceProtocol
    private let scheduler: AnySchedulerOf<DispatchQueue>
    private var cancellables = Set<AnyCancellable>()
    
    init(
        searchService: SearchServiceProtocol,
        scheduler: AnySchedulerOf<DispatchQueue> = .main
    ) {
        self.searchService = searchService
        self.scheduler = scheduler
        
        $searchText
            .debounce(for: .milliseconds(300), scheduler: scheduler)
            .filter { !$0.isEmpty }
            .removeDuplicates()
            .flatMap { [weak self] query -> AnyPublisher<[SearchResult], Never> in
                guard let self else { return Empty().eraseToAnyPublisher() }
                self.isLoading = true
                return self.searchService.search(query: query)
                    .replaceError(with: [])
                    .eraseToAnyPublisher()
            }
            .receive(on: scheduler)
            .sink { [weak self] results in
                self?.isLoading = false
                self?.results = results
            }
            .store(in: &cancellables)
    }
}
// SearchViewModelTests.swift
import CombineSchedulers  // Point-Free's scheduler utilities

class SearchViewModelTests: XCTestCase {
    var cancellables = Set<AnyCancellable>()
    
    func testDebouncedSearchOnlyFiresOnce() {
        let scheduler = DispatchQueue.test  // Controllable test scheduler
        let mockService = MockSearchService()
        mockService.stubbedResults = [SearchResult(title: "Swift")]
        
        let vm = SearchViewModel(
            searchService: mockService,
            scheduler: scheduler.eraseToAnyScheduler()
        )
        
        vm.searchText = "s"
        vm.searchText = "sw"
        vm.searchText = "swi"
        vm.searchText = "swift"
        
        // Advance past debounce window
        scheduler.advance(by: .milliseconds(300))
        
        XCTAssertEqual(mockService.searchCallCount, 1, "Should debounce to single search")
        XCTAssertEqual(vm.results.count, 1)
    }
    
    func testIsLoadingTrueWhileSearching() {
        let scheduler = DispatchQueue.test
        let mockService = MockSearchService()
        // Service that takes time to respond
        mockService.responseDelay = .milliseconds(500)
        
        let vm = SearchViewModel(
            searchService: mockService,
            scheduler: scheduler.eraseToAnyScheduler()
        )
        
        vm.searchText = "swift"
        scheduler.advance(by: .milliseconds(300))  // Past debounce
        
        XCTAssertTrue(vm.isLoading)
        
        scheduler.advance(by: .milliseconds(500))  // Past response delay
        
        XCTAssertFalse(vm.isLoading)
    }
}

Testing Custom Operators

extension Publisher {
    func retryWithDelay<S: Scheduler>(
        retries: Int,
        delay: S.SchedulerTimeType.Stride,
        scheduler: S
    ) -> AnyPublisher<Output, Failure> {
        self
            .catch { error -> AnyPublisher<Output, Failure> in
                guard retries > 0 else {
                    return Fail(error: error).eraseToAnyPublisher()
                }
                return Just(())
                    .delay(for: delay, scheduler: scheduler)
                    .flatMap { _ in
                        AnyPublisher<Output, Failure>
                            .init(Fail(error: error))
                            .retryWithDelay(retries: retries - 1, delay: delay, scheduler: scheduler)
                    }
                    .eraseToAnyPublisher()
            }
            .eraseToAnyPublisher()
    }
}

class RetryOperatorTests: XCTestCase {
    func testRetrySucceedsOnSecondAttempt() {
        let scheduler = DispatchQueue.test
        var callCount = 0
        
        let publisher = Deferred {
            Future<String, Error> { promise in
                callCount += 1
                if callCount < 2 {
                    promise(.failure(URLError(.timedOut)))
                } else {
                    promise(.success("success"))
                }
            }
        }
        .retryWithDelay(retries: 2, delay: .seconds(1), scheduler: scheduler)
        
        var received: [String] = []
        var completionError: Error?
        
        publisher.sink(
            receiveCompletion: { completion in
                if case .failure(let error) = completion {
                    completionError = error
                }
            },
            receiveValue: { received.append($0) }
        ).store(in: &cancellables)
        
        scheduler.advance(by: .seconds(1))
        
        XCTAssertEqual(callCount, 2)
        XCTAssertEqual(received, ["success"])
        XCTAssertNil(completionError)
    }
}

Testing Error Handling

func testErrorPublishedAsUserMessage() {
    let mockRepo = MockUserRepository()
    mockRepo.stubbedError = URLError(.notConnectedToInternet)
    
    let vm = UserViewModel(repository: mockRepo)
    
    var receivedErrors: [String] = []
    let errorExpectation = expectation(description: "Error message published")
    
    vm.$errorMessage
        .compactMap { $0 }
        .first()
        .sink { message in
            receivedErrors.append(message)
            errorExpectation.fulfill()
        }
        .store(in: &cancellables)
    
    vm.loadUser(id: "1")
    
    waitForExpectations(timeout: 2)
    
    XCTAssertFalse(receivedErrors.isEmpty)
    XCTAssertTrue(
        receivedErrors[0].contains("connection") || receivedErrors[0].contains("network"),
        "Error message should be user-friendly, got: \(receivedErrors[0])"
    )
}

Testing @Published Properties

class FormViewModelTests: XCTestCase {
    func testSubmitButtonDisabledWhenFieldsEmpty() {
        let vm = FormViewModel()
        
        XCTAssertFalse(vm.isSubmitEnabled)
        
        vm.name = "Alice"
        // Still disabled — email missing
        XCTAssertFalse(vm.isSubmitEnabled)
        
        vm.email = "alice@example.com"
        // Now enabled
        XCTAssertTrue(vm.isSubmitEnabled)
    }
    
    func testIsSubmitEnabledPublishesChanges() {
        let scheduler = DispatchQueue.test
        let vm = FormViewModel(scheduler: scheduler.eraseToAnyScheduler())
        
        var states: [Bool] = []
        vm.$isSubmitEnabled
            .sink { states.append($0) }
            .store(in: &cancellables)
        
        vm.name = "Alice"
        vm.email = "alice@example.com"
        vm.name = ""  // Remove name
        
        scheduler.advance()
        
        // Should have published: false, false, true, false
        XCTAssertEqual(states, [false, false, true, false])
    }
}

Testing Combine with async/await

In Xcode 13+, bridge Combine to async/await for cleaner test syntax:

func testFetchPublisherWithAsyncAwait() async throws {
    let mockRepo = MockUserRepository()
    mockRepo.stubbedUser = User(id: "1", name: "Alice")
    
    let vm = UserViewModel(repository: mockRepo)
    vm.loadUser(id: "1")
    
    // Collect first non-nil value from publisher
    let user = try await vm.$user
        .compactMap { $0 }
        .first()
        .values
        .first(where: { _ in true })
    
    XCTAssertEqual(user?.name, "Alice")
}

Or use the AsyncPublisher extension:

func testValuesSequence() async throws {
    let subject = PassthroughSubject<Int, Never>()
    
    Task {
        for value in [1, 2, 3] {
            subject.send(value)
        }
        subject.send(completion: .finished)
    }
    
    var collected: [Int] = []
    for await value in subject.values {
        collected.append(value)
    }
    
    XCTAssertEqual(collected, [1, 2, 3])
}

Conclusion

Combine tests are reliable when you control time. Inject schedulers into production code, use DispatchQueue.test from CombineSchedulers in tests, and advance time explicitly. For simpler publishers, XCTestExpectation with dropFirst() covers most cases. The patterns here—scheduler injection, emission collection, operator unit tests—work together to make reactive code as testable as any synchronous code.

Read more

Start now free