# The 10 slowest tests in the project
./mvnw test -Dsurefire.reportFormat=plain
grep -h "Time elapsed" target/surefire-reports/*.txt | sort -t: -k2 -rn | head -10

@Test
void theDomainSuiteIsFast() {
    long start = System.nanoTime();
    // run the domain test set…
    long ms = (System.nanoTime() - start) / 1_000_000;
    assertThat(ms)
        .as("The domain tests must stay fast")
        .isLessThan(5_000);
}

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-testcontainers</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>postgresql</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>

/**
 * Base class for the integration tests.
 *
 * The container is static: it is created ONCE for the whole run
 * and shared by every class that inherits from it. Without static,
 * one PostgreSQL would start per test class (30 s each).
 */
@Testcontainers
public abstract class PostgresTestBase {

    @Container
    @ServiceConnection            // Spring Boot 3.1+: configures the DataSource on its own
    static final PostgreSQLContainer<?> POSTGRES =
            new PostgreSQLContainer<>("postgres:16-alpine")
                    .withDatabaseName("bibliotech_test")
                    .withUsername("test")
                    .withPassword("test")
                    .withReuse(true);      // reuses the container between local runs
}

@DynamicPropertySource
static void properties(DynamicPropertyRegistry registry) {
    registry.add("spring.datasource.url", POSTGRES::getJdbcUrl);
    registry.add("spring.datasource.username", POSTGRES::getUsername);
    registry.add("spring.datasource.password", POSTGRES::getPassword);
}

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)   // do not swap in H2!
@Tag("integration")
class LoanRepositoryIT extends PostgresTestBase {

    @Autowired LoanRepository repository;
    @Autowired TestEntityManager em;

    @Test
    void findsTheOverdueLoansOrderedByAge() {
        Employee marta = em.persist(anEmployee("Marta Ruiz"));
        Material java = em.persist(aBook("978-0000000001", "Effective Java"));

        em.persist(aLoan(java, marta).dueOn(LocalDate.of(2026, 3, 1)));    // overdue
        em.persist(aLoan(java, marta).dueOn(LocalDate.of(2026, 3, 10)));   // overdue
        em.persist(aLoan(java, marta).dueOn(LocalDate.of(2026, 9, 1)));    // current
        em.flush();

        List<Loan> overdue = repository.overdueBefore(LocalDate.of(2026, 8, 5));

        assertThat(overdue)
                .hasSize(2)
                .extracting(Loan::getDueDate)
                .containsExactly(LocalDate.of(2026, 3, 1), LocalDate.of(2026, 3, 10));
    }

    @Test
    void theSearchIgnoresCaseAndAccentsJustLikeInProduction() {
        em.persist(aBook("978-0000000003", "Refactoring"));
        em.flush();

        // This uses PostgreSQL's unaccent(): in H2 it would be IMPOSSIBLE to test
        assertThat(repository.findByTitle("refactoring")).hasSize(1);
        assertThat(repository.findByTitle("REFACTORING")).hasSize(1);
    }

    @Test
    void detectsTheOptimisticLockingConflict() {
        Loan loan = em.persistFlushFind(aLoan());
        em.detach(loan);

        // Simulate a concurrent modification by another transaction
        em.getEntityManager()
          .createNativeQuery("update loans set version = version + 1 where id = :id")
          .setParameter("id", loan.getId())
          .executeUpdate();

        loan.renew(7);

        assertThatThrownBy(() -> { repository.save(loan); em.flush(); })
                .isInstanceOf(OptimisticLockingFailureException.class);
    }
}

# ~/.testcontainers.properties — reuse containers between local runs
testcontainers.reuse.enable=true

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <configuration>
        <excludedGroups>integration</excludedGroups>   <!-- in case some Test carries the @Tag -->
        <includes>
          <include>**/*Test.java</include>
        </includes>
      </configuration>
    </plugin>

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-failsafe-plugin</artifactId>
      <configuration>
        <includes>
          <include>**/*IT.java</include>
        </includes>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>integration-test</goal>
            <goal>verify</goal>            <!-- verify is what FAILS the build -->
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

./mvnw test                    # unit tests only: ~20 s
./mvnw verify                  # unit + integration: ~3 min
./mvnw verify -DskipITs        # skip the integration ones
./mvnw test -Dgroups=fast       # only the tagged ones

@Tag("integration")
@Tag("slow")
class BulkImportIT extends PostgresTestBase { … }

# src/test/resources/junit-platform.properties
junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=concurrent
junit.jupiter.execution.parallel.config.strategy=dynamic
junit.jupiter.execution.parallel.config.dynamic.factor=1.0

