Subscribe now

When developers hear “port,” most think interface.

Add an interface, call it a port, check the box.

But here’s the trap: just adding interfaces doesn’t make your domain independent.
Abstraction alone doesn’t automatically enforce architecture.

If your dependencies point the wrong way, your domain depends on the database, API, or external services — instead of defining what the system should do.

In Hexagonal Architecture, the question isn’t just “do I have a port?”

It’s: who does the domain call, and who implements it?

Do your dependencies point the right way?

🚀 Register now: Acceptance Testing Workshop
Get 100 EUR off with code EARLYBIRD100

❌ Domain depends on Infrastructure

• Domain directly uses infrastructure classes like JpaOrderRepository or PaymentApiClient

• Business logic becomes tied to storage or APIs

• Changing the database or API can break domain code

✅ Domain defines the contract, infrastructure implements the contract

• Domain defines driven ports — interfaces that describe what it needs done

• Driven adapters implement the details

• Domain logic is stable, infrastructure can change without affecting it

Driven ports exist to control this dependency direction.

Abstraction alone doesn’t enforce architecture — direction does.

Real-life Example: Ordering System

Applying Hexagonal Architecture on the backend (for an e-commerce system).

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

The most common mistake in Hexagonal Architecture is mocking everything outside the domain.

Tests break after the tiniest change.

Refactors become nightmares.

And your “clean architecture” is now just a pile of mocks.

❌ Over-Mocking Everything

Okay, Order Service Test… let’s mock all the driven ports:

- Repository? mock
- Payment Gateway? mock
- Email Service? mock

By the time your test runs, it’s fragile spaghetti:

• Change a method signature in the repository? Test fails.

• Change a method signature in the payment gateway? Test fails.

In the repository, I had a method add(int id, OrderData data). I refactored it to be add(Order order)… tests fail because the mock is now out-of-date.

In the payment gateway, I used the method getAllInvoices() and then did in-memory filtering to find an invoice. In my source code I decided to use the method getInvoice(String invoiceId)… tests fail because the mock now is out-of-date.

You now have hexagonal architecture… and 47 failing tests.

Why it’s bad:

• Tests describe implementation, not behavior

• Ports are treated as a checklist of mocks, not boundaries

• Refactoring domain logic becomes a nightmare

• Cognitive load goes through the roof

✅ Testing What Matters

Focus on behavior, not mocks:

• ✅ Fakes

• ✅ Stubs

• ✅ Spies

• ❌ Mocks

For the same Order Service:

- Repository → in-memory fake
- Payment Gateway → simple stub that can be configured to maybe payment succeed or fail
- Email Service → spy, whereby we collect emails in a queue, and inspect emails sent

Notice the difference?

• Tests now describe what the domain does, not how infrastructure works.

• Refactoring domain code rarely breaks tests.

• Cognitive load drops — you’re testing one thing at a time.

Fake data, not behavior. Test behavior, not calls.

💡Order Test Without Mock Overload

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

I’ve lost count of how many times I’ve heard this:

“Yeah, this project uses Hexagonal Architecture.”

Then I open the repo.

And immediately feel confused.

Controllers mixed with use cases.
Repositories sitting next to domain objects.
Tests that need half the infrastructure just to run.

I stare at the screen and think: What is going on here?

The problem usually isn’t the architecture.

It’s the folder structure.

The One Mental Model That Finally Clicked for Me

I stopped thinking in terms of “layers”.

Instead, I started asking one simple question:

Is this part of my application’s core—or just a way to talk to the outside world?

Everything in the heart goes into the App folder.
Everything else—adapters, controllers, integrations—lives outside.

Suddenly, the structure made sense.

How I Actually Organize Things

📁 App (Hexagon)
 ├── 📁 Driving Ports
 │    └── 📁 DTOs
 └── 📁 Core
 │    ├── 📁 Application
 │    └── 📁 Domain
 └── 📁 Driven Ports

📁 Driving Adapters

📁 Driven Adapters
 ├── 📁 Real Driven Adapters
 └── 📁 Fake Driven Adapters

Inside a Shipping App—Pro Example

Let’s walk through a shipment.

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

Backend Component Tests

Backend Component Tests verify whether the Backend as a whole, works correctly (this spans all logic - presentation, business, infrastructure logic). They:

• Target the Backend API

• Stub out External Systems

