You add the annotation to a method, start the application, database writes work, rollback works, tests are green.

And I really do not want to write an article titled: “@Transactional is bad, remove it from your projects”. That would simply be untrue. The problem starts somewhere else: very often the annotation ends up where it is easiest to paste it, not where the transaction should actually start and end.

In this article I want to show a few problems I regularly see in code based on @Transactional, and an alternative I prefer to use in the application layer: an explicit transaction boundary based on a lambda.

In this part I focus only on classic, imperative code: JDBC, JPA, Spring Data, TransactionTemplate. No WebFlux, no R2DBC, no reactive streams. That deserves a separate article.

1. @Transactional is convenient, but it hides the boundary

The simplest example looks harmless:

@Service
class AccountService {

    private final AccountRepository accountRepository;
    private final ExchangeRateClient exchangeRateClient;
    private final AccountHistoryRepository historyRepository;

    AccountService(
            AccountRepository accountRepository,
            ExchangeRateClient exchangeRateClient,
            AccountHistoryRepository historyRepository
    ) {
        this.accountRepository = accountRepository;
        this.exchangeRateClient = exchangeRateClient;
        this.historyRepository = historyRepository;
    }

    @Transactional
    AccountSnapshot exchange(ExchangeCurrencyCommand command) {
        var account = accountRepository.findById(command.accountId())
                .orElseThrow(AccountNotFoundException::new);

        var rate = exchangeRateClient.currentUsdRate();

        account.exchangePlnToUsd(command.amount(), rate);

        accountRepository.save(account);
        historyRepository.save(AccountHistory.from(account));

        return account.toSnapshot();
    }
}

At first glance, everything is OK. One method, one use case, one transaction.

But let’s ask one question: what should actually be inside the transaction?

Should fetching an exchange rate from an external API keep a database transaction open? Should command validation run inside a transaction? Should mapping a DTO response run inside a transaction? Should the whole method be transactional only because we do two database writes at the end?

And this is where the problem starts. @Transactional on a method makes the whole method transactional. Not a “part of the method”. Not “only save”. The whole method.

☹️ Sad little code:

@Transactional
AccountSnapshot exchange(ExchangeCurrencyCommand command) {
    validate(command);

    var rate = exchangeRateClient.currentUsdRate(); // external API

    var account = accountRepository.findById(command.accountId())
            .orElseThrow(AccountNotFoundException::new);

    account.exchangePlnToUsd(command.amount(), rate);

    accountRepository.save(account);
    historyRepository.save(AccountHistory.from(account));

    return account.toSnapshot();
}

Technically, it works.

The problem is that the transaction starts before validation and also stays open during the external API call. If the API responds slowly, we hold transactional resources longer than necessary. If there are locks inside, SELECT ... FOR UPDATE, higher load, or several parallel requests, things become less pleasant.

Does it mean every method like this will immediately take production down? No. But this is exactly the kind of code that “works” for a long time, until one day it starts hurting.

2. A transaction should have the smallest readable scope possible

I prefer when a transaction looks like a conscious decision in code, not a decoration on a class.

Example:

public interface TransactionBoundary {

    <T> T inTransaction(Supplier<T> operation);

    void inTransaction(Runnable operation);
}

And a Spring-based implementation:

@Component
class SpringTransactionBoundary implements TransactionBoundary {

    private final TransactionTemplate transactionTemplate;

    SpringTransactionBoundary(PlatformTransactionManager transactionManager) {
        this.transactionTemplate = new TransactionTemplate(transactionManager);
    }

    @Override
    public <T> T inTransaction(Supplier<T> operation) {
        return transactionTemplate.execute(status -> operation.get());
    }

    @Override
    public void inTransaction(Runnable operation) {
        transactionTemplate.executeWithoutResult(status -> operation.run());
    }
}

From this point, the use case can look like this:

🙂

@Service
class AccountService {

    private final TransactionBoundary transaction;
    private final AccountRepository accountRepository;
    private final ExchangeRateClient exchangeRateClient;
    private final AccountHistoryRepository historyRepository;

    AccountService(
            TransactionBoundary transaction,
            AccountRepository accountRepository,
            ExchangeRateClient exchangeRateClient,
            AccountHistoryRepository historyRepository
    ) {
        this.transaction = transaction;
        this.accountRepository = accountRepository;
        this.exchangeRateClient = exchangeRateClient;
        this.historyRepository = historyRepository;
    }

    AccountSnapshot exchange(ExchangeCurrencyCommand command) {
        validate(command);

        var rate = exchangeRateClient.currentUsdRate();

        return transaction.inTransaction(() -> {
            var account = accountRepository.findById(command.accountId())
                    .orElseThrow(AccountNotFoundException::new);

            account.exchangePlnToUsd(command.amount(), rate);

            accountRepository.save(account);
            historyRepository.save(AccountHistory.from(account));

            return account.toSnapshot();
        });
    }
}

The difference in code is small, but the difference in intent is big.

Now it is clear that:

• validation is outside the transaction,
• the external API call is outside the transaction,
• the transaction contains only reading the current state, changing the aggregate and saving it,
• the boundary is visible exactly where I read the use case.

This is not a fight against Spring. Spring still does the work: opens the transaction, commits it, rolls it back. The difference is that the application layer does not have to guess where exactly the proxy works and which annotation will be intercepted.

3. The problem with private methods and self-invocation

This one is a classic.

☹️ Sad little code:

@Service
class OrderService {

    private final OrderRepository orderRepository;
    private final PaymentRepository paymentRepository;

    OrderService(OrderRepository orderRepository, PaymentRepository paymentRepository) {
        this.orderRepository = orderRepository;
        this.paymentRepository = paymentRepository;
    }

    OrderId create(CreateOrderCommand command) {
        validate(command);
        return createInsideTransaction(command);
    }

    @Transactional
    private OrderId createInsideTransaction(CreateOrderCommand command) {
        var order = Order.create(command.customerId(), command.amount());

        orderRepository.save(order);
        paymentRepository.reserve(order.id(), order.amount());

        return order.id();
    }
}

This is very easy to miss during code review. We see @Transactional, and our brain adds: “OK, there is a transaction”.

But a private method is not a place where a Spring proxy can normally intercept the call. What is more, even when the method is public, but it is called from the same class through this.someMethod(), we run into the self-invocation problem. We do not go through the proxy, so the annotation may not do what we expect.

With a lambda, the problem disappears, because the transaction does not depend on whether the method was public, private, called from another bean, or called from the same class.

🙂

@Service
class OrderService {

    private final TransactionBoundary transaction;
    private final OrderRepository orderRepository;
    private final PaymentRepository paymentRepository;

    OrderService(
            TransactionBoundary transaction,
            OrderRepository orderRepository,
            PaymentRepository paymentRepository
    ) {
        this.transaction = transaction;
        this.orderRepository = orderRepository;
        this.paymentRepository = paymentRepository;
    }

    OrderId create(CreateOrderCommand command) {
        validate(command);

        return transaction.inTransaction(() -> createInsideTransaction(command));
    }

    private OrderId createInsideTransaction(CreateOrderCommand command) {
        var order = Order.create(command.customerId(), command.amount());

        orderRepository.save(order);
        paymentRepository.reserve(order.id(), order.amount());

        return order.id();
    }
}

Is the private method a problem now? No. It is just a helper method. The transaction boundary is at the place where we call transaction.inTransaction(...).

4. The annotation often mixes an architectural decision with a technical detail

In practice, @Transactional often lands on classes like ApplicationService, UseCase, Facade.

In other words, in places where we want to read the business scenario.

And then such a use case starts to look like a Christmas tree:

@Service
@Transactional
class RegisterUserService {

    @Transactional(readOnly = true)
    UserView preview(PreviewUserCommand command) {
        // ...
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    void auditRegistration(User user) {
        // ...
    }

    @Transactional(timeout = 5)
    UserId register(RegisterUserCommand command) {
        // ...
    }
}

Of course, these settings are sometimes needed. The problem is that they start living as decorations on methods, not as a readable part of the process.

Why not simply name it like this?

public interface TransactionBoundary {

    <T> T inTransaction(Supplier<T> operation);

    <T> T inReadOnlyTransaction(Supplier<T> operation);

    <T> T inNewTransaction(Supplier<T> operation);
}

Implementation:

@Component
class SpringTransactionBoundary implements TransactionBoundary {

    private final TransactionTemplate required;
    private final TransactionTemplate readOnly;
    private final TransactionTemplate requiresNew;

    SpringTransactionBoundary(PlatformTransactionManager transactionManager) {
        this.required = new TransactionTemplate(transactionManager);

        this.readOnly = new TransactionTemplate(transactionManager);
        this.readOnly.setReadOnly(true);

        this.requiresNew = new TransactionTemplate(transactionManager);
        this.requiresNew.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRES_NEW);
    }

    @Override
    public <T> T inTransaction(Supplier<T> operation) {
        return required.execute(status -> operation.get());
    }

    @Override
    public <T> T inReadOnlyTransaction(Supplier<T> operation) {
        return readOnly.execute(status -> operation.get());
    }

    @Override
    public <T> T inNewTransaction(Supplier<T> operation) {
        return requiresNew.execute(status -> operation.get());
    }
}

Usage:

UserView preview(PreviewUserCommand command) {
    return transaction.inReadOnlyTransaction(() -> {
        var user = userRepository.findByEmail(command.email())
                .orElseThrow(UserNotFoundException::new);

        return UserView.from(user);
    });
}

In the code, I immediately see that this is a read. I do not have to look at the annotation on the method, on the class, in the interface, in the superclass, or wonder whether the call accidentally bypasses the proxy.

5. Long transactions are not only a technical problem, but also a modelling problem

Very often, long transactions are a symptom that a use case does too much.

☹️ Sad little code:

@Transactional
OrderId placeOrder(PlaceOrderCommand command) {
    var customer = customerRepository.findById(command.customerId())
            .orElseThrow(CustomerNotFoundException::new);

    var pricing = pricingClient.calculate(command.items());
    var order = Order.place(customer, command.items(), pricing);

    orderRepository.save(order);

    invoiceClient.createInvoice(order);
    emailSender.sendOrderConfirmation(order);

    orderStatusRepository.save(OrderStatus.confirmed(order.id()));

    return order.id();
}

We have here:

• reading the customer,
• a call to an external pricing service,
• saving the order,
• a call to an invoicing system,
• sending an email,
• saving the status.

All of this inside one method and one transaction. If the external invoicing system responds after three seconds, the transaction waits. If the email is not sent, should we roll back the order? Maybe yes, maybe no. But that should be a business decision, not a side effect of marking the whole method with a single annotation.

A better direction:

