{"id":15562988,"url":"https://github.com/barredewe/prefire","last_synced_at":"2025-05-16T11:07:05.434Z","repository":{"id":61753107,"uuid":"529987661","full_name":"BarredEwe/Prefire","owner":"BarredEwe","description":"🔥 A library based on Xcode Preview, for easy generation: Playbook view, Snapshot and Accessibility tests. SwiftUI and UIKit supported!","archived":false,"fork":false,"pushed_at":"2025-05-07T08:55:50.000Z","size":103205,"stargazers_count":344,"open_issues_count":11,"forks_count":24,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-09T16:42:22.188Z","etag":null,"topics":["accesibility-tests","component","ios","playbook","plugin","preview","screen","snapshot-testing","swift","swift-plugin","swiftui","swiftui-previews","swiftui-xcode-previews","testing","xcode","xcode-plugin","xcode-previews"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BarredEwe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2022-08-28T21:48:38.000Z","updated_at":"2025-05-09T12:48:57.000Z","dependencies_parsed_at":"2024-05-30T07:42:35.131Z","dependency_job_id":"fc8d703d-f86b-4134-a75a-649cd9f9e89c","html_url":"https://github.com/BarredEwe/Prefire","commit_stats":{"total_commits":185,"total_committers":12,"mean_commits":"15.416666666666666","dds":0.5405405405405406,"last_synced_commit":"309527e93af5a9635a26b6b3c465fd269d1e5310"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BarredEwe%2FPrefire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BarredEwe%2FPrefire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BarredEwe%2FPrefire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BarredEwe%2FPrefire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BarredEwe","download_url":"https://codeload.github.com/BarredEwe/Prefire/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254518378,"owners_count":22084374,"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":["accesibility-tests","component","ios","playbook","plugin","preview","screen","snapshot-testing","swift","swift-plugin","swiftui","swiftui-previews","swiftui-xcode-previews","testing","xcode","xcode-plugin","xcode-previews"],"created_at":"2024-10-02T16:17:02.285Z","updated_at":"2025-05-16T11:07:00.423Z","avatar_url":"https://github.com/BarredEwe.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Prefire](https://i.postimg.cc/Y9cbLVY4/temp-Image-P7o5-NQ.jpg)\n\n\u003cp align=\"center\"\u003eA library for easily generating automatic \u003cb\u003ePlaybook (Demo) view\u003c/b\u003e, \u003cb\u003eTests\u003c/b\u003e using \u003cb\u003ePreview\u003c/b\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003eWorks with: \u003cb\u003eUI-components, screens and flows\u003c/b\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/BarredEwe/Prefire/releases/latest\"\u003e\u003cimg alt=\"Release\" src=\"https://img.shields.io/github/release/BarredEwe/Prefire.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://developer.apple.com/\"\u003e\u003cimg alt=\"Platform\" src=\"https://img.shields.io/badge/platform-iOS-green.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://developer.apple.com/swift\"\u003e\u003cimg alt=\"Swift6\" src=\"https://img.shields.io/badge/language-Swift_6-green.svg\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://swift.org/package-manager\"\u003e\u003cimg alt=\"Swift Package Manager\" src=\"https://img.shields.io/badge/SwiftPM-compatible-yellowgreen.svg\"/\u003e\u003c/a\u003e\n\u003cimg alt=\"Swift Package Manager\" src=\"https://img.shields.io/badge/Xcode%20Plugins-Supported-brightgreen.svg\"/\u003e\n\u003c/p\u003e\n\nDo you like **SwiftUI Preview** and use it? Then you must try 🔥**Prefire**!\n\nYou can try 🔥**Prefire** starting from example project.\n\n## 🚀 Features\n\n\u003cimg src=\"https://i.ibb.co/LNYBfMw/ezgif-com-gif-maker-2.gif\" alt=\"Playbook\" width=\"200\" align=\"right\"\u003e\n\n- ✅ **Zero-Boilerplate Playbook** - Automatically generate interactive component catalogs\n- ✅ **Snapshot Testing** - Catch UI regressions with automatic test generation\n- ✅ **Smart Previews** - Enhance SwiftUI previews with states and user stories\n- ✅ **CI-Ready** - Seamless integration with GitHub Actions and other CI systems\n- ✅ **Xcode \u0026 CLI** - Choose your workflow: IDE integration or command line\n\n### Why Prefire? \n\n- 🔥 **Save Time** - Generate tests and documentation automatically\n- 🔥 **Stay Consistent** - Keep previews and tests always in sync\n- 🔥 **Improve Quality** - Catch visual regressions before users do\n- 🔥 **Boost Collaboration** - Share living documentation with your team\n\n\u003cbr clear=\"all\"\u003e\n\n---\n## ⚡ Quick Start\n\n### 1. Add Prefire to Your Project\n\n```swift\n// Package.swift\ndependencies: [\n    .package(url: \"https://github.com/BarredEwe/Prefire.git\", from: \"4.0.0\")\n],\n.testTarget(\n    plugins: [\n        // For Snapshot Tests\n        .plugin(name: \"PrefireTestsPlugin\", package: \"Prefire\")\n    ]\n)\n```\n\n### 2. Write `#Preview`\n```swift\n#Preview {\n    Button(\"Submit\")\n}\n```\n\n### 3. Run tests\n\nJust run generated tests 🚀\nAll tests will be generated in the DerivedData folder.\n\n\u003cimg src=\"https://i.postimg.cc/XNPVPL1G/Untitled-2.gif\" width=\"300\"\u003e\n\n---\n\n## 📦 Installation\n\n**Prefire** can be installed for an `Xcode Project` or only for one `Package` or `CLI` tool.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3 style=\"display:inline-block\"\u003eXcode Project Plugin\u003c/h3\u003e\u003c/summary\u003e\n\nYou can integrate Prefire as an Xcode Build Tool Plug-in if you're working\non a project in Xcode.\n\n1. Add `Prefire` as a package dependency to your project without linking any of the products.\n\n\u003cimg src=\"https://i.postimg.cc/nhWK6D17/Screenshot-2023-01-19-at-16-31-55.png\" width=\"800\"\u003e\n\n2. Select the target to which you want to add linting and open the `Build Phases` inspector.\nOpen `Run Build Tool Plug-ins` and select the `+` button.\nFrom the list, select `PrefirePlaybookPlugin` or `PrefireTestsPlugin`, and add it to the project.\n\n\u003cimg src=\"https://i.postimg.cc/VNnJNrX3/Screenshot-2023-01-19-at-16-43-44.png\" width=\"400\"\u003e\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3 style=\"display:inline-block\"\u003eSwift Package Plugin\u003c/h3\u003e\u003c/summary\u003e\n\nYou can integrate Prefire as a Swift Package Manager Plug-in if you're working with\na Swift Package with a `Package.swift` manifest.\n\n1. Add **Prefire** as a package dependency to your `Package.swift` file.\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/BarredEwe/Prefire\", from: \"4.0.0\")\n]\n```\n\n2. Add **Prefire** to a target using the `plugins` parameter.\n\n```swift\n.target(\n    plugins: [\n        // For Playbook (Demo) view\n        .plugin(name: \"PrefirePlaybookPlugin\", package: \"Prefire\")\n    ]\n),\n.testTarget(\n    plugins: [\n        // For Snapshot Tests\n        .plugin(name: \"PrefireTestsPlugin\", package: \"Prefire\")\n    ]\n)\n```\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3 style=\"display:inline-block\"\u003eCommand line interface (CLI)\u003c/h3\u003e\u003c/summary\u003e\n\nPrefire provides a command-line interface for generating snapshot tests from your previews.\n\n### Installation\nDownload Prefire from brew:\n```bash\nbrew tap barredewe/prefire\nbrew install prefire\n```\n\n### Basic Commands\n#### Generate Tests\nGenerate snapshot tests from your preview providers:\n```bash\nprefire tests\n```\n\u003e Tip: Use `prefire tests --help` for complete documentation\n\n#### Generate Playbook\nGenerate a playbook file documenting all your previews:\n\n```bash\nprefire playbook\n```\n\u003e Tip: Use `prefire playbook --help` for complete documentation\n\n\u003c/details\u003e\n\n---\n\n## 🛠 Advanced Usage\nTo generate **tests** and **playbook**, simply mark your preview using the `PrefireProvider` protocol:\n```swift\nstruct Text_Previews: PreviewProvider, PrefireProvider {\n    static var previews: some View { ... }\n}\n```\nIf you use the **`#Preview`** macro, **🔥Prefire** will automatically find it!\n\nIf you don't need it, mark view - `.prefireIgnored()`:\n```swift\n#Preview {\n    Text(\"\")\n        .prefireIgnored()\n}\n```\n\nIf you want to disable the automatic get of all previews, use the setting `preview_default_enabled`: false. Then to include preview in the test, you need to call the `.prefireEnabled()`:\n```swift\n#Preview {\n    Text(\"\")\n        .prefireEnabled()\n}\n```\n\n### **Playbook (Demo) View**\nTo use Playbook, simply use `PlaybookView`\n\n- If you want to see a list of all the Views, use `isComponent: true`\n- If you want to sort by UserStory, use `isComponent: false`\n\n```swift\nimport Prefire \n\nstruct ContentView: View {\n    var body: some View {\n        PlaybookView(isComponent: true, previewModels: PreviewModels.models)\n    }\n}\n```\n\n### **Snapshot tests**\n\nJust run generated tests 🚀\nAll tests will be generated in the DerivedData folder.\n\n\u003cimg src=\"https://i.postimg.cc/XNPVPL1G/Untitled-2.gif\" width=\"300\"\u003e\n\nPlugin `PrefireTestsPlugin` will handle everything for you 🛠️\n\nFor detailed instruction, check out [swift-snapshot-testing](https://github.com/pointfreeco/swift-snapshot-testing) or examine an example project.\n\n---\n\n## API\n**Prefire** provide new commands for previews:\n\n- You can set the delay, precision and perceptualPrecision parameters for the snapshot:\n\n    ```swift\n    .snapshot(delay: 0.3, precision: 0.95, perceptualPrecision: 0.98)\n    ```\n    \n    ```swift\n    static var previews: some View {\n        TestView()\n            .snapshot(delay: 0.3, precision: 0.95, perceptualPrecision: 0.98)\n    }\n    ```\n\n- Function for connecting preview together in one **Flow**:\n\n    \u003cimg src=\"https://i.postimg.cc/jSh23G8W/temp-Image9a-EDKU.avif\" width=\"350\" align=\"right\"\u003e\n\n    ```swift\n    .previewUserStory(.auth)\n    ```\n\n    ```swift\n    static var previews: some View {\n        PrefireView()\n            .previewUserStory(.auth)\n    }\n\n    static var previews: some View {\n        AuthView()\n            .previewUserStory(.auth)\n    }\n    ```\n\n    For example Authorization flow: `LoginView`, `OTPView` and `PincodeView`\n\n    \u003cbr clear=\"all\"\u003e\n\n- If a preview contains more than one `View`, you can mark `State` for these views.\n\n    \u003cimg src=\"https://i.postimg.cc/Z5JKNwTJ/temp-Imageh19pin.avif\" width=\"350\" align=\"right\"\u003e\n\n    ```swift\n    .previewState(.loading)\n    ```\n\n    ```swift\n    static var previews: some View {\n        TestView(\"Default\")\n\n        TestView(\"Loading\")\n            .previewState(.loading)\n    }\n    ```\n\n    \u003cbr clear=\"all\"\u003e\n\n---\n\n## ⚙ Configuration\n\nTo further customize **Prefire**, you can create a `.prefire.yml` file in the root directory of your project. Here's an example of its content:\n\n```yaml\ntest_configuration:\n  - target: PrefireExample \n  - test_file_path: PrefireExampleTests/PreviewTests.generated.swift\n  - template_file_path: CustomPreviewTests.stencil\n  - simulator_device: \"iPhone15,2\"\n  - required_os: 16\n  - preview_default_enabled: true\n  - sources:\n    - ${PROJECT_DIR}/Sources/\n  - snapshot_devices:\n  \t- iPhone 14\n  \t- iPad\n  - imports:\n    - UIKit\n    - SwiftUI\n  - testable_imports:\n    - Prefire\n\nplaybook_configuration:\n  - preview_default_enabled: true\n  - template_file_path: CustomModels.stencil\n  - imports:\n    - UIKit\n    - Foundation\n  - testable_imports:\n    - SwiftUI\n```\n### Configuration keys and their descriptions\n- `target` - Your project Target for Snapshot tests. __Default__: _FirstTarget_\n- `test_file_path` - Filepath to generated file. __Default__: _DerivedData_\n- `template_file_path` - Stencil file for generated file. Optional parameter.\\\n   For test plugin __Default__: _Templates/PreviewTests.stencil_ from the package.\\\n   For playbook plugin __Default__: _Templates/PreviewModels.stencil_ from the package\n- `simulator_device` - Device for Snapshot testing. Optional parameter.\n- `required_os` - iOS version for Snapshot testing. Optional parameter.\n- `snapshot_devices` - the list of devices snapshots should be generated for. The `simulator_device` specified above will still be required and used, but snapshotting will take on the traits of the `snapshot_devices`. The `displayScale` will default to `2.0` and device specific safe areas will be `.zero`. Optional parameter.\n- `preview_default_enabled` - Do I need to automatically add all previews based on the new syntax to the tests.  __Default__: true\n- `imports` - Additional imports for the generated Playbook/Tests. Optional parameter.\n- `testable_imports` - Additional `@testable` imports for the generated Playbook/Tests. Optional parameter.\n- `sources` - Paths to swift file or directory sources. __Default__: File paths of a specific target or project\n\n## Distribution\n\nWhen preparing for distribution, you may want to exclude your `PreviewProvider` and mock data from release builds. This can be achieved by wrapping them in `#if DEBUG` compiler directives. Alternatively, you can pass a compiler flag to exclude `PreviewModels` from release builds.\n\nTo exclude `PreviewModels` using Swift Package Manager, pass the `PLAYBOOK_DISABLED` swift setting in the package that links `PrefirePlaybookPlugin`:\n\n```swift\nswiftSettings: [\n    .define(\"PLAYBOOK_DISABLED\", .when(configuration: .release)),\n]\n```\n\nIf you are using Xcode, you can pass the compiler flag in the Xcode build settings:\n\n```\nSWIFT_ACTIVE_COMPILATION_CONDITIONS = PLAYBOOK_DISABLED;\n```\n\n## Requirements\n\n- Swift 5.6 or higher\n- Xcode 14.0 or higher\n- iOS 14 or higher\n\n## Troubleshooting\n`NavigationView` in Preview not supported for Playbook\n- Consider using other views or layouts for your Playbook needs.\n\nRunning Prefire via CI\n- To run Prefire via Continuous Integration (CI), you need to configure permissions:\n`defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES`\n\nXcode is unable to generate tests in a custom path.\n- To resolve this, you’ll need to disable the sandbox for file generation by running the following command in your terminal:\n`defaults write com.apple.dt.Xcode IDEPackageSupportDisablePluginExecutionSandbox -bool YES`\n\n## 🤝 Contributing\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch\n3. Submit a Pull Request\n\n## 📄 License\nPrefire is released under the Apache License 2.0. See [LICENSE](https://github.com/BarredEwe/Prefire/blob/main/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarredewe%2Fprefire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbarredewe%2Fprefire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbarredewe%2Fprefire/lists"}