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

Subscribe now

Every time I write about acceptance testing, someone asks:

This makes sense. But how do I actually start?

I’ve gotten this in DMs. In comments. In conversations with Tech Leads.

They understand why acceptance tests matter.
They’ve felt the pain of shipping bugs.
They’ve read about ATDD.

But when they sit down to actually write one?

They stare at a blank file and think:

• Where do you put the acceptance tests?

• How do you structure them so they don’t become as fragile as the E2E tests you’re trying to replace?

• How do you design them so your whole team can write and maintain them — not just the one person who “gets testing”?

You want tests that are:

Clean. Readable. Runs in seconds. Survives refactors.

But…

• How do you build the DSL that makes it work?

• How do you wire up the Drivers that connect these tests to your actual system?

• How do you structure all of this so it scales across your whole team?

Hands-On Acceptance Testing

That’s why I built a live, hands-on workshop.

This isn’t a course you watch alone at 2x speed and forget by Friday.

What you’ll learn:

1. The architecture. How acceptance tests are structured — DSL, Drivers, the layers that make them maintainable. You’ll understand why some acceptance tests become unmaintainable spaghetti and yours won’t.

2. ATDD Cycle with AI. We’ll design an acceptance test together — from a business scenario all the way through to verification. You’ll get to see the layers (DSL & Drivers) in practice.

3. Apply it with your team. How to introduce acceptance testing into an existing project without stopping everything. How to get buy-in. How to start.

When: May 25–26, 2026 | 2-4 PM CET
(FYI: May 27–28 | 5-7 PM CET — Fully Booked)
Where: Live on Zoom
Duration: 4 hours (2 sessions x 2 hours)

💻 Who it’s for: Senior Engineers and Tech Leads who are tired of shipping bugs and ready to do something about it

🚀 Register: ATDD – Acceptance Testing Workshop
Get €100 off with code EARLYBIRD100

Don’t spend next month debugging something that should have been caught before it shipped.

Join the workshop →

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

Subscribe now

This test doesn’t lie:

scenario
    .given().product().withUnitPrice(20.00)
    .and().country().withCode("US").withTaxRate(0.08)
    .when().placeOrder().withQuantity(5).withCountry("US")
    .then().shouldSucceed()
    .and().order()
        .hasBasePrice(100.00)
        .hasTaxAmount(8.00)
        .hasTotalPrice(108.00);

Clean. Readable. Runs in seconds. Survives refactors.

But how does it actually work?

What’s behind .given().product().withUnitPrice(20.00)? How does the same test run against both the API and the UI? Where does the “magic” come from?

I’m going to take this test apart, layer by layer, and show you exactly how the DSL is built.

⚡Ready to see this in action?

I’m running a live, hands-on workshop where we build acceptance tests using this exact architecture. 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

The four layers

An acceptance test DSL has four layers. Each layer has one job, and they only talk to the layer directly below them:

Test           →  what we're testing (the scenario)
DSL            →  how we express it (the fluent API)
Driver Port    →  what we need from the system (interfaces)
Driver Adapter →  how we interact with the system (API calls, browser clicks)

This separation is the entire reason acceptance tests are maintainable. Remove any layer and the whole thing falls apart.

Layer 1: The Test

This is what you’ve already seen. A test method that reads like a business scenario:

@TestTemplate
@Channel({ChannelType.UI, ChannelType.API})
void shouldCalculateCorrectTotalWithTaxRate() {
    scenario
        .given().product()
            .withUnitPrice(20.00)
        .and().country()
            .withCode("US")
            .withTaxRate(0.08)
        .when().placeOrder()
            .withQuantity(5)
            .withCountry("US")
        .then().shouldSucceed()
        .and().order()
            .hasBasePrice(100.00)
            .hasTaxAmount(8.00)
            .hasTotalPrice(108.00);
}

Notice what’s not here:

• No URLs

• No HTTP calls

