spring-jpa-testing

Spring JPA テスト

重要：@DataJpaTestでは、テストデータのセットアップにTestEntityManagerが必要です。また、読み取りアサーションの前にflush()とclear()を呼び出す必要があります。これを省略したテストでは、Hibernate の L1 キャッシュから読み取って誤ってテストが成功するため、データベースに対してクエリが実行されません。詳しくは、以下の「重要なルール」を参照してください。

関連項目：@DataJpaTest、JpaRepository、EntityManager、TestEntityManager、@ServiceConnection、PostgreSQLContainer、@AutoConfigureTestDatabase、@Modifying、clearAutomatically、Testcontainers、Hibernate 6、Hibernate 7

テスト済み環境

• Spring Boot 3.2+／Spring Boot 4.x
• Spring Framework 6.x／Spring Framework 7.x
• Hibernate 6.x／Hibernate 7.x
• JUnit 5、Testcontainers 1.19+

重要なルール — @DataJpaTestでは必ず適用

1. テストデータのセットアップにはTestEntityManagerを使用し、Mockitoのモックは使用しないでください。 @DataJpaTestは実際のインメモリデータベースを提供します。リポジトリをモックすると、その目的が損なわれます。 @Autowired TestEntityManager emを使用し、em.persist()／em.persistAndFlush()でテストデータを挿入してください。 セットアップにテスト対象のリポジトリを使用しないでください。リポジトリのバグによってセットアップとアサーションの両方の失敗が隠される、循環したロジックになってしまいます。

2. 読み取りアサーションの前に、必ずflush()とclear()を呼び出してください。 テストデータを永続化した後、リポジトリを通じてクエリを実行する前に、em.flush()、続けてem.clear()を呼び出してください。 flushしないと、SQLがデータベースに送信されない場合があります。clearしないと、リポジトリはHibernateのL1キャッシュからエンティティを返すため、クエリが実際にはデータベースに対して実行されません。

@DataJpaTest
class OrderRepositoryTest {
    @Autowired TestEntityManager em;
    @Autowired OrderRepository orders;

    @Test
    void findByStatus_returnsMatching() {
        em.persist(new Order("pending"));
        em.persist(new Order("shipped"));
        em.flush();   // SQL hits the database
        em.clear();   // L1 cache evicted — forces real DB read

        List<Order> result = orders.findByStatus("pending");
        assertThat(result).hasSize(1);
    }
}

@Modifyingによる一括更新、制約違反のテスト、@Transactionalの落とし穴など、詳細なパターンについてはreferences/transactional-tests.mdを参照してください。

このスキルを使用しない場合

• RESTコントローラーやHTTPエンドポイントのテスト → spring-mvc-testingを使用してください
• 認証、認可、CSRF、JWT、OAuth2のテスト → spring-security-testingを使用してください
• リアクティブリポジトリ（R2DBC）やWebClientのテスト → spring-webflux-testingを使用してください
• Springコンテキストを使用しない純粋なユニットテストの作成 → spring-testing-fundamentalsを使用してください
• AssertJアサーションやMockitoスタブの設定 → spring-testing-fundamentalsを使用してください

リファレンスを読むタイミング

状況	参照先
Testcontainersと@ServiceConnectionを使った@DataJpaTestのセットアップ	references/testcontainers.md
@DataJpaTestと@SpringBootTestのどちらを使うか選ぶ	references/testcontainers.md
@Transactionalのロールバック問題、flush／clearの問題、テストの分離をデバッグする	references/transactional-tests.md
テストパターンの作成：派生クエリ、@Query、ページネーション、仕様、プロジェクション、監査	references/transactional-tests.md
テストでは遅延読み込みが機能するのに本番環境では失敗する、N+1問題	references/lazy-loading-tests.md
SINGLE_TABLE継承、読み取り専用リポジトリ、@QueryHintの落とし穴のテスト	references/lazy-loading-tests.md
Hibernate 6.xまたは7.xへの移行時の失敗、Jakartaパッケージ、シーケンス名、ClassCastException	references/hibernate-6-migration.md
Boot 3.xから4.xへの移行に伴うテストパッケージのインポート変更	references/hibernate-6-migration.md