Subscribe now

Before we automate any use case with acceptance tests, we need two things:

1. Minimal Pipeline: gets the system onto the acceptance environment the same way every time. Acceptance tests run against the deployed system, so when one fails, we need to know the feature broke, not the deploy.

• 1.1 Dockerfiles

• 1.2 Docker Compose

• 1.3 Smoke Tests

• 1.4 Commit Stage

• 1.5 Acceptance Stage

• 1.6 Release Stages

2. Use Case Diagram: the actors, the use cases and the external systems. Every acceptance test covers one use case, so the diagram shows us what there is to test and which use case to start with.

• 2.1 Ask the Product Owner

• 2.2 Generate the Use Case Diagram

• 2.3 Review with the Product Owner

Where relevant, we give you the AI prompt for each step.

This is Phase 0 of the series Acceptance Testing in Legacy Code with AI.

In the next article, we pick the core use case and write its use case narrative and business rules.

1. Minimal Pipeline

The pipeline has four stages. Every stage after the commit stage has its own environment.

• Commit stage: one for each deployable component, such as the backend and the frontend. Compile the code, build the Docker images, publish them to the Docker registry.

• Acceptance stage: deploy to the acceptance environment, run the smoke tests.

• QA stage: deploy to the QA environment, run the smoke tests.

• Production stage: deploy to the production environment, run the smoke tests.

Unit tests, component tests and static code analysis go in the commit stage too. Acceptance testing doesn’t need them, so we leave them out of this series.

Notice what’s missing from the acceptance stage: acceptance tests. They don’t exist yet. We build them later in the series.

The acceptance, QA and production stages all do the same two things: deploy the system, then run the smoke tests. So we write those two steps once and reuse them in all three.

Why go all the way to production? If you deploy to acceptance one way and to production another, a release can work on acceptance and still break in production. If all three stages deploy the same way, every deploy to acceptance is practice for production.

1.1 Dockerfiles

No Dockerfiles yet? Write them first. They also tell you whether anyone can still build the system from a clean checkout.

AI prompt: Write a Dockerfile for each deployable component:

• one for the backend,

• one for the frontend.

Find out how each is built and started today from the build scripts, the deployment scripts and the README. Build each from a clean checkout, using nothing from a developer’s machine. Don’t change the system’s code.

Docker is the most common choice, and we recommend it wherever the system can run in a container. But it’s optional. If the system can’t run in a container, deploy it to a real server with the scripts you already have. You lose one thing: running the same setup on your machine and in the pipeline. You keep the most important one: every environment is deployed the same way. Without Docker, swap the Docker images for your build artifacts (such as JAR files or zip packages) and the Docker registry for your artifact repository. Run the system on your machine the way you do today; the steps stay the same.

1.2 Docker Compose

Write a Compose file to run the system on your machine. You use it to run the smoke tests locally before they go into the pipeline:

AI prompt: Write docker-compose.yml in the repository root:

• Build the backend and the frontend from their Dockerfiles and start them.

• Start everything they need to start, such as the database and the login server.

• Point each external system to its test instance.

• Find every setting the system reads at startup in the deployment scripts and the README, and set each one in the compose file.

Don’t change the system’s code, with one exception: if an external system’s URL is hard-coded, move it into the system’s configuration.

One rule: external system URLs must be settings, not hard-coded. It’s the only change we make to the system’s code.

Example of the generated file, trimmed to the backend and the frontend:

services:
  backend:
    build: ./backend
    ports:
      - "8080:8080"
    environment:
      - ERP_API_URL=https://test.erp.com
      - TAX_API_URL=https://test.tax.com
      - CLOCK_API_URL=https://test.clock.com
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"

Why build the images locally instead of pulling them from the Docker registry? The registry is still empty: the commit stages that publish the images come later. And on your machine, you want to run the code you just changed.

Why make external system URLs configurable? Later in the series we replace the external systems with stubs, and that only works if the URL is a setting.

Read more

One of the biggest challenges with practicing ATDD is the existing legacy code base, which basically has no tests. You write acceptance tests for the new user story, you see them red, then green. But you could have very easily broken something that already worked.

Automating the whole system used to take years and years. So it wasn’t feasible to automate the whole system. Rather, we did it incrementally: for each user story, we first did legacy coverage.

But here’s the thing. When AI came in, I changed my approach. Hey, it doesn’t have to take years. It can now take months, or even weeks. I think it’s the first time in history ever that we can do possibly full system coverage of a legacy system.

So why does it matter that we cover the whole system?

• No more manual regression testing. The manual test procedures that run before every release are covered by acceptance tests in the pipeline.

• You can modernize safely. Move to a modern tech stack, or restructure the architecture, for example from a monolith to microservices. The acceptance tests talk to the system only through its API and UI, so they keep checking the behaviour while you replace what’s behind them.

• You can trust what AI changes. AI writes code faster than anyone can review it by hand, and the acceptance tests tell you what a change broke.

The new approach

Phase 0: the pipeline and the use case diagram

We need a pipeline with the commit stage, the acceptance stage and the release stage, so from day one we see the tests passing in the acceptance stage.

Then the use case diagram, including which use cases depend on each other. The AI writes it from the source code, the docs and the running system. We pick the most important use case.

Phase 1: the pilot

