jacoco生成单元测试覆盖率报告

前言

单元测试是日常编写代码中常用的，用于测试业务逻辑的一种方式，单元测试的覆盖率可以用来衡量我们的业务代码经过测试覆盖的比例。

目前市场上开源的单元测试覆盖率的java插件，主要有Emma，Cobertura，Jacoco。具体对比如下：

工具	Jacoco	Emma	Cobertura
原理	使用 ASM 修改字节码	修改 jar 文件，class 文件字节码文件	基于 jcoverage,基于 asm 框架对 class 文件插桩
覆盖粒度	行，类，方法，指令，分支	行，类，方法，基本块，指令，无分支覆盖	项目，包，类，方法的语句覆盖/分支覆盖
插桩	on the fly、offline	on the fly、offline	offline，把统计代码插入编译好的class文件中
生成结果	在 Tomcat 的 catalina.sh 配置 javaangent 参数，指出需要收集覆盖率的文件，shutdown 时才收集，只能使用 kill 命令关闭 Tomcat，不要使用 kill -9	html、xml、txt，二进制格式报表	html，xml
缺点	需要源代码	1、需要 debug 版本，并打来 build.xml 中的 debug 编译项； 2、需要源代码，且必须与插桩的代码完全一致	1、不能捕获测试用例中未考虑的异常； 2、关闭服务器才能输出覆盖率信息（已有修改源代码的解决方案，定时输出结果；输出结果之前设置了 hook，会与某些服务器的 hook 冲突，web 测试中需要将 cobertura.ser 文件来回 copy
性能	快	小巧	插入的字节码信息更多
执行方式	maven，ant，命令行	命令行	maven，ant
jenkins集成	生成 html 报告，直接与 hudson 集成，展示报告，无趋势图	无法与 hudson 集成	有集成的插件，美观的报告，有趋势图
报告实时性	默认关闭，可以动态从jvm dump出数据	可以不关闭服务器	默认是关闭服务器时才写结果
维护状态	持续更新	停止维护	停止维护

其实上面的对比意义不大，只看最后一条即可，只有jacoco还在持续更新，所以我们肯定首选jacoco。

maven工程使用jacoco配置

在jacoco官网上就有关于maven插件配置的示例，包含单模块单元测试覆盖率报告和统计多模块单元测试覆盖率报告的配置。这里我也分单模块和多模块进行配置说明。

顺便说明，在官网提供的单模块配置中，需要使用两个命令才能生成测试覆盖率报告：
$> mvn clean test # 生成jacoco.exec文件，这里记录了测试执行的情况
$> mvn jacoco:report # 从jacoco.exec文件中解析并生成html测试报告

单模块工程覆盖率报告生成

在pom.xml文件中添加如下插件配置：

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

这里相比官网，我添加了如下配置：

<phase>test</phase>

这个配置可以让我们在执行mvn test的时候直接生成测试报告，不用单独执行mvn jacoco:report。

另外我移除了如下配置：

<execution>
    <id>default-check</id>
    <goals>
        <goal>check</goal>
    </goals>
    <configuration>
        <rules>
            <rule>
                <element>BUNDLE</element>
                <limits>
                    <limit>
                        <counter>COMPLEXITY</counter>
                        <value>COVEREDRATIO</value>
                        <minimum>0.60</minimum>
                    </limit>
                </limits>
            </rule>
        </rules>
    </configuration>
</execution>

这一段主要是用于检查测试覆盖率是否达到要求的配置，我们很少在这个阶段进行覆盖率检查，所以可以去掉这段配置为pom.xml瘦身，当然如果有需要可以加上，并且使用如下命令检查：

$> mvn jacoco:check

完成上述配置后，使用如下命令即可生成测试报告（测试报告在target/site/jacoco中）：

$> mvn test

多模块工程覆盖率报告生成

在多模块的工程中，测试执行的数据文件（jacoco.exec）和报告通常分散在不同的模块中，看聚合结果非常不便，因此我们通常会考虑将报告聚合起来看结果。

聚合报告的方式有两种，一种是使用jacoco的maven插件提供的聚合功能，这种方式在配置上比较麻烦，但是配置完成后可以不依赖外部应用直接查看结果。另一种方式是使用外部工具（如sonar）自动聚合报告，这种方式配置简单，但是需要以来外部应用。

使用sonar聚合报告的配置

使用sonar聚合报告的配置，只需要直接在工程的root模块中，配置如下插件：

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

然后再在root工程的根目录下配置sonar的扫描配置文件sonar-project.properties即可:

sonar.projectKey=${projectKey}
sonar.projectName=${projectName}
sonar.projectVersion=${projectVersion}
sonar.language=java
sonar.modules=${module1},${module2}
sonar.sources=src/main/java
sonar.java.binaries=target/classes
sonar.sourceEncoding=UTF-8
sonar.coverage.jacoco.xmlReportPaths=..

这里对属性作简单说明：

${projectKey}是工程在sonar中的ID
${prjectName}是工程在sonar中的名字
${projectVersion}是工程在sonar中的版本，通常来说可以自行定义，不过建议跟应用保持一致，如1.0
${module1},${module2}是工程模块，即模块在根目录的相对路径（笔者这里没有验证是相对目录还是模块名称，因为在我这里这两个是一致的，通常也建议保持一致，猜测是相对路径，因为sonar并没有分析pom.xml文件，实际上无法知道你的模块路径），多个模块用英文逗号分隔

