迁移到 Swift Testing

了解如何借助测试框架之间的互操作性，在使用 XCTest 的同时放心地采用 Swift Testing。探索逐步引入高级测试功能的最佳做法和模式，以便加快开发速度并扩大测试覆盖面。

章节

资源

- 高清视频
- 标清视频

相关视频

WWDC26

Swift 的新功能

WWDC24

你好我叫Jerry 我是Swift Testing团队的工程师今天我来分享如何比以往更轻松地从XCTest迁移到Swift Testing

我们在Xcode 16中推出了Swift Testing 它是一个现代测试库提供了简洁且富有表现力的接口来编写测试它也完全融入了 Swift生态系统例如它在设计时就考虑了Swift并发性可以并行运行测试用例并以极快的速度输出结果

我将首先回顾 Swift Testing的基础构建块并将其与XCTest中的类似概念进行比较接下来我将把Swift Testing 添加到XCTest项目中在此过程中我将演示如何复用现有代码利用测试框架互操作性功能

即使你不使用XCTest 也请继续收看我将分享如何使用 Swift Testing的功能大胆探索XCTest 从未踏足的领域

让我们从Swift Testing 的基础知识开始

我先导入 Swift Testing框架以及通过testable import 访问内部类型然后我创建一个新函数并用@Test宏对其进行标注将其声明为测试

Swift支持原始标识符由这些反引号标注这让我可以在测试名称中加入空格和标点在测试主体中我使用#expect宏来创建水果具有热带气候的预期这就是创建新测试所需的全部内容 @Test和#expect宏是大多数测试的核心构建块如果你刚接触Swift Testing 或只是想温故知新《Meet Swift Testing》是绝佳的参考资料它涵盖了更多构建块和测试工作流程

#expect宏非常灵活可替代许多XCTest断言要替换XCTFail 即无条件失败断言请改用Issue.record

使用Swift Testing 你将体验到用更少的代码编写更强大且更具表现力的测试但在某些场景下仍需继续使用XCTest UI自动化和性能测试API 仅在XCTest中可用而在测试会抛出 Objective-C异常的代码时必须使用同样以 Objective-C编写的XCTest 这是因为Swift代码包括用Swift编写的XCTest 无法安全地处理这些异常好了我知道你现在迫不及待地想写测试了下面我来演示如何无所顾虑地迁移到Swift Testing

我将介绍分批迁移测试代码的策略

接下来我将介绍测试框架互操作性这是一个强大的工具可让我复用现有测试代码

为帮助你的迁移顺利进行我将分享一些常见的参考模式好来聊聊迁移策略

修改旧测试会引入风险即便是小改动也不例外因此我会让大多数XCTest保持原样当我准备好时我会每次只修改少量测试重点关注最常更新的那些

我现有的测试目标可以包含两个框架的测试因此我可以对新测试直接使用Swift Testing 但它们不能放在XCTest类内部好的有了迁移策略我已准备好付诸实践我开发了一款应用训练社区里的鸟类进行水果配送就像鸟类随季节变化迁徙一样我认为现在也是我迁移到Swift Testing的时机

这是我的Fruit数据结构所对应的XCTest套件我最近为水果添加了气候信息但尚未对其进行测试我想使用Swift Testing 添加一些新测试而且不用离开这个文件就能完成首先我导入 Swift Testing框架

然后我将在文件末尾添加测试

我喜欢Swift Testing 能让测试置于套件之外等有了更多测试我随时可以再创建父套件在Test navigator中我注意到新测试已包含在内现在我打开Product菜单并选择Test

太好了我的新测试运行成功了

有些测试需要更多设置这个测试检查水果数组中的名称是否唯一我最初编写这个测试时用了多行代码来设置断言

后来运行测试时我发现很难理解它为何失败这个测试本想讲述一个故事却迷失在大量代码之中因此我将这个多步断言提取到了辅助函数中现在测试内容和方式都更加清晰了作为最后的修饰我提供了文件和行号参数并将其传入XCTFail

Xcode现在会将失败归因到调用辅助函数的那一行

我想用Swift Testing 创建新测试这些测试也会调用此辅助函数并最终调用XCTFail 但XCTFail不属于Swift Testing 这正是测试框架互操作性大显身手的地方这一功能让你可以安全地调用一个测试框架的API 同时在另一个框架的测试主体中使用

考虑互操作性时有两个方向需要思考你可以调用XCTest API 在Swift Testing测试中报告问题这正是我复用assertUnique辅助函数时的情况该函数封装了XCTFail 另一个方向你可以调用Swift Testing API 在XCTest中报告问题我稍后会解释这种情况

无论哪种情况都会产生跨框架问题报告问题的API与调用它的测试分属不同的框架 Xcode默认启用互操作性来处理这些问题让我来演示一下

