🔒 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 mistake is to look at the finished use case — availability check, number generation, persistence, a response — and write all of it in one go.

That’s not TDD.

That’s writing the answer and then sprinkling tests on top.

TDD is incremental: write the simplest behavior that could possibly work, get it green.

The next failing test decides what gets added next.

Behavior 1: a guest can reserve a room

Requirement:

“Guest can reserve a room.”

Notice what’s not in that sentence yet: nothing about availability. So we don’t build availability checking. We build the smallest thing the requirement asks for — a reservation gets added, and we get a reservation number back.

🔴 RED — Write the failing test

class PlaceReservationTest {

    private FakeReservationRepository reservationRepository;
    private StubReservationNumberGenerator reservationNumberGenerator;
    private PlaceReservationUseCase placeReservationUseCase;

    @BeforeEach
    void setUp() {
        reservationRepository = fakeReservationRepository();            // fake — in-memory, query state back
        reservationNumberGenerator = stubReservationNumberGenerator();  // stub — canned number
        placeReservationUseCase = new PlaceReservationUseCase(
            reservationRepository, reservationNumberGenerator);
    }

    @Test
    void createsReservation() {
        reservationNumberGenerator.returns("RES-123");

        var placeReservationRequest = PlaceReservationRequest.builder()
            .guestId("guest-1")
            .roomId("room-101")
            .build();

        var response = placeReservationUseCase.execute(placeReservationRequest);

        assertThat(response.reservationNumber()).isEqualTo("RES-123");

        var reservation = reservationRepository.findByReservationNumber("RES-123");
        assertThat(reservation.guestId()).isEqualTo("guest-1");
        assertThat(reservation.roomId()).isEqualTo("room-101");
    }
}

Notice what exists so far:

• repository to add the reservation

• number generator so the test can pin the returned number (RES-123) deterministically.

There is no AvailabilityGateway — nothing requires one yet.

Look at the request, too: it only has a guest and a room — no dates. A real reservation obviously has dates, but no behavior here uses them yet, so they’re not in the request yet.

The requirement was “reserve a room,” nothing about when. You add data for the same reason you add code: when a test needs it, not before.

🟢 GREEN — Make it pass with the simplest code

public class PlaceReservationUseCase {

    private final ReservationRepository reservationRepository;
    private final ReservationNumberGenerator reservationNumberGenerator;

    public PlaceReservationUseCase(ReservationRepository reservationRepository,
                                   ReservationNumberGenerator reservationNumberGenerator) {
        this.reservationRepository = reservationRepository;
        this.reservationNumberGenerator = reservationNumberGenerator;
    }

    public PlaceReservationResponse execute(PlaceReservationRequest request) {
        var reservationNumber = reservationNumberGenerator.next();

        reservationRepository.add(new Reservation(
            reservationNumber,
            request.guestId(),
            request.roomId()
        ));

        return new PlaceReservationResponse(reservationNumber);
    }
}

Green. It always adds the reservation — it never checks anything — because no test has demanded a check yet.

This feels too simple, and that’s the point. You are not allowed to add the availability logic now. There’s no failing test pushing you there.

🔵 REFACTOR — only if you see the need

With the test green, you now get a safe moment to improve the design — rename, extract, remove duplication — without changing behavior. You take it only if you actually see an improvement worth making; if nothing stands out, you skip it and move on.

Here the use case is a few straight-line statements with nothing to tidy, so there's nothing to do.

Behavior 2: only if the room is available

Now a new requirement arrives:

“A room can only be reserved if it is available for the selected dates.”

Now we need to know if the room is available.

🔴 RED — Write the failing test

    @Test
    void rejectsReservationWhenRoomIsUnavailable() {
        availabilityGateway
            .forRoom("room-101")
            .from("2026-07-10")
            .to("2026-07-12")
            .returnsUnavailable();

        var placeReservationRequest = PlaceReservationRequest.builder()
            .guestId("guest-1")
            .roomId("room-101")
            .from("2026-07-10")
            .to("2026-07-12")
            .build();

        assertThatThrownBy(() -> placeReservationUseCase.execute(placeReservationRequest))
            .hasMessage("Room is not available");
    }

Read more

Subscribe now

Most teams do the opposite.

Pain → delay → bigger merge → more pain.

That is the system.

“We’ll merge when it’s done”

Because:

• merge is painful

• integration is slow

• system breaks in unexpected ways

What teams do next:

❌ integrate less often
❌ delay merging

Wrong.

1. Integrate into main frequently

Not “eventually”. Not “when finished”.

✔ multiple times per day (or at least daily)
✔ small changes only

❌ no “feature branch for 2 weeks”
❌ no “merge at the end of development”

2. Every integration triggers a system check

When code is merged (or proposed for merge), the system must verify:

✔ compilation works
✔ unit tests pass
✔ component tests pass
✔ system tests pass

Not “some tests”.

The goal is:

• do the components work in isolation? AND

• does the system still work as a whole?

Note: quick verification (compilation, unit tests & component tests) is triggered on merge, whereas slower verification (system tests) are triggered on an interval-based schedule.

3. Broken main is not allowed to persist

This is the most important rule in real CI.

✔ if main breaks → fix immediately
✔ nobody continues building on a broken state
✔ the team treats main as always releasable

❌ “we’ll fix it later”
❌ “let’s ignore it and keep going”

4. Changes are small by design

CI only works if changes stay small.

• small commits

• small merges

• easy rollback

Because:

❌ large batches hide integration problems
✔ small batches expose them immediately

5. Integration problems are found immediately, not later

CI is basically: shorten the time between “change” and “system feedback”

So instead of:

❌ change → days later → production breaks

You get:

✔ change → minutes later → system check fails

6. The system is always in a working state

This is the outcome CI is trying to enforce.

