junit5-testcontainers-patterns

JUnit 5 + Testcontainers patterns

Choose the smallest scope that covers the AC

AC type	Use
Pure logic (calculator, validator, mapper)	Plain JUnit 5, no Spring
Controller validation, status codes, JSON shape	@WebMvcTest
JPA query / mapping	@DataJpaTest + Testcontainers (@ServiceConnection)
End-to-end through HTTP, with DB / external	@SpringBootTest(webEnvironment = RANDOM_PORT) + Testcontainers
Cache, security filter chain, bean wiring	targeted slice (e.g. @WebMvcTest + @Import)

@SpringBootTest is a last resort. If a slice test can cover it, use the slice.

Naming + traceability

• Every @Test and @ParameterizedTest method MUST carry @DisplayName. No exceptions — write the display name before the test body so articulating it forces clarity about what the test verifies. (Project rule: feedback_displayname_on_every_test.md.)

• The full annotation block on every test method is all three lines, in this order:

  @Test
  @Tag("AC-007")
  @DisplayName("AC-007: given expired gift card, when applied, then returns 4xx")
  void appliesExpiredGiftCard() { ... }
  

• Display-name format for AC-traced tests: "<T-ID>: given <precondition>, when <action>, then <outcome>". Short BDD-style sentence is acceptable for utility/regression tests not tied to a specific AC.

• @Tag("AC-NNN") makes the test machine-readable for the traceability matrix.

• One AC per test method when feasible.

• The simplify phase audits every newly-authored or modified test in the diff for @DisplayName — that's the safety net if the red phase missed it.

Testcontainers with @ServiceConnection (Spring Boot 4)

@DataJpaTest
@Testcontainers
class GiftCardRepositoryTest {

    @Container @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17-alpine");

    @Autowired GiftCardRepository repo;

    @Test
    @DisplayName("AC-004: given a new gift card, when saved and reloaded, then balance is preserved")
    @Tag("AC-004")
    void persistsBalance() {
        var saved = repo.save(GiftCard.with(BigDecimal.valueOf(100)));
        assertThat(repo.findById(saved.id()).orElseThrow().balance())
            .isEqualByComparingTo("100");
    }
}