我在testUniqueFruitNames中调用assertUnique辅助函数该辅助函数使用XCTFail报告失败我创建了另一个Swift Testing测试具有相同的主体这个辅助函数应该报告相同的失败但在这个测试中这是一个跨框架问题

来比较运行此测试后的结果

嗯我注意到测试通过了但实际上我以为它会失败就像上面的XCTest一样测试失败有时也是好事因为它意味着辅助函数正在捕获Bug 不过这里有一些消息我点击查看

互操作性产生了两个警告由紫色三角形标注由于这些不是错误测试仍然通过第一个警告告诉我 Lychee是重复名称第二个警告指示我将XCTFail替换为 Swift Testing的Issue.record

互操作性提供了不同的模式用于处理跨框架问题我刚才介绍了limited模式在此模式下来自XCTest的跨框架问题显示为警告 Xcode 27之前创建的测试计划沿用limited模式对于新项目 Xcode使用complete模式在此模式下相同的问题保持为错误

你可以随时通过 Test Plan Settings更改模式可在Test Execution部分找到来看看complete模式如何改变测试结果我来编辑测试计划

在这里我筛选互操作性

并将该模式改为Complete

现在我回到"Unique fruit names" 测试并再次运行

现在我的测试失败了来查看消息

complete模式保留了 XCTFail创建的错误它也保留了提示我迁移的警告可以把complete模式理解为 limited模式之上的一个层级它将跨框架问题从警告升级为错误让你不那么容易遗漏它们

strict模式是complete模式之上的再一步对于来自XCTest的跨框架问题 strict模式会以致命错误使测试立即停止这有助于找到需要替换 XCTest API的地方我已将模式更新为strict 现在我再次运行测试

哇！测试正好停在辅助函数中调用XCTFail的位置来查看这条消息

再一次我收到了替换XCTFail的提示但我必须记住我仍有XCTest在调用这个辅助函数这就是互操作性也支持来自Swift Testing的跨框架问题的原因在所有模式下这些问题均保持为错误因此你可以调用Swift Testing API 在两个框架的测试中均可使用替换XCTFail只需几个步骤我先将XCTest的导入替换为Swift Testing的导入

然后将XCTFail替换为Issue.record sourceLocation替换原始的文件和行号参数

更新辅助函数后我将再次运行所有测试用例

我将使用CMD+U 即product test的快捷键

使用更新后的辅助函数我的新测试和原始XCTest 都如预期地失败了感谢测试框架互操作性我将XCTest API替换为了Swift Testing API 而不改变测试的含义还有一个我尚未介绍的模式你可以将模式设置为none 以退出互操作性退出后 Xcode将不再报告跨框架问题无论哪个方向但这些问题可以帮助发现App中的Bug 如果禁用互操作性你将无法捕获这些Bug 因此如果必须使用此模式请仅临时使用请优先选择complete或strict模式 complete模式将跨框架问题保持为错误是limited模式之上有价值的提升 strict模式顾名思义很严格！如果你想完全阻止来自XCTest的跨框架问题它非常合适你也可以使用互操作性及其不同模式用于Swift Package项目这是以swift-tools-version: 6.3 创建的项目示例其中有一个测试产生来自XCTest的跨框架问题默认情况下 Swift 6.4工具链启用limited模式

当我使用swift test命令运行此项目时我注意到它将跨框架问题报告为警告

要使用complete模式请将软件包更新至swift-tools-version 6.4或更新版本

更新工具版本后之前的问题现在变成了错误

随时使用环境变量覆盖默认模式： SWIFT_TESTING_XCTEST_INTEROP_MODE 值填写模式名称的小写形式

最后互操作性支持一组有限的API 来自两个测试框架我刚演示了XCTFail 和Issue.record API 在XCTest中它还支持所有其他测试断言在Swift Testing中它支持两种预期宏： #expect和#require Swift Testing中的已知问题API 可将XCTest断言失败标记为已知 Test.cancel可以在XCTest中跳过测试用例

在你的迁移过程中可能会遇到一些常见模式我将分享一些应对这些模式的技巧

第一种模式是跳过测试在XCTest中你使用 XCTSkip API跳过测试

要将其替换为Swift Testing API 请使用Test.cancel 如果你在Swift Testing中编写新测试 Test.cancel在那里也同样有效但Swift Testing有traits 它们是可附加到测试函数和套件的注解

将测试启用逻辑移出测试主体使用enabled或disabled trait

另一种常见模式是在失败时中止在XCTest中将continueAfterFailure 属性赋值为false 这将在第一次断言失败时停止测试要替换为Swift Testing API 请使用#require宏它在失败时抛出错误中止测试无需再设置continueAfterFailure 使用Swift Testing 你还可以选择哪些预期会中止测试哪些不会

