swift-clocks

⏰ 一些时钟，使Swift并发更易测试和更加灵活。

• 动机
• 了解更多
  • TestClock
  • ImmediateClock
  • UnimplementedClock
  • 计时器
  • AnyClock
• 文档
• 许可证

了解更多

这个库是在[Point-Free][point-free]的系列视频中设计的，这是一个由[Brandon Williams][mbrandonw]和[Stephen Celis][stephencelis]主持的探索Swift编程语言的视频系列。

你可以在[这里][clock-collection]观看所有的剧集。

动机

Swift中的Clock协议为Swift的结构化并发提供了一个强大的时间基础异步抽象。仅通过一个sleep方法，你就可以表达许多强大的异步操作符，如计时器、debounce、throttle、timeout等（参见[swift-async-algorithms][swift-async-algorithms]）。

然而，当你在异步代码中使用具体的时钟，或直接使用Task.sleep时，你立即就失去了轻松测试和预览功能的能力，被迫等待真实世界的时间流逝来查看你的功能如何工作。

这个库提供了新的Clock实现，让你可以将任何基于时间的异步代码转变为更易于测试和调试的东西：

• TestClock
• ImmediateClock
• UnimplementedClock
• 计时器
• AnyClock

TestClock

一个可以以确定性方式控制时间的时钟。

这个时钟对于测试时间流逝如何影响异步和并发代码非常有用。这包括任何使用sleep或任何基于时间的异步操作符的代码，如debounce、throttle、timeout等。

例如，假设你有一个模型，封装了一个可以启动和停止的计时器的行为，每次计时器滴答一次，计数值就会增加：

@MainActor
class FeatureModel: ObservableObject {
  @Published var count = 0
  let clock: any Clock<Duration>
  var timerTask: Task<Void, Error>?

  init(clock: any Clock<Duration>) {
    self.clock = clock
  }
  func startTimerButtonTapped() {
    self.timerTask = Task {
      while true {
        try await self.clock.sleep(for: .seconds(1))
        self.count += 1
      }
    }
  }
  func stopTimerButtonTapped() {
    self.timerTask?.cancel()
    self.timerTask = nil
  }
}

注意，我们明确要求在构造FeatureModel时提供一个时钟。这使得在设备或模拟器上运行时可以使用真实的时钟（如ContinuousClock），而在测试中可以使用更可控的时钟，如[TestClock][test-clock-docs]。

要为这个功能编写测试，我们可以用TestClock构造一个FeatureModel，然后推进时钟并断言模型如何变化：

func testTimer() async {
  let clock = TestClock()
  let model = FeatureModel(clock: clock)

  XCTAssertEqual(model.count, 0)
  model.startTimerButtonTapped()

  // 将时钟推进1秒，并证明模型的计数增加了1。
  await clock.advance(by: .seconds(1))
  XCTAssertEqual(model.count, 1)

  // 将时钟推进4秒，并证明模型的计数增加了4。
  await clock.advance(by: .seconds(4))
  XCTAssertEqual(model.count, 5)

  // 停止计时器，运行时钟直到没有更多挂起，
  // 并证明计数没有增加。
  model.stopTimerButtonTapped()
  await clock.run()
  XCTAssertEqual(model.count, 5)
}

这个测试很容易编写，确定性地通过，并且只需要一小部分秒就能运行。如果你在你的功能中使用具体的时钟，这样的测试将很难编写。你将不得不等待真实时间流逝，减慢你的测试套件，并且你将不得不格外小心，以允许基于时间的异步固有的不精确性，以免出现不稳定的测试。

ImmediateClock

一个在睡眠时不挂起的时钟。

这个时钟对于将所有时间压缩到单个瞬间很有用，强制任何sleep立即执行。例如，假设你有一个功能需要等待5秒才执行某些操作，比如显示欢迎消息：

struct Feature: View {
  @State var message: String?

  var body: some View {
    VStack {
      if let message = self.message {
        Text(self.message)
      }
    }
    .task {
      do {
        try await Task.sleep(for: .seconds(5))
        self.message = "欢迎！"
      } catch {}
    }
  }
}

这目前正在使用通过调用 Task.sleep 实现的真实时钟,这意味着你对此功能的样式和行为做出的每个更改,都必须等待 5 秒钟真实时间才能看到效果。这将严重影响你在 Xcode 预览中快速迭代该功能的能力。

解决方法是让你的视图持有一个时钟,以便可以从外部控制:

struct Feature: View {
  @State var message: String?
  let clock: any Clock<Duration>

  var body: some View {
    VStack {
      if let message = self.message {
        Text(self.message)
      }
    }
    .task {
      do {
        try await self.clock.sleep(for: .seconds(5))
        self.message = "Welcome!"
      } catch {}
    }
  }
}

然后,在设备或模拟器上运行时可以使用 ContinuousClock 构造此视图,在 Xcode 预览中运行时可以使用 ImmediateClock:

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

