一个用于轻松生成自动化的 Playbook（演示）视图、使用预览生成测试的库

适用于：UI 组件、屏幕和流程

Prefire

您喜欢 SwiftUI Preview 并使用它吗？那么您一定要试试 🔥Prefire！

您可以从示例项目开始尝试 🔥Prefire。

🚀 特性

✅ 零样板 Playbook - 自动生成交互式组件目录
✅ 快照测试 - 通过自动测试生成捕获 UI 回归
✅ 智能预览 - 使用状态和用户故事增强 SwiftUI 预览
✅ CI 就绪 - 与 GitHub Actions 和其他 CI 系统无缝集成
✅ Xcode & CLI - 选择您的工作流程：IDE 集成或命令行

为什么选择 Prefire？

🔥 节省时间 - 自动生成测试和文档
🔥 保持一致 - 保持预览和测试始终同步
🔥 提高质量 - 在用户发现之前捕获视觉回归
🔥 促进协作 - 与您的团队共享实时文档

⚡ 快速开始

1. 将 Prefire 添加到您的项目

// 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. 编写 `#Preview`

#Preview {
    Button("Submit")
}

3. 运行测试

只需运行生成的测试即可 🚀 所有测试将在 DerivedData 文件夹中生成。

📦 安装

可以为 Xcode Project 或仅为一个 Package 或 CLI 工具安装 Prefire。

Xcode 项目插件

如果您正在 Xcode 中处理项目，则可以将 Prefire 作为 Xcode 构建工具插件集成。

将 Prefire 作为包依赖项添加到您的项目，无需链接任何产品。

选择要添加 linting 的目标，然后打开 Build Phases 检查器。打开 Run Build Tool Plug-ins 并选择 + 按钮。从列表中，选择 PrefirePlaybookPlugin 或 PrefireTestsPlugin，并将其添加到项目中。

Swift 包插件

如果您正在使用带有 Package.swift 清单的 Swift 包，则可以将 Prefire 作为 Swift Package Manager 插件集成。

将 Prefire 作为包依赖项添加到您的 Package.swift 文件。

dependencies: [
    .package(url: "https://github.com/BarredEwe/Prefire", from: "4.0.0")
]

使用 plugins 参数将 Prefire 添加到目标。

.target(
    plugins: [
        // For Playbook (Demo) view
        .plugin(name: "PrefirePlaybookPlugin", package: "Prefire")
    ]
),
.testTarget(
    plugins: [
        // For Snapshot Tests
        .plugin(name: "PrefireTestsPlugin", package: "Prefire")
    ]
)

命令行界面 (CLI)

Prefire 提供了一个命令行界面，用于从您的预览生成快照测试。

安装

从 brew 下载 Prefire

brew tap barredewe/prefire
brew install prefire

基本命令

生成测试

从您的预览提供程序生成快照测试

prefire tests

提示：使用 prefire tests --help 获取完整文档

生成 Playbook

生成一个 playbook 文件，记录您的所有预览

prefire playbook

提示：使用 prefire playbook --help 获取完整文档

🛠 高级用法

要生成测试和 playbook，只需使用 PrefireProvider 协议标记您的预览

struct Text_Previews: PreviewProvider, PrefireProvider {
    static var previews: some View { ... }
}

如果您使用 #Preview 宏，🔥Prefire 将自动找到它！

如果您不需要它，请标记视图 - .prefireIgnored()

#Preview {
    Text("")
        .prefireIgnored()
}

如果您想禁用自动获取所有预览，请使用设置 preview_default_enabled: false。然后，要将预览包含在测试中，您需要调用 .prefireEnabled()

#Preview {
    Text("")
        .prefireEnabled()
}

Playbook (演示) 视图

要使用 Playbook，只需使用 PlaybookView

如果您想查看所有视图的列表，请使用 isComponent: true
如果您想按 UserStory 排序，请使用 isComponent: false

import Prefire 

struct ContentView: View {
    var body: some View {
        PlaybookView(isComponent: true, previewModels: PreviewModels.models)
    }
}

快照测试