• No CSS selectors

• No database queries

• No setup or teardown

The test only knows what it’s testing. It has no idea how the system works under the hood. That’s the point.

The @Channel annotation is interesting — it tells the test runner to execute this same test once through the API and once through the UI. Same scenario, same assertions, two completely different ways of talking to the system. Here’s how it actually works.

Read more

Subscribe now

Marco stared at the Slack message from support.

“Customer says they were charged $110 on a $100 order. Tax should have been $8, not $10.”

He pulled up the dashboard. All tests green. CI/CD pipeline — clean. Not a single failure in weeks.

And yet, the tax calculation was wrong.

Marco spent the next hour tracing the bug. The tax calculation itself was correct. The unit test proved it: pass in a rate, get back the right amount. No issues there.

The problem was simpler than that. And worse.

The developer who built the order service had hardcoded the tax rate as a constant — 10% — while working on the feature. The plan was to pull it from the country configuration later.

But “later” never came.

The feature shipped, the tests passed, and nobody noticed.

The unit test for the tax calculation? It tested the math. And the math was right. 10% of $100 is $10. Test passes.

But the feature was wrong. The customer was in a state with an 8% tax rate, and the system charged 10% because it never actually looked up the rate.

E2E tests? They had those too. But the E2E test just checked that the confirmation page appeared after placing an order. It never verified the actual total.

The feature was broken. And no test caught it.

Here’s the uncomfortable truth most teams don’t talk about:

Unit tests verify that individual components work. They can’t tell you whether the feature works. Marco’s tax calculation was correct — it just used the wrong input.

E2E tests verify the happy path through the UI. But they’re slow, fragile, and they often check that something shows up on screen, not that the right thing shows up.

There’s a massive gap between “all my unit tests pass” and “this feature actually works as the customer expects.”

That gap is where your production bugs live.

There’s a test type that fills this gap

It’s called an acceptance test.

Not another E2E test. Something fundamentally different.

An acceptance test is an executable specification of system behavior. It answers one question: does this feature work the way the business expects?

Here’s what Marco’s E2E test looked like:

@Test
void testPlaceOrder() {
    driver.get(baseUrl + "/products");
    driver.findElement(By.id("product-1")).click();
    driver.findElement(By.id("add-to-cart")).click();
    driver.findElement(By.id("quantity")).sendKeys("5");
    driver.findElement(By.id("checkout")).click();
    driver.findElement(By.id("place-order")).click();

    WebElement confirmation = driver.findElement(By.id("confirmation"));
    assertTrue(confirmation.isDisplayed());
}

Brittle. Tied to the UI. Breaks if someone renames a button. And it only checks if the confirmation page shows up — it never verified the actual total.

Here’s the same scenario as an acceptance test:

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

No browser. No CSS selectors. No flaky waits.

Just a clear business scenario: given a product at $20, a quantity of 5, and a country with 8% tax — the base price should be $100, the tax should be $8, and the total should be $108.

This test would have caught Marco’s bug immediately. The system would return a total of $110 instead of $108 — test fails. The hardcoded constant would have been found before it ever reached a customer.

Marco’s team? After they introduced acceptance tests, customer-reported bugs dropped dramatically in the first few months. Not because they wrote more tests — but because they wrote the right tests.

Want to learn how to write 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 27-28, 5:00-7:00 PM CET

Join the workshop →

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

— Valentina

Subscribe now

Ever opened a class and thought, ‘What does this thing even do?’

It starts small, but over time…

❌One Class Tries to Do It All

OrderService becomes the place where everything goes.

Need to send an email? Add it to OrderService.
Need to generate an invoice? Add it to OrderService.
Need to call the shipping API? Add it to OrderService.

Suddenly, the class looks like this:

OrderService

// Own reposponsibilities
- createOrder()
- cancelOrder()
- getOrderById()

