Ohhnews

分类导航

$ cd ..
foojay原文

如何在 Java 项目中自定义 JaCoCo 报告样式

#jacoco#java#代码覆盖率#maven#css

目录

JaCoCo 是 Java 项目的首选代码覆盖率工具。它与 Maven 无缝集成，生成详细的 HTML 报告，并且开箱即用。但老实说——默认报告看起来像是 2008 年设计的，因为确实是。

如果您将覆盖率报告作为项目文档的一部分发布（例如在 GitHub Pages 上），您可能希望它们与您网站的外观和风格相匹配。好消息是：这完全可行。坏消息是：JaCoCo 没有提供任何内置的 CSS 自定义支持。

在这篇文章中，我将向您介绍我们如何在 Copilot SDK for Java 项目中为 JaCoCo 报告设置主题，以匹配我们的 Maven 站点设计——以及您如何做到这一点。

问题

JaCoCo 会生成独立的 HTML 报告，这些报告通过 <link> 标签引用它们自己的 jacoco-resources/report.css。没有插件配置，没有皮肤系统，也没有注入您自己 CSS 的钩子。生成的 HTML 如下所示：

$ markup
<link rel="stylesheet" href="jacoco-resources/report.css" type="text/css"/>

那个 report.css 控制着一切：表格样式、源代码高亮、覆盖率条颜色、面包屑导航、排版。如果您想改变外观，需要在 JaCoCo 生成它之后替换该文件。

这是默认 CSS 的样子：

[LOADING...]

策略：CSS 覆盖

方法很简单：让 JaCoCo 使用默认 CSS 生成报告，然后用您的自定义版本覆盖 report.css。我们在两个层面上执行此操作：

  1. 在 mvn site 期间 —— Maven 资源插件的执行会在 JaCoCo 完成后复制我们的 CSS。
  2. 在 CI 部署期间 —— 一个工作流步骤会在所有版本化文档目录中覆盖 CSS。

步骤 1：创建自定义 report.css

首先获取 JaCoCo 的默认 report.css。您可以在运行带有覆盖率数据的 mvn site 后在 target/site/jacoco/jacoco-resources/report.css 中找到它，或者在 JaCoCo 源代码中找到。

将您的自定义版本放置在：

src/site/jacoco-resources/report.css

这是我们的样式 —— 一个带有圆角卡片、GitHub 风格颜色和系统字体堆栈的浅色主题：

$ style
/* ===== Custom JaCoCo Report Theme ===== */

body, td {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  font-size: 10pt;
  color: #24292f;
}

body {
  background: #f6f8fa;
  margin: 0;
  padding: 20px;
}

/* Breadcrumb navigation */
.breadcrumb {
  background: #fff;
  border: 1px solid #d0d7de;
  border-radius: 10px;
  padding: 10px 16px;
  margin-bottom: 20px;
}

/* Coverage table */
table.coverage {
  border-collapse: separate;
  border-spacing: 0;
  border: 1px solid #d0d7de;
  border-radius: 10px;
  overflow: hidden;
  width: 100%;
  background: #fff;
}

table.coverage thead {
  background: #f6f8fa;
}

table.coverage thead td {
  padding: 10px 14px;
  border-bottom: 2px solid #d0d7de;
  font-weight: 700;
}

table.coverage tbody td {
  padding: 8px 10px;
  border-bottom: 1px solid #eaeef2;
}

table.coverage tbody tr:hover {
  background: rgba(102, 126, 234, 0.04) !important;
}