We start with the most important use case and the ones it depends on, in that order. For example, Place Order with a coupon needs a published coupon, so Publish Coupon goes first.

1. Use case narrative. The main scenario and the alternative scenarios. We review it with the domain experts.

2. Acceptance criteria. The use case scenarios, written as concrete examples with real values.

3. Acceptance tests, passing. Against the existing system, without changing it. Once the tests for the most important use case pass in the acceptance stage of the pipeline, we demo it to your team.

Phase 2: scaling

The pilot is where you learn the lessons if something goes wrong with AI. After the go-ahead, we repeat the same three steps for all the other use cases, one at a time, in the order they depend on each other.

To get that order, we use AI to build a dependency tree of the use cases. The tree sets the sequence: a use case only comes after the use cases it depends on.

This series is a work in progress. This list itself may be updated as I go through the writing of the series. The focus is primarily technical, but where I see it’s relevant, I might also include how to get buy-in from your team.

Where you end up

In a few weeks or a few months, instead of three to five years, you actually have protection. Then your team can keep working test-last, or move on to ATDD.

Ask me in the comments as you try to apply this in your real life project.

The discount

There’s a discount for the next 7 days: 20% off an annual subscription, until Tuesday, November 17.

Get 20% off

This series is practical so you can apply it at work - you get AI prompts and code examples. You can ask me questions as you try to apply it at your job. This series is designed for busy software engineers who want to get results fast.

Using your training budget

You can expense it to your team’s training budget.

Here’s a sample email you can send your manager. Feel free to adapt it:

Hi [manager name],

We’re using AI to code faster, but every release still waits for manual regression testing. We need to solve that problem.

Optivem Journal has a new series on using AI to cover a legacy system with automated acceptance tests in weeks or months, not years. The tests run in the pipeline, so we can stop testing every release by hand. It includes the AI prompts and code examples, so I can try it on our real system at work. Paid subscribers can also ask questions and get support when they get stuck.

I’d like to expense an annual subscription from our training budget. It’s 20% off until Tuesday, November 17: https://journal.optivem.com/26d7c410

Thanks,
[your name]

P.S. If it’s useful for the whole team, there’s also a group subscription, so we could all go through the series together.

You can get an invoice for your company from Substack (see how). To subscribe your whole team, click “Other payment options” when subscribing and choose “Group Subscription” (at least four people).

Most systems are legacy: years in production, no acceptance tests, and nobody can say exactly how they behave. Before every release, someone works through the manual test procedures by hand, and the list grows with every release.

Writing acceptance tests for the whole system by hand would take months, so it never starts. But the behaviour already exists: in the running system, the source code, the manual test procedures and the domain experts’ heads. AI can write it down, and the running system checks what the AI wrote.

The steps:

Phase 1. Prove it on the core use case

• Step 1.1. Generate the use case diagram.

• Step 1.2. Generate the use case narrative for the core use case.

• Step 1.3. Generate the acceptance criteria for the core use case.

• Step 1.4. Set up the acceptance test architecture, with the acceptance tests for the core use case.

• Step 1.5. Ensure that the acceptance tests pass against the existing system.

Phase 2. Scale to the other use cases

• Step 2.1. Generate the use case narratives for the other use cases.

• Step 2.2. Generate the acceptance criteria for the other use cases.

• Step 2.3. Generate the acceptance tests for the other use cases.

• Step 2.4. Ensure that the acceptance tests pass against the existing system.

• Step 2.5. Delete the acceptance criteria.

Take one use case all the way through before doing the rest. Each step comes with its prompt. The examples come from an online shop.

Read more

Book a call

A prompt might contain precise instructions but make a false assumption.

It might ask for a solution before the problem is understood.

Or it might push the AI to agree with what you already believe.

Models tend to do this anyway. Researchers call it sycophancy: the model leans towards the answer it thinks you want.

The result can be an answer that sounds convincing, looks professional, and solves the wrong problem.

1. Don’t use vague quality words when you can name the criteria

❌ Asking for “rigor” without saying what rigor means

“Act as a senior software architect and give me a rigorous review of this design.”

What’s wrong?

Words like senior, rigorous, and high-quality sound useful, but they don’t say what the AI should examine or how it should back up its conclusions.

A response can sound authoritative without naming a single problem you can act on.

A role can set a perspective, but it doesn’t replace a clear task. (Asking the model to reason step by step before answering is different — that does change how it works on the problem. “Be rigorous” doesn’t.)

Read more

Book a call

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal.

Subscribe now

We often hear that getting better results from AI is a matter of writing better prompts.

Be more specific. Give the AI a role. Add context. Explain what you want.

All of that can help. But: a prompt can be detailed, well-written, and still lead you in the wrong direction.

1. Don’t ask AI to confirm your decision. Ask it to evaluate it.

❌ Treating the decision as already made

“We’ve decided to move to microservices. Outline how to split our application into services.”

What’s wrong?

The decision is presented as settled, so the AI works on the next step. It will produce a sensible-looking list of services. It won’t usually stop to ask whether you need microservices at all.

Ask a model directly “Are microservices better than a monolith?” and it will usually say “it depends”. The risk is the prompt where the decision is built in and never questioned.

Read more

Book a call

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal.

Subscribe now

AI writes code fast. Many teams then ask AI to write the tests for that code too.