OrderId placeOrder(PlaceOrderCommand command) {
    validate(command);

    var pricing = pricingClient.calculate(command.items());

    var orderId = transaction.inTransaction(() -> {
        var customer = customerRepository.findById(command.customerId())
                .orElseThrow(CustomerNotFoundException::new);

        var order = Order.place(customer, command.items(), pricing);

        orderRepository.save(order);
        outboxRepository.save(OrderPlacedEvent.from(order));

        return order.id();
    });

    return orderId;
}

External side effects can be handled later: through an outbox, an event handler, an asynchronous process, a scheduler, a queue. You do not always have to bring event-driven architecture to a small problem, but it is worth building the habit of asking: does this side effect really have to be in the same database transaction?

6. Kotlin variant

In Kotlin, this kind of boundary looks even more natural. In one of my projects, I used a similar idea with an inTransaction { ... } function, because this syntax fits the style of use cases very well.

Minimal version:

interface TransactionBoundary {

    fun <T> inTransaction(block: () -> T): T

    fun <T> inReadOnlyTransaction(block: () -> T): T
}

Spring implementation:

@Component
class SpringTransactionBoundary(
    transactionManager: PlatformTransactionManager,
) : TransactionBoundary {

    private val required = TransactionTemplate(transactionManager)

    private val readOnly = TransactionTemplate(transactionManager).apply {
        isReadOnly = true
    }

    override fun <T> inTransaction(block: () -> T): T {
        return required.execute<T> { block() } as T
    }

    override fun <T> inReadOnlyTransaction(block: () -> T): T {
        return readOnly.execute<T> { block() } as T
    }
}

Usage in an application service:

@Service
class AccountService(
    private val transaction: TransactionBoundary,
    private val accountRepository: AccountRepository,
    private val accountOperationRepository: AccountOperationRepository,
    private val exchangeRateProvider: ExchangeRateProvider,
) {

    fun exchange(command: ExchangeCurrencyCommand): AccountSnapshot {
        val rate = exchangeRateProvider.currentUsdRate()

        return transaction.inTransaction {
            val account = accountRepository.findBy(command.accountId)
                ?: throw AccountNotFoundException(command.accountId)

            account.exchangePlnToUsd(command.amount, rate)

            accountRepository.save(account)
            accountOperationRepository.save(account.pullEvents())

            account.toSnapshot()
        }
    }
}

Is this much more complicated than @Transactional? No.

But it is more explicit. And for me, that is the main benefit.

7. Testing becomes simpler

If the use case depends on a small interface:

public interface TransactionBoundary {

    <T> T inTransaction(Supplier<T> operation);
}

then in a unit test I do not need Spring, proxies, or a real transaction manager.

final class ImmediateTransactionBoundary implements TransactionBoundary {

    @Override
    public <T> T inTransaction(Supplier<T> operation) {
        return operation.get();
    }
}

And I can test the use case logic normally:

@Test
void shouldCreateOrderAndReservePayment() {
    // given
    var transaction = new ImmediateTransactionBoundary();
    var orderRepository = new InMemoryOrderRepository();
    var paymentRepository = new InMemoryPaymentRepository();

    var service = new OrderService(transaction, orderRepository, paymentRepository);

    // when
    var orderId = service.create(new CreateOrderCommand("customer-1", BigDecimal.TEN));

    // then
    assertThat(orderRepository.findById(orderId)).isPresent();
    assertThat(paymentRepository.existsFor(orderId)).isTrue();
}

In an integration test, of course, I still want to verify that the Spring implementation works with the database. But I do not have to start the whole world for every business test only because there is a @Transactional annotation somewhere on a method.

8. So should we throw @Transactional away?

No.

There are places where @Transactional is good enough:

• simple CRUD,
• a small admin application,
• a method that really is one database operation from start to finish,
• infrastructure code where a dependency on Spring does not bother us,
• a quick prototype where an explicit boundary would only add noise.

The problem is not that the annotation exists. The problem is that we often use it as the default answer to every question about data consistency.

And a transaction is a design decision.

Where does a consistent write start? Where does the effect of rollback end? Should the external call be inside? Should the event be saved together with the aggregate? Should an email roll back the order? Should audit have its own transaction?

The annotation hides these questions. A lambda-based boundary forces us to see them.

Summary

@Transactional is convenient, but it has a few traps:

1. It covers the whole method, so it is easy to create a transaction scope that is too wide.
2. It works through proxies, so private methods and self-invocation can surprise you.
3. It mixes technical configuration with the description of the use case.
4. It makes it harder to see what exactly should be rolled back.
5. It tempts us to put things inside one transaction that should not be there.

The alternative does not have to be complicated. Sometimes a small interface is enough:

transaction.inTransaction(() -> {
    // only what really has to be inside the transaction
});

For me, the most important side effect of this approach is that the use case starts telling the truth about the process. It does not hide boundaries behind an annotation, does not require remembering how Spring proxies work, and does not pretend that the whole method is always a good transaction scope.

And if the transaction boundary is not visible in code, it is very easy to assume it is where we wish it was.

Unfortunately, code does not run on wishes.

What next

This article was about the classic, imperative approach: JDBC/JPA + TransactionTemplate.

In the reactive world, the topic becomes even more interesting, because Reactor context, Mono, Flux, subscription cancellation and TransactionalOperator enter the picture. For this reason I prepared a separate project: spring-reactive-transaction-boundary.

Repository:

https://github.com/CamilYed/spring-reactive-transaction-boundary

Dodajesz adnotację na metodzie, odpalasz aplikację, zapis do bazy działa, rollback działa, testy są zielone.

I naprawdę nie mam zamiaru pisać tekstu pod tytułem: “@Transactional jest zły, usuńcie go z projektów”. To byłoby zwyczajnie nieprawdziwe. Problem zaczyna się gdzie indziej: bardzo często adnotacja trafia tam, gdzie najłatwiej ją wkleić, a nie tam, gdzie faktycznie powinna zaczynać się i kończyć transakcja.

W tym artykule chciałbym pokazać kilka problemów, które regularnie widzę w kodzie opartym o @Transactional, oraz alternatywę, którą wolę stosować w warstwie aplikacyjnej: jawny transaction boundary oparty o lambdę.

W tej części skupiam się wyłącznie na klasycznym, imperatywnym kodzie: JDBC, JPA, Spring Data, TransactionTemplate. Bez WebFluxa, bez R2DBC, bez reactive streams. O tym można zrobić osobny tekst.

1. @Transactional jest wygodne, ale ukrywa granicę

Najprostszy przykład wygląda niewinnie:

@Service
class AccountService {

    private final AccountRepository accountRepository;
    private final ExchangeRateClient exchangeRateClient;
    private final AccountHistoryRepository historyRepository;

    AccountService(
            AccountRepository accountRepository,
            ExchangeRateClient exchangeRateClient,
            AccountHistoryRepository historyRepository
    ) {
        this.accountRepository = accountRepository;
        this.exchangeRateClient = exchangeRateClient;
        this.historyRepository = historyRepository;
    }

    @Transactional
    AccountSnapshot exchange(ExchangeCurrencyCommand command) {
        var account = accountRepository.findById(command.accountId())
                .orElseThrow(AccountNotFoundException::new);

        var rate = exchangeRateClient.currentUsdRate();

        account.exchangePlnToUsd(command.amount(), rate);

        accountRepository.save(account);
        historyRepository.save(AccountHistory.from(account));

        return account.toSnapshot();
    }
}

Na pierwszy rzut oka jest OK. Jedna metoda, jeden use case, jedna transakcja.

Ale zadajmy sobie pytanie: co tak naprawdę powinno być w transakcji?

Czy pobranie kursu waluty z zewnętrznego API powinno trzymać otwartą transakcję bazodanową? Czy walidacja komendy powinna działać w transakcji? Czy mapowanie odpowiedzi DTO powinno działać w transakcji? Czy cała metoda ma być transakcyjna tylko dlatego, że na końcu robimy dwa zapisy do bazy?

I tutaj zaczyna się problem. @Transactional na metodzie robi transakcyjną całą metodę. Nie “fragment metody”. Nie “tylko save”. Całą metodę.

☹️ Smutny kodzik:

@Transactional
AccountSnapshot exchange(ExchangeCurrencyCommand command) {
    validate(command);

    var rate = exchangeRateClient.currentUsdRate(); // zewnętrzne API

    var account = accountRepository.findById(command.accountId())
            .orElseThrow(AccountNotFoundException::new);

    account.exchangePlnToUsd(command.amount(), rate);

    accountRepository.save(account);
    historyRepository.save(AccountHistory.from(account));

    return account.toSnapshot();
}

Technicznie działa.

Tylko że transakcja zaczyna się przed walidacją i trwa również podczas wywołania zewnętrznego API. Jeśli API odpowiada wolno, trzymamy zasoby transakcyjne dłużej niż trzeba. Jeśli w środku mamy jeszcze locki, SELECT ... FOR UPDATE, większy load albo kilka równoległych requestów, to robi się mniej przyjemnie.

Czy to znaczy, że każda taka metoda od razu położy produkcję? Nie. Ale to jest dokładnie ten typ kodu, który przez długi czas “działa”, aż pewnego dnia zaczyna boleć.

2. Transakcja powinna mieć możliwie mały i czytelny zakres

Wolę, kiedy transakcja wygląda jak świadoma decyzja w kodzie, a nie jak dekoracja klasy.

Przykład:

public interface TransactionBoundary {

    <T> T inTransaction(Supplier<T> operation);

    void inTransaction(Runnable operation);
}

I implementacja oparta o Springa:

@Component
class SpringTransactionBoundary implements TransactionBoundary {

    private final TransactionTemplate transactionTemplate;

    SpringTransactionBoundary(PlatformTransactionManager transactionManager) {
        this.transactionTemplate = new TransactionTemplate(transactionManager);
    }

    @Override
    public <T> T inTransaction(Supplier<T> operation) {
        return transactionTemplate.execute(status -> operation.get());
    }

    @Override
    public void inTransaction(Runnable operation) {
        transactionTemplate.executeWithoutResult(status -> operation.run());
    }
}

Od tej chwili use case może wyglądać tak:

🙂

@Service
class AccountService {

    private final TransactionBoundary transaction;
    private final AccountRepository accountRepository;
    private final ExchangeRateClient exchangeRateClient;
    private final AccountHistoryRepository historyRepository;

    AccountService(
            TransactionBoundary transaction,
            AccountRepository accountRepository,
            ExchangeRateClient exchangeRateClient,
            AccountHistoryRepository historyRepository
    ) {
        this.transaction = transaction;
        this.accountRepository = accountRepository;
        this.exchangeRateClient = exchangeRateClient;
        this.historyRepository = historyRepository;
    }

    AccountSnapshot exchange(ExchangeCurrencyCommand command) {
        validate(command);

        var rate = exchangeRateClient.currentUsdRate();

        return transaction.inTransaction(() -> {
            var account = accountRepository.findById(command.accountId())
                    .orElseThrow(AccountNotFoundException::new);

            account.exchangePlnToUsd(command.amount(), rate);

            accountRepository.save(account);
            historyRepository.save(AccountHistory.from(account));

            return account.toSnapshot();
        });
    }
}

