テックブログ

Spring Boot 4でテストが動かない原因:test starter再編と設定の見直し

Spring Boot 4でテストが動かない原因:test starter再編と設定の見直し

Spring Boot 4では、本番向けモジュールだけでなくテスト基盤も技術ごとに分割されました。従来はspring-boot-starter-testや別のstarterから推移的に利用できていたMockMvc、Security Test、HTTPテスト支援などが、対象技術に対応するtest starterを明示しなければ利用できない場合があります。アプリ本体が起動してもテストだけがコンパイルエラーになったり、ApplicationContextの生成に失敗したりするのは、テスト側のクラスパスと自動構成が移行できていない可能性があります。

修正では、失敗したクラスを含むJARを一つずつ直接追加するのではなく、テスト対象の技術、必要なテスト用starter、使用するテスト注釈を対応させます。本記事ではSpring Boot 4.1.2を基準に、test starterの選び方、MockMvcと@SpringBootTest、Spring Security、Mockito、TestRestTemplateとRestTestClient、TestContextの設定を順番に確認し、テスト基盤の移行完了条件まで整理します。

1. テスト失敗を三つの段階に分ける

1.1 コンパイル前の依存解決失敗を確認する

最初に、ビルドツールが必要なテスト依存を解決できているか確認します。package ... does not existやcannot find symbolが出る場合は、テストコードを実行する前の問題です。importの変更またはtest starterの不足を疑います。

Spring Boot 4では、テスト支援クラスのパッケージも技術別モジュールへ移動しています。旧importを残したまま不足JARだけを追加すると、非推奨の互換モジュールへ依存したり、本番側と異なる世代のクラスが混在したりします。エラーに表示された完全修飾クラス名と、4.1.2 APIの所属パッケージを比較してください。

Mavenでは./mvnw test -DskipTests=false、Gradleでは./gradlew testをコマンドラインから実行します。IDEだけで成功または失敗する場合は、IDEのクラスパスとビルド定義が一致していません。CIで使うコマンドを基準にします。

1.2 ApplicationContext生成失敗を切り分ける

コンパイル後にFailed to load ApplicationContextとなる場合は、テスト用のSpringコンテキストを作る途中で失敗しています。依存不足、Bean不足、プロファイル、設定プロパティ、モックの置換、テストスライスの範囲などを調べます。

末尾の例外だけでなく、最初に発生したCaused byまで遡ります。たとえばNoSuchBeanDefinitionExceptionが原因なら、テストスライスに対象Beanが含まれないのか、@MockitoBeanが不足しているのか、本番用自動構成が成立していないのかを分けます。

同じテストクラスへ注釈を追加し続けると、偶然動く大きなコンテキストになり、原因が見えにくくなります。テスト対象に必要な最小構成を確認し、スライステストで足りないものと、結合テストとして本当に必要なものを分けます。

1.3 実行後の期待値差分を依存問題と混同しない

テストが起動してアサーションで失敗する場合は、依存不足とは限りません。JSON、HTTPステータス、認証フィルター、例外ハンドリング、トランザクション境界などの挙動差を確認します。

Spring Boot 4移行では、Jackson 3、Spring Security、Spring Frameworkの更新も同時に入ります。expected 200 but was 401ならSecurity設定、JSON文字列の差ならMapper設定、DBの状態が残るならトランザクションと実サーバーのスレッド境界というように、観測された差から責任範囲を絞ります。

次の表で、最初の調査先を固定できます。

失敗段階代表的な症状最初に確認するもの
依存解決・コンパイルclass、package、symbolが見つからないtest starter、import、依存スコープ
コンテキスト生成Failed to load ApplicationContextBean、プロファイル、テスト注釈、自動構成
テスト実行401、JSON差分、期待値不一致Security、Mapper、フィルター、テストデータ
CIのみ失敗ローカルでは成功するJava・ビルドツール・環境変数・キャッシュ

2. 技術別test starterへ移行する

2.1 test starterの命名規則を理解する

Spring Boot 4のテスト用starterは、原則としてspring-boot-starter-<technology>-testという名前です。対応するテストモジュールはspring-boot-<technology>-test、ルートパッケージはorg.springframework.boot.<technology>.testとなります。

たとえばSpring MVCのテストにはspring-boot-starter-webmvc-test、Spring Securityにはspring-boot-starter-security-testを使います。アプリが利用する本番技術と、その技術をテストするためのstarterを対にして考えます。