// Extra responsibilities
- generateInvoice()
- shipOrder()
- sendEmail()
- trackOrder()

.... a laundry list of responsibilities...

At first, it feels convenient.

Each method is small.
Each feature made sense when it was added.

But over time, this class becomes large, fragile, and difficult to change…

Because it’s responsible for too many different things:

• order logic

• invoice generation

• shipping logic

• email notifications

One class does all of it.

💡Want to make it safe to redesign your architecture without breaking everything?

Join the workshop →

Limited spots. Early bird discount - 100 EUR off with code EARLYBIRD100

✅One Class, One Job

The Single Responsibility Principle (SRP) prevents this from happening.

A class should have one reason to change.

Not five. Not ten. One.

Instead of putting everything into OrderService, split responsibilities:

OrderService
- createOrder()
- cancelOrder()
- getOrderById()

InvoiceService
- generateInvoice()

EmailService
- sendEmail()

ShippingService
- shipOrder()
- trackOrder()

Now each class changes for one reason.

• Order logic changes → OrderService

• Invoice logic changes → InvoiceService

• Email logic changes → EmailService

• Shipping logic changes → ShippingService

💡SRP Isn’t About One Method or Tiny Classes

Read more

Subscribe now

Bad Architecture Is Expensive

The “shortcut” decisions another developer made six months ago are now your daily headache.

Meetings start to revolve around workarounds. Every new feature is debated: “Is it safe? Will it break something else?”

And the pressure builds quietly.

Bad architecture doesn’t scream. It doesn’t send warning emails. It grows in the background.

It spreads through the system like rot.

Every service is tightly coupled. Every module is dependent on another. Every boundary unclear.

“If you think good architecture is expensive, try bad architecture.”
— Brian Foote & Joseph Yoder

So You Decide to Fix It

You’ve had enough. You start redesigning. You decouple the modules. You clean up the boundaries. You refactor the mess left behind by someone else.

And then everything breaks.

Regression bugs everywhere. Features that worked yesterday are failing today. QA is overwhelmed. Stakeholders are asking what happened. Your manager wants answers.

And suddenly, you’re the problem. The person who tried to improve the system is now the one everyone blames for breaking it.

What Went Wrong?

It wasn’t the refactoring. It was what you didn’t have before you started.

Half your unit tests broke — not because the behavior changed, but because they were coupled to the old structure. The other half still passed, but it didn’t matter. Bugs were slipping through anyway, in the gaps between units that no test ever covered.

Your unit tests couldn’t tell you whether the system still worked. They were never designed to. Because unit tests only tell you if individual units of behavior work. They do NOT tell you if the system as a whole works.

Now QA has to catch everything. You push a change, they find a bug, you fix it, they test again—a loop that never ends. It’s slow, it’s expensive, it’s frustrating… and code still ships with bugs.

Your System’s Real Safety Net

This is exactly where acceptance tests change the game.

Acceptance tests don’t care about internal structure. They test what the system does from the outside — the behavior your users and stakeholders actually depend on.

• Redesign your modules? Acceptance tests should still pass.

• Split a monolith into microservices? Acceptance tests should still pass.

• Switch from SQL to NoSQL? Acceptance tests should still pass.

In any System Redesign, Acceptance Tests should still pass, because we expect the system's black-box behavior NOT to change.

They’re the one safety net that survives architectural change.

The Right Sequence

Bad architecture and missing acceptance tests are an invisible tax. And the people paying for it are the ones writing, testing, and maintaining the code every day.

The fix isn’t to stop improving your architecture. It’s to change the order:

1. First, write acceptance tests around what the system does today. Lock in the behavior.

2. Then redesign the architecture, knowing that if something breaks, you’ll see it immediately — not three sprints later in production.

Acceptance tests first. Architecture second. That’s the sequence that actually works.

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 Tests Workshop on May 27–28 (4 hours).

Join the workshop →

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

Subscribe now