<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.12</version>
  <executions>
    <!-- 1. Instrument before the unit tests -->
    <execution>
      <id>prepare-agent</id>
      <goals><goal>prepare-agent</goal></goals>
    </execution>

    <!-- 2. Generate the report after the tests -->
    <execution>
      <id>report</id>
      <phase>verify</phase>
      <goals><goal>report</goal></goals>
    </execution>

    <!-- 3. Check thresholds: if they are not met, the build FAILS -->
    <execution>
      <id>coverage-threshold</id>
      <phase>verify</phase>
      <goals><goal>check</goal></goals>
      <configuration>
        <rules>
          <rule>
            <element>BUNDLE</element>
            <limits>
              <limit>
                <counter>INSTRUCTION</counter>
                <value>COVEREDRATIO</value>
                <minimum>0.75</minimum>
              </limit>
              <limit>
                <counter>BRANCH</counter>          <!-- the metric that really matters -->
                <value>COVEREDRATIO</value>
                <minimum>0.70</minimum>
              </limit>
            </limits>
          </rule>
          <!-- The domain is pure logic: more is demanded of it -->
          <rule>
            <element>PACKAGE</element>
            <includes><include>com.nexussoftware.bibliotech.domain.*</include></includes>
            <limits>
              <limit>
                <counter>BRANCH</counter>
                <value>COVEREDRATIO</value>
                <minimum>0.90</minimum>
              </limit>
            </limits>
          </rule>
        </rules>
      </configuration>
    </execution>
  </executions>

  <configuration>
    <excludes>
      <!-- Exclude whatever has no logic to test -->
      <exclude>**/dto/**</exclude>
      <exclude>**/*Application.class</exclude>
      <exclude>**/config/**</exclude>
      <exclude>**/generated/**</exclude>
    </excludes>
  </configuration>
</plugin>

./mvnw verify
# The browsable report, with the code coloured line by line:
open target/site/jacoco/index.html

public Money calculateFine(Loan loan, LocalDate today) {
    long days = ChronoUnit.DAYS.between(loan.getDueDate(), today);
    if (days <= 0) {
        return Money.ZERO;
    }
    Money fine = loan.finePerDay().times(days);
    return fine.isGreaterThan(MAX_FINE) ? MAX_FINE : fine;
}

@Test
void calculatesTheFineForTenDays() {
    assertThat(calculator.calculateFine(loanOverdueBy(10), TODAY))
            .isEqualTo(Money.euros("5.00"));
}

@Test
void calculatesTheFine() {
    // Runs the WHOLE method: 100% line coverage
    calculator.calculateFine(loanOverdueBy(10), TODAY);
    // And CHECKS NOTHING.
}

<plugin>
  <groupId>org.pitest</groupId>
  <artifactId>pitest-maven</artifactId>
  <version>1.16.1</version>
  <dependencies>
    <dependency>
      <groupId>org.pitest</groupId>
      <artifactId>pitest-junit5-plugin</artifactId>
      <version>1.2.1</version>
    </dependency>
  </dependencies>
  <configuration>
    <targetClasses>
      <param>com.nexussoftware.bibliotech.domain.*</param>   <!-- where the logic lives -->
    </targetClasses>
    <targetTests>
      <param>com.nexussoftware.bibliotech.domain.*Test</param>
    </targetTests>
    <mutationThreshold>70</mutationThreshold>
    <timestampedReports>false</timestampedReports>
  </configuration>
</plugin>

./mvnw org.pitest:pitest-maven:mutationCoverage
open target/pit-reports/index.html

public Money calculateFine(Loan loan, LocalDate today) {
    long days = ChronoUnit.DAYS.between(loan.getDueDate(), today);
    if (days <= 0) {                                    // ← the critical point
        return Money.ZERO;
    }
    Money fine = loan.finePerDay().times(days);
    return fine.isGreaterThan(MAX_FINE) ? MAX_FINE : fine;
}

@Test void noDelayMeansNoFine()        { assertThat(fineFor(-3)).isEqualTo(Money.ZERO); }
@Test void tenDaysMeansFiveEuros()     { assertThat(fineFor(10)).isEqualTo(Money.euros("5.00")); }
@Test void itNeverExceedsTheMaximum()  { assertThat(fineFor(100)).isEqualTo(Money.euros("20.00")); }

FineCalculator.java
  L.4   changed conditional boundary → SURVIVED    (days <= 0  →  days < 0)
  L.8   changed conditional boundary → KILLED
  L.7   Replaced long multiplication with division → KILLED

@ParameterizedTest
@CsvSource({
    "-1, 0.00",     // one day before it falls due
    " 0, 0.00",     // THE DUE DATE ITSELF: the boundary
    " 1, 0.50",     // one day late
    "39, 19.50",    // just under the maximum
    "40, 20.00",    // exactly the maximum
    "41, 20.00"     // above it: the cap applies
})
void calculatesTheFineAtTheBoundaries(int daysLate, String expectedFine) {
    assertThat(fineFor(daysLate)).isEqualTo(Money.euros(expectedFine));
}

<plugin>
  <groupId>com.github.spotbugs</groupId>
  <artifactId>spotbugs-maven-plugin</artifactId>
  <version>4.8.6.4</version>
  <configuration>
    <effort>Max</effort>
    <threshold>Medium</threshold>
    <failOnError>true</failOnError>
    <excludeFilterFile>config/spotbugs-exclusions.xml</excludeFilterFile>
    <plugins>
      <plugin>
        <groupId>com.h3xstream.findsecbugs</groupId>     <!-- security analysis -->
        <artifactId>findsecbugs-plugin</artifactId>
        <version>1.13.0</version>
      </plugin>
    </plugins>
  </configuration>
  <executions>
    <execution><phase>verify</phase><goals><goal>check</goal></goals></execution>
  </executions>
</plugin>

// SpotBugs: DM_DEFAULT_ENCODING — depends on the platform encoding
Files.readString(path);                          // BAD
Files.readString(path, StandardCharsets.UTF_8);  // GOOD

// SpotBugs: ES_COMPARING_STRINGS_WITH_EQ
if (status == "ACTIVE")           // BAD: compares references
if ("ACTIVE".equals(status))      // GOOD

// SpotBugs: EI_EXPOSE_REP — the internal representation is exposed
public List<Loan> getLoans() { return loans; }             // BAD: mutable
public List<Loan> getLoans() { return List.copyOf(loans); } // GOOD

// FindSecBugs: SQL_INJECTION_JPA
em.createQuery("select m from Material m where m.title like '%" + text + "%'");     // BAD
em.createQuery("select m from Material m where m.title like :t").setParameter("t", …); // GOOD

./mvnw verify sonar:sonar \
  -Dsonar.projectKey=nexussoftware_bibliotech \
  -Dsonar.host.url=https://sonarcloud.io \
  -Dsonar.token=$SONAR_TOKEN

./mvnw spotless:apply     # formats (locally, or as a pre-commit hook)
./mvnw spotless:check     # fails if it is not formatted (in CI)

// DEBT: the search walks the whole catalogue in memory because there are ~3,000 materials.
// Beyond 50,000 we will have to move to PostgreSQL full-text search.
// Consciously decided on 2026-08-05 — see docs/adr/0007-in-memory-search.md

// BEFORE: 40 lines, three responsibilities tangled together
public ImportResult importFrom(Path file) {
    List<String> lines = Files.readAllLines(file, UTF_8);
    List<Material> materials = new ArrayList<>();
    List<String> errors = new ArrayList<>();

    for (int i = 1; i < lines.size(); i++) {
        String[] fields = lines.get(i).split(";");
        if (fields.length < 4) { errors.add("Line " + i + ": not enough fields"); continue; }
        if (!fields[0].matches("97[89]-\\d{10}")) { errors.add("Line " + i + ": invalid ISBN"); continue; }
        // … 20 more lines of conversion and validation
    }
    // … saving and summary
}

// AFTER: the main method tells the story; the details live one level down
public ImportResult importFrom(Path file) throws IOException {
    List<CsvLine> lines = readLines(file);
    ParseResult parsed = parse(lines);
    List<Material> saved = save(parsed.valid());
    return new ImportResult(saved.size(), parsed.errors());
}

private ParseResult parse(List<CsvLine> lines) {
    List<Material> valid = new ArrayList<>();
    List<ImportError> errors = new ArrayList<>();
    for (CsvLine line : lines) {
        parseLine(line).ifPresentOrElse(valid::add, () -> errors.add(errorFrom(line)));
    }
    return new ParseResult(valid, errors);
}

// BEFORE: Loan mixes its identity with the fine calculation
public class Loan {
    public Money calculateFine(LocalDate today) {
        long days = ChronoUnit.DAYS.between(dueDate, today);
        if (days <= 0) return Money.ZERO;
        Money base = material.finePerDay().times(days);
        if (employee.tenureInMonths() < 6) base = base.multiplyBy(0.5);
        if (employee.isManagement()) return Money.ZERO;
        return base.isGreaterThan(MAX_FINE) ? MAX_FINE : base;
    }
}

// AFTER: the fine policy is a concept of its own, with tests of its own
public class FinePolicy {
    private final List<RateRule> rules;         // Strategy (12-02)

    public Money calculate(Loan loan, LocalDate today) { … }
}

public class Loan {
    public Money accruedFine(LocalDate today, FinePolicy policy) {
        return policy.calculate(this, today);
    }
}

// BEFORE
public int loanDays(Material m) {
    switch (m.getType()) {
        case BOOK: return 15;
        case MAGAZINE: return 7;
        case DVD: return 3;
        default: throw new IllegalStateException();
    }
}

// AFTER: each type answers for itself
public abstract class Material {
    public abstract int defaultLoanDays();
}

class DamageSurchargeTest {

    @Test
    void anUndamagedMaterialHasNoSurcharge() {
        var calculator = new SurchargeCalculator();
        var material = aBook("978-0000000001").withValue(Money.euros("45.00"));

        Money surcharge = calculator.calculate(material, ReturnCondition.UNDAMAGED);

        assertThat(surcharge).isEqualTo(Money.ZERO);
    }
}

public enum ReturnCondition { UNDAMAGED }

public class SurchargeCalculator {
    public Money calculate(Material material, ReturnCondition condition) {
        return Money.ZERO;      // yes, this is cheating. And it is correct in TDD.
    }
}

@Test
void minorDamageMeansTwentyPercentOfTheValue() {
    var material = aBook("978-0000000001").withValue(Money.euros("45.00"));

    Money surcharge = calculator.calculate(material, ReturnCondition.MINOR);

    assertThat(surcharge).isEqualTo(Money.euros("9.00"));     // 45 × 0.20
}

public enum ReturnCondition { UNDAMAGED, MINOR }

public class SurchargeCalculator {
    public Money calculate(Material material, ReturnCondition condition) {
        if (condition == ReturnCondition.UNDAMAGED) return Money.ZERO;
        return material.getValue().multiplyBy(new BigDecimal("0.20"));
    }
}

@ParameterizedTest
@CsvSource({
    "UNDAMAGED,      0.00",
    "MINOR,          9.00",
    "SEVERE,        27.00",
    "UNRECOVERABLE, 45.00"
})
void theSurchargeDependsOnTheReturnCondition(ReturnCondition condition, String expected) {
    var material = aBook("978-0000000001").withValue(Money.euros("45.00"));
    assertThat(calculator.calculate(material, condition)).isEqualTo(Money.euros(expected));
}

public Money calculate(Material material, ReturnCondition condition) {
    BigDecimal percentage = switch (condition) {
        case UNDAMAGED -> BigDecimal.ZERO;
        case MINOR -> new BigDecimal("0.20");
        case SEVERE -> new BigDecimal("0.60");
        case UNRECOVERABLE -> BigDecimal.ONE;
    };
    return material.getValue().multiplyBy(percentage);
}

public enum ReturnCondition {
    UNDAMAGED(BigDecimal.ZERO),
    MINOR(new BigDecimal("0.20")),
    SEVERE(new BigDecimal("0.60")),
    UNRECOVERABLE(BigDecimal.ONE);

    private final BigDecimal surchargePercentage;

    ReturnCondition(BigDecimal surchargePercentage) {
        this.surchargePercentage = surchargePercentage;
    }

    public BigDecimal surchargePercentage() { return surchargePercentage; }
    public boolean requiresWithdrawal() { return this == UNRECOVERABLE; }
}

public class SurchargeCalculator {
    public Money calculate(Material material, ReturnCondition condition) {
        return material.getValue().multiplyBy(condition.surchargePercentage());
    }
}

@Test
void theTotalOfFineAndSurchargeDoesNotExceedTheMaterialValue() {
    var material = aBook("978-0000000001").withValue(Money.euros("45.00"));
    var loan = aLoanOf(material).overdueBy(200);              // enormous fine

    Money total = calculator.totalToCharge(loan, ReturnCondition.SEVERE, TODAY);

    // fine (capped at €20) + surcharge (€27) = €47, but the material is worth €45
    assertThat(total).isEqualTo(Money.euros("45.00"));
}

public Money totalToCharge(Loan loan, ReturnCondition condition, LocalDate today) {
    Money fine = finePolicy.calculate(loan, today);
    Money surcharge = calculate(loan.getMaterial(), condition);
    Money total = fine.plus(surcharge);
    Money materialValue = loan.getMaterial().getValue();
    return total.isGreaterThan(materialValue) ? materialValue : total;
}

@Test
void anUnrecoverableMaterialIsWithdrawnFromTheCatalogue() {
    var material = aBook("978-0000000001").withValue(Money.euros("45.00"));
    var loan = aLoanOf(material);

    service.registerReturn(loan.getId(), ReturnCondition.UNRECOVERABLE, TODAY);

    assertThat(material.isWithdrawn()).isTrue();
    verify(catalog).withdraw(material.getIsbn(), WithdrawalReason.DAMAGED);
}

@Test
void aSeverelyDamagedMaterialStaysInTheCatalogue() {
    var material = aBook("978-0000000001");
    service.registerReturn(aLoanOf(material).getId(), ReturnCondition.SEVERE, TODAY);

    assertThat(material.isWithdrawn()).isFalse();
    verifyNoInteractions(catalog);
}

@Transactional
public ReturnResult registerReturn(Long loanId, ReturnCondition condition, LocalDate date) {
    Loan loan = repository.findById(loanId)
            .orElseThrow(() -> new LoanNotFoundException(loanId));

    loan.registerReturn(date);
    Money total = calculator.totalToCharge(loan, condition, date);

    if (condition.requiresWithdrawal()) {
        catalog.withdraw(loan.getIsbn(), WithdrawalReason.DAMAGED);
    }
    events.publish(new MaterialReturned(loan.getId(), condition, total));       // Observer
    return new ReturnResult(loan.getId(), date, total, condition);
}

./mvnw org.pitest:pitest-maven:mutationCoverage \
    -DtargetClasses=com.nexussoftware.bibliotech.domain.loans.*

SurchargeCalculator    : 100% mutation (8/8 mutants killed)
ReturnCondition        : 100% mutation (4/4)

## Code review — BiblioTech

### Correctness
- [ ] Does it do what the PR description says?
- [ ] Are the edge cases handled (empty, null, zero, negative, maximum)?
- [ ] Are exceptions caught at the right level (06-07)?
- [ ] Are there race conditions if this runs in parallel?

### Architecture
- [ ] Is it in the right module (domain / application / infrastructure)?
- [ ] Does the domain still avoid importing Spring or JPA?
- [ ] Are JPA entities exposed in the API? (they should not be)
- [ ] Is the transaction in the use case, not in the controller?

### Tests
- [ ] Are there tests for the happy path AND for the errors?
- [ ] Do the tests have meaningful assertions?
- [ ] Are they at the lowest possible level?
- [ ] Is an injectable `Clock` used instead of `LocalDate.now()`?

### Security (12-07)
- [ ] Is every external input validated?
- [ ] Are there secrets, tokens or personal data in the code or the log?
- [ ] Do the queries use parameters, never concatenation?

### Readability
- [ ] Do the names describe the intent?
- [ ] Does any method exceed 30 lines or complexity 10?
- [ ] Do the comments explain the "why", not the "what"?

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# Cancels earlier runs of the same PR: testing already-obsolete code makes no sense
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  JAVA_VERSION: '21'

jobs:

  # ---------------------------------------------------------------
  # Job 1: fast. Gives an answer in under 3 minutes.
  # ---------------------------------------------------------------
  fast-checks:
    name: Build, formatting and unit tests
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK ${{ env.JAVA_VERSION }}
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: temurin
          cache: maven              # caches ~/.m2: saves 1-2 minutes per run

      - name: Check formatting
        run: ./mvnw -B spotless:check

      - name: Compile
        run: ./mvnw -B clean compile

      - name: Unit tests
        run: ./mvnw -B test

      - name: Publish test results
        uses: mikepenz/action-junit-report@v4
        if: always()                # also when they fail: that is when it is needed most
        with:
          report_paths: '**/target/surefire-reports/TEST-*.xml'
          check_name: 'Unit tests'

  # ---------------------------------------------------------------
  # Job 2: slow. Testcontainers, coverage and static analysis.
  # ---------------------------------------------------------------
  full-checks:
    name: Integration, coverage and analysis
    runs-on: ubuntu-latest
    needs: fast-checks              # do not spend 10 minutes if it does not compile
    timeout-minutes: 25

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0            # Sonar needs the history for "new code"

      - uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: temurin
          cache: maven

      # Docker is already available on ubuntu-latest: Testcontainers just works

      - name: Integration tests and coverage
        run: ./mvnw -B verify
        env:
          TESTCONTAINERS_RYUK_DISABLED: 'false'

      - name: Check coverage thresholds
        run: ./mvnw -B jacoco:check

      - name: Publish coverage on the PR
        uses: madrapps/[email protected]
        if: github.event_name == 'pull_request'
        with:
          paths: '**/target/site/jacoco/jacoco.xml'
          token: ${{ secrets.GITHUB_TOKEN }}
          min-coverage-overall: 75
          min-coverage-changed-files: 80    # NEW code, held to a higher bar
          title: 'Coverage report'

      - name: Static analysis
        run: ./mvnw -B spotbugs:check

      - name: Store reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: reports
          path: |
            **/target/site/jacoco/
            **/target/spotbugsXml.xml
          retention-days: 7

  # ---------------------------------------------------------------
  # Job 3: main only. Mutation testing, which is slow.
  # ---------------------------------------------------------------
  mutation:
    name: Mutation testing
    runs-on: ubuntu-latest
    needs: full-checks
    if: github.ref == 'refs/heads/main'
    timeout-minutes: 30

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: temurin
          cache: maven

      - name: PIT over the domain
        run: ./mvnw -B -pl bibliotech-domain org.pitest:pitest-maven:mutationCoverage

      - uses: actions/upload-artifact@v4
        with:
          name: mutation-report
          path: '**/target/pit-reports/'