テスト対象主な本番starter主なtest starter
Spring MVCspring-boot-starter-webmvcspring-boot-starter-webmvc-test
WebFluxspring-boot-starter-webfluxspring-boot-starter-webflux-test
Securityspring-boot-starter-securityspring-boot-starter-security-test
JDBCspring-boot-starter-jdbcspring-boot-starter-jdbc-test
Jacksonspring-boot-starter-jacksonspring-boot-starter-jackson-test
RestClientspring-boot-starter-restclientspring-boot-starter-restclient-test

技術別test starterはspring-boot-starter-testを推移的に取り込むため、同じモジュールで重複して宣言する必要がない場合があります。依存ツリーを確認し、必要な技術をtest starterとして明示する構成へ整理します。

2.2 MavenとGradleでtestスコープへ追加する

Spring MVCとSpring SecurityをテストするMavenプロジェクトでは、次のようにtestスコープで追加します。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webmvc-test</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security-test</artifactId>
    <scope>test</scope>
</dependency>

GradleではtestImplementationを使います。

dependencies {
    testImplementation("org.springframework.boot:spring-boot-starter-webmvc-test")
    testImplementation("org.springframework.boot:spring-boot-starter-security-test")
}

test starterをimplementationへ入れると、本番成果物へテスト支援ライブラリが混入する可能性があります。Mavenのtest、GradleのtestImplementationまたは用途に合うテスト構成へ限定します。

2.3 classic starterは調査用の足場に限定する

移行直後に不足モジュールが多く、個別の原因を調べられない場合は、spring-boot-starter-test-classicで以前に近い広いテストクラスパスを一時的に復元できます。ただし、これは最終構成ではありません。

classicでテストが動けば、アプリのテストコードそのものより、新しいモジュール分割による依存不足の可能性が高まります。そこから技術別test starterへ一つずつ置き換え、不足した機能を記録します。

classicを残すと、実際には使っていない技術のテストモジュールまで入り、将来の不足を隠します。削除期限を決め、依存ツリーでclassicが残っていないことを移行完了条件にします。

3. 依存経路とimportを確認する

3.1 Maven dependency treeで導入元を特定する

Mavenでは次のコマンドでテスト依存を確認します。

./mvnw dependency:tree -Dscope=test

必要なstarterが表示されても、Spring Boot本体と異なるバージョンが直接指定されていないか確認します。BOM管理を使っている場合は、test starterのバージョンを個別指定しないことが基本です。

同じライブラリの複数バージョンが見える場合は、dependencyManagement、社内BOM、直接依存、プラグインを調べます。テストだけ古いSpring FrameworkやSecurity Testを使う構成は、実行時のNoSuchMethodErrorにつながります。

3.2 Gradle dependencyInsightで競合を調べる

GradleではtestRuntimeClasspathを基準にします。

./gradlew dependencies --configuration testRuntimeClasspath

特定モジュールの選択理由はdependencyInsightで確認できます。

./gradlew dependencyInsight \
  --dependency spring-security-test \
  --configuration testRuntimeClasspath

compileOnlyや独自configurationへ入っているだけでは、テスト実行時に利用できない場合があります。コンパイル時と実行時の両方で必要な依存が揃っているか確認します。

3.3 Boot 4のパッケージへimportを更新する

Spring MVCテストの注釈は、Boot 4では技術別パッケージにあります。

import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;

IDEの自動importだけに任せると、同名の旧クラスや別ライブラリの型を選ぶことがあります。公式APIで完全修飾名を確認し、プロジェクト全体を検索します。

importを更新しただけで実行時依存が入るわけではありません。Javaコードのパッケージ変更と、ビルド定義のtest starter追加を一組で行います。

4. MockMvcとSpringBootTestを明示的に構成する

4.1 SpringBootTestだけではMockMvcを構成しない

Spring Boot 4では、@SpringBootTestを付けただけではMockMvcが自動構成されません。MockMvcを使う結合テストには@AutoConfigureMockMvcを追加します。

@SpringBootTest
@AutoConfigureMockMvc
class OrderApiIntegrationTest {

    @Autowired
    MockMvc mockMvc;
}

@SpringBootTestはアプリ全体に近いコンテキストを作り、@AutoConfigureMockMvcはそのコンテキストへMockMvcを追加します。サーバーを起動せず、Servletフィルターを含むHTTP処理を確認したい場合に使います。

MockMvc Beanが見つからないとき、フィールドへnewして回避しないでください。Spring SecurityのFilterChain、例外ハンドラー、メッセージコンバーターなどが反映されない別物になります。