If you’ve ever written acceptance tests in plain-text Gherkin, you probably had the same thought I did:

“This looks clean… so why is it so painful to maintain?”

Gherkin was supposed to let product owners write specifications.

But in reality?

Almost never happens.

Developers write the .feature files.
Developers maintain them.
Developers debug them at runtime.

Most teams follow the usual setup: they write Gherkin scenarios in .feature files using Cucumber (Java), SpecFlow (.NET) or Cucumber.js (TypeScript).

At first glance, it looks great:

English sentences.
Given / When / Then.

But…

⚠️The Hidden Cost of Textual Gherkin

Scenario files look readable, but become a maintenance burden:

Scenario: Calculate base price as product of unit price and quantity
  Given a product with unit price $20.00
  When an order is placed for that product with quantity 5
  Then the order placement should succeed
  And the order base price should be $100.00

Duplication everywhere

That sentence in the .feature file?

You repeat it again in step definitions (“glue code“).

Change one word?
Now you change it in multiple places:

• Change it in the step definition

• Change it in all affected test scenarios

Typos = runtime failure

Misspell a word?

You won’t know until you run the test.

The compiler doesn’t help you.

Your IDE doesn’t help you.

You only find out after everything compiles… and then fails.

You’re on your own.

No auto-complete.
No “what comes next?”
No guardrails.

You have to remember exact sentences.

And nothing prevents you from:

• Writing two When steps

• Writing steps that don’t exist

• Mixing domain concepts accidentally

It’s fragile by design.

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

I’m running a live workshop where we build acceptance tests that are compile-time safe, IDE-guided, and refactor-proof — no .feature files, no glue code.

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 English sentences and matching them with strings…

Read more

Subscribe now

When people try Clean Architecture… they often end up with bloated application layers and empty domain layers.

Application Layer:
   - Validate input
   - Load entities
   - Perform business logic
   - Call repositories
   - Call gateways
   - Publish events

Domain Layer:
   - Entity with getters and setters

That’s an anemic domain, not a rich domain.

The domain doesn’t actually do anything. All the rules are in the application layer.

In Clean Architecture, we’re supposed to have a rich domain, which fits in with DDD.

❌Empty Domain

If you’re used to CRUD, you probably see entities as simple data structures with public getters and setters.

class Order {
    private int id;
    private List<Item> items;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public List<Item> getItems() {
        return items;
    }

    public void setItems(List<Item> items) {
        this.items = items;
    }
}

class Item {
    private String sku;
    private int quantity;
    private boolean expired;

    public String getSku() {
        return sku;
    }

    public void setSku(String sku) {
        this.sku = sku;
    }

    public int getQuantity() {
        return quantity;
    }

    public void setQuantity(int quantity) {
        this.quantity = quantity;
    }

    public boolean isExpired() {
        return expired;
    }

    public void setExpired(boolean expired) {
        this.expired = expired;
    }
}

Looks fine… but the business rules live elsewhere (application layer).

Your application service does this:

public void addItemToOrder(Order order, Item item) {
    if (item.isExpired()) {
        throw new ExpiredException();
    }

    List<Item> items = order.getItems();
    if (items == null) {
        items = new ArrayList<>();
    }

    if (items.size() > 10) {
        throw new LimitExceededException();
    }

    items.add(item);
    order.setItems(items);
    orderRepository.save(order);
}

All the rules (expiration check, limit check) live in the application layer.

The entity is just a data container.

Basically, you’ve moved all the complexity into a layer that’s supposed to orchestrate, not decide.

❌Bloated Application Layer

Read more

Subscribe now

Most devs start coding with only a hazy idea of what “done” really means.

• You assume requirements are clear.

• You assume you understand the edge cases.

• You assume QA will catch any gaps.

TDD forces you to confront assumptions before you touch the code.

It’s not about writing more tests.
It’s about clarity, assurance, and focus.

When you know you can test a requirement, you know exactly what success looks like.

