public LoanManager(MaterialRepository materials,
                   EmployeeRepository employees,
                   LoanRepository loans,
                   NoticeService notices,
                   BiblioTechProperties properties,
                   Clock clock) { ... }

class InMemoryRepository implements LoanRepository {
    private final Map<Long, Loan> data = new HashMap<>();
    private long nextId = 1;

    @Override public Loan save(Loan l) {
        if (l.getId() == null) l.assignId(nextId++);
        data.put(l.getId(), l);
        return l;
    }
    @Override public Optional<Loan> findById(Long id) {
        return Optional.ofNullable(data.get(id));
    }
    @Override public List<Loan> findByStatus(LoanStatus status) {
        return data.values().stream().filter(l -> l.getStatus() == status).toList();
    }
}

// With a MOCK: every answer has to be programmed, and there is no coherence
when(repository.save(any())).thenReturn(loan);
when(repository.findById(1L)).thenReturn(Optional.of(loan));
when(repository.countByEmployee(marta)).thenReturn(1L);
// If the code saves and then counts, the mock does NOT reflect what was saved.
// You have to maintain by hand a coherence the fake gives you for free.

// With a FAKE: you save and you count, and the right thing comes out
repository.save(loan);
assertThat(repository.countByEmployee(marta)).isEqualTo(1);

<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-core</artifactId>
    <version>5.12.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-junit-jupiter</artifactId>
    <version>5.12.0</version>
    <scope>test</scope>
</dependency>

package com.nexussoftware.bibliotech.service;

import static org.assertj.core.api.Assertions.*;
import static org.mockito.Mockito.*;

import org.junit.jupiter.api.*;
import org.mockito.*;
import org.mockito.junit.jupiter.MockitoExtension;

@ExtendWith(MockitoExtension.class)   // enables @Mock, @Spy, @Captor, @InjectMocks
class LoanManagerTest {

    @Mock private MaterialRepository materials;
    @Mock private EmployeeRepository employees;
    @Mock private LoanRepository loans;
    @Mock private NoticeService notices;

    private LoanManager manager;

    @BeforeEach
    void setUp() {
        // Explicit construction: better than @InjectMocks (section 6)
        manager = new LoanManager(materials, employees, loans, notices,
                                  testProperties(), FIXED_CLOCK);
    }
}

// Way 1: annotation (recommended, more readable)
@ExtendWith(MockitoExtension.class)
class AnnotationBasedTest {
    @Mock private MaterialRepository materials;
}

// Way 2: factory method (useful for mocks local to a single test)
class FactoryBasedTest {
    @Test
    void example() {
        MaterialRepository materials = mock(MaterialRepository.class);
        // ...
    }
}

// With a name: error messages identify it
MaterialRepository materials = mock(MaterialRepository.class, "materialRepository");

// Different default answers
NoticeService notices = mock(NoticeService.class, Answers.RETURNS_DEEP_STUBS);

// Throws if an unprogrammed method is called: forces you to be explicit
MaterialRepository strict = mock(MaterialRepository.class, Answers.RETURNS_SMART_NULLS);

@ExtendWith(MockitoExtension.class)
class LoanManagerTest {

    @Mock private MaterialRepository materials;
    @Mock private NoticeService notices;

    @InjectMocks private LoanManager manager;   // built automatically
}

@BeforeEach
void setUp() {
    manager = new LoanManager(materials, employees, loans, notices,
                              testProperties(), FIXED_CLOCK);
}

@Test
void lendingReturnsALoanDueInFifteenDays() {

    // ARRANGE: program what the collaborators return
    Material book = new Book("978-0000000001", "Effective Java", 3, "J. Bloch");
    Employee marta = new Employee("[email protected]", "Marta Ruiz");

    when(materials.findByIsbn("978-0000000001")).thenReturn(Optional.of(book));
    when(employees.findByEmail("[email protected]")).thenReturn(Optional.of(marta));
    when(loans.countByEmployeeAndStatus(marta, LoanStatus.ACTIVE)).thenReturn(0L);
    when(loans.save(any(Loan.class))).thenAnswer(inv -> inv.getArgument(0));

    // ACT
    Loan loan = manager.lend("978-0000000001", "[email protected]");

    // ASSERT
    assertThat(loan.getDueDate())
            .isEqualTo(LocalDate.of(2026, 3, 20).plusDays(15));
}

// Different values on successive calls
when(loans.count())
        .thenReturn(0L)      // 1st call
        .thenReturn(1L)      // 2nd
        .thenReturn(2L);     // 3rd and onwards

// Equivalent, shorter
when(loans.count()).thenReturn(0L, 1L, 2L);

@Test
void ifTheRepositoryFailsOnSaveNoNoticeIsSent() {

    when(materials.findByIsbn(anyString())).thenReturn(Optional.of(aBook()));
    when(employees.findByEmail(anyString())).thenReturn(Optional.of(marta()));
    when(loans.countByEmployeeAndStatus(any(), any())).thenReturn(0L);

    // The repository fails on save
    when(loans.save(any()))
            .thenThrow(new DataAccessResourceFailureException("Connection lost"));

    assertThatThrownBy(() -> manager.lend("978-0000000001", "[email protected]"))
            .isInstanceOf(DataAccessResourceFailureException.class);

    // The important bit: NOBODY was notified about a loan that was not saved
    verifyNoInteractions(notices);
}

// Concurrency exception (the optimistic locking of 11-03)
when(materials.findByIsbn(anyString()))
        .thenThrow(new OptimisticLockingFailureException("Stale version"));

// Network timeout (the MetadataClient of 09-06)
when(httpClient.send(any(), any()))
        .thenThrow(new HttpTimeoutException("The API is not responding"));

// Failure the first time, success the second: testing the retry
when(loans.save(any()))
        .thenThrow(new OptimisticLockingFailureException("conflict"))
        .thenReturn(savedLoan);

// The most common case: save returns whatever was passed to it
when(loans.save(any(Loan.class))).thenAnswer(inv -> inv.getArgument(0));

// Simulating the id assignment the database would do
when(loans.save(any(Loan.class))).thenAnswer(invocation -> {
    Loan l = invocation.getArgument(0);
    if (l.getId() == null) {
        l.assignId(nextId.getAndIncrement());
    }
    return l;
});

// An answer that depends on the argument
when(materials.findByIsbn(anyString())).thenAnswer(invocation -> {
    String isbn = invocation.getArgument(0);
    return testCatalog.containsKey(isbn)
            ? Optional.of(testCatalog.get(isbn))
            : Optional.empty();
});

// when syntax: the usual one
when(materials.findByIsbn("x")).thenReturn(Optional.empty());