// BAD: it tests HOW it is done. Refactoring breaks it even if the behaviour does not change.
@Test
void usesTheRepositoryToSearch() {
    service.findByIsbn(isbn);
    verify(repository).findByIsbn(isbn);       // what if tomorrow it uses a cache?
}

// GOOD: it tests WHAT it does. It survives any internal refactor.
@Test
void returnsTheMaterialWhenItExists() {
    when(repository.findByIsbn(isbn)).thenReturn(Optional.of(effectiveJava));

    Optional<Material> result = service.findByIsbn(isbn);

    assertThat(result).contains(effectiveJava);
}

// FLAKY: fails on 1 January, or if the test runs at midnight
@Test
void theLoanFallsDueInFifteenDays() {
    Loan loan = manager.lend(isbn, 1L, 15);
    assertThat(loan.getDueDate()).isEqualTo(LocalDate.now().plusDays(15));
}

// ROBUST: time is a dependency like any other
@Test
void theLoanFallsDueInFifteenDays() {
    var clock = Clock.fixed(Instant.parse("2026-08-05T10:00:00Z"), ZoneId.of("Europe/Madrid"));
    var manager = new LoanManager(repository, notices, clock);

    Loan loan = manager.lend(isbn, 1L, 15);

    assertThat(loan.getDueDate()).isEqualTo(LocalDate.of(2026, 8, 20));
}