That’s the problem. The tests check the code against itself. They don’t check it against what the business asked for.

It’s like a student marking their own exam. The answers always match, so they always pass. A test that can’t fail tells you nothing.

❌ Write test after code

The test comes from the code, not from the spec.

1. AI Reads Spec

AI reads the spec:

A customer gets the 10% promotion and their 20% coupon.

There are (at least) two ways to interpret the spec:

• Interpretation A: 10% off first, then 20% off what is left.

• Interpretation B: 10% + 20% = 30% off.

2. AI Writes Code

AI picks interpretation A: 10% off first, then 20% off the reduced price.

var promotedPrice = basePrice.multiply(promotionFactor);
var discountAmount = promotedPrice.multiply(discountRate);
var totalPrice = promotedPrice.subtract(discountAmount);

Note: AI is non-deterministic, so we can’t know which interpretation it will choose. In one run it may only think of interpretation A. In another run it may only think of B. In another it may see both and ask us to choose. And in another it may come up with an interpretation C that we hadn’t even thought of.

3. AI Writes Acceptance Test

AI reads its own code, then writes a test that mirrors the behavior of that code. It makes up inputs and answers that fit the code:

@TestTemplate
@Channel({ChannelType.UI, ChannelType.API})
void shouldApplyCouponOnPromotedPrice() {
    scenario
            .given().product().withUnitPrice(”100.00”)
                .and().promotion().isActive().withDiscount(”10%”)
                .and().coupon().withDiscountRate(”20%”)
            .when().placeOrder()
            .then().shouldSucceed()
                .and().order().hasTotalPrice(72.00);
}

4. Verify Acceptance Test Passes

The acceptance test is executed. It passes, because it was made to match the code, so the build is green.

5. Human discovers misinterpretation

The build is green, so the work goes to QA. QA reads the spec their own way. They expect $70.00 and see $72.00, so they report a bug. The bug goes to the product owner.

Only now does anyone ask the question that should have been asked first. The product owner says 30% off.

6. AI reworks code & test

The code is wrong, and the test is wrong too, because it was made to match the code. Both the code and the test must be reworked.

It was circular: the code decided the test, and then the test “proved” the code. That makes it tautological: true by construction, so it can never fail.

✅ Write test before code

Read more

Register now

👋 Hello, this is Valentina with the free edition of the Optivem Journal.

Subscribe now

Markdown spec = enforced spec? WRONG.

Markdown = Spec. Acceptance Test = Executable Spec.

❌ Spec -> AI writes code -> Human manually tests

✅ Executable Spec -> AI writes code -> Automatic spec verification

99% of developers follow Spec-Driven Development (SDD) the WRONG way.

1. They write the spec in Markdown.
2. They tell AI to implement code based on spec.

But what's the problem here? Sure, AI reads the markdown file, but doesn't follow it fully! It may decide to skip instructions, or misinterpret instructions, etc.

So we can NOT trust AI!

We have to manually read the spec, manually run the system, and manually decide whether the functionality that the system implemented matches what was in the spec.

Interestingly, this is not a new problem. We've had this problem for ages, with human developers. Remember, we'd write a User Story, the developer thinks they followed it, but then QA says it doesn't work correctly - that there was something that the developer missed, or they had misinterpretations.

Well, that's exactly the same problem in Spec-Driven Development, how most people practice it.

The solution is: EXECUTABLE specs. With executable specs, we can be sure to enforce that AI actually implements the behavior that we specified. We have an automated way to check - a pass or fail. This means if AI skips instructions, or misinterprets something, we'll have a test telling us it failed. AI tries again, until the test passes. There's no way for AI to "cheat" the test.

That's the right way to do Spec-Driven Development. Convert textual specs to executable specs.

⚡Full walkthrough, with the code examples

📅 Register (free): Spec-Driven Development with ATDD & AI (Oct 14)

Register now

Register now

🔒 Hello, this is Valentina with a premium issue of the Optivem Journal.

Subscribe now

The Strategy pattern is usually introduced with a diagram:

Context
  └── Strategy
        ├── Strategy A
        ├── Strategy B
        └── Strategy C

Useful. But in a real application, the more important question is:

Where should those strategies live in Clean Architecture?

The problem

You’re placing an order, and the shipping cost depends on where it’s going.

public Money calculateShipping(Order order) {
    if (order.country().zone() == ShippingZone.DOMESTIC) {
        return Money.of(5);
    }

    return Money.of(15);
}

That works. Then the rules grow:

public Money calculateShipping(Order order) {
    var zone = order.country().zone();

    if (zone == ShippingZone.DOMESTIC) {
        return order.subtotal().isAtLeast(Money.of(50))
            ? Money.ZERO
            : Money.of(5);
    } else if (zone == ShippingZone.NORTH_AMERICA) {
        return Money.of(10).add(Money.of(1).multiply(order.itemCount()));
    } else if (zone == ShippingZone.INTERNATIONAL) {
        return Money.of(20)
            .add(Money.of(2).multiply(order.itemCount()))
            .add(Money.of(15));
    }

    throw new IllegalStateException(”Unknown zone: “ + zone);
}

Now the code that places the order knows every shipping rule in the system. Every new market means editing it. Every rate change means editing it.

Step 1: The domain defines the interface

Define what the business needs, not how it’s done:

