|
4 | 4 | [](https://swiftpackageindex.com/pointfreeco/xctest-dynamic-overlay) |
5 | 5 | [](https://swiftpackageindex.com/pointfreeco/xctest-dynamic-overlay) |
6 | 6 |
|
7 | | -Report issues in your application and library code as Xcode runtime warnings, test failures, and |
8 | | -more. |
| 7 | +Report issues in your application and library code as Xcode runtime warnings, breakpoints, |
| 8 | +assertions, and do so in a testable manner. |
9 | 9 |
|
10 | 10 | ## Overview |
11 | 11 |
|
12 | | -Swift Issue Reporting lets you generate your own "purple" Xcode runtime warnings in application and |
13 | | -library code: |
| 12 | +This library provides robust tools for reporting issues in your application with a customizable |
| 13 | +degree of granularity and severity. In its most basic for you use the unified |
| 14 | +[`reportIssue`](<doc:reportIssue(_:fileID:filePath:line:column:)>) function anywhere in your |
| 15 | +application to flag an issue with your code, such as a code path that you think should never be |
| 16 | +executed: |
14 | 17 |
|
15 | | -[] |
16 | | - |
17 | | -Further, if one of these runtime warnings is emitted from a unit test, it will automatically be |
18 | | -recorded as a test failure: |
| 18 | +```swift |
| 19 | +guard let lastItem = items.last |
| 20 | +else { |
| 21 | + reportIssue("'items' should never be empty.") |
| 22 | + return |
| 23 | +} |
| 24 | +… |
| 25 | +``` |
19 | 26 |
|
20 | | -[] |
| 27 | +By default, [`reportIssue`](<doc:reportIssue(_:fileID:filePath:line:column:)>) will trigger an |
| 28 | +unobtrusive, purple runtime warning when running your app in Xcode (simulator and device): |
21 | 29 |
|
22 | | -And so the benefits are twofold: reporting issues will help you catch bugs during debug _and_ test |
23 | | -sessions. |
| 30 | + |
24 | 31 |
|
25 | | -While this is incredibly useful on its own, it only scratches the library's surface. This |
26 | | -functionality is built on top of a highly flexible issue reporting system that can be used in a |
27 | | -variety of ways. |
| 32 | +This provides a very visible way to see when an issue has occured in your application without |
| 33 | +stopping the app's execution and interrupting your workflow. |
28 | 34 |
|
29 | | -### Custom issue reporting |
| 35 | +The [`reportIssue`](<doc:reportIssue(_:fileID:filePath:line:column:)>) tool can also be customized |
| 36 | +to allow for other ways of reporting issues. It can be configured to trigger a breakpoint if you |
| 37 | +want to do some debugging when an issue is reported, or a precondition or fatal error if you want |
| 38 | +to truly stop execution. And you can create your own custom issue reporter to send issues to OSLog |
| 39 | +or an external server. |
30 | 40 |
|
31 | | -<!-- TODO --> |
| 41 | +Further, when running your code in a testing context (both XCTest and Swift's native Testing |
| 42 | +framework), all reported issues become _test failures_. This helps you get test coverage that |
| 43 | +problematic code paths are not executed, and makes it possible to build testing tools for libraries |
| 44 | +that ship in the same target as the library itself. |
32 | 45 |
|
33 | | -### Custom test helpers |
| 46 | +// TODO: test failure image |
34 | 47 |
|
35 | | -<!-- TODO --> |
| 48 | +// TODO: link to get started article |
36 | 49 |
|
37 | 50 | ## Case studies |
38 | 51 |
|
39 | 52 | There are many popular libraries out there using Swift Issue Reporting. To name a few: |
40 | 53 |
|
41 | 54 | <!-- TODO: Order? --> |
42 | | - |
43 | | - * [**The Composable Architecture**](https://github.com/pointfreeco/swift-composable-architecture) |
44 | | - comes with powerful testing tools that support both Swift Testing and XCTest out of the box |
45 | | - thanks to Swift Issue Reporting. In addition, the library is heavily instrumented with issue |
46 | | - reporting to help developers catch bugs in their code early. |
| 55 | +<!-- TODO: Rewrite for SwiftUI Navigation if Swift Issue Reporting is released first --> |
47 | 56 |
|
48 | 57 | * [**Perception**](https://github.com/pointfreeco/swift-perception) is a back-port of Swift's |
49 | 58 | Observation framework that can be deployed all the way back to the iOS 13 generation of devices. |
50 | 59 | It provides a special SwiftUI view that can observe changes to objects annotated with the macro, |
51 | 60 | and uses Swift Issue Reporting to warn developers when this view is missing. |
52 | 61 |
|
53 | | - <!-- TODO: Rewrite for SwiftUI Navigation if Swift Issue Reporting is released first --> |
54 | | - |
55 | | - * [**Swift Navigation**](https://github.com/pointfreeco/swiftui-navigation) provides concise |
56 | | - domain modeling tools for UI frameworks including SwiftUI, UIKit, and more; and it uses Swift |
57 | | - Issue Reporting to raise runtime warnings when APIs are used in unexpected ways. |
58 | | - |
59 | 62 | * [**Swift Dependencies**](https://github.com/pointfreeco/swift-dependencies) is a general purpose |
60 | 63 | dependency injection tool inspired by SwiftUI's environment. It uses Swift Issue Reporting to |
61 | 64 | notify users when they haven't asserted against how a dependency is used. This forces each test |
62 | 65 | to explicitly declare its dependencies, and when a new dependency is introduced to a feature, |
63 | 66 | existing tests will fail until they account for it. |
64 | 67 |
|
65 | | - * [**Swift Snapshot Testing**](https://github.com/pointfreeco/swift-snapshot-testing) provides |
66 | | - test helpers that can automatically record failures to disk, or inline into tests when possible. |
67 | | - These helpers are powered by Swift Issue Reporting and are automatically supported in both |
68 | | - Swift Testing and XCTest. |
| 68 | + * [**Swift Navigation**](https://github.com/pointfreeco/swiftui-navigation) provides concise |
| 69 | + domain modeling tools for UI frameworks including SwiftUI, UIKit, and more; and it uses Swift |
| 70 | + Issue Reporting to raise runtime warnings when APIs are used in unexpected ways. |
69 | 71 |
|
70 | | - * [**Swift Macro Testing**](https://github.com/pointfreeco/swift-macro-testing) builds upon |
71 | | - [Swift Snapshot Testing](https://github.com/pointfreeco/swift-snapshot-testing), but |
72 | | - specifically for macros. It uses the same issue reporting mechanism to provide test helpers to |
73 | | - both Swift Testing and XCTest. |
| 72 | + * [**The Composable Architecture**](https://github.com/pointfreeco/swift-composable-architecture) |
| 73 | + comes with powerful testing tools that support both Swift Testing and XCTest out of the box |
| 74 | + thanks to Swift Issue Reporting. In addition, the library is heavily instrumented with issue |
| 75 | + reporting to help developers catch bugs in their code early. |
74 | 76 |
|
75 | 77 | * [**Swift Custom Dump**](https://github.com/pointfreeco/swift-custom-dump) is an improved version |
76 | 78 | of Swift's `dump` function, and a whole lot more. It provides well-formatted dumps of data types |
|
0 commit comments