✔ main branch always works
✔ every change is either:

• integrated and working

• or not integrated at all

❌ no “half-working shared state”

What CI/CD is NOT (important)

❌ running Jenkins
❌ having a pipeline
❌ building artifacts
❌ running tests once per day
❌ merging occasionally

Those are tools or schedules.

Not CI/CD.

✅ A Real Pipeline = Continuous Delivery

👉 I’m running a live workshop where we walk through a working e-shop example with a pipeline architecture, so you can see how it works in practice.

No rebuild tricks. No “it passed CI but broke anyway” surprises.

Join Pipelines Workshop →

€100 off with code EARLYBIRD100 — limited spots.

Subscribe now

“How to handle errors properly?”

You’ve seen:

• SQLException and DataAccessException caught inside controllers

• catch (Exception e) returning a hand-rolled 500

• giant try/catch blocks wrapping every endpoint

• RuntimeException thrown and swallowed at random

And nobody agrees on the “right” way to do it.

Start where those mistakes happen — the API layer — and get one rule right: a controller turns errors into HTTP responses, and it should never reach for a database or framework exception to do it.

Error Handling at the API layer

This layer should turn errors into HTTP responses.

Examples:

• HTTP status codes

• error messages

• API response bodies

❌ Controllers should NOT handle database/framework errors

@GetMapping("/orders")
public ResponseEntity<?> getOrders() {

    try {
        return ResponseEntity.ok(orderRepository.findAll());
    } catch (DataAccessException e) {
        return ResponseEntity.status(500).body("Database error");
    }
}

That’s the wrong place for database exception handling.

👉 I’m running a live workshop where we walk through a working e-shop example with a pipeline architecture, so you can see how it works in practice.

No rebuild tricks. No “it passed CI but broke anyway” surprises.

Join Pipelines Workshop →

€100 off with code EARLYBIRD100 — limited spots.

✅ The API layer should turn errors into responses — via a global exception handler

Read more

Subscribe now

Most teams I talk to will tell me they have a pipeline.

They have GitHub Actions. Or Jenkins. Or Azure DevOps. The build compiles, the Docker image gets pushed, a deploy script runs, and a green checkmark shows up next to the commit. That’s a pipeline, right?

It isn’t.

What they have is build and deployment automation. The green checkmark only proves the code compiled. Nothing in that verified that the code actually works before the bytes reach a customer.

I know this because the symptom is always the same.

The release went out on Tuesday. By Wednesday morning, the support inbox is full — somebody broke a critical path that nobody tested. Someone stays late. War room reconvenes.

And it ends with the line every senior engineer has heard a hundred times: “the pipeline didn’t catch it.”

The pipeline didn’t catch it because there was no pipeline. There was a conveyor belt.

A Pipeline Has Checkpoints, NOT Steps

Here is the part most teams skip: a pipeline is not a sequence of build steps. It is a sequence of checkpoints.

Because steps just run.

But a real pipeline doesn’t just move code forward. It asks at every checkpoint:
“Does this build move forward?”

If the answer is no, everything stops.

Most “pipelines” don’t do that.

They just run jobs until they’re done and call it success.

“The Pipeline Didn’t Catch It”

Each stage ran. Each stage passed.

But there were no tests.
So the bugs slipped through.

A real pipeline tests the system at each stage:

“Does it work on my machine?”

• Commit Stage — compile, run the fast tests (unit, narrow integration, component, contract), run static analysis, package, publish. Fast. Under five minutes. Triggered on every push.

“Does it work when deployed?”

• Acceptance Stage — deploy it and runs system tests (smoke, acceptance, external system contract, E2E).

“Do we release it?”

• Release Stage — takes it through QA and into production.

Each stage verifies something different. Each stage can stop the pipeline. The Commit Stage’s job is not the Acceptance Stage’s job, and treating them as one big “CI/CD workflow” is how you end up with code that “passed CI” but breaks the moment it gets deployed.

If you compile and deploy but never run the deployed code and check whether the deployed version does what it is supposed to do, you’re skipping the most important point.

You Didn’t Deploy the Same Build You Tested

Now here’s the part that quietly breaks most pipelines — even the ones with good tests.

The Commit Stage produces a build (e.g. a backend image and a frontend bundle). And from that point on, every stage is supposed to run the same build.

No rebuilds. No separate “QA build.” No special “production image.”

Testing the SAME build makes deployments predictable. "Works in Acceptance" means it will work in Production, because it's the same build.

The moment you rebuild between stages — even to swap a config, even to “just bump the version” — the guarantee disappears. The build your tests verified is not what is shipped.

This is the single most common quiet failure mode I see in real pipelines. The team did the work. They wrote the tests. They setup up the stages. And then somewhere in the middle, a “for deployment convenience” rebuild crept in and silently invalidated the whole chain.

Is It a Pipeline or Just Automation?

If you want to know whether your team has a pipeline or just automation, ask three questions:

1. What does the green checkmark prove?

“The code compiled” — this is a build, not a pipeline.

“The code was tested” — this is a pipeline.

❌ Just ran
✅ Verified behavior

2. What runs between commit and production?

If the answer is “compile, package, deploy,” you’re missing the Acceptance Stage. The pipeline cannot tell you whether the version works — only that it built.

❌ Just built
✅ It works

3. Are you running the same build in production that you tested earlier?

If you rebuild between stages, the answer is no. If you cannot tell, the answer is also no.

❌ Different built
✅ Same build

If any of those answers comes back wrong, the green checkmark is lying to you.

A pipeline is not a deploy script.

It is a sequence of checkpoints that decide whether a build should move forward.

If your green checkmark only means “it compiled and got deployed,” then you don’t have a pipeline — you have a conveyor belt that moves broken code faster.

And that’s why release day still feels like a gamble.

