Nexus/.cursor/skills/test-driven-development/testing-anti-patterns.md

测试反模式

在以下情况加载此参考： 编写或修改测试、添加 mock、或想在生产代码中添加仅测试用方法时。

概述

测试必须验证真实行为，而非 mock 行为。Mock 是隔离的手段，不是被测试的对象。

核心原则： 测试代码做了什么，而非 mock 做了什么。

严格遵循 TDD 可以防止这些反模式。

铁律

1. 绝不测试 mock 行为
2. 绝不在生产类中添加仅测试用的方法
3. 绝不在不理解依赖的情况下使用 mock

反模式 1：测试 Mock 行为

违规做法：

// ❌ 差：测试 mock 是否存在
test('renders sidebar', () => {
  render(<Page />);
  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
});

为什么这是错误的：

• 你在验证 mock 能工作，而非组件能工作
• mock 存在时测试通过，不存在时失败
• 对真实行为一无所知

你的人类伙伴的纠正： "我们是在测试 mock 的行为吗？"

正确做法：

// ✅ 好：测试真实组件或不要 mock 它
test('renders sidebar', () => {
  render(<Page />);  // 不要 mock sidebar
  expect(screen.getByRole('navigation')).toBeInTheDocument();
});

// 或者如果必须 mock sidebar 来隔离：
// 不要对 mock 做断言——测试 Page 在 sidebar 存在时的行为

门控函数

在对任何 mock 元素做断言之前：
  问："我是在测试真实组件行为还是仅仅测试 mock 的存在？"

  如果是测试 mock 的存在：
    停下——删除断言或取消 mock

  改为测试真实行为

反模式 2：在生产代码中添加仅测试用方法

违规做法：

// ❌ 差：destroy() 仅在测试中使用
class Session {
  async destroy() {  // 看起来像生产 API！
    await this._workspaceManager?.destroyWorkspace(this.id);
    // ... 清理
  }
}

// 在测试中
afterEach(() => session.destroy());

为什么这是错误的：

• 生产类被仅测试用的代码污染
• 如果在生产环境中意外调用会很危险
• 违反 YAGNI 和关注点分离
• 混淆了对象生命周期和实体生命周期

正确做法：

// ✅ 好：测试工具处理测试清理
// Session 没有 destroy()——它在生产中是无状态的

// 在 test-utils/ 中
export async function cleanupSession(session: Session) {
  const workspace = session.getWorkspaceInfo();
  if (workspace) {
    await workspaceManager.destroyWorkspace(workspace.id);
  }
}

// 在测试中
afterEach(() => cleanupSession(session));

门控函数

在向生产类添加任何方法之前：
  问："这只被测试使用吗？"

  如果是：
    停下——不要添加
    放到测试工具中

  问："这个类是否拥有此资源的生命周期？"

  如果否：
    停下——这个方法不属于这个类

反模式 3：不理解依赖就使用 Mock

违规做法：

// ❌ 差：Mock 破坏了测试逻辑
test('detects duplicate server', () => {
  // Mock 阻止了测试依赖的配置写入！
  vi.mock('ToolCatalog', () => ({
    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
  }));

  await addServer(config);
  await addServer(config);  // 应该抛异常——但不会！
});

为什么这是错误的：

• 被 mock 的方法有测试依赖的副作用（写入配置）
• "保险起见"过度 mock 破坏了实际行为
• 测试因错误的原因通过或莫名其妙地失败

正确做法：

// ✅ 好：在正确的层级 mock
test('detects duplicate server', () => {
  // Mock 慢的部分，保留测试需要的行为
  vi.mock('MCPServerManager'); // 只 mock 慢的服务器启动

  await addServer(config);  // 配置被写入
  await addServer(config);  // 检测到重复 ✓
});

门控函数