4.2 WebMvcTestはController範囲へ限定する

Controller単体に近いテストでは@WebMvcTestを使います。

@WebMvcTest(OrderController.class)
class OrderControllerTest {

    @Autowired
    MockMvc mockMvc;

    @MockitoBean
    OrderService orderService;
}

@WebMvcTestはMVC関連のBeanへ範囲を絞り、通常の@Serviceや@ConfigurationPropertiesをすべて読み込むわけではありません。必要な協力オブジェクトは@MockitoBean、@Import、@EnableConfigurationPropertiesなどで明示します。

Beanが不足するたびに@SpringBootTestへ変更すると、テストが遅くなり、Controllerの責任範囲が曖昧になります。必要な構成がMVCの一部なのか、業務サービスなのかを判断します。

4.3 フィルターを外して成功させない

@AutoConfigureMockMvc(addFilters = false)を使うと、Security Filterなどを外したテストを作れます。しかし、401や403を避けるためだけに無効化すると、本番と異なる経路を確認することになります。

認証不要なControllerの構造だけを確認する目的なら有効ですが、認可やCSRFを検証するテストではFilterを有効にします。テスト名と目的から、どちらの構成か分かるようにします。

HtmlUnitの設定は@AutoConfigureMockMvcのhtmlUnit属性へ移動しています。旧webClientEnabledやwebDriverEnabledがコンパイルエラーになる場合は、4.1.2 APIの属性を確認します。

5. Security TestとMockitoを移行する

5.1 WithMockUserにはSecurity test starterを用意する

@WithMockUserや@WithUserDetailsを使うテストでは、spring-boot-starter-security-testを明示します。spring-security-testだけを直接追加するより、Spring Bootが管理する対応版とテスト自動構成を揃えやすくなります。

@WebMvcTest(AdminController.class)
class AdminControllerTest {

    @Test
    @WithMockUser(roles = "ADMIN")
    void adminCanRead() throws Exception {
        // MockMvcで認可結果を確認する
    }
}

認証済みユーザーを用意しても403になる場合は、CSRF、必要ロール、SecurityFilterChain、メソッドセキュリティを確認します。テスト依存が入ったことと、アプリの認可条件を満たしたことは別です。

5.2 MockBeanとSpyBeanを新しい注釈へ置き換える

Spring Bootの@MockBeanと@SpyBeanは非推奨となり、Spring Frameworkの@MockitoBeanと@MockitoSpyBeanへ移行します。

import org.springframework.test.context.bean.override.mockito.MockitoBean;

@SpringBootTest
class PaymentApplicationTest {

    @MockitoBean
    PaymentGateway paymentGateway;
}

機械的な置換だけでなく、モックをフィールド、型、Bean名のどれで特定していたか確認します。複数の同型Beanがある場合は、Bean名やQualifierの扱いがテスト結果へ影響します。

@MockitoBeanを@Configurationクラスのフィールドとして共有する旧パターンは、そのまま移せません。テストクラス上の型指定、基底クラス、合成注釈などへ再構成します。

5.3 通常のMockとCaptorにはMockitoExtensionを使う

SpringのBeanを置き換えず、単純な単体テストでMockitoの@Mockや@Captorを使う場合はMockitoExtensionを明示します。

@ExtendWith(MockitoExtension.class)
class PriceServiceTest {

    @Mock
    PriceRepository repository;

    @Captor
    ArgumentCaptor<Price> captor;
}

Spring Boot 4では、非推奨だったMockitoTestExecutionListenerが削除されています。@Mockフィールドがnullになる場合、Springのコンテキストを大きくするのではなく、JUnit 5とMockitoの標準的な初期化へ移します。

@MockitoBeanはSpringコンテキスト内のBean置換、@Mockは通常のJavaオブジェクト用です。目的を混同しないことで、不要なコンテキスト起動を減らせます。

6. HTTPテストクライアントを明示する

6.1 TestRestTemplateは注釈とモジュールを追加する

@SpringBootTest(webEnvironment = RANDOM_PORT)だけでは、TestRestTemplateは自動構成されません。利用する場合は@AutoConfigureTestRestTemplateを追加します。

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureTestRestTemplate
class OrderHttpTest {

    @Autowired
    TestRestTemplate restTemplate;
}

クラスのパッケージはorg.springframework.boot.resttestclient.TestRestTemplateです。コンパイルできない場合はspring-boot-resttestclientとRestClient側の依存、または対応するtest starterを確認します。