And that changes everything — from how you design your interface to how you structure your implementation to how fast you can deliver working software.

⚡Can You Even Test the Requirement?

Before you write code, TDD forces you to ask:

Can I write a test for this requirement?

If you can’t, something’s wrong.

Maybe:

• The requirement is vague.

• There’s no concrete example.

• Nobody knows what “done” really means.

And here’s the uncomfortable truth:

If you can’t construct an example to verify the requirement…
… you’re about to implement something blind.

You might push code that looks correct.
It might even pass code reviews.
And yet… it may fail silently in production.

TDD flips the script.

The first checkpoint isn’t your implementation.
It’s the requirement itself.

No test? No implementation.

That simple rule prevents hours (or days) of wasted effort, wasted code, and wasted frustration.

⚡TDD & ATDD

TDD is amazing at keeping your code correct, but it mostly protects your implementation.

ATDD (Acceptance Test–Driven Development) takes it one step further.

Instead of just asking:

“Can I write a test that proves my code works?”

ATDD asks:

“Can I write a test that proves the system behaves as the user expects?”

It shifts the focus from “my code works” to “the system works for everyone.”

• Requirements become executable specifications.

• Developers, QA, and Product Owners are all aligned on what “done” really means.

• Regression bugs drop, because everyone agrees on the expected behavior before a single line of code is written.

Think of it this way:

• TDD protects the code.

• ATDD protects the behavior.

If you’re working on legacy systems or teams where QA keeps reporting regression bugs, ATDD can transform the process — turning vague requirements and tribal knowledge into tests that everyone trusts.

⚡Release Without the Stress

You know something is wrong with how testing is done.

This workshop is for engineers who refuse to accept that “this is just how it is.”

Date & Time: Wed Feb 25, 5-7PM (CET)
Where: Live online
Cost: €97 — (100% off for Optivem Journal paid members)

📌Spots are limited – Sign up here: Acceptance Testing (Live Training)

Reserve Your Spot

🎁 Free for Paid Members - Claim your 100% discount
Not a member yet? Upgrade now for immediate access and replays

🔒 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

Many years ago, I used to think every test had to touch everything — the database, other services, payment providers… you name it.

Then I realized: that’s inefficient, feedback loop is too slow. We need tests at different levels.

A user adds a product to their cart, maybe ten times while browsing, and then finally hits checkout, then later cancels their order.

That’s two very different use cases: AddItemToCart and PlaceOrder. And each requires different tests.

The problem: Use Cases and the External World

Most real-world use cases depend on something external:

• Databases

• Message brokers

• External API services

For example, the PlaceOrder use case involves the DB (we need to save orders), it involves message brokers (we publish an event, so that the reporting service can register the newly placed order), and it involves external API services (we need to use PayPal for processing payment for the placed order).

The problem with testing use cases in this way, involving the external world are the following:

• The test is too slow due to the I/O

• We might not be able to test various logic scenarios

• The test might not be able to run if the external system is not available

The solution: Isolation from the External World

In order to be able to test our use case in isolation from the external world:

• User-side api: We test the use case via its driving (incoming) port, so that we bypass UI / REST API

• Server-side api: We “mock out” the driven (outgoing) ports, so that we’re excluding DB, external APIs, etc. In this way, the use case depends on interfaces of the external world, and doesn’t know (or care) about concrete implementations

This keeps your core logic isolated and maintainable.

Server-side API: Enter Test Doubles

When we write unit tests, those server-side ports are replaced with in-memory test doubles:

• Repositories Test Doubles (e.g. Order Repository Test Double)

• Gateway Test Doubles (e.g. Notification Test Double, Payment Test Double)

There are different types of Test Doubles: Dummies, Fakes, Stubs, Spies, Mocks (see Fowler’s Test Double article)

The test doubles:

• Live entirely in memory

• Run ultra fast

• Behave predictably