更多信息请参阅开发者文档中的《Migrating a test from XCTest》它涵盖了更多场景是迁移过程中的绝佳参考资料 Xcode的Coding Assistant 也了解这份文档它可以帮助制定迁移策略或审查你的工作它甚至有一项技能可以自动化部分迁移工作哇我们涵盖了很多内容！总结一下以下是如何无所顾虑地迁移到Swift Testing

不要在准备好之前被迫修改你的XCTest 专注于使用Swift Testing 编写新测试依靠互操作性你甚至可以复用封装了XCTest API的辅助代码

在此过程中你会发现来自XCTest的跨框架问题互操作性允许你将XCTest API替换为Swift Testing API 以解决这些问题而Xcode 27默认启用了互操作性确保处理所有未来的跨框架问题通过升级到 complete或strict模式

现在是时候将聚光灯转向Swift Testing了

迁移到Swift Testing后你可以使用新工具来大幅提升测试能力让我们从参数化测试开始

这些测试会用不同的参数重复执行每个参数都会成为一个单独的测试用例所有Swift Testing测试包括参数化测试用例默认并行运行这比串行运行快得多来看这个示例

我已将项目的Bird测试迁移到Swift Testing 这检查每只鸟能否拍打翅膀四十到一百次但我无法为每种组合都编写一个单独的测试组合实在太多了在我原始XCTest的主体中我使用了嵌套循环来生成所有组合我来运行这个测试

有几件事引起了我的注意测试花了一段时间才完成可能是因为有很多组合另外测试失败了但我甚至不知道哪只鸟失败了

如果我仍在使用XCTest 我必须捕获这些错误或在附加调试器的情况下运行测试我有个更好的主意让我们把它变成参数化测试我先从测试主体中删除这些循环

然后将bird和count 定义为测试函数参数

我将birds和counts的输入作为参数提供在test宏中

Swift Testing会将第一个参数中的每只鸟与第二个参数中的每个count配对我再次运行测试

嘿！这次测试几乎立刻就完成了因为Swift Testing 并行运行了所有组合在Test navigator中我的参数化测试左侧现在有一个展开箭头我点击它来显示所有正在测试的组合

哇真是很多测试用例好的我还需要找出失败的组合在Test navigator中我筛选失败的测试结果

啊找到了！燕子拍翅次数不能少于43次使用参数化测试大幅提升了我的测试执行效率不仅获取结果的速度更快还能清楚地知道哪些测试输入失败了

接下来我要展示如何通过 exit tests大幅提升测试覆盖率请注意 exit tests仅在 macOS Linux FreeBSD和Windows上支持我在寻找需要测试覆盖率的代码在Bird初始化器中发现了一些东西

如果新Bird的名称为空我会用前置条件失败来中止程序

我可以打开"Editor"菜单来验证是否已测试过这一点并显示"Code Coverage"

覆盖率注解将前置条件标注为红色这意味着我的测试没有运行到此代码 exit test是添加此覆盖率的完美工具

你使用#expect宏定义exit test 提供预期的进程退出条件以及exit test的主体当你启动测试时 Swift Testing会在子进程中运行exit test主体由于该代码是隔离的它可以崩溃而不影响其他测试 exit test等待子进程完成并检查退出状态来判断测试成功或失败我可以在测试套件的这个扩展中添加新测试我使用#expect宏创建exit test 并指定进程应以失败退出

在exit test主体内部我将创建一个名称为空的Bird 这应该会崩溃但它会被隔离因为Swift Testing会在单独的进程中运行此代码现在我运行所有测试

太好了我的exit test通过了！来再次检查覆盖率我在Bird初始化器上右击选择"Jump to Definition" 现在我们回来了来再次查看覆盖率覆盖率注解现在将前置条件高亮显示为绿色这意味着它现在已被测试到了！

这是两种提升测试能力方式的快速预览如果你有关于 Swift Testing如何改进的想法我鼓励你来贡献！这是因为 Swift Testing是开源的它是GitHub上 SwiftLang组织的一部分它现已支持比以往更多的平台今年开始完全支持FreeBSD

Testing Workgroup 负责管理该项目并定期举行会议任何Swift社区成员均可参加新功能由Swift Evolution指导实际上互操作性就是其中之一！欢迎加入Swift Forums 分享你的意见和想法现在轮到你像鸟一样迁移到Swift Testing了！ Xcode 27中的互操作性让这一过渡比以往更轻松在你的项目中试用并探索其不同模式在此过程中你可以采用强大的工具例如参数化测试和exit tests 如需深入了解请查看WWDC 2024的《Go further with Swift Testing》祝你改造测试愉快！

