Spring Boot 애플리케이션을 개발하면서 컨트롤러 레이어만 빠르게 검증하기 위해 @WebMvcTest를 실행했다가 UnsatisfiedDependencyException이나 401 Unauthorized 에러로 테스트가 차단된 경험이 있을 것이다.
전체 컨텍스트를 띄우는 @SpringBootTest보다 가볍게 동작할 것이라 기대했지만, 막상 실행해보면 의존성 주입 실패나 스프링 시큐리티 필터와의 충돌로 테스트가 터지곤 한다.
다만 많은 개발자들이 정확한 원인이나 해결책을 모른 채 전체 DB와 서비스 레이어까지 모두 띄우는 무거운 테스트로 되돌아가거나 테스트 작성을 포기하곤 한다.
이번에는 @WebMvcTest의 동작 원리가 정확히 뭔지, 왜 시큐리티와 의존성 오류가 발생하며, 이를 어떻게 완벽하게 해결하고 가벼운 슬라이스 테스트를 작성할 수 있는지 완벽하게 정리해서 소개하겠다.
스프링 부트 테스트는 크게 전체 통합 테스트와 레이어별 슬라이스 테스트(Slice Test)로 나뉜다. 대규모 프로젝트일수록 전체 통합 테스트는 빌드 및 CI 파이프라인 시간을 크게 늘린다.
컨트롤러의 URL 매핑, 요청 파라미터 바인딩, HTTP 응답 상태 코드, JSON 직렬화만 빠르게 검증하고 싶다면 @WebMvcTest를 사용하는 것이 올바른 선택이다.
| 구분 | @SpringBootTest | @WebMvcTest |
|---|---|---|
| 스캔 범위 | 모든 빈(@Component, @Service, @Repository 등) | 웹 관련 빈(@Controller, @ControllerAdvice, Filter 등) |
| 실행 속도 | 상대적으로 느림 (전체 컨텍스트 로딩) | 매우 빠름 (웹 레이어만 로딩) |
| DB 및 서비스 주입 | 실제 빈 주입 또는 테스트 DB 연결 | 서비스/리포지토리 빈을 로딩하지 않음 (Mocking 필요) |
| 주요 용도 | 엔드투엔드(E2E) 및 전체 통합 검증 | HTTP 요청/응답 및 컨트롤러 로직 단독 검증 |
@WebMvcTest 실행 시 대표적으로 두 가지 문제가 발생한다.
첫째, 컨트롤러가 주입받는 Service나 Component 빈을 스프링 컨텍스트가 찾지 못해 UnsatisfiedDependencyException이 발생하는 현상이다. @WebMvcTest는 @Service나 @Repository 클래스를 스캔하지 않기 때문이다.
둘째, Spring Security가 프로젝트에 포함되어 있는 경우, 테스트 환경에서 HTTP 요청을 보낼 때 401 Unauthorized 또는 403 Forbidden 에러가 발생한다. 기본 보안 필터 체인이 작동하여 인증되지 않은 요청을 차단하기 때문이다.
이 문제를 해결하려면 @MockBean을 사용해 컨트롤러가 의존하는 서비스 클래스를 가짜 객체로 대체하고, @WithMockUser 또는 SecurityCustomizer를 통해 테스트용 인증 세션을 부여해야 한다.
사용자 프로필 조회를 담당하는 컨트롤러 테스트 코드를 작성하면서 발생할 수 있는 실패 케이스와 올바른 구현 방식을 살펴본다.
✗ 잘못된 코드: 의존하는 서비스 클래스에 대한 Mocking이 누락되어 스프링 컨텍스트 로딩에 실패하거나, Security 인증 처리가 없어 401 에러로 테스트가 실패한다.
package com.example.demo.controller;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@WebMvcTest(UserController.class)
class UserControllerTest {
@Autowired
private MockMvc mockMvc;
// ✗ UserService 빈이 주입되지 않아 Context load failure 발생
// ✗ Security 인증 헤더나 Mock User가 없어 401 Unauthorized 발생
@Test
void getUserProfile_실패케이스() throws Exception {
mockMvc.perform(get("/api/users/1"))
.andExpect(status().isOk());
}
}
✓ 올바른 코드: @MockBean으로 UserService를 가짜 객체로 주입하고, @WithMockUser를 사용하여 인증된 사용자로 HTTP 요청을 수행하도록 작성한다.
package com.example.demo.controller;
import com.example.demo.dto.UserResponse;
import com.example.demo.service.UserService;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.security.test.context.support.WithMockUser;
import org.springframework.test.web.servlet.MockMvc;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.verify;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@WebMvcTest(UserController.class)
class UserControllerTest {
@Autowired
private MockMvc mockMvc;
@MockBean
private UserService userService;
@Test
@DisplayName("사용자 프로필 정상 조회 검증")
@WithMockUser(username = "dev_user", roles = "USER")
void getUserProfile_성공() throws Exception {
// given: 가짜 응답 데이터 및 서비스 동작 정의
UserResponse mockResponse = new UserResponse(1L, "dev_user", "dev@redinfo.co.kr");
given(userService.getUserProfile(1L)).willReturn(mockResponse);
// when & then: GET 요청 수행 및 응답 검증
mockMvc.perform(get("/api/users/1"))
.andExpect(status().isOk())
.andExpect(jsonPath("$.id").value(1))
.andExpect(jsonPath("$.username").value("dev_user"))
.andExpect(jsonPath("$.email").value("dev@redinfo.co.kr"));
// 서비스 메서드가 1회 호출되었는지 검증
verify(userService).getUserProfile(1L);
}
}출력 결과: 테스트가 전체 스프링 컨텍스트를 띄우지 않고 1~2초 내외로 통과하며, JSON 구조와 HTTP status 200이 정상적으로 검증된다.
@WebMvcTest를 사용할 때 흔히 실수하는 두 가지 패턴이 존재한다.
첫 번째는 사용자 정의 SecurityConfig에 커스텀 Filter나 JPA Repository 의존성이 얽혀 있을 때 발생한다.
@WebMvcTest는 SecurityConfig를 스캔 대상에 포함하기 때문에, 커스텀 시큐리티 필터가 주입받는 서비스 빈이 없으면 여전히 컨텍스트 로딩 에러가 난다.
✗ 잘못된 방식: 불필요한 시큐리티 전역 설정을 그대로 스캔하도록 방치하여 관련 빈을 모두 @MockBean으로 일일이 선언하는 방식이다.
✓ 올바른 방식: @WebMvcTest(controllers = UserController.class, excludeFilters = @ComponentScan.Filter(type = FilterType.ASSIGNABLE_TYPE, classes = SecurityConfig.class)) 구문을 사용해 테스트에 불필요한 시큐리티 설정을 컴포넌트 스캔에서 제외하거나, 테스트 전용 SecurityConfig를 별도로 지정하는 것이다.
두 번째는 CSRF 토큰 누락이다. POST, PUT, DELETE 요청을 보낼 때 Spring Security 환경에서는 기본적으로 CSRF 검증을 수행한다.
✗ 잘못된 방식: mockMvc.perform(post("/api/users")...) 형태로 전송하여 403 Forbidden 에러가 나타나는 경우다.
✓ 올바른 방식: import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf; 구문을 임포트하고, post("/api/users").with(csrf())를 명시하여 요청해야 한다.
Spring Boot에서 컨트롤러 슬라이스 테스트는 전체 애플리케이션을 구동하지 않고도 HTTP 계층의 입출력을 명확하고 빠르게 검증할 수 있는 강력한 도구다.
@MockBean으로 서비스 레이어를 분리하고 @WithMockUser와 with(csrf())로 시큐리티 장벽을 적절히 처리하는 습관이 모여서 빠른 CI/CD 파이프라인과 높은 테스트 신뢰성을 만든다는 점을 잊지 말자.
이 글의 @WebMvcTest 구성 패턴과 예제 코드를 참고해 컨트롤러 테스트를 작성하면, 전체 DB나 복잡한 빈 로딩 없이 단 몇 초 만에 완료되는 쾌적한 테스트 환경을 구축할 수 있을 것이다.