JaCoCoの使い方｜Gradle・Mavenでカバレッジを測りCIで基準を決める

JaCoCo（ジャココ）は、Java のテストを実行したときに「どの命令・分岐・行が実行されたか」を測り、カバレッジ（網羅率）のレポートを作るツールです。 Gradle は jacoco プラグイン、Maven は jacoco-maven-plugin を足すだけで使えます。

基準を決めて、下回ったらビルドを失敗させることもできます。 実際に「命令 80% 以上、クラスごとの分岐 70% 以上」のルールで Gradle を実行すると、次のように止まりました。

> Task :jacocoTestCoverageVerification FAILED
[ant:jacocoReport] Rule violated for bundle demo: instructions covered ratio is 0.67, but expected minimum is 0.80
[ant:jacocoReport] Rule violated for class com.example.PriceCalculator: branches covered ratio is 0.50, but expected minimum is 0.70

確認環境：JaCoCo 0.8.15（GitHub のリリースで最新の版。2026年6月4日公開）を、タグ v0.8.15 のソースから ASM 9.7 でビルドし、OpenJDK 21.0.10（Linux）で使いました。小さな Java のクラスと JUnit 4.13.2 のテストに、エージェント（計測用のプログラム）を付けて計測し、コマンドライン版でレポートを作成しました。Gradle 8.14.3 の jacoco プラグイン（toolVersion = "0.8.15"）でも、レポートとルール判定を実行しています。Maven の設定・既定値・メッセージは、jacoco-maven-plugin のソースとドキュメントで確かめました（確認日 2026年10月13日）。

版について

Gradle は、Gradle の版ごとに既定の JaCoCo の版が決まっています。 新しい Java で動かすときは、jacoco { toolVersion = "0.8.15" } と明示すると、Gradle の版に左右されません。変更履歴によると、0.8.15 は Java 26 に正式対応し、Java 27 のクラスファイルを試験的に扱えます。

Gradle の設定全文（build.gradle.kts）

この記事で実際に動かした設定です（repositories だけ mavenCentral() に戻しています）。

plugins {
    java
    jacoco
}

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("junit:junit:4.13.2")
}

java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }

jacoco {
    toolVersion = "0.8.15"
}

tasks.test {
    finalizedBy(tasks.jacocoTestReport)   // テストの後に必ずレポートを作る
}

val coverageExcludes = listOf("**/config/**", "**/*Application*")

tasks.jacocoTestReport {
    dependsOn(tasks.test)
    classDirectories.setFrom(
        files(classDirectories.files.map { fileTree(it) { exclude(coverageExcludes) } })
    )
    reports {
        xml.required = true    // CI や SonarQube で読む
        csv.required = true    // 集計に使う
        html.required = true   // 人が見る
    }
}

tasks.jacocoTestCoverageVerification {
    classDirectories.setFrom(
        files(classDirectories.files.map { fileTree(it) { exclude(coverageExcludes) } })
    )
    violationRules {
        rule {
            limit {
                minimum = "0.80".toBigDecimal()          // 既定は INSTRUCTION の COVEREDRATIO
            }
        }
        rule {
            element = "CLASS"
            limit {
                counter = "BRANCH"
                value = "COVEREDRATIO"
                minimum = "0.70".toBigDecimal()
            }
        }
    }
}

tasks.check {
    dependsOn(tasks.jacocoTestCoverageVerification)   // ./gradlew check で判定も走る
}

JUnit 5（JUnit Platform）を使う場合は、tasks.test { useJUnitPlatform() } を足します。JaCoCo の設定は同じです。

./gradlew test                              # テスト → レポート（finalizedBy）
./gradlew check                             # テスト → レポート → 基準の判定
./gradlew jacocoTestCoverageVerification    # 判定だけ

Groovy DSL（build.gradle）で書く場合の対訳は、関連記事「build.gradle書き方｜Groovy/Kotlin DSL対訳と依存設定一覧」で扱っています。

Maven の設定全文（pom.xml の build 部分）