public interface ShippingPolicy {
    Money calculate(Money subtotal, Quantity quantity);
}

This is something the business needs: “give me the shipping cost for an order of this value and size”. So the domain owns it.

Notice the name: ShippingPolicy, not ShippingStrategy. “Strategy” is the pattern’s name; “policy” is the business’s word for it. The interface is a Strategy, but you name it in the language of the domain.

Step 2: Each rule becomes a class

public final class DomesticShipping implements ShippingPolicy {

    private static final Money FREE_SHIPPING_THRESHOLD = Money.of(50);
    private static final Money FLAT_RATE = Money.of(5);

    @Override
    public Money calculate(Money subtotal, Quantity quantity) {
        if (subtotal.isAtLeast(FREE_SHIPPING_THRESHOLD)) {
            return Money.ZERO;
        }

        return FLAT_RATE;
    }
}

public final class NorthAmericaShipping implements ShippingPolicy {

    private static final Money BASE = Money.of(10);
    private static final Money PER_ITEM = Money.of(1);

    @Override
    public Money calculate(Money subtotal, Quantity quantity) {
        return BASE.add(PER_ITEM.multiply(quantity.value()));
    }
}

public final class InternationalShipping implements ShippingPolicy {

    private static final Money BASE = Money.of(20);
    private static final Money PER_ITEM = Money.of(2);
    private static final Money CUSTOMS_HANDLING = Money.of(15);

    @Override
    public Money calculate(Money subtotal, Quantity quantity) {
        return BASE
            .add(PER_ITEM.multiply(quantity.value()))
            .add(CUSTOMS_HANDLING);
    }
}

Each rule can change without touching the others or the use case.

Step 3: The domain selects the policy by shipping zone

Read more

Register now

👋 Hello, this is Valentina with the free edition of the Optivem Journal.

Subscribe now

Mike is a software developer.

He had been asking for better requirements for years.

Not because he loved writing documentation — because he was tired of building the wrong thing.

The product owner would create a one-line ticket. He was always busy and also hated writing)

Then, in backlog refinement:

“Everyone understands?”

Nod. Nod.

Next ticket.

And then off the developers go to implement it.

Mike gets the blame

QA started reporting so many bugs, so many scenarios that developers didn’t think of.

The product owner saw the feature and shook his head:

“This isn’t what we wanted. You’ve basically implemented the wrong thing”

Mike was frustrated. This kept happening.

He brought it up to management.

The answer?

“We can't spend half the sprint on requirements.”

“Just start coding.”

“You’re the developer. You should figure it out.”

Then AI arrived

Suddenly, specifications were a priority.

Now management was pushing Spec-Driven Development down on the whole team.

Mike’s reaction?

“Wait. NOW specifications are important?”

But there was another problem.

AI would skip parts of the requirements or misinterpret them.

Unlike a developer would at least try to follow the specification, not skip stuff.

AI gives Mike more work

Mike has to spend a lot of time like reviewing AI’s work, and management is now angry at him. They’re paying for all these AI tools, but delivery is still not fast enough.

He’s really frustrated, because now he has to do a lot of checking: did AI actually satisfy the specifications or not?

And he has to do it all manually, like manually testing things before handing it over to QA — and it’s just boring, tedious.

Mike takes back control

Then Mike discovered that if you do Spec-Driven Development with actually executable specifications, that problem pretty much disappears.

So instead of just giving a user story to AI, he’d have AI turn it into acceptance tests first. He’d confirm the acceptance tests before AI started coding.

And all of a sudden, he was back in control.

AI couldn’t just do whatever it wanted.

Want to stop manually checking AI’s work?

📅 Register (free): Spec-Driven Development with ATDD & AI (Oct 14)

Register now

Register for free

🔒 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

You’ve split your application into one class per use case.

Then you gave every use case the same interface — the Command Handler pattern:

public interface UseCase<TRequest, TResponse> {
    Result<TResponse, UseCaseError> execute(TRequest request);
}

One request in. One result out.

But you run into issues:

❗Problem #1: Cross-cutting concerns duplicated across use cases

Logging, transactions, authorization — many use cases need them, so you end up copying them into each one:

public final class PlaceOrder
        implements UseCase<PlaceOrderRequest, PlaceOrderResponse> {

    public Result<PlaceOrderResponse, UseCaseError> execute(
        PlaceOrderRequest request
    ) {
        log.info("PlaceOrder started");
        authorize(Permission.PLACE_ORDER);
        return transactional(() -> {
            // ... the actual use case logic
        });
    }
}

public final class CancelOrder
        implements UseCase<CancelOrderRequest, CancelOrderResponse> {

    public Result<CancelOrderResponse, UseCaseError> execute(
        CancelOrderRequest request
    ) {
        log.info("CancelOrder started");
        authorize(Permission.CANCEL_ORDER);
        return transactional(() -> {
            // ... the actual use case logic
        });
    }
}

The same lines repeat in many use cases, and every new use case has to remember them.

❗Problem #2 (secondary): Constructors with lots of injection

Every use case is its own class, so every controller needs each one it calls injected:

public OrderController(
    PlaceOrder placeOrder,
    ViewOrderDetails viewOrderDetails,
    CancelOrder cancelOrder,
    PublishCoupon publishCoupon,
    BrowseCoupons browseCoupons,
    // ... and more with every new use case
) { ... }