👉 I’m running a live workshop where we walk through a working e-shop example with a pipeline architecture, so you can see how it works in practice.

No rebuild tricks. No “it passed CI but broke anyway” surprises.

Join Pipelines Workshop →

€100 off with code EARLYBIRD100 — limited spots.

Subscribe now

“Never allow similar code to exist.”

That’s not DRY.

The original idea behind DRY wasn’t “remove every repeated line.”

It was:

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

— Andrew Hunt and David Thomas (The Pragmatic Programmer)

Knowledge duplication.

Not code duplication.

Want releases to stop feeling stressful and unpredictable?

I’m running a live CI/CD Pipeline Workshop where we build systems that catch issues before production — not after deployment panic.

Reserve My Spot

€100 off with code EARLYBIRD100 — limited spots.

❌ Two identical lines are not always duplication

Developers see this:

public class InvoiceTaxCalculator {

    public BigDecimal calculateTax(BigDecimal subtotal) {
        return subtotal.multiply(new BigDecimal("0.20"));
    }
}

…and then later see this:

public class ImportDutyCalculator {

    public BigDecimal calculateDuty(BigDecimal subtotal) {
        return subtotal.multiply(new BigDecimal("0.20"));
    }
}

The callers would call:

var tax = invoiceTaxCalculator.calculateTax(subtotal);
var duty = importDutyCalculator.calculateDuty(subtotal);

And immediately someone says:

“We should extract this into a shared utility.”

So it gets merged.

So we decide to get rid of the duplication, by extracting duplicated code here:

public class Calculator {
    public BigDecimal calculate(BigDecimal subtotal) {
        return subtotal.multiply(new BigDecimal(”0.20”));
    }
}

We then realize we don’t need neither InvoiceTaxCalculator nor ImportDutyCalculator, so we delete them too.

Then, the callers would call:

var tax = calculator.calculate(subtotal);
var duty = calculator.calculate(subtotal);

But the problem is that Invoice Tax and Import Duty calculations are completely unrelated from the business perspective. They have completely different business rules.

Today, they happen to have the same formula, but that is just incidental.

Tomorrow, they will end up with different business rules:

public class InvoiceTaxCalculator {
    public BigDecimal calculateTax(BigDecimal subtotal, String category) {
        if (category.equals("FOOD")) return subtotal.multiply(new BigDecimal("0.05"));
        if (category.equals("ELECTRONICS")) return subtotal.multiply(new BigDecimal("0.18"));
        return subtotal.multiply(new BigDecimal("0.20"));
    }
}

public class ImportDutyCalculator {
    public BigDecimal calculateDuty(BigDecimal subtotal, String country) {
        if (country.equals("US")) return subtotal.multiply(new BigDecimal("0.25"));
        return subtotal.multiply(new BigDecimal("0.30"));
    }
}

Now the shared abstraction becomes a bug factory.

• flags everywhere

• branching logic explosion

• “generic” calculator that no longer represents a real concept

The duplication was never the code.

The real mistake was coupling two unrelated business concepts because they happened to look similar at one moment in time.

✅ DRY is about knowledge, not code

Read more

Subscribe now

Jenkins does NOT equal continuous integration (CI).

Many teams believe:

“We have Jenkins, therefore, we are practicing CI.”

This is wrong.

Jenkins is just a tool

If a team has Jenkins, but developers work on long-lived branches for days or weeks, then they are not practicing CI.

If merges happen only before release day, they are not practicing CI.

If testing is mostly manual, they are not practicing CI.

If bugs are discovered late, they are not practicing CI.

No TDD = no CI

Without automated tests you CANNOT:

• merge code frequently without fear of breaking things

• ship small, incremental changes

• catch regressions early in the pipeline

• get fast feedback from unit tests

• verify system behavior with acceptance tests

Releases are big, risky, and infrequent.

Do you have CI?

Don’t ask:

“Do we have Jenkins?”

Ask:

• Do we merge into main daily?

• Are we protected by automated tests?

• Do we have Trunk Based Development (TBD) or short-lived branches?

• Can we merge safely multiple times per day?

• Is the main branch always releasable?

If the answer is “no” to most of these, you don’t have CI.

You have a build server.

CI in practice

This workshop is for Senior Engineers & Tech Leads who are:
▪ Stuck with stressful releases
▪ Stay late fixing production deployments
▪ See releases break critical paths that nobody tested

Join the CI/CD workshop →

Limited spots. Register now with the early bird discount - 100 EUR off with code EARLYBIRD100

Subscribe now

You went straight into microservices because… well, everyone else was doing it.

“Scalable.”
“Cloud-native.”
“Future-proof.”
“Independent deployments.”

Suddenly there are:

• 12 services

• 14 repositories

• RabbitMQ

• Kafka

• Kubernetes

…before you even fully understand the domain.

❌ The Distributed Monolith Trap

You are guessing domain boundaries, so microservice boundaries based on your guesses.

The problem is you discover, during the next months, that you’ve modelled the domain in the wrong way. You discover that your microservices are too tightly coupled, and to implement a simple User Story, you have to coordinate changes across multiple microservices. Changes become expensive.

Immediately jumping to microservices — especially the wrong microservices — is expensive to build and expensive to run.

You can call it “microservices”…

…but it’s just a distributed monolith.

⚠️Fear of the Monolith

Some developers hear “monolith” and imagine:

• massive bloated classes

• tangled dependencies

• painful future migrations

But not every monolith has to become a “big ball of mud.”

🚀 Register now: ATDD – Acceptance Testing Workshop
Get 100 EUR off with code DISCOUNT_100

Hexagonal Architecture Inside the Modules

• Modular Monolith → all the modules are deployed as a single artifact

• Microservices → each microservice is deployed independently

Read more

Subscribe now

It’s not because developers hate talking.

