Unit Test JPA Repositories Trong Spring Boot: Nền Tảng Vững Chắc Cho Lớp Dữ Liệu (Series Java Spring Roadmap)

Repository của bạn trả về đúng trên H2, nhưng production PostgreSQL báo lỗi cú pháp JSONB, hoặc thứ tự bản ghi lệch vì NULL. Test xanh chỉ chứng minh query đúng trên database mà bạn chạy test — không hơn. Kiểm thử JPA Repository chỉ có giá trị khi database trong test giống database thật ở những điểm ảnh hưởng đến query.

Bài này đi qua @DataJpaTest, giới hạn của H2, Testcontainers 2.0.5 với @ServiceConnection, và cách viết test cho query thay vì test framework. Entity và repository cơ bản đã có trong bài Spring Data JPA cho người mới bắt đầu và bài Hibernate basics với Spring Boot.

Cập nhật 2026

  • Package của test slice đã đổi. Trên Boot 4.1.2, @DataJpaTest nằm ở org.springframework.boot.data.jpa.test.autoconfigure; TestEntityManager ở org.springframework.boot.jpa.test.autoconfigure; AutoConfigureTestDatabase ở org.springframework.boot.jdbc.test.autoconfigure. Import cũ trong ...test.autoconfigure.orm.jpa không còn đúng.
  • Mặc định của @DataJpaTest không đổi: test method chạy trong transaction và rollback, DataSource bị thay bằng embedded database, spring.jpa.show-sql=true.
  • Testcontainers 2.0.5 tách artifact. Dùng org.testcontainers:testcontainers-postgresql và org.testcontainers:testcontainers-junit-jupiter; class là org.testcontainers.postgresql.PostgreSQLContainer. Tọa độ 1.x như org.testcontainers:postgresql không có ở bản 2.0.5.
  • Stack đang dùng: Spring Boot 4.1.2, Spring Data JPA 4.1.2, Hibernate ORM 7.4.15.Final, Java 25 LTS. Không còn javax.*; toàn bộ là jakarta.*.

Unit Test JPA Repository: @DataJpaTest thực sự làm gì

@DataJpaTest là một slice test. Nó giới hạn component scan vào entity @Entity và repository JPA, đồng thời auto-configure DataSource, EntityManager, TestEntityManager và các repository. Service, controller, security và phần lớn auto-configuration khác không được load. Nhờ vậy context nhỏ hơn nhiều so với @SpringBootTest.

Ba mặc định quyết định cách test của bạn chạy:

  • Embedded database thay DataSource. @DataJpaTest được meta-annotate bằng @AutoConfigureTestDatabase, nên mọi DataSource — kể cả loại bạn tự cấu hình — bị thay bằng H2 nếu H2 có trên classpath.
  • Transactional rollback. Mỗi test method chạy trong transaction do test quản lý và rollback khi kết thúc. Dữ liệu không rò sang test khác. @Commit hoặc @Rollback(false) tắt rollback, chỉ nên dùng khi debug.
  • SQL logging bật sẵn. showSql mặc định true; tắt bằng @DataJpaTest(showSql = false) khi log quá dài.

Về phân loại, đây là slice/integration test: có Spring context và database, dù database là embedded. Gọi nó là unit test thuần là nhầm; unit test thuần không khởi động context.

H2 nói dối về PostgreSQL ở đâu

H2 không phải PostgreSQL thu nhỏ. Nó chấp nhận SQL mà PostgreSQL từ chối và ngược lại. Bốn nhóm khác biệt thường làm test xanh giả:

Khía cạnh H2 embedded PostgreSQL thật
Dialect và SQL Hibernate chọn H2Dialect và sinh SQL khác. Native query không được kiểm tra. PostgreSQLDialect; native query, ON CONFLICT, FOR UPDATE SKIP LOCKED, array, ILIKE chỉ đúng ở đây.
Sequence và identity Schema dựng lại mỗi context, id thường bắt đầu từ 1. Container dùng lại qua nhiều test class, id tiếp tục tăng; DDL identity/sequence cũng khác.
JSONB Có kiểu JSON nhưng không có JSONB, không có toán tử @>, ->> hay GIN index. jsonb nhị phân, toán tử và GIN index là đặc trưng riêng.
Case và NULL Identifier mặc định viết hoa; thứ tự NULL trong ORDER BY có thể khác. Identifier không quote gấp về chữ thường; NULL được xếp theo quy tắc khác.

