Tiêu đề bài này vẫn nói về @MockBean vì đó là từ khóa bạn gõ khi cần thay một dependency trong test. Nhưng trên Spring Boot 4, annotation đó không còn tồn tại: @MockBean và @SpyBean đã bị xóa, thay bằng @MockitoBean và @MockitoSpyBean. Copy một test viết năm 2023, lỗi đầu tiên bạn gặp là lỗi compile ở dòng import, không phải một cảnh báo deprecation.
Bài này giải thích mocking ở tầng ApplicationContext nghĩa là gì, hai annotation mới hoạt động ra sao, và phần quan trọng hơn: khi nào mock là lựa chọn sai. Code dưới đây chạy trên Java 25, Spring Boot 4.1.2, Spring Framework 7.0.10 và Mockito 5.23.0 — các phiên bản mà Boot 4.1.2 quản lý.
Mục lục
Cập nhật 2026
@MockBean/@SpyBeanđã bị xóa. Chúng được deprecated từ Boot 3.4 và bị remove trong Boot 4.0. Annotation thay thế nằm ởorg.springframework.test.context.bean.override.mockito, không phải packageorg.springframework.boot.test.mock.mockitocũ.@MockitoBeancó nhiều thuộc tính hơn. Ngoàiname/types, nó cònreset(mặc địnhMockReset.AFTER),enforceOverride,answers,extraInterfaces. Đây là API của Spring Framework, không phải của Boot.- Mockito 5 dùng inline mock maker mặc định. Final class, final method và static method mock được mà không cần thêm
mockito-inline. Sealed type vẫn là trường hợp riêng, xử lý bên dưới. - Bean override nằm trong context cache key. Tập mock và tên field của bạn quyết định có tái dùng context hay không — chi tiết ở mục context caching.
Mock một bean trong context nghĩa là gì
Spring không “mock một class”. Nó thay một bean definition trong context bằng một định nghĩa khác trỏ tới đối tượng Mockito. Các bean khác đã được inject theo type sẽ nhận đối tượng mới, vì việc resolve dependency xảy ra trên context, không trên biến local của bạn.
@MockitoBean dùng chiến lược REPLACE_OR_CREATE: nếu context đã có bean khớp type hoặc tên, nó thay; nếu chưa có, nó tạo mới. Vì vậy cùng một annotation chạy được trong @SpringBootTest (nơi service thật tồn tại) và trong @WebMvcTest (nơi service không được scan). Nếu bạn muốn chắc chắn mình đang thay một bean thật chứ không phải đang tạo thêm, đặt enforceOverride = true; test sẽ fail khi không tìm thấy bean để thay.
Một điểm ít người để ý: mock được đặt thẳng vào context, bỏ qua bean post-processing. Nó là object trần, không bị bọc trong AOP proxy. Nếu bean gốc có @Transactional, @Cacheable hay @Retryable, mock của bạn không có các hành vi đó. Với spy cũng vậy: spy bọc instance gốc, không tái tạo proxy. Đây là lý do mock một repository trong test transaction là ý tồi — bạn đang kiểm tra một thứ không giống production ở đúng điểm quan trọng nhất.
Còn hai chi tiết vòng đời: mock một bean prototype hay scoped sẽ biến nó thành singleton, và mock một bean do FactoryBean tạo ra sẽ thay chính FactoryBean bằng mock của object nó sinh ra.
So với @Mock thuần của Mockito: @Mock chỉ tạo object, không đụng gì tới context. Bạn tự new service với mock đó, hoặc để MockitoExtension inject. @MockBean cũ và @MockitoBean hiện tại chỉ có nghĩa khi có context — nếu test không load context, chúng vô dụng.
@MockitoBean: field, tên bean và types
Khai báo trên field là cách phổ biến nhất. Type của field quyết định bean bị thay. Nếu context có nhiều candidate cùng type, thêm @Qualifier; không có @Qualifier thì tên field được dùng làm qualifier dự phòng. Bạn cũng có thể chỉ định tên bean trực tiếp bằng @MockitoBean("orders") hoặc @MockitoBean(name = "orders").
Khai báo ở mức type dùng khi nhiều test class cần cùng bộ mock, hoặc khi bạn muốn một composed annotation. Lúc này types là bắt buộc, và nếu có name thì types chỉ được chứa đúng một type:
@MockitoBean(types = {OrderService.class, PricingClient.class})
class OrderFlowTest { }
// name + types: chỉ một type được phép
@MockitoBean(name = "primaryPricing", types = PricingClient.class)
class PricingFailoverTest { }
Annotation không dùng được trong lớp @Configuration. Giới hạn này có từ thời @MockBean và vẫn giữ nguyên: bean override phải khai báo trên test class, field của nó, hoặc một annotation tổ hợp áp lên test class.
@MockitoSpyBean: hành vi thật, sửa một phần
Spy khác mock ở chỗ gọi method thật theo mặc định; bạn chỉ chặn những method cần chặn. Nó hữu ích khi muốn giữ logic thật của bean nhưng quan sát lời gọi, hoặc khi chỉ một nhánh phụ thuộc mạng cần vô hiệu hóa.
@MockitoSpyBean
PricingClient pricing;
@Test
void dungGiaMacDinhKhiApiLoi() {
// doThrow, không phải when(...).thenThrow(...)
doThrow(new IllegalStateException("timeout")).when(pricing).quote("SKU-1");
Quote quote = checkout.total("SKU-1", 2);
assertThat(quote.unitPrice()).isEqualTo(money("19.90")); // fallback thật
verify(pricing).quote("SKU-1");
}
Phải dùng doThrow(...).when(spy) hoặc doReturn(...).when(spy). Viết when(spy.quote("SKU-1")).thenThrow(...) sẽ gọi method thật ngay trong lúc stub, và exception bắn ra từ dòng stub chứ không phải từ lúc service chạy.
Ví dụ chạy được: @WebMvcTest với @MockitoBean
Trong slice web, @Service và @Repository không được scan. Controller cần một OrderService, nên @MockitoBean tạo mock theo REPLACE_OR_CREATE và inject vào constructor. Đây là use case sạch nhất của mocking trong context: bạn kiểm tra hợp đồng HTTP, không kiểm tra business rule.
// File: src/main/java/com/example/shop/order/OrderController.java
package com.example.shop.order;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/orders")
public class OrderController {
private final OrderService orders;
public OrderController(OrderService orders) {
this.orders = orders;
}
@GetMapping("/{code}")
public OrderView byCode(@PathVariable String code) {
return orders.findByCode(code);
}
}
// File: src/main/java/com/example/shop/order/OrderService.java
public interface OrderService {
OrderView findByCode(String code);
}
// File: src/main/java/com/example/shop/order/OrderView.java
public record OrderView(String code, String sku, int quantity) { }
// File: src/test/java/com/example/shop/order/OrderControllerTest.java
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.Mockito.verify;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
@WebMvcTest(OrderController.class) // org.springframework.boot.webmvc.test.autoconfigure
class OrderControllerTest {
@Autowired
MockMvc mvc;
@MockitoBean
OrderService orders; // thay/tạo bean trong context của slice
@Test
void traVeDonHangTheoCode() throws Exception {
when(orders.findByCode("A-100"))
.thenReturn(new OrderView("A-100", "SKU-1", 2));
mvc.perform(get("/api/orders/A-100").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andExpect(jsonPath("$.sku").value("SKU-1"))
.andExpect(jsonPath("$.quantity").value(2));
verify(orders).findByCode("A-100");
}
}
@WebMvcTest đến từ package mới của Boot 4, @MockitoBean từ spring-test. verify không truyền times(1) vì đó là mặc định; nếu controller gọi service hai lần, test này đỏ — đúng thứ bạn muốn.
Stubbing, verify và ArgumentCaptor
when(...).thenReturn(...) và .thenThrow(...) là API cơ bản; given(...).willReturn(...) chỉ là bí danh BDD, đừng trộn hai phong cách trong một file. Với verify, times(2), never(), atLeastOnce() là đủ cho hầu hết trường hợp; verifyNoMoreInteractions hữu ích khi bạn muốn chốt chính xác tập tương tác, nhưng dễ vỡ khi refactor.
ArgumentCaptor dùng khi đối số được tạo bên trong code và bạn cần kiểm tra nội dung, không chỉ kiểm tra có gọi:
ArgumentCaptor<PlaceOrderRequest> captor =
ArgumentCaptor.forClass(PlaceOrderRequest.class);
verify(orders).place(captor.capture());
assertThat(captor.getValue().sku()).isEqualTo("SKU-2");
assertThat(captor.getValue().quantity()).isEqualTo(1);
Hai lỗi thường gặp với matcher. Thứ nhất, không được trộn giá trị thật với matcher trong cùng một lời gọi: verify(orders).place(any(), true) sẽ ném InvalidUseOfMatchersException; phải là any(), eq(true). Thứ hai, chọn đúng overload: Java phân giải method theo kiểu tham số, nên any() trên method có nhiều overload có thể trỏ nhầm bản. Khi nghi ngờ, viết any(PlaceOrderRequest.class) thay vì any().
Về strict stubs: cơ chế UnnecessaryStubbingException thuộc về MockitoSession, tức là MockitoExtension/MockitoJUnitRunner. Mock do @MockitoBean tạo ra không chạy qua session đó — Spring gọi thẳng Mockito.mock(...) với MockSettings. Hệ quả thực tế: một stub không bao giờ được dùng không làm test đỏ. @MockitoSettings cũng là annotation của extension, không phải công cụ cấu hình @MockitoBean; đừng trông vào nó để bắt stub thừa. Cách bắt là verifyNoMoreInteractions ở nơi thật sự cần.
Reset và context caching
MockReset.AFTER là mặc định cho cả @MockitoBean và @MockitoSpyBean: sau mỗi test method, mock bị reset cả invocation lẫn stubbing. Nghĩa là stub phải khai báo lại trong từng test — đừng đặt when(...) trong @BeforeAll rồi ngạc nhiên vì test thứ hai nhận null. MockReset.NONE giữ nguyên trạng thái và tiết kiệm vài dòng stub, nhưng đổi lại thứ tự chạy test bắt đầu ảnh hưởng kết quả; chỉ dùng khi thật sự cần.
Context caching là chỗ chi phí thật sự nằm. Bean override được đưa vào contextCustomizers, và danh sách customizer là một phần của context cache key. Hai test class có cùng cấu hình nhưng khác tập mock, khác tên field hay khác @Qualifier sẽ cần hai context riêng, mỗi context khởi động lại toàn bộ hạ tầng. Tài liệu Spring nói thẳng: nếu mock cùng một bean ở nhiều test class, hãy đặt tên field giống nhau để tránh context thừa.
Mock, fake hay Testcontainers?
| Cách | Dùng khi | Tránh khi |
|---|---|---|
| Mockito mock | Cần cô lập một quyết định; collaborator ở biên (HTTP client, publisher, Clock); cần kiểm tra hợp đồng tương tác |
Điều cần kiểm tra là SQL, mapping, transaction hay migration |
| Fake/in-memory | Repository hoặc port có hành vi gần thật; nhiều kịch bản business rule chạy lặp lại; muốn tốc độ mà vẫn kiểm tra logic | Fake bắt đầu phải mô phỏng khóa, unique constraint, isolation — lúc đó fake đang nói dối |
| Testcontainers 2.0.5 | Hành vi phụ thuộc DB thật: query, index, dialect, transaction, migration | Unit test thuần; môi trường CI không có Docker |
Một fake tốt là một class implement đúng interface, dùng ConcurrentHashMap và giữ nguyên semantics bạn cần (ví dụ trả về Optional.empty() thay vì null). Nó nhanh gần bằng mock, nhưng kiểm tra được nhiều nhánh hơn vì state thật sự thay đổi. Với repository JPA, đừng fake: @DataJpaTest hoặc Testcontainers rẻ hơn về niềm tin.
Mock trong @WebMvcTest và @SpringBootTest
Trong @WebMvcTest, mock là bắt buộc ở biên của slice: service, client, publisher. Nhưng đừng bật enforceOverride = true cho service ở đây — service không nằm trong slice, nên annotation sẽ fail vì không có bean để thay. Đó là hành vi đúng, không phải lỗi cấu hình.
Trong @SpringBootTest, bean thật tồn tại và bị thay. Cái bẫy là mock chỉ thay đúng một bean: các collaborator khác của service thật vẫn là bean thật, và logic của service không chạy. Nếu bạn mock repository rồi kỳ vọng kiểm tra được service, bạn đang kiểm tra một chuỗi không tồn tại trong production. Muốn kiểm tra service, hãy để service thật chạy và mock đúng thứ nó gọi ra ngoài.
Final class, sealed type và inline mock maker
Từ Mockito 5.0, inline mock maker là mặc định, nên final class, final method và static method đều mock được mà không cần cấu hình. Đó là lý do các client kiểu final class hoặc record không còn là vấn đề như thời Mockito 3. Với static, dùng mockStatic(...) trong try-with-resources để trả lại trạng thái sau test.
Sealed type là ngoại lệ khó chịu: Java chỉ cho phép subtype nằm trong danh sách permits, nên Mockito không tạo được mock cho sealed class hay sealed interface và sẽ báo lỗi. Đừng đi tìm cờ cấu hình. Nếu một type bị sealed đến mức không mock được, thiết kế đang nói rằng bạn nên mock interface bên trong hoặc tách collaborator ra; đó là tín hiệu kiến trúc, không phải phiền toái của test.
Pitfalls
- Mock mọi thứ. Nếu mọi collaborator đều là mock, test chỉ còn kiểm tra wiring và chuỗi
when/verifybạn tự viết. Nó xanh cả khi implementation sai hợp đồng. Giữ ít nhất một tầng thật. @MockBeancòn sót trong code cũ. Trên Boot 4 đây là lỗi compile; đổi import sangorg.springframework.test.context.bean.override.mockito.MockitoBean, đổi@SpyBeansang@MockitoSpyBean. Đừng chỉ đổi tên rồi giữ nguyên giả định cũ về reset và vị trí khai báo.- Quên reset hoặc tắt reset. Mặc định đã reset sau mỗi method; nếu bạn đặt
MockReset.NONEđể “đỡ phải stub lại”, bạn vừa tạo phụ thuộc thứ tự test. - Tin vào strict stubs không tồn tại. Stub thừa không bị bắt với mock do Spring tạo, nên dead stub sống rất lâu trong suite. Rà khi review, đừng chờ exception.
- Context explosion. Mỗi tổ hợp mock và tên field khác nhau là một context mới. Đặt tên field nhất quán, và xóa mock không dùng.
- Verify sai overload hoặc trộn matcher.
InvalidUseOfMatchersExceptionvà “verify không bắt được gì” thường đến từ đây; dùngany(Type.class)và kiểm tra chữ ký method. - Mock bean có AOP. Mất
@Transactional/@Cacheabletrên mock; đừng dùng mock để kiểm tra transaction hay cache.
Nhìn về 2027
API bean override đã ổn định trong Framework 7 và là con đường chính thức duy nhất sau khi @MockBean biến mất, nên không có migration sóng lớn nào đang chờ. Điều đang thay đổi là thói quen: các team dùng Testcontainers 2.x cho tầng dữ liệu nhiều hơn, và dùng fake cho repository thay vì mock. Boot 4.2 mới ở mức RC, đừng lên kế hoạch dựa trên nó.
Checklist
- Xóa toàn bộ import
org.springframework.boot.test.mock.mockito; đổi sangorg.springframework.test.context.bean.override.mockito. - Kiểm tra mỗi mock có thật sự cần thiết, hay fake/Testcontainers sẽ kiểm tra được nhiều hơn.
- Đặt tên field mock giống nhau giữa các test class dùng chung bộ mock.
- Với
@WebMvcTest, không bậtenforceOverridecho bean ngoài slice. - Thêm ít nhất một
verifycho tương tác quan trọng, và một assert cho giá trị trả về — đừng chỉ kiểm tra status code.
Bài viết liên quan
- MockMvc: kiểm thử controller mà không cần khởi động server — chi tiết slice web và
MockMvcTester. - Kiểm thử tích hợp với
@SpringBootTest— khi nào cần load toàn bộ context. - Unit test JPA repository — vì sao tầng dữ liệu nên dùng DB thật thay vì mock.
- Lộ trình Spring Boot — thứ tự các bài trong series.