Developers can talk for hours — just ask them about architecture.

The 6-person call where 2 people speak

Two people talk the entire time.

The rest are:

• on mute

• pretending to follow

• occasionally saying “yeah” at the wrong moment

The developer translation layer

• “we’ll figure it out” → this is now my problem

• “should be simple” → it absolutely isn’t

• “just a small change” → redesign incoming

• “we can iterate” → nothing is defined

You get asked for estimates on something that is vaguely described.

You give a number.

Everyone writes it down like it’s a fact.

Then later the same number becomes:

“why is this taking longer than expected?”

What developers actually need

Developers don’t need more meetings.

They don’t need longer discussions either.

Not 20 minutes of debate.

Not “we’ll figure it out later.”

Just enough concrete detail so the work isn’t being invented mid-implementation.

A few examples instead of abstract descriptions.

Most of the frustration comes from building something that wasn’t fully defined, and then being judged as if it was.

Vague requests → Concrete examples

This is exactly where acceptance testing and ATDD help.

They take requirements that sound like:

“It should handle refunds properly”

and turn them into concrete examples developers can implement.

Acceptance tests turn that into questions like:

• Given this input, what should happen?

• When this happens, what is the expected output?

• What should not happen?

⚡Ready to see this in action?

I’m running a hands-on ATDD – Acceptance Testing Workshop on May 25–26 (4 hours).

Join the workshop →

Limited spots. Register now - 100 EUR off with code DISCOUNT_100

Subscribe now

I thought bugs came from bad code.

But I noticed that a lot of the bugs we were fixing in QA…
weren’t really coding bugs.

The implementation matched the ticket.
The unit tests passed.
The code review passed.

And somehow, the feature was “wrong behavior.”

Not because the code was broken.

But because people had imagined different things in their mind — usually in the same meeting where everyone thought they agreed.

That mismatch only shows up later.

QA raises issues.

The product owner says: “That’s not what I expected.”

Acceptance Testing Isn’t Really About Testing

Acceptance testing — or ATDD — isn’t just about “more tests.”

It’s about creating shared understanding before implementation starts.

It’s asking questions like:

• What should happen here?

• What does success actually look like?

• Can we describe this with real examples?

• What happens in edge cases?

That’s where a lot of bugs get prevented.

Not during coding.

During alignment.

⛔ Without Acceptance Testing

The developer gets a ticket: “Apply a 10% discount to orders over €100.”

The developer reads the ticket and assumes:

• discount applies before tax

• only for logged-in users

• applies to the entire cart total

QA, later on, tests and assumes:

• discount applies after tax

• also works for guest users

• applies per item, not cart total

The product owner expected:

• discount applies before tax

• only for logged-in users

• based on cart total

Same ticket. Three different interpretations.

And nobody realises until QA finds it — or worse, after release.

✅ With Acceptance Testing

Before coding starts, the team writes examples like:

• Given the customer is logged in, when the customer makes an order of €120, then a 10% discount is applied before tax

• Given the customer is logged in, when the customer makes an order of €80, no discount is applied

• Given a guest user, when the guest makes an order of €150, no discount is applied

Suddenly, there’s no room for interpretation.

Everyone is reacting to the same examples — not their own mental version of the feature.

That’s the shift.

Acceptance testing doesn’t add “more testing.”

It removes guessing before the code is even written.

Why Teams Skip This

Teams want to jump straight into implementation.

Writing code feels productive.

Clarifying expectations sometimes feels like “extra process.”

Until the feature comes back three times for rework.

Then suddenly those early conversations don’t seem so expensive anymore.

See It In Practice

I’m running a live, hands-on workshop where we build acceptance tests. We go from vague requirements → to concrete examples → to executable acceptance tests.

⚡In 4 hours, you’ll:

• Design acceptance tests using DSL + driver architecture

• Apply ATDD Cycle with AI to write an acceptance test and implement the change

• Learn how to introduce acceptance testing in your team

📅 May 25-26, 2:00-4:00 PM CET

Join the workshop →

Limited spots. Register now and get 100 EUR off with code DISCOUNT_100

Subscribe now

Logging injected directly into use cases, services and handlers is justified as:

• “we need debugging”

• “we need traceability”

• “we need observability”

But…

❌Logger in every use case

• every use case now knows about logging

• business logic is mixed with runtime reporting

• logs become part of how code is “explained”

class CreateOrderUseCase {

    private final Logger logger;

    public CreateOrderUseCase(Logger logger) {
        this.logger = logger;
    }

    public OrderResult execute(CreateOrderCommand cmd) {

        logger.info("CreateOrder started");

        Order order = new Order(cmd.userId());

        logger.info("Order created", Map.of(
            "orderId", order.getId()
        ));

        return new OrderResult(order.getId());
    }
}

⚠️Structured logging doesn’t fix the real issue

After a while, debugging becomes painful, so you switch to structured logging:

logger.info("OrderCreated", Map.of(
    "userId", cmd.userId(),
    "orderId", order.getId()
));

This is better:

• easier to search

• consistent format

• better for tools

But the real problem doesn’t change.

You still have logging calls inside every use case.

You’ve just improved how logs look.

🚀 Register now: ATDD – Acceptance Testing Workshop
Get 100 EUR off with code DISCOUNT_100

✅Infrastructure Layer: Logging outside the use case

Read more

Subscribe now

I thought software development meant building things.

Then I got my first job.

And most of my time wasn’t building.

It was retesting.

Fix something → test it
Add something → test it
Change something small → test everything again

The system felt fragile.
Like it was waiting to break.

No one called it “testing”—I was a developer, after all.
But in reality, I was running the same manual checks again and again just to feel confident enough to move forward.

It was exhausting.

The first breakthrough

Then I discovered unit tests.

Write the test once → run it forever.

