Community编程与开发github.com

单元测试

针对设计、编写、审查和改进语言无关的单元测试提供指导:涵盖测试用例、边界情况、测试替身(模拟桩、存根、伪造对象)、不稳定或脆弱的测试、缺失场景。当用户要求添加、修复、审查或扩展测试,为函数编写测试,或报告不稳定或失败的测试时使用,即使他们未明确提及“单元测试”。如果存在语言特定的单元测试技能,请一并使用。不适用于端到端、性能或基础设施测试。

单元测试 是什么?

该技能为AI代理(如Claude Code、Cursor、Codex)提供了一套全面的、语言无关的单元测试编写与审查指南。其核心原则是测试行为而非实现细节,确保测试可靠、可读、可维护,并专注于验证可观察的契约。技能覆盖了完整的测试生命周期,包括用例设计、测试替身(存根、伪造对象、模拟桩)的审慎选择、断言最佳实践以及测试结构命名。它还详细定义了工作流程(从阅读语言特定技能到报告结果)、审查现有测试的优先级排序方法(高、中、低),以及一个严格的验证步骤,包括检查测试的敏感性(通过突变测试)和可靠性(重复运行、随机顺序运行)。该技能明确排除了端到端、性能和基础设施测试,并设立了约束,例如不得修改生产代码以使测试通过,以及不得删除现有测试来维持通过率。其最终目标是确保AI辅助的测试工作能产出高质量、稳固的测试套件,这些测试能真正验证功能,支持重构,并在不同环境下保持确定性。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lukeweb/ai-coding-agent-skills/tree/HEAD/skills/unit-testing

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

单元测试 是做什么的?

目的

确保单元测试可靠、可读、可维护,并能验证可观察的行为。

这是一个基础技能。语言特定的技能可以添加框架、命名和工具细节,但不得与下文的核心原则或约束相矛盾。

范围

在内:

  • 设计测试用例。
  • 编写新的单元测试。
  • 改进和审查现有的单元测试。

不在内:

  • 端到端测试。
  • 性能测试。
  • 基础设施测试。

单元测试验证的是隔离状态下、与不受控的外部系统和副作用无关联的、聚焦的行为单元。

单元测试不应依赖实时网络服务、共享数据库、外部基础设施或不受控的挂钟时间。

受控的内存实现、临时资源和确定性的本地依赖是可以接受的,只要它们有助于验证单元的行为,且不损害隔离性或可靠性。

如果用户要求需要实时外部系统的测试,请声明这超出了本技能的范围,并建议使用集成测试。

对于依赖全局状态或单例但缺乏测试接缝的代码,通过约束来处理:报告问题,而不是围绕它工作(例如,通过修补全局变量)。

优先级

当指令发生冲突时,按以下顺序应用:

  1. 显式的用户指令。
  2. 本技能的核心原则和约束。
  3. 现有项目的约定和工具(框架、命名、结构、辅助函数)。
  4. 语言特定的技能。
  5. 本技能中的测试设计指导。

项目约定永远不能凌驾于核心原则或约束之上(例如,验证每个模拟桩调用的约定不能成为测试实现细节的理由)。

核心原则

测试行为,而非实现

验证可观察的契约:返回值、通过公共API可见的状态变更、错误,以及属于契约一部分的副作用(例如,发布的事件、保存的记录)。

当实现被重构且行为不变时,测试必须仍然有效。

不要直接测试私有成员;通过公共API验证它们的行为。

从契约而非代码中推导预期

预期行为必须主要从显式需求、验收标准和权威文档中推导。

将公共API、方法名、签名和现有测试作为辅助证据,而非决定性规格说明。

将当前实现视为实际行为的证据,而非预期行为的来源。

如果实现与既定契约相矛盾,报告差异,而不是将错误行为编码到测试中。

如果预期行为不明确:

  • 如果歧义影响多个测试或重要场景的结果,且可以询问用户,则在编写这些测试之前询问。
  • 否则,选择最保守的解释,用简短的注释标记测试,说明该假设,并在报告中列出该假设。