Różnica jest mała w kodzie, ale duża w intencji.

Teraz widać, że:

• walidacja jest poza transakcją,
• call do zewnętrznego API jest poza transakcją,
• transakcja obejmuje tylko odczyt aktualnego stanu, zmianę agregatu i zapis,
• granica jest widoczna tam, gdzie czytam use case.

To nie jest walka ze Springiem. Spring nadal robi robotę: otwiera transakcję, commituje, rollbackuje. Różnica polega na tym, że warstwa aplikacyjna nie musi zgadywać, gdzie dokładnie działa proxy i która adnotacja zostanie przechwycona.

3. Problem prywatnych metod i self-invocation

To jest klasyk.

☹️ Smutny kodzik:

@Service
class OrderService {

    private final OrderRepository orderRepository;
    private final PaymentRepository paymentRepository;

    OrderService(OrderRepository orderRepository, PaymentRepository paymentRepository) {
        this.orderRepository = orderRepository;
        this.paymentRepository = paymentRepository;
    }

    OrderId create(CreateOrderCommand command) {
        validate(command);
        return createInsideTransaction(command);
    }

    @Transactional
    private OrderId createInsideTransaction(CreateOrderCommand command) {
        var order = Order.create(command.customerId(), command.amount());

        orderRepository.save(order);
        paymentRepository.reserve(order.id(), order.amount());

        return order.id();
    }
}

Na code review bardzo łatwo to przeoczyć. Widzimy @Transactional, mózg dopowiada: “OK, transakcja jest”.

Tylko że prywatna metoda nie jest miejscem, w którym Springowe proxy może normalnie przeciąć wywołanie. Co więcej, nawet gdy metoda jest publiczna, ale wywoływana z tej samej klasy przez this.someMethod(), wchodzimy w problem self-invocation. Nie przechodzimy przez proxy, więc adnotacja może nie zrobić tego, czego się spodziewamy.

Z lambdą problem znika, bo transakcja nie zależy od tego, czy metoda była publiczna, prywatna, zawołana z innego beana czy z tej samej klasy.

🙂

@Service
class OrderService {

    private final TransactionBoundary transaction;
    private final OrderRepository orderRepository;
    private final PaymentRepository paymentRepository;

    OrderService(
            TransactionBoundary transaction,
            OrderRepository orderRepository,
            PaymentRepository paymentRepository
    ) {
        this.transaction = transaction;
        this.orderRepository = orderRepository;
        this.paymentRepository = paymentRepository;
    }

    OrderId create(CreateOrderCommand command) {
        validate(command);

        return transaction.inTransaction(() -> createInsideTransaction(command));
    }

    private OrderId createInsideTransaction(CreateOrderCommand command) {
        var order = Order.create(command.customerId(), command.amount());

        orderRepository.save(order);
        paymentRepository.reserve(order.id(), order.amount());

        return order.id();
    }
}

Czy prywatna metoda jest teraz problemem? Nie. To zwykła metoda pomocnicza. Granica transakcji jest w miejscu, gdzie wywołujemy transaction.inTransaction(...).

4. Adnotacja często miesza decyzję architektoniczną z detalem technicznym

@Transactional w praktyce często ląduje na klasach typu ApplicationService, UseCase, Facade.

Czyli w miejscu, gdzie chcemy czytać scenariusz biznesowy.

A potem taki use case zaczyna wyglądać jak choinka:

@Service
@Transactional
class RegisterUserService {

    @Transactional(readOnly = true)
    UserView preview(PreviewUserCommand command) {
        // ...
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    void auditRegistration(User user) {
        // ...
    }

    @Transactional(timeout = 5)
    UserId register(RegisterUserCommand command) {
        // ...
    }
}

Oczywiście, te ustawienia są czasem potrzebne. Problem polega na tym, że zaczynają żyć jako dekoracje metod, a nie jako czytelny fragment procesu.

Czemu po prostu nie nazwać tego w taki sposób?:

public interface TransactionBoundary {

    <T> T inTransaction(Supplier<T> operation);

    <T> T inReadOnlyTransaction(Supplier<T> operation);

    <T> T inNewTransaction(Supplier<T> operation);
}

Implementacja:

@Component
class SpringTransactionBoundary implements TransactionBoundary {

    private final TransactionTemplate required;
    private final TransactionTemplate readOnly;
    private final TransactionTemplate requiresNew;

    SpringTransactionBoundary(PlatformTransactionManager transactionManager) {
        this.required = new TransactionTemplate(transactionManager);

        this.readOnly = new TransactionTemplate(transactionManager);
        this.readOnly.setReadOnly(true);

        this.requiresNew = new TransactionTemplate(transactionManager);
        this.requiresNew.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRES_NEW);
    }

    @Override
    public <T> T inTransaction(Supplier<T> operation) {
        return required.execute(status -> operation.get());
    }

    @Override
    public <T> T inReadOnlyTransaction(Supplier<T> operation) {
        return readOnly.execute(status -> operation.get());
    }

    @Override
    public <T> T inNewTransaction(Supplier<T> operation) {
        return requiresNew.execute(status -> operation.get());
    }
}

Użycie:

UserView preview(PreviewUserCommand command) {
    return transaction.inReadOnlyTransaction(() -> {
        var user = userRepository.findByEmail(command.email())
                .orElseThrow(UserNotFoundException::new);

        return UserView.from(user);
    });
}

W kodzie od razu widać, że to jest odczyt. Nie muszę patrzeć na adnotację nad metodą, nad klasą, w interfejsie, w superklasie, albo zastanawiać się, czy przypadkiem wywołanie nie omija proxy.

5. Długie transakcje to nie tylko problem techniczny, ale też modelowania

Bardzo często długie transakcje są objawem tego, że use case robi za dużo.

☹️ Smutny kodzik:

@Transactional
OrderId placeOrder(PlaceOrderCommand command) {
    var customer = customerRepository.findById(command.customerId())
            .orElseThrow(CustomerNotFoundException::new);

    var pricing = pricingClient.calculate(command.items());
    var order = Order.place(customer, command.items(), pricing);

    orderRepository.save(order);

    invoiceClient.createInvoice(order);
    emailSender.sendOrderConfirmation(order);

    orderStatusRepository.save(OrderStatus.confirmed(order.id()));

    return order.id();
}

Mamy tutaj:

• odczyt klienta,
• call do zewnętrznego pricingu,
• zapis zamówienia,
• call do systemu faktur,
• wysyłkę maila,
• zapis statusu.

To wszystko w jednej metodzie i jednej transakcji. Jeśli zewnętrzny system faktur odpowie po 3 sekundach, transakcja czeka. Jeśli mail nie wyjdzie, rollbackujemy zapis zamówienia? Może tak, może nie. Ale to powinna być decyzja biznesowa, a nie efekt tego, że cała metoda była oznaczona jedną adnotacją.

Lepszy kierunek:

OrderId placeOrder(PlaceOrderCommand command) {
    validate(command);

    var pricing = pricingClient.calculate(command.items());

    var orderId = transaction.inTransaction(() -> {
        var customer = customerRepository.findById(command.customerId())
                .orElseThrow(CustomerNotFoundException::new);

        var order = Order.place(customer, command.items(), pricing);

        orderRepository.save(order);
        outboxRepository.save(OrderPlacedEvent.from(order));

        return order.id();
    });

    return orderId;
}

Zewnętrzne efekty uboczne można obsłużyć później: przez outbox, event handler, proces asynchroniczny, scheduler, kolejkę. Nie zawsze trzeba robić event-driven architecture z armaty do muchy, ale warto mieć odruch pytania: czy ten efekt uboczny naprawdę musi być w tej samej transakcji bazodanowej?

6. Kotlinowy wariant

W Kotlinie taki boundary wygląda jeszcze naturalniej. W jednym z moich projektów robiłem podobną rzecz właśnie przez funkcję inTransaction { ... }, bo taki zapis bardzo dobrze pasuje do stylu use case’ów.

Minimalna wersja:

interface TransactionBoundary {

    fun <T> inTransaction(block: () -> T): T

    fun <T> inReadOnlyTransaction(block: () -> T): T
}

Implementacja Springowa:

@Component
class SpringTransactionBoundary(
    transactionManager: PlatformTransactionManager,
) : TransactionBoundary {

    private val required = TransactionTemplate(transactionManager)

    private val readOnly = TransactionTemplate(transactionManager).apply {
        isReadOnly = true
    }

    override fun <T> inTransaction(block: () -> T): T {
        return required.execute<T> { block() } as T
    }

    override fun <T> inReadOnlyTransaction(block: () -> T): T {
        return readOnly.execute<T> { block() } as T
    }
}

Użycie w serwisie aplikacyjnym:

@Service
class AccountService(
    private val transaction: TransactionBoundary,
    private val accountRepository: AccountRepository,
    private val accountOperationRepository: AccountOperationRepository,
    private val exchangeRateProvider: ExchangeRateProvider,
) {

    fun exchange(command: ExchangeCurrencyCommand): AccountSnapshot {
        val rate = exchangeRateProvider.currentUsdRate()

        return transaction.inTransaction {
            val account = accountRepository.findBy(command.accountId)
                ?: throw AccountNotFoundException(command.accountId)

            account.exchangePlnToUsd(command.amount, rate)

            accountRepository.save(account)
            accountOperationRepository.save(account.pullEvents())

            account.toSnapshot()
        }
    }
}

Czy to jest dużo bardziej skomplikowane niż @Transactional? Nie.

Ale jest bardziej jawne. I dla mnie to jest główny zysk.

7. Testowanie staje się prostsze

Jeśli use case zależy od małego interfejsu:

public interface TransactionBoundary {

    <T> T inTransaction(Supplier<T> operation);
}

to w teście jednostkowym nie potrzebuję Springa, proxy ani prawdziwego transaction managera.

final class ImmediateTransactionBoundary implements TransactionBoundary {

    @Override
    public <T> T inTransaction(Supplier<T> operation) {
        return operation.get();
    }
}

I testuję logikę use case’a normalnie:

@Test
void shouldCreateOrderAndReservePayment() {
    // given
    var transaction = new ImmediateTransactionBoundary();
    var orderRepository = new InMemoryOrderRepository();
    var paymentRepository = new InMemoryPaymentRepository();

    var service = new OrderService(transaction, orderRepository, paymentRepository);

    // when
    var orderId = service.create(new CreateOrderCommand("customer-1", BigDecimal.TEN));

    // then
    assertThat(orderRepository.findById(orderId)).isPresent();
    assertThat(paymentRepository.existsFor(orderId)).isTrue();
}

