testable-design

Testable Design

Architecture and design patterns for testable code, focusing on boundary isolation and dependency injection.

When to Use

• Designing test strategies for new features
• Refactoring untestable code with hard dependencies
• Improving test coverage by isolating layers
• Evaluating whether code is testable before implementation
• Designing boundaries that enable fast unit tests

When Not to Use

• Class-level SOLID violations (use solid-principles)
• Architectural boundary decisions (use clean-architecture)
• Choosing structural patterns (use design-patterns)

Testable Design Principles

Tests Are Architecture

If code is hard to test, it's a design problem, not a testing problem.

Boundary Verification

Test at architectural boundaries, not internal implementation details:

• Unit tests: Test pure business logic (entities, use cases) in isolation
• Integration tests: Test boundary adapters (repositories, controllers, gateways)
• End-to-end tests: Test complete user workflows across boundaries

Layer Isolation

Each layer should be testable in isolation:

• Entities: Pure functions, no dependencies
• Use Cases: Depend on interfaces (ports), not concrete implementations
• Adapters: Test with fake use cases or real infrastructure
• Infrastructure: Test with integration tests, not unit tests

Workflow

Step 1: Identify Hard-to-Test Code

Output: List of testability blockers.

Example:

Testability blocker: OrderService instantiates PostgresRepository in constructor.
Problem: Cannot unit test OrderService without a real database.
Refactor: Inject IOrderRepository interface; provide mock in tests.

Step 2: Apply Dependency Injection

Output: Dependencies injected via constructor or method parameters.

Template:

// Before: hard to test (concrete dependency)
class OrderService {
  private repo = new PostgresOrderRepository()
  
  async createOrder(input: OrderInput): Promise<Order> {
    // Logic using this.repo
  }
}

// After: testable (injected interface)
class OrderService {
  constructor(private repo: IOrderRepository) {}
  
  async createOrder(input: OrderInput): Promise<Order> {
    // Logic using this.repo (mockable in tests)
  }
}