Jenkins GSoC : Code Coverage API plugin 一个新的代码覆盖率

说明：由于微信不允许外部链接，请点击文末地址，访问文中链接。

概要

Code Coverage API plugin 是 Jenkins 在 GSoC 2018 中的一个子项目。GSoC 是一个由谷歌举办的，帮助在校学生进入开源社区，为开源组织贡献代码的活动。

在这个项目中，我的 mentor 是 Steven Christou, Supun Wanniarachchi, Jeff Pearce 和 Oleg Nenashev。

目前在Jenkins中，有很多插件都实现了代码覆盖率工具的接入，例如 Cobertura Plugin, Jacoco Plugin, Clover Plugin…但是这些插件的配置项，结果页展示的图表和显示的内容都是类似的。

因此，相对于现在的为每一个代码覆盖率工具都从头编写一个新的插件，我们能提供一个 API 插件将会大大减少开发者的工作量。这个 API 插件将处理那些最重复的工作，将其封装成不同的抽象层，并提供易于使用的 API 接口让其它插件去实现。

支持的代码覆盖率工具

内置
- JaCoCo
其它实现了 Code Coverage API plugin 的插件
- Cobertura (Cobertura Plugin)
- llvm-cov (llvm-cov Plugin)

Features

现代化的图表
代码覆盖率变化趋势图
支持源代码浏览
支持 Pipeline 和 Parallel Pipeline
支持 Report combining
提供 REST API
灵活的 Failed Conditions

现代化的图表

在概要表中我们可以看到当前位置的代码覆盖率概况。

在子概要表中，看到每一个子项的代码覆盖率情况。同时，使用右上角的 range handler 可以筛选出我们想要看到的项来减小表的大小。通过点击节点的名字可以进入子项的详情页，来看到更多的关于子项代码覆盖率的信息。

代码覆盖率变化趋势图

我们也支持代码覆盖率趋势图，来显示 Build 之间的代码覆盖率变化趋势。

源代码浏览

通过设置 Source File Storing Level 为 save last build source files(将会在当前和上一次Build的结果页中显示源码) 或者 save all build source files (在所有Build的结果页中显示源码) 来启用源代码浏览。

之后我们就可以在 File 元素的节点中看到源代码以及与之相关联的代码覆盖率信息。

Pipeline 和 Parallel Pipeline

API 插件提供 Pipeline 和 Parallel Pipeline 的支持，你可以在不同的 Branch 中调用插件:

node {    parallel firstBranch: {        publishCoverage adapters: [jacocoAdapter('target/site/jacoco/jacoco.xml')]}, secondBranch: {        publishCoverage adapters: [jacocoAdapter('jacoco.xml')]    }}

Reports Combining

通过给 publishCoverage 设置 tag，把含有相同 tag 的报告结合为一个报告。

node {    parallel firstBranch: {        publishCoverage adapters: [jacocoAdapter('target/site/jacoco/jacoco.xml')], tag: ‘t’}, secondBranch: {        publishCoverage adapters: [jacocoAdapter('jacoco.xml')], tag: ‘t’    }}

REST API

我们提供 REST API 供其它应用获取覆盖率信息。

覆盖率: …/{buildNumber}/coverage/…/result/api/{json|xml}
覆盖率变化: …/{buildNumber}/coverage/…/trend/api/{json|xml}
上一次Build的覆盖率: …/{buildNumber}/coverage/…/last/result/api/{json|xml}
上一次Build的覆盖率变化: …/{buildNumber}/coverage/…/last/trend/api/{json|xml}

灵活的 Failed Conditions

我们可以在 Global 和 Adapter 级别为不同的元素设置失败条件来控制 Build 的结果。

假如代码覆盖率符合失败的条件，插件将会使当前的 Build 失败。

其他功能

我们也支持其它一些像是自动检测报告，筛选覆盖率这样的功能，在插件的文档中可以找到更多的信息。

架构

插件在运行过程中主要会做下面几个事情:

根据用户的配置找到代码覆盖率报告文件
使用 Adapter 将报告文件转化为统一的标准格式
解析标准格式的报告文件并并合并它们
显示解析后的结果

所以，我们可以简单编写一个 Adapter 来实现一个新的代码覆盖率工具。这个 Adapter 只需要做一件事，将其它格式的代码覆盖率报告转化为我们插件的标准格式。Adapter的实现方式基于 ExtensionPoint，所以我们可以将 adapter 的实现分离到不同的插件中，插件将会自动发现它们。同时，为了简化转化的过程，我们也提供了一系列的抽象层。

The below diagram show the architecture of Code Coverage API plugin

实现一个新的代码覆盖率插件

我们通过实现CoverageReportAdapter这个 extension point 来实现一个新的插件。通过使用我们插件提供的抽象层，我们可以像下面这样的简单来实现 JaCoCo:

public final class JacocoReportAdapter extends JavaXMLCoverageReportAdapter {    @DataBoundConstructor    public JacocoReportAdapter(String path) {        super(path);    }    /**     * {@inheritDoc}     */    @Override    public String getXSL() {        return "jacoco-to-standard.xsl";    }    /**     * {@inheritDoc}     */    @Override    public String getXSD() {        return null;    }    @Symbol("jacoco")    @Extension    public static final class JacocoReportAdapterDescriptor extends JavaCoverageReportAdapterDescriptor {        public JacocoReportAdapterDescriptor() {            super(JacocoReportAdapter.class);        }        @Nonnull        @Override        public String getDisplayName() {            return Messages.JacocoReportAdapter_displayName();        }    }}

在这里我们只做了两件事，实现了为 Java XML 报告编写的抽象层，提供了一个将 JaCoCo 报告转化为我们标准格式的 XSL 文件。

假如你想要实现一个我们没有提供抽象层的代码覆盖率工具，你还需要注册 CoverageElement 并实现一个简单的 Parser。可参考 llvm-cov Plugin，更多的信息参见插件的 GitHub wiki page。

附文中链接： Code Coverage API plugin：https://jenkins.io/projects/gsoc/ Steven Christou：https://github.com/christ66 Supun Wanniarachchi：https://github.com/Supun94 Jeff Pearce：https://github.com/jeffpearce Oleg Nenashev：https://github.com/oleg-nenashev Cobertura Plugin：https://github.com/jenkinsci/cobertura-plugin llvm-cov Plugin：https://github.com/jenkinsci/llvm-cov-plugin repo：https://github.com/jenkinsci/code-coverage-api-plugin

概要