TestRestTemplateを使い続ける理由がなければ、Spring Boot 4で用意されたRestTestClientへの移行も検討します。既存テストをすべて一度に書き換えず、新規または変更対象から段階的に進めます。

6.2 RestTestClientは用途に応じて接続方法を選ぶ

RestTestClientは、MockMvcを使うモック環境と、実サーバーへ接続する環境の両方でHTTP結果を検証できます。@AutoConfigureRestTestClientで自動構成を有効にします。

@SpringBootTest
@AutoConfigureMockMvc
@AutoConfigureRestTestClient
class OrderRestTestClientTest {

    @Autowired
    RestTestClient client;
}

モック環境で十分なテストと、実ポート、TLS、圧縮、ネットワーク境界まで確認するテストを分けます。クライアントAPIが同じでも、実行経路は同じではありません。

6.3 トランザクションの境界を確認する

@SpringBootTestで実サーバーを起動すると、テストメソッドとサーバー処理は別スレッド・別トランザクションになります。テストクラスに@Transactionalを付けても、HTTP経由で作成されたデータが自動的にロールバックされない場合があります。

データが残るテストでは、依存移行の失敗と決めつけず、セットアップとクリーンアップを確認します。テストごとに一意なデータを使う、明示的に削除する、コンテナを分離するなど、実行方式に合う方法を選びます。

7. TestContextとプロファイルを見直す

7.1 主構成クラスの探索範囲を確認する

Spring Bootのテスト注釈は、テストクラスのパッケージから上へ探索し、@SpringBootApplicationまたは@SpringBootConfigurationを見つけます。テストパッケージを移動した結果、主構成が見つからないことがあります。

安易にすべてのテストへclasses = ...を追加する前に、アプリとテストのパッケージ構造を確認します。主構成の探索が成立する標準構成に戻せるなら、その方が保守しやすくなります。

複数アプリを持つモジュールでは、対象構成を明示する方が安全です。どのアプリのコンテキストを作るテストなのか、クラス名と注釈から分かるようにします。

7.2 ActiveProfilesと設定値の由来を固定する

移行前後で違うプロファイルが有効になると、Beanや外部接続先が変わります。@ActiveProfiles、@TestPropertySource、@SpringBootTest(properties = ...)、環境変数、CIのシークレットを一覧にします。

テスト用プロパティで本番設定の不足を隠していないかも確認します。移行後に新しい設定名が必要なのに、ローカルの環境変数だけで偶然満たしていると、CIで失敗します。

値をログへ出す場合は秘密情報を避け、プロパティ名とPropertySourceだけを記録します。再現に必要な条件を残しつつ、認証情報をテストレポートへ含めないようにします。

7.3 TestConfigurationを本番構成と分離する

テスト専用Beanには@TestConfigurationを使います。通常の@Configurationをテストクラス内へ置くと、主構成を置き換えたり、想定外のComponent Scanへ入ったりすることがあります。

共有設定が増えたら、対象テスト群、提供するBean、必要なプロファイルを明記します。便利だからという理由で全テストへimportすると、コンテキストキャッシュが細分化され、実行時間が増える可能性があります。

テストが通るためだけのBeanと、本番にも必要なBeanを区別します。本番Bean不足をテスト設定で補うと、リリース後に初めて起動エラーが見つかります。

8. CIで再現可能なテスト基盤を作る

8.1 Javaとビルドツールの版を固定する

CIとローカルでJava、Maven、Gradle、Spring Bootの版を揃えます。Wrapperを利用し、CIログへjava -versionとビルドツールのバージョンを残します。

Spring Boot 4.1では、Maven PluginのテストAOTスキップ判定がmaven.test.skipへ整理されています。-DskipTestsだけを渡したときの処理が以前と同じとは限らないため、CIで何を省略しているか確認します。

テストを省略したビルド成果物を「テスト済み」と扱わないよう、ビルドジョブとテストジョブの責任を分けます。AOTを使う場合は、通常テストとAOT処理の両方が意図どおり実行されることを確認します。

8.2 キャッシュを消したクリーンビルドを確認する

依存キャッシュやIDEの出力が古いクラスを残すことがあります。移行の最終確認では、Mavenのclean verifyまたはGradleのclean testを実行します。

キャッシュ削除で直った場合も、原因を「キャッシュだった」で終わらせません。ビルド定義に必要な依存がなく、過去の成果物へ依存していた可能性があります。新しい環境でゼロから再現できることを確認します。

8.3 テスト一覧と除外条件を記録する