These tests are agnostic to the architecture inside the Backend. It doesn’t matter whether the Backend is a Big Ball of Mud, or Hexagonal Architecture, or Vertical Architecture, etc. The Component Tests don’t care, they don’t know, because they are blackbox tests - they are testing the Backend as a blackbox.

Example: OrderControllerTest sets up the Stripe WireMock Stub that it returns some invoice number, we call the Backend REST API endpoint POST /api/orders with request body { sku=ABC, quantity=4 }, and then verify that it returns an order number.

In Legacy Code, we can write Component Tests from Day 1.

Backend Hexagonal Architecture Testing

If the Backend is structured using Hexagonal Architecture, then we can go a level down, to do this kind of testing:

1. Unit Tests - testing the Hexagon

2. Narrow Integration Tests - testing the Adapters

Note: In Legacy Code, if your Backend is a Big Ball of Mud, you’ll you need to have Component Tests first, then you’ll be able to safely redesign your Backend from Big Ball of Mud towards Hexagonal Architecture, and then you’ll be able to introduce these tests.

Unit Tests - Hexagon

Unit Tests verify Business Logic. They:

• Target Driving Ports

• Stub out Driven Ports

Therefore, they span the Hexagon, i.e. testing the Hexagon in isolation.

Example I: With coarse-grained ports (Application Services): OrderServiceTest tests the business logic inside OrderService, whilst stubbing out the OrderRepository.

Example II: With fine-grained ports (Request Handlers): PlaceOrderTest tests the business logic inside PlaceOrderHandler, whilst stubbing out the OrderRepository.

Narrow Integration Tests - Driving Adapters

Driving Adapter Narrow Integration Tests verify Presentation Logic. They:

• Target Driving Adapters

• Stub out Driven Ports

Therefore, they span the Driving Adapters, i.e. testing the Driving Adapters in isolation.

Example: OrderControllerTest tests the presentation logic inside the OrderController, e.g. how it maps success/failure to http status codes and responses.

Narrow Integration Tests - Driven Adapters

Driven Adapter Narrow Integration Tests verify Infrastructure Logic. They:

• Target Driven Adapters via Driven Ports

• Stub out External Systems

Therefore, they span the Driven Adapters, i.e., testing the Driven Adapters in isolation.

Example I: OrderRepositoryTest tests the infrastructure logic of the OrderRepository. It’s executed against the SqlOrderRepository (using real DB) and the FakeOrderRepository adapters.

Example II: PaymentGatewayTest tests the infrastructure logic of the PaymentGateway. It’s executed against the StripePaymentGateway (using WireMock instead of Stripe API) and the FakePaymentGateway adapters.

Real-life Example: Ordering System

For an e-commerce system:

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

The Outside of the Hexagon

The “external world” contains all the technologies and systems that surround our core application: databases, APIs, message brokers, user interfaces, etc.

The hexagon acts as a shield - it defines a clear boundary between what’s inside (domain and use cases) and what’s outside (infrastructure and delivery).

The outside world can change - you might switch frameworks, UIs, or databases - without changing the core logic inside the hexagon.

That’s because communication between the two happens only through ports and adapters.

Driving Adapters (User-side API)

On the left side of the hexagon, we have Driving Adapters — these are the entry points that drive the application from the outside.

They present the application in a way suitable for clients, and then call the driving ports (the use cases).

Driving adapters - examples:

• A REST API that receives HTTP requests and calls a use case

• A Web UI or mobile app interacting with backend services

• A command-line or batch process triggering operations

Driving adapters don’t contain business logic. Instead they contain presentation logic:

• Receive external input (like an HTTP request or button click)

• Convert it into a suitable format (e.g. a DTO)

• Call the appropriate use case inside the hexagon

• Return the result back to the client

Driving adapters make it possible to expose the same use case in multiple ways — e.g. through a web API, CLI, or message consumer — without duplicating logic.

You can swap out your web framework or migrate from REST to GraphQL without touching your business rules.

Driven Adapters (Server-side API)

On the opposite side of the hexagon, we have Driven Adapters — these implement the driven ports that the application depends on.

If a use case needs to:

• Save data to a database

• Call an external API

• Send an email

• Publish an event

…it doesn’t do those things directly. Instead, it talks to a driven port interface, and the driven adapter handles the infrastructure details.

Driven Adapters - examples:

• Database Adapter implementing OrderRepository interface, e.g. by executing SQL queries on an SQL database, or perhaps by using an ORM, etc.