And each endpoint calls its own use case directly:

@PostMapping("/orders")
public ResponseEntity<?> placeOrder(@RequestBody PlaceOrderRequest request) {
    return mapResult(placeOrder.execute(request));
}

The constructor grows with every use case you add. The wiring becomes noise, and every controller test has to supply them all.

❌ Poor Solution: Base Classes

The tempting fix for Problem #1 is a BaseUseCase that every use case extends. But as it grows with logging, authorization, transactions, and error handling, every use case inherits all of it — whether it needs it or not.

And it does nothing for Problem #2: the controller still needs every use case injected.

✅ Effective Solution: Command Bus — in Practice

Read more

Subscribe now

Your team automated testing.

So why does every release still wait for QA?

Register for free

You invested in E2E test automation to get faster releases and fewer bugs.

Instead, what you got is a test suite that breaks with every UI change, a team that doesn’t trust it, and a manual regression pass that still sits between “done” and “released.”

Now AI is helping your developers write code faster, and the queue in front of QA is only getting longer.

This isn’t a people problem, and more automation of the same kind won’t fix it. It comes down to how the tests are designed.

What You’ll Learn

• Why E2E automation rarely replaces manual QA — and the three design decisions behind it

• What changes when tests are written in business language — your product owner can read them, QA can trust them, and UI changes stop breaking them

• How to start small — with one critical use case, without stopping delivery or rewriting everything

• How to get it funded — by presenting it to your CEO in terms of release speed, cost of bugs and time spent on repeat work

Who Should Join

This is for you if:

• You lead an engineering team (as engineering manager, head of engineering or CTO)

• Releases are slowed down by manual testing

• Your team tried test automation and it didn’t deliver what was promised

Event Details

📅 Date & Time: Wed, Oct 7, 2026 5:30PM
📍 Where: Live online
💰 Cost: Free

🔗 Register here: Why Your E2E Tests Didn’t Replace Manual QA

Meet Your Coach

Valentina Jemuović is a technical coach and the founder of Optivem. She coaches engineering teams in ATDD and TDD, helping them deliver software faster with fewer bugs. She works in Java, .NET and TypeScript, and shares her work with ~30K followers on LinkedIn.

Coding Got Faster — Releases Are Still Slow

If you want to eliminate manual regression testing and get faster delivery with fewer bugs…

📌 Register here: Why Your E2E Tests Didn’t Replace Manual QA

Register for free

Book a call

“Spec-driven development” is everywhere in AI tooling right now: Kiro, GitHub’s spec-kit, Tessl. Write the spec first, then let the agent build against it. Birgitta Böckeler reviewed all three in Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl on martinfowler.com and found the catch.

In every one of them, “spec” means a Markdown document the agent is supposed to read. Nothing checks that the code matches it, and the agents don’t always follow it. As she put it: “I frequently saw the agent ultimately not follow all the instructions.”

The problem isn’t the tools. It’s that the spec is a Markdown file, and you can’t run a Markdown file against the code. To find out whether the agent followed it, a person has to read the code line by line. That’s the work you hoped the spec would save.

We’ve had a spec without this problem since 1999. Kent Beck’s first Extreme Programming book, Extreme Programming Explained (1999), already had acceptance tests, and the XP rules on extremeprogramming.org spell out how they work: acceptance tests “are created from user stories” and “should be automated so they can be run often.”

In 2010, Jez Humble and Dave Farley’s Continuous Delivery gave automated acceptance tests their own chapter: “Acceptance tests are a crucial stage in the deployment pipeline: They take delivery teams beyond basic continuous integration. Once you have automated acceptance tests in place, you are testing the business acceptance criteria of your application, that is, validating that it provides users with valuable functionality.”

An acceptance test is the spec and the check in one: it describes what the system should do, and it fails until the system does it.

An agent can ignore a Markdown file.

It can’t ignore a test that won’t pass.

An acceptance test doesn’t call the system directly. It calls a DSL, and the DSL calls two kinds of drivers. System drivers talk to the system through its UI or API. External-system drivers talk to the external systems it depends on, such as an ERP.

In acceptance test-driven development (ATDD), the Red step is where you write that test, before any system code exists. When an AI agent does the work, the Red step is split into four small steps, and a human reviews each one.

In every box, the AI writes the code, a human reviews it, and then it’s committed.

Before Red: the acceptance criteria

Example: placing an order in an online shop.

It starts with a ticket. Its acceptance criteria are agreed before any code is written:

Scenario: Calculate the base price from unit price and quantity
  Given a product with unit price 20.00
  When I place an order for 5 of that product
  Then the order is placed successfully
  And the order’s base price is 100.00

Inside the Red step

1. Write Acceptance Tests

The agent turns the acceptance criteria into a test. The test is written in a DSL, the test code’s own vocabulary (placeOrder().withQuantity(...)). Here’s the acceptance test, from PlaceOrderPositiveTest.java:

@TestTemplate
@Channel({ChannelType.UI, ChannelType.API})
void shouldCalculateBasePriceAsProductOfUnitPriceAndQuantity() {
    scenario
            .given().product()
                .withUnitPrice(20.00)
            .when().placeOrder()
                .withQuantity(5)
            .then().shouldSucceed()
            .and().order()
                .hasBasePrice(100.00);
}

Read more

