报告工具：ExtentReports

作者：瞿丹丹  浏览 1363 发布时间： 更新时间：

一、ExtentReports 概述

ExtentReports 是一款功能强大的测试报告生成工具，广泛应用于自动化测试领域，尤其在 Java 和 Python 生态中较为常用。它能够生成美观、详细且交互式的 HTML 测试报告，帮助测试人员和开发人员更直观地了解测试执行情况。

二、核心优势

1、直观的可视化呈现

内置多种图表（饼图、柱状图、趋势图等），直观展示测试用例的通过 / 失败 / 跳过等状态分布，以及执行时间、趋势变化等关键指标。

2、高度交互的报告体验

生成的 HTML 报告支持搜索、筛选、折叠 / 展开测试细节，可快速定位失败用例及原因，还能查看截图、日志等附加信息。

3、灵活的自定义能力

可自定义报告标题、Logo、主题（浅色 / 深色），支持添加测试类别、标签，以及通过 CSS/JS 调整样式，满足不同团队的报告规范。

4、多语言支持

主要支持 Java 和 Python 生态，提供简洁的 API 便于集成到各类测试框架中。

三、基本使用流程

1、 以 Java 为例

1.1、添加依赖

在 Maven 项目中引入相关依赖：

xml

com.aventstack extentreports 5.0.9 com.aventstack extent-spark-reporter 5.0.9
1.2、初始化报告

创建报告生成器并配置基础信息：

  1. java 运行
  3. // 指定报告路径
  5. ExtentSparkReporter sparkReporter = new ExtentSparkReporter("test-report.html");
  7. // 配置报告标题、主题等
  9. sparkReporter.config().setDocumentTitle("自动化测试报告");
  11. sparkReporter.config().setTheme(Theme.STANDARD);
  13. // 创建报告实例并关联生成器
  15. ExtentReports extent = new ExtentReports();
  17. extent.attachReporter(sparkReporter);
1.3、记录测试用例

通过 ExtentTest 记录测试步骤和结果：

  1. java 运行
  3. // 创建测试用例
  5. ExtentTest test = extent.createTest("登录功能测试", "验证用户登录流程");
  7. // 记录测试步骤
  9. test.log(Status.INFO, "输入用户名：testuser");
  11. test.log(Status.INFO, "输入密码：123456");
  13. test.log(Status.PASS, "登录成功，跳转至首页");
1.4、生成报告

执行 flush() 方法生成最终报告：

  1. java 运行
  3. extent.flush();

2、在Python 中的基本示例

Python 版本通常使用 pytest-extent-report 或 extentreports 库：

  1. python运行
  3. from extentreports import ExtentReports, ExtentTest, Status
  5. \# 初始化报告
  7. extent = ExtentReports()
  9. extent.attach\_reporter("extent-report.html")
  11. \# 创建测试用例
  13. test1 = extent.create\_test("登录测试", "验证正常登录")
  15. test1.log(Status.INFO, "输入用户名")
  17. test1.log(Status.PASS, "登录成功")
  19. test2 = extent.create\_test("购物车测试", "验证添加商品")
  21. test2.log(Status.INFO, "点击添加按钮")
  23. test2.log(Status.FAIL, "商品未添加成功")
  25. \# 生成报告
  27. extent.flush()

3、核心组件说明

  • ExtentReports：报告的主类，用于管理测试报告的生命周期。
  • ExtentSparkReporter（Java）/ 报告生成器（Python）：负责生成 HTML 报告，可配置报告的样式和元数据。
  • ExtentTest：代表一个测试用例，用于记录测试步骤、状态和附加信息（如截图）。
  • Status：枚举类，定义测试状态（PASS、FAIL、SKIP、INFO 等）。

四、适用场景

1、自动化测试结果展示

  • 最核心的应用场景，无论是 Web 自动化、移动端自动化还是 API 自动化，都能通过 ExtentReports 清晰呈现测试执行情况。
  • 尤其适合测试用例数量多、模块复杂的项目，帮助团队快速把握整体质量。