No more clicking through the same flows.
No more guessing what broke.

If something failed, I knew exactly where.

It felt like I finally unlocked “real” development.

Everything passed. Things still broke.

But then something didn’t make sense.

All my tests were passing.

And production bugs…
weren’t really going down.

That was the confusing part.

If everything was “tested”…
why were things still breaking?

Here’s what I was missing:

Unit tests tell you that pieces of your system work.

They don’t tell you that the system works.

You don’t ship code. You ship behavior.

You can have 100% unit test coverage…
and still ship a broken feature.

Because users don’t interact with your classes.

They interact with behavior.

That’s what led me to acceptance tests.

Tests that don’t care how the code works (you can write them even if your code is a Ball of Mud)—
only whether the system behaves correctly from the outside.

Like a user would experience it.

Because in the end:

You don’t ship code.
You ship behavior.

See It in Practice

Want to see how acceptance tests can save you time, frustration, and endless bug loops? I’m running a hands-on Acceptance Testing Workshop on May 25–26 (4 hours).

Join the workshop →

Limited spots. Register now - 100 EUR off with code DISCOUNT_100

Subscribe now

Most developers test the same behavior twice.

Once through the API.
Once through the UI.

Two separate tests suites.
Two sets of assertions.
Double the maintenance costs.

And sooner or later?…

The API tests pass.
The UI tests fail randomly.
Nobody fully trusts either.

⚠️Duplication is risky

If you test both channels, you end up with two completely separate test suites:

• An API test suite that sends HTTP requests and checks JSON responses

• A UI test suite that drives a browser with Selenium or Playwright

Same scenarios. No shared structure. No shared assertions.

When a requirement changes, you update two tests instead of one.

Worse — the two suites start contradicting each other.

The API tests check one set of scenarios.
The UI tests check a slightly different set.

Gaps appear. Bugs hide in the gaps.

Want to skip the pain and go straight to the solution?

I’m running a live, hands-on workshop where we build acceptance tests that run against both the API and UI — compile-time safe, IDE-guided and refactor-proof.

Join the workshop →

Limited spots. Register now with the early bird discount - 100 EUR off with code EARLYBIRD100

💡What Changed Everything for Me

Instead of writing the same test twice…

Read more

Subscribe now

You followed the pattern.

You split your domain from infrastructure.
You added interfaces.
You called them “driven ports.”

It looks clean.

But then:

• Your tests are full of mocks

• Refactoring breaks everything

• Your domain still feels… tied to something

And you can’t quite explain why.

Driven Ports Gone Wrong

Most developers know they need interfaces between their domain and infrastructure. But the mistake isn’t forgetting to add them.

It’s adding them at the wrong level of abstraction.

Your driven port might look clean on the surface — but if infrastructure concepts are leaking through, your domain is already compromised.

What a Driven Port Should Do

A driven port isn’t:

• a wrapper around a framework class

• a thin layer over a database driver

• a generic interface that exposes how things work underneath

A driven port is:

• something the domain needs to get its work done

• a boundary expressed in domain language

• a contract that hides how things are implemented

The key question: does this interface expose what the domain needs, or how the infrastructure works?

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

❌ Driven Ports That Leak Infrastructure

interface OrderRepository {
    ResultSet executeQuery(String sql);
    void executeBatch(String[] statements);
}

interface PaymentGateway {
    HttpResponse post(String url, Map<String, String> headers, String jsonBody);
}

interface NotificationService {
    void sendRawMessage(String host, int port, String payload);
}

interface ProductCatalog {
    Map<String, AttributeValue> getItem(String tableName, Map<String, AttributeValue> key);
}

What’s wrong here?

• OrderRepository exposes SQL — the domain now knows it’s a relational database

• PaymentGateway exposes HTTP — the domain now knows it’s a REST API

• NotificationService exposes host and port — the domain now knows about transport protocols

• ProductCatalog exposes AttributeValue — the domain now knows it’s DynamoDB

Your domain is shaped by your infrastructure. Change the database, the API, or the message broker — and your domain code has to change too.

That’s the opposite of decoupling.

Read more

Subscribe now

The Unit Test Passed. The Customer Was Overcharged.

Your unit tests can’t catch this category of bug. Here’s proof.

Before, I showed you how Marco’s team shipped a broken tax calculation despite having green tests across the board.

I received this question:

“Can you show me the actual code? I want to prove this to my team.”

So here it is. A concrete example you can drop into any conversation about test strategy.

The Setup

We have a simple e-commerce system. When a customer places an order, the system needs to look up the tax rate from an external Tax API and calculate the total.

public class TaxGateway {
    private final HttpClient httpClient;

    public double getTaxRate(String countryCode) {
        HttpResponse response = httpClient.get(
            "https://tax-api.example.com/rates/" + countryCode
        );
        JsonObject json = JsonParser.parse(response.getBody());
        return json.getDouble("rate");
    }
}

public class OrderService {
    private final TaxGateway taxGateway;

    public Order placeOrder(String countryCode, double unitPrice, int quantity) {
        double basePrice = unitPrice * quantity;
        double taxRate = taxGateway.getTaxRate(countryCode);
        double taxAmount = basePrice * taxRate;
        return new Order(basePrice, taxAmount, basePrice + taxAmount);
    }
}

The code looks correct. OrderService calls TaxGateway, which makes an HTTP call to the external Tax API. Everything is wired up properly.

But there’s a hidden bug. The Tax API returns rates as whole numbers — { "rate": 8 } for 8%. The TaxGateway reads this value and returns it directly. It should divide by 100 first, but it doesn’t.

The Unit Test: GREEN ✅