W teście integracyjnym oczywiście nadal chcę sprawdzić, czy implementacja Springowa działa z bazą. Ale nie muszę do każdego testu biznesowego odpalać całego świata tylko dlatego, że gdzieś na metodzie jest @Transactional.

8. Czyli @Transactional wyrzucamy do kosza?

Nie.

Są miejsca, gdzie @Transactional jest wystarczająco dobre:

• prosty CRUD,
• mała aplikacja administracyjna,
• metoda, która naprawdę w całości jest jedną operacją bazodanową,
• kod infrastrukturalny, gdzie nie przeszkadza nam zależność od Springa,
• szybki prototyp, gdzie jawna granica byłaby tylko dodatkowym szumem.

Problem nie polega na tym, że adnotacja istnieje. Problem polega na tym, że często używamy jej jako domyślnej odpowiedzi na każde pytanie o spójność danych.

A transakcja jest decyzją projektową.

Gdzie zaczyna się spójny zapis? Gdzie kończy się wpływ rollbacka? Czy zewnętrzny call powinien być w środku? Czy event ma być zapisany razem z agregatem? Czy mail ma rollbackować zamówienie? Czy audyt ma mieć własną transakcję?

Adnotacja ukrywa te pytania. Boundary przez lambdę zmusza, żeby je zobaczyć.

Podsumowanie

@Transactional jest wygodne, ale ma kilka pułapek:

1. Obejmuje całą metodę, więc łatwo stworzyć zbyt szeroki scope transakcji.
2. Działa przez proxy, więc prywatne metody i self-invocation potrafią zaskoczyć.
3. Miesza konfigurację techniczną z opisem use case’a.
4. Utrudnia zobaczenie, co dokładnie ma zostać rollbackowane.
5. Kusi, żeby wrzucać do jednej transakcji rzeczy, które nie powinny tam być.

Alternatywa nie musi być skomplikowana. Czasem wystarczy mały interfejs:

transaction.inTransaction(() ->{
        // tylko to, co naprawdę ma być w transakcji
        });

Dla mnie najważniejszy jest efekt uboczny tego podejścia: kod use case’a zaczyna mówić prawdę o procesie. Nie ukrywa granic za adnotacją, nie wymaga pamiętania o Springowym proxy i nie udaje, że cała metoda zawsze jest dobrym zakresem transakcji.

A jeśli granicy transakcji nie widać w kodzie, to bardzo łatwo założyć, że jest tam, gdzie chcielibyśmy, żeby była.

Niestety kod nie działa na życzeniach.

Co dalej

Ten tekst dotyczył klasycznego, imperatywnego podejścia: JDBC/JPA + TransactionTemplate.

W świecie reaktywnym temat robi się jeszcze ciekawszy, bo dochodzi Reactor context, Mono, Flux, anulowanie subskrypcji i TransactionalOperator. Z tego powodu przygotowałem osobny projekt: spring-reactive-transaction-boundary.

Repozytorium jest tutaj:

https://github.com/CamilYed/spring-reactive-transaction-boundary

Bielany is a northern district of Warsaw, a little away from the postcard version of the city.
Around Młociny, you can still feel a mix of residential calm, metro-endpoint rhythm, forest edges, and traces of older industrial Warsaw.
One of those traces is the memory of the steelworks — a place that once shaped the character of this part of the city.
I live nearby, so this industrial background is not an abstract historical note for me, but part of the local landscape.
That is why a simple desk with coffee, Java, and a “Zakład Pracy” mug suddenly feels connected to something bigger.

Młociny, Bielany, somewhere near the old steelworks.

A few chimneys, an industrial landscape, and a completely different kind of workplace today: coffee, Java, two monitors, and a laptop.

Steel was produced here once.
Today, it is code.

I do not want to turn this into a grand metaphor, but I like the contrast.

The steelworks in the background.
Java on the screens.
Coffee next to the keyboard.

Different tools. Different noise. A similar rhythm.

brewCoffee();
writeCode();
runTests();
commit();

Bielany to północna dzielnica Warszawy, trochę poza pocztówkowym obrazem miasta.
W okolicach Młocin czuć mieszankę spokojnej, mieszkaniowej codzienności, końcowej stacji metra, bliskości lasu i śladów dawnej przemysłowej Warszawy.
Jednym z takich śladów jest pamięć o Hucie — miejscu, które przez lata wpływało na charakter tej części miasta.
Mieszkam niedaleko, więc ten przemysłowy kontekst nie jest dla mnie abstrakcyjną historią, tylko częścią lokalnego krajobrazu.
Dlatego zwykłe biurko z kawą, Javą i kubkiem „Zakład Pracy” nagle zaczyna łączyć się z czymś większym.

Młociny, Bielany, okolice Huty.

Kilka kominów, przemysłowy krajobraz i zupełnie inny rodzaj zakładu pracy dzisiaj: kawa, Java, dwa monitory i laptop.

Dawniej produkcja stali.
Dzisiaj produkcja kodu.

Nie chcę robić z tego wielkiej metafory, ale podoba mi się ten kontrast.

Huta w tle.
Java na ekranach.
Kawa obok klawiatury.

Inne narzędzia. Inny hałas. Podobny rytm.

brewCoffee();
writeCode();
runTests();
commit();

did Kotlin get another way to do dependency injection?

After playing with it for a while, I do not see it that way.

context parameters do not create objects. They do not manage dependency lifecycles. They do not replace Spring, Koin or Dagger.

They describe something simpler:

this function can run only when the required context exists at the call site.

And that condition is checked by the compiler.

That is the important part. Not runtime. Not a magic provider. Not a global singleton. The compiler.

The simplest example

Take a clock.

interface ClockProvider {
    fun now(): Instant
}

If a function needs the current time, we can pass the clock as a normal parameter:

fun confirmedAt(clock: ClockProvider): Instant =
    clock.now()

We can also keep it in the constructor, like in classic dependency injection:

class OrderService(
    private val clock: ClockProvider,
) {
    fun confirmedAt(): Instant =
        clock.now()
}

Or we can say that the clock is part of the execution context of this function:

context(clock: ClockProvider)
fun confirmedAt(): Instant =
    clock.now()

The call site looks like this:

val clock = FixedClockProvider(
    Instant.parse("2026-06-05T10:15:30Z"),
)

context(clock) {
    confirmedAt()
}

Without context(clock), this function should not compile.

That is the key difference from a service locator. The dependency is still visible in the function signature, but we do not have to pass it as a regular argument every time.

Parameter, constructor or context?

I would not treat context parameters as a new default answer for everything.

For me the split looks like this:

normal parameters     -> operation input
constructor injection -> stable object dependencies
context parameters    -> execution context

orderId, amount, email, newAddress — these are normal parameters.

OrderRepository, PaymentGateway, HttpClient — these often belong in the constructor of a use case or service.

ClockProvider, UserContext, DomainEvents, Transaction, TenantContext, CorrelationId — these are good candidates for execution context.

Not always, of course. But this boundary feels much healthier than: “great, now everything goes into context(...)”.

Example repository

For this article I created a small DDD / hexagonal example repository:

src/main/kotlin/io/github/camilyed/contextparameters
├── domain
├── application
└── adapter

There is no Spring here. On purpose.

I wanted the example to show the language feature and the design decision, not framework integration.

The domain contains one aggregate: Order.

An order can be a draft or confirmed:

sealed interface OrderState {

    data object Draft : OrderState

    data class Confirmed(
        val confirmedAt: Instant,
    ) : OrderState
}

The aggregate snapshot is simple:

data class OrderSnapshot(
    val id: OrderId,
    val ownerId: UserId,
    val state: OrderState,
)

Now the rule.

An order can be confirmed only when:

• it is still a draft,
• the current user is the owner or can confirm orders,
• confirmation stores the current time,
• confirmation publishes a domain event.

Inside the aggregate it looks like this:

class Order private constructor(
    val id: OrderId,
    val ownerId: UserId,
    private var state: OrderState,
) {
    context(clock: ClockProvider, events: DomainEvents, user: UserContext)
    fun confirm() {
        require(state == OrderState.Draft) {
            "Only draft order can be confirmed"
        }

        require(user.userId == ownerId || user.canConfirmOrders) {
            "User cannot confirm this order"
        }

        val now = clock.now()

        state = OrderState.Confirmed(
            confirmedAt = now,
        )

        events.publish(
            OrderConfirmed(
                orderId = id,
                confirmedAt = now,
            ),
        )
    }
}

This is still a normal domain method.

But its signature says something important:

context(clock: ClockProvider, events: DomainEvents, user: UserContext)
fun confirm()

In other words:

I can confirm an order, but only with a clock, domain events and the current user in context.

I do not want to keep ClockProvider in the entity constructor. A clock does not describe an order.

I also do not want to hide the current user behind a global CurrentUserProvider.

This operation simply runs in a specific context.

Application layer

The use case adds a transaction.

This is where the example becomes more interesting, because the responsibilities are visible:

package io.github.camilyed.contextparameters.application

import io.github.camilyed.contextparameters.domain.ClockProvider
import io.github.camilyed.contextparameters.domain.DomainEvents
import io.github.camilyed.contextparameters.domain.OrderRepository
import io.github.camilyed.contextparameters.domain.OrderSnapshot
import io.github.camilyed.contextparameters.domain.Transaction
import io.github.camilyed.contextparameters.domain.UserContext

class ConfirmOrderUseCase(
    private val orderRepository: OrderRepository,
) {
    context(
        clock: ClockProvider,
        events: DomainEvents,
        user: UserContext,
        transaction: Transaction,
    )
    fun confirm(command: ConfirmOrderCommand): OrderSnapshot =
        transaction.within {
            val order = orderRepository.findById(command.orderId)

            order.confirm()

            orderRepository.save(order)

            order.toSnapshot()
        }
}

orderRepository is in the constructor because it is a stable dependency of the use case.

command is a normal parameter because it is the operation input.

clock, events, user and transaction are in context(...) because they describe the environment in which the operation runs.

This split is the most readable one for me.

What about adapters?

The interfaces live in the domain:

interface OrderRepository {
    fun findById(id: OrderId): Order
    fun save(order: Order)
}

The adapter provides an implementation:

class InMemoryOrderRepository : OrderRepository {

    private val orders = mutableMapOf<OrderId, Order>()

    override fun findById(id: OrderId): Order =
        orders[id]
            ?: throw OrderNotFoundException("Order with id ${id.value} not found")

    override fun save(order: Order) {
        orders[order.id] = order
    }
}

So the dependency direction stays classic.

The domain knows the abstraction.

The adapter knows the implementation.

The use case gets the repository through the constructor and the execution context through context parameters.

Why not Service Locator?

Because Service Locator removes dependencies from the signature.

fun confirm() {
    val clock = ServiceLocator.get<ClockProvider>()
    val events = ServiceLocator.get<DomainEvents>()
    val user = ServiceLocator.get<UserContext>()

    // ...
}

