For AI agents: the complete documentation index is available at /Practical-Introduction-to-Spring-Boot/llms.txt, the full documentation bundle is available at /Practical-Introduction-to-Spring-Boot/llms-full.txt, and this page is available as Markdown at /Practical-Introduction-to-Spring-Boot/SpringBootテスト入門/DBを含む統合テスト入門.md.

DB を含む統合テスト入門

講義の区切り

基本編の目安は 90 分です。終了条件は「H2で保存と登録・削除失敗を検証」です。 発展内容・次回の目安: PostgreSQL を次の60分で実施。基本の確認後に取り組んでください。 準備と前後の章は 学習ガイド で確認できます。

概要

Controller、Service、Mapper、DB を接続した状態で、注文 API の結果を検証します。 HTTP 応答だけでなく、保存された行や失敗後の DB 状態まで確認します。 最初は H2 で実行し、その後 Testcontainers で PostgreSQL を起動して同じテストを実行します。PostgreSQL の部分は発展内容で、基本編の 90 分には含みません。

対象読者

  • Service と Controller の部分テストを書ける方
  • SQL やトランザクションを実物の DB と組み合わせて確認したい方
  • テスト用 DB の用意とデータの初期化を自動化したい方

事前準備と到達目標

Java 21、Maven Wrapper、Spring Boot 4.0 系を使います。 テスト入門 と DB アクセス・トランザクション入門 を前提にします。 注文 API のプロジェクトを、トランザクションを追加した最終段階まで完成させてください。 OrderService.createWithItem と delete に @Transactional が付いた状態から始めます。 パッケージ名は同じ dev.mikoto2000.springboot.database を使います。

前半の H2 テストには Docker は不要です。 後半では Linux コンテナーを実行できる Docker 環境が必要です。 次のコマンドで、クライアントとサーバーの両方が表示されることを確認します。

docker version
docker info

コンテナーイメージの初回取得にはネットワーク接続とディスク容量も必要です。 Windows では Docker Desktop などの対応環境を起動し、Linux コンテナーを使ってください。

完了時には、モックで省略する範囲と実物を使う範囲を選び、DB の状態まで検証できることを目指します。 テストごとにデータを独立させ、DB の接続情報とライフサイクルを管理します。

この資料の構成

この資料は 2 部構成です。

  1. 触って学ぶ DB を含む統合テスト: H2 と PostgreSQL で注文 API の登録・取得・削除・ロールバックを検証するハンズオン。
  2. 座学で学ぶ DB を含む統合テスト: テスト範囲、データ管理、トランザクション、コンテナーの使い方を整理する座学。
触って学ぶ(ハンズオン)座学で学ぶ(理論)
アプリ全体と MockMvc の起動部分テストと統合テスト
HTTP と DB の両方の検証接続した状態で見つかる不具合
テスト前のデータ削除データの独立性と並列実行
明細の失敗とロールバックテスト側のトランザクションの影響
PostgreSQL コンテナー実物の DB と接続情報の管理

触って学ぶ DB を含む統合テスト

プロジェクトの準備

注文 API には MyBatis Starter 4.0.0、Validation、H2、Spring Web が入っています。 OrderService の createWithItem と delete に @Transactional が付いていることを確認します。 前の教材の練習で数量に @Positive を追加した場合は外します。数量 0 の明細を DB の CHECK 制約で失敗させるためです。 pom.xml の dependencies に、次のテスト用依存関係を追加します。 すでにある場合は重複させません。

Web MVC テストの依存関係
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webmvc-test</artifactId>
  <scope>test</scope>
</dependency>

src/test/resources/application-integration.yaml を作成します。

application-integration.yaml
spring:
  sql:
    init:
      mode: always
  h2:
    console:
      enabled: false

このプロファイルは @ActiveProfiles("integration") で読み込みます。 テーブル定義は前の教材の src/main/resources/schema.sql をそのまま使います。 今回はスキーマを SQL 初期化で作り、テストの前には行だけを削除します。

DB 更新失敗の HTTP 応答を定義