我们特别注意sonar.coverage.jacoco.xmlReportPaths这个属性的配置，值是..，表示上一层目录。这是因为sonar-scanner在扫描报告时，会在执行路径生成.scannerwork文件夹，并以此文件夹为workdir，而我们需要扫描的目录是根目录，因此需要使用..回到根目录。

这点可以在sonar-scanner的扫描日志中看到：

INFO: Base dir: ~/workspace/griffin
INFO: Working dir: ~/workspace/griffin/.scannerwork

我的执行目录是~/workspace/griffin，因此basedir是~/workspace/griffin，而working dir是~/workspace/griffin/.scannerwork。

完成上述配置之后，我们就可以通过如下命令将报告扫描并上传到sonar了：

$> mvn clean test
$> sonar-scanner -Dsonar.host.url=${sonarUrl} -Dsonar.login=${sonarUsername} -Dsonar.password=${sonarPassword}

这个过程发生了什么？

先通过maven运行单元测试，并在每个模块生成jacoco.exec执行数据文件
通过jacoco.exec数据文件，在每个模块的target/site/jacoco生成xml报告(还有html等其他格式的报告)
sonar-scanner扫描根目录下所有xml报告并上传到sonar服务
sonar服务整合计算报告，并生成结果

最终我们可以在sonar中看到如下报告：

sonar

使用jacoco聚合报告的配置

使用jacoco的聚合报告配置，配置稍微复杂一些，需要使用maven的ant插件，我们可以在root工程的根目录下创建一个jacoco.xml文件，它本质是一个pom文件，内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-coverage-aggregate</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-antrun-plugin</artifactId>
                <version>3.0.0</version>
                <executions>
                    <execution>
                        <phase>post-integration-test</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                        <configuration>
                            <target>
                                <echo message="Generating JaCoCo Reports" />
                                <taskdef name="report" classname="org.jacoco.ant.ReportTask">
                                    <classpath path="${basedir}/target/jacoco-jars/org.jacoco.ant.jar" />
                                </taskdef>
                                <mkdir dir="${basedir}/target/coverage-report" />
                                <report>
                                    <executiondata>
                                        <fileset dir="${basedir}/${module1}/target">
                                            <include name="jacoco.exec" />
                                        </fileset>
                                        <fileset dir="${basedir}/${module2}/target">
                                            <include name="jacoco.exec" />
                                        </fileset>
                                        <fileset dir="${basedir}/${module3}/target">
                                            <include name="jacoco.exec" />
                                        </fileset>
                                    </executiondata>
                                    <structure name="jacoco-multi Coverage Project">
                                        <group name="jacoco-multi">
                                            <classfiles>
                                                <fileset dir="${basedir}/${module1}/target/classes" />
                                                <fileset dir="${basedir}/${module2}/target/classes" />
                                                <fileset dir="${basedir}/${module3}/target/classes" />
                                            </classfiles>
                                            <sourcefiles encoding="UTF-8">
                                                <fileset dir="${basedir}/${module1}/src"/>
                                                <fileset dir="${basedir}/${module2}/src"/>
                                                <fileset dir="${basedir}/${module3}/src"/>
                                            </sourcefiles>
                                        </group>
                                    </structure>
                                    <html destdir="${basedir}/target/coverage-report/html" />
                                    <xml destfile="${basedir}/target/coverage-report/coverage-report.xml" />
                                    <csv destfile="${basedir}/target/coverage-report/coverage-report.csv" />
                                </report>
                            </target>
                        </configuration>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>org.jacoco</groupId>
                        <artifactId>org.jacoco.ant</artifactId>
                        <version>0.8.7</version>
                    </dependency>
                </dependencies>
            </plugin>
        </plugins>
    </build>
</project>

在这个配置中，我有三个模块，因此在配置文件中有${module1}, ${module2}, ${module3}三个占位符，分别代表三个模块的目录名（实际使用的时候需要改成真正的值），另外对于pom文件，groupId，artifactId和version是必须的元素，在这里其实随便起名即可，示例中给了一个勉强通用的配置，当然建议改成和工程相当的值。

完成上述配置后，使用如下两个命令即可生成合并的测试报告：

$> mvn clean test
$> mvn clean verify -f jacoco.xml

最终可以在{project.basedir}/target/coverage-report目录下看到聚合的报告结果，包含html和xml：

jacoco

这个过程发生了什么？

先通过maven运行单元测试，并在每个模块生成jacoco.exec执行数据文件
使用maven指定jacoco.xml文件作为pom文件，利用ant插件聚合单元测试覆盖率报告
ant插件通过executiondata标签的配置搜集jacoco的数据文件
ant插件通过structure标签的配置读取项目源码和字节码
org.jacoco.ant.ReportTask类通过ant插件加载的执行数据和源码计算覆盖率生成报告

如果这时候希望聚合上报结果到sonar，则需要将sonar-project.properties中的报告路径配置为聚合报告的结果：

sonar.coverage.jacoco.xmlReportPaths=../target/coverage-report/coverage-report.xml