Mocking với @MockBean: Thay thế Dependency trong Bài Test của Bạn | Lộ Trình Java Spring

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ý.

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 package org.springframework.boot.test.mock.mockito cũ.
  • @MockitoBean có nhiều thuộc tính hơn. Ngoài name/types, nó còn reset (mặc định MockReset.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/verify bạn tự viết. Nó xanh cả khi implementation sai hợp đồng. Giữ ít nhất một tầng thật.
  • @MockBean còn sót trong code cũ. Trên Boot 4 đây là lỗi compile; đổi import sang org.springframework.test.context.bean.override.mockito.MockitoBean, đổi @SpyBean sang @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. InvalidUseOfMatchersException và “verify không bắt được gì” thường đến từ đây; dùng any(Type.class) và kiểm tra chữ ký method.
  • Mock bean có AOP. Mất @Transactional/@Cacheable trê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 sang org.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ật enforceOverride cho bean ngoài slice.
  • Thêm ít nhất một verify cho 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