前の教材では、DB 制約違反の本文を定義していませんでした。 統合テストで HTTP 応答を検証できるよう、この演習では HTTP 500 とエラーコード DB_WRITE_FAILED を返します。 次のファイルを src/main/java/dev/mikoto2000/springboot/database に追加します。

OrderStorageExceptionHandler.java
package dev.mikoto2000.springboot.database;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class OrderStorageExceptionHandler {
  private static final Logger log = LoggerFactory.getLogger(OrderStorageExceptionHandler.class);

  @ExceptionHandler(DataIntegrityViolationException.class)
  public ResponseEntity<ProblemDetail> storageFailure(DataIntegrityViolationException ex) {
    log.error("Order storage failed", ex);
    ProblemDetail body = ProblemDetail.forStatusAndDetail(
        HttpStatus.INTERNAL_SERVER_ERROR, "注文を保存できませんでした");
    body.setProperty("code", "DB_WRITE_FAILED");
    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(body);
  }
}

通常の API では入力検証を追加し、業務上の重複などは原因を区別して 409 にする設計もできます。 このハンドラーは、この演習の DB 制約違反を 500 とする契約です。 共通エラー応答の設計は 例外処理・エラー応答入門 を参照してください。

共通の API テストを作成

以下のファイルを src/test/java/dev/mikoto2000/springboot/database に配置します。 H2 と PostgreSQL で同じケースを実行するため、テストの本文を抽象クラスにまとめます。

講義では OrderApiContract の責務と確認する結果に注目します。実装時には次の完成コードを開いて配置してください。

注目するのは、失敗応答の後に実物の DB を照会する部分です。

抜粋: 削除失敗後の確認
mvc.perform(delete("/orders/" + id))
    .andExpect(status().isInternalServerError());
assertEquals(1, orderCount());
assertEquals(1, itemCount());
OrderApiContract の完成コード
OrderApiContract.java
package dev.mikoto2000.springboot.database;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
import org.springframework.http.MediaType;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.servlet.MockMvc;

@SpringBootTest
@AutoConfigureMockMvc
@ActiveProfiles("integration")
abstract class OrderApiContract {
  @Autowired
  MockMvc mvc;

  @Autowired
  JdbcTemplate jdbc;

  @BeforeEach
  void clearRows() {
    // 補助テーブルが残っている場合は、参照先の行より先に削除します。
    jdbc.execute("DROP TABLE IF EXISTS order_delete_guard");
    jdbc.update("DELETE FROM order_item");
    jdbc.update("DELETE FROM purchase_order");
  }

  int orderCount() {
    return jdbc.queryForObject("SELECT COUNT(*) FROM purchase_order", Integer.class);
  }

  int itemCount() {
    return jdbc.queryForObject("SELECT COUNT(*) FROM order_item", Integer.class);
  }

  @Test
  void createCanBeReadAndPersistsBothRows() throws Exception {
    var response = mvc.perform(post("/orders/with-item")
        .contentType(MediaType.APPLICATION_JSON)
        .content("""
            {"customerName":"Alice","productName":"Book","quantity":2}
            """))
        .andExpect(status().isCreated())
        .andExpect(jsonPath("$.id").isNumber())
        .andExpect(jsonPath("$.customerName").value("Alice"))
        .andReturn().getResponse();

    String location = response.getHeader("Location");
    assertNotNull(location);
    mvc.perform(get(location))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.customerName").value("Alice"));

    assertEquals(1, orderCount());
    assertEquals(1, itemCount());
    long orderId = jdbc.queryForObject(
        "SELECT id FROM purchase_order WHERE customer_name = ?", Long.class, "Alice");
    long itemOrderId = jdbc.queryForObject("SELECT order_id FROM order_item", Long.class);
    assertEquals(orderId, itemOrderId);
    assertEquals("Book", jdbc.queryForObject("SELECT product_name FROM order_item", String.class));
    assertEquals(2, jdbc.queryForObject("SELECT quantity FROM order_item", Integer.class).intValue());
  }

  @Test
  void missingOrderReturns404() throws Exception {
    mvc.perform(get("/orders/999999"))
        .andExpect(status().isNotFound());
  }