// FLAKY: 500 ms may not be enough on a loaded machine, and is wasted on a fast one
@Test
void theAsyncImportFinishes() throws Exception {
    service.importAsync(file);
    Thread.sleep(500);
    assertThat(repository.count()).isEqualTo(100);
}

// ROBUST: wait for the CONDITION, not for a duration
@Test
void theAsyncImportFinishes() {
    service.importAsync(file);

    await().atMost(Duration.ofSeconds(5))
           .pollInterval(Duration.ofMillis(50))
           .untilAsserted(() -> assertThat(repository.count()).isEqualTo(100));
}

class ReservationProcessorTest {

    ReservationProcessor processor = new ReservationProcessor(
            new InMemoryReservationRepository(), new FakeNotices());

    @Test
    void testReserve() {
        processor.reserve("978-0000000001", 1L);
    }

    @Test
    void testCancel() throws Exception {
        Reservation r = processor.reserve("978-0000000001", 1L);
        processor.cancel(r.getId());
        assertNotNull(r);
    }

    @Test
    void testExpiry() throws Exception {
        Reservation r = processor.reserve("978-0000000001", 1L);
        Thread.sleep(1000);
        processor.expireOverdue();
        assertTrue(true);
    }

    @Test
    void testDeadline() {
        Reservation r = processor.reserve("978-0000000001", 1L);
        assertEquals(LocalDate.now().plusDays(2), r.getDeadline());
    }
}