如果不存在契约(遗留代码)且用户显式要求在进行重构之前固定当前行为,则编写特征化测试:将其命名或标记为特征化测试,并在报告中说明这些测试记录的是实际行为,而非已验证行为。

保持测试隔离

每个测试必须独立于执行顺序和共享的可变状态。

每个测试应建立并清理自身所需的状态和资源。

测试不能依赖于其他测试的副作用。

保持测试确定性

测试必须产生可预测和可重现的结果,不受执行顺序、机器或环境的影响。

控制非确定性的来源:

  • 当前时间和日期。
  • 随机数生成器。
  • UUID和ID生成。
  • 外部服务。
  • 环境相关配置。
  • 映射和集合的迭代顺序。
  • 时区和区域设置。
  • 浮点数比较。
  • 线程或任务调度。

优先使用依赖注入使非确定性依赖可控。

只有在生成器被注入到单元中,并且测试断言的行为不依赖于特定生成值时,才可以使用固定种子。

对于确定性、快速、进程内的协作者,如果它们不损害测试隔离或可靠性,优先使用真实实现。

当依赖引入不受控的副作用、外部状态、非确定性或不必要的复杂性时,使用适当的测试替身。

工作流程

在编写或改进单元测试时:

  1. 如果存在语言特定的单元测试技能,请在开始前阅读它。
  2. 阅读被测单元、其公共API和文档,以识别预期契约。
  3. 审查现有测试:框架、命名、结构、约定和可用的辅助函数。
  4. 运行现有的相关测试以建立基线。注意任何预先存在的失败;不要将其归因于你的更改,除非被要求,否则不要修复它们。
  5. 识别该单元的职责和依赖。
  6. 决定哪些依赖应保持真实,哪些需要测试替身。
  7. 识别相关场景,并优先处理那些在实际中可能出错的场景。
  8. 按照项目约定实现测试。
  9. 执行下面的验证步骤。
  10. 报告结果、假设和未解决的问题。

当被要求审查现有测试时,请遵循“审查现有测试”。

测试设计

场景检查清单

在相关时考虑以下场景:

  • 正常执行路径。
  • 边界条件(空、零、一、最大值、差一错误的情况)。
  • 无效输入。
  • 错误处理和失败路径。
  • 重要的状态转换。
  • 有意义的条件组合。
  • 必须始终成立的重要不变量。当项目工具支持时,基于属性的测试非常适合不变量。

不要仅仅为了提高代码覆盖率数字而添加测试。

对于错误修复,首先编写一个能重现该错误的测试,并确认它因正确原因而失败。如果修复在范围内,则之后确认测试通过。如果未授权更改生产代码,则报告重现器而不是留下一个未宣布的失败测试,并询问是否保留它。

测试替身

有目的地使用测试替身,并为场景选择适当的类型:

  • 存根:为依赖调用提供受控的响应。
  • 伪造对象:提供简化的可行实现。
  • 模拟桩:验证与依赖的预期交互。
  • 间谍:记录交互以供后续验证。

当依赖具有可以通过轻量级实现表示的有意义行为时,优先使用伪造对象(简单的内存实现)而非模拟桩。

仅在交互本身是预期契约的一部分时才断言交互,例如必须发送通知或某调用绝不能发生。

除非调用次数或调用顺序明确是预期行为的一部分,否则不要断言它们。

当现有包装器或边界上的伪造对象可用时,不要模拟你不拥有的类型。在生产代码中创建新的包装器需要用户批准(见约束)。

永远不要模拟被测单元。

断言

断言特定结果,而不仅仅是执行完成没有错误或结果不为空。

断言应验证可观察的行为,并区分正确和不正确的结果。

对于错误,断言相关的错误契约:类型、类别、代码或其他稳定的错误属性。

仅在消息内容是预期行为的一部分或提供稳定、有意义的保证时才断言其内容。

避免那些即使行为错误也会通过的断言(例如,仅检查结果的长度)。

除非日志记录是预期契约的一部分,否则不要断言日志输出。

结构和命名

每个测试应聚焦于一个逻辑场景或行为。

当多个断言验证同一行为的不同方面时,是可以接受的。