  @Test
  void invalidInputDoesNotWriteRows() throws Exception {
    mvc.perform(post("/orders/with-item").contentType(MediaType.APPLICATION_JSON)
        .content("""
            {"customerName":"","productName":"Book","quantity":2}
            """))
        .andExpect(status().isBadRequest());
    assertEquals(0, orderCount());
    assertEquals(0, itemCount());
  }

  @Test
  void failedItemRollsBackOnlyItsOrder() throws Exception {
    mvc.perform(post("/orders/with-item").contentType(MediaType.APPLICATION_JSON)
        .content("""
            {"customerName":"Existing","productName":"Pen","quantity":1}
            """))
        .andExpect(status().isCreated());

    mvc.perform(post("/orders/with-item").contentType(MediaType.APPLICATION_JSON)
        .content("""
            {"customerName":"Failure","productName":"Book","quantity":0}
            """))
        .andExpect(status().isInternalServerError())
        .andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_PROBLEM_JSON))
        .andExpect(jsonPath("$.code").value("DB_WRITE_FAILED"));

    assertEquals(1, orderCount());
    assertEquals(1, itemCount());
    assertEquals("Existing", jdbc.queryForObject(
        "SELECT customer_name FROM purchase_order", String.class));
  }

  @Test
  void failedHeaderDeleteRestoresDeletedItems() throws Exception {
    mvc.perform(post("/orders/with-item").contentType(MediaType.APPLICATION_JSON)
        .content("{\"customerName\":\"Guarded\",\"productName\":\"Book\",\"quantity\":2}"))
        .andExpect(status().isCreated());
    long id = jdbc.queryForObject("SELECT id FROM purchase_order", Long.class);
    // テスト専用の参照を用意し、明細削除の後に行うヘッダー削除だけを失敗させる。
    jdbc.execute("CREATE TABLE order_delete_guard (order_id BIGINT PRIMARY KEY REFERENCES purchase_order(id))");
    try {
      jdbc.update("INSERT INTO order_delete_guard (order_id) VALUES (?)", id);
      mvc.perform(delete("/orders/" + id))
          .andExpect(status().isInternalServerError())
          .andExpect(jsonPath("$.code").value("DB_WRITE_FAILED"));
      assertEquals(1, orderCount());
      assertEquals(1, itemCount());
    } finally {
      jdbc.execute("DROP TABLE order_delete_guard");
    }
  }

  @Test
  void deleteRemovesOrderAndItem() throws Exception {
    var response = mvc.perform(post("/orders/with-item")
        .contentType(MediaType.APPLICATION_JSON)
        .content("""
            {"customerName":"Alice","productName":"Book","quantity":2}
            """))
        .andExpect(status().isCreated()).andReturn().getResponse();
    String location = response.getHeader("Location");
    assertNotNull(location);

    mvc.perform(delete(location)).andExpect(status().isNoContent());
    mvc.perform(get(location)).andExpect(status().isNotFound());
    assertEquals(0, orderCount());
    assertEquals(0, itemCount());
  }
}

削除の原子性を確認するには、正常系に加えて途中失敗も検証します。追加した失敗ケースでは、テスト専用の外部キーで2番目の削除を失敗させます。 先に削除した明細も元に戻ることを確認し、delete の @Transactional を外すと失敗するテストです。 本番スキーマにはこのテーブルを追加しません。

@MockitoBean は使いません。Service と Mapper も実物を読み込みます。 HTTP の取得結果と、JdbcTemplate で確認した DB の値を組み合わせています。 失敗のテストでは、先に成功した注文を用意します。 失敗した注文だけが取り消され、既存の注文が残ることを確認します。

H2 で実行

OrderApiContract.java と同じディレクトリに、次のファイルを追加します。

OrderApiH2Test.java
package dev.mikoto2000.springboot.database;

import org.springframework.test.context.TestPropertySource;

@TestPropertySource(properties = {
    "spring.datasource.url=jdbc:h2:mem:order-api-test;DB_CLOSE_DELAY=-1",
    "spring.datasource.username=sa",
    "spring.datasource.password="
})
class OrderApiH2Test extends OrderApiContract {}
./mvnw -Dtest=OrderApiH2Test test