At first glance, the method looks cleaner.

But that cleanliness is borrowed.

Looking at confirm(), we no longer know what the method needs. We have to open the body. And if something is missing from the locator, we often find out at runtime.

With context parameters, the dependency is still part of the contract:

context(clock: ClockProvider, events: DomainEvents, user: UserContext)
fun confirm()

The reader sees the requirements.

The compiler checks them.

Test without a container

In tests I do not need Spring or a DI container.

I have a fake clock:

class TestingClockProvider(
    private var currentInstant: Instant,
) : ClockProvider {

    override fun now(): Instant =
        currentInstant

    fun setNow(value: Instant) {
        currentInstant = value
    }
}

And a Given-When-Then aggregate test:

@Test
fun `should confirm draft order by owner`() {
    // given
    val order =
        Order.fromSnapshot(
            anOrder()
                .withId("ORD-123")
                .ownedBy("user-123")
                .build(),
        )

    // and
    currentUserIs("user-123")

    // and
    currentTimeIs("2026-06-05T10:15:30Z")

    // when
    context(clock, domainEvents, currentUser) {
        order.confirm()
    }

    // then
    expectThat(order.toSnapshot())
        .isConfirmed()
        .wasConfirmedAt("2026-06-05T10:15:30Z")

    // and
    expectThat(domainEvents)
        .hasPublishedOrderConfirmed(
            orderId = "ORD-123",
            confirmedAt = "2026-06-05T10:15:30Z",
        )
}

This is still a normal Given-When-Then test.

The test context is explicit:

context(clock, domainEvents, currentUser) {
    order.confirm()
}

But the domain operation itself does not have a noisy parameter list.

Where would I use it?

For things that are execution context:

context(clock: ClockProvider)
fun Order.isExpired(): Boolean

context(user: UserContext)
fun Document.canBeEdited(): Boolean

context(tx: Transaction)
fun OrderRepository.save(order: Order)

context(events: DomainEvents)
fun Order.markAsPaid()

These are not the main input data.

They are also not always stable object dependencies.

They are the environment in which a piece of logic makes sense.

Where would I not use it?

I would not put half of the application into context(...).

☹️ Sad code:

context(
    user: UserContext,
    tenant: TenantContext,
    clock: ClockProvider,
    events: DomainEvents,
    logger: Logger,
    paymentGateway: PaymentGateway,
    orderRepository: OrderRepository,
    invoiceClient: InvoiceClient,
    emailSender: EmailSender,
)
fun confirmOrder(orderId: OrderId) {
    // ...
}

This is not execution context.

This is a DI container written with different syntax.

I also would not put normal input data there:

context(orderId: OrderId)
fun confirmOrder()

orderId is an operation argument.

Not context.

This is clearer:

fun confirmOrder(orderId: OrderId)

Not everything has to use the new syntax.

Watch out for overly generic types

Context is resolved by types, so I would be careful with primitives and generic types.

☹️ Sad code:

context(id: String)
fun loadSomething() {
    // ...
}

Which string?

User id?

Tenant id?

Correlation id?

A small type is better:

@JvmInline
value class UserId(val value: String)

@JvmInline
value class TenantId(val value: String)

data class TenantContext(
    val tenantId: TenantId,
)

Good types matter even more with context parameters, because the compiler uses them to find the required context.

Summary

context parameters are not a replacement for DI.

They do not create objects.

They do not manage lifecycles.

They do not replace constructors.

The split that works best for me is:

constructor injection -> stable object dependencies
normal parameters     -> operation input
context parameters    -> execution context

In a small domain fragment, this can clean up the code nicely.

Not because parameters magically disappear.

Because we name their role better.

Example repository: kotlin-context-parameters-ddd

Technical sources:

• Context parameters - Kotlin Documentation
• What’s new in Kotlin 2.4.0

czy Kotlin dostał kolejny sposób na dependency injection?

Po kilku próbach patrzę na to inaczej.

context parameters nie tworzą obiektów. Nie zarządzają cyklem życia zależności. Nie zastępują Springa, Koina ani Daggera.

One opisują coś prostszego:

ta funkcja może wykonać się tylko wtedy, gdy w miejscu wywołania istnieje wymagany kontekst.

I ten warunek jest sprawdzany przez kompilator.

To jest dla mnie najważniejsze zdanie w całym temacie. Nie runtime. Nie magiczny provider. Nie globalny singleton. Kompilator.

Najprostszy przykład

Weźmy zegar.

interface ClockProvider {
    fun now(): Instant
}

Jeśli funkcja potrzebuje aktualnego czasu, zwykle mamy trzy opcje.

Możemy przekazać zegar jako zwykły parametr:

fun confirmedAt(clock: ClockProvider): Instant =
    clock.now()

Możemy trzymać go w konstruktorze jak klasyczne dependency injection:

class OrderService(
    private val clock: ClockProvider,
) {
    fun confirmedAt(): Instant =
        clock.now()
}

Albo możemy powiedzieć, że zegar jest kontekstem wykonania tej funkcji:

context(clock: ClockProvider)
fun confirmedAt(): Instant =
    clock.now()

Wywołanie:

val clock = FixedClockProvider(
    Instant.parse("2026-06-05T10:15:30Z"),
)

context(clock) {
    confirmedAt()
}

Bez context(clock) ta funkcja nie powinna się skompilować.

I to jest różnica względem service locatora. Zależność nadal jest widoczna w sygnaturze funkcji, ale nie przepychamy jej jako zwykłego argumentu przez każde wywołanie.

Parametr, konstruktor czy context?

Nie traktowałbym context parameters jako nowej domyślnej odpowiedzi na wszystko.

Dla mnie podział jest mniej więcej taki:

zwykłe parametry      -> dane wejściowe operacji
constructor injection -> stałe zależności obiektu
context parameters    -> kontekst wykonania

orderId, amount, email, newAddress — to są normalne parametry.

OrderRepository, PaymentGateway, HttpClient — często pasują do konstruktora use case’a albo serwisu.

ClockProvider, UserContext, DomainEvents, Transaction, TenantContext, CorrelationId — to są dobrzy kandydaci na kontekst wykonania.

Oczywiście nie zawsze. Ale ta granica jest dla mnie dużo zdrowsza niż myślenie: „super, teraz wszystko wrzucamy w context(...)”.

Przykład z repo

Do artykułu zrobiłem małe repo z przykładem DDD / hexagonal:

src/main/kotlin/io/github/camilyed/contextparameters
├── domain
├── application
└── adapter

Nie ma tutaj Springa. Celowo.

Chciałem, żeby przykład pokazywał samą składnię i decyzję projektową, a nie integrację z frameworkiem.

Domena ma jeden agregat: Order.

Zamówienie może być szkicem albo może być potwierdzone:

sealed interface OrderState {

    data object Draft : OrderState

    data class Confirmed(
        val confirmedAt: Instant,
    ) : OrderState
}

Snapshot agregatu jest prosty:

data class OrderSnapshot(
    val id: OrderId,
    val ownerId: UserId,
    val state: OrderState,
)

I teraz sama reguła.

Zamówienie można potwierdzić tylko wtedy, gdy:

• jest jeszcze szkicem,
• aktualny użytkownik jest właścicielem albo może potwierdzać zamówienia,
• zapisujemy czas potwierdzenia,
• publikujemy event domenowy.

W agregacie wygląda to tak:

class Order private constructor(
    val id: OrderId,
    val ownerId: UserId,
    private var state: OrderState,
) {
    context(clock: ClockProvider, events: DomainEvents, user: UserContext)
    fun confirm() {
        require(state == OrderState.Draft) {
            "Only draft order can be confirmed"
        }

        require(user.userId == ownerId || user.canConfirmOrders) {
            "User cannot confirm this order"
        }

        val now = clock.now()

        state = OrderState.Confirmed(
            confirmedAt = now,
        )

        events.publish(
            OrderConfirmed(
                orderId = id,
                confirmedAt = now,
            ),
        )
    }
}

To jest zwykła metoda domenowa.

Ale jej sygnatura mówi coś ważnego:

context(clock: ClockProvider, events: DomainEvents, user: UserContext)
fun confirm()

Czyli:

potrafię potwierdzić zamówienie, ale tylko w kontekście zegara, eventów domenowych i aktualnego użytkownika.

Nie chcę trzymać ClockProvider w konstruktorze encji. Zegar nie opisuje zamówienia.

Nie chcę też chować użytkownika w globalnym CurrentUserProvider.

Ta operacja po prostu działa w konkretnym kontekście.

Warstwa aplikacji

W use case dochodzi jeszcze transakcja.

I tutaj przykład robi się ciekawszy, bo widać podział odpowiedzialności:

package io.github.camilyed.contextparameters.application

import io.github.camilyed.contextparameters.domain.ClockProvider
import io.github.camilyed.contextparameters.domain.DomainEvents
import io.github.camilyed.contextparameters.domain.OrderRepository
import io.github.camilyed.contextparameters.domain.OrderSnapshot
import io.github.camilyed.contextparameters.domain.Transaction
import io.github.camilyed.contextparameters.domain.UserContext

class ConfirmOrderUseCase(
    private val orderRepository: OrderRepository,
) {
    context(
        clock: ClockProvider,
        events: DomainEvents,
        user: UserContext,
        transaction: Transaction,
    )
    fun confirm(command: ConfirmOrderCommand): OrderSnapshot =
        transaction.within {
            val order = orderRepository.findById(command.orderId)

            order.confirm()

            orderRepository.save(order)

            order.toSnapshot()
        }
}

orderRepository jest w konstruktorze, bo to stała zależność use case’a.

command jest zwykłym parametrem, bo to dane wejściowe operacji.

clock, events, user i transaction są w context(...), bo opisują otoczenie, w którym wykonuje się operacja.

Ten podział jest dla mnie najczytelniejszy.

A gdzie adaptery?

Interfejsy są w domenie:

interface OrderRepository {
    fun findById(id: OrderId): Order
    fun save(order: Order)
}

Adapter daje implementację:

class InMemoryOrderRepository : OrderRepository {

    private val orders = mutableMapOf<OrderId, Order>()

    override fun findById(id: OrderId): Order =
        orders[id]
            ?: throw OrderNotFoundException("Order with id ${id.value} not found")

    override fun save(order: Order) {
        orders[order.id] = order
    }
}

Czyli klasyczny kierunek zależności zostaje zachowany.

Domena zna abstrakcję.

Adapter zna implementację.

Use case dostaje repozytorium przez konstruktor, a kontekst wykonania przez context parameters.

Dlaczego nie Service Locator?

Bo Service Locator usuwa zależności z sygnatury.

fun confirm() {
    val clock = ServiceLocator.get<ClockProvider>()
    val events = ServiceLocator.get<DomainEvents>()
    val user = ServiceLocator.get<UserContext>()

    // ...
}

