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:
- XCTestExpectation — classic callback synchronization
- Collecting with sink — gather all emissions, assert after publisher completes
- Scheduler injection — use
ImmediateSchedulerto 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.