jacoco生成代码覆盖率报告

最新推荐文章于 2026-06-22 08:04:45 发布

原创最新推荐文章于 2026-06-22 08:04:45 发布 · 1k 阅读

11 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

编程语言

一、Maven 项目集成 Jacoco

在 pom.xml 文件中添加 Jacoco 插件：

<build>
    <plugins>
        <plugin>
            <groupId>org.jacoco</groupId>
            <artifactId>jacoco-maven-plugin</artifactId>
            <version>0.8.10</version>
            <executions>
                <execution>
                    <goals>
                        <goal>prepare-agent</goal>
                    </goals>
                </execution>
                <execution>
                    <id>report</id>
                    <phase>test</phase>
                    <goals>
                        <goal>report</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

说明：

prepare-agent 目标会在测试前自动添加 Jacoco 的 Java Agent，用于收集覆盖率数据。
report 目标会在测试后自动生成覆盖率报告。

二、运行测试并生成报告

在项目根目录执行：

mvn clean test

或者：

mvn clean verify

执行完成后，Jacoco 会自动生成覆盖率报告。

三、查看覆盖率报告

报告默认生成在：

target/site/jacoco/index.html

用浏览器打开该 HTML 文件，即可看到详细的覆盖率统计，包括：

类、方法、行的覆盖率百分比
覆盖和未覆盖的代码高亮显示

同时还有 XML、CSV 等格式的报告，分别在 target/site/jacoco/ 目录下。

四、常见配置项

指定报告格式

<configuration>
    <outputDirectory>${project.build.directory}/jacoco-report</outputDirectory>
    <formats>
        <format>HTML</format>
        <format>XML</format>
    </formats>
</configuration>

排除/包含特定类或包