Na pierwszy rzut oka metoda wygląda czyściej.

Ale to jest czystość na kredyt.

Czytając sygnaturę confirm(), nie wiemy już, czego ta metoda potrzebuje. Trzeba wejść do środka. A jeśli czegoś zabraknie w locatorze, często dowiemy się o tym dopiero w runtime.

Przy context parameters zależność nadal jest częścią kontraktu:

context(clock: ClockProvider, events: DomainEvents, user: UserContext)
fun confirm()

Czytelnik widzi wymagania.

Kompilator ich pilnuje.

Test bez kontenera

W testach nie potrzebuję Springa ani kontenera DI.

Mam fake zegara:

class TestingClockProvider(
    private var currentInstant: Instant,
) : ClockProvider {

    override fun now(): Instant =
        currentInstant

    fun setNow(value: Instant) {
        currentInstant = value
    }
}

I test zachowania agregatu:

@Test
fun `should confirm draft order by owner`() {
    // given
    val order =
        Order.fromSnapshot(
            anOrder()
                .withId("ORD-123")
                .ownedBy("user-123")
                .build(),
        )

    // and
    currentUserIs("user-123")

    // and
    currentTimeIs("2026-06-05T10:15:30Z")

    // when
    context(clock, domainEvents, currentUser) {
        order.confirm()
    }

    // then
    expectThat(order.toSnapshot())
        .isConfirmed()
        .wasConfirmedAt("2026-06-05T10:15:30Z")

    // and
    expectThat(domainEvents)
        .hasPublishedOrderConfirmed(
            orderId = "ORD-123",
            confirmedAt = "2026-06-05T10:15:30Z",
        )
}

To jest nadal zwykły test Given-When-Then.

Kontekst testu jest jawny:

context(clock, domainEvents, currentUser) {
    order.confirm()
}

Ale sama operacja domenowa nie ma sztucznej listy parametrów.

Kiedy bym tego użył?

Przy rzeczach, które są kontekstem wykonania:

context(clock: ClockProvider)
fun Order.isExpired(): Boolean

context(user: UserContext)
fun Document.canBeEdited(): Boolean

context(tx: Transaction)
fun OrderRepository.save(order: Order)

context(events: DomainEvents)
fun Order.markAsPaid()

To nie są główne dane wejściowe.

To nie są też zawsze stałe zależności obiektu.

To jest otoczenie, w którym dana logika ma sens.

Kiedy bym tego nie użył?

Nie wrzucałbym do context(...) połowy aplikacji.

☹️ Smutny kodzik:

context(
    user: UserContext,
    tenant: TenantContext,
    clock: ClockProvider,
    events: DomainEvents,
    logger: Logger,
    paymentGateway: PaymentGateway,
    orderRepository: OrderRepository,
    invoiceClient: InvoiceClient,
    emailSender: EmailSender,
)
fun confirmOrder(orderId: OrderId) {
    // ...
}

To nie jest kontekst wykonania.

To jest kontener DI zapisany inną składnią.

Nie dawałbym tam też zwykłych danych wejściowych:

context(orderId: OrderId)
fun confirmOrder()

orderId jest argumentem operacji.

Nie kontekstem.

Czytelniej:

fun confirmOrder(orderId: OrderId)

Nie wszystko musi używać nowej składni.

Uwaga na zbyt ogólne typy

Context jest rozwiązywany po typach, więc warto uważać na prymitywy i zbyt ogólne typy.

☹️ Smutny kodzik:

context(id: String)
fun loadSomething() {
    // ...
}

Jaki string?

Id użytkownika?

Id tenanta?

Correlation id?

Lepiej użyć małych typów:

@JvmInline
value class UserId(val value: String)

@JvmInline
value class TenantId(val value: String)

data class TenantContext(
    val tenantId: TenantId,
)

Przy context parameters dobre typy są jeszcze ważniejsze, bo to po nich kompilator rozpoznaje, czego szuka.

Podsumowanie

context parameters nie są zamiennikiem DI.

Nie tworzą obiektów.

Nie zarządzają cyklem życia.

Nie zastępują konstruktora.

Najprostszy podział, który mi się sprawdza:

constructor injection -> stałe zależności obiektu
zwykłe parametry      -> dane wejściowe operacji
context parameters    -> kontekst wykonania

W małym fragmencie domeny to potrafi fajnie oczyścić kod.

Nie dlatego, że parametry magicznie znikają.

Tylko dlatego, że lepiej nazywamy ich rolę.

Przykładowe repo: kotlin-context-parameters-ddd

Źródła techniczne:

• Context parameters - Kotlin Documentation
• What’s new in Kotlin 2.4.0

Today we will talk about trust in our tests. Because the worst kind of test is one that gives you a sense of safety, even though the code underneath does something completely different from what the test suggests.

1. The trap of testing implementation (White Box)

I have noticed that in many projects Mockito is added to tests “automatically”. We generate a test class, mock all dependencies, and done. Few people ask themselves then: why am I actually using this mock?

Imagine a simple service for updating user data.

☹️ Sad code:

@Test
void shouldUpdateUserName() {
    // given
    var userId = 1L;
    var user = new User(userId, "Jan");

    // We have to "feed" the mock so the test can even start
    when(userRepository.findById(userId)).thenReturn(Optional.of(user));

    // when
    userService.updateName(userId, "Jan Kowalski");

    // then
    // We only check a technical method call.
    // Do we know whether the name was actually changed in the object before saving?
    // This test will say "YES" even if the service sends old data to save().
    verify(userRepository).save(any(User.class));
}

This test lies to you. It only checks whether the save method was called. If a developer mixes up fields and assigns the new value to a completely different field in production code, or skips the assignment entirely, this test will still be green. Instead of testing business behavior, which is changing the name, you test a technical library call.

Okay, but someone may notice that we can still verify the object state and try to use ArgumentCaptor for update logic.

☹️ Even sadder code:

@Test
void shouldUpdateUserName_CaptorVersion() {
    // given
    var userId = 1L;
    var existingUser = new User(userId, "Jan");
    var userCaptor = ArgumentCaptor.forClass(User.class);

    when(userRepository.findById(userId)).thenReturn(Optional.of(existingUser));

    // when
    userService.updateName(userId, "Jan Kowalski");

    // then
    // This is where the trouble begins. We expose implementation details.
    verify(userRepository).save(userCaptor.capture());
    var savedUser = userCaptor.getValue();

    assertThat(savedUser.getName()).isEqualTo("Jan Kowalski");
}

So, success? Not exactly. We have just entered White Box Testing mode. Tests become fragile (Fragile tests) because:

• Refactoring becomes painful: change save() to saveAll() and the test blows up, even though the business logic still works.
• You test “how”, not “what”: you care whether a specific line of code was called, not what the result is for the user.
• Sonar lies: reports show line coverage, but you did not test those lines — you only executed them in an artificial environment.

Solution: In-Memory implementation

Instead of fighting Mockito, let’s treat the service as a black box. We need something that pretends to be a database but works in memory. A ConcurrentHashMap under the repository is the simplest approach.

public class InMemoryUserRepository implements UserRepository {
    private final Map<Long, User> db = new ConcurrentHashMap<>();

    @Override
    public User save(User user) {
        db.put(user.getId(), user);
        return user;
    }

    @Override
    public Optional<User> findById(Long id) {
        return Optional.ofNullable(db.get(id));
    }

    public void clear() {
        db.clear();
    }
}

A state-based test could look like this. Now the test does not need any verify. We simply execute the action and check whether the state in the “database” is correct.

class UserServiceTest {
    private final InMemoryUserRepository userRepository = new InMemoryUserRepository();
    private final UserService userService = new UserService(userRepository);

    @BeforeEach
    void setup() {
        userRepository.clear();
    }

    @Test
    void shouldUpdateUserName() {
        // given
        userRepository.save(new User(1L, "Jan"));

        // when
        userService.updateName(1L, "Jan Kowalski");

        // then
        var updatedUser = userRepository.findById(1L).orElseThrow();
        assertThat(updatedUser.getName()).isEqualTo("Jan Kowalski");
    }
}

What about DSL?

Remember the first part? We can use those patterns to prepare the initial state even more cleanly. Instead of manually calling userRepository.save() in the given section, we will use our “ability”.

Happy code:

@Test
void shouldUpdateUserName() {
    // given
    thereIsAUser(anUser().withId(1L).withName("Jan").build());

    // when
    userService.updateName(1L, "Jan Kowalski");

    // then
    var updatedUser = userRepository.findById(1L).orElseThrow();
    assertThat(updatedUser.getName()).isEqualTo("Jan Kowalski");
}

Is this still White Box? Someone might say: “Wait, but in the assertion you call the repository!”. No. The difference is fundamental:

• In Mockito (Interaction): You ask, “Did you call the save method?”. If a developer changes the way the save works, the test fails.
• In-Memory (State): You ask, “System, no matter how you did it, does this user have a new name?”.

In the Black Box approach, we treat the Service + InMemoryRepo pair as one black box. We do not care how many times the service “talked” to the repository. We care about the final effect.

How it could look in the end

You may wonder: where does Ability get the repository from and is it definitely the same instance that the service uses? This is the key point. For this to work, we need one source of truth.

The best way is to use interfaces with default methods.

public interface UserAbility {
    UserRepository userRepository(); // Provider method

    default void thereIsAUser(UserBuilder user) {
        userRepository().save(user);
    }
}

// builder in another package, for example com.ourdomain.testing.dsl.builders

public class UserBuilder {
    private Long id = 1L; // Default ID
    private String name = "Jan"; // Default name
    // ... other fields

    public static UserBuilder anUser() {
        return new UserBuilder();
    }

    public UserBuilder withId(Long id) {
        this.id = id;
        return this;
    }

    public UserBuilder withName(String name) {
        this.name = name;
        return this;
    }

    public User build() {
        return new User(id, name);
    }
}

Let’s create a base class for unit tests to hide technical implementation details of our DSL.

public abstract class BaseUnitTest implements UserAbility {
    // One shared instance for the service, assertions, and all Abilities
    protected final InMemoryUserRepository userRepository = new InMemoryUserRepository();

    @Override
    public UserRepository userRepository() {
        return userRepository;
    }

    @BeforeEach
    void clearDatabase() {
        userRepository.clear(); // Important for isolating tests: clean in-memory database state before each test
    }
}

Thanks to this, your test class simply extends BaseUnitTest and can use our In-Memory implementation. Here is what the final test class looks like. Notice how little technical noise is left. We focus only on business behavior.

class UserServiceTest extends BaseUnitTest {

    // We inject the same repository that lives in BaseUnitTest
    private final UserService userService = new UserService(userRepository);

