Swift 问题报告

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

概述

该库提供了强大的工具，用于报告应用程序中的问题，并具有可自定义的粒度和严重程度。最基本的形式是在应用程序中的任何位置使用 reportIssue 函数来标记代码中的问题，例如您认为永远不应该执行的代码路径

guard let lastItem = items.last
else {
  reportIssue("'items' should never be empty.")
  return 
}
…

默认情况下，在 Xcode (模拟器和设备) 中运行应用程序时，这将触发一个不显眼的紫色运行时警告

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

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

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

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

有许多流行的库正在使用 Issue Reporting。仅举几例

Perception 是 Swift Observation 框架的一个向后移植版本，可以部署到 iOS 13 世代的设备，但需要一个特殊的 SwiftUI 视图来观察用宏注释的对象的更改。当库检测到此视图丢失时，它会使用 Issue Reporting 来警告开发人员，并提供指向该视图的跟踪。
Dependencies 是一个通用的依赖注入库，灵感来自 SwiftUI 的环境。它使用 Swift Issue Reporting 在用户访问依赖项而未覆盖它们时通知用户。这会在在模拟器中运行时导致运行时警告，并在测试时导致测试失败。它强制每个测试显式声明其依赖项，并且当向功能引入新依赖项时，现有测试将失败，直到它们考虑到它为止。

The Composable Architecture 配备了强大的测试工具，这要归功于 Swift Issue Reporting，开箱即用地支持 Swift Testing 和 XCTest。此外，该库还大量使用了问题报告功能，以帮助开发人员尽早发现代码中的错误。
Custom Dump 是 Swift dump 函数的改进版本，还有更多功能。它提供格式良好的数据类型转储，读起来像 Swift 代码，以及在比较数据类型时格式良好的差异。它还附带了由 Swift Issue Reporting 提供支持的多个测试助手，包括 #expect(_ == _) 和 XCTAssertEqual 的直接替代品，它们将失败呈现为简洁的差异，以及允许您断言数据结构随时间变化的助手。
Swift Clocks 和 Combine Schedulers 是兄弟包，它们使用问题报告来驱动其“测试”和“未实现”的时钟和调度器。“测试”时钟/调度器允许您在测试中控制时间，并且在未满足期望时会发出失败。“未实现”的时钟/调度器将意外使用记录为问题。

还有其他案例研究要分享吗？请告诉我们！

完整文档可以在这里找到。

该库在 MIT 许可证下发布。有关详细信息，请参阅 LICENSE。