Home

Awesome

Swift Issue Reporting

CI

Report issues in your application and library code as Xcode runtime warnings, breakpoints, assertions, and do so in a testable manner.

Overview

This library provides robust tools for reporting issues in your application with a customizable degree of granularity and severity. In its most basic form you use the reportIssue function anywhere in your application to flag an issue in your code, such as a code path that you think should never be executed:

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

By default, this will trigger an unobtrusive, purple runtime warning when running your app in Xcode (simulator and device):

<picture> <source media="(prefers-color-scheme: dark)" srcset="Sources/IssueReporting/Documentation.docc/Resources/runtime-warning~dark.png"> <source media="(prefers-color-scheme: light)" srcset="Sources/IssueReporting/Documentation.docc/Resources/runtime-warning.png"> <img alt="A purple runtime warning in Xcode showing that an issue has been reported." src="Sources/IssueReporting/Documentation.docc/Resources/runtime-warning.png"> </picture>

This provides a very visual way of seeing when an issue has occurred in your application without stopping the app's execution or interrupting your workflow.

The reportIssue tool can also be customized to allow for other ways of reporting issues. It can be configured to trigger a breakpoint if you want to do some debugging when an issue is reported, or a precondition or fatal error if you want to truly stop execution. And you can create your own custom issue reporter to send issues to OSLog or an external server.

Further, when running your code in a testing context (both Swift's native Testing framework as well as XCTest), all reported issues become test failures. This helps you get test coverage that problematic code paths are not executed, and makes it possible to build testing tools for libraries that ship in the same target as the library itself.

<picture> <source media="(prefers-color-scheme: dark)" srcset="Sources/IssueReporting/Documentation.docc/Resources/test-failure~dark.png"> <source media="(prefers-color-scheme: light)" srcset="Sources/IssueReporting/Documentation.docc/Resources/test-failure.png"> <img alt="A test failure in Xcode where an issue has been reported." src="Sources/IssueReporting/Documentation.docc/Resources/test-failure.png"> </picture>

Issue Reporting comes with a number of reporters, custom reporting functionality, and more. To learn about these features, see Getting started.

Case studies

There are many popular libraries out there using Issue Reporting. To name a few:

<!-- * [**Swift Navigation**](https://github.com/pointfreeco/swiftui-navigation) provides concise--> <!-- domain modeling tools for UI frameworks including SwiftUI, UIKit, and more; and it uses Swift--> <!-- Issue Reporting to raise runtime warnings when APIs are used in unexpected ways.-->

Have another case study to share? Let us know!

Documentation

Full documentation can be found here.

License

This library is released under the MIT license. See LICENSE for details.