swift-clocks

The library provides three primary implementations of the Clock protocol to handle different development scenarios:

• ImmediateClock: Executes time-based operations immediately.
• TestClock: Allows for manual control over time progression, making it ideal for testing asynchronous logic without waiting for real-world time.
• UnimplementedClock: Used to represent a clock that has not yet been implemented, useful for scaffolding or identifying missing dependencies.

An UnimplementedClock causes an XCTest failure if any of its endpoints are invoked. Use this when a feature requires a clock dependency, but you want to prove that the specific execution flow being tested does not actually use any time-based asynchrony. If the code accidentally uses the clock, the test will fail, alerting you to unexpected behavior.

func testIncrementDecrement() {
  let model = FeatureModel(clock: UnimplementedClock())

  XCTAssertEqual(model.count, 0)
  self.model.incrementButtonTapped()
  XCTAssertEqual(model.count, 1)
  self.model.decrementButtonTapped()
  XCTAssertEqual(model.count, 0)
}

An ImmediateClock squashes time down to a single instant, causing any sleep calls to execute immediately. This is highly useful for SwiftUI Previews where you want to avoid waiting for real-world timers (e.g., a 5-second welcome message) to finish before seeing UI changes.

struct Feature_Previews: PreviewProvider {
  static var previews: some View {
    Feature(clock: ImmediateClock())
  }
}

All clocks in this library provide a timer(interval:) method that returns an AsyncSequence. This allows you to handle periodic tasks using a simple for await loop.

for await _ in self.clock.timer(interval: .seconds(1)) {
  self.count += 1
}

When using TestClock, you can verify if the clock is currently suspended (i.e., time is not advancing). This is useful for ensuring that tasks are correctly scheduled or that a process has paused as expected.

• checkSuspension(): Throws a SuspensionError if the clock is not in a suspended state.
• SuspensionError: The error thrown when checkSuspension() is called on a clock that is not suspended.

let clock = TestClock()
// ... perform actions ...
try clock.checkSuspension()

The library provides continuousClock and suspendingClock environment values to easily propagate clocks through a SwiftUI view hierarchy. This allows you to use a real ContinuousClock in production and an ImmediateClock in previews.

struct Feature: View {
  @Environment(\.continuousClock) var clock

  var body: some View {
    // ... use self.clock.sleep(for: ...) 
  }
}

struct Feature_Previews: PreviewProvider {
  static var previews: some View {
    Feature()
      .environment(\.continuousClock, ImmediateClock())
  }
}

A TestClock provides methods to manually manipulate the current time, allowing you to trigger scheduled tasks or simulate delays in your asynchronous code.

• advance(by:): Advances the clock by a specific duration.
• advance(to:): Advances the clock to a specific point in time.
• run(timeout:file:line:): Runs a block of code and fails if the code does not complete within the specified timeout relative to the clock's time.

let clock = TestClock()

// Advance time by 5 seconds
await clock.advance(by: .seconds(5))

// Advance time to a specific instant
await clock.advance(to: .now + .seconds(10))

// Run a task with a timeout
try await clock.run(timeout: .seconds(1)) {
    // asynchronous work here
}

An ImmediateClock is a clock that always returns the same instant for every call to now(). It is useful for testing scenarios where you want to simulate time passing without actually waiting, or when you need a stable reference point for time-based logic.

You can create an ImmediateClock using the default initializer or by providing a specific starting instant.

// Create an immediate clock starting at the current time
let clock = ImmediateClock()

// Create an immediate clock starting at a specific instant
let specificInstant = ContinuousClock.now
let clockWithInstant = ImmediateClock(now: specificInstant)

Use TestClock to control time in your tests. This allows you to simulate the passage of time deterministically without waiting for real-world wall clock time. You can initialize it with a specific starting time or use the default initializer.

let clock = TestClock()
// or
let clock = TestClock(now: .now)