swift-testing-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swift Testing

Overview

概述

Use this skill to write, review, migrate, and debug Swift tests with modern Swift Testing APIs. Prioritize readable tests, robust parallel execution, clear diagnostics, and incremental migration from XCTest where needed.

使用本技能，借助现代Swift Testing API编写、评审、迁移和调试Swift测试。优先保证测试的可读性、稳健的并行执行、清晰的诊断信息，并在需要时逐步从XCTest迁移。

Agent behavior contract (follow these rules)

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

Prefer Swift Testing for Swift unit and integration tests, but keep XCTest for UI automation (
```
XCUIApplication
```
), performance metrics (
```
XCTMetric
```
), and Objective-C-only test code.
Treat
```
#expect
```
as the default assertion and use
```
#require
```
when subsequent lines depend on a prerequisite value.
Default to parallel-safe guidance. If tests are not isolated, first propose fixing shared state before applying
```
.serialized
```
.
Prefer traits for behavior and metadata (
```
.enabled
```
,
```
.disabled
```
,
```
.timeLimit
```
,
```
.bug
```
, tags) over naming conventions or ad-hoc comments.
Recommend parameterized tests when multiple tests share logic and differ only in input values.
Use
```
@available
```
on test functions for OS-gated behavior instead of runtime
```
#available
```
checks inside test bodies; never annotate suite types with
```
@available
```
.
Keep migration advice incremental: convert assertions first, then organize suites, then introduce parameterization/traits.
Only import
```
Testing
```
in test targets, never in app/library/binary targets.

优先使用Swift Testing进行Swift单元测试和集成测试，但UI自动化（
```
XCUIApplication
```
）、性能指标（
```
XCTMetric
```
）以及仅支持Objective-C的测试代码仍保留使用XCTest。
将
```
#expect
```
作为默认断言，当后续代码依赖某个前置条件的值时，使用
```
#require
```
。
默认提供并行安全的指导建议。如果测试未实现隔离，首先建议修复共享状态，再考虑应用
```
.serialized
```
。
优先使用特性来定义行为和元数据（
```
.enabled
```
、
```
.disabled
```
、
```
.timeLimit
```
、
```
.bug
```
、标签），而非命名约定或临时注释。
当多个测试共享逻辑，仅输入值不同时，推荐使用参数化测试。
针对系统版本限制的行为，在测试函数上使用
```
@available
```
，而非在测试代码块内使用运行时
```
#available
```
检查；切勿为测试套件类型添加
```
@available
```
注解。
迁移建议保持渐进式：先转换断言，再整理测试套件，最后引入参数化/特性。
仅在测试目标中导入
```
Testing
```
，切勿在应用/库/二进制目标中导入。

First 60 seconds (triage template)

前60秒（分类模板）

Clarify the goal: new tests, migration, flaky failures, performance, CI filtering, or async waiting.
Collect minimal facts:
- Xcode/Swift version and platform targets
- Whether tests currently use XCTest, Swift Testing, or both
- Whether failures are deterministic or flaky
- Whether tests access shared resources (database, files, network, global state)
Branch quickly:
- repetitive tests -> parameterized tests
- noisy or flaky failures -> known issue handling and test isolation
- migration questions -> XCTest mapping and coexistence strategy
- async callback complexity -> continuation/await patterns

明确目标：编写新测试、迁移、不稳定失败排查、性能优化、CI过滤或异步等待处理。
收集关键信息：
- Xcode/Swift版本及平台目标
- 当前测试使用XCTest、Swift Testing还是两者混用
- 失败是确定性的还是不稳定的
- 测试是否访问共享资源（数据库、文件、网络、全局状态）
快速分支处理：
- 重复测试 -> 参数化测试
- 噪声或不稳定失败 -> 已知问题处理与测试隔离
- 迁移问题 -> XCTest映射与共存策略
- 异步回调复杂度 -> 延续/await模式

Routing map (read the right reference fast)

路由图（快速找到正确参考）

Test building blocks and suite organization ->
```
references/fundamentals.md
```

#expect

#require

, and throw expectations ->

references/expectations.md

Traits, tags, and Xcode test-plan filtering ->
```
references/traits-and-tags.md
```
Parameterized test design and combinatorics ->
```
references/parameterized-testing.md
```

Default parallel execution,

.serialized

, isolation strategy ->

references/parallelization-and-isolation.md

Test speed, determinism, and flakiness prevention ->
```
references/performance-and-best-practices.md
```
Async waiting and callback bridging ->
```
references/async-testing-and-waiting.md
```
XCTest coexistence and migration workflow ->
```
references/migration-from-xctest.md
```
Test navigator/report workflows and diagnostics ->
```
references/xcode-workflows.md
```
Index and quick navigation ->
```
references/_index.md
```

测试构建模块与套件组织 ->
```
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
```

Common pitfalls -> next best move

常见陷阱与应对方案

Repetitive
```
testFooCaseA/testFooCaseB/...
```
methods -> replace with one parameterized
```
@Test(arguments:)
```
.
Failing optional preconditions hidden in later assertions ->
```
try #require(...)
```
then assert on unwrapped value.
Flaky integration tests on shared database -> isolate dependencies or in-memory repositories; use
```
.serialized
```
only as a transition step.
Disabled tests that silently rot -> prefer
```
withKnownIssue
```
for temporary known failures to preserve signal.
Unclear failure values for complex types -> conform type to
```
CustomTestStringConvertible
```
for focused test diagnostics.
Test-plan include/exclude by names -> use tags and tag-based filters instead.

重复的
```
testFooCaseA/testFooCaseB/...
```
方法 -> 替换为单个参数化的
```
@Test(arguments:)
```
。
可选前置条件失败隐藏在后续断言中 -> 使用
```
try #require(...)
```
，然后对解包后的值进行断言。
共享数据库上的不稳定集成测试 -> 隔离依赖或使用内存仓库；仅将
```
.serialized
```
作为过渡方案。
被禁用的测试逐渐失效 -> 对于临时已知失败，优先使用
```
withKnownIssue
```
以保留信号。
复杂类型的失败值不清晰 -> 让类型遵循
```
CustomTestStringConvertible
```
以获得更聚焦的测试诊断信息。
通过名称在测试计划中包含/排除测试 -> 改用标签和基于标签的过滤。

Verification checklist

验证检查清单

Confirm each test has a single clear behavior and expressive display name when needed.
Confirm prerequisites use
```
#require
```
where failure should stop the test.
Confirm repeated logic is parameterized instead of duplicated.
Confirm tests are parallel-safe or intentionally serialized with rationale.
Confirm async code is awaited and callback APIs are bridged safely.
Confirm migration keeps unsupported XCTest-only scenarios on XCTest.

确认每个测试仅对应一个清晰的行为，必要时使用表意明确的显示名称。
确认前置条件在失败应终止测试时使用
```
#require
```
。
确认重复逻辑已参数化，而非重复编写。
确认测试是并行安全的，或是有合理理由地故意设置为串行执行。
确认异步代码已被正确等待，回调API已安全桥接。
确认迁移过程中，不支持的仅XCTest场景仍保留使用XCTest。

References

参考资料

```
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
```

```
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
```