tdd

测试驱动开发（TDD）

使用此技能执行严格的测试优先开发：先编写一个失败的测试，再实现通过测试所需的最少代码，最后在保持测试通过的同时进行重构。

决定何时使用 TDD

使用以下决策表：

情况	使用此技能？	默认操作
新的实用函数	是	立即执行 TDD 循环
新的 Effect 服务	是	先通过测试定义行为
复杂的业务逻辑	是	在实现前通过测试锁定行为
修复 Bug	是	先用失败的测试复现 Bug
仅更改 UI 样式/布局	否	使用标准实现流程
探索性原型开发	否	先制作原型，待行为稳定后再切换到 TDD
TRPC 端点（简单 CRUD）	通常不需要	默认使用 testing-patterns；仅在用户明确要求测试优先/RGR 时使用此技能

---

执行 Red-Green-Refactor

一次只围绕一个行为，按三个阶段执行。

1. RED - 先编写失败的测试

import { describe, expect, it } from "vitest";
import { calculateDiscount } from "../calculate-discount";

describe("calculateDiscount", () => {
  it("applies 10% discount for orders over 100", () => {
    // This test fails first: function does not exist yet
    expect(calculateDiscount(150)).toBe(135);
  });
});

运行测试，确认它失败：

bun run vitest run packages/common/src/__tests__/calculate-discount.test.ts

2. GREEN - 实现最少代码

编写通过测试所需的最少代码：

// packages/common/src/calculate-discount.ts
export function calculateDiscount(amount: number): number {
  if (amount > 100) {
    return amount * 0.9;
  }
  return amount;
}

运行测试，确认它通过：

bun run vitest run packages/common/src/__tests__/calculate-discount.test.ts

3. REFACTOR - 在不破坏行为的前提下改进

在保持测试通过的同时提升代码质量：

const DISCOUNT_THRESHOLD = 100;
const DISCOUNT_RATE = 0.1;

export function calculateDiscount(amount: number): number {
  if (amount <= DISCOUNT_THRESHOLD) {
    return amount;
  }
  return amount * (1 - DISCOUNT_RATE);
}

再次运行测试，确认重构没有破坏任何内容。

如需更多示例、失败诊断和迭代扩展示例，请阅读 references/red-green-refactor.md。

---

保持测试范围精简

优先选择轻量级测试，仅在需要时再升级：

1. 单元测试（首选）- 纯函数和带有模拟层的 Effect 服务。
2. TRPC 集成测试 - 完整的 TRPC + 持久化行为。
3. E2E 测试 - 浏览器级别的流程和用户旅程。

情况	测试类型	操作
纯函数、解析器、实用工具	单元	立即编写
带有依赖项的 Effect 服务	使用模拟层的单元测试	立即编写
TRPC 过程（数据库逻辑）	TRPC 集成测试	遵循 testing-patterns 决策流程
面向用户的流程、UI 行为	E2E	遵循 testing-patterns 决策流程

---

应用 Effect 专用的 TDD 模式

通过明确的层采用测试优先的服务设计。

1. 通过测试定义接口 - 在实现前明确行为。
2. 创建模拟层 - 隔离依赖项并确保测试具有确定性。
3. 实现服务 - 以最少的行为满足测试要求。
4. 重构 - 在保留行为的同时提升可读性并改进结构。

import { describe, expect, it } from "@effect/vitest";
import { Effect, Layer } from "effect";

describe("PricingService", () => {
  // 1. Define what the service should do via tests
  it.effect("calculates base price without discount", () =>
    Effect.gen(function* () {
      const service = yield* PricingService;
      const result = yield* service.calculatePrice({
        itemId: "item-1",
        quantity: 2,
      });
      expect(result.total).toBe(200);
    }).pipe(Effect.provide(testLayer)),
  );

  it.effect("applies bulk discount for quantity > 10", () =>
    Effect.gen(function* () {
      const service = yield* PricingService;
      const result = yield* service.calculatePrice({
        itemId: "item-1",
        quantity: 15,
      });
      expect(result.total).toBe(1350); // 15% discount
    }).pipe(Effect.provide(testLayer)),
  );
});

模拟层工厂模式

// Create parameterized mock layers for different test scenarios
const createMockInventoryLayer = (inventory: Map<string, number>) =>
  Layer.succeed(InventoryService, {
    getStock: (itemId) => Effect.succeed(inventory.get(itemId) ?? 0),
    reserveStock: (itemId, qty) => Effect.succeed(void 0),
  });

// Use in tests
const testLayer = PricingService.layer.pipe(
  Layer.provide(createMockInventoryLayer(new Map([["item-1", 100]]))),
);

如需深入了解错误路径测试、层组合以及反对使用 vi.mock() 的理由，请阅读 references/effect-tdd-patterns.md。

---

使用项目约定的测试位置（示例）

将这些路径视为项目约定或示例；如果仓库采用不同的测试布局，请相应调整。

代码位置	测试位置
packages/X/src/file.ts	packages/X/src/__tests__/file.test.ts
apps/web-app/src/infrastructure/trpc/routers/X.ts	apps/web-app/src/__tests__/X.test.ts
apps/web-app/src/routes/**	apps/web-app/e2e/feature.e2e.ts

---

使用辅助参考资料深入了解

执行期间请加载针对性的参考资料，而不是扩展此文件：

• 使用 references/commands.md 查看可运行的命令模式。
• 使用 references/anti-patterns.md 查看失败模式演练及修正方法。

资源

references/

• red-green-refactor.md - 详细的 TDD 循环工作流及示例
• effect-tdd-patterns.md - Effect 服务测试、模拟层和错误用例
• test-first-examples.md - 本代码库的逐步 TDD 示例
• commands.md - 命令目录以及正确和错误的调用模式
• anti-patterns.md - 详细的 TDD 反模式演练及修复方法

相关技能

• testing-patterns - 测试语法、TRPC 集成测试和 E2E 模式
• effect-ts - Effect 服务设计、层和错误处理