1:12 - Name a test using a raw identifier

import Testing

@testable import DemoApp

@Test func `Default climate: tropical`() async throws {
    let fruit = Fruit(name: "Coconut")
    #expect(fruit.climate == .tropical)
}

5:03 - Wrap XCTFail in a test helper function

func testUniqueFruitNames() async throws {
    assertUnique(Market.fruits + [Fruit.lychee])
}

// TestHelpers.swift

func assertUnique(_ fruits: [Fruit], file: StaticString = #filePath, line: UInt = #line) {
    var uniqueNames = Set<String>()
    for name in fruits.map(\.name) {
        if !uniqueNames.insert(name).inserted {
            XCTFail("Duplicate name: \(name)", file: file, line: line)
        }
    }
}

10:12 - Replace XCTFail with Issue.record in the test helper

import Testing

func assertUnique(_ fruits: [Fruit], sourceLocation: SourceLocation = ...) {
    var uniqueNames = Set<String>()
    for name in fruits.map(\.name) {
        if !uniqueNames.insert(name).inserted {
            Issue.record("Duplicate name: \(name)", sourceLocation: sourceLocation)
        }
    }
}

12:15 - Run Swift Package tests with the strict interoperability mode from Terminal
```
> SWIFT_TESTING_XCTEST_INTEROP_MODE=strict swift test
```

13:10 - Common migration: skipping tests

let isFall = false

// XCTest
func testSwallowFallMigration() async throws {
    try XCTSkipIf(!isFall, "Wrong season for migration")
    // ...
}

// Test.cancel interoperability from Swift Testing
func testSwallowFallMigration() async throws {
    if !isFall {
        try Test.cancel("Wrong season for migration")
    }
    // ...
}

// ✅ Prefer test trait in Swift Testing
@Test(.enabled(if: isFall, "Wrong season for migration"))
func `Swallow fall migration`() async throws {
   // ...
}

13:41 - Common migration: halting after test failures

func testExample() async throws {
    #expect(Fruit.banana.climate == .temperate)

    try #require(Fruit.banana == Fruit.plantain)
    XCTFail("This is never reached")
}

15:57 - Example of nested loops which can be converted into a parameterized @Test function

struct BirdTests {

    @Test func `Birds flap wings successfully`() async throws {
        for bird in Aviary.birds {
            for count in (40...100) {
                try await bird.flapWings(count: count)
            }
        }
    }

}

16:47 - Refactor nested loops into a parameterized @Test function

struct BirdTests {

    @Test(arguments: Aviary.birds, 40...100)
    func `Birds flap wings successfully`(bird: Bird, count: Int) async throws {
        try await bird.flapWings(count: count)
    }

}

18:21 - Precondition check on empty input name in an initializer

// In `Bird.init(...)`
if name.isEmpty {
    preconditionFailure("Bird name cannot be empty")
}

19:27 - Add coverage for precondition failure with exit test

extension BirdTests {

    @Test func `Bird with empty name crashes`() async throws {
        await #expect(processExitsWith: .failure) {
            _ = Bird(name: "")
        }
    }

}

0:07 - Introduction
How to fearlessly migrate from XCTest to Swift Testing using the new interoperability feature.
1:08 - Swift Testing basics
A quick review of core Swift Testing building blocks — the @Test macro, #expect, and how they compare to XCTest assertions.
2:50 - Migration strategy
Covers the recommended incremental approach: leave existing XCTests in place, and start writing new tests in Swift Testing right away.
5:48 - Test framework interoperability
Introduces the interoperability feature that lets you safely call XCTest or Swift Testing API from within a test belonging to the other framework.
7:43 - Interoperability modes
Walks through the four interoperability modes — Limited, Complete, Strict, and None — and how to configure them in Xcode Test Plans and Swift packages.
13:02 - Common migration patterns
Covers practical patterns you will encounter during migration, including replacing XCTSkip with Test.cancel or traits, and continueAfterFailure with #require.
15:34 - Parameterized tests
Shows how to replace loop-based XCTest cases with Swift Testing parameterized tests for faster parallel execution and clearer failure reporting.
18:02 - Exit tests
Demonstrates how to use Swift Testing exit tests to cover code paths that call preconditionFailure or crash, running them safely in a child process.
20:04 - Next steps
Recaps the migration path, highlights Swift Testing open-source availability and cross-platform support, and encourages community participation.

探索“入门汇总”

及时了解最新动态

探索“平台”

精选

探索“技术”

精选

探索“社区”

精选

探索“文档”

发布说明

探索“下载”

精选

探索“支持”

精选

快速链接

迁移到 Swift Testing

章节

资源

相关视频

WWDC26

WWDC24