PowerShell では .\mvnw.cmd '-Dtest=OrderApiH2Test' test を使います。 6 件のテストが成功することを確認してください。 意図的な DB 制約違反のテストでは ERROR ログが出ますが、期待した応答と DB 状態ならテストは成功します。

このテストを実行するとき、アプリを別のターミナルで起動する必要はありません。 MockMvc は実際の HTTP サーバーを起動せず、アプリのリクエスト処理を呼び出します。

Testcontainers の依存関係

次に、pom.xml の dependencies に追加します。 Spring Boot 4.0 系が管理する Testcontainers 2 系のモジュール名と import を使います。 1 系の postgresql モジュールや org.testcontainers.containers.PostgreSQLContainer と混在させないでください。

PostgreSQL テストの依存関係
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-testcontainers</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-postgresql</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <scope>test</scope>
</dependency>

コンテナーのモジュールと JDBC ドライバーは別の依存関係です。 この教材では JUnit のコンテナー拡張を使わず、Spring Bean として起動・停止を管理します。

PostgreSQL で同じテストを実行

次の 2 ファイルも src/test/java/dev/mikoto2000/springboot/database に配置します。

PostgresTestConfiguration.java
package dev.mikoto2000.springboot.database;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
import org.testcontainers.postgresql.PostgreSQLContainer;

@TestConfiguration(proxyBeanMethods = false)
public class PostgresTestConfiguration {
  @Bean
  @ServiceConnection
  PostgreSQLContainer postgres() {
    return new PostgreSQLContainer("postgres:17-alpine");
  }
}
OrderApiPostgresTest.java
package dev.mikoto2000.springboot.database;

import org.springframework.context.annotation.Import;

@Import(PostgresTestConfiguration.class)
class OrderApiPostgresTest extends OrderApiContract {}

@ServiceConnection がコンテナーの接続情報を DataSource に渡します。 localhost:5432 の固定設定や、既存 DB のユーザー名・パスワードは不要です。 H2 用クラスの @TestPropertySource は PostgreSQL 用クラスには継承されません。 共通プロファイルで SQL 初期化を有効にしたため、PostgreSQL にも同じ schema.sql が適用されます。

Docker を起動して実行します。

./mvnw -Dtest=OrderApiPostgresTest test

PostgreSQL のコンテナーが起動し、同じ 6 件のテストが成功することを確認します。 初回はイメージの取得があるため、H2 より時間がかかります。 テスト中のログで jdbc:postgresql: を含む接続先を確認し、H2 に接続していないことも確認してください。

両方のテストを実行する場合は次を使います。

./mvnw test

Docker が使えない環境では PostgreSQL のテストは失敗します。 前半だけ進める場合は -Dtest=OrderApiH2Test を指定します。 Docker の不備をテスト成功として扱わず、実行できた範囲を区別してください。

練習

  1. 注文名を更新する API のテストを追加し、GET と DB の値が両方変わることを確認する。
  2. createWithItem の @Transactional を一時的に外し、失敗後の件数確認が失敗することを確認する。
  3. SQL 初期化の代わりに Flyway を使い、アプリとテストで同じマイグレーションを適用する。

設定を戻して、テストが成功することを確認してください。 Flyway を使う場合は schema.sql の初期化を無効化し、テーブル作成の二重実行を避けます。 DB マイグレーション入門 を参照してください。

座学で学ぶ DB を含む統合テスト

部分テストと統合テスト

構成実物を使う主な範囲主に見つける問題
Service と Mapper のモック業務ロジック条件分岐や呼び出す処理の誤り
@WebMvcTest と Service のモックHTTP の入出力ステータス、JSON、入力検証の誤り
Mapper と DBSQL と DB列名、型、制約の誤り
@SpringBootTest と MockMvc と DBController から DBDI、設定、データ保存、ロールバックの誤り

今回のテストでは、実際の HTTP サーバーやブラウザーは範囲外です。 実際のポートで通信を検証する場合は、webEnvironment = RANDOM_PORT でサーバーを起動し、HTTP クライアントからアクセスします。 その場合のトランザクションや通信の性質は、MockMvc と異なります。