在 mock 任何方法之前：
  停下——先不要 mock

  1. 问："真实方法有什么副作用？"
  2. 问："这个测试是否依赖这些副作用？"
  3. 问："我完全理解这个测试需要什么吗？"

  如果依赖副作用：
    在更底层 mock（实际的慢操作/外部操作）
    或使用保留必要行为的测试替身
    而非测试依赖的高层方法

  如果不确定测试依赖什么：
    先用真实实现运行测试
    观察实际需要发生什么
    然后在正确的层级添加最少的 mock

  危险信号：
    - "我 mock 一下保险"
    - "这可能慢，还是 mock 掉吧"
    - 不理解依赖链就 mock

反模式 4：不完整的 Mock

违规做法：

// ❌ 差：部分 mock——只包含你认为需要的字段
const mockResponse = {
  status: 'success',
  data: { userId: '123', name: 'Alice' }
  // 缺失：下游代码使用的 metadata
};

// 之后：代码访问 response.metadata.requestId 时崩溃

为什么这是错误的：

• 部分 mock 隐藏了结构假设 — 你只 mock 了你知道的字段
• 下游代码可能依赖你没包含的字段 — 静默失败
• 测试通过但集成失败 — mock 不完整，真实 API 完整
• 虚假的信心 — 测试对真实行为什么也没证明

铁律： Mock 真实存在的完整数据结构，而非只包含你当前测试用到的字段。

正确做法：

// ✅ 好：镜像真实 API 的完整性
const mockResponse = {
  status: 'success',
  data: { userId: '123', name: 'Alice' },
  metadata: { requestId: 'req-789', timestamp: 1234567890 }
  // 真实 API 返回的所有字段
};

门控函数

在创建 mock 响应之前：
  检查："真实 API 响应包含哪些字段？"

  操作：
    1. 从文档/示例中查看实际 API 响应
    2. 包含系统下游可能消费的所有字段
    3. 验证 mock 完全匹配真实响应的结构

  关键：
    如果你在创建 mock，你必须理解完整的结构
    部分 mock 在代码依赖遗漏字段时会静默失败

  不确定时：包含所有文档记录的字段

反模式 5：集成测试作为事后补充

违规做法：

✅ 实现完成
❌ 没写测试
"准备好测试了"

为什么这是错误的：

• 测试是实现的一部分，不是可选的后续
• TDD 本可以防止这种情况
• 没有测试就不能声称完成

正确做法：

TDD 循环：
1. 编写失败的测试
2. 实现使其通过
3. 重构
4. 然后才声称完成

当 Mock 变得过于复杂时

警告信号：

• Mock 的 setup 比测试逻辑还长
• 为了让测试通过而 mock 一切
• Mock 缺少真实组件拥有的方法
• Mock 变更时测试就坏了

你的人类伙伴的问题： "我们这里真的需要用 mock 吗？"

考虑： 使用真实组件的集成测试往往比复杂的 mock 更简单

TDD 如何防止这些反模式

TDD 有帮助的原因：

1. 先写测试 → 迫使你思考你到底在测什么
2. 看它失败 → 确认测试测的是真实行为，不是 mock
3. 最少实现 → 仅测试用方法不会混入
4. 真实依赖 → 你在 mock 之前看到测试实际需要什么

如果你在测试 mock 行为，你违反了 TDD — 你在没有先用真实代码让测试失败的情况下就加了 mock。

快速参考

反模式	修复方式
对 mock 元素做断言	测试真实组件或取消 mock
生产代码中的仅测试用方法	移到测试工具中
不理解就 mock	先理解依赖，最少 mock
不完整的 mock	完整镜像真实 API
测试作为事后补充	TDD——先写测试
过于复杂的 mock	考虑集成测试

危险信号

• 断言检查 *-mock test ID
• 方法仅在测试文件中被调用
• Mock setup 占测试的 >50%
• 移除 mock 测试就失败
• 无法解释为什么需要 mock
• "保险起见" mock 掉

底线

Mock 是隔离的工具，不是被测试的对象。

如果 TDD 揭示你在测试 mock 行为，你已经走偏了。

修复方法：测试真实行为，或质疑为什么要 mock。