Let's talk

📅 Join our next live course: ATDD, Clean Architecture, Pipelines
Early bird: €100 off with code EARLYBIRD100

🔒 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

Your SubscriptionService has 800 lines.

It activates subscriptions, handles cancellations, validates plan changes, checks expiration...

Meanwhile Subscription is just getters and setters.

That’s the problem.

❌Your Domain Is Just Data (Anemic Domain)

public class Subscription {
    private String customerId;
    private SubscriptionPlan plan;
    private SubscriptionStatus status;
    private LocalDate startedAt;
    private LocalDate expiresAt;
    private BigDecimal price;

    public String getCustomerId() {
        return customerId;
    }

    public void setCustomerId(String customerId) {
        this.customerId = customerId;
    }

    public SubscriptionPlan getPlan() { ... }

    public void setPlan(SubscriptionPlan plan) { ... }

    public SubscriptionStatus getStatus() { ... }

    public void setStatus(SubscriptionStatus status) { ... }

    public LocalDate getStartedAt() { ... }

    public void setStartedAt(LocalDate startedAt) { ... }

    public LocalDate getExpiresAt() { ... }

    public void setExpiresAt(LocalDate expiresAt) { ... }

    public BigDecimal getPrice() { ... }

    public void setPrice(BigDecimal price) { ... }
}

There isn’t much here.

The Subscription holds data.

The business rules live somewhere else:

public class SubscriptionService {

    public void cancel(Subscription subscription) {
        if (subscription.getStartedAt().plusDays(7).isBefore(LocalDate.now())) {
            throw new IllegalStateException(
                "Free cancellation is only available during the 7-day trial"
            );
        }

        subscription.setStatus(SubscriptionStatus.CANCELLED);
    }

    public void changePlan(
        Subscription subscription,
        SubscriptionPlan newPlan
    ) {
        if (newPlan == subscription.getPlan()) {
            throw new IllegalArgumentException(
                "Subscription is already on this plan"
            );
        }

        subscription.setPlan(newPlan);
        subscription.setPrice(newPlan.getPrice());
    }

    public void renew(Subscription subscription) {
        if (subscription.getStatus() != SubscriptionStatus.ACTIVE) {
            throw new IllegalStateException(
                "Only active subscriptions can be renewed"
            );
        }

        subscription.setExpiresAt(
            subscription.getExpiresAt().plusMonths(1)
        );
    }
}

At first, this doesn’t look terrible.

But keep adding business rules.

Soon you have:

SubscriptionService
├── startTrial()
├── cancel()
├── changePlan()
├── renew()
├── pause()
├── resume()
├── extendTrial()
├── changeBillingCycle()
├── updatePaymentMethod()
└── ...

And your Subscription is still just data.

That’s where the real problems appear:

• Rules get scattered across services

• The same rules get duplicated in different places

• Rules can be bypassed by calling setters directly

• Changing a business rule means hunting through services to find everywhere it is implemented

• The Subscription object can’t protect its own state

✅Your Domain Owns the Rules (Rich Domain)

Read more

Let's talk

👋 Hello, this is Valentina with the free edition of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

When there are hundreds of things to check, QA can't check everything.

“That feature hasn’t changed.”

“Let’s just test the critical flows.”

Some tests get skipped.

That’s when production bugs slip through.

❌ “Just hire more QA”

But every release adds more features.

More features = more things to regression test.

QA can’t keep up.

❌ “But we already automated!”

You tried e2e tests.

Run it → red.

Run it again → green.

Eventually, nobody trusts the tests.

Developers start ignoring them.

You tried unit tests.

They're green.

But something still breaks in production.

Why?

Does Checkout Work?

Checkout has these requirements:

• Customer can add a product to the cart.

• Customer can pay by card.

• Order is created after payment.

• Customer can’t order an out-of-stock product.

⚠️Unit tests

Test individual pieces, but not the whole flow.

CartService adds a product.

PaymentService charges the card.

OrderService creates the order.

They can all pass while the checkout flow still breaks.

⚠️E2E test

It tests the whole flow.

But the behaviour is buried inside UI steps.

Open checkout → add product → enter card → click Pay → see “Order confirmed”

So what is this test actually checking?

Can the customer pay by card?

Is an order created?

Is the cart emptied?

Does the confirmation page appear?

You have to read the steps and figure it out.

Now imagine 200 tests like that.

You can’t easily tell:

“Which test proves that an out-of-stock product can’t be ordered?”

“Do we have a test for refunds?”

“Do we test that an order is only created after successful payment?”

✅ Acceptance test

The behavior being checked is obvious.

Given a product is out of stock
When a customer tries to order it
Then the order is rejected

The requirement and the test are the same.

You can see exactly what behavior you’re checking.

And because the test isn't tied to the UI, changing the checkout screen doesn't mean rewriting the test.

ATDD in Legacy Code: catch regression bugs before production.
Hands-on work with your teams. Limited spaces for 2027.

Let's talk

Let's talk

📅 Join our next live course: ATDD, Clean Architecture, Pipelines
Early bird: €100 off with code EARLYBIRD100

🔒 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

You already know a fat service class is a bad place for all your business logic.

So you split it up.

One class per use case, like in Uncle Bob's example:

public class PlaceOrder {
    public PlaceOrderResponse placeOrder(PlaceOrderRequest request) { ... }
}

