Gradleでテストを効率化する方法とコード品質管理・SonarQube連携の実践

Gradleのテスト実行とは？基本コマンドとJUnit 5の設定方法

Gradleのテスト実行の基本と代表的なコマンド

JavaプロジェクトでGradleを使う場合、テスト実行は`./gradlew test`コマンドが基本です。このコマンドはGradleのJavaプラグインが提供する標準タスクで、`src/test/java`配下のテストコードをコンパイルし、すべてのテストを実行します。Gradle Wrapper（`gradlew`）を使うことで、開発者全員が同じGradleバージョンでテストを実行できるため、環境差による問題を防げます。テスト結果はXML形式で`build/test-results/test/`に、HTMLレポートは`build/reports/tests/test/index.html`に出力されます。テストを含む検証タスク一式をまとめて実行したい場合は`./gradlew check`を使用します。このタスクはテスト実行に加えて、コード品質チェックなどプロジェクトに設定された検証処理を一括で行います。

JUnit 5をGradleで使うための設定方法

GradleはJUnit 5（JUnit Platform）をネイティブサポートしていますが、設定をしないとJUnit 5のテストが検出されません。`build.gradle`に以下の設定を追加する必要があります。

• `dependencies`ブロックに`testImplementation ‘org.junit.jupiter:junit-jupiter:5.11.0’`を追加
• `testRuntimeOnly ‘org.junit.platform:junit-platform-launcher’`を追加
• `test`タスク内に`useJUnitPlatform()`を指定

特に`useJUnitPlatform()`の指定は必須で、これがないとJUnit 5のテストが実行されません。JUnit 4との後方互換が必要な場合は`junit-vintage-engine`を追加します。依存関係のバージョンは記事公開時点でMaven Centralで最新を確認することをおすすめします。

テストタスクの主な設定項目とテストログの活用

テストタスクは`test`ブロック内でさまざまな設定が可能です。テスト結果のコンソール出力を詳細にしたい場合は、以下のように`testLogging`を設定します。

• testLogging { events "passed", "skipped", "failed" }：テストの成功・スキップ・失敗をコンソールに表示
• reports { html.required = true; xml.required = false }：レポート出力形式の制御
• maxParallelForks = 4：JVMフォーク数を増やして並列実行（詳細は次セクション）

テストログを設定すると、CIツールのログからもテスト結果を確認しやすくなります。レポート設定は、後述するJaCoCoやSonarQube連携時にXMLレポートが必要になるため、プロジェクトの要件に応じて適切に設定しましょう。

要点：Javaプロジェクトでは`./gradlew test`でテストを実行し、JUnit 5を使うには`useJUnitPlatform()`の指定が必須。テスト結果は`build/reports/tests/test/index.html`で確認できます。

テストを絞り込む！Gradleのテストフィルタリングと並列実行の設定

テストフィルタリングで実行するテストを制御する

Gradleのテストフィルタリングを使うと、実行するテストをクラス名やメソッド名で柔軟に絞り込めます。ビルドスクリプトで設定する場合は、`test`タスク内に`filter`ブロックを記述します。

• includeTestsMatching "*Test"：全パッケージの`*Test`クラスを実行
• excludeTestsMatching "*IntegrationTest"：統合テストを除外

コマンドラインから指定する場合は`–tests`オプションを使用します。例えば`./gradlew test –tests org.example.MyTest`のように実行できます。注意点として、`–tests`オプション使用時はビルドスクリプト内のincludeフィルタが無視されます。また、該当するテストがない場合、デフォルトではタスクが失敗します。

並列実行でテスト時間を短縮する方法

テストの実行時間を短縮するには、並列実行が有効です。Gradleでは`test`タスク内で`maxParallelForks`を設定することで、複数のJVMプロセスでテストを並列実行できます。以下のように設定します。

• maxParallelForks = 4：4つのJVMフォークで並列実行（デフォルトは1）
• systemProperty "junit.jupiter.execution.parallel.enabled", "true"：JUnit 5内部の並列実行を有効化

ただし、テスト間で共有状態を持つテストは並列実行で問題が起きることがあるため、注意が必要です。並列実行の導入は、テストが独立していることを確認してから行いましょう。テストクラス単位の並列実行は`maxParallelForks`、テストメソッド単位の並列実行はJUnit 5の設定で制御します。

