spring-boot-integration

name: spring-boot-integration description: | Spring Boot integration testing with Testcontainers, sliced tests, and full context. Covers real database testing, API integration, and end-to-end flows.

USE WHEN: user mentions "spring integration test", "testcontainers spring", "full context test", asks about "@SpringBootTest webEnvironment", "integration test database", "API integration test"

DO NOT USE FOR: Unit tests - use junit; Slice tests only - use spring-boot-test; REST client testing - use rest-assured; E2E browser tests - use Selenium allowed-tools: Read, Grep, Glob, Write, Edit

Spring Boot Integration Testing

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: spring-boot-test for comprehensive documentation.

When NOT to Use This Skill

• Pure Unit Tests - Use junit with Mockito for isolated tests
• Slice Tests Only - Use spring-boot-test for @WebMvcTest, @DataJpaTest
• REST Client Testing - Use rest-assured for HTTP/API testing
• E2E Browser Tests - Use Selenium or Playwright
• Contract Testing - Use Spring Cloud Contract

Test Annotations

Full Context

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class FullIntegrationTest {
    @LocalServerPort
    private int port;

    @Autowired
    private TestRestTemplate restTemplate;
}

Sliced Tests

// Controller layer only
@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean UserService userService;
}

// Repository layer only
@DataJpaTest
class UserRepositoryTest {
    @Autowired TestEntityManager entityManager;
    @Autowired UserRepository repository;
}

// MongoDB layer only
@DataMongoTest
class ProductRepositoryTest {
    @Autowired MongoTemplate mongoTemplate;
}

// JSON serialization
@JsonTest
class UserJsonTest {
    @Autowired JacksonTester<User> json;
}

MockMvc Patterns

GET Request

mockMvc.perform(get("/api/users/{id}", 1)
        .accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    .andExpect(jsonPath("$.name").value("John"))
    .andExpect(jsonPath("$.email").value("john@email.com"));

POST Request

mockMvc.perform(post("/api/users")
        .contentType(MediaType.APPLICATION_JSON)
        .content("""
            {"name": "John", "email": "john@email.com"}
            """))
    .andExpect(status().isCreated())
    .andExpect(header().exists("Location"))
    .andExpect(jsonPath("$.id").isNumber());

With Authentication

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

// Or with custom user
mockMvc.perform(get("/api/profile")
        .with(user("john").roles("USER")))
    .andExpect(status().isOk());

Error Handling

@Test
void shouldReturn404WhenNotFound() throws Exception {
    when(userService.findById(99L))
        .thenThrow(new ResourceNotFoundException("User not found"));

    mockMvc.perform(get("/api/users/99"))
        .andExpect(status().isNotFound())
        .andExpect(jsonPath("$.message").value("User not found"));
}

@DataJpaTest Patterns

With Real Database

@DataJpaTest
@AutoConfigureTestDatabase(replace = Replace.NONE) // Don't replace with H2
@Testcontainers
class UserRepositoryTest {

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

    @Autowired
    private UserRepository repository;

    @Test
    void shouldFindByEmail() {
        repository.save(new User("John", "john@email.com"));

        Optional<User> found = repository.findByEmail("john@email.com");

        assertThat(found).isPresent();
    }

    @Test
    void shouldFindActiveUsers() {
        repository.save(User.builder().name("Active").active(true).build());
        repository.save(User.builder().name("Inactive").active(false).build());

        List<User> active = repository.findByActiveTrue();

        assertThat(active).hasSize(1);
    }
}

Custom Queries

@Test
void shouldExecuteCustomQuery() {
    repository.save(new User("John", "john@example.com"));
    repository.save(new User("Jane", "jane@example.com"));

    List<User> users = repository.findByEmailDomain("example.com");

    assertThat(users).hasSize(2);
}

WebEnvironment Options

Test Properties

Inline Properties

@SpringBootTest(properties = {
    "spring.datasource.url=jdbc:h2:mem:test",
    "logging.level.org.springframework=DEBUG"
})
class TestWithProperties {
}

Profile-based

@SpringBootTest
@ActiveProfiles("test")
class TestWithProfile {
}

application-test.yml

spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true
  sql:
    init:
      mode: always

Common Assertions

Response Body

.andExpect(jsonPath("$.name").value("John"))
.andExpect(jsonPath("$.items").isArray())
.andExpect(jsonPath("$.items", hasSize(3)))
.andExpect(jsonPath("$.items[0].name").value("Item 1"))
.andExpect(jsonPath("$.total").value(greaterThan(0)))

Headers

.andExpect(header().string("Content-Type", "application/json"))
.andExpect(header().exists("X-Custom-Header"))

Status

.andExpect(status().isOk())           // 200
.andExpect(status().isCreated())      // 201
.andExpect(status().isNoContent())    // 204
.andExpect(status().isBadRequest())   // 400
.andExpect(status().isUnauthorized()) // 401
.andExpect(status().isForbidden())    // 403
.andExpect(status().isNotFound())     // 404

Anti-Patterns

Quick Troubleshooting

Reference Documentation

• Spring Boot Testing Reference