public class ViewOrderDetails {
    public ViewOrderDetailsResponse getOrder(String orderNumber) { ... }
}

public class CancelOrder {
    public void cancelOrder(String orderNumber) { ... }
}

public class PublishCoupon {
    public Coupon createCoupon(String couponCode, BigDecimal discountRate,
                                Instant validFrom, Instant validTo, Integer usageLimit) { ... }
}

public class BrowseCoupons {
    public List<Coupon> getAllCoupons() { ... }
}

Looks better.

But splitting the service into separate classes didn’t fix everything.

Here’s what’s still wrong:

❌ Entities leak across the boundary — but only sometimes

PublishCoupon returns a Coupon.

BrowseCoupons returns List<Coupon>.

But PlaceOrder and ViewOrderDetails return response DTOs.

So... can entities cross the use case boundary or not?

You can’t tell. It depends on which class you’re looking at.

❌ A bug is hiding in PublishCoupon

If you accidently swap validFrom and validTo — it still compiles, because they’re the same type.

But now your coupon has the wrong validity period — it’s backwards.

CouponController already has a PublishCouponRequest with all the values. Instead of passing that request to PublishCoupon, it pulls the values out and passes them one by one.

That's how you end up with a bug like this.

❌ Expected outcomes are thrown, not declared

Order not found, order can’t be delivered — are thrown as exceptions instead of declared.

These aren't bugs. They're things that can happen when the use case runs.

But they’re in a shared exception handler that has grown a case for every use case's failures.

The method says “I return an order.” It doesn't tell you that “order not found” or “order can't be delivered” can happen.

❌ Calling each use case is different

PlaceOrder takes a request object, ViewOrderDetails/CancelOrder take a raw String, PublishCoupon takes five loose parameters, BrowseCoupons takes nothing.

There’s no obvious answer to: “How do I call a use case?”

❌ The class says one thing, the method says another

ViewOrderDetails.getOrder()

The class says “view the order details”, but the method says “get the order.”

Same problem here: PublishCoupon.createCoupon()

The class says “publish a coupon”, but the method says “create a coupon”.

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

You open a PR labelled:

“API redesign — no behavior change”

Looks fine.

Merged.

The one-line acceptance test change goes unnoticed.

Six months later, a regression bug slips through.

The acceptance test that was supposed to catch it didn’t.

Why?

Because the test was quietly changed at the same time as the code.

That’s the problem.

If the behavior didn't change, the acceptance test shouldn't need to change.

The driver should handle it.

✅The test stays the same — the driver changes

Look at PlaceOrderPositiveTest.java in the shop’s system-test module:

@TestTemplate
@Channel({ChannelType.UI, ChannelType.API})
void shouldCalculateBasePriceAsProductOfUnitPriceAndQuantity() {
    scenario
            .given().product()
                .withUnitPrice(20.00)
            .when().placeOrder()
                .withQuantity(5)
            .then().shouldSucceed()
            .and().order()
                .hasBasePrice(100.00);
}

This test has no idea whether the order is placed by POST /api/orders or POST /api/purchases.

It has no idea whether the UI’s place-order button is selected by [aria-label="Place Order"] or by some new CSS class.

It also has no idea whether the ERP returns the product’s price as price or unitPrice.

Read more

Let's talk

📅 Join our next live courses: ATDD, Clean Architecture, Pipelines
Early bird: €100 off with code EARLYBIRD100

👋 Hello, this is Valentina with the free edition of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

“AI can write the tests.”

Finally.

All those tests nobody has time to write.

No more days spent waiting for manual QA before every release.

Six months later…

More code.

More PRS.

But releases aren’t faster.

QA is still testing everything manually before anything ships — exactly as they were last year.

And the bugs? Still there.

Now management wants to know:

What did we actually get for the money?

You have plenty of numbers to show them.

More code.
More PRs.
More tests.

But none of those numbers answer the question.

Because more code isn't the same as safer releases.

AI copies whatever it finds

Ask AI to write a test.

But what if your e2e suite is full of tests coupled to the UI?

Click the button.
Fill the field.
Check the screen.

AI just writes hundreds more tests like that.

Faster.

It doesn't stop and ask:

“Is this a good way to test this application?”

It looks at the tests you already have and learns:

“This is how tests are written here.”

You had a speed limit

Before AI, writing tests was slow.

That was annoying.

But it also limited how many bad tests you could create.

Your team could only write so many brittle E2E tests before the sprint ended.

AI removed that limit.

Now you can write hundreds in the time it used to take to write a few.

But the tests aren’t any better.

They’re still coupled to the UI.

Still break when the UI changes.

Still create more work for the team.

Before AI writes 100 more tests

AI writing tests isn’t the problem.

AI writing bad tests faster is.

The problem is giving it a bad test suite to learn from.

❌ If your tests are all coupled to the UI, AI will keep generating tests like:

click("Place Order")

✅ Instead, fix the test, so that it's coupled to the domain rather than the UI:

shop.placeOrder()

Now AI can do what it’s good at:

Write hundreds more. Fast.

⚡Join our next live courses

• ATDD: Stop Shipping Bugs

• Clean Architecture: In Practice

• Pipelines: Stop Release Nightmares

Early bird: €100 off with code EARLYBIRD100