只需运行生成的测试即可 🚀 所有测试将在 DerivedData 文件夹中生成。

插件 PrefireTestsPlugin 将为您处理一切 🛠️

有关详细说明，请查看 swift-snapshot-testing 或检查示例项目。

API

Prefire 为预览提供新命令

您可以为快照设置 delay、precision 和 perceptualPrecision 参数

.snapshot(delay: 0.3, precision: 0.95, perceptualPrecision: 0.98)

static var previews: some View {
    TestView()
        .snapshot(delay: 0.3, precision: 0.95, perceptualPrecision: 0.98)
}

用于将预览连接在一起以形成一个 Flow 的函数

.previewUserStory(.auth)

static var previews: some View {
    PrefireView()
        .previewUserStory(.auth)
}

static var previews: some View {
    AuthView()
        .previewUserStory(.auth)
}

例如，授权流程：LoginView、OTPView 和 PincodeView

如果预览包含多个 View，您可以为这些视图标记 State。

.previewState(.loading)

static var previews: some View {
    TestView("Default")

    TestView("Loading")
        .previewState(.loading)
}

⚙ 配置

要进一步自定义 Prefire，您可以在项目的根目录中创建一个 .prefire.yml 文件。这是一个示例内容

test_configuration:
  - target: PrefireExample 
  - 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

配置键及其描述

target - 快照测试的项目目标。默认：FirstTarget
test_file_path - 生成文件的文件路径。默认：DerivedData
template_file_path - 生成文件的 Stencil 文件。可选参数。
对于测试插件默认：来自包的Templates/PreviewTests.stencil。
对于 playbook 插件默认：来自包的Templates/PreviewModels.stencil。
simulator_device - 用于快照测试的设备。可选参数。
required_os - 快照测试的 iOS 版本。可选参数。
snapshot_devices - 应该为其生成快照的设备列表。上面指定的 simulator_device 仍然是必需的并且会被使用，但是快照将会具有 snapshot_devices 的特征。 displayScale 将默认为 2.0 并且特定于设备的安全区域将为 .zero。可选参数。
preview_default_enabled - 我是否需要自动将所有基于新语法的预览添加到测试中。默认：true
imports - 为生成的 Playbook/测试添加额外的导入。可选参数。
testable_imports - 为生成的 Playbook/测试添加额外的 @testable 导入。可选参数。
sources - Swift 文件或目录源的路径。默认：特定目标或项目的文件路径

发布

在准备发布时，您可能想要从发布版本中排除您的 PreviewProvider 和模拟数据。这可以通过将它们包装在 #if DEBUG 编译器指令中来实现。或者，您可以传递一个编译器标志以从发布版本中排除 PreviewModels。

要使用 Swift Package Manager 排除 PreviewModels，请在链接 PrefirePlaybookPlugin 的包中传递 PLAYBOOK_DISABLED swift 设置

swiftSettings: [
    .define("PLAYBOOK_DISABLED", .when(configuration: .release)),
]

如果您正在使用 Xcode，则可以在 Xcode 构建设置中传递编译器标志

SWIFT_ACTIVE_COMPILATION_CONDITIONS = PLAYBOOK_DISABLED;

要求

Swift 5.6 或更高版本
Xcode 14.0 或更高版本
iOS 14 或更高版本

问题排查

Playbook 不支持 Preview 中的 NavigationView

请考虑使用其他视图或布局来满足您的 Playbook 需求。

通过 CI 运行 Prefire

要通过持续集成 (CI) 运行 Prefire，您需要配置权限：defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES

Xcode 无法在自定义路径中生成测试。

要解决此问题，您需要通过在您的终端中运行以下命令来禁用文件生成的沙盒：defaults write com.apple.dt.Xcode IDEPackageSupportDisablePluginExecutionSandbox -bool YES

🤝 贡献

我们欢迎贡献！请按照以下步骤

Fork 存储库
创建一个功能分支
提交一个 Pull Request

📄 许可证

Prefire 在 MIT 许可证下发布。有关详细信息，请参阅 LICENSE。