Testing at the boundary

Why the old architecture was untestable

The opening story’s untestability was structural. OrderService had compile-time dependencies on PostgresOrderRepository, StripeClient, and SendGridClient. To instantiate OrderService in a test, you either provided real infrastructure or mocked those classes with a mocking framework. Both options carry costs:

Real infrastructure in tests requires environment setup (Docker Compose, external accounts, network access), is slow (seconds per test, minutes per suite), and is flaky (external services fail, containers timeout, rate limits hit).

Mock frameworks require the test to know the internal implementation details of OrderService — which methods it calls on which dependencies, in what order, with what arguments. When OrderService is refactored (say, extracting a domain method), the mocks break, even if the behavior is unchanged. The tests become fragile maintenance burden instead of reliable safety nets.

Both problems share a root cause: OrderService has direct source-code dependencies on infrastructure classes. The test cannot isolate the domain logic from those dependencies without either providing them or replacing them with structurally identical copies (mocks).

Hexagonal architecture removes the root cause. The domain does not have source-code dependencies on infrastructure classes — it has source-code dependencies only on its own port interfaces. You cannot instantiate PostgresOrderRepository accidentally inside the domain, because the domain does not import it. The only way to satisfy a secondary port is to provide an implementation — which can be a fast, in-memory fake.

Driving through the primary port with a test driver

The test driver is a driving adapter (lesson 02). It calls the primary port directly, just as the HTTP controller does. There is no HTTP involved — no server, no request parsing, no response formatting.

// domain/ports/OrderConfirmationPort.ts
interface OrderConfirmationPort {
  confirmOrder(orderId: string, approverId: string): Promise<ConfirmationResult>;
}

// Test: drive through the primary port
describe('Order confirmation use case', () => {
  let useCase: OrderConfirmationPort;
  let orderRepo: InMemoryOrderRepository;
  let paymentGateway: FakePaymentGateway;
  let emailNotifier: FakeEmailNotifier;

  beforeEach(() => {
    orderRepo = new InMemoryOrderRepository();
    paymentGateway = new FakePaymentGateway();
    emailNotifier = new FakeEmailNotifier();

    // Wire up the use case with fake driven adapters
    useCase = new OrderConfirmationUseCase(orderRepo, paymentGateway, emailNotifier);
  });

  it('confirms a pending order and charges the customer', async () => {
    // Arrange: plant a pending order in the fake repo
    const order = Order.pending({ id: 'order-1', customerId: 'cust-42', amount: Money.of(500, 'USD') });
    await orderRepo.save(order);

    // Act: drive through the primary port
    const result = await useCase.confirmOrder('order-1', 'approver-99');

    // Assert: domain outcome
    expect(result.success).toBe(true);
    expect(paymentGateway.chargesIssued).toHaveLength(1);
    expect(paymentGateway.chargesIssued[0].amount).toEqual(Money.of(500, 'USD'));
    expect(emailNotifier.sentMessages).toHaveLength(1);
  });

  it('rejects confirmation when order has overdue invoices', async () => {
    const order = Order.pending({ id: 'order-2', customerId: 'cust-42', amount: Money.of(200, 'USD') });
    order.markInvoiceOverdue('inv-7');
    await orderRepo.save(order);

    const result = await useCase.confirmOrder('order-2', 'approver-99');

    expect(result.success).toBe(false);
    expect(result.reason).toBe('overdue-invoice');
    expect(paymentGateway.chargesIssued).toHaveLength(0);
  });
});

No Docker Compose. No Stripe account. No SendGrid sandbox. Each test runs in milliseconds. The test suite can be hundreds of tests and finish in under two seconds.

In-memory fakes at secondary ports

The key enabler is the in-memory fake — a simple, fast implementation of a secondary port that stores state in memory. It is not a mock (which records call expectations); it is a real implementation that happens to use memory instead of a network or disk.

// Implements the secondary port: IOrderRepository
class InMemoryOrderRepository implements IOrderRepository {
  private store = new Map<string, Order>();

