Node.js 测试命名最佳实践：让每个测试名称包含 3 个组成部分（被测对象 + 场景 + 期望结果）

导读

本文基于 Node.js 最佳实践开源仓库（nodebestpractices）中“Testing and Overall Quality Practices”章节的 4.2 条目，系统讲解如何为每个测试命名时强制注入 3 个组成部分：被测对象是什么（What）、在什么场景下（When）、期望得到什么结果（Then）。掌握这套命名规范后，你的测试报告将像一份可读的需求文档，测试人员、负责部署的 DevOps 工程师以及两年后的你，都能在不阅读测试实现代码的情况下，一眼判断当前应用版本是否满足业务需求。

为什么测试名称需要表达“需求”，而不是“代码”

在 3-parts-in-name.md（本文所依据的原始英文文档）与 3-parts-in-name.russian.md（俄语译本）中，核心论点是一致的：一份测试报告应当能够回答“当前应用版本是否满足需求”，而它的读者往往并不熟悉代码本身：

• 测试人员：需要核对测试覆盖与验收标准是否对应；
• 部署上线的 DevOps 工程师：需要判断这个版本能否安全发布；
• 两年后的你：早已遗忘当时的实现细节，需要快速恢复上下文。

如果测试名称只描述“代码做了什么”，读者就必须钻进 describe/it 的实现体里去猜意图，这违背了测试作为“回归安全网”和“可执行需求文档”的双重价值。因此，最佳实践要求每个测试用例的名称都以**需求语言（requirements level）**来表述，并且天然包含 3 个组成部分。

三部分命名法的完整拆解

一个符合规范的测试名称应依次回答三个问题：

序号	组成部分	回答的问题	示例
(1)	被测对象（Unit under test）	正在测试什么？	ProductsService.addNewProduct 方法
(2)	场景（Scenario）	在什么条件下、什么场景下？	调用方法时未传入价格
(3)	期望结果（Expectation）	期望得到什么结果？	新产品处于“待审批”状态

将三部分连缀成一句话，便是一个自解释的测试用例名，例如：“When no price is specified, then the product status is pending approval”（当未指定价格时，产品状态为待审批）。

三部分分别落到测试框架的哪一层

在 Mocha/Jest 等常见测试框架中，这套命名法可以通过嵌套结构自然落地（对应英文原版 3-parts-in-name.md 的示例）：

• describe（第 1 层）：承载“被测对象”，如 Products Service；
• describe（第 2 层）：承载“被测行为/动作”，如 Add new product；
• it/test：承载“场景 + 期望结果”，如 When no price is specified, then the product status is pending approval。

这样一来，测试报告在终端或 CI 面板上的输出本身就形成了一份可读的树状需求清单。

正确示例：三段式命名的正面模式

以下是文档提供的完整正面示例，代码注释标明了每一层的职责（见 3-parts-in-name.russian.md）：

//1. unit under test —— 被测对象
describe('Products Service', () => {
  describe('Add new product', () => {
    //2. scenario and 3. expectation —— 场景与期望结果
    it('When no price is specified, then the product status is pending approval', () => {
      const newProduct = new ProductService().add(...);
      expect(newProduct.status).to.equal('pendingApproval');
    });
  });
});

阅读这个测试时，你甚至不需要看 it 回调里的实现，仅凭嵌套的 describe 与 it 名称，就能复述出这条业务规则：“在 Products 服务中新增产品时，如果不传价格，新产品应处于 pendingApproval 状态”。这正是测试作为“可执行需求文档”的体现。

反模式：必须通读测试代码才能理解意图

以下是文档给出的反面对比示例（见 3-parts-in-name.russian.md）：

describe('Products Service', () => {
  describe('Add new product', () => {
    it('Should return the right status', () => {
        //hmm, what is this test checking? what are the scenario and expectation?
      const newProduct = new ProductService().add(...);
      expect(newProduct.status).to.equal('pendingApproval');
    });
  });
});

这个反模式的问题一目了然：

1. “Should return the right status” 只说“返回了正确的状态”，却没有说明输入条件和场景（价格缺失）与期望结果（待审批）；
2. 代码注释中的反问 hmm, what is this test checking? 正是痛点：读者被迫进入实现体，逐行推断断言在验证什么；
3. 当测试套件规模增长后，这类“模糊命名”的用例会显著增加回归排查与需求追溯的成本。

判断准则：如果一个用例的名称被删除后，你必须阅读其实现才能说清它在验证什么业务规则，那么它就是不合格的命名。

如何落地：命名模板与自查清单

把三部分命名法固化为团队约定，可以使用统一的“句式模板”：

When <场景条件>, then <期望结果>

• 场景条件尽量具体：no price is specified、customer spent more than 500$、site name is already taken；
• 期望结果尽量是“可观察的业务状态”：the product status is pending approval、the update returns success confirmation、the customer is classified as premium；
• 避免使用模糊词：right、correct、properly、works、should work 等无法传达业务含义的词汇。

实践进阶：命名三部分与报告输出的配合

在仓库配套的 6-parts-in-test.jpg 相关的“测试报告如需求文档”理念中，Yoni Goldberg（本仓库作者、Node.js 测试实践专家）进一步提出，测试报告应尽量呈现出“类似需求文档”的观感。下方为文档引用的真实测试报告示例，可以直观看到按三段式命名后，测试输出如何像一份需求清单一样逐条陈述业务规则：

测试报告示例：三段式命名让测试输出像一份需求文档

当 describe 层级用于承载被测对象与行为、it 名称用于承载“场景 + 期望”时，CI 平台、测试覆盖率工具与控制台输出的每一行，都是可被非代码人员直接阅读的需求条目。

与仓库其他测试实践的关系：形成完整的“可读测试”体系

三部分命名法不是孤立的技巧，它与仓库中同属“Testing And Overall Quality Practices”章节的其他条目互为补充，共同构成一套“测试即文档”的方法论：

• AAA 模式（Arrange-Act-Assert）：命名只解决“读者能读懂意图”，而测试体内部还需要用“准备-执行-断言”三段式结构，让读者无需解析命令式代码逻辑。两者结合，外部名称与内部结构都保持声明式、可速读；
• 避免全局测试夹具（Avoid global test fixtures）：每个用例应独立准备自己的数据。只有数据自给自足，三段式命名中的“场景”才是真实可复现的，而不是依赖某个隐藏的 seed 文件；
• 覆盖五种可能的输出（Test the five potential outcomes）：命名中的“期望结果”应覆盖响应、新状态、外部调用、消息队列、可观测性等五种业务输出类型，避免只断言 HTTP 响应而遗漏数据变更与日志埋点。

从仓库结构看，README.md 的目录将本条列为 4.2 Include 3 parts in each test name，并标记为 #new（新增实践），与 AAA、测试夹具、中间件隔离测试、端口随机化等条目并列，说明它是整体测试质量基线中的基础一环：在动手写断言之前，先把用例的“身份”——名称——写好。

小结

为每个测试名称包含 3 个组成部分（被测对象 / 场景 / 期望结果），是把测试套件从“面向实现的验证脚本”升级为“面向需求的可执行文档”的最低成本手段。它不依赖任何工具或框架，只依赖命名纪律：

1. 用外层 describe 声明被测对象与行为；
2. 用 it 名称按 When <场景>, then <期望> 的模板描述业务规则；
3. 拒绝 Should return the right status 这类语义模糊的命名；
4. 与 AAA 结构、每测试独立数据、五种输出覆盖等实践组合使用。

下次运行测试时，请先看一眼终端输出的用例名称——如果它像一份需求清单，说明你的测试命名已经达标。