// do syntax: equivalent, but the method is named at the end
doReturn(Optional.empty()).when(materials).findByIsbn("x");

// DOES NOT COMPILE: notify() returns void, there is nothing to pass to when()
when(notices.notify(marta, "message")).thenThrow(new RuntimeException());

// CORRECT
doThrow(new NoticeServiceException("SMTP down"))
        .when(notices).notify(any(Employee.class), anyString());

// And to make a void method do nothing (it is the default behaviour,
// but stating it explicitly sometimes clarifies the intent)
doNothing().when(notices).notify(any(), anyString());

List<String> list = new ArrayList<>();
List<String> spy = spy(list);

// WRONG: when() REALLY CALLS get(0) on an empty list
// -> IndexOutOfBoundsException before anything is programmed
when(spy.get(0)).thenReturn("Effective Java");

// RIGHT: do... does NOT invoke the real method
doReturn("Effective Java").when(spy).get(0);

when(materials.findByIsbn(anyString())).thenReturn(Optional.of(book));
// Later on, change the behaviour:
doReturn(Optional.empty()).when(materials).findByIsbn("978-9999999999");

org.mockito.exceptions.misusing.UnnecessaryStubbingException:
Unnecessary stubbings detected.
Clean & maintainable test code requires zero unnecessary code.
  1. -> at LoanManagerTest.setUp(LoanManagerTest.java:44)

@Test
void returningLateRecordsTheFineAndNotifiesTheEmployee() {

    Loan overdue = loanOverdueBy(10);
    when(loans.findById(1L)).thenReturn(Optional.of(overdue));

    manager.returnItem(1L);

    // The updated loan was saved
    verify(loans).save(overdue);

    // The employee was notified
    verify(notices).notify(eq(overdue.getEmployee()), contains("fine"));
}

verify(notices, times(1)).notify(any(), anyString());        // exactly 1 (the default)
verify(notices, times(3)).notify(any(), anyString());        // exactly 3
verify(notices, never()).notify(any(), anyString());         // NEVER
verify(notices, atLeastOnce()).notify(any(), anyString());   // 1 or more
verify(notices, atLeast(2)).notify(any(), anyString());      // 2 or more
verify(notices, atMost(5)).notify(any(), anyString());       // 5 or fewer
verify(notices, only()).notify(any(), anyString());          // this call AND NO OTHER

verifyNoInteractions(notices);                   // the mock was not used at all
verifyNoMoreInteractions(loans);                 // there were no calls beyond the verified ones

@Test
void aLoanReturnedOnTimeGeneratesNoNotice() {
    when(loans.findById(1L)).thenReturn(Optional.of(loanOnTime()));

    manager.returnItem(1L);

    verify(notices, never()).notify(any(), anyString());
}

@Test
void stockIsDecrementedBeforeTheLoanIsSaved() {

    InOrder order = inOrder(materials, loans, notices);

    manager.lend("978-0000000001", "[email protected]");

    order.verify(materials).findByIsbn("978-0000000001");
    order.verify(loans).save(any(Loan.class));
    order.verify(notices).notify(any(), anyString());
}

manager.find("978-0000000001");

verify(materials).findByIsbn("978-0000000001");
verifyNoMoreInteractions(materials);   // nothing else was called

// WRONG: verifying a query
verify(materials).findByIsbn("978-0000000001");
verify(loans).countByEmployeeAndStatus(marta, LoanStatus.ACTIVE);

// RIGHT: verifying a command
verify(notices).notify(marta, "Your loan of Effective Java is due in 2 days");

when(materials.findByIsbn(anyString())).thenReturn(Optional.of(book));

verify(notices).notify(any(Employee.class), contains("due"));

// argThat: arbitrary conditions
verify(loans).save(argThat(l ->
        l.getStatus() == LoanStatus.ACTIVE
        && l.getDueDate().equals(LocalDate.of(2026, 4, 4))));

// DOES NOT WORK
verify(notices).notify(marta, anyString());

org.mockito.exceptions.misusing.InvalidUseOfMatchersException:
Invalid use of argument matchers!
2 matchers expected, 1 recorded.
This exception may occur if matchers are combined with raw values:
    //incorrect:
    someMethod(anyObject(), "raw String");
When using matchers, all arguments have to be provided by matchers.

// CORRECT
verify(notices).notify(eq(marta), anyString());

// Also correct: no matchers at all
verify(notices).notify(marta, "Your loan is due in 2 days");

// Also correct: all matchers
verify(notices).notify(any(Employee.class), anyString());

@ExtendWith(MockitoExtension.class)
class DueDateNoticeServiceTest {

    @Mock private LoanRepository loans;
    @Mock private NoticeService notices;

    @Captor private ArgumentCaptor<String> messageCaptor;
    @Captor private ArgumentCaptor<Employee> employeeCaptor;

    @Test
    void theNoticeMessageIncludesTheTitleAndTheDaysRemaining() {

        Loan loan = loanDueOn(TODAY.plusDays(2), marta(), "Effective Java");
        when(loans.findActive()).thenReturn(List.of(loan));

        service.sendTodaysNotices();

        // Capture the REAL arguments of the call
        verify(notices).notify(employeeCaptor.capture(), messageCaptor.capture());

        assertThat(employeeCaptor.getValue().getEmail())
                .isEqualTo("[email protected]");
        assertThat(messageCaptor.getValue())
                .contains("Effective Java")
                .contains("2 days")
                .doesNotContain("null");        // the classic concatenation bug
    }
}

@Test
void everyEmployeeWithALoanDueSoonIsNotified() {

    when(loans.findActive()).thenReturn(List.of(
            loanDueOn(TODAY.plusDays(2), marta(), "Effective Java"),
            loanDueOn(TODAY.plusDays(2), diego(), "Design Patterns"),
            loanDueOn(TODAY.plusDays(9), nuria(), "Refactoring")));   // not yet

    service.sendTodaysNotices();

    verify(notices, times(2)).notify(employeeCaptor.capture(), messageCaptor.capture());

    assertThat(employeeCaptor.getAllValues())
            .extracting(Employee::getEmail)
            .containsExactly("[email protected]",
                             "[email protected]");

    assertThat(messageCaptor.getAllValues())
            .allSatisfy(message -> assertThat(message).contains("2 days"));
}

@ExtendWith(MockitoExtension.class)
class FineCalculatorTest {

    @Spy private FineCalculator calculator =
            new FineCalculator(testProperties(), FIXED_CLOCK);

    @Test
    void example() {
        // REAL behaviour by default
        assertThat(calculator.calculate(loanOverdueBy(5))).isEqualByComparingTo("2.50");

        // Replace ONLY one method (note: do... is mandatory, section 10)
        doReturn(new BigDecimal("999.99")).when(calculator).calculate(any());
        assertThat(calculator.calculate(loanOverdueBy(5))).isEqualByComparingTo("999.99");
    }
}

