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

Step 3: Isolate Side Effects

Output: Pure business logic separated from side effects.

Use the Humble Object pattern:

• Humble object: Thin adapter with minimal logic (controller, presenter, gateway)
• Testable object: Pure logic with no infrastructure dependencies (use case, entity)

Example:

// Humble object (minimal logic, hard to test)
class HttpController {
  constructor(private useCase: CreateOrderUseCase) {}
  
  async handle(req: Request, res: Response): Promise<void> {
    const input = { userId: req.body.userId, items: req.body.items }
    const output = await this.useCase.execute(input)
    res.json(output)
  }
}

// Testable object (pure logic, easy to test)
class CreateOrderUseCase {
  constructor(private repo: IOrderRepository) {}
  
  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
    // Business logic here (unit testable with mock repo)
  }
}

Step 4: Design Test Doubles

Output: Mocks, stubs, or fakes for dependencies.

Choose appropriate test double:

• Stub: Returns fixed data (for queries)
• Mock: Verifies behavior (for commands)
• Fake: Lightweight implementation (in-memory DB)

Example:

// Stub (for queries)
class StubOrderRepository implements IOrderRepository {
  async findById(id: string): Promise<Order | null> {
    return new Order({ id, status: 'pending' })
  }
}

// Mock (for commands)
class MockOrderRepository implements IOrderRepository {
  saveWasCalled = false
  
  async save(order: Order): Promise<void> {
    this.saveWasCalled = true
  }
}

// Fake (lightweight alternative)
class InMemoryOrderRepository implements IOrderRepository {
  private orders = new Map<string, Order>()
  
  async save(order: Order): Promise<void> {
    this.orders.set(order.id, order)
  }
  
  async findById(id: string): Promise<Order | null> {
    return this.orders.get(id) || null
  }
}

Step 5: Verify Boundary Tests

Output: Test coverage at each architectural boundary.

Check:

• Entities are unit tested (pure logic, no dependencies)
• Use cases are unit tested (with mocked ports)
• Adapters are integration tested (with real or fake infrastructure)
• Controllers are integration tested (with real use cases or fakes)

Example:

Unit test: CreateOrderUseCase with mock IOrderRepository
Integration test: PostgresOrderRepository with real database
End-to-end test: POST /orders with real HTTP server and database

Anti-Patterns

NEVER instantiate concrete dependencies in business logic

BAD: new PostgresRepository() in OrderService constructor.
GOOD: Depend on IRepository interface; inject implementation.

NEVER test implementation details

BAD: Test that method X calls method Y internally.
GOOD: Test public behavior: given input, expect output.

NEVER use real infrastructure in unit tests

BAD: Unit test connects to real database.
GOOD: Unit test uses mock repository; integration test uses real database.

NEVER skip tests because code is "hard to test"

BAD: Skip test, ship untested code.
GOOD: Refactor code to be testable (dependency injection, layer isolation).

NEVER tangle business logic with infrastructure

BAD: OrderService contains SQL queries and HTTP response formatting.
GOOD: OrderService orchestrates pure entities; adapters handle infrastructure.

Quick Commands

# Find hard-to-test code (concrete instantiation)
rg -n "new [A-Z].*Repository\(|new [A-Z].*Service\(|new [A-Z].*Gateway\(" src

# Find side effects in business logic
rg -n "fetch\(|axios\.|fs\.|process\.env" src/domain src/application

# Run tests with coverage
npm run test:coverage

References

Testable Design Files

• Boundary verification: references/test-boundary-verification.md
• Testable design: references/test-testable-design.md
• Layer isolation: references/test-layer-isolation.md
• Tests are architecture: references/test-tests-are-architecture.md

Related Patterns

For dependency inversion (DIP), see solid-principles.
For boundary design, see clean-architecture.
For Humble Object pattern, see design-patterns.

• Growing Object-Oriented Software, Guided by Tests
• Working Effectively with Legacy Code (Michael Feathers)
• Test-Driven Development by Example (Kent Beck)