Gradle 2.0 用户指南翻译——第三十四章. JaCoCo 插件

本文禁止w3cschool转载！

翻译项目请关注Github上的地址：https://github.com/msdx/gradledoc 。

本文翻译所在分支：https://github.com/msdx/gradledoc/tree/2.0 。
更好的阅读体验请访问：http://gradledoc.githang.com/2.0/userguide/userguide.html 。
另外，Android 手机用户可通过我写的一个程序浏览文档，带缓存功能的，目前0.6.1版本兼容 Android 4.0.3以上系统，项目地址如下：
https://github.com/msdx/gradle-doc-apk

翻译不易，本文采用 CC BY-NC-SA 4.0 许可协议，转载请务必署名及注明本文在优快云博客上的出处：

https://blog.youkuaiyun.com/maosidiaoxian/article/details/86672038

关于我对Gradle的翻译，以Github上的项目及http://gradledoc.githang.com 上的文档为准。如发现翻译有误的地方，将首先在以上两个地方更新。因时间精力问题，博客中发表的译文基本不会同步修改。

 

第三十四章. JaCoCo 插件

Chapter 34. The JaCoCo Plugin

JaCoCo 目前是一个试验性插件。注意，在以后的 Gradle 版本中，其 DSL 和其他配置可能会有变化。 
The JaCoCo plugin is currently incubating. Please be aware that the DSL and other configuration may change in later Gradle versions.

JaCoCo 插件通过集成 JaCoCo 为 Java 代码提供了代码覆盖率指标。 
The JaCoCo plugin provides code coverage metrics for Java code via integration with JaCoCo.

34.1. 入门

34.1. Getting Started

首先，请将 JaCoCo 插件应用于你想要计算代码覆盖率的项目中。
To get started, apply the JaCoCo plugin to the project you want to calculate code coverage for.

示例 34.1. 应用 JaCoCo 插件 - Example 34.1. Applying the JaCoCo plugin

build.gradle

apply plugin: "jacoco"

如果你的项目同时也应用了 Java 插件，那么会创建一个名为 jacocoTestReport 的新任务，并且这个新任务依赖于 test 任务。该报告可以在 $buildDir/report/jacoco/test 中看到。默认情况下，会生成一个 HTML 报告。 
If the Java plugin is also applied to your project, a new task named jacocoTestReport is created that depends on the test task. The report is available at $buildDir/reports/jacoco/test. By default, a HTML report is generated.

34.2. 配置 JaCoCo 插件

34.2. Configuring the JaCoCo Plugin

JaCoCo 插件添加一个类型为 JacocoPluginExtension，名为jacoco 的 project 扩展，这个扩展允许在你的构建中配置 JaCoCo 所使用的默认值。 
The JaCoCo plugin adds a project extension named jacoco of type JacocoPluginExtension, which allows configuring defaults for JaCoCo usage in your build.

示例 34.2. 配置 JaCoCo 插件设置 - Example 34.2. Configuring JaCoCo plugin settings

build.gradle

jacoco {
    toolVersion = "0.6.2.201302030002"
    reportsDir = file("$buildDir/customJacocoReportDir")
}

表 34.1. JaCoCo 属性的 Gradle 默认值 - Table 34.1. Gradle defaults for JaCoCo properties

属性 Property	Gradle 默认值 Gradle default
reportsDir	"$buildDir/reports/jacoco"

34.3. JaCoCo 报告配置

34.3. JaCoCo Report configuration

JacocoReport 任务可以生成不同格式的代码覆盖率报告。它实现了标准的 Gradle 类型 Reporting，并向外暴露了一个 JacocoReportsContainer 类型的报告容器。 
The JacocoReport task can be used to generate code coverage reports in different formats. It implements the standard Gradle type Reporting and exposes a report container of type JacocoReportsContainer.

示例 34.3. 配置测试任务 - Example 34.3. Configuring test task

build.gradle

jacocoTestReport {
    reports {
        xml.enabled false
        csv.enabled false
        html.destination "${buildDir}/jacocoHtml"
    }
}