@DisplayName("Reservation processor")
class ReservationProcessorTest {

    // FIXED clock: removes any dependency on the moment of execution
    private static final Instant NOW = Instant.parse("2026-08-05T10:00:00Z");
    private static final ZoneId MADRID = ZoneId.of("Europe/Madrid");

    private InMemoryReservationRepository repository;
    private RecordingNotices notices;
    private MutableClock clock;                  // advanceable clock, no Thread.sleep
    private ReservationProcessor processor;

    @BeforeEach
    void setUp() {
        // FRESH state for every test: no contamination between them
        repository = new InMemoryReservationRepository();
        notices = new RecordingNotices();
        clock = MutableClock.at(NOW, MADRID);
        processor = new ReservationProcessor(repository, notices, clock);
    }

    @Nested
    @DisplayName("When creating a reservation")
    class WhenReserving {

        @Test
        @DisplayName("it is left pending and in the material's queue")
        void isPendingAndInTheQueue() {
            Reservation reservation = processor.reserve(ISBN_JAVA, MARTA);

            assertThat(reservation.getStatus()).isEqualTo(ReservationStatus.PENDING);
            assertThat(reservation.getMaterialIsbn()).isEqualTo(ISBN_JAVA);
            assertThat(reservation.getEmployeeId()).isEqualTo(MARTA);
            assertThat(reservation.getRequestDate()).isEqualTo(NOW);
            assertThat(repository.pendingFor(ISBN_JAVA)).containsExactly(reservation);
        }

        @Test
        @DisplayName("it respects the arrival order in the queue")
        void respectsTheArrivalOrder() {
            Reservation first = processor.reserve(ISBN_JAVA, MARTA);
            clock.advance(Duration.ofMinutes(5));
            Reservation second = processor.reserve(ISBN_JAVA, DIEGO);

            assertThat(repository.pendingFor(ISBN_JAVA))
                    .containsExactly(first, second);         // the order matters
        }

        @Test
        @DisplayName("it rejects a second reservation for the same employee and material")
        void rejectsDuplicateReservation() {
            processor.reserve(ISBN_JAVA, MARTA);

            assertThatThrownBy(() -> processor.reserve(ISBN_JAVA, MARTA))
                    .isInstanceOf(DuplicateReservationException.class)
                    .hasMessageContaining(ISBN_JAVA.value());

            assertThat(repository.pendingFor(ISBN_JAVA)).hasSize(1);
        }