/* Source code coverage highlights */
pre.source span.fc  { background-color: #dafbe1; }  /* fully covered - green */
pre.source span.nc  { background-color: #ffeef0; }  /* not covered - red */
pre.source span.pc  { background-color: #fff8c5; }  /* partially covered - yellow */

您可以在我们的仓库中查看完整文件：src/site/jacoco-resources/report.css。

重要提示： 您必须在自定义 CSS 中包含元素图标类（.el_package、.el_class、.el_method 等）和可排序标题类（.sortable、.up、.down）—— 它们引用 JaCoCo 与报告一起生成的 GIF 图像。省略它们会破坏导航图标和列排序。

步骤 2：在 Maven 构建期间覆盖 CSS

在 pom.xml 中的 maven-resources-plugin 配置中添加一个 copy-resources 执行。关键是使用 phase: site，以便它在 JaCoCo 报告插件生成默认 CSS 之后运行：

$ xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <id>overlay-jacoco-css</id>
            <phase>site</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>
                    ${project.reporting.outputDirectory}/jacoco/jacoco-resources
                </outputDirectory>
                <resources>
                    <resource>
                        <directory>src/site/jacoco-resources</directory>
                        <filtering>false</filtering>
                    </resource>
                </resources>
                <overwrite>true</overwrite>
            </configuration>
        </execution>
    </executions>
</plugin>

请参见上下文：pom.xml (第 371--387 行)。

现在，当您运行 mvn site 时，自定义 CSS 会在报告生成后立即替换 JaCoCo 的默认 CSS。

步骤 3：处理 CI 部署（可选）

如果您部署版本化文档（就像我们一样 —— snapshot/、latest/、1.0.8/ 等），您需要为所有版本目录覆盖 CSS，而不仅仅是 Maven 刚刚构建的那个。

在我们的 GitHub Actions 部署工作流中，我们在所有版本构建完成后添加一个步骤：

$ bash
- name: Overlay custom JaCoCo CSS
  run: |
    cd site
    for dir in */jacoco/jacoco-resources; do
      if [ -d "$dir" ]; then
        cp ../src/site/jacoco-resources/report.css "$dir/report.css"
        echo "Overlaid JaCoCo CSS in $dir"
      fi
    done

查看完整工作流：deploy-site.yml。

注意：输出目录路径

这是困扰我们的一个陷阱。在典型的 Maven 项目中，JaCoCo 有两个插件配置，它们输出到不同的目录：

上下文插件部分默认输出路径
mvn verify<plugin> (goal: report, phase: verify`)可配置（我们使用 jacoco-coverage/）
mvn site<reporting> (goal: report`)jacoco/（默认）

部署文档时，通常运行 mvn site，而不是 mvn verify。因此，报告会落在 jacoco/ 中，而不是您的构建插件配置写入的位置。您的 CSS 覆盖必须针对报告插件使用的相同路径。 如果它们不匹配，您最终会在空目录中得到自定义 CSS，而在实际报告上得到默认 CSS。

结果

相同的数据，完全不同的体验。自定义主题拥有干净的白色卡片、圆角边框、GitHub 风格的覆盖率颜色和现代排版。

[LOADING...]

您可以在我们的文档站点上查看实时结果：Copilot SDK for Java --- JaCoCo Report。

快速入门清单

  1. ☐ 运行 mvn clean verify site 以生成带有默认 CSS 的 JaCoCo 报告。
  2. ☐ 将 target/site/jacoco/jacoco-resources/report.css 复制到 src/site/jacoco-resources/report.css。
  3. ☐ 自定义 CSS 以匹配您站点的设计。
  4. ☐ 保留所有 .el_* 图标类和 .sortable/.up/.down 排序类 —— 它们引用 JaCoCo 的 GIF 资源。
  5. ☐ 在您的 pom.xml 中向 maven-resources-plugin 添加 overlay-jacoco-css 执行。
  6. ☐ 如果使用版本化文档部署到 GitHub Pages，请添加工作流覆盖步骤。
  7. ☐ 再次运行 mvn clean verify site 并打开 target/site/jacoco/index.html 进行验证。

完整示例

完整的实现位于 Copilot SDK for Java 仓库中：

由 Bruno Borges 和 GitHub Copilot 用 ❤️ 构建。