@Test
void shouldApplyTaxRateFromExternalService() {
    when(taxGatewayMock.getTaxRate("US"))
        .thenReturn(0.08);

    Order order = orderService.placeOrder("US", 20.00, 5);

    assertEquals(100.00, order.getBasePrice());
    assertEquals(8.00, order.getTaxAmount());
    assertEquals(108.00, order.getTotalPrice());
}

This test passes. And it should pass — given the mock’s return value, the math is perfect.

The developer sees green. CI sees green. The PR gets approved.

But the mock is a lie. It returns 0.08 because that’s what the developer assumed TaxGateway would return. The mock replaces the entire TaxGateway — the HTTP call never happens, the JSON parsing never runs, and the missing / 100.0 is never exposed.

In production, the customer orders $100 worth of products and gets charged $900 — because 100 * 8 = 800 in tax.

And here’s the thing: you can’t fix this with more unit tests. You could unit test every single class — OrderService, TaxGateway — and they would all pass. The bug lives at the boundary between your code and the real world, and unit tests must mock that boundary. If the mock is wrong, every test built on top of it is wrong too.

The Acceptance Test: RED ❌

Now here’s the same scenario written as an acceptance test:

@Test
void shouldCalculateCorrectTotalWithCountryTaxRate() {
    scenario
        .given().product()
            .withUnitPrice("20.00")
        .and().country()
            .withCode("US")
            .withTaxRate("8%")
        .when().placeOrder()
            .withQuantity("5")
            .withCountry("US")
        .then().shouldSucceed()
        .and().order()
            .hasBasePrice("100.00")
            .hasTaxAmount("8.00")
            .hasTotalPrice("108.00");
}

This test runs against the real system — real backend, real database, real TaxGateway code — but with a stub for the external Tax API. The given().country().withTaxRate("8%") line configures the Tax API Stub to return { "rate": 8 } — exactly what the real Tax API would return.

The real TaxGateway code executes. The HTTP call fires against the Tax API Stub. The JSON is parsed. And the missing / 100.0 is exposed.

Result: FAILS.

Expected taxAmount: 8.00
Actual taxAmount:   800.00

Expected totalPrice: 108.00
Actual totalPrice:   900.00

The Tax API Stub returned { "rate": 8 }, just like the real API would. TaxGateway read the value and returned 8 directly to OrderService, which calculated 100 * 8 = 800 in tax. In the unit test, the mock hid this by returning 0.08 directly. In the acceptance test, the real code path runs and the bug is caught.

Why Unit Tests Can Never Catch This

The bug isn’t in OrderService. The math is correct. The wiring is correct. The bug is inside TaxGateway — in how it parses the external API response.

But the unit test for OrderService mocks out TaxGateway entirely. The HTTP call never fires. The JSON parsing never runs. The bug is invisible.

The unit test:

• Tests OrderService in isolation

• Replaces TaxGateway with a mock

• The mock returns what the developer assumes the gateway returns

• The real HTTP call and JSON parsing never execute

• Can’t catch a bug inside the mocked component

The acceptance test:

• Tests the full feature against the real system with stubs for external dependencies

• The real TaxGateway code runs — HTTP call, JSON parsing, everything

• The Tax API Stub behaves like the real Tax API — returning { "rate": 8 }

• Catches bugs anywhere in the chain, not just in the class under test

Unit tests verify your logic given your assumptions. Acceptance tests verify the feature works regardless of your assumptions. No amount of unit testing can catch a bug that’s hidden behind a mock.

But Wait — How Do We Know the Stub Is Correct?

Fair question. If the acceptance test uses a Tax API Stub instead of the real Tax API, couldn’t the stub itself be wrong?

That’s where contract tests come in. A contract test runs the same scenarios against both the real Tax API and the Tax API Stub, and verifies they return the same results. If the stub drifts from reality, the contract test fails.

So the full safety net looks like this:

• Unit tests verify each component’s logic in isolation

• Acceptance tests verify the feature works end-to-end, using stubs for external systems

• Contract tests verify the stubs behave like the real external systems

Each layer catches a different category of bug. Skip any one of them, and you have a blind spot.

This Isn’t an Edge Case

The bug in our example was a wrong assumption about the API response format. But this is just one of many ways external system integration breaks:

• Wrong format assumption — The Tax API returns { "rate": 8 } meaning 8%, but your code treats it as 0.08. Your mock returns whatever you assumed, so the unit test passes.

• Hardcoded value — The developer hardcoded return 0.10 inside TaxGateway while building the feature, planning to wire up the HTTP call “later.” Later never came. The unit test mocks out TaxGateway entirely, so the hardcoded value is never executed.

• Wrong field — The API returns { "taxRate": 8, "importRate": 12 } and your code reads importRate instead of taxRate. Your mock only returns the field you expected, so the unit test passes.

• Stale mapping — The API used to return { "rate": 8 } but v2 changed it to { "tax": { "rate": 8 } }. Your code still reads the top-level field. Your mock still returns the old format, so the unit test passes.

This pattern shows up constantly across all types of external integrations:

• A payment gateway that returns amounts in cents, but your code treats them as dollars.

• A shipping API that changed its response format in v2, but your mocks still return v1.

• An inventory service that returns "OUT_OF_STOCK" as a string, but your mock returns a boolean false.

• A currency API that returns rates with 6 decimal places, but your mock rounds to 2.

Every one of these passes unit tests — because the mock is the assumption. If the assumption is wrong, the mock is wrong, and the test is worthless.

Every one of these ships to production. Every one of these gets caught by acceptance tests.

The Takeaway

Unit tests answer: “Does this component do its job correctly, given my assumptions?”

Acceptance tests answer: “Does this feature work the way the customer expects?”

Contract tests answer: “Are my assumptions about external systems correct?”

These are fundamentally different questions. If you’re only asking the first one, you’re leaving the other two for your customers to answer.

Want to learn how to write acceptance tests like this?

I’m running a live workshop: Stop Shipping Bugs: Acceptance Tests Workshop.

