Swift 测试代码分析参考指南基于 XCTest 与 Swift Testing 的 Polyglot 测试分析能力矩阵【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills本指南围绕 Swift 测试框架参考文档 展开该文档是dotnet-test插件中test-analysis-extensions技能为 Swift 语言提供的测试分析参考数据。它服务于仓库中的多语言polyglot测试分析技能——assertion-quality、test-anti-patterns、test-gap-analysis、test-smell-detection、test-tagging等帮助 AI 编码 Agent 以语言无关的视角识别 Swift 测试中的断言、跳过注解、睡眠模式、外部依赖Mystery Guest与集成测试标记。读完本文你将掌握两套 Swift 测试框架XCTest 与 Swift Testing的能力对照表、可复制的断言与异常校验代码范式以及如何利用test-analysis-extensions让测试分析技能正确校准 Swift 特有的异步与标签行为。背景扩展文件在测试分析流水线中的角色在 plugins/dotnet-test/README.md 中test-analysis-extensions被归类为检测与参考数据技能它提供各语言参考文件的路径供多语言测试分析技能按需加载。该技能在 SKILL.md 中声明disable-model-invocation: true与user-invocable: false即它不面向用户直接调用而是由test-quality-auditorAgent 及各分析技能在分析前按需读取。每个扩展文件dotnet.md、python.md、swift.md、typescript.md等都覆盖同一组能力类别保证分析技能可以保持语言中立。从 SKILL.md 的Notes for skill authors一节可以看到明确的使用约定把扩展文件当数据而非逐字遵循的指导——它们告诉技能如何在各语言中检测事物而非对发现结果应该如何思考语言检测不确定时优先读多个扩展文件而非猜测用户明确点名但暂无扩展文件的框架时回退到语义最接近的扩展文件并在报告中标注缺口。swift.md正是这一架构下 Swift 语言的检测数据源。以下按文档本身的骨架逐节展开并结合仓库内消费方技能test-tagging、test-smell-detection、assertion-quality的用法给出深度解读。能力标签Capability Tags先声明能力边界再安全地执行扩展文件开头的能力标签表是所有分析技能的能力门禁。Swift 的能力声明如下CapabilitySupportTest discoveryStrong —XCTestCase子类、Test函数Assertion detectionStrong —XCTAssert*、#expect、#requireSleep/delay detectionStrong —Thread.sleep、Task.sleep、XCTWaiterSkip/ignore detectionStrong —XCTSkip、.disabled(...)Setup/teardown detectionStrong —setUp/tearDown、Swift Testing 的init/deinitTag supportauto-editSwift Testing—Test(.tags(...))/Suite(.tags(...))XCTest: report-onlyTag support这一列最值得注意因为它在 test-tagging 技能 中直接决定行为分支。test-tagging将各框架的标签能力分为三类auto-edit—— 语言存在可安全写入的规范属性/标记技能可以直接编辑源码report-only—— 没有公认的规范语法只产出审计报告而不改动源码convention-based—— 仅存在命名/文件约定需用户确认项目约定后才编辑。Swift 恰好呈现分裂状态Swift Testing 的Test(.tags(...))/Suite(.tags(...))属于auto-edit可直接写入而 XCTest 没有内置标签机制属于report-only只能报告。这与 test-tagging 的内置能力分类表 完全一致该表把 Swift TestingTag(.tagName) 列为 auto-edit把 plain XCTest without a test plan 列为 report-only。测试文件识别两套框架的发现约定FrameworkFile conventionTest method markersXCTest*Tests.swiftSwift Package Manager:Tests/ModuleTests/class FooTests: XCTestCase方法以test开头Swift Testing相同文件约定Test func foo() async throws { ... }可选地在Suite类型内部两个框架可以共存于同一个 target。这一约定与 code-testing-extensions 的 Swift 扩展 中的项目布局章节相互印证SPM 下测试 target 约定命名为TargetNameTests位于Tests/TargetNameTests/并在Package.swift中以.testTarget(name: MyLibraryTests, dependencies: [MyLibrary])声明依赖Xcode 下测试位于独立 target如MyAppTests并加入 scheme 的 Test action。识别框架时code-testing-researcherAgent 的策略是检查Package.swiftSPM或*.xcodeproj/*.xcworkspaceXcode区分import XCTest的XCTestCase子类与import Testing的Test自由函数见 code-testing-researcher.agent.md。扩展文件给出文件级识别特征后分析技能即可用正则扫描定位测试方法。断言 API 对照XCTest 与 Swift Testing 的逐类映射文档用一张横跨 13 个语义类别的对照表将两套框架的断言 API 一一对应。这是assertion-quality技能做断言分类时的字典该技能要求必须先读对应扩展文件再分类断言见 assertion-quality/SKILL.mdCategoryXCTestSwift TestingEqualityXCTAssertEqual(actual, expected)#expect(actual expected)InequalityXCTAssertNotEqual#expect(actual ! expected)BooleanXCTAssertTrue/XCTAssertFalse#expect(condition)NilXCTAssertNil/XCTAssertNotNil#expect(value nil)/#expect(value ! nil)ThrowsXCTAssertThrowsError(try fn()) { error in ... }#expect(throws: SomeError.self) { try fn() }/try #require(throws: ...)No throwXCTAssertNoThrow(try fn())隐式直接try fn()Identical (reference)XCTAssertIdentical#expect(a b)ApproximateXCTAssertEqual(x, y, accuracy: 0.01)#expect(abs(x - y) 0.01)TypeXCTAssertTrue(x is T)#expect(x is T)MembershipXCTAssertTrue(arr.contains(item))#expect(arr.contains(item))FailXCTFail(reason)Issue.record(reason)Soft fail (continue)XCTAssert*默认继续执行#expect记录 issue 后继续Hard fail (stop)XCTSkipIf属于跳过测试级无硬失败try #require(...)中止测试表尾的两行揭示了 Swift 语义的关键差异直接影响test-smell-detection的严重性判定软失败soft fail#expect记录 issue 后测试继续运行类似 XCTest 的XCTAssert*默认行为硬失败hard failtry #require(...)在条件不满足时中止整个测试——这是 Swift Testing 独有的前置条件机制。语言级断言XCTAssert*与#expect的语义差别从源码结构可以推断#expect的实现基于宏macro展开它捕获的是表达式是否满足这个事实而不是 XCTest 那种值比较 失败消息的命令式 API。这对分析技能有两层含义#expect(actual expected)同时承担相等性断言与布尔断言两种职责表中 Equality 与 Boolean 两行都指向它错误类型断言的三种写法#expect(throws:)、try #require(throws:)、XCTAssertThrowsError闭包内的guard case ... else XCTFail在语义强度上不同分析时应区分仅断言抛错类型与断言具体错误值。近似比较的框架差异XCTest 用accuracy:参数做容差比较XCTAssertEqual(x, y, accuracy: 0.01)Swift Testing 没有专门的近似断言需自行写#expect(abs(x - y) 0.01)。在assertion-quality的 12 类断言分类中两者都归入 Approximate 类目但检测正则必须按各自语法形态分别匹配。睡眠/延迟模式区分睡眠味道与合法异步协调Sleepy Test 是test-smell-detection的核心学术味道之一。文档给出 Swift 中四类延迟模式及其合法性判定PatternExampleThread sleepThread.sleep(forTimeInterval: 1.0)Async sleeptry await Task.sleep(nanoseconds: 1_000_000_000)Swift 5.5Async sleep (newer)try await Task.sleep(for: .seconds(1))Swift 5.7XCTest waiterwait(for: [exp], timeout: 5)基于 expectation 的测试可接受Async waiterawait fulfillment(of: [exp], timeout: 5)Xcode 14关键校准规则在文档中单独强调XCTestExpectationwait(for:timeout:)是 XCTest 惯用的异步协调模式不是睡眠味道。这一点与 test-smell-detection 的校准规则 相呼应——固定墙钟睡眠等待结果应判为 Sleepy Test但用 expectation 等待异步回调完成属于框架惯用法不应降级误报。同理Swift 生成扩展 也提醒XCTest 下异步期望应尽量重构为async测试无法重构时才用XCTestExpectationwait(for:timeout:)Swift Testing 下用await confirmation { ... }断言回调被触发。分析技能因此可以建立如下判定链Thread.sleep/ 固定Task.sleep→ 疑似 Sleepy Test高严重度候选wait(for:timeout:)/await fulfillment(of:timeout:)→ XCTest 惯用法放行Task.sleep出现在轮询/重试逻辑中 → 视具体场景校准测试集成测试中的固定睡眠仍不能因它是集成测试而降级见test-smell-detection校准规则。跳过/忽略注解区分跳过语义FrameworkAnnotationXCTestthrow XCTSkip(reason)、XCTSkipIf(cond, reason)、XCTSkipUnless(cond, reason)Swift TestingTest(.disabled(reason))、Test(.disabled(if: cond, reason))、Test(.enabled(if: cond))XCTest 的跳过是运行时控制流在测试体内throw XCTSkip而 Swift Testing 的禁用是声明式 trait标注在Test上。test-smell-detection将禁用测试归类为 Ignored Test 味道并规定校准规则每个跳过都要报告但有理由且被跟踪的跳过严重度低于无理由的跳过不能因为跳过理由充分就清除它也不能给两者相同紧迫度。分析技能正是依靠上表正则识别两种框架各自的跳过形态再结合理由的有无分配严重度。异常处理惯用替代写法的完整代码示例文档用一段可直接复制的 Swift 代码展示手写do/catch捕获异常应替换为框架原生形式。这段代码是全文档最核心的可执行资产完整保留如下// XCTest: XCTAssertThrowsError(try service.placeOrder(emptyOrder)) { error in guard case OrderError.empty error else { XCTFail(Expected .empty, got \(error)) return } } // Swift Testing: #expect(throws: OrderError.self) { try service.placeOrder(emptyOrder) } // Specific case (Swift Testing): let err try #require(throws: OrderError.self) { try service.placeOrder(emptyOrder) } #expect(err .empty)配套的检测规则是标记手写的do { try fn(); XCTFail(expected throw) } catch { ... }模式推荐使用框架原生形式。这与test-smell-detection的 Exception Handling 学术味道一一对应——该味道的判定是测试手动管理期望的异常流程修复方式是使用框架的异常断言并检查有意义的细节而绝不能宣称捕获并断言的测试什么都没验证。三种写法的强度递进值得展开#expect(throws: OrderError.self)—— 只断言抛出的错误类型try #require(throws: OrderError.self)—— 断言类型并取回错误值若未抛出则中止测试XCTAssertThrowsErrorguard case ... else XCTFail—— XCTest 下同时断言类型与具体 case 的惯用写法。分析技能在判定异常断言是否充分时应识别出仅XCTAssertThrowsError(try fn())而未检查error的测试属于低强度异常断言#expect(throws:)同理。Mystery GuestSwift 常见外部依赖指示器Mystery Guest 学术味道指测试依赖了未声明的文件、网络服务、环境值或数据库。文档给出 Swift 侧的指示器清单IndicatorWhat to look forFile systemFileManager.default.contents(atPath:)、硬编码的Bundle.main路径Database直接对真实文件使用SQLite.swift、在内存存储之外的原生CoreData保存NetworkURLSession.shared.dataTask而无URLProtocolstub、Alamofire指向真实 URLEnvironmentProcessInfo.processInfo.environment[X]AcceptableURLProtocolstubs、OHHTTPStubs、Mocker、使用 in-memory store type 的NSPersistentContainer、Bundle.module资源路径最后一行Acceptable是关键校准输入合法的测试替身URLProtocol拦截、内存数据库、模块资源路径不算Mystery Guest。test-smell-detection 的校准规则 进一步明确本地临时文件仍满足 Mystery Guest 的正式定义——封闭的创建与清理降低严重度但不改变分类以及集成标记使声明的外部资源合法化但不使固定睡眠或无断言的执行合法化。对照 Swift 生成扩展 的 Mocking 规则可以推断其设计哲学Swift 没有 Mockito 等价物应偏向协议导向设计——为依赖定义 protocol、经初始化器注入、在测试 target 中实现 fake/stub structURL/HTTP 用URLProtocol子类拦截URLSession请求日期/时钟注入ClockContinuousClock、SuspendingClock或自定义Clock类型一个测试需要 3 个以上 mock 就标记为设计味道。集成测试标记识别集成/UI/E2E 测试以校准严重度文件夹约定IntegrationTests/、UITests/、E2ETests/类名后缀*IntegrationTests、*UITestsXCUITestXCUIApplication、XCUIElement→ UI/E2E 测试Swift TestingTag命名为.integration或.ui集成标记的作用在 test-smell-detection 中体现为严重度校准集成标记使声明的外部资源和多步骤流程合法化——识别出集成测试后其外部依赖不再单独加重 Mystery Guest 严重度但固定睡眠与无断言执行仍照常判味。Setup/Teardown 生命周期两套框架的夹具模型FrameworkPer-testPer-class/suiteXCTestsetUp() / setUpWithError()override class func setUp()XCTesttearDown() / tearDownWithError()override class func tearDown()Swift Testing每个实例init(...) async throws通过Suite类型静态化Swift Testingdeinit做清理通过Suite类型静态化文档特别强调Swift Testing 默认每个测试创建一个全新实例——init中初始化的字段会在测试之间重置。这一语义直接影响 General Fixture过度宽泛的共享夹具味道的判定Swift Testing 下不存在 XCTest 那种同一个实例复用于多个测试的隐式状态泄漏但Suite上的共享设置若与多数测试无关仍需按字段被少于 50% 测试使用的规则标记。XCTest 侧则要区分实例方法setUp()每个测试执行与类方法override class func setUp()整个类执行一次。标签/特性属性test-tagging的 Swift 支持策略对于test-tagging技能Swift 是文档中少数双轨制语言FrameworkTag mechanismExampleSwift TestingTest(.tags(.positive, .boundary))预定义或自定义标签需要extension Tag { Tag static var positive: Self }Swift Testing (suite)Suite(.tags(...))标签继承给其中包含的测试XCTest无内置机制——用类组织、命名或测试计划.xctestplan(report-only)文档给出标签定义的标准位置——在单个模块级位置统一定义标签extension Tag { Tag static var positive: Self Tag static var negative: Self Tag static var boundary: Self Tag static var integration: Self }结合 test-tagging 的 Swift 示例Test(.tags(.negative, .boundary)) func parseNullInputThrows() throws { ... }可以总结test-tagging对 Swift 的完整处理流程Step 1 能力判定Swift Testing →auto-edit可写Test(.tags(...))/Suite(.tags(...))纯 XCTest →report-only只输出 Markdown 映射表不修改源码Step 2 扫描已有标签检查测试是否已带Tag(.name)避免重复Step 3 逐测试分类按方法名、断言类型、输入值nil//0/边界值、设置复杂度、注释中的 issue 号等 15 条启发式规则分类到positive/negative/boundary/critical-path/smoke/regression/integration/performance等 16 个预定义 trait 值——performance的启发式明确列出 Swift 的XCTMetricStep 5 生成分布摘要报告 positive 与 negative 比例、关键路径覆盖等且注明百分比可超 100%因单个测试可有多个 trait。值得注意的分类规则细节boundary是附加标签——边界成功用例仍计为positive被拒绝的边界输入仍计为negativeconcurrencytrait 的启发式在 Swift 侧对应DispatchQueue/actor等并发原语。语言特定校准注意事项避免误报的 8 条规则文档结尾的校准清单是分析技能避免误报的护栏每条都直接映射到具体味道判定Swift Testing#expect失败后继续try #require中止——混合前置条件与断言的测试前置条件应使用try #requireXCTAssert*失败后继续——含多个级联断言的测试可能因单一根因记录大量失败这是 Assertion Roulette 严重度判定的输入异步测试必须await——缺失await会在异步 API 上产生警告和静默跳过。这一点在 assertion-quality 的校准规则 中被提升为异步测试未 await 断言 → 即使断言调用存在也视为无断言TUnit、Jest.resolves/.rejects、pytest-asyncio、Swift Testing、Kotest 同列其中Combine 测试使用expectation(description:)是 XCTest 惯用异步模式不是睡眠味道快照测试SnapshotTesting库——快照比较视为合法断言标记过期的快照记录stale records参数化测试Test(arguments: [...])不是重复测试——这与 test-anti-patterns 的数据驱动测试不视为重复规则一致**测试计划.xctestplan**可按标签/配置过滤——作为逐测试打标签之外的结构性替代方案提出continueAfterFailure—— 设为false时 XCTest 在首次失败即停止适用于快速失败的集成测试。其中第 5、6 条与assertion-quality的校准规则完全同构快照断言计为 Structural/Deep 断言、属性测试按生成用例的内层断言逻辑计数而非外层脚手架test-gap-analysis的语义也与第 6 条一致参数化是合并形态不是重复覆盖。消费方技能如何加载本扩展整套机制的运行链路可从 test-analysis-extensions/SKILL.md 的 Usage 一节还原检测目标代码库的主要语言与测试框架在执行分析之前读取匹配的扩展文件若同时存在多个测试框架如 Swift 项目中 XCTest 与 Swift Testing 混用读取所有相关扩展各扩展文件覆盖相同类别使分析技能保持语言中立。具体到 Swift 场景test-smell-detection 在其工作流中要求对不熟悉的框架 API先调用test-analysis-extensions并读取匹配的语言扩展assertion-quality 则强制在分类断言前必须读扩展文件因为跨框架断言 API 差异显著。test-tagging 给出兜底策略尝试test-analysis-extensions一次若不可用立即继续使用内置框架表绝不让标签流程阻塞在辅助技能上——内置表中 Swift Testing 的Tag(.name)语法与扩展文件一致形成双层保障。结语swift.md虽然是一份纯参考数据文件但它是 Swift 测试分析能力的事实源头从测试发现、断言分类、睡眠/跳过识别到 Mystery Guest 判定、集成标记校准、Setup/Teardown 建模与标签写入策略六个 polyglot 分析技能的全部 Swift 行为都以这份表为基准再叠加 code-testing-extensions 的 Swift 扩展生成侧视角与 dotnet-test 插件 README整体架构视角形成闭环。对希望在自有流水线中复用这套 Swift 测试分析能力的开发者而言最直接的落地方式就是把本文件作为检测规则字典接入分析工具并严格遵循其能力标签与校准注意事项——尤其是Swift Testing 可 auto-edit 标签、XCTest 仅 report-only的双轨策略以及await缺失即静默跳过这一最容易造成假阳性报告的语言陷阱。【免费下载链接】skillsRepository for skills to assist AI coding agents with .NET and C#项目地址: https://gitcode.com/GitHub_Trending/skills17/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考