JaCoCo官方教程

翻译自官方文档

1 概念

1.1 任务 - Mission

JaCoCo应该为基于Java VM的环境中的代码覆盖率分析提供标准技术。重点是提供一个轻量级，灵活且文档齐全的库，以与各种构建和开发工具集成。

有几种适用于Java的开源覆盖技术。在实现Eclipse插件EclEmma时，观察到它们都不是真正为集成而设计的。它们中的大多数特别适合特定工具（Ant任务，命令行，IDE插件），并且不提供允许在不同上下文中嵌入的文档化API。 EMMA和Cobertura是最好的和广泛使用的两个开源工具。这两个工具都不再由原始作者积极维护，并且不支持当前的Java版本。由于缺乏回归测试，因此很难进行维护和添加功能。

因此，我们启动了JaCoCo项目，以为基于Java VM的环境中的代码覆盖率分析提供一种新的标准技术。重点是提供一个轻量级，灵活且文档齐全的库，以与各种构建和开发工具集成。提供了Ant任务，Maven插件和EclEmma Eclipse插件作为参考使用方案。同样，许多其他工具供应商和开源项目也将JaCoCo集成到了他们的工具中。

产品定义

特征

• 指令（C0），分支（C1），行，方法，类型和圈复杂度的覆盖率分析
• 基于Java字节码，因此无需源文件也可以工作
• 通过基于 Java-agent 的即时检测进行简单集成。其他集成方案（例如自定义类加载器）也可以通过API来实现
• 与框架无关的：与基于Java VM的应用程序（如纯Java程序，OSGi框架，Web容器或EJB服务器）平滑集成
• 与所有已发布的Java类文件版本兼容
• 支持不同的JVM语言
• 几种报告格式（HTML，XML，CSV）
• 远程协议和JMX控制可在任何时间点从coverage agent请求执行数据dump
• Ant任务，用于收集和管理执行数据并创建结构化的覆盖率报告
• Maven插件可收集覆盖率信息并在Maven构建中创建报告

非功能特性

• 简单的用法以及与现有构建脚本和工具的集成
• 良好的性能和最小的运行时开销，尤其是对于大型项目
• 轻量级实现，对外部库和系统资源的依赖性最小
• 全面的文档
• 完整记录的API（JavaDoc）以及与其他工具集成的示例
• 基于JUnit测试用例的功能全面的回归测试

1.2 整合矩阵 - Integration Matrix

目前，JaCoCo已与以下产品和技术集成在一起。

JaCoCo 提供的集成

Technology	Documentation	Remarks
Java API	JaCoCo JavaDoc
Java Agent	JaCoCo Manual
Command Line Tools	JaCoCo Manual	Since version 0.8.0
Apache Ant	JaCoCo Manual
Apache Maven	JaCoCo Manual	Since version 0.5.3
Eclipse	EclEmma Project	Since version 2.0

第三方集成

与往常一样，上面列出的所有商标均为其各自所有者的财产。

1.3 覆盖率计数器 - Coverage Counters

JaCoCo使用一组不同的计数器来计算覆盖率指标。所有这些计数器都从Java类文件中包含的信息派生而来，这些信息基本上是Java字节码指令以及调试信息（可选地嵌入在类文件中）。即使没有可用的源代码，这种方法也可以对应用程序进行高效的即时检测和分析(instrumentation and analysis)。在大多数情况下，可以将收集到的信息映射回源代码，并可视化到行级粒度。无论如何，这种方法存在局限性。必须使用调试信息编译类文件，以计算行级覆盖率并提供源高亮显示。并非所有Java语言构造都可以直接编译为相应的字节码。在这种情况下，Java编译器会创建所谓的合成代码，有时会导致意外的代码覆盖率结果。

指令 - Instructions（C0覆盖率）

JaCoCo计数的最小单位是单个Java字节代码指令。指令覆盖率提供有关已执行或遗漏(executed or missed)的代码量的信息。该度量完全独立于源格式，并且即使在类文件中没有调试信息的情况下也始终可用。

分支 - Branches（C1覆盖率）

JaCoCo还为所有if和switch语句计算分支覆盖率。此度量标准统计方法中此类分支的总数，并确定已执行或遗漏的分支的数量。分支覆盖始终可用，即使类文件中没有调试信息也是如此。请注意，在此计数器定义的上下文中，异常处理不视为分支。

如果尚未使用调试信息编译类文件，则可以将决策点映射到源代码行并高亮:

• 无覆盖范围：该行没有分支执行（红色菱形）
• 部分覆盖：仅执行了该行中的一部分分支（黄色菱形）
• 全面覆盖：该行中的所有分支均已执行（绿色菱形）

圈复杂度 - Cyclomatic Complexity

JaCoCo 还为每种非抽象方法计算圈复杂度，并汇总了类，包和组的复杂度。根据 McCabe1996 的定义，圈复杂度是可以（线性）组合生成一种方法的所有可能路径的最小路径数。因此，复杂度值可以作为完全覆盖某个软件的单元测试用例数量的指示。即使类文件中没有调试信息，也总是可以计算复杂度数字。

圈复杂度v（G）的形式定义基于方法的控制流图作为有向图的表示：

v（G）= E- N 2

其中，E是边数，N是节点数。 JaCoCo根据分支数（B）和决策点数（D）使用以下等效方程式计算方法的圈复杂度：

v（G）= B - D + 1

根据每个分支的覆盖状态，JaCoCo还可以计算每种方法的覆盖和遗漏复杂度。缺少的复杂性再次表明完全覆盖模块的测试用例的数量。请注意，由于JaCoCo不考虑异常处理，因为分支try / catch块也不会增加复杂性。

行

对于已使用调试信息编译的所有类文件，可以计算各个行的覆盖率信息。当已执行至少一个分配给该源代码行的指令时，该源代码行被视为已执行。

由于单行通常会编译为多字节代码指令，因此，源代码高亮显示每行包含源代码的三种不同状态：

• 无覆盖：该行中没有指令被执行（红色背景）
• 部分覆盖：仅执行了该行中的一部分指令（黄色背景）
• 全面覆盖：该行中的所有指令均已执行（绿色背景）

根据源格式，源代码的一行可能会引用多个方法或多个类。因此，不能简单地添加方法的行数以获得包含类的总数。单个源文件中的多个类的行也是如此。 JaCoCo根据覆盖的实际源代码行计算类和源文件的代码行覆盖率。

方法
每个非抽象方法都包含至少一条指令。当至少一个指令已被执行时，一种方法被视为已执行。由于JaCoCo在字节码级别上工作，因此构造函数和静态初始化程序也被视为方法。这些方法中的某些方法在Java源代码中可能没有直接的对应关系，例如隐式生成的常量的默认构造函数或初始化器。

类

当至少一个类的方法已执行时，该类被视为已执行。 请注意，JaCoCo将构造函数以及静态初始化程序视为方法。 由于Java接口类型可能包含静态初始化器，因此此类接口也被视为可执行类。