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

Option Server Use Case

MOCK

No MockMvc testing

RANDOM_PORT

Yes, random port Full integration

DEFINED_PORT

Yes, configured port Specific port needed

NONE

No Non-web testing

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

Anti-Pattern Why It's Bad Solution

Using @SpringBootTest for unit tests Extremely slow Use @ExtendWith(MockitoExtension.class)

Hardcoding ports Port conflicts Use webEnvironment = RANDOM_PORT

Using H2 for DB-specific features False confidence Use Testcontainers with real DB

No data cleanup between tests Tests interfere Use @Transactional or manual cleanup

Not using @ServiceConnection Manual configuration Let Spring auto-configure from container

Testing with production profile Dangerous side effects Use @ActiveProfiles("test")

Ignoring test execution time Slow CI/CD Optimize with slice tests, parallelize

Quick Troubleshooting

Problem Likely Cause Solution

Tests very slow Full context for everything Use slice tests where possible

"Port already in use" Hardcoded port Use RANDOM_PORT

Flaky tests Shared state or timing Isolate data, use @Transactional

"Bean not found" Wrong context configuration Check @Import or component scan

Container won't start Docker not running Start Docker daemon

"Connection refused" Wrong host/port Use container.getHost(), getMappedPort()

Reference Documentation

• Spring Boot Testing Reference