Bạn sửa một @PostMapping, chạy mvn test, và mất gần một phút chỉ để kiểm tra một trường JSON. Vấn đề không nằm ở code: bạn đang khởi động cả Tomcat, context Spring và DataSource cho một thứ chỉ liên quan lớp web. MockMvc chạy DispatcherServlet trong cùng JVM, không mở socket, không cần server.
Bài này đi từ cơ chế của MockMvc đến một test class hoàn chỉnh cho REST controller trên Boot 4.1.2 / Framework 7.0.10 / Security 7.1.2, kèm các lỗi khiến test xanh mà production vẫn đỏ.
Mục lục
Cập nhật 2026
- Package của test slice đã đổi. Trên Boot 4,
@WebMvcTestvà@AutoConfigureMockMvcnằm ởorg.springframework.boot.webmvc.test.autoconfigure, modulespring-boot-webmvc-test. Import cũ...test.autoconfigure.web.servletkhông còn đúng. @MockBeanđã bị xóa. Boot 4 bỏ@MockBean/@SpyBean; thay bằng@MockitoBean/@MockitoSpyBean. Đây là lỗi compile, không phải cảnh báo deprecated.MockMvcTesterlà lựa chọn mặc định. Framework 6.2 giới thiệu API AssertJ; Boot 4.1.2 tự cấu hình nó trong@WebMvcTestkhi có AssertJ.@SpringBootTestkhông còn tặng kèmMockMvc. Phải thêm@AutoConfigureMockMvc.TestRestTemplatecũng không còn auto-configure;RestTestClientthay thế.
MockMvc làm gì thật sự
MockMvc dựng MockHttpServletRequest, đưa qua DispatcherServlet trong test context, rồi ghi kết quả vào MockHttpServletResponse. Toàn bộ diễn ra trong bộ nhớ: không cổng, không Tomcat, không HTTP thật.
Dù vậy, phần lớn hạ tầng MVC vẫn chạy: handler mapping, argument resolver, Bean Validation, HttpMessageConverter, HandlerExceptionResolver, interceptor, và security filter chain nếu bạn bật. MockMvc không phải unit test thuần: nó kiểm tra controller trong môi trường servlet giả lập, với đúng các quyết định mà Spring MVC sẽ đưa ra.
Những gì nó không làm: không chạy container thật, không render JSP/Thymeleaf, không áp dụng giới hạn multipart của Tomcat, không mô phỏng timeout async hay trang lỗi container. Lỗi chỉ xuất hiện sau khi qua Tomcat sẽ không hiện ở đây.
@WebMvcTest: chỉ load những bean của lớp web
@WebMvcTest(BookController.class) giới hạn việc scan vào một danh sách type cố định: @Controller, @ControllerAdvice, @JacksonComponent, Converter, Filter, HandlerInterceptor, WebMvcConfigurer, WebMvcRegistrations, HandlerMethodArgumentResolver. Nó cũng auto-configure hạ tầng MVC, MockMvc, và MockMvcTester nếu có AssertJ.
Điều quan trọng nhất: @Component, @Service, @Repository và @ConfigurationProperties không được scan. Nếu controller inject một service mà bạn không mock, context sẽ fail với NoSuchBeanDefinitionException. Đó là hợp đồng của slice test, không phải lỗi cấu hình.
Với @SpringBootTest, bạn phải thêm @AutoConfigureMockMvc để có MockMvc. Cách này load toàn bộ context, phù hợp khi muốn kiểm tra controller với service thật, repository thật và security config thật. Cái giá là thời gian và độ phức tạp của context.
Cả hai trường hợp đều inject theo cùng một kiểu:
@Autowired
MockMvc mockMvc; // Hamcrest API: perform(...).andExpect(...)
@Autowired
MockMvcTester mvcTester; // AssertJ API: assertThat(mvcTester.get()...)
@WebMvcTest cũng scan các bean Filter trong context và auto-configure Spring Security nếu nó có trên classpath. Vì vậy test controller mặc định có thể nhận 401/403 trước khi vào method — hành vi đúng, không phải lỗi test.
Mock service bằng @MockitoBean
@MockitoBean thay thế một bean trong context bằng Mockito mock, theo type của field hoặc theo types bạn chỉ định. Nó reset sau mỗi test method, nên stub của test này không rò sang test khác.
// File: src/test/java/com/example/catalog/book/BookControllerTest.java
@WebMvcTest(BookController.class)
class BookControllerTest {
@MockitoBean
BookService books; // thay bean BookService thật trong context
}
Không dùng @MockitoBean trong lớp @Configuration: annotation này chỉ có hiệu lực trên field của test class. Nếu nhiều test class cần cùng bộ mock, tạo composed annotation hoặc khai báo @MockitoBean(types = ...) trên từng class. Còn @MockBean đã biến mất ở Boot 4 — xóa import cũ là bước migration bắt buộc.
Một test class đầy đủ: tạo, đọc và lỗi validation
Giả sử controller có hai endpoint và DTO request validate bằng Jakarta Bean Validation (cần spring-boot-starter-validation):
// File: src/main/java/com/example/catalog/book/BookController.java
package com.example.catalog.book;
import jakarta.validation.Valid;
import java.net.URI;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/books")
public class BookController {
private final BookService books;
public BookController(BookService books) {
this.books = books;
}
@GetMapping("/{id}")
public BookDto byId(@PathVariable long id) {
return books.find(id);
}
@PostMapping
public ResponseEntity<BookDto> create(@Valid @RequestBody CreateBookRequest request) {
BookDto created = books.create(request);
return ResponseEntity.created(URI.create("/api/books/" + created.id())).body(created);
}
}
// File: src/main/java/com/example/catalog/book/CreateBookRequest.java
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
public record CreateBookRequest(
@NotBlank(message = "title không được để trống") String title,
@Min(value = 1, message = "pages phải lớn hơn 0") int pages) {
}
public record BookDto(long id, String title, int pages) {
}
Test class chạy trên slice web, mock service, và kiểm tra cả happy path lẫn error path:
// File: src/test/java/com/example/catalog/book/BookControllerTest.java
package com.example.catalog.book;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.servlet.MockMvc;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
@WebMvcTest(BookController.class)
class BookControllerTest {
@Autowired
MockMvc mockMvc;
@MockitoBean
BookService books;
@Test
void createReturns201WithLocation() throws Exception {
when(books.create(any())).thenReturn(new BookDto(7L, "Effective Java", 412));
mockMvc.perform(post("/api/books")
.contentType(MediaType.APPLICATION_JSON)
.content("""
{"title": "Effective Java", "pages": 412}
"""))
.andExpect(status().isCreated())
.andExpect(header().string("Location", "/api/books/7"))
.andExpect(jsonPath("$.id").value(7))
.andExpect(jsonPath("$.title").value("Effective Java"));
}
@Test
void getReturns200WithJson() throws Exception {
when(books.find(7L)).thenReturn(new BookDto(7L, "Effective Java", 412));
mockMvc.perform(get("/api/books/{id}", 7L)
.accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_JSON))
.andExpect(jsonPath("$.pages").value(412));
}
@Test
void invalidBodyReturns400ProblemDetail() throws Exception {
mockMvc.perform(post("/api/books")
.contentType(MediaType.APPLICATION_JSON)
.content("""
{"title": "", "pages": 0}
"""))
.andExpect(status().isBadRequest())
.andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_PROBLEM_JSON))
.andExpect(jsonPath("$.title").value("Validation failed"))
.andExpect(jsonPath("$.errors[?(@.field == 'title')].message").isNotEmpty());
}
}
Ba test, ba mục đích. Test đầu xác minh status, header Location và body; test thứ hai xác minh converter và JSON; test thứ ba xác minh validation thực sự chạy và @ControllerAdvice được áp dụng. Thiếu test thứ ba là lỗi phổ biến nhất: nhiều người chỉ test 200/201 rồi ngỡ controller đã được kiểm thử đầy đủ.
Request builder và assertion: bảng tra nhanh
MockMvcRequestBuilders tạo request; MockMvcResultMatchers kiểm tra kết quả. Ghép đúng hai nhóm này là kỹ năng chính khi viết test MockMvc.
| Việc cần làm | Request builder | Assertion |
|---|---|---|
| Gửi GET kèm query | get("/api/books").param("page", "2") |
status().isOk() |
| POST JSON | post(uri).contentType(APPLICATION_JSON).content(body) |
status().isCreated() |
| Đọc một trường JSON | — | jsonPath("$.id").value(7) |
| Kiểm tra header | — | header().string("Location", "/api/books/7") |
| So sánh body nguyên khối | — | content().json(expectedJson) hoặc content().string(...) |
| Kiểm tra Content-Type | — | content().contentTypeCompatibleWith(...) |
Với path variable, truyền đối số vào get("/api/books/{id}", 7L); với header, dùng .header("X-Request-Id", "abc"); với form, dùng .param(...) và contentType(APPLICATION_FORM_URLENCODED). Dùng placeholder thay vì tự nối URL để test luôn khớp mapping.
MockMvcTester: cùng request, assertion kiểu AssertJ
MockMvcTester bọc MockMvc và trả về MvcTestResult, nhưng thay andExpect bằng AssertJ. Nó được auto-configure trong @WebMvcTest khi AssertJ có mặt:
import org.springframework.test.web.servlet.assertj.MockMvcTester;
@Autowired
MockMvcTester mvc;
@Test
void getReturnsJsonWithAssertJ() {
when(books.find(7L)).thenReturn(new BookDto(7L, "Effective Java", 412));
assertThat(mvc.get().uri("/api/books/{id}", 7L).accept(MediaType.APPLICATION_JSON))
.hasStatusOk()
.hasContentTypeCompatibleWith(MediaType.APPLICATION_JSON)
.bodyJson()
.extractingPath("$")
.asMap()
.containsEntry("title", "Effective Java");
}
Ba điểm đáng chú ý. Request builder là mvc.get()/mvc.post(), không phải MockMvcRequestBuilders. bodyJson() mở ra AssertJ cho JSON: extractingPath, asMap, convertTo, hoặc so sánh nguyên khối bằng isLenientlyEqualTo. Cần nhiều assertion trên cùng kết quả thì gọi .exchange() một lần rồi assert trên MvcTestResult.
MockMvcTester không đổi ngữ nghĩa của MockMvc, chỉ đổi ngôn ngữ assertion. Đừng trộn andExpect và assertThat trong cùng test class nếu không có lý do rõ ràng — chọn một phong cách cho cả codebase.
Validation, ProblemDetail và @ControllerAdvice
Khi @Valid thất bại trên @RequestBody, Spring ném MethodArgumentNotValidException. Mặc định nó thành 400 với body rỗng hoặc theo format riêng của bạn. Cách hiện đại là trả ProblemDetail theo RFC 9457, và Spring MVC render nó với Content-Type: application/problem+json:
// File: src/main/java/com/example/catalog/book/ApiExceptionHandler.java
package com.example.catalog.book;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
class ApiExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
ProblemDetail invalidBody(MethodArgumentNotValidException ex) {
ProblemDetail problem = ProblemDetail.forStatusAndDetail(
HttpStatus.BAD_REQUEST, "Request body không hợp lệ");
problem.setTitle("Validation failed");
problem.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
.map(error -> Map.of(
"field", error.getField(),
"message", error.getDefaultMessage()))
.toList());
return problem;
}
@ExceptionHandler(BookNotFoundException.class)
ProblemDetail notFound(BookNotFoundException ex) {
return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
}
}
@RestControllerAdvice là @ControllerAdvice cộng @ResponseBody; nó được scan trong @WebMvcTest, nên handler này chạy ngay cả khi bạn chỉ test một controller. Status lấy từ ProblemDetail.getStatus(), các property như errors được serialize ở top level, và client thấy một shape ổn định thay vì message lỗi tự do.
Nếu bạn muốn Boot tự xử lý các exception MVC chuẩn, bật spring.mvc.problemdetails.enabled=true. Khi đó lỗi như body không đọc được hay method không được hỗ trợ sẽ có ProblemDetail mặc định; handler riêng vẫn thắng khi exception khớp cụ thể hơn. Với validation, handler riêng đáng viết vì bạn kiểm soát được danh sách errors mà client nhận.
Bảo mật trong MockMvc
Nếu spring-security-test có trên classpath, bạn có hai cách kiểm tra quyền: giả lập user qua annotation, hoặc gắn request post-processor.
import org.springframework.security.test.context.support.WithMockUser;
@WebMvcTest(AdminController.class)
@WithMockUser(roles = "ADMIN") // áp dụng cho cả class
class AdminControllerTest {
// ...
}
// Trong test cụ thể:
mockMvc.perform(post("/api/books")
.with(csrf())
.with(user("editor").roles("EDITOR"))
.contentType(MediaType.APPLICATION_JSON)
.content(body))
.andExpect(status().isCreated());
@WithMockUser đặt một Authentication đã xác thực vào SecurityContext; filter chain vẫn chạy và vẫn trả 403 nếu role không khớp. Nó bỏ qua authentication, không bỏ qua authorization. Với request thay đổi state, nhớ .with(csrf()) nếu CSRF đang bật, nếu không bạn sẽ nhận 403 và tưởng logic controller sai.
Trên Boot 4, test security được module hóa: nếu @WithMockUser không resolve, thêm starter spring-boot-starter-security-test. Security 7.1 vẫn dùng SecurityFilterChain; @WebMvcTest không tự tạo chain tùy chỉnh trừ khi cấu hình đó nằm trong phạm vi được scan, nên test 401/403 nên chạy trong class có cấu hình bảo mật thật.
Standalone setup cho unit test thuần
Khi bạn không cần context Spring, MockMvcBuilders.standaloneSetup dựng MVC với đúng controller và advice bạn đưa vào. Nó nhanh hơn slice test và không phụ thuộc auto-configuration:
import static org.mockito.Mockito.mock;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
class BookControllerUnitTest {
private final BookService books = mock(BookService.class);
private final MockMvc mockMvc = MockMvcBuilders
.standaloneSetup(new BookController(books))
.setControllerAdvice(new ApiExceptionHandler())
.build();
}
Standalone không tự đăng ký @ControllerAdvice; phải gọi setControllerAdvice. Nó cũng không có security filter chain, Boot property hay custom converter từ ứng dụng. Đổi lại, test chạy cực nhanh và cô lập hoàn toàn — phù hợp để kiểm tra mapping và logic controller, không phù hợp để xác minh wiring.
Những pitfalls làm test xanh mà production đỏ
- Quên mock
@Service.@WebMvcTestkhông scan@Component/@Service, nên context fail ngay khi khởi động. Mock đúng dependency thay vì nới rộng slice. - Context cache theo cấu hình. Mỗi tổ hợp
@WebMvcTest(A.class),@WebMvcTest(B.class), property và mock override tạo một context cache riêng. Thêm annotation “để chạy được” có thể làm bùng nổ số context và thời gian test. Giữ cấu hình slice tối thiểu; đừng trộn@SpringBootTestvào test chỉ cần web layer. - Assert trên HTML thay vì JSON. Với
@RestController, assertjsonPathvà content type, đừng so chuỗi JSON nguyên khối — thứ tự field và whitespace làm test giòn. Với@Controllertrả view, MockMvc không render JSP/Thymeleaf;content().string()thường rỗng. Assertview().name()vàmodel(), hoặc dùng HtmlUnit nếu cần HTML thật. - Không test error path. 400/404/409 mới là nơi controller hay sai: exception map sai status, advice không chạy, ProblemDetail thiếu field. Test class chỉ có 200/201 là chưa đủ.
- Còn sót
@MockBean. Trên Boot 4 nó không compile; đổi sang@MockitoBeanvà bỏ@SpyBean. - Filter bị bỏ qua. Filter chỉ đăng ký ở tầng container, hoặc thêm bằng
ServletContextInitializer, không nằm trong danh sách filter MockMvc biết. Test sẽ không chạy chúng. Tương tự,@AutoConfigureMockMvc(addFilters = false)tắt toàn bộ filter chain — chỉ dùng khi thật sự muốn bỏ qua security.
Khi nào dùng gì
| Mục tiêu | Công cụ | Đặc điểm |
|---|---|---|
| Mapping, JSON, validation, advice với service mock | @WebMvcTest + MockMvc/MockMvcTester |
Nhanh, cô lập lớp web |
| Controller với service/repository/security thật | @SpringBootTest + @AutoConfigureMockMvc |
Trung bình, kiểm tra wiring |
| HTTP thật, filter container, serialization ngoài luồng MockMvc | @SpringBootTest(webEnvironment = RANDOM_PORT) + RestTestClient |
Chậm, sát production |
| Logic controller thuần, không cần Spring context | MockMvcBuilders.standaloneSetup |
Nhanh nhất, ít hạ tầng |
RestTestClient là điểm mới đáng biết: nó test RestClient và HTTP interface client qua hạ tầng MockMvc, cấu hình bằng @AutoConfigureRestTestClient. Nó không thay MockMvc khi kiểm tra controller; nó giải quyết bài toán phía client. MockMvc vẫn là servlet-based: nếu ứng dụng dùng WebFlux, dùng WebTestClient với @WebFluxTest, đừng trộn hai mô hình.
2027: những gì đang dịch chuyển
Framework 7.1 và Boot 4.2 còn ở RC, API có thể đổi trước GA. Hướng rõ ràng là AssertJ-first: MockMvcTester xuất hiện trong tài liệu chính thức của Boot và dần thay các ví dụ Hamcrest cũ. RestTestClient tiếp tục thế chỗ TestRestTemplate trong test cần HTTP thật. Nếu viết test mới hôm nay, chọn MockMvcTester và RestTestClient sẽ giảm công migration sau này.
Checklist trước khi commit
- Test class dùng đúng import Boot 4:
org.springframework.boot.webmvc.test.autoconfigure, không dùng packageboot.test.autoconfigure.web.servletcũ. - Mọi dependency của controller được mock bằng
@MockitoBean; không còn@MockBean/@SpyBean. - Có ít nhất một test cho happy path và một test cho error path (400, 404 hoặc 403).
- Assert trên status, content type và field JSON cụ thể, không chỉ
status().isOk(). - Nếu có security, có test 401/403 và test POST với
csrf()khi CSRF bật. - Chạy
mvn testvà kiểm tra số Spring context được cache; nếu tăng bất thường, rà lại annotation trên test class.
Đọc tiếp
Nếu bạn đang đi theo lộ trình, bài trước về Spring Data JPA và Repository giải thích tầng dữ liệu mà controller gọi tới. Bài @SpringBootTest đi sâu vào integration test, còn bài mocking dependency trong bài test giải thích cơ chế thay bean — hãy đọc nó với lăng kính @MockitoBean, vì @MockBean trong bài cũ đã bị Boot 4 xóa. Toàn bộ thứ tự các bài nằm ở Spring Boot Roadmap.