// TRAP: the spy is a COPY, not the original object
List<String> original = new ArrayList<>();
List<String> spy = spy(original);

spy.add("Effective Java");
assertThat(spy).hasSize(1);         // ok
assertThat(original).isEmpty();     // the original did NOT change!

// TRAP: internal calls do NOT go through the spy
// It is exactly the proxy problem from 11-02 §26.
// If methodA() calls this.methodB(), replacing methodB does not affect methodA.

@Test
void staticExample() {
    try (MockedStatic<LocalDate> date = mockStatic(LocalDate.class)) {
        date.when(LocalDate::now).thenReturn(LocalDate.of(2026, 3, 20));

        // inside this block, LocalDate.now() returns the fixed date
        assertThat(LocalDate.now()).isEqualTo(LocalDate.of(2026, 3, 20));
    }
    // outside, normal behaviour
}

// Option A: mockStatic. It works, and it drags problems along.
try (MockedStatic<LocalDate> d = mockStatic(LocalDate.class)) {
    d.when(LocalDate::now).thenReturn(LocalDate.of(2026, 3, 20));
    assertThat(calculator.calculate(loan)).isEqualByComparingTo("2.50");
}

// Option B: injected Clock. The design removes the need for the mock.
var calculator = new FineCalculator(properties, Clock.fixed(...));
assertThat(calculator.calculate(loan)).isEqualByComparingTo("2.50");

@Mock private HttpClient http;

when(http.send(any(), any())).thenReturn(fakeResponse);

@Test
void lend() {
    when(materials.findByIsbn("978-0000000001")).thenReturn(Optional.of(book));
    when(employees.findByEmail("[email protected]")).thenReturn(Optional.of(marta));
    when(loans.countByEmployeeAndStatus(marta, ACTIVE)).thenReturn(0L);
    when(properties.loan()).thenReturn(new Loan(15, 3));
    when(calculator.calculate(any())).thenReturn(BigDecimal.ZERO);
    when(loans.save(any())).thenReturn(savedLoan);

    manager.lend("978-0000000001", "[email protected]");

    verify(materials).findByIsbn("978-0000000001");
    verify(employees).findByEmail("[email protected]");
    verify(loans).countByEmployeeAndStatus(marta, ACTIVE);
    verify(loans).save(any());
    verify(notices).notify(any(), anyString());
    verifyNoMoreInteractions(materials, employees, loans, notices);
}

@Test
void lendingCreatesAnActiveLoanDueInFifteenDays() {

    when(materials.findByIsbn("978-0000000001")).thenReturn(Optional.of(book));
    when(employees.findByEmail("[email protected]")).thenReturn(Optional.of(marta));
    when(loans.save(any(Loan.class))).thenAnswer(inv -> inv.getArgument(0));

    Loan loan = manager.lend("978-0000000001", "[email protected]");

    // BEHAVIOUR: what was produced
    assertThat(loan)
            .satisfies(l -> {
                assertThat(l.getMaterial()).isEqualTo(book);
                assertThat(l.getEmployee()).isEqualTo(marta);
                assertThat(l.getStatus()).isEqualTo(LoanStatus.ACTIVE);
                assertThat(l.getDueDate()).isEqualTo(LocalDate.of(2026, 4, 4));
            });

    // Observable EFFECTS (commands)
    verify(loans).save(loan);
    verify(notices).notify(eq(marta), contains("Effective Java"));
}

@Test
void returningLateRecordsTheFine_interaction() {

    Loan overdue = loanOverdueBy(10);
    when(loans.findById(1L)).thenReturn(Optional.of(overdue));
    when(calculator.calculate(overdue)).thenReturn(new BigDecimal("5.00"));

    manager.returnItem(1L);

    verify(calculator).calculate(overdue);
    verify(fines).register(eq(overdue), eq(new BigDecimal("5.00")));
}

@Test
void returningLateRecordsTheFine_state() {

    // REAL collaborators for whatever is cheap and deterministic
    var calculator = new FineCalculator(testProperties(), FIXED_CLOCK);
    var inMemoryFines = new InMemoryFineRegistry();                // fake
    var manager = new LoanManager(loans, calculator, inMemoryFines, notices, FIXED_CLOCK);

    Loan overdue = loanOverdueBy(10);
    when(loans.findById(1L)).thenReturn(Optional.of(overdue));

    manager.returnItem(1L);

    // The resulting STATE is what gets checked
    assertThat(inMemoryFines.forEmployee(overdue.getEmployee()))
            .singleElement()
            .satisfies(fine -> {
                assertThat(fine.amount()).isEqualByComparingTo("5.00");
                assertThat(fine.loan()).isEqualTo(overdue);
            });

    assertThat(overdue.getStatus()).isEqualTo(LoanStatus.RETURNED);
}

// Without Clock: a static method has to be mocked
try (MockedStatic<LocalDate> d = mockStatic(LocalDate.class)) {
    d.when(LocalDate::now).thenReturn(LocalDate.of(2026, 3, 20));
    // ... a slow, brittle test with a risk of contamination
}

// With an injected Clock: NO mock is needed at all
var calculator = new FineCalculator(properties, Clock.fixed(...));

@Test
void theNoticeContainsAllTheLoanDetails() {

    when(loans.findActive()).thenReturn(List.of(martasLoan(), diegosLoan()));

    service.sendTodaysNotices();

    ArgumentCaptor<Notice> captor = ArgumentCaptor.forClass(Notice.class);
    verify(notices, times(2)).send(captor.capture());

    // AssertJ on what was captured: expressive and with good error messages
    assertThat(captor.getAllValues())
            .hasSize(2)
            .extracting(Notice::recipient, Notice::subject)
            .containsExactly(
                    tuple("[email protected]",  "Your loan is due in 2 days"),
                    tuple("[email protected]","Your loan is due in 2 days"));

    assertThat(captor.getAllValues())
            .allSatisfy(notice -> {
                assertThat(notice.body()).doesNotContain("null");
                assertThat(notice.recipient()).endsWith("@nexussoftware.com");
            });
}

when(loans.save(any())).thenThrow(new DataAccessResourceFailureException("No connection"));

assertThatThrownBy(() -> manager.lend("978-0000000001", "[email protected]"))
        .isInstanceOf(BiblioTechException.class)                  // the exception is translated
        .hasCauseInstanceOf(DataAccessResourceFailureException.class)
        .hasMessageContaining("978-0000000001");

package com.nexussoftware.bibliotech.service;

import static org.assertj.core.api.Assertions.*;
import static org.mockito.ArgumentMatchers.*;
import static org.mockito.Mockito.*;

