Testing Spring Boot Applications

Testing the Persistence Layer with @DataJpaTest

18 min Lesson 6 of 13

Testing the Persistence Layer with @DataJpaTest

Your repositories are the boundary between your domain logic and the database. Testing them in isolation — without booting the full application context — gives you fast, deterministic feedback on your JPA mappings, custom queries, and data constraints. Spring Boot's @DataJpaTest slice annotation is designed exactly for this purpose.

What @DataJpaTest Actually Does

When you annotate a test class with @DataJpaTest, Spring Boot builds a slice of the application context that contains only the components needed for the persistence layer:

All Spring Data JPA repositories
Your @Entity classes and their Hibernate mappings
A configured EntityManager (and TestEntityManager)
Spring's transaction support

What it deliberately excludes: @Service beans, @Controller beans, and the full @SpringBootTest context. This means your test starts in milliseconds rather than seconds, and it tests only the code you care about.

In-memory database by default: @DataJpaTest replaces your configured DataSource with an embedded H2 database (in-memory) and runs schema.sql / data.sql if present, or relies on Hibernate's ddl-auto=create-drop. Each test method runs inside a transaction that is rolled back at the end, so the database resets automatically between tests.

Setting Up: Dependencies

Add the Spring Boot test starter and H2 to your pom.xml (both in test scope):

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>test</scope>
</dependency>

Spring Boot's dependency management provides compatible versions, so no version tags are needed.

The Entity and Repository Under Test

Consider a simple Order entity and a Spring Data repository that adds one custom finder:

package com.example.shop.order;

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

@Entity
@Table(name = "orders")
public class Order {

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

    @Column(nullable = false)
    private String customerEmail;

    @Column(nullable = false)
    private BigDecimal total;

    @Column(nullable = false)
    private String status;  // PENDING, PAID, SHIPPED

    private LocalDateTime placedAt;

    // --- constructors, getters, setters omitted for brevity ---
    protected Order() {}

    public Order(String customerEmail, BigDecimal total, String status) {
        this.customerEmail = customerEmail;
        this.total = total;
        this.status = status;
        this.placedAt = LocalDateTime.now();
    }

    public Long getId() { return id; }
    public String getCustomerEmail() { return customerEmail; }
    public BigDecimal getTotal() { return total; }
    public String getStatus() { return status; }
    public LocalDateTime getPlacedAt() { return placedAt; }
    public void setStatus(String status) { this.status = status; }
}

package com.example.shop.order;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import java.util.List;

public interface OrderRepository extends JpaRepository<Order, Long> {

    List<Order> findByCustomerEmail(String email);

    List<Order> findByStatus(String status);

    @Query("SELECT o FROM Order o WHERE o.total > :minTotal ORDER BY o.total DESC")
    List<Order> findHighValueOrders(java.math.BigDecimal minTotal);
}

Writing a @DataJpaTest Test Class

Here is a full, realistic test class using TestEntityManager to arrange data and the repository to act and assert:

package com.example.shop.order;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.*;

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

import static org.assertj.core.api.Assertions.assertThat;
import static org.junit.jupiter.api.Assertions.assertThrows;

@DataJpaTest
class OrderRepositoryTest {

    @Autowired
    private TestEntityManager em;   // lightweight JPA helper for arrange phase

    @Autowired
    private OrderRepository repo;

    @Test
    void findByCustomerEmail_returnsOnlyThatCustomersOrders() {
        // Arrange
        em.persistAndFlush(new Order("alice@example.com", new BigDecimal("120.00"), "PENDING"));
        em.persistAndFlush(new Order("alice@example.com", new BigDecimal("45.00"),  "PAID"));
        em.persistAndFlush(new Order("bob@example.com",   new BigDecimal("200.00"), "SHIPPED"));

        // Act
        List<Order> result = repo.findByCustomerEmail("alice@example.com");

        // Assert
        assertThat(result).hasSize(2)
                          .extracting(Order::getCustomerEmail)
                          .containsOnly("alice@example.com");
    }

