ECC Swift Testing 规则详解：用 Swift Testing 编写隔离、参数化与可注入的确定性测试

ECC Swift Testing 规则详解用 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/ECCECC 将面向 AI 编程助手Cursor、Claude Code 等的工程规范沉淀为一套可被按需加载的规则文件rules其中 Swift Testing 规则 就是这条链上针对 Swift 项目的测试规范它继承通用测试基线80% 覆盖率、TDD 流程并规定了 Swift Testing 框架下Test/#expect的写法、测试隔离方式、参数化测试与覆盖率采集方法。读完本文你能理解该规则在 ECC 规则体系中的加载机制掌握规则中每一类测试写法的完整代码范式并能结合仓库中配套的swift-protocol-di-testing技能落地一套基于协议依赖注入的 Swift 测试方案。规则文件定位Cursor 按需加载的语言专属扩展该规则以 Cursor Rules 的 Frontmatter Markdown 格式定义在.cursor/rules/swift-testing.md头部元数据声明了它的行为--- description: Swift testing extending common rules globs: [**/*.swift, **/Package.swift] alwaysApply: false ---三个字段决定了这条规则的工作方式globs: [**/*.swift, **/Package.swift]当 Cursor 上下文涉及任意.swift文件或 SwiftPM 的Package.swift清单时该规则会被自动纳入上下文alwaysApply: false它不是全局常驻规则只在上述文件出现时生效避免污染其他技术栈会话的上下文预算description供检索/匹配使用的简短描述。规则正文第一行即声明其定位This file extends the common testing rule with Swift specific content——它是对 通用测试规则 的 Swift 特化扩展。值得注意的是仓库中同一规范还存在一个不带 Cursor 专属 Frontmatter 的源版本 rules/swift/testing.md两者内容一致后者用paths字段同样匹配**/*.swift与**/Package.swift声明作用范围。从源码结构看.cursor/rules/目录是按语言 维度组织的规则集合每个语言包含 coding-style、hooks、patterns、security、testing 五个维度文件Swift 亦如此而scaffolds/cursor/目录则存放了 Cursor 侧的配套模板如 hooks.json供初始化 Swift 项目的工作区时复用整套规则。这种通用基线 语言扩展的分层设计是 ECC 规则体系的核心组织原则语言文件只写增量公共要求覆盖率门槛、TDD 流程统一维护在 common 层改一处即全局生效。继承的通用测试基线80% 覆盖率与强制 TDD.cursor/rules/swift-testing.md声明extends common testing rule而该基线.cursor/rules/common-testing.mdalwaysApply: true全局常驻对 Swift 项目同样生效包含以下硬性要求最低测试覆盖率 80%且三类测试全部必须覆盖单元测试——单个函数、工具、组件集成测试——API 端点、数据库操作端到端测试——关键用户流框架按语言选择Swift 场景通常由 Swift Testing 的 async 测试承担。强制 TDD 工作流六步1. 先写测试RED 2. 运行测试——应当失败 3. 写最小实现GREEN 4. 运行测试——应当通过 5. 重构IMPROVE 6. 验证覆盖率80%测试失败排查顺序使用tdd-guideagent对应仓库中的 agents/tdd-guide.md要求在新功能开发时 PROACTIVELY 启用→ 检查测试隔离 → 校验 mock 是否正确 → 修实现而非修测试除非测试本身写错。与 Swift 规则配套的 rules/common/testing.md 还补充了 AAA 结构与命名约定直接适用于 Swift 测试的编排Arrange-Act-Assert每个测试显式分三段——构造前置条件、执行被测行为、断言结果行为描述式命名测试名解释在什么条件下发生什么行为例如returns empty array when no markets match query、throws error when API key is missing。这正好与 Swift 规则中Test(User creation validates email)这种字符串描述符风格一致——Test的第一个参数即行为描述承担命名规范的作用。理解这一层的关系很重要.cursor/rules/swift-testing.md本身只写Swift 怎么写而必须写、写到什么程度、按什么流程写由 common 基线保证。核心内容一Swift Testing 框架的Test与#expect规则的第一个小节明确新测试一律使用 Swift Testingimport Testing使用Test宏与#expect宏而非 XCTest。规则给出的标准范式是异常路径断言Test(User creation validates email) func userCreationValidatesEmail() throws { #expect(throws: ValidationError.invalidEmail) { try User(email: not-an-email) } }要点解析Test(...)中的字符串是测试的行为描述对应 common 基线里的行为描述式命名要求#expect(throws:)是宏形式的断言throws:参数直接匹配具体错误值如ValidationError.invalidEmail比 XCTest 的XCTAssertThrowsError写法更贴近 Swift 的错误类型系统测试函数标注throws后try直接作用于被测调用无需额外包装。这一选择意味着仓库规则要求新代码统一迁移到 Swift Testing 生态它原生支持 Swift 并发下的async测试、await #expect(...)写法以及后文要讲的参数化与隔离特性。核心内容二测试隔离——init 建立、deinit 销毁规则对隔离性给出了一条明确的实现约定Each test gets a fresh instance — set up ininit, tear down indeinit. No shared mutable state between tests.即每个测试拿到全新实例在init中完成搭建、在deinit中完成拆除测试之间禁止共享可变状态。这条约定与 common 基线中测试失败先检查隔离Check test isolation的排查项形成闭环——隔离失效是共享状态污染、顺序依赖导致的偶发失败的最常见来源。从规则原文看它描述的是针对测试主体SUT包装类这一常见模式将 SUT 及其依赖封装为测试 fixture 类每个Test函数内部构造该类的实例利用 Swift 的引用计数保证deinit在函数结束时自动释放资源如关闭 mock 连接、清理临时目录。这与 Swift Testing 的运行模型匹配同一测试套件内各Test函数相互独立、可并行执行任何静态可变状态都会破坏可重复性。核心内容三参数化测试的arguments写法规则给出了参数化data-driven测试的标准形式Test(Validates formats, arguments: [json, xml, csv]) func validatesFormat(format: String) throws { let parser try Parser(format: format) #expect(parser.isValid) }其中Test宏的arguments:参数声明了一组测试数据测试框架会为每个元素生成一个独立的测试实例json、xml、csv各跑一次validatesFormat任一数据项失败都会精确定位到该值。相比在函数体内手写for循环遍历数据集合参数化的优势在于每个数据项在测试报告中是独立条目失败可直接看到是哪个 format 出了问题数据项之间无状态耦合符合上文禁止共享可变状态的隔离要求数据集合可以来自Collection扩展成多参数组合时框架会做笛卡尔积展开规则示例保持单参数形式多参数场景可从源码结构看按同样的arguments:机制叠加。对于 Swift 项目中同一逻辑对不同输入格式/配置应表现一致这类校验规则示例即解析器格式验证这是推荐的默认写法。核心内容四覆盖率采集规则给出的覆盖率命令是 SwiftPM 原生能力swift test --enable-code-coverage该命令在项目根目录含Package.swift的包下执行跑完测试后在.build/x86_64-unknown-linux-gnu/debug/或.build/apple/Products/Debug/macOS目录下生成codecov风格的.profdata/ LLVM coverage 产物可配合 Xcode 的覆盖率报告或llvm-cov工具链转换为可读报告。结合 common 基线的 80% 门槛Swift 项目的验证链路即swift test --enable-code-coverage跑全量测试 → 生成覆盖率数据 → 确认 ≥80% 且三类测试齐备。规则将**/Package.swift列入 glob 匹配正是因为 SwiftPM 包是该命令的触发前提——上下文里出现Package.swift即表示这是一个可用该命令闭环的 Swift 包。纵深扩展规则引用的swift-protocol-di-testing技能规则末尾的 Reference 一节指向仓库内的 swift-protocol-di-testing 技能protocol-based dependency injection and mock patterns with Swift Testing。该技能是 Swift Testing 规则在外部依赖如何 mock这一关键问题上的完整落地核心是把文件系统、网络、外部 API 抽象为小而专注的协议用默认参数注入生产实现、测试注入 mock实现零 I/O 的确定性测试。其完整流程分五步1. 定义单一职责协议每个协议只处理一类外部关注点并且因为要跨 actor 边界使用而要求Sendable// 文件系统访问 public protocol FileSystemProviding: Sendable { func containerURL(for purpose: Purpose) - URL? } // 文件读写操作 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. 生产默认实现public struct DefaultFileAccessor: FileAccessorProviding { public func read(from url: URL) throws - Data { try Data(contentsOf: url) } public func write(_ data: Data, to url: URL) throws { try data.write(to: url, options: .atomic) } public func fileExists(at url: URL) - Bool { FileManager.default.fileExists(atPath: url.path) } }3. 可配置错误的 Mock 实现Mock 的关键设计是可注入的错误属性用于确定性触发失败路径规则示例中的#expect(throws:)断言正是消费这些错误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 } // write / fileExists 同理 }4. 默认参数注入生产代码零改动即可用真实实现测试只需显式传 mockpublic actor SyncManager { public init( fileSystem: FileSystemProviding DefaultFileSystemProvider(), fileAccessor: FileAccessorProviding DefaultFileAccessor() ) { ... } }5. 用 Swift Testing 断言import Testing Test(Sync manager handles missing container) func testMissingContainer() async { let mockFileSystem MockFileSystemProvider(containerURL: nil) let manager SyncManager(fileSystem: mockFileSystem) await #expect(throws: SyncError.containerNotAvailable) { try await manager.sync() } }注意await #expect(throws:)的 async 形态Swift Testing 对并发被测对象actor、async throws提供原生支持这正是规则要求新测试使用import Testing而非 XCTest 的实际收益之一。该技能同时给出了边界清晰的最佳实践与反模式清单可直接作为 Code Review 检查项每个协议只管一件事禁止上帝协议跨 actor 边界必须Sendable生产走默认参数仅测试显式注入 mock只 mock 边界文件系统、网络、外部 API不要 mock 无外部依赖的内部类型避免用#if DEBUG条件编译代替正规依赖注入。规则如何被 Agent 消费从规则到工作流这套 Swift 规则并非孤立存在而是 ECC规则 代理 命令协同体系中面向 Swift 的一环触发在 Cursor 中打开任何.swift/Package.swift文件时swift-testing规则因globs匹配而进入上下文common 测试规则因alwaysApply: true始终在场两者叠加生效执行tdd-guideagent 按 common 基线强制先写测试的 RED-GREEN-REFACTOR 流程Swift 侧的测试写法Test、#expect、隔离、参数化则按本篇规则约束兜底涉及文件系统/网络等外部依赖的测试设计时Reference 指向的 swift-protocol-di-testing 提供协议划分与 mock 的完整范式仓库内还有 swift-concurrency-6-2、swift-actor-persistence 等技能可与 actor 测试场景互补。速查小结要求出处Swift 落地方式新测试统一 Swift Testingswift-testing.mdimport TestingTest#expect行为描述式命名common-testing.md / rules/common/testing.mdTest(User creation validates email)测试隔离swift-testing.md每测试全新实例init搭建、deinit拆除禁止共享可变状态参数化测试swift-testing.mdTest(..., arguments: [...])逐数据项独立执行覆盖率 ≥80%common-testing.mdswift test --enable-code-coverage强制 TDD 六步common-testing.mdRED → GREEN → REFACTOR → 验证覆盖率外部依赖 Mockswift-protocol-di-testing 技能单职责Sendable协议 默认参数注入 可配置错误的 Mock综合来看.cursor/rules/swift-testing.md的价值不在于单独的四小节内容而在于它与 common 基线、tdd-guideagent 和 DI 测试技能构成的完整闭环common 层规定必须写、按 TDD 写、覆盖 80%Swift 层规定用 Swift Testing 这样写技能层规定外部依赖这样 mock。在 Swift/SwiftPM 项目中启用 ECC 这套 Cursor 规则后AI 助手产出的测试代码会被约束在这一范式内——新测试一律Test/#expect、数据驱动、无共享状态、异常路径经 mock 确定性触发并可用swift test --enable-code-coverage一条命令闭环验证覆盖率门槛。【免费下载链接】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），仅供参考