IssueReporting
Report issues in your application and library code as Xcode runtime warnings, breakpoints, assertions, and do so in a testable manner.
import IssueReporting
Module information
- Declarations
- 52
- Symbols
- 64
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 unified 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, reportIssue
will trigger an unobtrusive, purple runtime warning when running your app in Xcode (simulator and device):
This provides a very visible way to see when an issue has occurred in your application without stopping the app’s execution and 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 XCTest and Swift’s native Testing framework), 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.
Essentials
Getting started
Learn how to report issues in your application code, and how to customize how issues are reported.
Read MoreTesting in release mode
Learn about extra steps that must be taken when writing tests in release mode.
Read MoreCreating testing tools
Learn how to build testing tools in your libraries using Issue Reporting.
Read More
Reporting issues
func reportIssue(@autoclosure () -> String?, fileID: StaticString, filePath: StaticString, line: UInt, column: UInt
) Report an issue.
func withExpectedIssue(String?, isIntermittent: Bool, fileID: StaticString, filePath: StaticString, line: UInt, column: UInt, () throws -> Void
) Invoke a function that has an issue that is expected to occur during its execution.
func withErrorReporting<R>(@autoclosure () -> String?, to: [any IssueReporter]?, fileID: StaticString, filePath: StaticString, line: UInt, column: UInt, catching: () throws -> R
) -> R? Evaluates a throwing closure and automatically catches and reports any error thrown.
Issue reporters
IssueReporter/breakpoint
static var fatalError: Self
An issue reporter that terminates program execution.
static var runtimeWarning: Self
An issue reporter that emits “purple” runtime warnings to Xcode and logs fault-level messages to the console.
Custom reporting
protocol IssueReporter
A type that can report issues.
func withIssueReporters<R>([any IssueReporter], operation: () throws -> R
) rethrows -> R Overrides the task’s issue reporters for the duration of the synchronous operation.
func withIssueContext<R>(fileID: StaticString, filePath: StaticString, line: UInt, column: UInt, operation: () throws -> R
) rethrows -> R Sets the context for issues reported for the duration of the synchronous operation.
enum IssueReporters
Testing
let isTesting: Bool
Whether or not the current process is running tests.
enum TestContext
A type representing the context in which a test is being run, i.e. either in Swift’s native Testing framework, or Xcode’s XCTest framework.
Unimplemented
func unimplemented<each Argument, Result>(@autoclosure @escaping () -> String, placeholder: @autoclosure @escaping () -> Result, fileID: StaticString, filePath: StaticString, function: StaticString, line: UInt, column: UInt
) -> (repeat each Argument) -> Result Returns a closure that reports an issue when invoked.