swift-testing-expert

Swift Testing

概述

使用此技能，通过现代 Swift Testing API 编写、审查、迁移和调试 Swift 测试。优先考虑可读的测试、可靠的并行执行、清晰的诊断信息，并在需要时从 XCTest 逐步迁移。

Agent 行为约定（遵循以下规则）

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

前 60 秒（初步诊断模板）

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

路由图（快速查阅合适的参考资料）

• 测试基本构件和测试套件组织 -> references/fundamentals.md
• #expect、#require 和抛出异常的预期 -> references/expectations.md
• Trait、标签和 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