SpringBootTest

// MOCK (default): in-process, @WithMockUser works
@SpringBootTest
@AutoConfigureMockMvc
class UserMockMvcTest {

    @Autowired MockMvc mockMvc;

    @Test
    @WithMockUser(roles = "ADMIN")
    void adminCanList() throws Exception {
        mockMvc.perform(get("/api/users")).andExpect(status().isOk());
    }

    // If CSRF protection is on, state-changing requests also need: .with(csrf())
}

// RANDOM_PORT: real server, so authenticate for real. @WithMockUser would be ignored here.
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserHttpTest {

    @Autowired TestRestTemplate rest;

    @Test
    void adminCanList() {
        String token = login("admin@example.com", "password");     // your helper: POST /api/auth/login
        HttpHeaders headers = new HttpHeaders();
        headers.setBearerAuth(token);

        ResponseEntity<UserResponse[]> response = rest.exchange(
            "/api/users", HttpMethod.GET, new HttpEntity<>(headers), UserResponse[].class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    }
}

// NONE: no web layer. Good for services, consumers, schedulers.
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
class PricingServiceTest { ... }

// Notes:
//  - TestRestTemplate and WebTestClient both work against RANDOM_PORT. WebTestClient needs
//    spring-webflux on the test classpath even for MVC apps.
//  - On Spring Boot 4 the test auto-configuration annotations and TestRestTemplate moved into
//    separate test modules; if imports stop resolving after an upgrade, check the migration guide.

@TestConfiguration(proxyBeanMethods = false)
public class TestcontainersConfig {

    @Bean
    @ServiceConnection
    PostgreSQLContainer<?> postgres() {
        return new PostgreSQLContainer<>("postgres:16-alpine");   // .withReuse(true) speeds up local reruns
    }
}

@SpringBootTest
@AutoConfigureMockMvc
@Import(TestcontainersConfig.class)
@ActiveProfiles("test")
public abstract class AbstractIntegrationTest {
    @Autowired protected MockMvc mockMvc;
    @Autowired protected ObjectMapper objectMapper;
}

@Transactional                                   // MockMvc runs in the test thread, so this rolls back
class UserIntegrationTest extends AbstractIntegrationTest {

    @Autowired UserRepository userRepository;

    @Test
    @WithMockUser(roles = "ADMIN")
    void createThenFetch() throws Exception {
        var request = new CreateUserRequest("Alice", "alice@example.com", "password123");

        String location = mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))
            .andExpect(status().isCreated())
            .andReturn().getResponse().getHeader("Location");

        mockMvc.perform(get(location))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("Alice"))
            .andExpect(jsonPath("$.email").value("alice@example.com"));

        assertThat(userRepository.findByEmail("alice@example.com")).isPresent();
    }

    @Test
    @WithMockUser(roles = "ADMIN")
    void updatePersistsChanges() throws Exception {
        UserEntity saved = userRepository.saveAndFlush(
            UserEntity.builder().name("Bob").email("bob@example.com").build());

        mockMvc.perform(put("/api/users/" + saved.getId())
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(new UpdateUserRequest("Robert", null))))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("Robert"));
    }

    @Test
    @WithMockUser(roles = "USER")
    void nonAdminCannotDelete() throws Exception {
        mockMvc.perform(delete("/api/users/1")).andExpect(status().isForbidden());
    }
}

// Option 1: replace the client bean. Fast, but skips the HTTP layer.
class OrderIntegrationTest extends AbstractIntegrationTest {

    @MockitoBean UserClient userClient;
    @MockitoBean InventoryClient inventoryClient;
    @MockitoBean PaymentClient paymentClient;

    @BeforeEach
    void stubs() {
        when(userClient.findById(1L)).thenReturn(new UserResponse(1L, "Alice", "alice@example.com"));
        when(inventoryClient.checkStock(10L)).thenReturn(new InventoryResponse(10L, true, 5));
        when(paymentClient.charge(any())).thenReturn(new PaymentResponse(PaymentStatus.SUCCESS));
    }

    @Test
    @WithMockUser(username = "1", roles = "USER")
    void placeOrder_persistsAndCallsDependencies() throws Exception {
        mockMvc.perform(post("/api/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"userId\":1,\"productId\":10,\"quantity\":2}"))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.status").value("CONFIRMED"));

        verify(paymentClient).charge(any());
    }

    @Test
    @WithMockUser(username = "1", roles = "USER")
    void placeOrder_outOfStock_returns409_andPaymentIsNeverCalled() throws Exception {
        when(inventoryClient.checkStock(10L)).thenReturn(new InventoryResponse(10L, false, 0));

        mockMvc.perform(post("/api/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"userId\":1,\"productId\":10,\"quantity\":2}"))
            .andExpect(status().isConflict());

        verifyNoInteractions(paymentClient);            // the important assertion
    }
}

// Option 2: fake the remote service over real HTTP with WireMock. Tests serialization,
// error handling and your retry/circuit-breaker settings.
class InventoryHttpTest extends AbstractIntegrationTest {

    @RegisterExtension
    static WireMockExtension inventory = WireMockExtension.newInstance()
        .options(wireMockConfig().dynamicPort()).build();

    @DynamicPropertySource
    static void clientUrls(DynamicPropertyRegistry registry) {
        registry.add("clients.inventory.url", inventory::baseUrl);     // use your own property name
    }

    @Test
    @WithMockUser(roles = "USER")
    void inventoryServerError_returns503() throws Exception {
        inventory.stubFor(get(urlEqualTo("/stock/10")).willReturn(serverError()));

        mockMvc.perform(post("/api/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"userId\":1,\"productId\":10,\"quantity\":1}"))
            .andExpect(status().isServiceUnavailable());
    }
}

# src/test/resources/application-test.yml
spring:
  jpa:
    show-sql: false              # turn on temporarily while debugging
    hibernate:
      ddl-auto: validate         # let Flyway own the schema, same as production
  flyway:
    enabled: true

logging:
  level:
    org.hibernate.SQL: DEBUG     # optional while debugging

# Your own switches, honoured only if your code reads them:
app:
  scheduling:
    enabled: false
  security:
    bcrypt-strength: 4           # faster password hashing in tests (default cost is 10)

// The guard that makes app.scheduling.enabled actually work
@Configuration
@EnableScheduling
@ConditionalOnProperty(name = "app.scheduling.enabled", havingValue = "true", matchIfMissing = true)
class SchedulingConfig {}

// One-off override for a single class (creates a separate context, so use sparingly)
@TestPropertySource(properties = "app.feature.new-checkout=true")
class CheckoutFeatureFlagTest extends AbstractIntegrationTest { ... }

# See whether contexts are being reused
logging:
  level:
    org.springframework.test.context.cache: DEBUG

// Typical split in a healthy suite
//   @WebMvcTest(UserController.class)    controller, validation, JSON, security rules  (fast)
//   @DataJpaTest + Testcontainers        repositories and custom queries               (fast-ish)
//   @SpringBootTest + shared base class  a few end-to-end flows per feature            (slow, keep few)

// Things that each create a NEW context:
//   different @ActiveProfiles           different @TestPropertySource
//   different @MockitoBean set          different @Import / @TestConfiguration
//   @DirtiesContext                     different webEnvironment