import java.math.BigDecimal;
import java.time.*;
import java.util.*;
import org.junit.jupiter.api.*;
import org.mockito.*;
import org.mockito.junit.jupiter.MockitoExtension;

@ExtendWith(MockitoExtension.class)
@DisplayName("LoanManager")
class LoanManagerTest {

    private static final ZoneId MADRID = ZoneId.of("Europe/Madrid");
    private static final LocalDate TODAY = LocalDate.of(2026, 3, 20);
    private static final Clock CLOCK = Clock.fixed(TODAY.atStartOfDay(MADRID).toInstant(), MADRID);

    @Mock private MaterialRepository materials;
    @Mock private EmployeeRepository employees;
    @Mock private LoanRepository loans;
    @Mock private NoticeService notices;

    private LoanManager manager;
    private Material book;
    private Employee marta;

    @BeforeEach
    void setUp() {
        // REAL properties and calculator: cheap, deterministic and effect-free
        var properties = new BiblioTechProperties(
                "BiblioTech",
                new BiblioTechProperties.Loan(15, 3),
                new BiblioTechProperties.Fine(new BigDecimal("0.50"), new BigDecimal("20.00")),
                new BiblioTechProperties.Reservation(3));
        var calculator = new FineCalculator(properties, CLOCK);

        manager = new LoanManager(materials, employees, loans, calculator,
                                  notices, properties, CLOCK);

        book = new Book("978-0000000001", "Effective Java", 3, "J. Bloch");
        marta = new Employee("[email protected]", "Marta Ruiz");
    }

    @Nested
    @DisplayName("when lending")
    class Lend {

        @Test
        @DisplayName("creates an active loan due in 15 days")
        void createsTheRightLoan() {
            when(materials.findByIsbn("978-0000000001")).thenReturn(Optional.of(book));
            when(employees.findByEmail(marta.getEmail())).thenReturn(Optional.of(marta));
            when(loans.save(any(Loan.class))).thenAnswer(inv -> inv.getArgument(0));

            Loan loan = manager.lend("978-0000000001", marta.getEmail());

            assertThat(loan.getMaterial()).isEqualTo(book);
            assertThat(loan.getEmployee()).isEqualTo(marta);
            assertThat(loan.getStatus()).isEqualTo(LoanStatus.ACTIVE);
            assertThat(loan.getLoanDate()).isEqualTo(TODAY);
            assertThat(loan.getDueDate()).isEqualTo(TODAY.plusDays(15));
        }

        @Test
        @DisplayName("decrements the material's available copies")
        void decrementsCopies() {
            when(materials.findByIsbn("978-0000000001")).thenReturn(Optional.of(book));
            when(employees.findByEmail(marta.getEmail())).thenReturn(Optional.of(marta));
            when(loans.save(any(Loan.class))).thenAnswer(inv -> inv.getArgument(0));

            manager.lend("978-0000000001", marta.getEmail());

            assertThat(book.getAvailableCopies()).isEqualTo(2);          // real state
        }

        @Test
        @DisplayName("fails if the material does not exist, and saves nothing")
        void materialNotFound() {
            when(materials.findByIsbn("978-9999999999")).thenReturn(Optional.empty());

            assertThatThrownBy(() -> manager.lend("978-9999999999", marta.getEmail()))
                    .isInstanceOf(MaterialNotFoundException.class)
                    .hasMessageContaining("978-9999999999");

            verify(loans, never()).save(any());
            verifyNoInteractions(notices);
        }

        @Test
        @DisplayName("fails if the material has no available copies")
        void noCopiesLeft() {
            Material soldOut = new Book("978-0000000003", "Refactoring", 0, "M. Fowler");
            when(materials.findByIsbn("978-0000000003")).thenReturn(Optional.of(soldOut));
            when(employees.findByEmail(marta.getEmail())).thenReturn(Optional.of(marta));

            assertThatThrownBy(() -> manager.lend("978-0000000003", marta.getEmail()))
                    .isInstanceOf(NoCopiesAvailableException.class);

            verify(loans, never()).save(any());
        }

        @Test
        @DisplayName("fails if the employee has reached the limit of 3 loans")
        void limitReached() {
            when(materials.findByIsbn("978-0000000001")).thenReturn(Optional.of(book));
            when(employees.findByEmail(marta.getEmail())).thenReturn(Optional.of(marta));
            when(loans.countByEmployeeAndStatus(marta, LoanStatus.ACTIVE))
                    .thenReturn(3L);

            assertThatThrownBy(() -> manager.lend("978-0000000001", marta.getEmail()))
                    .isInstanceOf(LoanLimitExceededException.class)
                    .hasMessageContaining(marta.getEmail());

            verify(loans, never()).save(any());
            assertThat(book.getAvailableCopies()).isEqualTo(3);          // no effects
        }
    }

    @Nested
    @DisplayName("faced with infrastructure failures")
    class Failures {

        @Test
        @DisplayName("if the save fails, nobody is notified")
        void theSaveFails() {
            when(materials.findByIsbn("978-0000000001")).thenReturn(Optional.of(book));
            when(employees.findByEmail(marta.getEmail())).thenReturn(Optional.of(marta));
            when(loans.save(any()))
                    .thenThrow(new DataAccessResourceFailureException("Connection lost"));

            assertThatThrownBy(() -> manager.lend("978-0000000001", marta.getEmail()))
                    .isInstanceOf(DataAccessResourceFailureException.class);

            verifyNoInteractions(notices);   // requirement: unpersisted things are not notified
        }

        @Test
        @DisplayName("retries after a concurrency conflict and ends up succeeding")
        void retriesAfterAConflict() {
            when(materials.findByIsbn("978-0000000001")).thenReturn(Optional.of(book));
            when(employees.findByEmail(marta.getEmail())).thenReturn(Optional.of(marta));
            when(loans.save(any()))
                    .thenThrow(new OptimisticLockingFailureException("stale version"))
                    .thenAnswer(inv -> inv.getArgument(0));   // second time, success

            Result<Loan> result =
                    manager.lendWithRetry("978-0000000001", marta.getEmail());

            assertThat(result.isSuccess()).isTrue();
            verify(loans, times(2)).save(any());   // it was attempted twice
        }
    }
}

@ExtendWith(MockitoExtension.class)
@DisplayName("Due-date notices")
class DueDateNoticeServiceTest {

    private static final ZoneId MADRID = ZoneId.of("Europe/Madrid");
    private static final LocalDate TODAY = LocalDate.of(2026, 3, 20);
    private static final Clock CLOCK = Clock.fixed(TODAY.atStartOfDay(MADRID).toInstant(), MADRID);

    @Mock private LoanRepository loans;
    @Mock private NoticeService notices;