• Email Adapter implementing NotificationGateway interface, e.g. by using Gmail SDK to send emails

• Payment Adapter implementing PaymentGateway, e.g. by integrating with Stripe or PayPal API

• Event Adapter implementing PublisherGateway, e.g. by publishing messages to Kafka or RabbitMQ

Driven adapters keep infrastructure concerns separate from business logic.

If your database, API provider, or message broker changes, you only update the adapter — your domain and use cases remain untouched.

Real-life Example: Ordering System

Read more

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

Hexagon

The “internal world” is the application itself – its domain logic, the rules that define what the system does and how it behaves.

We want to keep the “internal world” uncontaminated, we don’t want it to be affected by the “external” world (external technologies).

We can think of this as a capsule, called a “Hexagon”. It that defines a clear boundary between the inside and the outside.

Keep your core independent from frameworks, databases, UIs, or any other external systems. This gives you flexibility to change your database, UI, or external APIs without rewriting your business logic.

Driving Ports (User-side API)

On one side of the hexagon, we have Driving Ports — the user-facing entry points into the system.

Our application exists so that it helps clients to run some use cases. Clients could be:

• Human users interacting via a UI

• Other systems making API calls

• Test harnesses simulating real-world behavior

• etc…

Driving Ports define what the system can do, not how it does it. Think of them like the “steering wheel” - they let you control the application, but not open the hood.

We want to expose ONLY the use cases to the clients (and NOT expose the internals of the application!).

The Hexagon provides some kind of user-facing API (”driving” ports), so that our clients can execute the use cases.

Driven Ports (Server-side API)

On the opposite side, we have Driven Ports — these are the interfaces that the application needs the outside world to implement.

The application might need to:

• Save data to a database

• Send an email notification

• Publish an event to a message broker

• Call an external payment service

• etc…

We don’t want to directly be aware of external tech nor directly talk to those external systems, so we need some kind of server-side API.

The internal world should never know which specific technology is used.

Real-life Example: Ordering System

Read more

Testing driving ports (spanning the hexagon in isolation) had a clear value - providing regression bug protection in business logic.

📢 My next Live Q&A Session about Unit Tests is on Wed 30th April 17:00. If you’re an Optivem Journal paid member, get your 100% discount ticket.

Register now

Upgrade to join the Live Q&A for free:

Subscribe now

But what about testing adapters, e.g. testing database adapters, file adapters, external system adapters?

1. Should adapters be tested, are they worthy of being tested?

2. If adapters should be tested, should we test them in an integrated way or in an isolated way?

Read more

Subscribe now

I thought ALL Integration Tests should include I/O

When connecting to I/O sources, we use Driven Adapters, which integrate with the I/O source. The Driven Adapter does some translation work, calls the I/O source, and then does that translation again.

Internal I/O Driven Adapters

These Driven Adapters connect to the I/O that is owned by our microservice. For example, we have the OrderRepository (driven port), which is implemented by the PostgresOrderRepository (driven adapter). The Driven Adapter integrates with our Postgres database using ORM and/or SQL queries and/or stored procedures.

When doing Integration Tests for the PostgresOrderRepository, the test should span the Postgres Database. This means running the Postgres database locally, on our Test Server, or even better, running Postgres with Testcontainers.

External I/O Driven Adapters

These Driven Adapters connect to stuff that is not owned by our microservice. For example, we have the PaymentGateway (driven port), which is implemented by the PayPalPaymentGateway (driven adapter), which integrates with PayPal by making HTTP calls to the PayPal REST API.

When doing Integration Testing for the PayPalPaymentGateway, I (and many other developers) thought that we should integrate it with PayPal's REST API. This means running an External System Test Instance on our Test Server, or connecting to the Test Instance provided by the third-party vendor. In the case of PayPal, it means using the PayPal sandbox.

Thus, like many other developers, I thought that to test Driven Adapters, we should truly connect to the Test Instance of that I/O source.

But I was wrong (in the case of External Systems)

Fortunately, Integration Testing for Internal I/O Driven Adapters worked out well.

But Integration Testing for External I/O Driven Adapters was a nightmare! The mistake I made was including the External System Test Instance in the Integration Test itself, and that’s a mistake I’ve seen so many others developers make as well - due to fallacies in widespread notions of integration testing.

I’m now going to reveal to you:

• The 5 problems of mainstream Integration Testing for Driven Adapters

• The solution I discovered to overcome this problem ⬇️⬇️⬇️

Read more