ATDD in Legacy Code: catch regression bugs before production — in banking, insurance, and healthcare systems.
Hands-on work with your teams. Limited spaces for 2027.

Let's talk

Let’s talk →

🔒 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

“What should I do when a use case fails?”

But a use case can fail for completely different reasons.

Maybe:

• the customer doesn’t exist

• the order hasn’t been paid for

• the order cannot be checked out

• the payment provider is unavailable

Should the use case handle all of them?

Error Handling at the Application layer

This layer contains your use cases:

• checkout order

• refund payment

• create shipment

• reserve seat

This is where application rules are enforced.

Examples:

• cannot checkout if another checkout is already in progress

• cannot place an order for a customer that doesn’t exist

• cannot apply the same coupon twice

These are rules that the use case needs to check because because the information isn't inside the Order itself.

E.g. an Order can’t know whether the customer exists or another checkout is already in progress, or whether a coupon had already been used. The use case can check that information.

These are not technical failures. A database connection dropping is a completely different kind of problem.

❌ Use cases should NOT handle infrastructure exceptions

public void checkout(Order order) {

    try {
        paymentGateway.charge(order);
        orderRepository.save(order);
        shippingGateway.notifyWarehouse(order);

    } catch (StripeException e) {
        throw new RuntimeException("Payment failed");
    } catch (SQLException e) {
        throw new RuntimeException("Database error");
    } catch (HttpException e) {
        throw new RuntimeException("Warehouse call failed");
    }
}

Now the use case is tied to three unrelated technologies:

• StripeException — Stripe’s SDK

• SQLException — JDBC / the database

• HttpException — the HTTP client

Swap Stripe for PayPal, JDBC for an ORM, or the HTTP client for a message queue, and you now have to change the use case too.

But the checkout rules haven’t changed.

That’s the problem.

✅ Use cases should ONLY handle application errors

Read more

👋 Hello, this is Valentina with the free edition of the Optivem Journal. I help Engineering Leaders & Senior Software Developers apply TDD in Legacy Code.

Subscribe now

Someone can spend 20 years getting better at software engineering.

Or they can spend 20 years repeating the same mistakes.

The “I’ve Been Doing This for 20 Years” Developer

There’s a particular kind of senior engineer who is difficult to work with.

They’ve been doing this for a long time.
They’ve seen everything.
They have an answer for everything.

And every new problem gets solved with something they’ve already done before.

You suggest a different approach.
They tell you why it won’t work.

You show them an example.
They explain why that example is different.

You point out a problem with their approach.
They tell you they’ve been doing this for 20 years.

And that’s supposed to end the discussion.

Experience Doesn’t Fix Bad Habits

It makes them harder to see.

A developer who has spent 10 years writing huge classes doesn’t necessarily become better at design.

They might simply become extremely fast at writing huge classes.

A developer who has spent 10 years avoiding tests doesn’t become good at testing.

They become very experienced at working without tests.

And someone who has spent years solving every problem with another layer, abstraction, framework, or design pattern can become incredibly experienced at overengineering.

Experience makes you better at whatever you repeatedly practice.

Including the wrong things.

Stop Counting Years

Years of experience are a terrible measurement of engineering ability.

A developer with three years of experience who constantly learns, experiments, gets feedback, and improves their approach can be far more effective than someone with fifteen years who stopped learning five years ago.

I’ve seen developers with relatively little experience who can walk into an unfamiliar codebase and start asking the right questions.

And I’ve seen extremely experienced developers who can’t change their approach even when it’s clearly not working.

Good Engineers Say “I Was Wrong”

The best engineers can look at their own code and say:

“I wouldn’t write this that way today.”

Years of experience can tell you how long someone has been in the game.

It doesn’t tell you how well they’ve played it.

Getting better means being willing to rethink how you’ve been doing things.

Join the live session:

Clean Architecture for Backend Developers

🗓 Aug 26
⏰ 5:00–6:30 PM (CEST)

🏆Register now

🔒 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 first time you see Hexagonal Architecture, it can feel like a lot.

Schedule a shipment.

You're used to something like: ShipmentHttpController, talking straight to the ORM and the FedEx API. One class, two integrations.

Then you look at the Hexagonal Architecture version of the same feature:

• driving adapter (ShipmentHttpController)

• driving port (ScheduleShipmentUseCase)

• the hexagon itself (Shipment, Address, PackageDetails, ShipmentRepository, CourierGateway)

• driven adapters (SqlShipmentRepository, FedExCourierGateway).

And here’s where things can get out of hand.

You start creating all of these classes before you actually need them.

The Starting Point

🚫 Problem: No pain yet

One feature, one caller, one integration on each side.

✅ Solution: Ship it as a single class

There’s nothing to abstract until something actually hurts.

One class handles the HTTP request, runs the validation, talks to Postgres through JPA, and calls the FedEx SDK directly. No ports, no adapters, no domain model.

This isn't the design we'd want to keep forever: it’s slow to test and it’s going to get worse as more logic lands in it — but it hasn’t gotten worse yet.

Step 1 — Driven Ports Keep I/O Out of the Way

🚫 Problem: Tests are slow

Every test hits a real Postgres instance and the real FedEx test instance, so they’re slow, and the test instance goes down more often than the code changes.

✅ Solution: Use driven ports for I/O

Read more