        @Test
        @DisplayName("it rejects reserving a material that does not exist")
        void rejectsUnknownMaterial() {
            assertThatThrownBy(() -> processor.reserve(ISBN_UNKNOWN, MARTA))
                    .isInstanceOf(MaterialNotFoundException.class);
        }
    }

    @Nested
    @DisplayName("When cancelling")
    class WhenCancelling {

        @Test
        @DisplayName("the reservation moves to CANCELLED and leaves the queue")
        void movesToCancelledAndLeavesTheQueue() {
            Reservation reservation = processor.reserve(ISBN_JAVA, MARTA);

            processor.cancel(reservation.getId());

            assertThat(repository.byId(reservation.getId()))
                    .get()
                    .extracting(Reservation::getStatus)
                    .isEqualTo(ReservationStatus.CANCELLED);
            assertThat(repository.pendingFor(ISBN_JAVA)).isEmpty();
        }

        @Test
        @DisplayName("cancelling twice throws InvalidTransitionException")
        void cancellingTwiceFails() {
            Reservation reservation = processor.reserve(ISBN_JAVA, MARTA);
            processor.cancel(reservation.getId());

            assertThatThrownBy(() -> processor.cancel(reservation.getId()))
                    .isInstanceOf(InvalidTransitionException.class);
        }

        @Test
        @DisplayName("cancelling a reservation that does not exist throws ReservationNotFoundException")
        void unknownReservation() {
            assertThatThrownBy(() -> processor.cancel(9999L))
                    .isInstanceOf(ReservationNotFoundException.class);
        }
    }

    @Nested
    @DisplayName("Expiry")
    class Expiry {

        @Test
        @DisplayName("an available reservation expires after exactly 48 hours")
        void expiresAfter48Hours() {
            Reservation reservation = processor.reserve(ISBN_JAVA, MARTA);
            processor.assignCopy(reservation.getId());

            clock.advance(Duration.ofHours(48));         // no Thread.sleep!
            int expired = processor.expireOverdue();

            assertThat(expired).isEqualTo(1);
            assertThat(repository.byId(reservation.getId()))
                    .get().extracting(Reservation::getStatus)
                    .isEqualTo(ReservationStatus.EXPIRED);
        }

        @Test
        @DisplayName("at 47 hours and 59 minutes it has NOT expired yet")
        void doesNotExpireEarly() {
            Reservation reservation = processor.reserve(ISBN_JAVA, MARTA);
            processor.assignCopy(reservation.getId());

            clock.advance(Duration.ofHours(47).plusMinutes(59));
            int expired = processor.expireOverdue();

            assertThat(expired).isZero();                // THE BOUNDARY
            assertThat(repository.byId(reservation.getId()))
                    .get().extracting(Reservation::getStatus)
                    .isEqualTo(ReservationStatus.AVAILABLE);
        }

        @Test
        @DisplayName("pending reservations do not expire: they have no deadline")
        void pendingOnesDoNotExpire() {
            processor.reserve(ISBN_JAVA, MARTA);         // PENDING, no copy assigned

            clock.advance(Duration.ofDays(30));

            assertThat(processor.expireOverdue()).isZero();
        }

        @Test
        @DisplayName("on expiry the employee is notified and the next in the queue is activated")
        void notifiesAndActivatesTheNextOne() {
            Reservation martasOne = processor.reserve(ISBN_JAVA, MARTA);
            Reservation diegosOne = processor.reserve(ISBN_JAVA, DIEGO);
            processor.assignCopy(martasOne.getId());

            clock.advance(Duration.ofHours(48));
            processor.expireOverdue();

            assertThat(notices.sent())
                    .extracting(Notice::type)
                    .containsExactly(NoticeType.RESERVATION_EXPIRED, NoticeType.RESERVATION_AVAILABLE);
            assertThat(repository.byId(diegosOne.getId()))
                    .get().extracting(Reservation::getStatus)
                    .isEqualTo(ReservationStatus.AVAILABLE);
        }
    }

    @Nested
    @DisplayName("Collection deadline")
    class CollectionDeadline {

        @Test
        @DisplayName("it is set 48 hours from the copy assignment")
        void at48HoursFromTheAssignment() {
            Reservation reservation = processor.reserve(ISBN_JAVA, MARTA);
            clock.advance(Duration.ofDays(3));           // the assignment arrives days later
            processor.assignCopy(reservation.getId());

            // ABSOLUTE date computed from the fixed clock: never depends on "today"
            assertThat(repository.byId(reservation.getId()))
                    .get().extracting(Reservation::getCollectionDeadline)
                    .isEqualTo(NOW.plus(Duration.ofDays(3)).plus(Duration.ofHours(48)));
        }

        @Test
        @DisplayName("a pending reservation has no deadline")
        void pendingOnesHaveNoDeadline() {
            Reservation reservation = processor.reserve(ISBN_JAVA, MARTA);
            assertThat(reservation.getCollectionDeadline()).isNull();
        }
    }
}

/** Mutable Clock for tests: lets you move time forward without waiting. */
public class MutableClock extends Clock {

    private Instant current;
    private final ZoneId zone;

    private MutableClock(Instant current, ZoneId zone) {
        this.current = current;
        this.zone = zone;
    }

    public static MutableClock at(Instant current, ZoneId zone) {
        return new MutableClock(current, zone);
    }

    public void advance(Duration duration) { this.current = current.plus(duration); }

    @Override public Instant instant() { return current; }
    @Override public ZoneId getZone() { return zone; }
    @Override public Clock withZone(ZoneId z) { return new MutableClock(current, z); }
}

@Test
void anEmployeeWithoutACriticalProjectCannotUsePriority() {
    Employee diego = anEmployee("Diego Alonso").withoutCriticalProjects();

    assertThatThrownBy(() -> service.lendWithPriority(ISBN_JAVA, diego.getId()))
            .isInstanceOf(NoPriorityAvailableException.class)
            .hasMessageContaining("has no active critical project");
}