  async findById(id: string): Promise<Order | null> {
    return this.store.get(id) ?? null;
  }

  async save(order: Order): Promise<void> {
    this.store.set(order.id, order);
  }

  async findByCustomerId(customerId: string): Promise<Order[]> {
    return [...this.store.values()].filter(o => o.customerId === customerId);
  }
}

// Implements the secondary port: IPaymentGateway
class FakePaymentGateway implements IPaymentGateway {
  public chargesIssued: Array<{ customerId: string; amount: Money }> = [];
  public shouldFail = false;

  async charge(customerId: CustomerId, amount: Money): Promise<ChargeResult> {
    if (this.shouldFail) return ChargeResult.failure('card-declined');
    this.chargesIssued.push({ customerId: customerId.value, amount });
    return ChargeResult.success(`charge-${Date.now()}`);
  }

  async refund(chargeId: ChargeId, amount: Money): Promise<RefundResult> {
    return RefundResult.success();
  }
}

The fakes implement the secondary port interface exactly — the same interface the production Postgres and Stripe adapters implement. The domain use case cannot distinguish between them at compile time. At runtime, the test injects the fake; production wires the real adapter. The same use case runs in both contexts without modification.

The test pyramid hexagonal teams actually use

The structural separation of domain from adapters produces a natural three-level test pyramid:

Level 1 — Domain tests (many, milliseconds): Drive through the primary port with a test driver and fake driven adapters. Test every business rule, every invariant, every edge case in the domain. These tests have no infrastructure dependencies — they run anywhere, instantly. This is the bulk of the test suite: every combination of order state, approval logic, billing rule, and error condition. In the B2B platform, this is hundreds of tests covering the full confirmation, invoicing, and billing approval logic.

Level 2 — Adapter tests (fewer, seconds): Test each adapter in isolation against its port contract. The PostgreSQL repository test starts a real database, saves and retrieves domain objects, and verifies the mapping is correct. The Stripe adapter test (against Stripe’s test API) verifies the charge/refund mapping. The HTTP controller test verifies that HTTP request fields are correctly parsed into port parameters and port results are correctly serialized to HTTP responses. These tests verify that the adapter correctly implements the port — they do not re-test domain logic.

Level 3 — End-to-end tests (very few, seconds to minutes): Start the full application with all real adapters wired. Send real HTTP requests. Verify the whole stack integrates. These tests are expensive — keep them to critical happy paths only.

Level 1: Domain tests      ████████████████████████████████████  (hundreds)
Level 2: Adapter tests     ██████████                            (tens)
Level 3: E2E tests         ██                                    (handful)

The B2B platform’s original problem — 72% nominal coverage achieved through slow integration tests — was a symptom of having no Level 1 tests at all. Everything was Level 3. Hexagonal architecture inverts this: Level 1 tests are cheap to write because the domain is fully accessible through the primary port without infrastructure.

Adapter tests: testing the boundary from the outside

The adapter tests are structurally independent of the domain tests. They test a different question: “Does this adapter correctly implement the port contract?”

// Adapter test: PostgresOrderRepository implements IOrderRepository
describe('PostgresOrderRepository', () => {
  let db: Pool; // Real PostgreSQL connection
  let repo: PostgresOrderRepository;

  beforeAll(async () => {
    db = await createTestDatabase();
    repo = new PostgresOrderRepository(db);
  });

  it('saves and retrieves an order by id', async () => {
    const order = Order.pending({ id: 'test-1', customerId: 'c-1', amount: Money.of(100, 'USD') });
    await repo.save(order);
    const retrieved = await repo.findById('test-1');
    expect(retrieved).toEqual(order);
  });

  it('returns null for a non-existent order', async () => {
    const result = await repo.findById('no-such-id');
    expect(result).toBeNull();
  });
});

These tests start the real database. They are slower than domain tests. But they cover the one thing domain tests cannot: the correct mapping between domain objects and database rows (column names, types, NULL handling, serialization). A domain test with a fake repository would never catch a column mapping bug. The adapter test catches it exactly, without testing any domain logic.