34.4. JaCoCo 的特定任务配置

34.4. JaCoCo specific task configuration

JaCoCo 插件添加了一个 JacocoTaskExtension 扩展到所有 Test 类型的任务中。这一扩展允许配置测试任务中的一些特定的 JaCoCo 属性。 
The JaCoCo plugin adds a JacocoTaskExtension extension to all tasks of type Test. This extension allows the configuration of the JaCoCo specific properties of the test task.

示例 34.3. 配置测试任务 - Example 34.4. Configuring test task

build.gradle

test {
    jacoco {
        append = false
        destinationFile = file("$buildDir/jacoco/jacocoTest.exec")
        classDumpFile = file("$buildDir/jacoco/classpathdumps")
    }
}

表 34.2. JaCoCo 任务扩展的默认值 - Table 34.2. Default values of the JaCoCo Task extension

属性 Property	Gradle 默认值 Gradle default
enabled	true
destPath	$buildDir/jacoco
append	true
includes	[]
excludes	[]
excludeClassLoaders	[]
sessionId	auto-generated
dumpOnExit	true
output	Output.FILE
address	-
port	-
classDumpPath	-
jmx	false

虽然所有 Test 类型的任务会在应用 java 插件时自动增强以提供覆盖率信息，但是任何实现了 JavaForkOptions 的任务都可以通过 JaCoCo 插件得到增强。也就是说，任何 fork Java 进程的任务都可生成覆盖信息。 
While all tasks of type Test are automatically enhanced to provide coverage information when the java plugin has been applied, any task that implements JavaForkOptions can be enhanced by the JaCoCo plugin. That is, any task that forks Java processes can be used to generate coverage information.

例如，你可以配置你的构建使用 application 插件来生成代码覆盖率。 
For example you can configure your build to generate code coverage using the application plugin.

示例 34.5. 使用 application 插件来生成代码覆盖率数据 - Example 34.5. Using application plugin to generate code coverage data

build.gradle

apply plugin: "application"
apply plugin: "jacoco"

mainClassName = "org.gradle.MyMain"

jacoco {
    applyTo run
}

task applicationCodeCoverageReport(type:JacocoReport){
    executionData run
    sourceSets sourceSets.main
}

注： 此示例中的代码可以在 Gradle 的二进制分发包及源代码分发包中的 samples/testing/jacoco/application 中找到。
Note: The code for this example can be found at samples/testing/jacoco/application which is in both the binary and source distributions of Gradle.

示例 34.6. 由 applicationCodeCoverageReport 生成的覆盖率报告 - Example 34.6. Coverage reports generated by applicationCodeCoverageReport

构建布局
Build layout

application/
  build/
    jacoco/
      run.exec
    reports/jacoco/applicationCodeCoverageReport/html/
      index.html

34.5. 任务

34.5. Tasks

对于同时也应用了 Java 插件的项目，JaCoCo 插件会自动添加以下任务：
For projects that also apply the Java Plugin, The JaCoCo plugin automatically adds the following tasks:

表 34.3. JaCoCo 插件——任务 - Table 34.3. JaCoCo plugin - tasks

任务名称 Task name	依赖于 Depends on	类型 Type	描述 Description
jacocoTestReport	-	JacocoReport	为测试任务生成代码覆盖率报告。 Generates code coverage report for the test task.

34.6. 依赖管理

34.6. Dependency management

JaCoCo 插件添加了以下依赖配置：
The JaCoCo plugin adds the following dependency configurations:

表34.4. JaCoCo 插件——依赖配置 - Table 34.4. JaCoCo plugin - dependency configurations

名称 Name	意义 Meaning
jacocoAnt	用于运行 JacocoReport 和 JacocoMerge 任务的 JaCoCo Ant 库。  The JaCoCo Ant library used for running the JacocoReport and JacocoMerge tasks.
jacocoAgent	用于检测位于 test 下的代码的 JaCoCo 客户端库。 The JaCoCo agent library used for instrumenting the code under test.