Gradleプロジェクトでspring-boot-starter-testにJUnit5を導入するときの競合を解決する

目標

Spring Bootでstarterを利用している環境にJUnit5を導入して、既存のJunit4のテストも対応準備をする。¹
慣れている方には難しい話ではないと思うのですが、私は半日かかりました。

2019/11/20追記

2019/11/20現在、Spring Initializrで生成されるbuild.gradleが修正されて、初期状態でjUnit5のみが有効になっているようです。
実際のソースでは確認していませんが、excludeされている"org.junit.vintage"がjUnit4以前のグループですので、この行を削除するとjUnit4も動くのではないかと思います。

生成されたbuild.gradleより抜粋

  testImplementation('org.springframework.boot:spring-boot-starter-test') {
    exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
  }

依存性の解決

starter-testに含まれているJUnitのグループを除外する

これが重要でした。
starter-testにはJunit4が既に含まれているので、それを一度除外します。
参照：Stack Overflow : spring-boot-starter-test with JUnit 5

build.gradle

dependencies {
...
    testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: 'junit', module: 'junit'
    }
...
}

Dependency Management Pluginを適用してBOMをインポート

バージョンを直接指定するなら必要ありませんが、ここではSpringが提供しているDependency Management Pluginを使います。JUnit5本体とgradleやIDE対応のモジュールでバージョンが全く違うため、BOMを使った方が無難だと思います。

プラグインはプロジェクトを作成したときの環境によってはすでに適用されているかもしれないので、build.gradleファイルの頭の方を確認してみてください。
参照：プラグイン公式ページの該当部分

build.gradle

apply plugin: 'io.spring.dependency-management'//プラグインを適用

dependencyManagement {
    imports {
        mavenBom "org.junit:junit-bom:5.4.2"//BOMのインポート
    }
}

改めてJunitの依存性を追加（2019/06/12追記この章の設定だけでは不十分です）

改めてdependenciesブロックで必要なモジュールを追加します。
先ほどのstarter-testからJUnitを抜く設定の後に追加したものとします。
参照：@tsukakeiさんによるJUnit5ユーザーガイド日本語訳

build.gradle

dependencies {
...
    testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: 'junit', module: 'junit'
    }
    testCompile 'org.junit.jupiter:junit-jupiter'//JUnit5のAPI
    testRuntime 'org.junit.platform:junit-platform-launcher'//IDEなどのサポート用
    testRuntime 'org.junit.vintage:junit-vintage-engine'//JUnit3,4対応
...
}

BOMを使っているのでバージョン指定が要りません。これで導入の設定は完了です。

2019/06/12:追記-1 依存の宣言をGradle5の表記に修正、Gradle,IDEからJunitのテストを利用するための設定の追加

前述の設定だけだときちんと動かないことがわかって、追加で調査しました。
まず、依存性の宣言がGradle5の書式になっていないかったので修正。
参照：junit5-migration-gradleのサンプルのbuild.gradleファイル
参照2：Gradle公式のUsing JUnit 5

build.gradle

dependencies {
...
    testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: 'junit', module: 'junit'
    }
    testImplementation 'org.junit.jupiter:junit-jupiter'//JUnit5のAPI
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'//IDEなどのサポート用
    testRuntimeOnly 'org.junit.vintage:junit-vintage-engine'//JUnit3,4対応
    testCompileOnly 'junit:junit'//Junit5のBOMからJunit4を入れなおせば、4以前のテストも競合しないようです
...
}

/* Gradle,IDEからJunitテストを起動するための設定*/
test {
    useJUnitPlatform()//このブロックで細かい設定が可能
}

JUnit4のテストは動かないとしていましたが、Junit4をそのまま依存性に追加しなおすことできちんと動くようです。
また、GradleからJUnitのテストを起動するには、testタスクにJunitPlatformを利用する宣言が必要です。

2019/06/12:追記-2 JUnitでSpringのテストをするとき特有の問題の回避

上記の設定まで行ってGradleからまとめてテストを行ったとき、テストの起動に失敗するケースが発生しました。
これはSpring特有の問題で、いくつか回避方法があるようです。
このほかにもSpring(SpringMVC)特有の設定等で思い通りにテストが動いてくれないケースが多いため、近日中に「JUnit5でSpringMVCをテストする」として別記事にまとめたいと思います。
設定が上手くいっていると特に問題なく動くように思います。

プロジェクトをリフレッシュする

IDEかコマンドラインから依存性のキャッシュをリフレッシュします。
これでJUnit5がSpring Bootのstarterでも使用できるようになりました。

JUnit4のテストの5への移行についても、前述のユーザーガイドに記述がありますので参照してください。

---

1. ×廃止になっているアノテーションなどがあるため、ソースを修正しないと動きません →JUnit4を追加しなおすことで動くようです ↩