Combine Schedulers

A TestScheduler allows for deterministic control over time and execution. It is essential for testing Combine operators that depend on time, such as debounce, throttle, delay, timeout, and receive(on:).

You can use scheduler.advance(by:) to manually move time forward, allowing you to assert the state of your publishers at specific points in time without waiting for real-world clock time.

let scheduler = DispatchQueue.test

let first = Future<Int, Never> { callback in
  scheduler.schedule(after: scheduler.now.advanced(by: 1)) { callback(.success(1)) }
}
let second = Future<Int, Never> { callback in
  scheduler.schedule(after: scheduler.now.advanced(by: 2)) { callback(.success(2)) }
}

var output: [Int] = []
let cancellable = race(first, second).sink { output.append($0) }

scheduler.advance(by: 1)
XCTAssertEqual(output, [1])

scheduler.advance(by: 1)
XCTAssertEqual(output, [1])

The ImmediateScheduler executes work immediately, effectively collapsing time into a single point. Unlike TestScheduler, you cannot explicitly control the flow of time, but it is highly useful for testing code that uses receive(on:) or subscribe(on:) without needing to use XCTestExpectation or wait for real-world delays.

It is available for common types: DispatchQueue.immediate, RunLoop.immediate, and OperationQueue.immediate.

// In your view model, inject the scheduler
class HomeViewModel: ObservableObject {
  let scheduler: AnySchedulerOf<DispatchQueue>
  // ...
  func reloadButtonTapped() {
    Just(())
      .delay(for: .seconds(10), scheduler: self.scheduler)
      .flatMap { apiClient.fetchEpisodes() }
      .assign(to: &self.$episodes)
  }
}

// In your test, use .immediate to skip the 10s delay
func testViewModel() {
  let viewModel = HomeViewModel(
    apiClient: .mock,
    scheduler: .immediate
  )
  viewModel.reloadButtonTapped()
  XCTAssertEqual(viewModel.episodes, [Episode(id: 42)])
}

The AnyScheduler provides a type-erasing wrapper for the Scheduler protocol. This allows you to inject different types of schedulers (like DispatchQueue.main for production and ImmediateScheduler for testing) into your classes without making those classes generic.

Instead of using a generic type like class MyViewModel<S: Scheduler>, use AnySchedulerOf<T> where T is the underlying scheduler type (e.g., DispatchQueue).

To create an AnyScheduler from a live scheduler, use .eraseToAnyScheduler(). For common schedulers like DispatchQueue, OperationQueue, and RunLoop, you can use convenient static helpers like .main or .immediate.

class EpisodeViewModel: ObservableObject {
  @Published var episode: Episode?
  let apiClient: ApiClient
  let scheduler: AnySchedulerOf<DispatchQueue>

  init(apiClient: ApiClient, scheduler: AnySchedulerOf<DispatchQueue>) {
    self.apiClient = apiClient
    self.scheduler = scheduler
  }

  func reloadButtonTapped() {
    self.apiClient.fetchEpisode()
      .receive(on: self.scheduler)
      .assign(to: &self.$episode)
  }
}

// Production usage
let viewModel = EpisodeViewModel(
  apiClient: ..., 
  scheduler: .main
)

// Test usage
let viewModel = EpisodeViewModel(
  apiClient: ..., 
  scheduler: .immediate
)

Instead of using Foundation's Timer.publisher, use Publishers.Timer or the .timerPublisher(every:) method on a scheduler. This allows you to use any scheduler (including TestScheduler) for the timer, making time-based Combine code fully testable and deterministic.

• Publishers.Timer(every:scheduler:): Creates a timer publisher on a specific scheduler.
• scheduler.timerPublisher(every:): A convenience method on the scheduler to derive a timer.

// Using the publisher directly
Publishers.Timer(every: .seconds(1), scheduler: DispatchQueue.main)
  .autoconnect()
  .sink { print("Timer", $0) }

// Using the scheduler helper
DispatchQueue.main.timerPublisher(every: .seconds(1))
  .autoconnect()
  .sink { print("Timer", $0) }

// Testing a timer with TestScheduler
let scheduler = DispatchQueue.test
var output: [Int] = []

Publishers.Timer(every: 1, scheduler: scheduler)
  .autoconnect()
  .sink { _ in output.append(output.count) }
  .store(in: &self.cancellables)

scheduler.advance(by: 1)
XCTAssertEqual(output, [0])

scheduler.advance(by: 1_000)
XCTAssertEqual(output, Array(0...1_001))