public Loan lendWithPriority(Isbn isbn, Long employeeId) {
    Employee employee = employees.findById(employeeId).orElseThrow(…);
    if (!employee.hasActiveCriticalProject()) {
        throw new NoPriorityAvailableException(
                "Employee %s has no active critical project."
                        .formatted(employee.getName()));
    }
    return null;   // the minimum for the test to pass
}

@Test
void ifTheMaterialIsFreeItIsANormalLoanAndNoPriorityIsSpent() {
    Employee marta = anEmployee("Marta Ruiz").withCriticalProject();
    materialAvailable(ISBN_JAVA);

    Loan loan = service.lendWithPriority(ISBN_JAVA, marta.getId());

    assertThat(loan.isPriority()).isFalse();
    assertThat(marta.prioritiesInUse()).isZero();        // the priority was NOT spent
}

public Loan lendWithPriority(Isbn isbn, Long employeeId) {
    Employee employee = …;
    checkHasCriticalProject(employee);

    Material material = materials.findByIsbn(isbn).orElseThrow(…);
    if (material.hasFreeCopies()) {
        return loanManager.lend(isbn, employeeId, null);          // normal loan
    }
    return null;
}

@Test
void flagsTheLoanInProgressForUrgentReturnWithinFortyEightHours() {
    Employee marta = anEmployee("Marta Ruiz").withCriticalProject();
    Loan inProgress = activeLoanOf(ISBN_JAVA, DIEGO);
    materialWithNoFreeCopies(ISBN_JAVA);

    service.lendWithPriority(ISBN_JAVA, marta.getId());

    assertThat(inProgress.isUrgent()).isTrue();
    assertThat(inProgress.getDueDate())
            .isEqualTo(LocalDate.now(clock).plusDays(2));
}

@Test
void notifiesTheEmployeeHoldingTheMaterial() {
    Employee marta = anEmployee("Marta Ruiz").withCriticalProject();
    activeLoanOf(ISBN_JAVA, DIEGO);
    materialWithNoFreeCopies(ISBN_JAVA);

    service.lendWithPriority(ISBN_JAVA, marta.getId());

    assertThat(notices.sent())
            .singleElement()
            .satisfies(n -> {
                assertThat(n.type()).isEqualTo(NoticeType.URGENT_RETURN);
                assertThat(n.recipient()).isEqualTo(DIEGO.getEmail());
            });
}

public Loan lendWithPriority(Isbn isbn, Long employeeId) {
    Employee employee = …;
    checkHasCriticalProject(employee);

    Material material = …;
    if (material.hasFreeCopies()) {
        return loanManager.lend(isbn, employeeId, null);
    }

    Loan inProgress = loans.activeFor(isbn).orElseThrow(…);
    inProgress.markUrgent(LocalDate.now(clock).plusDays(2));
    notices.send(Notice.urgentReturn(inProgress));

    return Loan.priorityWaiting(material, employee, LocalDate.now(clock));
}

@Test
void anEmployeeCannotHoldTwoSimultaneousPriorities() {
    Employee marta = anEmployee("Marta Ruiz").withCriticalProject().withPriorityInUse();
    materialWithNoFreeCopies(ISBN_JAVA);

    assertThatThrownBy(() -> service.lendWithPriority(ISBN_JAVA, marta.getId()))
            .isInstanceOf(PriorityAlreadyInUseException.class);
}

@Test
void priorityCannotBeUsedOnAMaterialAlreadyFlaggedAsUrgent() {
    Employee marta = anEmployee("Marta Ruiz").withCriticalProject();
    activeLoanOf(ISBN_JAVA, DIEGO).alreadyMarkedUrgent();
    materialWithNoFreeCopies(ISBN_JAVA);

    assertThatThrownBy(() -> service.lendWithPriority(ISBN_JAVA, marta.getId()))
            .isInstanceOf(MaterialAlreadyUrgentException.class)
            .hasMessageContaining("already has an urgent return in progress");
}

@Service
public class PriorityLoanService {

    private final List<PriorityCheck> checks;                   // Chain of Responsibility
    private final Clock clock;

    @Transactional
    public Loan lendWithPriority(Isbn isbn, Long employeeId) {
        PriorityContext ctx = buildContext(isbn, employeeId);

        // If the material is free, there is nothing to check: normal loan
        if (ctx.material().hasFreeCopies()) {
            return loanManager.lend(isbn, employeeId, null);
        }

        // Each check throws its own specific exception
        checks.forEach(c -> c.check(ctx));

        return activatePriority(ctx);
    }

    private Loan activatePriority(PriorityContext ctx) {
        LocalDate deadline = LocalDate.now(clock).plusDays(2);
        ctx.loanInProgress().markUrgent(deadline);
        ctx.employee().consumePriority();
        notices.send(Notice.urgentReturn(ctx.loanInProgress(), deadline));
        events.publish(new PriorityActivated(ctx.isbn(), ctx.employee().getId(), deadline));
        return Loan.priorityWaiting(ctx.material(), ctx.employee(), LocalDate.now(clock));
    }
}

@Component @Order(10)
class CheckCriticalProject implements PriorityCheck {
    public void check(PriorityContext ctx) {
        if (!ctx.employee().hasActiveCriticalProject()) {
            throw new NoPriorityAvailableException(ctx.employee().getName());
        }
    }
}

@Component @Order(20)
class CheckPriorityAvailable implements PriorityCheck {
    public void check(PriorityContext ctx) {
        if (ctx.employee().prioritiesInUse() >= 1) {
            throw new PriorityAlreadyInUseException(ctx.employee().getName());
        }
    }
}