现在,每次对视图进行更改时,欢迎消息都会立即显示。无需等待 5 秒钟真实时间过去。

你还可以通过库附带的 continuousClock 和 suspendingClock 环境值将时钟传播到 SwiftUI 视图:

struct Feature: View {
  @State var message: String?
  @Environment(\.continuousClock) var clock

  var body: some View {
    VStack {
      if let message = self.message {
        Text(self.message)
      }
    }
    .task {
      do {
        try await self.clock.sleep(for: .seconds(5))
        self.message = "Welcome!"
      } catch {}
    }
  }
}

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

UnimplementedClock

一个在调用其任何端点时导致 XCTest 失败的时钟。

当必须提供时钟依赖项来测试功能,但你实际上并不期望在正在执行的特定执行流程中使用时钟时,此时钟很有用。

例如,考虑以下模型,该模型封装了能够增加和减少计数的行为,以及启动和停止每秒递增计数器的计时器:

@MainActor
class FeatureModel: ObservableObject {
  @Published var count = 0
  let clock: any Clock<Duration>
  var timerTask: Task<Void, Error>?

  init(clock: some Clock<Duration>) {
    self.clock = clock
  }
  func incrementButtonTapped() {
    self.count += 1
  }
  func decrementButtonTapped() {
    self.count -= 1
  }
  func startTimerButtonTapped() {
    self.timerTask = Task {
      for await _ in self.clock.timer(interval: .seconds(1)) {
        self.count += 1
      }
    }
  }
  func stopTimerButtonTapped() {
    self.timerTask?.cancel()
    self.timerTask = nil
  }
}

如果我们测试用户增加和减少计数的流程,就不需要时钟。我们不期望发生任何基于时间的异步操作。为了明确这一点,我们可以使用 UnimplementedClock:

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)
}

如果此测试通过,它明确证明在测试的用户流程中根本没有使用时钟,这使得这个测试更加强大。如果将来增加和减少端点开始使用基于时间的异步操作使用时钟,我们将立即通过测试失败得到通知。这将帮助我们找到应该更新以断言功能中新行为的测试。

计时器

所有时钟现在都带有一个方法,允许你在由持续时间指定的间隔上创建基于 AsyncSequence 的计时器。这允许你使用简单的 for await 语法处理计时器,例如这个可观察对象公开了启动和停止计时器以每秒递增值的能力:

@MainActor
class FeatureModel: ObservableObject {
  @Published var count = 0
  let clock: any Clock<Duration>
  var timerTask: Task<Void, Error>?

  init(clock: any Clock<Duration>) {
    self.clock = clock
  }
  func startTimerButtonTapped() {
    self.timerTask = Task {
      for await _ in self.clock.timer(interval: .seconds(1)) {
        self.count += 1
      }
    }
  }
  func stopTimerButtonTapped() {
    self.timerTask?.cancel()
    self.timerTask = nil
  }
}

通过使用上面讨论的 TestClock,也可以轻松测试此功能:

func testTimer() async {
  let clock = TestClock()
  let model = FeatureModel(clock: clock)

  XCTAssertEqual(model.count, 0)
  model.startTimerButtonTapped()

  await clock.advance(by: .seconds(1))
  XCTAssertEqual(model.count, 1)

  await clock.advance(by: .seconds(4))
  XCTAssertEqual(model.count, 5)

  model.stopTimerButtonTapped()
  await clock.run()
}

AnyClock

any Clock 的具体版本。

这种类型使得可以将时钟存在类型传递给原本禁止的 API。

例如,Async Algorithms 包提供了许多接受时钟的 API,但由于 Swift 的限制,它们不能接受 any Clock 形式的时钟存在类型:

class Model: ObservableObject {
  let clock: any Clock<Duration>
  init(clock: some Clock<Duration>) {
    self.clock = clock
  }

  func task() async {
    // 🛑 类型 'any Clock<Duration>' 无法符合 'Clock'
    for await _ in stream.debounce(for: .seconds(1), clock: self.clock) {
      // ...
    }
  }
}

相反,通过使用具体的 AnyClock,我们可以解决这个限制:

// ✅
for await _ in stream.debounce(for: .seconds(1), clock: AnyClock(self.clock)) {
  // ...
}

文档

此库的最新文档可在[此处][clock-docs]获得。

许可证

该库根据 MIT 许可证发布。有关详细信息,请参阅 LICENSE。 [swift-async-algorithms]：http://github.com/apple/swift-async-algorithms [point-free]：https://www.pointfree.co [mbrandonw]：https://github.com/mbrandonw [stephencelis]：https://github.com/stephencelis [clock-collection]：https://www.pointfree.co/collections/concurrency/clocks [clock-docs]：https://swiftpackageindex.com/pointfreeco/swift-clocks/main/documentation/clocks [test-clock-docs]：待定