Tdd

Test-Driven Development (TDD)

Apply this skill to execute strict test-first development: write a failing test, implement the minimum code to pass, then refactor while keeping tests green.

Decide when to use TDD

Use this decision table:

Execute Red-Green-Refactor

Follow one behavior at a time through three phases.

1. RED - Write Failing Test First

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);
  });
});

Run test to see it fail:

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

2. GREEN - Implement Minimum Code

Write the minimum code to make the test pass:

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

Run test to see it pass:

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

3. REFACTOR - Improve Without Breaking Behavior

Improve code quality while keeping tests green:

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);
}

Run tests again to verify refactoring didn't break anything.

For extended examples, failure diagnostics, and iterative expansions, read references/red-green-refactor.md.

Keep test scope lean

Prefer lighter tests first and escalate only when needed:

1. Unit tests (preferred) - Pure functions and Effect services with mock layers.
2. TRPC integration tests - Full TRPC + persistence behavior.
3. E2E tests - Browser-level flows and user journeys.

Apply Effect-specific TDD patterns

Use test-first service design with explicit layers.

1. Define interface via test - Make behavior explicit before implementation.
2. Create mock layer - Isolate dependencies and keep tests deterministic.
3. Implement service - Satisfy the tests with the minimal behavior.
4. Refactor - Improve readability and structure while preserving behavior.

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)),
  );
});

Mock Layer Factory Pattern

// 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]]))),
);

For deeper guidance (error-path testing, layer composition, anti-vi.mock() rationale), read references/effect-tdd-patterns.md.

Use project-convention test locations (examples)

Treat these paths as project conventions/examples; adapt if a repository uses different test layout.

Use supporting references for depth

Load targeted references instead of expanding this file during execution:

• Use references/commands.md for runnable command patterns.
• Use references/anti-patterns.md for failure-mode walkthroughs and corrections.

Resources

references/

• red-green-refactor.md - Detailed TDD cycle workflow with examples
• effect-tdd-patterns.md - Effect service testing, mock layers, error cases
• test-first-examples.md - Step-by-step TDD examples for this codebase
• commands.md - Command catalog and correct/incorrect invocation patterns
• anti-patterns.md - Detailed TDD anti-pattern walkthroughs with fixes

Related Skills

• testing-patterns - Test syntax, TRPC integration tests, E2E patterns
• effect-ts - Effect service design, layers, error handling