フィルタリングと並列実行の実践的な組み合わせ

実際の開発では、フィルタリングと並列実行を組み合わせて使うことで効率的なテスト運用ができます。例えば、通常の開発中は`excludeTestsMatching “*SlowTest”`で遅いテストを除外し、`maxParallelForks = 2`で並列実行する設定にしておきます。CI環境では全テストを実行するプロファイルを用意する、という使い分けが可能です。コマンドラインでのフィルタは、特定のテストクラスだけを再実行したい場合に特に便利です。テストフィルタリングはクラス名・メソッド名ベースで動作するため、パッケージ構成とテスト命名規則を統一しておくと、フィルタ条件をシンプルに保てます。

要点：テストフィルタリングはfilterブロックまたは--testsオプションで指定し、並列実行はmaxParallelForksで制御します。フィルタと並列実行の組み合わせで開発効率を向上できます。

コード品質を可視化するJaCoCoカバレッジレポートの生成方法

JaCoCoプラグインの適用と基本設定

JaCoCo（Java Code Coverage）は、Javaプロジェクト向けのテストカバレッジ計測ツールで、Gradleプラグインとして提供されています。`build.gradle`に`id ‘jacoco’`を追加するだけで利用できます。プラグインを適用すると、テスト実行時にカバレッジデータ（`.exec`ファイル）が`build/jacoco/`に生成されます。JaCoCoは、テストがソースコードのどの行・どの分岐を実行したかを計測し、コード品質の可視化に役立ちます。カバレッジレポートは`jacocoTestReport`タスクで生成しますが、デフォルトではテスト実行後に自動生成されないため、明示的に実行するか`finalizedBy`でtestタスクに紐づける必要があります。

カバレッジレポートの生成と出力形式の設定

カバレッジレポートを生成するには、`jacocoTestReport`タスクを設定します。以下のように`reports`ブロックで出力形式を制御できます。

• xml.required = true：SonarQube連携に必須のXMLレポートを出力
• html.required = true：ブラウザで閲覧できるHTMLレポートを出力
• csv.required = false：CSV出力は不要な場合が多い

レポートの出力先は、XMLが`build/reports/jacoco/test/jacocoTestReport.xml`、HTMLが`build/reports/jacoco/test/html/index.html`です。実行コマンドは`./gradlew test jacocoTestReport`となります。SonarQubeでカバレッジを反映させるにはXMLレポートの生成が必須です。

カバレッジ閾値を設定して品質を担保する

カバレッジの最低基準を設定したい場合は、`jacocoTestCoverageVerification`タスクを使用します。以下のようにカバレッジの閾値を設定できます。

• counter = 'LINE'：行カバレッジを対象にする
• counter = 'BRANCH'：分岐カバレッジを対象にする
• minimum = 0.70：70%以上を要求

閾値未達の場合はビルドが失敗します。`check.dependsOn jacocoTestCoverageVerification`を設定すると、`./gradlew check`実行時に自動でカバレッジ検証が行われます。数値はプロジェクトの方針に応じて設定してください。マルチモジュールプロジェクトでは、Gradle 7.4以上の`jacoco-report-aggregation`プラグインで全サブプロジェクトのカバレッジを集約できます。

要点：JaCoCoはid 'jacoco'を追加するだけで使え、SonarQube連携にはXMLレポート（xml.required = true）が必須。閾値設定はjacocoTestCoverageVerificationで行います。

SonarQubeとGradleを連携する手順とプラグインの設定方法

SonarScanner for Gradleプラグインの導入

SonarQubeとGradleを連携するには、SonarScanner for Gradle（`org.sonarqube`プラグイン）を使用します。2026年8月時点の最新バージョンは7.3.1.8318（2026年6月3日リリース）です。`build.gradle`に以下のように記述します。

• id 'org.sonarqube' version '7.3.1.8318'をpluginsブロックに追加
• プラグインはルートプロジェクトにのみ適用するのが原則

プラグインを適用すると`sonar`タスクが利用可能になります。タスク名は`sonar`であり、`sonarqube`ではない点に注意してください。マルチモジュールプロジェクトでは、サブプロジェクトに適用すると重複解析や予期しない挙動の原因になるため、ルートプロジェクトのみに適用します。

sonar拡張ブロックでの接続設定