根据场景和预期结果命名测试,例如 rejects_expired_token,而不是 test1 或 testValidate。命名风格仅供参考;请遵循项目约定。

当它能提高可读性时,使用 Arrange / Act / Assert 模式。

保持预期值为字面量和显式值。切勿在测试中计算预期值,特别是通过重用实现逻辑。

循环仅可用于遍历显式的表格用例,或用于框架的参数化或基于属性的机制。如果测试体根据用例字段分支(例如错误与成功),且分支增多,则将其拆分为独立的测试或表格。

使测试数据不言自明。对含义不明显的值进行命名或注释。

使用合成测试数据。切勿使用真实凭证、个人数据或生产数据转储。

当多个用例共享相同结构时,使用项目的参数化机制;否则,保持用例独立。

在测试中倾向于少量重复,而非隐藏测试功能的抽象。

当现有项目辅助函数能提高清晰度和一致性时,重用它们。

仅为非显而易见的行为或测试决策添加注释。

上述未涵盖的反模式

  • 测试第三方库或框架代码,而非单元自身行为。
  • 测试没有逻辑的简单 getter 或 setter。
  • 使用 sleep 同步并发代码,而不是控制时间或使用显式同步。

审查现有测试

当被要求审查而非编写测试时:

  1. 确定单元的契约(见核心原则)。
  2. 根据核心原则和测试设计检查每个测试。通过运行测试(例如,对于怀疑不稳定的测试进行重复运行)来确认疑似问题,而不是猜测。
  3. 首先按优先级汇报发现:
    • 高:当行为被破坏时通过、编码了错误、不稳定或顺序依赖。
    • 中:与实现耦合、缺少重要场景。
    • 低:命名、可读性、重复。
  4. 分别列出缺失的场景。
  5. 仅在报告发现后更改测试,除非用户直接要求修复。

约束

  • 不得为通过测试而修改生产代码。如果单元难以测试(例如,缺乏用于时间、随机性或依赖的接缝),请报告问题并提出最小的必要更改。只有在获得用户明确批准后才可应用。

  • 现有测试可以被重构或改进,但最终验证的范围绝不能少于之前。不得删除、禁用或削弱它们以使测试套件通过。

  • 除非需求已合法更改,否则不得更改现有断言的预期值;在报告中解释此类更改。允许使断言更严格或更精确。

  • 当现有项目工具足够时,不得引入新的测试框架或依赖。

验证

  1. 使用项目自身的测试命令运行新的或修改过的测试。

  2. 运行周围的包或模块测试,然后运行完整的测试套件,除非它太慢。如果跳过了完整套件,请在报告中说明。

  3. 检查测试敏感性。

    重要测试是指覆盖条件逻辑、错误路径和边界值的测试;琐碎的映射或传递测试被排除在外。

    对于每个重要测试,识别至少一个生产行为中的现实更改,该更改会导致它失败(翻转的条件、移动的边界、移除的错误处理)。如果无法做到,请增强断言。

    如果项目中已配置了变异测试工具,则对更改的代码运行它。

    仅当被触及的文件没有未提交的更改(或以可丢弃的副本或工作目录完成工作)且之后能精确还原原始文件时,才允许手动变异生产代码。否则跳过,并在报告中说明。切勿覆盖或还原无关的用户更改。

  4. 检查可靠性。

    验证测试在重复运行时通过,并在工具支持时以随机或倒序顺序运行。

    检查是否有残留状态、资源或副作用。

  5. 调查失败。

    确定根本原因,并将每个失败分类为测试缺陷或生产缺陷。

    切勿仅为了通过测试而修改断言。

    报告未解决的失败及其可能原因。

报告

提供一个简洁的摘要,包含:

  • 创建或修改的测试。
  • 执行的命令及其结果。
  • 观察到的预先存在的失败(非由你的更改引起)。
  • 发现的疑似生产缺陷。
  • 关于预期行为所做的假设。
  • 跳过或无法执行的验证步骤及其原因。绝对不要报告测试通过,除非它们已被执行。
  • 未解决的失败或限制。

相关技能