    @Captor private ArgumentCaptor<Employee> employeeCaptor;
    @Captor private ArgumentCaptor<String> messageCaptor;

    private DueDateNoticeService service;

    @BeforeEach
    void setUp() {
        service = new DueDateNoticeService(loans, notices, propertiesWithDaysAhead(2), CLOCK);
    }

    @Test
    @DisplayName("the message includes the material's title and the days remaining")
    void messageContent() {
        when(loans.findActive()).thenReturn(List.of(
                loan("Effective Java", marta(), TODAY.plusDays(2))));

        service.sendTodaysNotices();

        verify(notices).notify(employeeCaptor.capture(), messageCaptor.capture());

        assertThat(employeeCaptor.getValue().getEmail())
                .isEqualTo("[email protected]");

        assertThat(messageCaptor.getValue())
                .contains("Effective Java")
                .contains("2 days")
                .doesNotContain("null")          // classic concatenation bug
                .doesNotContain("@{");           // unsubstituted template
    }

    @Test
    @DisplayName("notifies only the employees whose loan is due in exactly 2 days")
    void noticeWindow() {
        when(loans.findActive()).thenReturn(List.of(
                loan("Effective Java",  marta(), TODAY.plusDays(2)),   // YES
                loan("Design Patterns", diego(), TODAY.plusDays(2)),   // YES
                loan("Refactoring",     nuria(), TODAY.plusDays(1)),   // no
                loan("Effective Java",  nuria(), TODAY.plusDays(3)),   // no
                loan("Refactoring",     diego(), TODAY.minusDays(5))));// no

        service.sendTodaysNotices();

        verify(notices, times(2)).notify(employeeCaptor.capture(), anyString());

        assertThat(employeeCaptor.getAllValues())
                .extracting(Employee::getEmail)
                .containsExactly("[email protected]",
                                 "[email protected]");
    }

    @Test
    @DisplayName("a broken channel does not stop the remaining notices")
    void oneFailureDoesNotStopTheRest() {
        when(loans.findActive()).thenReturn(List.of(
                loan("Effective Java",  marta(), TODAY.plusDays(2)),
                loan("Design Patterns", diego(), TODAY.plusDays(2)),
                loan("Refactoring",     nuria(), TODAY.plusDays(2))));

        // The second notice fails
        doNothing()
                .doThrow(new NoticeServiceException("SMTP is not responding"))
                .doNothing()
                .when(notices).notify(any(), anyString());

        int sent = service.sendTodaysNotices();

        assertThat(sent).isEqualTo(2);                            // 3 attempts, 2 successful
        verify(notices, times(3)).notify(any(), anyString());     // all 3 were attempted
    }
}

package com.nexussoftware.bibliotech.network;

// OUR OWN interface, expressing what the domain needs
public interface MetadataGateway {
    Optional<BookMetadata> findByIsbn(String isbn);
}

// The real implementation, which does use HttpClient
@Component
public class HttpMetadataGateway implements MetadataGateway {

    private final HttpClient http;
    private final String baseUrl;

    public HttpMetadataGateway(HttpClient http,
                               @Value("${bibliotech.metadata.url}") String baseUrl) {
        this.http = http;
        this.baseUrl = baseUrl;
    }

    @Override
    public Optional<BookMetadata> findByIsbn(String isbn) { /* real HTTP */ }
}

@Service
public class CatalogEnricher {

    private final MetadataGateway gateway;        // the INTERFACE, not HttpClient
    private final MaterialRepository materials;

    public CatalogEnricher(MetadataGateway gateway, MaterialRepository materials) {
        this.gateway = gateway;
        this.materials = materials;
    }

    public int enrichCatalog() {
        int enriched = 0;
        for (Material material : materials.findByAuthorIsNull()) {
            try {
                Optional<BookMetadata> metadata = gateway.findByIsbn(material.getIsbn());
                if (metadata.isPresent()) {
                    material.completeWith(metadata.get());
                    materials.save(material);
                    enriched++;
                }
            } catch (GatewayUnavailableException e) {
                log.warn("Could not enrich {}: {}", material.getIsbn(), e.getMessage());
                // carries on with the next one
            }
        }
        return enriched;
    }
}

@ExtendWith(MockitoExtension.class)
@DisplayName("Catalogue enrichment")
class CatalogEnricherTest {

    @Mock private MetadataGateway gateway;
    @Mock private MaterialRepository materials;

    private CatalogEnricher enricher;

    @BeforeEach
    void setUp() { enricher = new CatalogEnricher(gateway, materials); }

    @Test
    @DisplayName("fills in the author of the materials that have it empty")
    void fillsInTheData() {
        Material withoutAuthor = new Book("978-0000000001", "Effective Java", 3, null);
        when(materials.findByAuthorIsNull()).thenReturn(List.of(withoutAuthor));
        when(gateway.findByIsbn("978-0000000001"))
                .thenReturn(Optional.of(new BookMetadata("Joshua Bloch", 2018, "Addison-Wesley")));

        int enriched = enricher.enrichCatalog();

        assertThat(enriched).isEqualTo(1);
        assertThat(withoutAuthor.getAuthor()).isEqualTo("Joshua Bloch");
        verify(materials).save(withoutAuthor);
    }

    @Test
    @DisplayName("saves nothing if the API does not know the ISBN")
    void unknownIsbn() {
        Material withoutAuthor = new Book("978-0000000099", "Odd title", 1, null);
        when(materials.findByAuthorIsNull()).thenReturn(List.of(withoutAuthor));
        when(gateway.findByIsbn(anyString())).thenReturn(Optional.empty());

        assertThat(enricher.enrichCatalog()).isZero();
        verify(materials, never()).save(any());
    }

    @Test
    @DisplayName("if the API is down, it carries on with the rest of the catalogue")
    void apiPartiallyDown() {
        Material one = new Book("978-0000000001", "Effective Java", 3, null);
        Material two = new Book("978-0000000002", "Design Patterns", 2, null);
        when(materials.findByAuthorIsNull()).thenReturn(List.of(one, two));

        when(gateway.findByIsbn("978-0000000001"))
                .thenThrow(new GatewayUnavailableException("504 Gateway Timeout"));
        when(gateway.findByIsbn("978-0000000002"))
                .thenReturn(Optional.of(new BookMetadata("GoF", 1994, "Addison-Wesley")));

        assertThat(enricher.enrichCatalog()).isEqualTo(1);
        assertThat(two.getAuthor()).isEqualTo("GoF");
        verify(materials, times(1)).save(two);
    }

