https://github.com/BarredEwe/Prefire
🔥 A library based on SwiftUI Preview, for easy generation: Playbook view, Snapshot and Accessibility tests
https://github.com/BarredEwe/Prefire
accesibility-tests component ios playbook plugin preview screen snapshot-testing swift swift-plugin swiftui swiftui-previews swiftui-xcode-previews testing xcode-plugin xcode-previews
Last synced: 10 days ago
JSON representation
🔥 A library based on SwiftUI Preview, for easy generation: Playbook view, Snapshot and Accessibility tests
- Host: GitHub
- URL: https://github.com/BarredEwe/Prefire
- Owner: BarredEwe
- License: apache-2.0
- Created: 2022-08-28T21:48:38.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-24T08:26:01.000Z (7 months ago)
- Last Synced: 2024-10-30T04:50:23.950Z (7 months ago)
- Topics: accesibility-tests, component, ios, playbook, plugin, preview, screen, snapshot-testing, swift, swift-plugin, swiftui, swiftui-previews, swiftui-xcode-previews, testing, xcode-plugin, xcode-previews
- Language: Swift
- Homepage:
- Size: 89.4 MB
- Stars: 290
- Watchers: 2
- Forks: 18
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
A library for easily generating automatic Playbook (Demo) view, Tests using Preview
Works with: UI-components, screens and flows
Do you like **SwiftUI Preview** and use it? Then you must try 🔥**Prefire**!
You can try 🔥**Prefire** starting from example project.
## 🚀 Features
- ✅ **Zero-Boilerplate Playbook** - Automatically generate interactive component catalogs
- ✅ **Snapshot Testing** - Catch UI regressions with automatic test generation
- ✅ **Smart Previews** - Enhance SwiftUI previews with states and user stories
- ✅ **CI-Ready** - Seamless integration with GitHub Actions and other CI systems
- ✅ **Xcode & CLI** - Choose your workflow: IDE integration or command line
### Why Prefire?
- 🔥 **Save Time** - Generate tests and documentation automatically
- 🔥 **Stay Consistent** - Keep previews and tests always in sync
- 🔥 **Improve Quality** - Catch visual regressions before users do
- 🔥 **Boost Collaboration** - Share living documentation with your team
---
## ⚡ Quick Start
### 1. Add Prefire to Your Project
```swift
// Package.swift
dependencies: [
.package(url: "https://github.com/BarredEwe/Prefire.git", from: "4.0.0")
],
.testTarget(
plugins: [
// For Snapshot Tests
.plugin(name: "PrefireTestsPlugin", package: "Prefire")
]
)
```
### 2. Write `#Preview`
```swift
#Preview {
Button("Submit")
}
```
### 3. Run tests
Just run generated tests 🚀
All tests will be generated in the DerivedData folder.
---
## 📦 Installation
**Prefire** can be installed for an `Xcode Project` or only for one `Package` or `CLI` tool.
Xcode Project Plugin
You can integrate Prefire as an Xcode Build Tool Plug-in if you're working
on a project in Xcode.
1. Add `Prefire` as a package dependency to your project without linking any of the products.
2. Select the target to which you want to add linting and open the `Build Phases` inspector.
Open `Run Build Tool Plug-ins` and select the `+` button.
From the list, select `PrefirePlaybookPlugin` or `PrefireTestsPlugin`, and add it to the project.
Swift Package Plugin
You can integrate Prefire as a Swift Package Manager Plug-in if you're working with
a Swift Package with a `Package.swift` manifest.
1. Add **Prefire** as a package dependency to your `Package.swift` file.
```swift
dependencies: [
.package(url: "https://github.com/BarredEwe/Prefire", from: "4.0.0")
]
```
2. Add **Prefire** to a target using the `plugins` parameter.
```swift
.target(
plugins: [
// For Playbook (Demo) view
.plugin(name: "PrefirePlaybookPlugin", package: "Prefire")
]
),
.testTarget(
plugins: [
// For Snapshot Tests
.plugin(name: "PrefireTestsPlugin", package: "Prefire")
]
)
```
Command line interface (CLI)
Prefire provides a command-line interface for generating snapshot tests from your previews.
### Installation
Download Prefire from brew:
```bash
brew tap barredewe/prefire
brew install prefire
```
### Basic Commands
#### Generate Tests
Generate snapshot tests from your preview providers:
```bash
prefire tests
```
> Tip: Use `prefire tests --help` for complete documentation
#### Generate Playbook
Generate a playbook file documenting all your previews:
```bash
prefire playbook
```
> Tip: Use `prefire playbook --help` for complete documentation
---
## 🛠 Advanced Usage
To generate **tests** and **playbook**, simply mark your preview using the `PrefireProvider` protocol:
```swift
struct Text_Previews: PreviewProvider, PrefireProvider {
static var previews: some View { ... }
}
```
If you use the **`#Preview`** macro, **🔥Prefire** will automatically find it!
If you don't need it, mark view - `.prefireIgnored()`:
```swift
#Preview {
Text("")
.prefireIgnored()
}
```
If 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()`:
```swift
#Preview {
Text("")
.prefireEnabled()
}
```
### **Playbook (Demo) View**
To use Playbook, simply use `PlaybookView`
- If you want to see a list of all the Views, use `isComponent: true`
- If you want to sort by UserStory, use `isComponent: false`
```swift
import Prefire
struct ContentView: View {
var body: some View {
PlaybookView(isComponent: true, previewModels: PreviewModels.models)
}
}
```
### **Snapshot tests**
Just run generated tests 🚀
All tests will be generated in the DerivedData folder.
Plugin `PrefireTestsPlugin` will handle everything for you 🛠️
For detailed instruction, check out [swift-snapshot-testing](https://github.com/pointfreeco/swift-snapshot-testing) or examine an example project.
---
## API
**Prefire** provide new commands for previews:
- You can set the delay, precision and perceptualPrecision parameters for the snapshot:
```swift
.snapshot(delay: 0.3, precision: 0.95, perceptualPrecision: 0.98)
```
```swift
static var previews: some View {
TestView()
.snapshot(delay: 0.3, precision: 0.95, perceptualPrecision: 0.98)
}
```
- Function for connecting preview together in one **Flow**:
```swift
.previewUserStory(.auth)
```
```swift
static var previews: some View {
PrefireView()
.previewUserStory(.auth)
}
static var previews: some View {
AuthView()
.previewUserStory(.auth)
}
```
For example Authorization flow: `LoginView`, `OTPView` and `PincodeView`
- If a preview contains more than one `View`, you can mark `State` for these views.
```swift
.previewState(.loading)
```
```swift
static var previews: some View {
TestView("Default")
TestView("Loading")
.previewState(.loading)
}
```
---
## ⚙ Configuration
To further customize **Prefire**, you can create a `.prefire.yml` file in the root directory of your project. Here's an example of its content:
```yaml
test_configuration:
- target: PrefireExample
- test_target_path: ${PROJECT_DIR}/Tests
- test_file_path: PrefireExampleTests/PreviewTests.generated.swift
- template_file_path: CustomPreviewTests.stencil
- simulator_device: "iPhone15,2"
- required_os: 16
- preview_default_enabled: true
- sources:
- ${PROJECT_DIR}/Sources/
- snapshot_devices:
- iPhone 14
- iPad
- imports:
- UIKit
- SwiftUI
- testable_imports:
- Prefire
playbook_configuration:
- preview_default_enabled: true
- template_file_path: CustomModels.stencil
- imports:
- UIKit
- Foundation
- testable_imports:
- SwiftUI
```
### Configuration keys and their descriptions
- `target` - Your project Target for Snapshot tests. __Default__: _FirstTarget_
- `test_target_path` — The path to the test directory. Generates snapshots will be placed into its `__Snapshots__` subdirectory. __Default__: The same as the test target name.
- `test_file_path` - Filepath to generated file. __Default__: _DerivedData_
- `template_file_path` - Stencil file for generated file, relative to `test_target_path`. Optional parameter.\
For test plugin __Default__: _Templates/PreviewTests.stencil_ from the package.\
For playbook plugin __Default__: _Templates/PreviewModels.stencil_ from the package
- `simulator_device` - Device for Snapshot testing. Optional parameter.
- `required_os` - iOS version for Snapshot testing. Optional parameter.
- `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.
- `preview_default_enabled` - Do I need to automatically add all previews based on the new syntax to the tests. __Default__: true
- `imports` - Additional imports for the generated Playbook/Tests. Optional parameter.
- `testable_imports` - Additional `@testable` imports for the generated Playbook/Tests. Optional parameter.
- `sources` - Paths to swift file or directory sources. __Default__: File paths of a specific target or project
## Distribution
When 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.
To exclude `PreviewModels` using Swift Package Manager, pass the `PLAYBOOK_DISABLED` swift setting in the package that links `PrefirePlaybookPlugin`:
```swift
swiftSettings: [
.define("PLAYBOOK_DISABLED", .when(configuration: .release)),
]
```
If you are using Xcode, you can pass the compiler flag in the Xcode build settings:
```
SWIFT_ACTIVE_COMPILATION_CONDITIONS = PLAYBOOK_DISABLED;
```
## Requirements
- Swift 5.6 or higher
- Xcode 14.0 or higher
- iOS 14 or higher
## Troubleshooting
`NavigationView` in Preview not supported for Playbook
- Consider using other views or layouts for your Playbook needs.
Running Prefire via CI
- To run Prefire via Continuous Integration (CI), you need to configure permissions:
`defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES`
Xcode is unable to generate tests in a custom path.
- To resolve this, you’ll need to disable the sandbox for file generation by running the following command in your terminal:
`defaults write com.apple.dt.Xcode IDEPackageSupportDisablePluginExecutionSandbox -bool YES`
## 🤝 Contributing
We welcome contributions! Please follow these steps:
1. Fork the repository
2. Create a feature branch
3. Submit a Pull Request
## 📄 License
Prefire is released under the Apache License 2.0. See [LICENSE](https://github.com/BarredEwe/Prefire/blob/main/LICENSE) for details.