Testable Design

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

Philosophy

• Treat difficulty in testing as feedback about the design, not as a testing problem.
• Fix coupling rather than compromising the architecture to make a test pass.
• Test behaviour at architectural boundaries, not the internals behind them.
• Prefer small, fast unit tests over pure logic, and a few integration tests at each adapter.

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
• Reviewing a test suite that relies on static mocking, real databases or skipped tests

When Not to Use

• Class-level SOLID violations (use solid-principles)
• Architectural boundary decisions (use clean-architecture)
• Choosing structural patterns (use design-patterns)
• Writing a test-first workflow from scratch (use test-driven-development)

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

WHY: A hard-wired dependency cannot be replaced in a test, so the class needs real infrastructure to run.

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

NEVER test implementation details

WHY: Tests coupled to internal calls break on every refactor while saying nothing about behaviour.

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

NEVER use real infrastructure in unit tests

WHY: Real databases and networks make unit tests slow, flaky and unable to pinpoint a failure.

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

NEVER skip tests because code is "hard to test"

WHY: Hard-to-test code is a design signal; skipping the test hides the coupling and ships untested code.

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

NEVER tangle business logic with infrastructure

WHY: Mixed logic and infrastructure forces every business rule test to set up SQL, HTTP or filesystems.

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

NEVER depend on static calls or singletons for behaviour

WHY: Statics and singletons are hidden dependencies that need static-mocking tools and shared-state resets in every test.

BAD: InventoryChecker.isAvailable(items) and NotificationService.getInstance() inside the processor. GOOD: Inject an inventory interface and a notification port, and pass instances.

NEVER read the current time or random numbers directly in logic

WHY: Direct access to the clock or randomness makes results non-deterministic, so tests cannot assert exact values.

BAD: order.setProcessedAt(new Date()) inside the service. GOOD: Inject a Clock and call clock.now(); tests supply a fixed time.

NEVER leave dependency rules unenforced

WHY: Without automated checks, shortcuts such as framework imports in the domain accumulate until refactoring becomes impossible.

BAD: Rely on code review to notice import prisma in the domain layer. GOOD: Run architecture tests (for example dependency-cruiser or ArchUnit) in CI so violations fail the build.

NEVER compromise the architecture for testability

WHY: Test-only hooks and exposed internals hide the real coupling and leave the design worse than before.

BAD: Make a private method public, or add a test flag, so a test can reach it. GOOD: Fix the coupling by extracting a collaborator and injecting it.

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

Related Patterns

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

Further Reading

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