4 hours. Two evenings. Live on Zoom, with me.

⚡ I’ll walk you through the full architecture — DSL, Drivers, how it all fits together — and by the end, you’ll have written a real acceptance test from scenario to assertion.

📅 May 25-26, 2:00-4:00 PM CET

Join the workshop →

Limited spots. Register now with the early bird discount - 100 EUR off with code EARLYBIRD100

— Valentina

Subscribe now

“Where should validation go?”

You’ve seen:

• validation in controllers

• validation in services

• validation duplicated in multiple places

And no one is really sure what’s “correct”.

So let’s make it concrete.

1. Validation at the API layer (input checks)

This is the first place data enters your system.

Here you check things like:

• required fields exist

• types are correct

• format is valid (email, date, UUID, etc.)

Example:

• email is missing → reject request

• age is a string → reject request

• orderDate is "not-a-date" → reject request

The API layer’s job is to fail fast with clear errors for malformed input, so the application and domain layers can work with clean, well-typed data.

2. Validation in the Application Layer (policies - use case rules)

This is where most real mistakes happen.

This layer handles rules like:

• cannot create shipment if stock is insufficient

• order cannot be placed if cart is empty

• cannot refund payment if transaction is already settled beyond refund window

• cannot process payment if currency is not supported for merchant

• cannot cancel order after it has been shipped

• cannot apply discount code if it is expired or not eligible

These are not input checks anymore.

They are policies. A policy is a rule about whether an action is allowed right now, given the current state of the world.

Every one of these needs something outside the aggregate itself to evaluate — inventory, the clock, a merchant config, a discount catalog. In DDD terms, they cross the aggregate boundary.

That’s why they don’t belong in the domain object. An Order alone doesn’t know whether stock exists. The application layer orchestrates: it fetches what’s needed, evaluates the policy, and either proceeds or rejects.

Example flow:

• API sends a valid, well-formed request

• application checks the relevant policies

• if a policy fails → reject here, before touching the domain

This is where you stop things that are technically valid, but not allowed in this situation.

⚡ Register now: ATDD – Acceptance Testing Workshop
Get 100 EUR off with code EARLYBIRD100

3. Validation in the Domain Layer (invariants)

This is the strictest level.

These are rules that must never be broken, no matter where the code is called from.

An invariant is a rule that must always hold for a given object, no matter who calls it, from where, at what time.

Examples:

• order must always have at least one line item

• order total cannot be negative

• payment cannot be “SUCCESSFUL” without a transaction reference

• reserved quantity cannot exceed available stock

• order status must follow valid transitions: CREATED → PAID → SHIPPED → DELIVERED

• order cannot have SHIPPED status without a tracking number

If this is broken, your system is already inconsistent.

So this validation:

• is enforced when creating or modifying core objects

• is tied directly to the business model itself

The key principle: the domain never trusts its callers.

Even if the API already checked something, the domain re-checks any invariant. Why? Because the domain can be invoked from anywhere — a job, an event, a test, another bounded context. It cannot assume a well-behaved API sits in front of it.

What you should NOT do

This is where most real-world code goes wrong:

Read more

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

Subscribe now

Now you’ve written a test.

But does it fail?

If it doesn’t, you have no proof that your implementation makes a difference.

A test that always passes is worse than no test.

It gives you a false sense of security.
It hides bugs instead of exposing them.

That’s why the RED step matters.

You watch it fail.

That failure is evidence.

Later, when it turns GREEN, you know the code caused it — not luck, not a misconfigured test, not a false positive.

⚡Can the Test Actually Fail?

If you’ve seen it fail:

• It confirms the test is valid.

• It means that the later GREEN step actually proves your code works.

• It protects you from false positives — those sneaky tests that always pass, giving you a fake sense of correctness.

TDD makes it unavoidable.

No RED? No trust in your code.

Why Developers Skip It (And Regret It)

It’s tempting to skip RED:

• “I know this code will work, so why watch it fail?”

• “It’s faster to just implement and see GREEN.”

But skipping RED is like installing a fire alarm that never goes off — you won’t know something’s broken until it’s too late.

Watching the test fail is the cheapest, fastest bug prevention you can get.

RED Before GREEN

TDD isn’t just about writing tests.

It’s about proof.

Proof that your test matters.
Proof that your code works.
Proof that the system behaves as expected.

You can take a step further with Acceptance Test–Driven Development (ATDD).

Instead of just asking:

“Does my code work?”

ATDD asks:

“Does the system behave as the user expects?”

It’s less about writing more tests and more about making sure everyone — Devs, QA, and Product Owners — agrees on what “done” really means.

The cool part? Fewer arguments about whether something is broken, fewer regression bugs, and a lot less late-night firefighting — because expectations are clear before you write a single line of code.

🚀 Join me for: ATDD – Acceptance Testing Workshop

Join the workshop →

Limited spots. Get 100 EUR off with code EARLYBIRD100

Subscribe now

Developers like DTOs. And wrappers. And more wrappers.

Until your “simple” API layer turns into a tower of classes no one can read, tests become painful, and adding a new field feels like a chore.

DTOs and mappers are tools — not dogma. Clean Architecture doesn’t say “wrap everything 5 times.” It says: be intentional about what crosses boundaries.

The Problem

Many codebases follow a pattern like this:

Domain objects
   ↓
Domain DTO
   ↓
Application DTO
   ↓
API DTO
   ↓
JSON

That’s 3–4 layers of wrapping for the same data, plus mappers everywhere.

To be clear — sometimes multiple layers are justified. If you're serving both GraphQL and REST from the same domain, or maintaining a published API contract that must change independently from your domain, extra DTOs earn their keep. The problem isn't layers — it's layers that exist "just in case."

The result:

• Lots of boilerplate