    @Test
    @DisplayName("does not call the API if there are no incomplete materials")
    void completeCatalogue() {
        when(materials.findByAuthorIsNull()).thenReturn(List.of());

        assertThat(enricher.enrichCatalog()).isZero();
        verifyNoInteractions(gateway);       // not a single needless request
    }
}

@SpringBootTest
@ActiveProfiles("test")
class LoanManagerIT {              // IT suffix: failsafe runs it (11-05)

    @Autowired private LoanManager manager;
    @Autowired private MaterialRepository materials;

    // Replaces the real bean in the Spring context with a mock
    @MockitoBean private NoticeService notices;

    @Test
    void lendingPersistsAndNotifies() {
        materials.save(new Book("978-0000000001", "Effective Java", 3, "J. Bloch"));

        Loan loan = manager.lend("978-0000000001", "[email protected]");

        assertThat(loan.getId()).isNotNull();          // it really was persisted
        verify(notices).notify(any(), contains("Effective Java"));  // no real e-mail was sent
    }
}

@DataJpaTest                       // JPA only: repositories, EntityManager, embedded DB
@Tag("integration")
class LoanRepositoryIT {

    @Autowired private LoanRepository repository;
    @Autowired private TestEntityManager em;

    @Test
    @DisplayName("finds the overdue, unreturned loans with their relations loaded")
    void findsOverdueOnes() {
        Material book = em.persist(new Book("978-0000000001", "Effective Java", 3, "J. Bloch"));
        Employee marta = em.persist(new Employee("[email protected]", "Marta Ruiz"));

        em.persist(new Loan(book, marta, LocalDate.of(2026, 3, 1), LocalDate.of(2026, 3, 10)));
        em.persist(new Loan(book, marta, LocalDate.of(2026, 3, 1), LocalDate.of(2026, 4, 10)));
        em.flush();
        em.clear();                // empties the context: forces a real read from the DB

        List<Loan> overdue = repository.overdue(LocalDate.of(2026, 3, 20));

        assertThat(overdue).hasSize(1);
        // The JOIN FETCH from 11-03 works: no LazyInitializationException
        assertThat(overdue.get(0).getMaterial().getTitle()).isEqualTo("Effective Java");
    }
}

@SpringBootTest
@Testcontainers
class LoanRepositoryPostgresIT {

    @Container
    @ServiceConnection    // Spring Boot 3.1+: configures the DataSource on its own
    static PostgreSQLContainer<?> postgres =
            new PostgreSQLContainer<>("postgres:16-alpine");

    @Autowired private LoanRepository repository;

    @Test
    void worksAgainstRealPostgres() {
        // Runs against real PostgreSQL 16, started and destroyed by the test
    }
}

@Test
void highCoverage() {
    when(materials.findByIsbn(anyString())).thenReturn(Optional.of(book));
    when(employees.findByEmail(anyString())).thenReturn(Optional.of(marta));
    when(loans.save(any())).thenReturn(loan);

    manager.lend("978-0000000001", "[email protected]");
    // Not one assertion. Coverage of the method: 100%. Value: zero.
}

@ExtendWith(MockitoExtension.class)
class ReservationProcessorTest {

    @Mock private ReservationRepository reservations;
    @Mock private LoanManager manager;
    @Mock private BiblioTechProperties properties;
    @Mock private BiblioTechProperties.Reservation reservationProperties;
    @Mock private Clock clock;
    @Mock private Reservation reservation;
    @Mock private Material material;

    @InjectMocks private ReservationProcessor processor;

    @Test
    void test() {
        when(properties.reservation()).thenReturn(reservationProperties);
        when(reservationProperties.expiryDays()).thenReturn(3);
        when(clock.instant()).thenReturn(Instant.parse("2026-03-20T10:00:00Z"));
        when(clock.getZone()).thenReturn(ZoneId.of("Europe/Madrid"));
        when(reservations.pending()).thenReturn(List.of(reservation));
        when(reservation.getRequestDate()).thenReturn(LocalDate.of(2026, 3, 10));
        when(reservation.getMaterial()).thenReturn(material);
        when(material.getIsbn()).thenReturn("978-0000000001");
        when(manager.isAvailable(anyString())).thenReturn(false);

        processor.processPending();

        verify(properties).reservation();
        verify(reservationProperties).expiryDays();
        verify(reservations).pending();
        verify(reservation).getRequestDate();
        verify(reservations).expire(reservation);
        verifyNoMoreInteractions(reservations, manager, properties);
    }
}

@Service
public class ReturnManager {

    private final LoanRepository loans;
    private final FineCalculator calculator;
    private final FineRegistry fines;
    private final ReservationProcessor reservations;
    private final NoticeService notices;
    private final Clock clock;

    @Transactional
    public ReturnResult returnItem(Long loanId) {

        Loan loan = loans.findById(loanId)
                .orElseThrow(() -> new LoanNotFoundException(loanId));

        if (loan.getReturnDate().isPresent()) {
            throw new LoanAlreadyReturnedException(loanId);
        }

        LocalDate today = LocalDate.now(clock);
        BigDecimal fine = calculator.calculate(loan);

        loan.returnItem(today);
        loan.getMaterial().returnOneCopy();
        loans.save(loan);

        if (fine.compareTo(BigDecimal.ZERO) > 0) {
            fines.register(loan, fine);
            notices.notify(loan.getEmployee(),
                    "A fine of " + fine + " EUR has been recorded for the late return of "
                    + loan.getMaterial().getTitle());
        }

        Optional<Reservation> next = reservations.nextFor(loan.getMaterial());
        next.ifPresent(r -> {
            r.markNotified(clock);
            notices.notify(r.getEmployee(),
                    "The material you reserved is now available: "
                    + loan.getMaterial().getTitle());
        });

        return new ReturnResult(loan, fine, next.isPresent());
    }
}

// 1. No doubles: everything real
var calculator = new FineCalculator(testProperties(), Clock.fixed(...));
assertThat(calculator.calculate(loanOverdueBy(200))).isEqualByComparingTo("20.00");

// 2. A mock to verify the command
verify(notices).notify(eq(librarianInCharge), contains("last copy"));

// 3. A stub for the query, verify(never) for the absence of a command
when(loans.countByEmployeeAndStatus(marta, ACTIVE)).thenReturn(3L);
assertThatThrownBy(() -> manager.lend(...)).isInstanceOf(LoanLimitExceededException.class);
verify(loans, never()).save(any());

// 4. A fake: coherence between queries, for free
var repository = new InMemoryLoanRepository();
repository.save(loanOf(marta, "978-0000000001"));
repository.save(loanOf(marta, "978-0000000002"));
repository.save(loanOf(diego, "978-0000000001"));

var statistics = new BiblioTechStatistics(repository);
assertThat(statistics.mostLentMaterial()).contains("978-0000000001");
assertThat(statistics.loansPerEmployee()).containsEntry("Marta Ruiz", 2L);

