ECC Swift 测试规范实战指南基于 Swift Testing 框架的单元测试、测试隔离与覆盖率实践【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文基于 ECC 仓库中的 Swift 测试规则 docs/ja-JP/rules/swift/testing.md其英文原版为 rules/swift/testing.md展开。这篇技术指南系统讲解在 ECC 的 Swift 项目开发流程中如何采用 Swift Testing 框架Test/#expect编写高质量测试落实测试隔离、参数化测试与代码覆盖率要求并结合协议式依赖注入实现可测试架构。读完本文你将掌握一套可直接落地到.swift与Package.swift工程中的测试编写规范以及与之配套的 TDD 工作流和 Agent 协作方式。一、为什么 ECC 要求新测试统一使用 Swift TestingECCThe agent harness performance optimization system为各语言维护了一套分层的规则体系每种语言的规则文件如 rules/swift/都是对 rules/common/testing.md 等公共规则的语言特化扩展。Swift 的测试规则在文件头通过 frontmatter 声明了其作用范围paths: - **/*.swift - **/Package.swift这意味着凡是触及 Swift 源码含 Swift Package 清单的改动都应遵循这套测试要求。规则明确新增测试必须使用 Swift Testing 框架import Testing并使用其两大核心 API——Test声明测试用例、#expect进行断言。Swift Testing 是 Apple 官方推出的新一代测试框架相比 XCTest 提供了更简洁的语法、更好的并行执行支持与更强大的参数化能力与 Swift 6 的并发模型actor、Sendable天然契合。二、编写第一个 Swift Testing 测试用例规则给出了一个完整的示例用于验证创建用户时必须校验邮箱格式这一行为Test(User creation validates email) func userCreationValidatesEmail() throws { #expect(throws: ValidationError.invalidEmail) { try User(email: not-an-email) } }逐行拆解这段示例可以看到几个关键要点Test(描述文本)Test宏除了标记测试函数外还支持传入人类可读的描述字符串。描述应聚焦被测行为而非实现细节这与 ECC 在 rules/common/testing.md 中强调的测试命名要解释被测行为如throws error when API key is missing一脉相承。#expect(throws: ...)专门用于断言错误抛出的宏。这里断言传入非法邮箱时会抛出ValidationError.invalidEmail这正是对错误路径error path的验证——ECC 公共测试规则与 agents/tdd-guide.md 中的质量清单都明确要求错误路径必须被测试而不只是 happy path。throws函数签名允许测试体内部使用try把错误传播给测试框架统一处理。与 XCTest 的XCTAssertThrowsError相比#expect(throws:)的闭包语法更直观且#expect还支持#expect(throws: Never.self)断言不抛错以及自定义匹配条件表达能力更强。与公共测试规则衔接AAA 结构与行为命名ECC 的公共测试规则 rules/common/testing.md 要求测试优先采用 Arrange-Act-AssertAAA三段式结构并给出通用示例test(calculates similarity correctly, () { // Arrange const vector1 [1, 0, 0] const vector2 [0, 1, 0] // Act const similarity calculateCosineSimilarity(vector1, vector2) // Assert expect(similarity).toBe(0) })在 Swift Testing 中这套 AAA 结构同样适用只需把断言宏换成#expectTest(Parser accepts valid JSON input) func parserAcceptsValidJSON() throws { // Arrange let input #{ key: value }# // Act let parser try Parser(format: json) let isValid parser.isValid(input) // Assert #expect(isValid) }三、测试隔离每个测试都从全新实例开始规则强调的核心原则是每个测试获取一个全新的实例——在init中完成 setup在deinit中完成 teardown测试之间不得共享可变状态。Swift Testing 框架的设计天然支持这一原则实例生命周期Swift Testing 会为每个测试用例创建独立的测试类型实例。因此你可以在测试类型的init里准备前置条件如构造被测对象、填充内存版依赖在deinit里做清理如释放资源、关闭句柄而无需像 XCTest 那样重写setUp()/tearDown()。无共享可变状态禁止测试间通过静态变量、单例或类级属性共享状态。原因与 agents/tdd-guide.md 中列出的测试反模式一致——测试相互依赖共享状态会导致测试顺序敏感、偶发失败破坏并行执行。并行执行由于每个测试独立运行Swift Testing 可以在默认配置下并行执行测试这也是框架测试隔离设计的直接收益。从源码结构上看ECC 的 rules/swift/patterns.md 强调用 actor 管理共享可变状态、用带默认参数的构造器注入协议依赖这与测试隔离要求互为表里生产代码通过依赖注入获得干净的可测试边界测试代码则通过 mock 替换外部依赖获得确定性。四、参数化测试一份用例覆盖多组输入规则给出了参数化测试的标准写法使用Test的arguments参数Test(Validates formats, arguments: [json, xml, csv]) func validatesFormat(format: String) throws { let parser try Parser(format: format) #expect(parser.isValid) }参数化测试的核心价值一行参数列表 N 个独立测试用例arguments: [json, xml, csv]会让该测试函数针对每种格式各运行一次。在测试报告中每个参数组合都会被单独记录失败时能精确定位到具体参数值例如仅csv失败而不是笼统地看到整个测试挂掉。消除重复代码无需复制粘贴三段几乎相同的测试体只需维护参数表。便于扩充边界用例后续要增加yaml、toml等格式支持只需往数组里加一个字符串。结合公共规则中边界值min/max、空数组/空字符串等必须覆盖的用例参数化是批量覆盖边界输入的高效手段Test(Parser rejects invalid formats, arguments: [, unknown, json ]) func parserRejectsInvalidFormat(format: String) throws { let parser try Parser(format: format) #expect(!parser.isValid) }五、覆盖率度量让 80% 目标可执行、可验证规则给出的覆盖率命令swift test --enable-code-coverage命令行为--enable-code-coverage让 Swift Package Manager 在测试运行时采集代码覆盖率数据。执行完毕后会在.build/debug/codecov/下生成 LLVM 格式的覆盖率信息可通过xcrun llvm-cov report等工具查看各文件的行覆盖率与分支覆盖率。与 80% 底线联动ECC 公共测试规则 rules/common/testing.md 明确要求最低测试覆盖率达 80%且单测单元、集成、E2E 三类测试均为必需。Swift 侧的落地路径通常是在 CI 中执行swift test --enable-code-coverage xcrun llvm-cov report .build/debug/PackageName.xctest/Contents/MacOS/PackageName \ -instr-profile .build/debug/codecov/default.profdata覆盖率是结果而非目的与 agents/tdd-guide.md 中覆盖率 80%分支、函数、行、语句的质量清单一致覆盖率数字用于发现未被测试触达的分支尤其要关注错误路径与边界分支而非仅仅追求行数达标。六、进阶协议式依赖注入与 Mockswift-protocol-di-testing 技能规则在参考一节明确指出协议式依赖注入与 Swift Testing 的 Mock 模式见技能 skills/swift-protocol-di-testing/SKILL.md。这是让上述测试规范真正落地到文件系统、网络、iCloud 等外部依赖场景的关键。1. 定义小而聚焦的协议每个协议只负责一种外部关注点避免上帝协议// File system access public protocol FileSystemProviding: Sendable { func containerURL(for purpose: Purpose) - URL? } // File read/write operations public protocol FileAccessorProviding: Sendable { func read(from url: URL) throws - Data func write(_ data: Data, to url: URL) throws func fileExists(at url: URL) - Bool }2. 生产实现使用默认参数注入生产代码默认使用真实实现测试时才注入 mockpublic actor SyncManager { private let fileSystem: FileSystemProviding private let fileAccessor: FileAccessorProviding public init( fileSystem: FileSystemProviding DefaultFileSystemProvider(), fileAccessor: FileAccessorProviding DefaultFileAccessor() ) { self.fileSystem fileSystem self.fileAccessor fileAccessor } }这种默认参数注入模式与 rules/swift/patterns.md 中UserService的依赖注入示例完全同构——生产代码零改动测试代码显式传入 mock。3. Mock 设计可配置的错误注入技能中给出的MockFileAccessor是错误路径测试的范本——通过公开的readError/writeError属性模拟失败public final class MockFileAccessor: FileAccessorProviding, unchecked Sendable { public var files: [URL: Data] [:] public var readError: Error? public var writeError: Error? public func read(from url: URL) throws - Data { if let error readError { throw error } guard let data files[url] else { throw CocoaError(.fileReadNoSuchFile) } return data } // ... }4. 用 Swift Testing 验证错误路径import Testing Test(Sync manager reads data correctly) func testReadData() async throws { let mockFileAccessor MockFileAccessor() mockFileAccessor.files[testURL] testData let manager SyncManager(fileAccessor: mockFileAccessor) let result try await manager.loadData() #expect(result expectedData) } Test(Sync manager handles read errors gracefully) func testReadError() async { let mockFileAccessor MockFileAccessor() mockFileAccessor.readError CocoaError(.fileReadCorruptFile) let manager SyncManager(fileAccessor: mockFileAccessor) await #expect(throws: SyncError.self) { try await manager.sync() } }注意两点异步测试用asyncawait #expect(throws:)断言并发场景下的错误Sendable一致性在协议跨越 actor 边界时是硬性要求见技能最佳实践与 rules/swift/coding-style.md 中Swift 6 严格并发检查的说明。反模式清单务必规避技能明确列出了需要规避的反模式其中与本文测试主题强相关的有创建覆盖所有外部访问的超大协议Mock 没有外部依赖的内部类型用#if DEBUG条件编译替代真正的依赖注入与 actor 配合时遗漏Sendable一致性过度设计——类型没有外部依赖时不需要协议。七、配套机制TDD 工作流、Agent 与 HooksTDD红-绿-重构六步法ECC 公共测试规则 rules/common/testing.md 将 TDD 设为强制工作流先写测试RED运行测试——应当失败编写最小实现GREEN运行测试——应当通过重构IMPROVE验证覆盖率80%。Swift 侧执行这套流程时测试文件放入Tests/目录与 agents/tdd-guide.md 中先写失败测试描述预期行为的步骤一致。Agent 支持tdd-guideagents/tdd-guide.md 定义了一个专门的 TDD 专家 Agent其职责包括强制测试先行方法论、引导红-绿-重构循环、确保 80% 覆盖率、编写单测/集成/E2E 测试套件、在实现前捕捉边界用例。在 Swift 项目中编写新特性时应主动调用该 Agent。它的必须测试的边界用例清单null/空值、空数组、非法类型、边界值、错误路径、并发竞争、大数据量、特殊字符可以直接映射到 Swift Testing 的#expect与参数化测试中。Hooks格式化、Lint 与类型检查rules/swift/hooks.md 建议在~/.claude/settings.json中配置 PostToolUse 钩子让工具链在每次编辑后自动兜底SwiftFormat自动格式化.swift文件rules/swift/coding-style.md 同时提到 Xcode 16 自带的swift-format可作为替代SwiftLint编辑后执行 lint 检查swift build对修改过的包做类型检查。这套钩子与测试规范配合形成编码 → 格式化/Lint → 构建 → 测试 → 覆盖率的完整质量闭环。八、速查Swift 测试规则要点一览主题规则要点关键 API / 命令测试框架新测试统一使用 Swift Testingimport Testing、Test、#expect测试隔离每用例全新实例initsetup、deinitteardown不共享可变状态测试类型实例生命周期参数化测试用参数数组批量生成用例Test(..., arguments: [...])覆盖率覆盖率达到公共规则要求的 80% 底线swift test --enable-code-coverage依赖注入协议默认参数注入测试注入 mock见 skills/swift-protocol-di-testing/SKILL.mdTDD红-绿-重构强制流程见 agents/tdd-guide.md工具链SwiftFormat / SwiftLint / swift build 钩子见 rules/swift/hooks.md结语ECC 的 Swift 测试规范rules/swift/testing.md日文版见 docs/ja-JP/rules/swift/testing.md虽然篇幅精炼却是一条承上启下的规则主干向上衔接公共测试规则中 80% 覆盖率、TDD、AAA 结构与测试命名的通用要求rules/common/testing.md向下延伸出协议式依赖注入与 Mock 的完整实战技能skills/swift-protocol-di-testing/SKILL.md并配套 tdd-guide Agent 与 SwiftFormat/SwiftLint 钩子形成闭环。在实际项目中建议以Swift Testing 编写用例 协议注入构造隔离 覆盖率命令验证 tdd-guide 兜底四步组合落地即可获得确定性高、可并行、可度量的 Swift 测试体系。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考