swift-testing-expert

Swift Testing

概述

使用此技能编写、审查、迁移和调试使用现代 Swift Testing API 的 Swift 测试。优先考虑可读性强的测试、稳健的并行执行、清晰的诊断以及在需要时从 XCTest 逐步迁移。

智能体行为契约（遵守以下规则）

1. 对于 Swift 单元测试和集成测试，优先使用 Swift Testing，但保留 XCTest 用于 UI 自动化（XCUIApplication）、性能指标（XCTMetric）以及仅 Objective-C 的测试代码。
2. 将 #expect 视为默认断言，当后续行依赖于某个前提值时使用 #require。
3. 默认提供并行安全的指导。如果测试未隔离，首先建议修复共享状态，然后再应用 .serialized。
4. 优先使用特质来表示行为和元数据（.enabled、.disabled、.timeLimit、.bug、标签），而不是命名约定或临时注释。
5. 当多个测试共享逻辑且仅输入值不同时，推荐使用参数化测试。
6. 对于操作系统版本限制的行为，在测试函数上使用 @available，而不是在测试体内部使用运行时 #available 检查；切勿在套件类型上标注 @available。
7. 保持迁移建议的渐进性：先转换断言，然后组织套件，最后引入参数化/特质。
8. 仅在测试目标中导入 Testing，绝不在应用/库/二进制目标中导入。

前 60 秒（分诊模板）

• 明确目标：新测试、迁移、不稳定失败、性能、CI 过滤或异步等待。
• 收集最少事实：
  • Xcode/Swift 版本和平台目标
  • 测试当前是否使用 XCTest、Swift Testing 或两者
  • 失败是确定性的还是不稳定的
  • 测试是否访问共享资源（数据库、文件、网络、全局状态）
• 快速分支：
  • 重复测试 -> 参数化测试
  • 嘈杂或不稳定的失败 -> 已知问题处理和测试隔离
  • 迁移问题 -> XCTest 映射和共存策略
  • 异步回调复杂性 -> continuation/await 模式

路由图（快速阅读正确的参考资料）

• 测试构建块和套件组织 -> references/fundamentals.md
• #expect、#require 和抛出期望 -> references/expectations.md
• 特质、标签和 Xcode 测试计划过滤 -> references/traits-and-tags.md
• 参数化测试设计和组合 -> references/parameterized-testing.md
• 默认并行执行、.serialized、隔离策略 -> references/parallelization-and-isolation.md
• 测试速度、确定性和防止不稳定 -> references/performance-and-best-practices.md
• 异步等待和回调桥接 -> references/async-testing-and-waiting.md
• XCTest 共存和迁移工作流 -> references/migration-from-xctest.md
• 测试导航器/报告工作流和诊断 -> references/xcode-workflows.md
• 索引和快速导航 -> references/_index.md

常见陷阱 -> 下一步最佳行动

• 重复的 testFooCaseA/testFooCaseB/... 方法 -> 替换为一个参数化的 @Test(arguments:)。
• 可选前提条件失败隐藏在后续断言中 -> try #require(...) 然后对解包后的值进行断言。
• 共享数据库上的不稳定集成测试 -> 隔离依赖或使用内存仓库；仅作为过渡步骤使用 .serialized。
• 被禁用且悄然腐烂的测试 -> 优先使用 withKnownIssue 处理临时已知失败以保留信号。
• 复杂类型的失败值不清晰 -> 使类型符合 CustomTestStringConvertible 以获得聚焦的测试诊断。
• 按名称包含/排除测试计划 -> 改用标签和基于标签的过滤器。

验证清单

• 确认每个测试具有单一清晰的行为，并在需要时具有表达性的显示名称。
• 确认前提条件使用 #require，以便失败时应停止测试。
• 确认重复逻辑已参数化而非重复。
• 确认测试是并行安全的，或者有理由地故意序列化。
• 确认异步代码已等待，并且回调 API 已安全桥接。
• 确认迁移将不支持的仅 XCTest 场景保留在 XCTest 上。

参考资料

• references/_index.md
• references/fundamentals.md
• references/expectations.md
• references/traits-and-tags.md
• references/parameterized-testing.md
• references/parallelization-and-isolation.md
• references/performance-and-best-practices.md
• references/async-testing-and-waiting.md
• references/migration-from-xctest.md
• references/xcode-workflows.md