<build>
  <plugins>
    <plugin>
      <groupId>org.jacoco</groupId>
      <artifactId>jacoco-maven-plugin</artifactId>
      <version>0.8.15</version>
      <configuration>
        <excludes>
          <exclude>**/config/**</exclude>
          <exclude>**/*Application*</exclude>
        </excludes>
      </configuration>
      <executions>
        <!-- テストの JVM にエージェントを付ける（argLine に設定される） -->
        <execution>
          <id>prepare-agent</id>
          <goals>
            <goal>prepare-agent</goal>
          </goals>
        </execution>
        <!-- verify フェーズでレポートを作る -->
        <execution>
          <id>report</id>
          <goals>
            <goal>report</goal>
          </goals>
        </execution>
        <!-- verify フェーズで基準を判定する -->
        <execution>
          <id>check</id>
          <goals>
            <goal>check</goal>
          </goals>
          <configuration>
            <rules>
              <rule>
                <element>BUNDLE</element>
                <limits>
                  <limit>
                    <counter>INSTRUCTION</counter>
                    <value>COVEREDRATIO</value>
                    <minimum>0.80</minimum>
                  </limit>
                </limits>
              </rule>
              <rule>
                <element>CLASS</element>
                <limits>
                  <limit>
                    <counter>BRANCH</counter>
                    <value>COVEREDRATIO</value>
                    <minimum>0.70</minimum>
                  </limit>
                </limits>
              </rule>
            </rules>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

./mvnw verify      # test → report → check

jacoco-maven-plugin のソースでは、各ゴールの既定のフェーズは次のとおりです。

基準を満たさないと、check は次のメッセージでビルドを止めます（ソースの文言）。満たしたときは All coverage checks have been met. です。

Coverage checks have not been met. See log for details.

pom.xml の書き方とコマンドは、関連記事「Mavenコマンド一覧｜pom.xml書き方とよく使うオプション」で扱っています。

Maven でよくある失敗：argLine を上書きしている

Surefire（テストを実行するプラグイン）の設定で <argLine> を自分で書くと、JaCoCo が入れたエージェントの指定が消えます。 すると jacoco.exec が作られず、report と check は次のメッセージで飛ばされます（ソースの文言）。

Skipping JaCoCo execution due to missing execution data file:

自分の JVM オプションを足すときは、@{argLine} で JaCoCo の分を残します。

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <argLine>@{argLine} -Xmx1g -Dfile.encoding=UTF-8</argLine>
  </configuration>
</plugin>

計測した対象とテスト

ここからの結果は、次のクラスとテストで計測したものです。

package com.example;

public class PriceCalculator {

    /** 合計金額。会員で 5000 円以上なら 1 割引き */
    public int total(int price, int qty, boolean member) {
        if (price < 0 || qty < 0) {
            throw new IllegalArgumentException("negative");
        }
        int sum = price * qty;
        if (member && sum >= 5000) {
            sum = sum * 90 / 100;
        }
        return sum;
    }

    /** ポイントからランクを決める */
    public String rank(int points) {
        if (points >= 1000) {
            return "GOLD";
        } else if (points >= 100) {
            return "SILVER";
        }
        return "BRONZE";
    }

    /** どこからも呼ばれないメソッド */
    public int unused() {
        return 42;
    }
}

public class PriceCalculatorTest {
    private final PriceCalculator calc = new PriceCalculator();

    @Test public void memberDiscount() { assertEquals(5400, calc.total(1000, 6, true)); }
    @Test public void noDiscount()     { assertEquals(100, calc.total(100, 1, false)); }
    @Test public void gold()           { assertEquals("GOLD", calc.rank(1500)); }
}

レポートの読み方

1回目の結果（テスト3件）

HTML レポートのクラスの表です。

「Missed」は実行されなかった数です。メソッドは 4 個中 1 個（unused）が一度も呼ばれていませんでした。同じテストでも、命令 67%・分岐 50%・行 約62%（8/13）・メソッド 75%（3/4）と、指標によって数字が違います。