@Component @Order(30)
class CheckMaterialNotUrgent implements PriorityCheck {
    public void check(PriorityContext ctx) {
        if (ctx.loanInProgress().isUrgent()) {
            throw new MaterialAlreadyUrgentException(ctx.isbn());
        }
    }
}

@Test
void afterUsingThePriorityTheEmployeeCannotUseAnother() {
    Employee marta = anEmployee("Marta Ruiz").withCriticalProject();
    materialWithNoFreeCopies(ISBN_JAVA);
    materialWithNoFreeCopies(ISBN_PATTERNS);

    service.lendWithPriority(ISBN_JAVA, marta.getId());

    assertThatThrownBy(() -> service.lendWithPriority(ISBN_PATTERNS, marta.getId()))
            .isInstanceOf(PriorityAlreadyInUseException.class);
}

@Test
void publishesThePriorityActivatedEvent() {
    Employee marta = anEmployee("Marta Ruiz").withCriticalProject();
    activeLoanOf(ISBN_JAVA, DIEGO);
    materialWithNoFreeCopies(ISBN_JAVA);

    service.lendWithPriority(ISBN_JAVA, marta.getId());

    assertThat(events.published())
            .singleElement(as(InstanceOfAssertFactories.type(PriorityActivated.class)))
            .satisfies(e -> {
                assertThat(e.isbn()).isEqualTo(ISBN_JAVA);
                assertThat(e.deadline()).isEqualTo(LocalDate.of(2026, 8, 7));      // EXACT date
            });
}

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 4 * * 1'        # Mondays at 04:00 UTC: mutation testing

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read
  pull-requests: write         # needed to comment on the PR
  checks: write

jobs:

  # =====================================================================
  # 1. FAST — an answer in under 3 minutes
  # =====================================================================
  fast:
    name: Formatting and unit tests
    runs-on: ubuntu-latest
    timeout-minutes: 8

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: temurin
          cache: maven

      - name: Check formatting
        run: ./mvnw -B --no-transfer-progress spotless:check

      - name: Compile and unit tests
        run: ./mvnw -B --no-transfer-progress test

      - name: Publish results
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: '**/target/surefire-reports/TEST-*.xml'
          check_name: 'Unit tests'
          detailed_summary: true

  # =====================================================================
  # 2. MATRIX — Java 21 (production) and Java 23 (early warning)
  # =====================================================================
  compatibility:
    name: Java ${{ matrix.java }}
    runs-on: ubuntu-latest
    needs: fast
    timeout-minutes: 15

    strategy:
      fail-fast: false            # a failure on 23 must not cancel the 21 run
      matrix:
        java: ['21', '23']

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: ${{ matrix.java }}
          distribution: temurin
          cache: maven

      - name: Unit tests
        run: ./mvnw -B --no-transfer-progress test
        # Java 23 is informational: it must not block the merge
        continue-on-error: ${{ matrix.java == '23' }}

  # =====================================================================
  # 3. FULL — integration with Testcontainers, coverage and analysis
  # =====================================================================
  full:
    name: Integration, coverage and analysis
    runs-on: ubuntu-latest
    needs: fast
    timeout-minutes: 25

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: temurin
          cache: maven

      # Pre-pull the image: stops the first test carrying the 30 s download
      - name: Pre-pull the PostgreSQL image
        run: docker pull postgres:16-alpine

      - name: Integration tests and coverage
        run: ./mvnw -B --no-transfer-progress verify
        env:
          TESTCONTAINERS_REUSE_ENABLE: 'false'      # in CI, clean containers

      - name: Comment the coverage on the PR
        uses: madrapps/[email protected]
        if: github.event_name == 'pull_request'
        with:
          paths: '**/target/site/jacoco/jacoco.xml'
          token: ${{ secrets.GITHUB_TOKEN }}
          min-coverage-overall: 75
          min-coverage-changed-files: 80
          title: '📊 Coverage'
          update-comment: true                      # updates instead of piling up comments
          pass-emoji: '✅'
          fail-emoji: '❌'

      - name: Check coverage thresholds
        run: ./mvnw -B jacoco:check

      - name: Static analysis (SpotBugs + FindSecBugs)
        run: ./mvnw -B spotbugs:check

      - name: Architecture rules (ArchUnit)
        run: ./mvnw -B test -Dtest='ArchitectureRulesTest'

      - name: Store reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: quality-reports
          path: |
            **/target/site/jacoco/
            **/target/spotbugsXml.xml
            **/target/failsafe-reports/
          retention-days: 14

      - name: Summary on the run tab
        if: always()
        run: |
          echo "## Quality summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Check | Result |" >> $GITHUB_STEP_SUMMARY
          echo "|---|---|" >> $GITHUB_STEP_SUMMARY
          echo "| Unit tests | ${{ needs.fast.result }} |" >> $GITHUB_STEP_SUMMARY
          echo "| Integration | ${{ job.status }} |" >> $GITHUB_STEP_SUMMARY

  # =====================================================================
  # 4. MUTATION — Mondays and main only. It is slow.
  # =====================================================================
  mutation:
    name: Mutation testing (PIT)
    runs-on: ubuntu-latest
    if: github.event_name == 'schedule' || github.ref == 'refs/heads/main'
    timeout-minutes: 40

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: temurin
          cache: maven

      - name: PIT over the domain
        run: |
          ./mvnw -B -pl bibliotech-domain \
            org.pitest:pitest-maven:mutationCoverage \
            -DmutationThreshold=70

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: mutation-report
          path: '**/target/pit-reports/'
          retention-days: 30

      - name: Open an issue if it drops below the threshold
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: '⚠️ Domain mutation coverage dropped below 70%',
              body: 'Check the PIT report in the artifacts of run ' +
                    context.runId + '. There are surviving mutants: the assertions ' +
                    'in some test do not detect changes in the code.',
              labels: ['quality', 'testing']
            })