Swift 问题报告

以可测试的方式，将应用程序和库代码中的问题报告为 Xcode 运行时警告、断点和断言。

概述

该库提供了强大的工具，可以通过可自定义的粒度和严重程度报告应用程序中的问题。最基本的形式是，你可以在应用程序的任何地方使用 reportIssue 函数来标记代码中的问题，比如你认为永远不应该执行的代码路径：

guard let lastItem = items.last
else {
  reportIssue("'items' 不应该为空。")
  return 
}
…

默认情况下，这将在 Xcode 中运行应用程序时（模拟器和设备）触发一个不引人注目的紫色运行时警告：

这提供了一种非常直观的方式来查看应用程序中何时发生问题，而不会停止应用程序的执行或中断你的工作流程。

reportIssue 工具还可以自定义，允许其他方式报告问题。可以配置它触发断点（如果你想在报告问题时进行调试），或者触发前置条件或致命错误（如果你真的想停止执行）。你还可以创建自定义的问题报告器，将问题发送到 OSLog 或外部服务器。

此外，在测试环境中运行代码时（包括 Swift 的原生测试框架和 XCTest），所有报告的问题都会变成测试失败。这有助于你获得有问题的代码路径未被执行的测试覆盖率，并使得为与库在同一目标中发布的库构建测试工具成为可能。

问题报告附带了许多报告器、自定义报告功能等。要了解这些功能，请参阅入门指南。

案例研究

有许多流行的库正在使用问题报告。以下是其中一些：

Perception 是 Swift 的 Observation 框架的向后移植版本，可以部署到 iOS 13 一代设备，但需要特殊的 SwiftUI 视图来观察带有宏注解的对象的变化。当库检测到缺少这个视图时，它会使用问题报告来警告开发者，并指向该视图。
Dependencies 是一个受 SwiftUI 环境启发的通用依赖注入库。它使用 Swift 问题报告来通知用户在未重写依赖项的情况下访问依赖项。这会在模拟器中运行时产生运行时警告，在测试时产生测试失败。它强制每个测试明确声明其依赖项，当向功能引入新的依赖项时，现有测试将失败，直到它们考虑到这一点。
The Composable Architecture 提供了强大的测试工具，默认支持 Swift Testing 和 XCTest，这要归功于 Swift 问题报告。此外，该库大量使用问题报告来帮助开发者尽早发现代码中的错误。
Custom Dump 是 Swift 的 dump 函数的改进版本，还有更多功能。它提供了看起来像 Swift 代码的数据类型的格式良好的转储，以及数据类型比较时的格式良好的差异。它还提供了几个由 Swift 问题报告支持的测试辅助工具，包括 #expect(_ == _) 和 XCTAssertEqual 的替代品，可以将失败渲染为简洁的差异，以及允许你断言数据结构随时间变化的辅助工具。
Swift Clocks 和 Combine Schedulers 是姐妹包，使用问题报告来驱动它们的"测试"和"未实现"时钟和调度器。"测试"时钟/调度器允许你在测试中控制时间，并在不满足预期时发出失败。"未实现"时钟/调度器将意外的使用记录为问题。