// 5. thenThrow: the scenario that is impossible to reproduce
when(gateway.findByIsbn("978-0000000001"))
        .thenThrow(new GatewayUnavailableException("503 Service Unavailable"));

// 6. A captor for the audit content
verify(auditLog).write(entryCaptor.capture());
assertThat(entryCaptor.getValue())
        .extracting(AuditEntry::operation, AuditEntry::isbn)
        .containsExactly("LOAN", "978-0000000001");

// 7. A REAL fixed clock, not a mock of Clock
var processor = new ReservationProcessor(repository, manager, properties,
                                         Clock.fixed(Instant.parse("2026-03-20T10:00:00Z"), MADRID));

@ExtendWith(MockitoExtension.class)
@DisplayName("ReservationProcessor")
class ReservationProcessorTest {

    private static final ZoneId MADRID = ZoneId.of("Europe/Madrid");
    private static final LocalDate TODAY = LocalDate.of(2026, 3, 20);
    private static final Clock CLOCK = Clock.fixed(TODAY.atStartOfDay(MADRID).toInstant(), MADRID);

    @Mock private ReservationRepository reservations;   // external collaborator: mock
    @Mock private LoanManager manager;                  // collaborator with effects: mock

    private ReservationProcessor processor;
    private Material book;
    private Employee marta;

    @BeforeEach
    void setUp() {
        // REAL objects: configuration records, fixed clock and domain entities
        var properties = new BiblioTechProperties(
                "BiblioTech",
                new BiblioTechProperties.Loan(15, 3),
                new BiblioTechProperties.Fine(new BigDecimal("0.50"), new BigDecimal("20.00")),
                new BiblioTechProperties.Reservation(3));    // 3-day expiry

        // Explicit construction, not @InjectMocks
        processor = new ReservationProcessor(reservations, manager, properties, CLOCK);

        book = new Book("978-0000000001", "Effective Java", 0, "J. Bloch");
        marta = new Employee("[email protected]", "Marta Ruiz");
    }

    @Test
    @DisplayName("expires the reservations requested more than 3 days ago")
    void expiresTheOldReservations() {
        // Requested on the 10th -> expired on the 13th -> today is the 20th: expired
        Reservation old = new Reservation(book, marta, LocalDate.of(2026, 3, 10), 3);
        when(reservations.pending()).thenReturn(List.of(old));

        processor.processPending();

        verify(reservations).expire(old);                         // COMMAND: verified
        assertThat(old.getStatus()).isEqualTo(ReservationStatus.EXPIRED);    // real STATE
        verify(manager, never()).lend(anyString(), anyString());
    }

    @Test
    @DisplayName("does not expire a reservation still within the 3-day window")
    void doesNotExpireTheRecentOnes() {
        // Requested on the 18th -> expires on the 21st -> today is the 20th: still valid
        Reservation recent = new Reservation(book, marta, LocalDate.of(2026, 3, 18), 3);
        when(reservations.pending()).thenReturn(List.of(recent));
        when(manager.isAvailable("978-0000000001")).thenReturn(false);

        processor.processPending();

        verify(reservations, never()).expire(any());
        assertThat(recent.getStatus()).isEqualTo(ReservationStatus.PENDING);
    }

    @Test
    @DisplayName("lends and completes the reservation when a copy is available")
    void completesTheReservationIfACopyIsFree() {
        Reservation valid = new Reservation(book, marta, LocalDate.of(2026, 3, 18), 3);
        when(reservations.pending()).thenReturn(List.of(valid));
        when(manager.isAvailable("978-0000000001")).thenReturn(true);

        processor.processPending();

        verify(manager).lend("978-0000000001", marta.getEmail());     // COMMAND
        verify(reservations).complete(valid);                          // COMMAND
        verify(reservations, never()).expire(any());
    }

    @Test
    @DisplayName("on the exact expiry day the reservation is still valid")
    void theEdgeOfTheWindow() {
        // Requested on the 17th -> expires on the 20th -> today is the 20th: IT IS the last day, still valid
        Reservation onTheEdge = new Reservation(book, marta, LocalDate.of(2026, 3, 17), 3);
        when(reservations.pending()).thenReturn(List.of(onTheEdge));
        when(manager.isAvailable(anyString())).thenReturn(false);

        processor.processPending();

        verify(reservations, never()).expire(any());
    }

    @Test
    @DisplayName("does nothing if there are no pending reservations")
    void noReservations() {
        when(reservations.pending()).thenReturn(List.of());

        processor.processPending();

        verifyNoInteractions(manager);
    }
}

package com.nexussoftware.bibliotech.service;

import static org.assertj.core.api.Assertions.*;
import static org.mockito.ArgumentMatchers.*;
import static org.mockito.Mockito.*;

import java.math.BigDecimal;
import java.time.*;
import java.util.*;
import org.junit.jupiter.api.*;
import org.mockito.*;
import org.mockito.junit.jupiter.MockitoExtension;

@ExtendWith(MockitoExtension.class)
@DisplayName("ReturnManager")
class ReturnManagerTest {

    private static final ZoneId MADRID = ZoneId.of("Europe/Madrid");
    private static final LocalDate TODAY = LocalDate.of(2026, 3, 20);
    private static final Clock CLOCK = Clock.fixed(TODAY.atStartOfDay(MADRID).toInstant(), MADRID);

    // MOCKS: collaborators with external effects or infrastructure
    @Mock private LoanRepository loans;
    @Mock private FineRegistry fines;
    @Mock private ReservationProcessor reservations;
    @Mock private NoticeService notices;

    @Captor private ArgumentCaptor<String> messageCaptor;
    @Captor private ArgumentCaptor<Employee> employeeCaptor;
    @Captor private ArgumentCaptor<BigDecimal> amountCaptor;

    private ReturnManager manager;
    private Material book;
    private Employee marta;
    private Employee diego;

    @BeforeEach
    void setUp() {
        var properties = new BiblioTechProperties(
                "BiblioTech",
                new BiblioTechProperties.Loan(15, 3),
                new BiblioTechProperties.Fine(new BigDecimal("0.50"), new BigDecimal("20.00")),
                new BiblioTechProperties.Reservation(3));

        // REAL: pure, cheap, deterministic. Mocking it would weaken the test
        var calculator = new FineCalculator(properties, CLOCK);

        manager = new ReturnManager(loans, calculator, fines, reservations, notices, CLOCK);

        book  = new Book("978-0000000001", "Effective Java", 2, "J. Bloch");
        marta = new Employee("[email protected]", "Marta Ruiz");
        diego = new Employee("[email protected]", "Diego Alonso");
    }