SonarQubeサーバーへの接続情報は、`sonar`拡張ブロックで設定します。以下のような設定が必要です。

• sonar.projectKey：プロジェクトを一意に識別するキー（毎回同じ値にする）
• sonar.host.url：SonarQubeサーバーのURL（例：`http://localhost:9000`）
• sonar.coverage.jacoco.xmlReportPaths：JaCoCoのXMLレポートパス

認証トークンはセキュリティ上、ビルドスクリプトに直接書かず、コマンドラインから`-Dsonar.token=YOUR_TOKEN`で渡すのが推奨されています。SonarScanner for Gradleは、JavaプロジェクトのソースパスやバイナリパスなどをGradleのオブジェクトモデルから自動推測するため、基本的なプロジェクトでは最小限の設定で連携できます。

解析の実行手順とタスク依存関係の注意点

SonarQube解析を実行するには、以下の順序でタスクを実行します。

1. `./gradlew test`：テストを実行してカバレッジデータを生成
2. `./gradlew jacocoTestReport`：XMLカバレッジレポートを生成
3. `./gradlew sonar -Dsonar.token=YOUR_TOKEN`：SonarQube解析を実行

SonarScanner for Gradle v3.0以降、プラグインはタスク依存関係を自動追加しません。そのため、`./gradlew sonar`だけを実行してもテストやカバレッジレポートは生成されず、カバレッジが0%になる原因となります。ワンコマンドで実行する場合は`./gradlew test jacocoTestReport sonar -Dsonar.token=YOUR_TOKEN`のように順番に指定します。

要点：SonarQube連携はorg.sonarqubeプラグインを適用し、sonarタスクで解析します。テスト→カバレッジレポート→解析の順で明示的に実行する必要があります。

よくあるトラブルと対処法：カバレッジ0%問題と品質ゲートの設定

カバレッジが0%になる原因と対処法

SonarQubeでカバレッジが0%と表示される問題は、Gradle連携で最も多いトラブルです。主な原因は以下のとおりです。

• XMLレポートが生成されていない（`xml.required = true`の設定漏れ）
• `jacocoTestReport`タスクが実行されていない
• `sonar.coverage.jacoco.xmlReportPaths`のパスが実際のレポート位置と一致していない
• マルチモジュールでサブプロジェクトのレポートパスがrootのみを指している

対処法として、まず`build/reports/jacoco/test/jacocoTestReport.xml`が存在するか確認します。存在しない場合は`jacocoTestReport`タスクを実行し、`reports.xml.required = true`の設定を確認します。マルチモジュールではワイルドカード`**/build/reports/jacoco/test/jacocoTestReport.xml`での指定も有効です。

品質ゲートをCIで活用する方法

SonarQubeの品質ゲートは、コード品質の基準を定義し、基準を満たさない場合にビルドを失敗させられる仕組みです。CIで品質ゲートを活用するには、以下の設定が有効です。

• sonar.qualitygate.wait=true：品質ゲート判定を待ってビルドを失敗させる
• GitHub Actionsではfetch-depth: 0を設定（shallow clone無効）

GitHub ActionsでPR解析を行う場合、浅いクローンでは十分なGit履歴が取得できず、正しい解析結果が得られないことがあります。`fetch-depth: 0`を設定して全履歴を取得しましょう。品質ゲートの判定をCIパイプラインに組み込むことで、品質基準を満たさないコードのマージを防げます。

プロジェクトキーの管理と重複解析の防止

SonarQubeで「Project Not Found」や毎回新規プロジェクトが作られる問題が発生する場合、`sonar.projectKey`の管理に問題があることが多いです。以下の点を確認しましょう。

• `sonar.projectKey`をビルドスクリプトに固定し、実行ごとに変化しないようにする
• Gitブランチ名やビルド番号をキーに含めない
• プラグインをルートプロジェクトにのみ適用し、サブプロジェクトへの重複適用を避ける

プロジェクトキーはSonarQube上でプロジェクトを一意に識別するため、安定的に同じ値を使うことが重要です。キーが変わると、過去の解析履歴や品質ゲートの設定と紐づかなくなり、実質的に新規プロジェクトとして扱われてしまいます。

要点：カバレッジ0%の主因はXMLレポート未生成またはパス不一致です。CIではsonar.qualitygate.wait=trueで品質ゲート判定を活用し、sonar.projectKeyは固定値を設定します。