接続した状態で見つかる不具合

各クラスが個別に動いても、依存関係の登録漏れや SQL の型の不一致でアプリ全体は動かないことがあります。 統合テストは、それらを接続した構成で動作確認する手段です。 HTTP が 201 でも、明細が保存されていなければ業務処理は完成していません。 件数だけでなく、関連する ID と値も確認しましょう。

テスト側のトランザクションの影響

この教材のテストには @Transactional を付けていません。 Service のトランザクションで確定した結果を、テストから確認します。 テスト側でトランザクションを開始すると、Service が参加して、アプリ側の境界設定の不足を隠す場合があります。

テストの最後に自動でロールバックする方法は、データを戻す用途には便利です。 ただし、実際にコミットできるか、制約違反がいつ発生するかも検証対象に応じて確認します。 別スレッドの HTTP サーバーを使うテストでは、サーバーの更新はテストスレッドのトランザクションに参加しません。 テストに @Transactional があっても、サーバーが保存した行を自動で戻せるとは限りません。

データの独立性と並列実行

この教材はテストメソッドを順番に実行し、各テスト前に子テーブルから削除します。 前のテストのデータや実行順序に依存しないよう、各ケースで必要な行を作成します。 自動採番の値は初期化していないため、ID が 1 になることは前提にしていません。

共通 DB を使うテストの並列実行では、他のケースが保存した行を削除する可能性があります。 並列化する場合は、テストごとに DB やスキーマを分けるなど、データの分離を設計してください。 テストの削除先として、開発用や本番用の DB を使わないでください。

H2 と PostgreSQL の使い分け

H2 は環境準備が少なく、前半の動作確認に向いています。 ただし、SQL の方言、型、制約、ロックの挙動は PostgreSQL と完全には一致しません。 互換モードを使っても、実物の DB での確認が不要になるわけではありません。

本番で PostgreSQL を使うなら PostgreSQL、本番で MySQL を使うなら MySQL のコンテナーで確認します。 今回の PostgreSQL は切り替え方法を学ぶ題材です。本番と同じ DB 製品・主要バージョンを選びましょう。 イメージのタグを固定し、更新時にテストします。厳密な再現性が必要ならダイジェストも固定します。

コンテナーの接続情報とライフサイクル

Testcontainers はテスト用コンテナーを起動し、割り当てられたポートなどを Java から取得できるようにします。 @ServiceConnection は、その情報を Spring Boot の接続設定に渡します。 固定ポートを指定しないことで、ローカル DB との競合を避けられます。

今回は Spring がコンテナー Bean の起動と停止を管理します。 コンテナーは ApplicationContext のライフサイクルに対応し、同じコンテキストのテスト間では共有されます。 データはテストメソッドごとに初期化し、コンテナーをケースごとに作り直しているわけではありません。

JUnit の @Container を使う方式もありますが、コンテキストの再利用とコンテナーの停止時期に注意が必要です。 停止済みコンテナーを指す接続設定が再利用されないよう、管理方式を揃えましょう。

実行環境の問題を切り分ける

症状確認する場所
Docker 環境を検出できないDocker の起動状態、docker info、実行ユーザーの接続権限
イメージを取得できないレジストリーへの接続、認証、取得制限
DB が起動しないコンテナーのログ、メモリーやディスクの空き
テーブルがないプロファイル、SQL 初期化、マイグレーションの適用
データ件数が想定と異なる初期化処理、並列実行、別ケースの影響

CI にも対応するコンテナー実行環境が必要です。 環境の起動失敗とアプリのテスト失敗を区別し、スキップしたテストは未検証として扱います。

まとめ

  • Controller から DB まで実物をつなぎ、HTTP と保存結果を両方確認する。
  • 失敗時は、対象の更新だけが取り消されることも検証する。
  • Service の境界を確認するテストは、テスト側のトランザクションで包まない。
  • データの初期化とコンテナーの起動・停止を分けて管理する。
  • 本番で使う DB 製品に合わせたテストも用意する。

参考資料