    // ============ (1) ON TIME ============
    @Nested
    @DisplayName("on-time return")
    class OnTime {

        @Test
        @DisplayName("generates neither a fine nor a notice")
        void noFineNoNotice() {
            Loan loan = loanDueOn(TODAY.plusDays(5));                // still within the term
            when(loans.findById(1L)).thenReturn(Optional.of(loan));
            when(reservations.nextFor(book)).thenReturn(Optional.empty());

            ReturnResult result = manager.returnItem(1L);

            assertThat(result.fine()).isEqualByComparingTo("0.00");
            assertThat(result.hasPendingReservation()).isFalse();
            assertThat(loan.getStatus()).isEqualTo(LoanStatus.RETURNED);
            assertThat(loan.getReturnDate()).contains(TODAY);

            verify(loans).save(loan);                  // COMMAND
            verifyNoInteractions(fines);               // no fine was recorded
            verify(notices, never()).notify(any(), anyString());
        }

        // ============ (6) COPIES ============
        @Test
        @DisplayName("the material recovers an available copy")
        void recoversACopy() {
            Loan loan = loanDueOn(TODAY.plusDays(5));
            when(loans.findById(1L)).thenReturn(Optional.of(loan));
            when(reservations.nextFor(book)).thenReturn(Optional.empty());

            int before = book.getAvailableCopies();
            manager.returnItem(1L);

            assertThat(book.getAvailableCopies()).isEqualTo(before + 1);
        }
    }

    // ============ (2) LATE ============
    @Nested
    @DisplayName("late return")
    class Late {

        @Test
        @DisplayName("records a €5.00 fine for 10 days and notifies with the detail")
        void tenDayFine() {
            Loan loan = loanDueOn(TODAY.minusDays(10));
            when(loans.findById(1L)).thenReturn(Optional.of(loan));
            when(reservations.nextFor(book)).thenReturn(Optional.empty());

            ReturnResult result = manager.returnItem(1L);

            // The fine is computed by the REAL code: 10 days x €0.50 = €5.00
            assertThat(result.fine()).isEqualByComparingTo("5.00");

            // COMMAND 1: recording the fine, capturing the real arguments
            verify(fines).register(eq(loan), amountCaptor.capture());
            assertThat(amountCaptor.getValue()).isEqualByComparingTo("5.00");

            // COMMAND 2: the notice, with its CONTENT verified
            verify(notices).notify(employeeCaptor.capture(), messageCaptor.capture());
            assertThat(employeeCaptor.getValue()).isEqualTo(marta);
            assertThat(messageCaptor.getValue())
                    .contains("fine")
                    .contains("5.00")
                    .contains("Effective Java")
                    .doesNotContain("null");
        }

        @Test
        @DisplayName("the fine is capped at the €20 maximum for very long delays")
        void cappedFine() {
            Loan loan = loanDueOn(TODAY.minusDays(300));
            when(loans.findById(1L)).thenReturn(Optional.of(loan));
            when(reservations.nextFor(book)).thenReturn(Optional.empty());

            assertThat(manager.returnItem(1L).fine()).isEqualByComparingTo("20.00");
            verify(fines).register(eq(loan), argThat(f -> f.compareTo(new BigDecimal("20.00")) == 0));
        }
    }

    // ============ (3) WITH A PENDING RESERVATION ============
    @Nested
    @DisplayName("when there is a pending reservation for the material")
    class WithReservation {

        @Test
        @DisplayName("also notifies the next employee in the queue")
        void notifiesTheNextOne() {
            Loan loan = loanDueOn(TODAY.plusDays(5));                // on time: only 1 notice
            Reservation diegosReservation = new Reservation(book, diego, TODAY.minusDays(1), 3);

            when(loans.findById(1L)).thenReturn(Optional.of(loan));
            when(reservations.nextFor(book)).thenReturn(Optional.of(diegosReservation));

            ReturnResult result = manager.returnItem(1L);

            assertThat(result.hasPendingReservation()).isTrue();
            assertThat(diegosReservation.getStatus()).isEqualTo(ReservationStatus.NOTIFIED);
            assertThat(diegosReservation.getNotifiedAt()).isPresent();

            verify(notices).notify(employeeCaptor.capture(), messageCaptor.capture());
            assertThat(employeeCaptor.getValue()).isEqualTo(diego);
            assertThat(messageCaptor.getValue())
                    .contains("available")
                    .contains("Effective Java");
        }

        @Test
        @DisplayName("late AND reserved sends two notices, the fine one first")
        void twoNoticesInOrder() {
            Loan loan = loanDueOn(TODAY.minusDays(10));
            Reservation diegosReservation = new Reservation(book, diego, TODAY.minusDays(1), 3);

            when(loans.findById(1L)).thenReturn(Optional.of(loan));
            when(reservations.nextFor(book)).thenReturn(Optional.of(diegosReservation));

            manager.returnItem(1L);

            verify(notices, times(2))
                    .notify(employeeCaptor.capture(), messageCaptor.capture());

            // Order IS a requirement here: the person hit by the fine hears about it first
            assertThat(employeeCaptor.getAllValues()).containsExactly(marta, diego);
            assertThat(messageCaptor.getAllValues().get(0)).contains("fine");
            assertThat(messageCaptor.getAllValues().get(1)).contains("available");
        }
    }

    // ============ (4) and (5) ERROR CASES ============
    @Nested
    @DisplayName("error cases")
    class Errors {

        @Test
        @DisplayName("non-existent loan: exception and no effects")
        void loanNotFound() {
            when(loans.findById(99L)).thenReturn(Optional.empty());

            assertThatThrownBy(() -> manager.returnItem(99L))
                    .isInstanceOf(LoanNotFoundException.class)
                    .hasMessageContaining("99");

            verify(loans, never()).save(any());
            verifyNoInteractions(fines, notices, reservations);
        }

        @Test
        @DisplayName("already-returned loan: exception and no effects")
        void loanAlreadyReturned() {
            Loan returned = loanDueOn(TODAY.minusDays(10));
            returned.returnItem(TODAY.minusDays(5));               // already returned
            when(loans.findById(1L)).thenReturn(Optional.of(returned));

            int copiesBefore = book.getAvailableCopies();

            assertThatThrownBy(() -> manager.returnItem(1L))
                    .isInstanceOf(LoanAlreadyReturnedException.class);

            verify(loans, never()).save(any());
            verifyNoInteractions(fines, notices, reservations);
            // No effect on the material's state
            assertThat(book.getAvailableCopies()).isEqualTo(copiesBefore);
        }
    }

    // --- scenario factory ---
    private Loan loanDueOn(LocalDate dueDate) {
        return new Loan(book, marta, dueDate.minusDays(15), dueDate);
    }
}