指標（カウンター）の違い

JaCoCo のドキュメント「Coverage Counters」の説明をまとめました。

• 命令（C0）は、ソースの書き方（改行の位置など）に左右されません。デバッグ情報が無くても測れます。
• 分岐（C1）は、a || b のような条件も1つずつの分かれ道として数えます。if (price < 0 || qty < 0) は4つの分岐になります。ドキュメントには「例外処理（try/catch）は分岐として数えない」とあります。
• 行は、クラスファイルにデバッグ情報（行番号）があるときだけ測れます。
• 複雑度は、ドキュメントでは「すべての道を通すのに要るテストの数の目安」と説明され、「Missed の複雑度」は足りないテストの数の目安になります。今回は 6 でした。

C0・C1 などのホワイトボックステストの考え方は、関連記事「テスト技法一覧｜ブラックボックス・ホワイトボックスの種類と選び方早見表」で扱っています。

色とひし形の意味

ソースのページでは、行の背景の色と、行の左のひし形で状態を表します。今回の結果です。

黄色の行が「テストが足りない条件」の目印です。 11行目の 1 of 4 branches missed. は、「会員で 5000 円未満」の組み合わせを通っていないことを表していました。表の「Missed Instructions」などの棒グラフは、赤が実行されなかった分、緑が実行された分の割合です。

2回目の結果（テストを足す）

黄と赤の行を見て、次の3件を足しました。

@Test(expected = IllegalArgumentException.class)
public void negativePrice() { calc.total(-1, 1, false); }

@Test
public void memberBelow5000() { assertEquals(4000, calc.total(1000, 4, true)); }

@Test
public void silverAndBronze() {
    assertEquals("SILVER", calc.rank(100));
    assertEquals("BRONZE", calc.rank(99));
}

分岐で1つ残ったのは、price < 0 || qty < 0 の「qty < 0 が true」の道です。price が負のときは || の右側が評価されないため、calc.total(1, -1, false) のテストが要ります。境界値の選び方は、関連記事「同値分割・境界値分析｜テストケース表とpytestコード例で解説」で扱っています。

基準未達で失敗させる（ルールの書き方）

ルールの部品

よく使うルールの例（Gradle）

violationRules {
    // 全体で命令 80% 以上
    rule { limit { minimum = "0.80".toBigDecimal() } }

    // 全体で分岐 70% 以上
    rule { limit { counter = "BRANCH"; minimum = "0.70".toBigDecimal() } }

    // 実行されなかったメソッドを 0 個にする（クラスごと）
    rule {
        element = "CLASS"
        limit { counter = "METHOD"; value = "MISSEDCOUNT"; maximum = "0".toBigDecimal() }
    }

    // service パッケージだけ厳しく
    rule {
        element = "PACKAGE"
        includes = listOf("com.example.service")
        limit { counter = "LINE"; minimum = "0.90".toBigDecimal() }
    }
}

失敗したときのメッセージの形は、Rule violated for <要素> <名前>: <カウンター> <値> is <実際>, but expected <minimum|maximum> is <基準> です。Maven の check も同じ JaCoCo のしくみで判定します（jacoco-maven-plugin の結合テストでは、methods missed count is 1, but expected maximum is 0 という文を確かめています）。

分岐が1つも無いクラス（getter だけのクラスなど）は、分岐のルールでは失敗しませんでした。 除外しないまま分岐 70% のクラスごとのルールで判定しても、分岐 0 個の AppConfig は違反になりませんでした。

基準値の決め方の目安

カバレッジは「テストが通った場所」を示すだけで、判定（assert）が正しいかは示しません。 assert の無いテストでも数字は上がるので、レビューと組み合わせます。品質の数値の扱いは、関連記事「品質管理の指標一覧（システム開発）｜バグ密度・レビュー指摘密度の計算式」で扱っています。

除外の書き方

Gradle：クラスのディレクトリから外す