Thêm vào đó, timestamptz, kiểu numeric, collation và cách so sánh chuỗi cũng không giống nhau. Càng dùng native query hoặc JSONB, khoảng cách giữa H2 và PostgreSQL càng lớn.

@AutoConfigureTestDatabase: NONE hay H2

Mặc định là Replace.ANY: DataSource bị thay, kể cả khi bạn đã cấu hình một DataSource khác. Để giữ PostgreSQL container, phải khai báo @AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE). Thiếu NONE, @ServiceConnection vẫn bị vô hiệu vì DataSource đã bị thay trước đó.

Với database thật, schema không tự xuất hiện. Đặt spring.jpa.hibernate.ddl-auto=create-drop cho profile test, hoặc chạy Flyway/Liquibase trước khi test. Đừng trỏ test vào schema production và cũng đừng giả định schema đã có sẵn.

H2 vẫn hữu ích cho smoke test mapping và derived query đơn giản, miễn là bạn biết nó không đại diện cho PostgreSQL. Với ứng dụng target PostgreSQL, các test repository quan trọng nên chạy trên PostgreSQL thật.

Testcontainers 2.0.5 với @ServiceConnection

Dependency tối thiểu (ngoài spring-boot-starter-data-jpa và spring-boot-starter-test):

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-testcontainers</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-postgresql</artifactId>
  <version>2.0.5</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-junit-jupiter</artifactId>
  <version>2.0.5</version>
  <scope>test</scope>
</dependency>

@Testcontainers quản lý vòng đời container; @Container trên field static giữ container sống suốt test class. @ServiceConnection bảo Spring Boot tạo JdbcConnectionDetails từ container, nên bạn không cần @DynamicPropertySource hay tự set URL, user, password.

Pin image tag cụ thể như postgres:17-alpine, đừng dùng latest. Nếu nhiều test class cùng dùng một database, tạo singleton container trong base class hoặc @TestConfiguration để container không bị dừng giữa các class trong khi context vẫn cache.

TestEntityManager, flush và clear

TestEntityManager là helper thay thế một phần EntityManager trong test. Nó có persist, persistAndFlush, flush, clear, find và getEntityManager. Dùng nó để setup object graph; đừng dùng nó thay cho repository trong phần act của test.

Persistence context là first-level cache. save() đưa entity vào context; findById() có thể trả entity đã cache mà không chạy SELECT. flush() đẩy INSERT/UPDATE xuống database và làm constraint error lộ ra sớm; clear() detach toàn bộ entity, buộc lần đọc sau đi xuống database. Cặp flush() + clear() biến test thành kiểm tra round-trip thật, thay vì kiểm tra bộ nhớ.

Một test class @DataJpaTest + PostgreSQL hoàn chỉnh

Giả sử Book có bốn field và id dùng GenerationType.IDENTITY:

// File: src/main/java/com/example/catalog/book/Book.java
package com.example.catalog.book;

import jakarta.persistence.*;
import java.math.BigDecimal;

@Entity
@Table(name = "books")
public class Book {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String title;

    @Column(nullable = false)
    private String author;

    @Column(nullable = false, precision = 12, scale = 2)
    private BigDecimal price;

    protected Book() {
    }

    public Book(String title, String author, BigDecimal price) {
        this.title = title;
        this.author = author;
        this.price = price;
    }

    public Long getId() { return id; }
    public String getTitle() { return title; }
    public BigDecimal getPrice() { return price; }
}

Repository khai báo ba truy vấn cần kiểm tra: một finder có điều kiện và sort, một truy vấn phân trang trả projection:

// File: src/main/java/com/example/catalog/book/BookRepository.java
package com.example.catalog.book;

import java.math.BigDecimal;
import java.util.List;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.JpaRepository;

public interface BookRepository extends JpaRepository<Book, Long> {

    List<Book> findByAuthorIgnoreCaseOrderByPriceAsc(String author);

    Page<BookSummary> findByPriceGreaterThan(BigDecimal price, Pageable pageable);

    interface BookSummary {
        String getTitle();
        BigDecimal getPrice();
    }
}

Test class dùng PostgreSQL thật, bật schema tạm cho test và tắt SQL log:

// File: src/test/java/com/example/catalog/book/BookRepositoryTest.java
package com.example.catalog.book;