2、测试团队协作与汇报

  • 报告美观且信息结构化，便于测试人员向开发、产品等角色展示测试进度和问题，减少沟通成本。
  • 支持导出或在线分享，适合远程团队协作。

3、持续集成 / 持续部署（CI/CD）流程

  • 在 CI 流水线中，测试完成后自动生成 ExtentReports 报告，可作为质量门禁的依据（如通过率低于阈值则阻断部署）。
  • 结合历史报告的趋势图，可跟踪项目质量的长期变化。

4、问题排查与回归测试

  • 失败用例的详细日志和附件（截图等）可加速问题定位，回归测试时也能快速对比历史结果，验证问题是否解决。

5、大型项目的测试状态跟踪

  • 对于多模块、多版本的大型项目，可通过自定义标签和筛选功能，按模块、版本或测试类型（如冒烟测试、回归测试）分别统计，清晰跟踪各维度的测试进度。

五、ExtentReports支持的图表类型

1、饼图（Pie Chart）

最常用的图表类型，用于展示不同状态的测试用例占比，如通过（Pass）、失败（Fail）、跳过（Skip）、警告（Warning）等。能直观反映测试通过率和各类状态的分布情况，是报告首页的核心图表之一。

2、柱状图（Bar Chart）

用于对比不同测试套件或测试组的用例执行结果。可按状态（通过 / 失败等）分别展示各套件的用例数量，便于横向比较不同模块或批次的测试情况。

3、趋势图（Trend Chart）

展示多次测试执行的趋势变化，如通过率、总用例数、失败数等随时间的变化。需结合历史测试数据（通常通过配置报告持久化实现），适合跟踪测试质量的长期变化和项目质量趋势。

4、时间线图（Timeline Chart）

展示测试用例的执行时间分布，以时间轴形式呈现各用例的执行时长，帮助识别执行耗时较长的用例，为优化测试效率提供依据。

5、类别分布图（Category Distribution）

按自定义类别（如功能模块、优先级、测试类型等）展示用例的执行结果分布。需在测试代码中为用例添加类别标签，适合按业务维度分析测试覆盖情况和各模块的质量状态。

六、在ExtentReports中配置图表的样式

1、Java 中配置图表样式（以 ExtentSparkReporter 为例）

Java 版本的 ExtentReports 提供了丰富的 API 用于自定义图表，核心是通过 ExtentSparkReporter 的配置类 SparkReporterConfig 进行设置。

  1. java 运行
  3. import com.aventstack.extentreports.ExtentReports;
  5. import com.aventstack.extentreports.reporter.ExtentSparkReporter;
  7. import com.aventstack.extentreports.reporter.configuration.Theme;
  9. import com.aventstack.extentreports.reporter.configuration.ViewName;
  11. public class ExtentChartStyleConfig {
  13. public static void main(String\[\] args) {
  15. // 1. 创建报告生成器并指定路径
  17. ExtentSparkReporter sparkReporter = new ExtentSparkReporter("extent-report.html");
  19. // 2. 获取配置对象
  21. var config = sparkReporter.config();
  23. // 3. 配置整体主题（影响图表配色）
  25. config.setTheme(Theme.DARK); // 可选：Theme.STANDARD（默认浅色）/ Theme.DARK（深色）
  27. // 4. 自定义图表标题
  29. config.setChartTitle("测试结果统计");
  31. // 5. 控制图表显示（默认全显示，可按需隐藏）
  33. config.setViews(ViewName.DASHBOARD, ViewName.TESTS, ViewName.CATEGORIES);
  35. // 说明：ViewName.DASHBOARD 包含饼图/柱状图，ViewName.TRENDS 包含趋势图
  37. // 6. 配置图表尺寸（部分版本支持）
  39. config.setChartVisibilityOnOpen(true); // 打开报告时默认显示图表
  41. config.setDocumentTitle("自定义图表样式示例");
  43. // 7. 关联配置到报告实例
  45. ExtentReports extent = new ExtentReports();
  47. extent.attachReporter(sparkReporter);
  49. // ... 后续添加测试用例逻辑 ...
  51. extent.flush();
  53. }
  55. }