• Hard to understand what actually changes the domain

• Fragile tests because every layer must be mocked

• Accidental complexity: devs can’t tell which layer matters for business rules

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

💡Code Example

Over-Wrapping Everything ❌

Read more

Subscribe now

It’s tempting to write code fast and plan to clean it up later.

Skip the naming.
Duplicate a bit of logic.
Add “just one more if”.

Messy Code Is a Tax

Every change on top of messy code costs more:

• Features take longer because you can’t trust what’s already there. You read more than you write, trying to figure out what the code actually does.

• Bugs hide in unclear abstractions and duplicated logic. You fix something in one place and miss the copy-pasted version three files over.

• Refactoring is painful because dependencies are tangled. You pull one thread and everything unravels.

So you slow down. Every change gets harder. Every decision gets riskier. Every task takes longer than it should.

And the worst part? You know you should fix it, but now you can’t justify the time — because there’s a backlog of features waiting.

This is how codebases rot. Not from one bad decision, but from hundreds of small ones that compound.

No matter how slow you are writing clean code, you will always be slower if you make a mess. — Uncle Bob

Clean code may feel slower at first. But every line you write on top of it is faster, safer, and less stressful.

The hard truth: Messy code always costs more time than taking the time to do it right.

But How Do You Keep Code Clean — and Keep It Working?

Say you’ve written clean, well-structured code. You refactor a service, rename some methods, extract a class. The code reads well. You’re confident it’s correct.

But is it?

How do you know that the order flow still works end to end? That the payment integration didn’t break? That a customer can still check out?

You don’t — unless you have tests that verify behavior, not implementation.

Clean Code Needs a Safety Net

Unit tests are fast. They give you quick feedback and make refactoring feel safe.

But even the best unit tests have a blind spot.

They verify pieces in isolation. They mock the database, stub the API, skip the serialization. So when everything passes, you know your unit logic works — but you don’t know if the system logic works.

The gaps live at the boundaries: the database query that returns data in a different shape than you assumed. The HTTP layer that silently drops a field. The integration that worked in isolation but breaks when it meets real I/O.

Unit tests can’t catch these problems — not because they’re poorly written, but because that’s not what they’re designed to do.

Acceptance tests fill that gap. They exercise the system end-to-end, through the same boundaries your users hit:

A unit test says: “This function calculates the discount correctly.”

An acceptance test says: “When a customer applies a coupon at checkout, the total price is reduced and the order goes through.”

They’re slower than unit tests. You won’t run them on every keystroke. But they answer the question that unit tests can’t:

Does this actually work for the user?

Clean Code Without Acceptance Tests Is a Risk

Clean code keeps you moving fast. Unit tests ensure your refactoring doesn’t break the unit's logic. So why do you need anything else?

Because unit tests verify your code works in isolation. Acceptance tests verify your system works in reality.

You can have clean code, a full suite of passing unit tests, and still deploy a broken checkout flow — because the bug lives at a boundary that no unit test touches.

• Clean code lets you move fast.

• Unit tests make sure the pieces work.

• Acceptance tests make sure the system works.

One without the other will eventually slow you down.

You need all three.

Where do you start?

If you’re working in a greenfield project, you can build all three from day one.

But what about legacy code — where there are no tests, and the code is too messy to unit test?

You don’t start with unit tests. You can’t — the code isn’t structured for them yet.

You start with acceptance tests.

They don’t need clean code. They don’t need dependency injection or isolated modules. They test the system from the outside, through the same entry points your users hit. That means you can add them to any codebase, no matter how messy.

Once acceptance tests are in place, you have a safety net. Now you can refactor toward clean code and add unit tests — without breaking what already works.

Ready to put this into practice?

I’m running a hands-on Acceptance Testing Workshop on May 27–28 (4 hours).

Join the workshop →

Limited spots. Register now with the early bird discount - 100 EUR off with code EARLYBIRD100

Subscribe now

When I first got into TDD, I thought I had it figured out.

I was reading Kent Beck, Martin Fowler… all of it just made sense.

I was really into clean code and unit tests.

I knew about e2e testing, but I saw it as QA’s job, not mine. Those tests were really badly written and constantly breaking. And to be honest, I saw it as boring and something that developers shouldn’t be doing.

I saw the whole CI/CD pipeline as a separate thing done by a DevOps engineer — not me.

Still, no matter how many unit tests were written, management kept on complaining:

“Why are there still so many bugs?”

“Why is everything taking so long?”

“I thought the last release fixed this!”

“Customers are frustrated — something has to change!”

⚡Want to skip the pain and go straight to the solution?

Every Release Is a Nightmare doesn’t have to be your reality.

Join the workshop →

Limited spots. Register now with the early bird discount - 100 EUR off with code EARLYBIRD100

A Story That Stuck With Me

Later, I stumbled across something Dave Farley shared. The teams were practicing TDD… they were lots of unit tests, all green — but the system was failing in QA environment, for possibly weeks. QA engineers constantly had to play catch-up with their e2e tests.

And that’s what got Dave Farley to develop acceptance tests.

I realized I had to see the bigger picture.

That meant looking at the whole continuous delivery pipeline and understanding how all the pieces fit together.

In the commit stage, we’re doing TDD and writing unit tests (and component tests)— making sure each component behaves the way we expect.

But further down the pipeline, there’s the acceptance stage, where ATDD comes in — checking that all those pieces actually work together as a system.

⚡TDD & ATDD in Microservice Architecture

ATDD: Seeing the System as a Whole

If you zoom out and look at the system… it starts with a user story.

And that story comes with acceptance criteria — the conditions that tell you: did we actually deliver what the user needs?

Instead of just reading those criteria… we can turn each one into an acceptance test. It’s basically like 1:1 mapping.

And these tests are very different from unit tests.

Read more