    @Test
    void findHighValueOrders_returnsOrdersAboveThreshold_sortedDescending() {
        em.persistAndFlush(new Order("alice@example.com", new BigDecimal("50.00"),  "PAID"));
        em.persistAndFlush(new Order("alice@example.com", new BigDecimal("300.00"), "PAID"));
        em.persistAndFlush(new Order("bob@example.com",   new BigDecimal("150.00"), "PAID"));

        List<Order> result = repo.findHighValueOrders(new BigDecimal("100.00"));

        assertThat(result).hasSize(2);
        assertThat(result.get(0).getTotal()).isEqualByComparingTo("300.00");
        assertThat(result.get(1).getTotal()).isEqualByComparingTo("150.00");
    }

    @Test
    void save_withNullCustomerEmail_throwsConstraintViolation() {
        Order bad = new Order(null, new BigDecimal("10.00"), "PENDING");

        assertThrows(Exception.class, () -> em.persistAndFlush(bad));
    }
}

Always flush before querying. persistAndFlush() writes the entity to the in-memory database immediately. If you only call persist(), Hibernate may batch the INSERT and your subsequent SELECT could run before the row exists, giving a false failure.

TestEntityManager vs the Repository

A common question: if you have the repository, why also use TestEntityManager? The rule is simple:

Use TestEntityManager to arrange (seed) and verify raw state. It bypasses the repository's logic, so it is appropriate for setting up preconditions and for asserting what was actually persisted at the entity level.
Use the repository as the system under test. The methods you are testing belong to the repository; call them in the act step.

Mixing the two roles inside the same step — for example, persisting with the repo and reading back with em.find() — is also valid when you need to verify the raw database state after a save operation.

Transaction Rollback and Test Isolation

Each test method is wrapped in a transaction that is rolled back when the method finishes. This means:

No data leaks between tests — each test starts with a clean database.
You never need @BeforeEach cleanup code to delete rows.
The auto-increment counter may still advance (H2 does not reset sequences on rollback), so never assert on specific generated ID values.

Watch out for lazy-loading in tests. Because the test runs inside a single transaction, lazy associations are still open and appear to load fine. When the same code runs in a real request (where the transaction closes before you access the lazy field), you may get a LazyInitializationException. Always test lazy vs eager behaviour deliberately, or configure @Transactional(propagation = REQUIRES_NEW) in a helper method to simulate the real transaction boundary.

Testing Against a Real Database with @AutoConfigureTestDatabase

The in-memory H2 database is convenient but not always faithful. Dialects differ: PostgreSQL's jsonb type, MySQL's full-text indexes, and database-specific JPQL extensions do not exist in H2. When your queries depend on database-specific behaviour, override the replacement:

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class OrderRepositoryIntegrationTest {
    // Spring now uses the DataSource in application.properties (or your Testcontainer DataSource)
}

Combine Replace.NONE with Testcontainers (covered in lesson 9) to spin up a real PostgreSQL or MySQL instance in Docker during the test run — the best of both worlds: isolation plus full dialect fidelity.

Performance Considerations

Because @DataJpaTest builds a minimal context, it is fast — typically under 3 seconds for the first test and near-instant for subsequent tests in the same test run (Spring caches the application context across tests with the same configuration). Keep the slice lean:

Do not add @Import of service or controller beans into a @DataJpaTest — that defeats the purpose. Test those layers in their own slices.
Group tests that share the same context configuration in one class so the context is reused.
Use @Sql for large fixture datasets instead of many individual em.persist() calls — it is faster and keeps the arrange phase readable.

Summary

@DataJpaTest gives you a focused, fast slice for testing repositories: an in-memory H2 database, a TestEntityManager for fixtures, automatic transaction rollback between tests, and only the JPA components loaded. Use it to verify your custom finders, JPQL queries, and database constraints without the overhead of a full application context. When H2 is not faithful enough, switch to Replace.NONE and point the slice at a real database or Testcontainer. In the next lesson you will learn how @MockBean lets you replace any bean in the context with a Mockito mock.