import java.math.BigDecimal;
import java.util.List;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.data.jpa.test.autoconfigure.DataJpaTest;
import org.springframework.boot.jdbc.test.autoconfigure.AutoConfigureTestDatabase;
import org.springframework.boot.jpa.test.autoconfigure.TestEntityManager;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Sort;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;

import static org.assertj.core.api.Assertions.assertThat;

@DataJpaTest(properties = "spring.jpa.hibernate.ddl-auto=create-drop", showSql = false)
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class BookRepositoryTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres =
            new PostgreSQLContainer<>("postgres:17-alpine");

    @Autowired
    BookRepository books;

    @Autowired
    TestEntityManager em;

    @Test
    @DisplayName("save ghi được row và sinh id")
    void save_persistsRowAndGeneratesId() {
        Book saved = books.save(
                new Book("Effective Java", "Joshua Bloch", new BigDecimal("54.90")));

        em.flush();
        em.clear();

        Book reloaded = books.findById(saved.getId()).orElseThrow();

        assertThat(reloaded.getTitle()).isEqualTo("Effective Java");
        assertThat(reloaded.getPrice()).isEqualByComparingTo("54.90");
    }

    @Test
    @DisplayName("finder khớp author không phân biệt hoa thường và sort theo giá")
    void finder_matchesAuthorIgnoringCase_andSortsByPrice() {
        persist("Clean Code", "Robert C. Martin", "42.00");
        persist("Clean Architecture", "Robert C. Martin", "38.50");
        persist("Refactoring", "Martin Fowler", "61.00");

        em.flush();
        em.clear();

        List<Book> found =
                books.findByAuthorIgnoreCaseOrderByPriceAsc("robert c. martin");

        assertThat(found).extracting(Book::getTitle)
                .containsExactly("Clean Architecture", "Clean Code");
    }

    @Test
    @DisplayName("pagination trả đúng slice, tổng và projection")
    void paging_returnsSliceTotalAndProjection() {
        persist("Clean Code", "Robert C. Martin", "42.00");
        persist("Refactoring", "Martin Fowler", "61.00");
        persist("Effective Java", "Joshua Bloch", "54.90");

        em.flush();
        em.clear();

        Page<BookRepository.BookSummary> page = books.findByPriceGreaterThan(
                new BigDecimal("40.00"),
                PageRequest.of(0, 2, Sort.by("price").descending()));

        assertThat(page.getTotalElements()).isEqualTo(3);
        assertThat(page.getTotalPages()).isEqualTo(2);
        assertThat(page.getContent())
                .extracting(BookRepository.BookSummary::getTitle)
                .containsExactly("Refactoring", "Effective Java");
    }

    private void persist(String title, String author, String price) {
        em.persist(new Book(title, author, new BigDecimal(price)));
    }
}

Ba test trên kiểm tra ba thứ khác nhau: round-trip qua database, predicate cùng sort của derived query, và phân trang kèm projection. Chúng không kiểm tra save() hay findById() của Spring Data — những thứ đó đã được framework test.

@Sql fixture: dữ liệu lớn, một lần

Với vài row, factory method như persist() gọn hơn. Với 20–50 row hoặc bộ dữ liệu lặp lại, dùng @Sql:

@Sql("/fixtures/books.sql")
@Test
void query_handlesBoundaryValues() {
    // dữ liệu đã được nạp trước test method
}

Script đặt ở src/test/resources/fixtures/books.sql, chạy trước test method trong cùng transaction và bị rollback sau đó. @Sql đặt trên class sẽ chạy cho mọi method; dùng @SqlGroup khi cần nhiều script. Khi chạy PostgreSQL, script phải là SQL hợp lệ với PostgreSQL — đừng dùng cú pháp riêng của H2.

INSERT INTO books (title, author, price) VALUES
  ('Clean Code', 'Robert C. Martin', 42.00),
  ('Refactoring', 'Martin Fowler', 61.00);

Đặt tên test

Đặt tên theo hành vi được bảo đảm, không theo method: finder_matchesAuthorIgnoringCase_andSortsByPrice, paging_returnsSliceTotalAndProjection. Dùng @DisplayName tiếng Việt cho báo cáo và @Nested để nhóm theo query. Tránh testFindAllWithData: tên đó mô tả code, không mô tả điều test chứng minh.