    @Test
    void shouldUpdateUserName() {
        // given
        thereIsAUser(anUser().withId(1L).withName("Jan"));

        // when
        userService.updateName(1L, "Jan Kowalski");

        // then
        var updatedUser = userRepository.findById(1L).orElseThrow();
        assertThat(updatedUser.getName()).isEqualTo("Jan Kowalski");
    }
}

Summary

By combining In-Memory, Ability and a Base Class, our BaseUnitTest, we stop fighting the tools and start supporting the process of delivering value. We managed to achieve three key goals:

• Isolation: Thanks to @BeforeEach in the base class, each test starts with an empty database. This eliminates errors caused by data leaking between tests, which is a nightmare in large test suites.
• One source of truth: thereIsAUser (Given), userService.updateName (When), and the assertion (Then) all operate on the same InMemoryUserRepository instance. You do not have to configure anything manually — what you save in Given is physically available in When and verifiable in Then.
• Easier debugging: You will feel the biggest difference when a test… fails. In the Mockito world, you often end up with an enigmatic “Wanted but not invoked” message. Here, instead of debugging the depths of the framework, you simply put a breakpoint in the updateName method and step into it.

What is next?

We now have unit tests that run fast and do not lie. In the next part, we will deal with integration tests.

You will learn:

• How not to fall into the trap of unnecessarily reloading the Spring context and why the @DirtiesContext annotation is probably your enemy rather than your friend.
• Why @SpyBean is an invitation to trouble and how to avoid it.
• How to make Testcontainers work so that integration tests are almost as pleasant and stable as today’s unit tests.

Dziś pogadamy o zaufaniu do naszych testów. Bo najgorszy rodzaj testu to taki, który daje Ci poczucie bezpieczeństwa, mimo że Twój kod pod spodem robi zupełnie coś innego, na co by wskazywał sam test.

1. Pułapka testowania implementacji (White Box)

Zauważyłem, że w wielu projektach Mockito dodaje się do testów “z automatu”. Generujemy klasę testową, mockujemy wszystkie zależności i cyk – robota zrobiona. Mało kto zadaje sobie wtedy pytanie: po co ja właściwie tego mocka używam?

Wyobraź sobie prosty serwis do aktualizacji danych użytkownika.

☹️ Smutny kodzik:

@Test
void shouldUpdateUserName() {
    // given
    var userId = 1L;
    var user = new User(userId, "Jan");
    // Musimy "nakarmić" mocka, żeby test w ogóle ruszył
    when(userRepository.findById(userId)).thenReturn(Optional.of(user));

    // when
    userService.updateName(userId, "Jan Kowalski");

    // then
    // Sprawdzamy tylko techniczne wywołanie metody. 
    // Czy wiemy, czy imię faktycznie zostało zmienione w obiekcie przed zapisem? 
    // Ten test powie "TAK", nawet jeśli serwis wyśle do save() stare dane.
    verify(userRepository).save(any(User.class));
}

Ten test Cię oszukuje. Sprawdza tylko, czy zawołano metodę save. Jeśli programista pomyli pola i w kodzie produkcyjnym przypisze nową wartość do zupełnie innego pola (albo w ogóle pominie przypisanie), ten test nadal przejdzie na zielono! Zamiast testować zachowanie biznesowe (zmiana imienia), testujesz techniczne wywołanie biblioteki.

No dobra, ale ktoś zauważy, że możemy jednak zweryfikować stan obiektu i spróbuje użyć ArgumentCaptor przy logice aktualizacji danych (update).

☹️ Jeszcze bardziej smutny kodzik:

@Test
void shouldUpdateUserName_CaptorVersion() {
    // given
    var userId = 1L;
    var existingUser = new User(userId, "Jan");
    var userCaptor = ArgumentCaptor.forClass(User.class);

    when(userRepository.findById(userId)).thenReturn(Optional.of(existingUser));

    // when
    userService.updateName(userId, "Jan Kowalski");

    // then
    // Tutaj zaczynają się schody. Odsłaniamy szczegóły implementacji.
    verify(userRepository).save(userCaptor.capture());
    var savedUser = userCaptor.getValue();

    assertThat(savedUser.getName()).isEqualTo("Jan Kowalski");
}

I co? Sukces? No nie do końca. Właśnie weszliśmy w tryb White Box Testing. Testy stają się kruche (Fragile tests), bo:

• Refaktoryzacja to ból: Zmieniasz save() na saveAll()? Test wybucha, mimo że logika biznesowa działa.
• Testujesz “jak”, a nie “co”: Obchodzi Cię, czy wywołałeś konkretną linię kodu, a nie jaki jest wynik dla użytkownika.
• Sonar kłamie: Raporty pokazują pokrycie linii, ale Ty ich nie przetestowałeś – Ty je tylko wywołałeś w sztucznym środowisku.

Rozwiązanie: Implementacja In-Memory

Zamiast walczyć z Mockito, potraktujmy serwis jako czarną skrzynkę. Potrzebujemy czegoś, co udaje bazę danych, ale działa w pamięci. ConcurrentHashMap pod spodem repozytorium to najprostszy sposób.

public class InMemoryUserRepository implements UserRepository {
    private final Map<Long, User> db = new ConcurrentHashMap<>();

    @Override
    public User save(User user) {
        db.put(user.getId(), user);
        return user;
    }

    @Override
    public Optional<User> findById(Long id) {
        return Optional.ofNullable(db.get(id));
    }

    public void clear() {
        db.clear();
    }
}

Tak mógłby wyglądać wtedy test oparty na stanie State-based. Teraz nasz test nie potrzebuje żadnych verify. Po prostu wywołujemy akcję i sprawdzamy, czy stan w “bazie” się zgadza.

class UserServiceTest {
    private final InMemoryUserRepository userRepository = new InMemoryUserRepository();
    private final UserService userService = new UserService(userRepository);

    @BeforeEach
    void setup() {
        userRepository.clear();
    }

    @Test
    void shouldUpdateUserName() {
        // given
        userRepository.save(new User(1L, "Jan"));

        // when
        userService.updateName(1L, "Jan Kowalski");

        // then
        var updatedUser = userRepository.findById(1L).orElseThrow();
        assertThat(updatedUser.getName()).isEqualTo("Jan Kowalski");
    }
}

A co z DSL?

Pamiętasz pierwszą część? Możemy użyć tamtych wzorców, aby przygotować stan początkowy jeszcze czyściej. Zamiast ręcznie wywoływać userRepository.save() w sekcji given, użyjemy naszej “zdolności” (Ability).

🙂 Uśmiechnięty kodzik:

@Test
void shouldUpdateUserName() {
    // given
    thereIsAUser(anUser().withId(1L).withName("Jan").build());

    // when
    userService.updateName(1L, "Jan Kowalski");

    // then
    var updatedUser = userRepository.findById(1L).orElseThrow();
    assertThat(updatedUser.getName()).isEqualTo("Jan Kowalski");
}

Czy to nadal White Box? Ktoś powie: “Zaraz, ale w asercji wywołujesz repozytorium!”. Nie. Różnica jest fundamentalna:

• W Mockito (Interakcja): Pytasz: “Czy zawołałeś metodę save?”. Jeśli programista zmieni sposób zapisu, test padnie.
• W In-Memory (Stan): Pytasz: “Systemie, nieważne jak to zrobiłeś, czy ten użytkownik ma nowe imię?”.

W podejściu Black Box traktujemy parę Service + InMemoryRepo jako jedną czarną skrzynkę. Nie obchodzi nas, ile razy serwis “gadał” z repozytorium. Obchodzi nas efekt końcowy.

Jak to mogło by wyglądać ostatecznie

Możesz się zastanawiać: Skąd Ability bierze repozytorium i czy to na pewno ta sama instancja, której używa serwis? To kluczowy punkt. Żeby to działało, musimy mieć jedno źródło prawdy.

Najlepszym sposobem jest użycie interfejsów z domyślnymi implementacjami (default methods).

public interface UserAbility {
    UserRepository userRepository(); // Metoda "dostawca"

    default void thereIsAUser(UserBuilder user) {
        userRepository().save(user);
    }
}

// builder w innym pakiece np. com.ourdomain.testing.dsl.builders

public class UserBuilder {
    private Long id = 1L; // Domyślne ID
    private String name = "Jan"; // Domyślne imię
    // ... inne pola

    public static UserBuilder anUser() {
        return new UserBuilder();
    }

    public UserBuilder withId(Long id) {
        this.id = id;
        return this;
    }

    public UserBuilder withName(String name) {
        this.name = name;
        return this;
    }

    public User build() {
        return new User(id, name);
    }
}

Stwórzmy sobie klasę bazową dla testów unitowych, aby ukryć detale technicznej implementacji naszego DSL.

public abstract class BaseUnitTest implements UserAbility {
    
    // Jedna, wspólna instancja dla serwisu, asercji i wszystkich Ability
    protected final InMemoryUserRepository userRepository = new InMemoryUserRepository();

    @Override
    public UserRepository userRepository() {
        return userRepository;
    }

    @BeforeEach
    void clearDatabase() {
        userRepository.clear(); // Ważne aby izolować testy czyścimy stan bazy w pamięci przed każdym
    }
}

Dzięki temu Twoja klasa testowa po prostu dziedziczy po BaseUnitTest i ma już możliwość skorzystania z naszej implementacji In-Memory.Oto jak wygląda ostateczny kod Twojej klasy testowej. Zauważ, jak mało “szumu technicznego” tu zostało. Skupiamy się wyłącznie na zachowaniu biznesowym.

class UserServiceTest extends BaseUnitTest {

    // Wstrzykujemy to samo repozytorium, które siedzi w BaseUnitTest
    private final UserService userService = new UserService(userRepository);

    @Test
    void shouldUpdateUserName() {
        // given 
        thereIsAUser(anUser().withId(1L).withName("Jan"));

        // when
        userService.updateName(1L, "Jan Kowalski");

        // then
        var updatedUser = userRepository.findById(1L).orElseThrow();
        assertThat(updatedUser.getName()).isEqualTo("Jan Kowalski");
    }
}

Podsumowanie

Stosując połączenie In-Memory, Ability oraz Base Class (nasza klasa BaseUnitTest), przestajemy walczyć z narzędziami, a zaczynamy wspierać proces dostarczania wartości. Udało nam się osiągnąć trzy kluczowe cele:

• Izolacja: Dzięki @BeforeEach w klasie bazowej każdy test startuje z pustą bazą. Eliminuje to błędy wynikające z wyciekania danych między testami, co jest zmorą dużych zestawów testowych.
• Jedno źródło prawdy: Zarówno thereIsAUser (Given), userService.updateName (When), jak i asercja (Then) operują na tej samej instancji InMemoryUserRepository. Nie musisz niczego konfigurować ręcznie – to, co zapiszesz w Given, jest fizycznie dostępne w When i weryfikowalne w Then.
• Łatwiejszy debug: Największą różnicę odczujesz, gdy test… nie przejdzie. W świecie Mockito często kończysz z enigmatycznym komunikatem Wanted but not invoked. Tutaj, zamiast debugować czeluści frameworka, po prostu stawiasz breakpoint w metodzie updateName i robisz Step Into.

