{"id":18818055,"url":"https://github.com/pointfreeco/swift-issue-reporting","last_synced_at":"2026-01-06T23:21:59.962Z","repository":{"id":41109376,"uuid":"348731867","full_name":"pointfreeco/swift-issue-reporting","owner":"pointfreeco","description":"Report issues in your application and library code as Xcode runtime warnings, breakpoints, assertions, and do so in a testable manner.","archived":false,"fork":false,"pushed_at":"2025-03-31T16:46:23.000Z","size":2319,"stargazers_count":440,"open_issues_count":6,"forks_count":72,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-31T21:45:57.545Z","etag":null,"topics":["swift-testing","xcode","xctest"],"latest_commit_sha":null,"homepage":"https://www.pointfree.co","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pointfreeco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-17T14:04:37.000Z","updated_at":"2025-03-28T04:56:28.000Z","dependencies_parsed_at":"2023-02-09T04:00:58.614Z","dependency_job_id":"9de637b1-b081-4202-b0b2-5a4cb8132d9c","html_url":"https://github.com/pointfreeco/swift-issue-reporting","commit_stats":{"total_commits":115,"total_committers":21,"mean_commits":5.476190476190476,"dds":"0.33913043478260874","last_synced_commit":"a3f634d1a409c7979cabc0a71b3f26ffa9fc8af1"},"previous_names":["pointfreeco/swift-issue-reporting","pointfreeco/xctest-dynamic-overlay"],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pointfreeco%2Fswift-issue-reporting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pointfreeco%2Fswift-issue-reporting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pointfreeco%2Fswift-issue-reporting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pointfreeco%2Fswift-issue-reporting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pointfreeco","download_url":"https://codeload.github.com/pointfreeco/swift-issue-reporting/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247737769,"owners_count":20987718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["swift-testing","xcode","xctest"],"created_at":"2024-11-08T00:14:43.850Z","updated_at":"2025-12-11T23:02:54.209Z","avatar_url":"https://github.com/pointfreeco.png","language":"Swift","funding_links":[],"categories":["Swift"],"sub_categories":[],"readme":"# Swift Issue Reporting\n\n[![CI](https://github.com/pointfreeco/xctest-dynamic-overlay/actions/workflows/ci.yml/badge.svg)](https://github.com/pointfreeco/swift-issue-reporting/actions/workflows/ci.yml)\n[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fpointfreeco%2Fswift-issue-reporting%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/pointfreeco/swift-issue-reporting)\n[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fpointfreeco%2Fswift-issue-reporting%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/pointfreeco/swift-issue-reporting)\n\nReport issues in your application and library code as Xcode runtime warnings, breakpoints, \nassertions, and do so in a testable manner.\n\n## Overview\n\n\u003e [!Important]\n\u003e Issue Reporting is an evolution of our previous library, XCTestDynamicOverlay. As such,\n\u003e to use this library you must depend on the old repository URL:\n\u003e\n\u003e ```\n\u003e https://github.com/pointfreeco/xctest-dynamic-overlay\n\u003e ```\n\nThis library provides robust tools for reporting issues in your application with a customizable\ndegree of granularity and severity. In its most basic form you use the `reportIssue` function\nanywhere in your application to flag an issue in your code, such as a code path that you think\nshould never be executed:\n\n```swift\nguard let lastItem = items.last\nelse {\n  reportIssue(\"'items' should never be empty.\")\n  return \n}\n…\n```\n\nBy default, this will trigger an unobtrusive, purple runtime warning when running your app in Xcode\n(simulator and device):\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"Sources/IssueReporting/Documentation.docc/Resources/runtime-warning~dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"Sources/IssueReporting/Documentation.docc/Resources/runtime-warning.png\"\u003e\n  \u003cimg alt=\"A purple runtime warning in Xcode showing that an issue has been reported.\" src=\"Sources/IssueReporting/Documentation.docc/Resources/runtime-warning.png\"\u003e\n\u003c/picture\u003e\n\nThis provides a very visual way of seeing when an issue has occurred in your application without\nstopping the app's execution or interrupting your workflow.\n\nThe `reportIssue` tool can also be customized to allow for other ways of reporting issues. It can be\nconfigured to trigger a breakpoint if you want to do some debugging when an issue is reported, or a\nprecondition or fatal error if you want to truly stop execution. And you can create your own custom\nissue reporter to send issues to OSLog or an external server. \n\nFurther, when running your code in a testing context (both Swift's native Testing framework as well\nas XCTest), all reported issues become _test failures_. This helps you get test coverage that\nproblematic code paths are not executed, and makes it possible to build testing tools for libraries\nthat ship in the same target as the library itself.\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"Sources/IssueReporting/Documentation.docc/Resources/test-failure~dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"Sources/IssueReporting/Documentation.docc/Resources/test-failure.png\"\u003e\n  \u003cimg alt=\"A test failure in Xcode where an issue has been reported.\" src=\"Sources/IssueReporting/Documentation.docc/Resources/test-failure.png\"\u003e\n\u003c/picture\u003e\n\nIssue Reporting comes with a number of reporters, custom reporting functionality, and more. To learn\nabout these features, see\n[Getting started](Sources/IssueReporting/Documentation.docc/Articles/GettingStarted.md).\n\n## Case studies\n\nThere are many popular libraries out there using Issue Reporting. To name a few:\n\n  * [**Perception**](https://github.com/pointfreeco/swift-perception) is a back-port of Swift's\n    Observation framework that can be deployed all the way back to the iOS 13 generation of devices,\n    but requires a special SwiftUI view to observe changes to objects annotated with the macro. When\n    the library detects this view is missing, it uses Issue Reporting to warn developers with a\n    trace pointing to the view.\n\n  * [**Dependencies**](https://github.com/pointfreeco/swift-dependencies) is a general purpose\n    dependency injection library inspired by SwiftUI's environment. It uses Swift Issue Reporting to\n    notify users when they access dependencies without overridding them. This results in runtime\n    warnings when running in the simulator, and test failures when testing. It forces each test\n    to explicitly declare its dependencies, and when a new dependency is introduced to a feature,\n    existing tests will fail until they account for it.\n\n  * [**Swift Navigation**](https://github.com/pointfreeco/swift-navigation) provides concise\n    domain modeling tools for UI frameworks including SwiftUI, UIKit, and more; and it uses Swift\n    Issue Reporting to raise runtime warnings when APIs are used in unexpected ways.\n\n  * [**The Composable Architecture**](https://github.com/pointfreeco/swift-composable-architecture)\n    comes with powerful testing tools that support both Swift Testing and XCTest out of the box\n    thanks to Swift Issue Reporting. In addition, the library is heavily instrumented with issue\n    reporting to help developers catch bugs in their code early.\n\n  * [**Custom Dump**](https://github.com/pointfreeco/swift-custom-dump) is an improved version of\n    Swift's `dump` function, and a whole lot more. It provides well-formatted dumps of data types\n    that read like Swift code, as well as well-formatted diffs when data types are compared. It also\n    ships several test helpers powered by Swift Issue Reporting, including drop-in replacements for\n    `#expect(_ == _)` and `XCTAssertEqual` that render failures as concise diffs, as well as helpers\n    that allow you to assert against changes to data structures over time.\n\n  * [**Swift Clocks**](https://github.com/pointfreeco/swift-clocks) and\n    [**Combine Schedulers**](https://github.com/pointfreeco/combine-schedulers) are sibling packages\n    that use issue reporting to drive their \"test\" and \"unimplemented\" clocks and schedulers. \"Test\" \n    clocks/schedulers allow you to _control time_ in tests, and will emit failures when expectations\n    aren't met. \"Unimplemented\" clocks/schedulers record unexpected usage as issues.\n\nHave another case study to share? [Let us know!](edit/main/README.md)\n\n## Documentation \n\nFull documentation can be found\n[here](https://swiftpackageindex.com/pointfreeco/swift-issue-reporting/main/documentation).\n\n## License\n\nThis library is released under the MIT license. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpointfreeco%2Fswift-issue-reporting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpointfreeco%2Fswift-issue-reporting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpointfreeco%2Fswift-issue-reporting/lists"}