关键配置说明：

主题（Theme）：STANDARD（浅色背景，亮色图表）和 DARK（深色背景，深色图表）会直接影响图表的配色方案。

图表可见性：通过 setViews() 控制是否显示包含图表的面板（如仪表盘、趋势图面板）。

标题与元数据：setChartTitle() 可自定义图表的标题，便于区分不同报告的统计维度。

2、Python 中配置图表样式

Python 版本的 ExtentReports 配置相对简洁，主要通过初始化报告时的参数或修改 CSS 样式实现。

  1. python 运行
  3. from extentreports import ExtentReports
  5. \# 1. 初始化报告并配置基础样式
  7. extent = ExtentReports()
  9. reporter = extent.attach\_reporter("extent-report.html")
  11. \# 2. 配置主题（影响图表配色）
  13. reporter.config.theme = "dark" # 可选："standard"（默认）或 "dark"
  15. \# 3. 自定义图表标题
  17. reporter.config.chart\_title = "测试执行统计"
  19. \# 4. （进阶）通过自定义 CSS 调整图表细节
  21. \# 例如：修改饼图颜色（需了解报告生成的 HTML 结构）
  23. custom\_css = """
  25. <style>
  27. .chart-container .pie-chart .pass { fill: #4CAF50 !important; } /\* 自定义通过状态颜色 \*/
  29. .chart-container .pie-chart .fail { fill: #F44336 !important; } /\* 自定义失败状态颜色 \*/
  31. </style>
  33. """
  35. reporter.config.add\_custom\_css(custom\_css)
  37. \# ... 后续添加测试用例逻辑 ...
  39. extent.flush()

关键配置说明：

主题切换：通过 theme 参数控制整体配色，间接影响图表颜色。

自定义 CSS：对于更精细的样式调整（如修改特定状态的颜色、图表尺寸），可通过注入 CSS 实现（需熟悉报告的 HTML 结构，可通过浏览器开发者工具查看）。

3、通用配置技巧

  • 颜色定制：若默认颜色不符合需求，Java 可通过扩展 ExtentSparkReporter 的样式模板实现；Python 则可通过自定义 CSS 覆盖默认样式（如上述示例中的饼图颜色）。
  • 图表尺寸：部分版本支持通过配置调整图表大小（如 Java 中 setChartHeight()、setChartWidth()），若不支持可通过 CSS 强制设置（如 : 80% !important;）。
  • 图表类型控制：若不需要某些图表（如趋势图），可通过 setViews()（Java）或隐藏对应 DOM 元素（Python 自定义 CSS）来移除。

七、图表不显示的常见原因及解决方法

1. 检查基础配置是否正确

图表依赖报告生成器的正确配置，尤其是视图（Views）设置。

1.1、Java 中常见问题
未启用含图表的视图

图表通常嵌入在 DASHBOARD 或 TRENDS 视图中，若未配置会导致图表不显示。解决：显式指定要显示的视图：

  1. java 运行
  3. import com.aventstack.extentreports.reporter.configuration.ViewName;
  5. ExtentSparkReporter spark = new ExtentSparkReporter("report.html");
  7. // 确保包含图表所在的视图（DASHBOARD 包含饼图/柱状图，TRENDS 包含趋势图）
  9. spark.config().setViews(ViewName.DASHBOARD, ViewName.TESTS, ViewName.TRENDS);
主题配置冲突

某些版本中，主题（Theme）配置错误可能导致图表渲染异常。解决：尝试切换主题或使用默认主题：

  1. java 运行
  3. spark.config().setTheme(Theme.STANDARD); // 恢复默认浅色主题