Khi nào unit test thuần là đủ

Không phải mọi thứ cần database:

  • Logic thuần: entity invariant, value object, mapper DTO, tính giá, chuẩn hóa chuỗi. Dùng JUnit 6 và AssertJ, không cần Spring context.
  • Service điều phối repository: Mockito kiểm tra nhánh và interaction; bài Mocking với @MockitoBean đi sâu vào cách thay dependency. Cách này không kiểm tra SQL.
  • Repository: đừng mock EntityManager. Test như vậy chỉ kiểm tra mock của bạn, không kiểm tra query hay mapping.

@DataJpaTest không phải unit test thuần; nó là slice test. Khi cần kiểm tra xuyên service và controller, dùng @SpringBootTest với Testcontainers; bài tiếp theo trong series có cấu hình đầy đủ.

Pitfalls thường gặp

1. Test framework thay vì test query

save() rồi findById() chỉ chứng minh Hibernate hoạt động. Giá trị nằm ở predicate, sort, boundary, projection, pagination và unique constraint của bạn. Nếu sửa sai mệnh đề WHERE mà test vẫn xanh, test đó không bảo vệ được gì.

2. Dựa vào side effect của rollback

Rollback không tua sequence, không xóa dữ liệu do @BeforeAll tạo ngoài transaction, và không dọn gì khi ai đó thêm @Commit. Đừng assert id cụ thể; đừng để test phụ thuộc thứ tự chạy. Schema test cũng phải được khởi tạo rõ ràng bằng ddl-auto, Flyway hoặc Liquibase.

3. Lazy loading ngoài transaction

Test method của @DataJpaTest đang mở transaction, nên lazy association luôn load được. Production thường đóng transaction ở service rồi serialize entity ở controller — LazyInitializationException xuất hiện ở đó. Hãy test bằng projection/DTO hoặc fetch join, và giữ một integration test không dùng test-managed transaction để tái hiện đúng ranh giới transaction.

4. Fixture mutable dùng chung

Một static List<Book> bị test khác sửa, hoặc entity được persist trong @BeforeAll, tạo phụ thuộc ngầm và thứ tự chạy. Tạo dữ liệu trong từng test hoặc bằng @Sql; giữ fixture immutable. Container static thì ổn — đó là hạ tầng, không phải dữ liệu mutable.

5. Context cache nổ

Mỗi tổ hợp @MockitoBean, @TestPropertySource, @ActiveProfiles, @AutoConfigureTestDatabase hay properties = ... tạo một context mới. Cache mặc định 32; vượt ngưỡng thì context bị evict và test chậm bất thường. Gom cấu hình về một composed annotation, tránh @DirtiesContext, và theo dõi context cache trong log CI.

Decision guide

Tình huống Dùng gì Lý do
Query trên PostgreSQL, JSONB, native SQL @DataJpaTest + Testcontainers SQL và dialect đúng như production.
Smoke test mapping, CI không có Docker @DataJpaTest + H2 Nhanh, nhưng chỉ kiểm tra được phần phổ thông.
Luồng xuyên controller/service/repository @SpringBootTest + Testcontainers Kiểm tra transaction và wiring thật.
Mapper, entity invariant, validation JUnit thuần + AssertJ Không cần context hay database.

Nhìn về 2027

Spring Boot 4.2.0-RC2 mới là preview, Hibernate 8.0.0.Beta4 là bản development; đừng nâng production chỉ vì số version. Khi nâng, kiểm tra lại package test slice và tọa độ Testcontainers — hai chỗ dễ vỡ nhất. Giữ một bộ test chạy PostgreSQL thật để migration không phải phát hiện muộn.

Checklist

  • Xác định database đích. Nếu là PostgreSQL, dùng Testcontainers ngay từ test repository đầu tiên.
  • Luôn thêm @AutoConfigureTestDatabase(replace = Replace.NONE) khi dùng container.
  • flush() và clear() trước khi assert để buộc đọc từ database.
  • Test predicate, sort, boundary, pagination và projection — không test CRUD của framework.
  • Dùng một composed annotation cho cấu hình test; tránh @DirtiesContext và context variant không cần thiết.
  • Fixture nhỏ tạo bằng factory; fixture lớn dùng @Sql và giữ dữ liệu immutable.

Bài tiếp theo trong series là Kiểm thử tích hợp với @SpringBootTest.