<configuration>
    <excludes>
        <exclude>**/dto/**</exclude>
        <exclude>**/config/**</exclude>
    </excludes>
</configuration>

设置覆盖率阈值（用于 CI 流程）

<execution>
    <goals>
        <goal>check</goal>
    </goals>
    <configuration>
        <rules>
            <rule>
                <element>BUNDLE</element>
                <limits>
                    <limit>
                        <counter>LINE</counter>
                        <value>COVEREDRATIO</value>
                        <minimum>0.80</minimum>
                    </limit>
                </limits>
            </rule>
        </rules>
    </configuration>
</execution>

这样可以在覆盖率不足时构建失败。

五、常见问题与解决办法

报告未生成？
- 检查测试是否执行成功，target/site/jacoco 目录是否存在。
- 检查插件版本和配置是否正确。
- 某些测试框架（如 TestNG、JUnit5）需确保 Maven Surefire 插件版本兼容 Jacoco。
覆盖率偏低？
- 确认测试代码是否真正覆盖了业务逻辑。
- 某些自动生成代码、配置类可通过 excludes 排除。
与 Spring Boot 集成？
- Spring Boot 项目也可直接使用 Jacoco Maven 插件，配置方式相同。

六、Gradle 项目集成 Jacoco

如果你的项目用的是 Gradle，只需在 build.gradle 添加：

plugins {
    id 'jacoco'
}

test {
    useJUnitPlatform()
    finalizedBy jacocoTestReport
}

jacocoTestReport {
    reports {
        xml.required = true
        html.required = true
    }
}

然后执行：

./gradlew test jacocoTestReport

报告路径为 build/reports/jacoco/test/html/index.html。

七、Jacoco 高级用法

1. 多模块（multi-module）项目覆盖率统计

如果你的项目是 Maven 的多模块结构，单独模块的覆盖率报告无法统计整体覆盖率。
可以用 jacoco:aggregate 目标聚合所有模块的覆盖率：

在父模块 pom.xml 添加：

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.10</version>
    <executions>
        <execution>
            <id>prepare-agent</id>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
        </execution>
        <execution>
            <id>report-aggregate</id>
            <phase>verify</phase>
            <goals>
                <goal>report-aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

然后执行：

mvn clean verify

聚合报告路径：target/site/jacoco-aggregate/index.html

2. 与 SonarQube 集成

Jacoco 可以生成 XML 格式的覆盖率报告，供 SonarQube 代码质量平台分析。

在 Jacoco 配置中添加：

<configuration>
    <outputDirectory>${project.build.directory}/jacoco-report</outputDirectory>
    <dataFile>${project.build.directory}/jacoco.exec</dataFile>
    <reports>
        <xml enabled="true"/>
        <html enabled="true"/>
    </reports>
</configuration>

然后在 SonarQube 配置里指定 Jacoco 的 XML 报告路径：

sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

3. 命令行生成报告（无 Maven/Gradle 时）

如果你用的是普通 Java 项目，可以用 Jacoco CLI 工具：

运行测试时加上 Jacoco 的 Java Agent，如下：

java -javaagent:/path/to/jacocoagent.jar=destfile=jacoco.exec -jar myapp.jar

用 Jacoco CLI 工具生成报告：

java -jar jacococli.jar report jacoco.exec \
    --classfiles ./target/classes \
    --sourcefiles ./src/main/java \
    --html ./coverage-report

4. Jacoco 与 CI/CD 集成

1）Jenkins

在 Jenkinsfile 里加上 mvn clean verify 步骤。
用 Jacoco 插件可自动收集并展示覆盖率报告。

2）GitLab CI

.gitlab-ci.yml 示例：

stages:
  - test

test:
  script:
    - mvn clean verify
  artifacts:
    paths:
      - target/site/jacoco/

3）GitHub Actions

name: Java CI with Jacoco

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
    - name: Build with Maven
      run: mvn clean verify
    - name: Upload coverage report
      uses: actions/upload-artifact@v3
      with:
        name: jacoco-report
        path: target/site/jacoco/

八、常见场景与技巧

1. 只统计主业务代码覆盖率

可以通过 Jacoco 的 includes 和 excludes 精确指定统计哪些包：

<configuration>
    <excludes>
        <exclude>**/dto/**</exclude>
        <exclude>**/config/**</exclude>
        <exclude>**/generated/**</exclude>
    </excludes>
</configuration>

2. 测试覆盖率阈值校验（构建失败）

如前文所述，可用 check goal：

<execution>
    <id>jacoco-check</id>
    <goals>
        <goal>check</goal>
    </goals>
    <configuration>
        <rules>
            <rule>
                <element>BUNDLE</element>
                <limits>
                    <limit>
                        <counter>LINE</counter>
                        <value>COVEREDRATIO</value>
                        <minimum>0.80</minimum>
                    </limit>
                </limits>
            </rule>
        </rules>
    </configuration>
</execution>

3. Jacoco 与 JUnit5/Spring Boot 兼容性

确保 Maven Surefire 插件版本 >= 2.22.0
Spring Boot 项目建议用 spring-boot-maven-plugin 和 Jacoco 配合

九、Jacoco 报告解读

红色/橙色：未覆盖代码
绿色：已覆盖代码
覆盖率统计：包括行覆盖率、分支覆盖率、方法覆盖率等
点击每个类可以看到详细的覆盖情况

十、Jacoco 报告优化与高级配置

1. 定制报告内容

你可以通过 Jacoco 插件配置，定制报告中显示的内容，甚至自定义报告输出目录和格式：

<configuration>
    <outputDirectory>${project.build.directory}/custom-jacoco-report</outputDirectory>
    <dataFile>${project.build.directory}/jacoco.exec</dataFile>
    <reports>
        <html enabled="true"/>
        <xml enabled="true"/>
        <csv enabled="false"/>
    </reports>
    <includes>
        <include>com/example/service/*</include>
        <include>com/example/controller/*</include>
    </includes>
    <excludes>
        <exclude>**/dto/**</exclude>
        <exclude>**/config/**</exclude>
    </excludes>
</configuration>

2. 合并多个 exec 文件

在某些场景下（比如分布式测试或多阶段测试），你可能会生成多个 jacoco.exec 文件。可以用 Jacoco CLI 工具合并：

java -jar jacococli.jar merge exec1.exec exec2.exec --destfile merged.exec

然后用合并后的 exec 文件生成报告。

3. 只统计测试覆盖率，不统计主方法覆盖率

有时候你只关心单元测试的覆盖率，而不希望主程序运行时的覆盖率混入统计。
建议只在测试阶段启用 Jacoco Agent（即 prepare-agent 只在 test 或 verify 阶段执行）。

4. 支持分支覆盖率和条件覆盖率

Jacoco 不仅统计行覆盖率，还能统计分支覆盖率（如 if/else、switch），报告中会清晰展示每个分支是否被测试覆盖。

十一、常见问题与解决方案

1. Jacoco 报告为空或覆盖率为 0%

检查测试是否实际调用了你的业务代码。
确认测试类和被测类在同一个 ClassLoader 下。
某些情况下，Jacoco 对于动态生成的类或 AOP 代理类无法统计覆盖率。

2. Spring Boot 项目覆盖率异常

Spring Boot 默认用 spring-boot-maven-plugin，可与 Jacoco 配合使用。
如果用嵌入式 Tomcat 或 Undertow，需确保 Jacoco Agent 正确挂载。

3. Jacoco 与 JUnit5 兼容性

Maven Surefire 插件需 >= 2.22.0。
如果用 @SpringBootTest 或集成测试，确保 Jacoco Agent 在测试 JVM 启动时加载。

4. Jacoco 与 TestNG、Spock 等框架兼容性

Jacoco 支持主流测试框架，但某些高级特性（如并发测试、动态类加载）可能导致覆盖率统计不准确。
遇到问题时，建议升级 Jacoco 和测试插件版本，并查阅官方 FAQ。

十二、Jacoco 在特殊场景下的应用

1. Android 项目

Android 项目可用 JaCoCo Gradle Plugin for Android。
需在 build.gradle 中配置，生成报告路径为 app/build/reports/jacoco/jacocoTestReport/html/index.html。

2. 代码质量门禁（Gatekeeping）

在 CI 流程中设置覆盖率阈值，自动阻止覆盖率过低的代码合并。
结合 GitHub Actions、GitLab CI、SonarQube 等自动化工具实现。

3. 增量覆盖率（仅统计新增/修改代码的覆盖率）

可与 SonarQube 或其他代码质量平台结合，只统计 PR/分支的增量覆盖率，提升测试针对性。

十三、Jacoco 与其它工具的集成

1. 与 Coveralls、Codecov 集成

生成 Jacoco 的 XML 报告后，可上传到 Coveralls、Codecov 等平台，获得更直观的覆盖率趋势和历史对比。

2. 与 IDE 集成

IntelliJ IDEA、Eclipse 等 IDE 支持直接运行测试并生成 Jacoco 覆盖率报告，便于开发时实时查看。

十四、常用命令总结

生成报告（Maven）：
mvn clean test 或 mvn clean verify
查看报告：
target/site/jacoco/index.html
合并 exec 文件：
java -jar jacococli.jar merge ...
CLI 生成报告：
java -jar jacococli.jar report ...

创作不易，点赞关注，感谢支持，互通有无！

标签

#代码覆盖率 #jacoco