1.2、Python 中常见问题
未正确初始化报告器

若报告器未正确附加到 ExtentReports 实例，图表会缺失。

解决：确保报告器初始化流程正确：

  1. python 运行
  3. from extentreports import ExtentReports
  5. extent = ExtentReports()
  7. \# 正确附加报告器
  9. reporter = extent.attach\_reporter("report.html")
  11. reporter.config.theme = "standard" # 避免主题配置错误

2. 检查依赖是否完整（Java 重点）

Java 版本的 ExtentReports 依赖特定库（如 extentreports 和 extent-spark-reporter），版本不匹配或缺失会导致图表无法生成。

2.1、依赖版本兼容问题

确保 extentreports 与 extent-spark-reporter 版本匹配（建议使用最新稳定版）。Maven 依赖示例（兼容版本）：

  1. xml
  3. <dependency>
  5. <groupId>com.aventstack</groupId>
  7. <artifactId>extentreports</artifactId>
  9. <version>5.0.9</version> <!-- 最新稳定版 -->
  11. </dependency>
  13. <dependency>
  15. <groupId>com.aventstack</groupId>
  17. <artifactId>extent-spark-reporter</artifactId>
  19. <version>5.0.9</version> <!-- 与 extentreports 版本一致 -->
  21. </dependency>
2.2、缺失图表渲染依赖

图表依赖 batik 等库处理 SVG 渲染，若缺失会导致图表空白。解决：添加相关依赖（Maven）：

  1. xml
  3. <dependency>
  5. <groupId>org.apache.xmlgraphics</groupId>
  7. <artifactId>batik-transcoder</artifactId>
  9. <version>1.17</version>
  11. </dependency>

3. 检查报告文件路径与权限

3.1、路径包含特殊字符

若报告路径含中文、空格或特殊符号，可能导致图表资源（如 SVG）加载失败。解决：使用纯英文路径，例如 ./reports/test-result.html。

3.2、文件权限不足

若程序无写入权限，图表资源可能无法生成。解决：确保报告输出目录可写（如修改文件夹权限为 755）。

4. 浏览器或缓存问题

4.1、浏览器兼容性

部分旧浏览器（如 IE）不支持 ExtentReports 的图表 SVG 渲染。解决：使用现代浏览器（Chrome、Firefox、Edge）打开报告。

4.2、缓存导致的显示异常

浏览器缓存可能导致修改后的报告未更新。解决：清除浏览器缓存，或使用「无痕模式」打开报告。

5. 高级排查：查看报告源码与控制台

5.1、检查 HTML 源码

用编辑器打开生成的 HTML 报告，搜索 chart 或 svg 关键词，确认是否存在图表相关代码。若完全缺失，说明生成过程出错。

5.2、浏览器控制台报错

在浏览器中打开报告，按 F12 打开开发者工具，查看「控制台（Console）」是否有报错（如资源加载失败、JS 错误），根据错误信息定位问题（如缺失 CSS/JS 文件）。

6. 尝试简化配置

若以上方法无效，可先使用最小化配置生成报告，排除复杂配置的干扰：

6.1、Java 最小化配置示例
  1. java 运行
  3. ExtentReports extent = new ExtentReports();
  5. ExtentSparkReporter spark = new ExtentSparkReporter("simple-report.html");
  7. extent.attachReporter(spark);
  9. // 添加一个简单测试用例
  11. extent.createTest("测试图表显示").pass("用例通过");
  13. extent.flush();
6.2、Python 最小化配置示例
  1. python 运行
  3. from extentreports import ExtentReports
  5. extent = ExtentReports()
  7. extent.attach\_reporter("simple-report.html")
  9. extent.create\_test("测试图表显示").pass("用例通过")
  11. extent.flush()

若简化配置后图表正常显示，则说明问题出在之前的自定义配置（如主题、视图、CSS 等），可逐步还原配置排查具体原因。