上の設定全文の classDirectories.setFrom(…) の部分です。レポート（jacocoTestReport）と判定（jacocoTestCoverageVerification）の両方に書きます。 片方だけだと、レポートと判定の数字がずれます。

除外の有無で比べた CSV の結果です（com.example.config.AppConfig はテストから呼ばれないクラス）。

# 除外なし
demo,com.example,PriceCalculator,0,41,1,11,0,12,1,8,0,3
demo,com.example.config,AppConfig,5,0,0,0,2,0,2,0,2,0

# "**/config/**" を除外
demo,com.example,PriceCalculator,0,41,1,11,0,12,1,8,0,3

Maven：configuration の excludes

<configuration>
  <excludes>
    <exclude>**/config/**</exclude>
    <exclude>**/dto/*</exclude>
    <exclude>com/example/DemoApplication.class</exclude>
  </excludes>
</configuration>

パターンはクラスファイルのパス（/ 区切り）で書きます。

@Generated の付いたメソッド・クラスは自動で除外される

JaCoCo のソース（AnnotationGeneratedFilter）には、「単純名に Generated を含み、保持期間が CLASS か RUNTIME の注釈」が付いたものを除外するとあります。自作の注釈でも効きました。

@Retention(RetentionPolicy.CLASS)
public @interface Generated {}

public class PriceCalculator {
    @Generated
    public int unused() { return 42; }
}

unused() に付けると、レポートから消え、メソッドの Missed が 1 → 0、命令の Missed が 2 → 0 になりました。Lombok は、設定ファイル lombok.config に lombok.addLombokGeneratedAnnotation = true を書くと、生成したメソッドに @lombok.Generated を付けます。 Lombok の注釈の一覧は、関連記事「Lombokアノテーション一覧｜展開後コードと使い分け早見表」で扱っています。

何を除外するかの目安

ロジックのあるクラスを除外して数字を上げることは避けます。 除外したものは、一覧としてチームで共有します。

GitHub Actions で出力する

テストの後に、HTML レポートを成果物（artifact）として保存し、要点をジョブの概要（Job Summary）に書き出す例です。

# .github/workflows/coverage.yml
name: coverage

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'

      - uses: gradle/actions/setup-gradle@v4

      - name: Test and verify coverage
        run: ./gradlew check

      - name: Write coverage summary
        if: always()
        run: |
          CSV=build/reports/jacoco/test/jacocoTestReport.csv
          [ -f "$CSV" ] || exit 0
          awk -F, 'NR>1 { im+=$4; ic+=$5; bm+=$6; bc+=$7; lm+=$8; lc+=$9 }
          END {
            printf "| 指標 | カバレッジ |\n|---|---|\n";
            printf "| 命令（C0） | %.1f%% (%d/%d) |\n", 100*ic/(im+ic), ic, im+ic;
            printf "| 分岐（C1） | %.1f%% (%d/%d) |\n", 100*bc/(bm+bc), bc, bm+bc;
            printf "| 行 | %.1f%% (%d/%d) |\n", 100*lc/(lm+lc), lc, lm+lc;
          }' "$CSV" >> "$GITHUB_STEP_SUMMARY"

      - name: Upload coverage report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: jacoco-report
          path: build/reports/jacoco/test/html

awk の部分は、この記事の CSV（除外なし）で次の表を出しました。

| 指標 | カバレッジ |
|---|---|
| 命令（C0） | 89.1% (41/46) |
| 分岐（C1） | 91.7% (11/12) |
| 行 | 85.7% (12/14) |

Maven の場合は、run: ./mvnw -B verify、CSV は target/site/jacoco/jacoco.csv、HTML は target/site/jacoco です。GitHub Actions の基本は、関連記事「CI/CDとは｜GitHub Actionsで最初のパイプラインを作るまで」で、キャッシュの設定は、関連記事「GitHub Actionsのキャッシュとmatrix｜コピペ用YAMLとキー設計」で扱っています。

コマンドラインで使う（エージェントと CLI）

ビルドツールを使わずに測ることもできます。この記事の1回目の数字は、この方法で出したものです。

# 1. エージェントを付けてテスト（またはアプリ）を実行
java -javaagent:jacocoagent.jar=destfile=build/jacoco.exec,includes=com.example.* \
     -cp build/main:build/test:junit-4.13.2.jar:hamcrest-2.2.jar \
     org.junit.runner.JUnitCore com.example.PriceCalculatorTest

# 2. 計測データの中身を見る
java -jar jacococli.jar execinfo build/jacoco.exec

# 3. レポートを作る
java -jar jacococli.jar report build/jacoco.exec \
     --classfiles build/main --sourcefiles src/main/java \
     --html build/report/html --xml build/report/jacoco.xml --csv build/report/jacoco.csv

execinfo の出力です。クラスごとに「通ったプローブ（計測点）の数／全体」が出ます。

CLASS ID         HITS/PROBES   CLASS NAME
ef1d019c94d88cfa    5 of  12   com/example/PriceCalculator
345bdc9746e73066    5 of   5   com/example/PriceCalculatorTest

レポートの出力先のディレクトリが無いと、CLI は FileNotFoundException で止まりました（--xml build/report/jacoco.xml の build/report が無いとき）。先に作っておきます。

よくある質問

Q. レポートが作られず、jacocoTestReport が SKIPPED になります。 A. 計測データ（build/jacoco/test.exec）が無いときは飛ばされます。テストが1件も実行されていない（JUnit 5 で useJUnitPlatform() が無いなど）ことが多いです。JUnit の設定は、関連記事「JUnitの使い方｜単体テストの書き方と観点【JUnit 5・6】」で扱っています。

Q. 行のカバレッジが出ません。 A. ドキュメントでは、行の情報はデバッグ情報付きでコンパイルしたクラスでだけ測れます。Gradle・Maven の既定のコンパイルでは付きます。

Q. マルチモジュールで全体のレポートを1つにしたいです。 A. Maven は report-aggregate ゴール、Gradle は jacoco-report-aggregation プラグインで、複数モジュールの結果を1つのレポートにまとめられます。

Q. Spring Boot のテストでも同じですか。 A. 同じです。@SpringBootTest のテストも、テストの JVM で実行されるので計測されます。Spring Boot のテストの書き方は、関連記事「Spring Bootテスト入門｜@WebMvcTestとMockMvcの使い分け」で扱っています。Python で同じことをする場合は、関連記事「pytest 使い方｜導入からfixture・mock・カバレッジまで実行結果つき」で扱っています。

まとめ

• Gradle は plugins { jacoco }、Maven は prepare-agent・report・check の3ゴール
• 命令（C0）・分岐（C1）・行・メソッドで数字が違う。今回は同じテストで 67%・50%・約62%・75%
• 黄色の行と黄のひし形が、足りない条件の目印
• 基準は jacocoTestCoverageVerification（Gradle）・check（Maven）。メッセージは Rule violated for … but expected minimum is …
• 除外はレポートと判定の両方に書く。@Generated の付いたものは自動で除外
• CI は ./gradlew check で止め、HTML を artifact、要点を Job Summary に出す

参考・出典

確認日はいずれも 2026年10月13日です。

• JaCoCo 公式サイト：https://www.jacoco.org/jacoco/
• JaCoCo ドキュメント「Coverage Counters」：https://www.jacoco.org/jacoco/trunk/doc/counters.html
• JaCoCo ドキュメント「Maven Plug-in」：https://www.jacoco.org/jacoco/trunk/doc/maven.html
• JaCoCo ドキュメント「Java Agent」：https://www.jacoco.org/jacoco/trunk/doc/agent.html
• JaCoCo（GitHub、ソース・タグ v0.8.15）：https://github.com/jacoco/jacoco
• Gradle User Manual「The JaCoCo Plugin」：https://docs.gradle.org/current/userguide/jacoco_plugin.html
• Gradle（GitHub、ソース・タグ v9.8.1）：https://github.com/gradle/gradle
• GitHub Docs「Workflow commands（Adding a job summary）」：https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。