Co dalej?

Mamy już unity, które działają błyskawicznie i nie kłamią. W kolejnej części zajmiemy się testami integracyjnymi.

Dowiesz się:

• Jak nie wpaść w pułapkę przeładowywania niepotrzebnie kontekstu Springa i dlaczego adnotacja @DirtiesContext to jednak raczej Twój wróg niż przyjaciel.
• Dlaczego @SpyBean to zaproszenie do kłopotów i jak go unikać.
• Jak zaprząc Testcontainers do pracy tak, aby testy integracyjne były niemal tak przyjemne i stabilne, jak nasze dzisiejsze unity.

Readability

Let’s start with the basics. If a test does not clearly communicate what is being tested and why it failed, then all the technology around it becomes unnecessary weight. Many times, while reviewing tests during code review, I really have to make an effort to understand what they are actually testing, without trusting the test name too much.

1. Given-When-Then structure

Let’s look at the first example. It is not complex at all, but already at the start it makes us work harder to extract what is the test input, what behavior we are testing, and what assertion we check at the end.

☹️ Sad code:

@Test
void updateTest() {
    User user = new User("Jan", "Active");
    repository.save(user);
    user.changeStatus("Inactive");
    service.update(user);
    User updated = repository.findById(user.getId());
    assertEquals("Inactive", updated.getStatus());
}

Simple code separators, for example comments, make it much easier at first glance to understand where we create the input setup — // given, what we test — // when, and what we verify — // then.

🙂

@Test
void shouldChangeUserStatusToInactive() {
    // given
    var user = new User("Jan", "Active");
    repository.save(user);

    // when
    user.changeStatus("Inactive");
    service.update(user);

    // then
    var updated = repository.findById(user.getId());
    assertThat(updated.getStatus()).isEqualTo("Inactive");
}

As our tests become more realistic, the data preparation and assertion sections can grow. Instead of creating one huge block of code under // given, it is worth using the helper word // and. It lets us logically group operations, for example separate creating a user from setting permissions or preparing database state.

Let’s look at a slightly more complex example:

☹️ Sad code:

@Test
void complexUpdateTest() {
    User user = new User("Jan", "Active");
    user.setAddress(new Address("Warszawa", "Złota 44"));
    user.setRole("ADMIN");
    repository.save(user);
    AuditLog log = new AuditLog("INITIAL_CREATION", user.getId());
    auditRepository.save(log);
    user.changeStatus("Inactive");
    user.setDeactivationReason("User requested");
    service.update(user);
    User updated = repository.findById(user.getId());
    assertEquals("Inactive", updated.getStatus());
    assertEquals("User requested", updated.getDeactivationReason());
    assertNotNull(auditRepository.findByUserIdAndType(user.getId(), "STATUS_CHANGE"));
}

Even in such a small test, we start squinting to understand what is background and what is the actual action. Using the and structure significantly improves readability:

🙂

@Test
void shouldDeactivateAdminUserAndLogEvent() {
    // given
    var user = new User("Jan", "Active");
    user.setRole("ADMIN");
    repository.save(user);
    // and
    var initialLog = new AuditLog("INITIAL_CREATION", user.getId());
    auditRepository.save(initialLog);

    // when
    user.deactivate("User requested");
    service.update(user);

    // then
    var updated = repository.findById(user.getId());
    assertThat(updated.getStatus()).isEqualTo("Inactive");
    assertThat(updated.getDeactivationReason()).isEqualTo("User requested");
    // and
    var statusLog = auditRepository.findByUserIdAndType(user.getId(), "STATUS_CHANGE");
    assertThat(statusLog).isNotNull();
}

Is that it?

Even though the code above looks much better than a wall of text, there is still a lot of technical noise here: manually setting fields, setters, and technical assertions one after another.

In the next sections, we will see how patterns such as Test Data Builder and Custom Assertions can make the same test look almost like sentences in natural language.

2. Test Data Builder

Let’s return to the “sad code” from the section above. Why does it actually hurt to look at it? Because every time we want to create a user, we have to call a constructor with all fields or a set of setters. This creates a lot of information noise. Not all data set in the constructor has any impact on the assertion result. What is more, if the constructor is extended with one more argument, our tests require changes everywhere that constructor is called. This is when we deal with fragile tests.

The solution to this situation is the Test Data Builder pattern described by Nat Pryce. The idea is to create a helper class that has reasonable default values for all fields. In the test itself, we override only the parameters that are important for a given scenario.

Before we move to the Builder implementation, let’s see what the // given section looks like when our domain becomes richer. Let’s assume that in order to save a user in the database, we must satisfy several technical requirements: address, contact details, dates, permissions.

In a deactivation test, these details are only background, but in the code they take the foreground:

☹️ Sad code:

@Test
void shouldDeactivateAdminUserAndLogEvent() {
    // given
    var address = new Address("Warszawa", "Złota 44", "00-123", "Polska");
    var user = new User("Jan", "Kowalski", "jan.k@example.com", "Active");
    user.setAddress(address);
    user.setRole("ADMIN");
    user.setCreatedAt(LocalDateTime.now());
    user.setLastLogin(LocalDateTime.now().minusDays(1));
    repository.save(user);

    // and - preparing technical logs that must exist in the system
    var initialLog = new AuditLog("INITIAL_CREATION", user.getId(), LocalDateTime.now(), "SYSTEM");
    auditRepository.save(initialLog);

    // when
    user.deactivate("User requested");
    service.update(user);

    // then - we only verify the status field
    var updated = repository.findById(user.getId());
    assertThat(updated.getStatus()).isEqualTo("Inactive");
}

We have as many as 8 lines of code only to prepare the object for the test. Does any of these parameters affect whether the administrator is correctly deactivated? Of course not. Since these technical details are irrelevant from the point of view of the deactivation business logic, they should be hidden.

This is exactly where Test Data Builder helps. It allows us to define reasonable default values for all required fields in one place. What is more, we can go one step further and compose builders. If our User has an Address, and the address does not matter in a given test, the user builder simply uses the default address builder.

Let’s look at the implementation:

public class UserBuilder {
    private String name = "Jan";
    private String lastName = "Kowalski";
    private String status = "Inactive";
    private String role = "USER";
    private String deactivationReason = null;
    private AddressBuilder addressBuilder = AddressBuilder.anAddress();

    private UserBuilder() {
    }

    public static UserBuilder aUser() {
        return new UserBuilder();
    }

    public UserBuilder withRole(String role) {
        this.role = role;
        return this;
    }

    public UserBuilder withStatus(String status) {
        this.status = status;
        return this;
    }

    public UserBuilder withAddress(AddressBuilder addressBuilder) {
        this.addressBuilder = addressBuilder;
        return this;
    }

    public User build() {
        User user = new User(name, lastName, status, role);
        user.setAddress(addressBuilder.build());
        user.setDeactivationReason(deactivationReason);
        return user;
    }
}

public class AddressBuilder {
    private String city = "Warszawa";
    private String street = "Złota 44";

    public static AddressBuilder anAddress() {
        return new AddressBuilder();
    }

    public AddressBuilder withCity(String city) {
        this.city = city;
        return this;
    }

    public Address build() {
        return new Address(city, street);
    }
}

What do we gain?

🙂

@Test
void shouldDeactivateAdminUserAndLogEvent() {
    // given
    var user = aUser()
            .withRole("ADMIN")
            .build();

    // rest of the code...
}

As you can see, we have hidden all irrelevant information noise in the given section, where we focus only on the user’s role, because that is what matters in this test.

3. Assertions - the most common mistakes

Now that we have perfectly prepared input data, we must make sure that the test result actually tells us something. There are two popular practices that give a false sense of safety.

3.1 Shared variables

It is very tempting to define a value once, for example a user’s name, and use it both in the // given and // then sections. This is a mistake. If you accidentally change the value at the beginning of the test, the assertion at the end will still be green, even though the system may behave incorrectly.

☹️ Sad code:

var expectedName = "Jan"; // If you change this to "Anna"...
var user = aUser().withName(expectedName).build();

// rest of the test ...

assertThat(result.getName()).isEqualTo(expectedName); 
// ...the test still passes!

To make the code above resistant to this kind of situation, it is enough to use string literals.

🙂

var user = aUser().withName("Jan").build();

// rest of the test ...

assertThat(result.getName()).isEqualTo("Jan");

3.2 DTO classes in assertions

In API tests, it is common to see a practice where the response from an endpoint is mapped to a DTO class representing the JSON response.

☹️ Sad code:

@Test
void shouldGetUserDetails() {
    // when
    ResponseEntity<UserResponse> response = restTemplate.getForEntity("/users/1", UserResponse.class);

    // then
    assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    assertThat(response.getBody().getFullName()).isEqualTo("Jan Kowalski");
}

Why do I consider this an unsafe practice? If you rename a field in the UserResponse class, for example from fullName to name, the IDE refactoring will automatically update this name in the test as well. The result is that the test still passes, but the endpoint contract is already broken. This is a common example of a False Positive test.

In integration tests, it is better to check the raw response, for example as a String or a map, or use a library such as JsonPath, which looks directly into the JSON structure.

🙂

@Test
void shouldGetUserDetailsAndValidateContract() {
    // omitted code, test setup that puts the user in the database ...

    // when
    ResponseEntity<String> response = restTemplate.getForEntity("/users/1", String.class);

    // then
    assertThat(JsonPath.read(response.getBody(), "$.fullName")).isEqualTo("Jan Kowalski");
}

4. Custom Assertion

In the // then section, I often see code that tries to verify the system state after a complex process. Instead of a clear signal, we get logic, loops, and manual data extraction.

☹️ Sad code:

// then
var logs = auditRepository.findByUserId(user.getId());

// We must check whether anything came back at all
assertNotNull(logs);
assertEquals(3, logs.size());

// We look for a specific deactivation log among many others
AuditLog deactivationLog = null;
for (AuditLog log : logs) {
    if ("USER_DEACTIVATED".equals(log.getEventName())) {
        deactivationLog = log;
    }
}

// We check details - a lot of technical assertions
assertNotNull(deactivationLog, "The deactivation log should exist!");
assertEquals("PROCESSED", deactivationLog.getStatus());
assertEquals("AUTH_SERVICE", deactivationLog.getSystemName());
assertEquals("ADMIN_123", deactivationLog.getActorId());
assertTrue(deactivationLog.getTimestamp().isAfter(LocalDateTime.now().minusMinutes(1)));

// And we also check the state of the remaining logs
logs.forEach(l -> assertEquals("SUCCESS", l.getDeliveryStatus()));