Basically, they let your tests focus on business logic, not “what the database or external API does today.”

Note: The above image is for a microservice, but a similar image can be applied to the frontend. Also, in case of monolithic architecture, similar image can be applied to the monolith.

AddItemToCart vs PlaceOrder (Real-life Example)

Read more

Subscribe now

You just finished a User Story.
Tested it locally. It worked.
You pushed it. Felt good.

And then…
QA comes back with a long list of regression bugs.

Again.

Your first reaction?

“How is this even related to what I changed?”

Your second reaction?

“Did QA even test this properly?”

And your third (the quiet one)?

“Am I actually bad at my job?”

You implemented exactly what the story asked for.
You didn’t refactor half the system.
You didn’t touch those areas.

“But it worked on my machine.”

You change one thing…
and accidentally affect five others.

Not because you’re reckless —
but because the system doesn’t tell you what behavior you’re about to break.

Manual QA discovers these issues after the fact.

The problem is that expected behavior lives only in people’s heads.
Or worse:

• In outdated tickets

• In vague acceptance criteria

• In tribal knowledge

• In “that one person who knows the system”

Nothing is executable.
Nothing runs automatically.
Nothing protects you before QA gets involved.

So regression bugs slip in — silently.

What Acceptance Tests change

Acceptance Tests move expectations out of conversations and into code.

They answer questions like:

• “What must never break?”

• “What behaviors define ‘working’?”

• “What does the business actually rely on?”

And they answer them before QA ever sees the build.

When you have Acceptance Tests in your pipeline:

• You catch regression bugs immediately

• QA spends less time reporting obvious breakages

• Developers stop being surprised

• Confidence comes back

Legacy Code is where bugs thrive

You expect things to break.
You’re afraid to touch anything.
Every change feels risky.

If you’ve ever thought:

• “QA is blocking us”

• “Regression bugs keep killing our velocity”

• “Every release feels risky”

• “We test, but it’s never enough”

That’s exactly where Acceptance Tests help most.

Want to see how this works in practice?

👉 Join me for a 2-hour live training on Acceptance Testing

I’ll walk you through:

• How to stop regression bugs before QA finds them

• How to write maintainable, behavior-driven acceptance tests

• How to do this safely — even in legacy code

• How to reduce friction between devs and QA

No theory-heavy fluff.
No “rewrite everything”.
Just a practical roadmap you can apply immediately.

📌Spots are limited – Sign up here: Acceptance Testing (Live Training)

Reserve Your Spot

🎁 Free for Paid Members - Claim your 100% discount
Not a member yet? 👉 Upgrade now for immediate access and replays

🔒 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 used to love code reviews. Going through a merge request line by line, questioning naming, debating implementation choices, which design patterns to use, etc....

Fast forward to today. AI is everywhere. Developers use AI to write code, refactor code, write tests. Before, it used to take hours/days, now it’s reduced to minutes.

The problem? Just because AI is fast doesn’t mean the code is good. Or even maintainable. How much should humans actually review?

Code Review in the age of AI

A developer recently told me he’s stopped reviewing code the way he used to.

He doesn’t read every line anymore. Instead, he checks:

• Is the code readable?

• Can a human actually understand what’s going on?

If the answer is no, the developer should explain or improve it. That’s it.

Human Review was already shrinking before AI

Even before AI, human review was already shrinking.

Linters in the pipeline would do formatting checks. SonarQube would do clean code checks — cyclomatic complexity, duplication, smells. A lot of issues that reviewers used to flag was already handled automatically.

So the shift didn’t start with AI.
AI just took it one level further.

Before AI, SonarLint would flag code with:

• Code smells

• Complexity

• Duplication

Developers fixed those issues locally.

Once the code reached the Pipeline, Linters & SonarQube ran the checks again, and developers fixed any remaining problems before merging.

8 Steps to Smarter Human–AI Code Reviews

Read more