成功件数だけでなく、実行対象、除外タグ、失敗時再実行、並列実行、外部サービスの代替方法を記録します。テスト数が大きく減ったのに成功している場合は、検出設定や命名規則が変わった可能性があります。

Surefire、Failsafe、Gradle test taskのinclude・excludeを確認します。単体テストだけ成功し、結合テストが実行されていない状態を移行完了としないでください。

9. よくあるエラーを原因別に直す

9.1 MockMvc Beanが見つからない

NoSuchBeanDefinitionException: MockMvcでは、まずspring-boot-starter-webmvc-testと@AutoConfigureMockMvcを確認します。@WebMvcTestであればMockMvcは自動構成されるため、importやstarterの不足を疑います。

WebFluxアプリへMockMvcを追加していないかも確認します。WebFluxではWebTestClientを利用し、アプリのWeb Application Typeとテスト手段を一致させます。

9.2 WithMockUserを付けても認証できない

spring-boot-starter-security-test、Spring Security Filterの有効化、必要ロール、CSRF、メソッドセキュリティを順番に確認します。roles = "ADMIN"は通常ROLE_ADMINとして扱われるため、authorityとの違いにも注意します。

Filterを無効化して200へする方法は、認可テストの修正ではありません。認証不要のテストと認可を確認するテストを分けます。

9.3 MockやCaptorがnullになる

通常のMockitoフィールドなら@ExtendWith(MockitoExtension.class)を使います。Spring Beanを置き換える目的なら@MockitoBeanを使います。両者を混在させる場合は、どのオブジェクトを誰が生成するか整理します。

MockitoAnnotations.openMocks(this)を手動で呼ぶ方法もありますが、JUnit 5ではExtensionを使う方がライフサイクルを統一しやすくなります。

9.4 TestRestTemplateがimportできない

Boot 4のパッケージorg.springframework.boot.resttestclient.TestRestTemplateへ更新し、対応モジュールまたはtest starterを追加します。Beanが注入できない場合は@AutoConfigureTestRestTemplateとRANDOM_PORTの有無を確認します。

新規テストではRestTestClientも候補にし、既存テストを維持するのか移行するのかをPR内で明確にします。

10. テスト基盤の移行完了を確認する

10.1 依存関係の完了条件

本番技術と技術別test starterが対応し、すべてtestスコープに限定されていることを確認します。spring-boot-starter-test-classicを使った場合は削除し、直接指定した古いSpring FrameworkやSecurity Testが残っていないか調べます。

MavenとGradleの依存レポートをCI成果物として保存すると、後から差分を追いやすくなります。採用理由のない直接モジュール追加を減らし、starterで利用意図を表します。

10.2 テスト設定の完了条件

MockMvc、WebTestClient、TestRestTemplate、RestTestClientが、使用するテストごとに明示的に構成されていることを確認します。@MockBeanと@SpyBeanは置換計画を持ち、通常のMockitoフィールドはExtensionで初期化します。

プロファイル、テストプロパティ、主構成クラス、テスト専用Beanの由来が説明できる状態にします。失敗を回避するためだけのFilter無効化や、過剰な@SpringBootTestが残っていないかレビューします。

10.3 実行結果の完了条件

クリーン環境で単体、スライス、結合、HTTPテストを実行し、移行前に存在したテストが意図せず除外されていないことを確認します。テスト件数、失敗件数、実行時間、除外条件を比較します。

最終的な完了条件は、テストが緑色になることだけではありません。テスト対象の技術に必要な依存を明示し、本番と同じ境界を確認し、CIで再現できる状態になったことです。

まとめ

Spring Boot 4ではテスト基盤も技術別に分割され、spring-boot-starter-<technology>-testを選ぶ構成へ変わりました。テストが動かないときは、コンパイル、ApplicationContext生成、テスト実行のどこで失敗したかを最初に分類し、不足クラスを含むJARを闇雲に追加しないことが重要です。

MockMvcを使う@SpringBootTestには@AutoConfigureMockMvc、Security Testにはspring-boot-starter-security-test、Spring Beanのモックには@MockitoBean、通常のMockitoフィールドにはMockitoExtensionを使います。TestRestTemplateやRestTestClientも、利用するクライアントと実行方式を明示します。

classic starterは移行調査の足場として利用できますが、最終的には技術別test starterへ置き換えます。依存スコープ、import、TestContext、プロファイル、CIの実行対象を揃え、クリーン環境で同じ結果を再現できれば、Spring Boot 4のテスト基盤移行は完了です。

参考リンク