但凡用 Cucumber 跑过 BDD 测试的人应该都有过这样的困惑跑完一条mvn test控制台输出一大屏 step 状态绿的花的都有但要把这份结果交给产品、开发或者领导你发现自己还得重新整理一份文档。Cucumber 的测试报告问题远不止“没有报告”这么简单。Gherkin 场景里写清楚了业务闭环执行结果却散落在终端日志和临时文件里没人愿意对着截图讲一整天。我自己的实践是从 Cucumber 的 JSON 输出开始逐步补上 HTML 可视化、数据统计和 CI 归档。再和 jmeter 5.6.3 生成的性能报告放在同一个测试报告体系里才算真正解决了“功能测试通过性能到底行不行”的追问。这篇文章就围绕这套 Cucumber 测试报告方案展开尽量把关键步骤和踩坑细节都写透。1. 为什么 Cucumber 需要一份“正经”测试报告1.1 Gherkin 文件不等于测试报告很多人有个误解认为项目里有.feature文件跑完测试就算有测试报告了。实际上 Gherkin 文件描述的是业务行为是测试的“输入”而不是测试结果的“输出”。一条场景Given 用户已登录 / When 用户点击下单 / Then 生成订单如果没有执行结果它就只是一份需求描述文档只有把这些步骤的状态、耗时、报错信息、执行时间点汇总成结构化数据才能叫测试报告。控制台日志更不算。控制台能告诉你“5 failed, 12 passed”但你没法一眼看出失败的是哪条业务链路更没法追溯到是哪一步、哪一行断言出了问题。尤其是项目大一点的时候feature 文件上百个场景上千条靠人眼去翻日志找失败原因效率低到没法接受。所以一份正经的 Cucumber 测试报告需要满足三个基本要求一是把每个场景的执行状态结构化二是能把失败信息、步骤耗时、错误堆栈关联起来三是能够保存下来做趋势分析和回归对比。做不到这三点报告就只是测试过程的一次性截图没有沉淀价值。1.2 谁在看报告谁在用报告设计报告体系之前先搞清楚阅读对象。测试人员看报告是想快速定位失败原因找到具体 step、具体断言、具体错误堆栈。开发人员看报告是想判断这个失败是不是自己改动引起的所以场景名称、feature 归属、失败重跑次数这些信息很重要。业务人员和团队负责人看报告不会关注某一行代码他们需要的是场景通过率、失败模块分布、以及一段时间内的趋势变化。这几种需求指向同一个结论Cucumber 测试报告必须是分层的。给机器读的、给测试工程师做深度定位的、给管理层做决策的应该是不同形式。只做一个 HTML 文件满足不了全部场景这也是为什么我在后面的方案里会把报告拆成三层来设计。2. 三层报告模型Cucumber 测试报告的核心骨架2.1 第一层实时控制台输出第一层是跑测过程中最直接的控制台反馈Cucumber 的pretty插件就是干这个的。执行时每个 step 前面会带颜色标识绿色表示通过红色表示失败黄色表示跳过。测试人员本地调试、快速判断当前代码是否破坏已有功能时控制台输出反而是最方便的。但这里有个容易忽略的问题如果你的团队用 CI 跑测试控制台输出会被重定向到构建日志文件ANSI 颜色码和 Unicode 符号处理不好会出现乱码。所以控制台层不追求美观追求的是信息完整。至少每一条 step 的状态、场景名、失败摘要都应在日志里能看到。最好再打开message插件把执行事件流完整记录下来方便后续排查。2.2 第二层HTML 可视化报告第二层给人类阅读通常是 HTML 页面展示功能场景的分组、通过失败状态、执行耗时、失败信息和附件截图。市面上的可选方案不少cucumber-html-reporter、Allure、ReportPortal 都可以做。我自己更倾向于 cucumber-html-reporter它基于 Cucumber 官方 JSON 输出做二次渲染安装轻量配置简单不需要额外起服务直接生成静态 HTML 文件就能共享给团队。Allure 功能更强有历史趋势和 test case 管理但要在 CI 里装 CLI还要处理 results 目录和 report 目录的分离对小型团队来说成本偏高。ReportPortal 则更像一个质量平台适合多个项目统一管理单项目用起来有点像高射炮打蚊子。做这块时我建议把报告生成逻辑独立成一个小工具脚本而不是每次手动点击。后面 Jenkins 里跑批量的 Cucumber jmeter 5.6.3 任务时只要调用同一个脚本自动产出 HTML。2.3 第三层JSON / Messages 数据存档第三层是最容易被忽视但长期价值最高的一层机器可读的结构化数据。Cucumber 官方支持输出json和message两种格式前者比较传统每个 feature 场景、步骤、结果都有后者是 ndjson 格式记录完整的测试事件流包括测试计划、步骤开始结束、钩子执行等。这层数据主要不是给人直接看的而是给脚本和分析工具用的。通过解析 JSON可以自动生成趋势报表、统计失败类型、计算执行时长通过解析 messages可以还原整个测试执行过程排查耗时异常和重试问题。我一般会把这些文件按日期归档到reports/archive/2025-06/目录下形成基础数据仓库后续做质量度量都不用重新跑测试。三层报告模型里控制台、HTML、JSON 各有分工缺一不可。HTML 做展示JSON 做数据源控制台做实时调试这样一套体系才能支撑起可持续的测试质量管理。3. 实操从零搭一套可用的 Cucumber 测试报告3.1 环境准备与依赖下面这套配置基于 Java 17 Maven JUnit 5 Cucumber 7.x是目前 Cucumber JVM 生态里最常见的技术栈。在pom.xml里需要加上 cucumber-java、cucumber-junit-platform-engine以及 junit-platform-suite 作为测试入口dependencies dependency groupIdio.cucumber/groupId artifactIdcucumber-java/artifactId version7.18.1/version /dependency dependency groupIdio.cucumber/groupId artifactIdcucumber-junit-platform-engine/artifactId version7.18.1/version scopetest/scope /dependency dependency groupIdorg.junit.platform/groupId artifactIdjunit-platform-suite/artifactId version1.10.2/version scopetest/scope /dependency /dependencies版本之间要注意兼容。Cucumber 7 对应 JUnit Platform 1.9 以上没问题但如果你项目里还引用了旧版 JUnit 4要小心cucumber-junit-platform-engine会不会和junit-vintage-engine冲突。建议先把测试工程独立成模块避免一大堆历史依赖纠缠。3.2 让测试入口暴露 JSON 报告创建测试入口类配置 Cucumber 的插件参数。这里的关键是把json、html、message三种输出同时打开import org.junit.platform.suite.api.ConfigurationParameter; import org.junit.platform.suite.api.IncludeEngines; import org.junit.platform.suite.api.SelectClasspathResource; import org.junit.platform.suite.api.Suite; import io.cucumber.junit.platform.engine.Constants; Suite IncludeEngines(cucumber) SelectClasspathResource(features) ConfigurationParameter( key Constants.PLUGIN_PROPERTY_NAME, value pretty, json:target/cucumber.json, html:target/cucumber-html-report/index.html, message:target/cucumber-messages.ndjson ) ConfigurationParameter(key Constants.PLUGIN_PUBLISH_ENABLED_KEY, value false) public class CucumberRunnerTest { }运行mvn test之后target目录下会生成cucumber.json、cucumber-messages.ndjson和基本的 HTML 文件。注意json:路径必须是相对当前工作目录的路径而且目标目录要提前存在否则 Cucumber 可能只创建一个空文件就停了。另外如果你用 Maven 的 clean 插件定时清理target记得把报告输出目录放到target之外或者安排报告归档步骤避免上一轮的结果被清掉。3.3 用 cucumber-html-reporter 生成美观的 HTML 报告Cucumber 自带的 HTML 插件生成的结果比较朴素不适合直接给团队看。我一般再加一层 cucumber-html-reporter 来渲染它读cucumber.json输出一个带侧边栏、统计卡片和图表的结果页。先初始化一个 Node 环境并安装依赖npm init -y npm install cucumber-html-reporter然后写一个report-gen.js文件const reporter require(cucumber-html-reporter); const options { theme: bootstrap, jsonFile: target/cucumber.json, output: target/cucumber-html-report.html, reportSuiteAsScenarios: true, scenarioTimestamp: true, launchReport: false, metadata: { App Version: 1.2.3, Test Environment: staging, Branch: release/2025Q1, Platform: Linux } }; reporter.generate(options);运行node report-gen.js后就能在target下得到一份更完整的 HTML 报告。launchReport: false是为了在 CI 环境里不自动打开浏览器。metadata里的信息要维护好后期看报告时能一眼确认这次跑的是哪个分支、哪个环境、哪个应用版本。如果需要把截图嵌进报告可以在 Java step 定义中使用scenario.attach()scenario.attach(Files.readAllBytes(screenshotPath), image/png, login-page-screenshot);不过 cucumber-html-reporter 对 attach 的展示支持比较有限复杂场景下还是建议把截图路径作为附件目录一并归档报告里只保留链接。3.4 在 Jenkins 里把 Cucumber 和 jmeter 5.6.3 报告合并很多团队实际测试不只是 BDD还有接口压测。我在 Jenkins 里会把 Cucumber 测试和 JMeter 压测放在同一个流水线任务中生成报告时一并归档这样能直接对比功能结果和性能结果。jmeteter 5.6.3 本身自带 HTML dashboard 生成能力命令很直接jmeter -n -t load_test.jmx -l target/jmeter/result.jtl -e -o target/jmeter-dashboard-e表示生成 dashboard-o指定输出目录。执行完成后target/jmeter-dashboard下会生成 index.html、统计表格和响应时间分布图。这和 Cucumber 报告的发布逻辑很像都是先产出文件再用 Jenkins 的 HTML Publisher 插件归档。完整流水线大致是# 1. 执行 Cucumber BDD 测试 mvn test # 2. 生成 Cucumber 自定义 HTML 报告 node report-gen.js # 3. 执行 JMeter 压测jmeter 5.6.3 生成测试报告 jmeter -n -t load_test.jmx -l target/jmeter/result.jtl -e -o target/jmeter-dashboard # 4. 归档到固定目录统一发布这里有个实操细节JMeter 的result.jtl格式要设置成 csv 或 jtl 默认格式jmeter.properties里的save_statistics相关配置不要随手改否则 dashboard 生成时会因为缺字段报错。第一次搭的时候最好先用最简单的 jmx 脚本把整条链路跑通再加复杂断言和监听器。4. 报告数据分析看完不等于看明白4.1 先看趋势再看成功率单次 Cucumber 报告的价值很低真正有价值的是连续多次执行后的趋势。我自己的做法是定期把cucumber.json里的场景总数、失败数、执行时长抽出来写入一个 CSV 文件用 Excel 或常见 BI 工具看趋势。下面是一个简单的解析脚本统计场景级别的通过失败情况import json from collections import Counter with open(target/cucumber.json, encodingutf-8) as f: data json.load(f) total 0 failed 0 failed_features Counter() for feature in data: for element in feature.get(elements, []): if element.get(type) ! scenario: continue total 1 has_failed_step any( step.get(result, {}).get(status) failed for step in element.get(steps, []) ) if has_failed_step: failed 1 failed_features[feature[name]] 1 print(ftotal scenarios: {total}) print(ffailed scenarios: {failed}) print(failed feature ranking:, failed_features.most_common(5))不同 Cucumber 版本的 JSON 结构略有差异跑之前先print一个 feature 节点确认字段名。如果版本太新导致elements字段变化更稳妥的办法是直接解析cucumber-messages.ndjson。数据有了之后每周生成一个趋势图重点看失败率是否在升高、某个模块的失败是否反复出现。单个失败可能是偶发但如果同一个场景连续三天失败那基本可以判断是稳定的线上回归必须立刻处理。4.2 失败用例的归类与处理报告中出现红块不能一概而论。按我的经验大部分失败可以归成三类。第一类是代码或接口问题表现是断言失败、HTTP 状态码不对、返回结构缺字段。这类问题要第一时间反馈给开发。第二类是测试数据问题表现是预期存在的数据不存在、环境里的 mock 数据过期处理办法是完善数据初始化脚本而不是改测试代码。第三类是环境问题表现是超时、连接拒绝、服务重启导致上下文丢失这类失败经常是偶发的需要在报告里打上“flaky”标记再决定是否自动重试。我把这三类做成一个简单的判断表贴在测试团队内部失败类型观察线索处理动作代码/接口问题error_message 中有 4xx/5xx、BeanValidation 异常第一时间提 bug附上失败步骤截图测试数据问题“expected but was” 中的值明显是脏数据调整 Before 中的数据预处理环境问题socket timeout、connection reset、服务未启动先确认环境健康再考虑自动重跑如果同时接了 JMeter 压测还能多做一层交叉判断Cucumber 场景大面积失败同时 JMeter 聚合报告里的响应时间中位数上涨明显那大概率不是业务逻辑 bug而是环境容量或网络问题。这种分析比单看一份报告有用得多。4.3 数据驱动辅助报表慢步骤和重复失败标准 HTML 报告之外我会额外生成两类辅助报表。一类是最慢步骤 TOP 10从cucumber-messages.ndjson里提取 step 开始结束时间计算每个 step 的耗时。产出这个表后经常能发现某个 Before 钩子初始化浏览器占了几秒钟测试执行时间被无谓拉长。另一类是重复失败场景列表。把同一场景在多次运行中的失败信息做聚合如果在不同环境、不同数据下都失败说明它大概率是真实缺陷。如果只在特定环境失败就是配置型问题。这个分析不需要多复杂一个计数器加一个字典就能实现但它能帮团队快速定位最容易出问题的业务链路优先补测试或修复。5. 常见问题与排查技巧实录5.1 Cucumber 报告最典型的五个坑搭建过程中下面五个问题我基本都踩过列出来给大家作参考。现象原因解决办法json 文件生成但内容为空数组Runner 没配置 json 插件或路径冲突检查 Constants.PLUGIN_PROPERTY_NAME 配置HTML 报告中文乱码编译和运行时的字符集不一致在 pom.xml 里配置 UTF-8并设置-Dfile.encodingUTF-8并行执行后结果文件互相覆盖多线程共写一个 json用 message 格式或用时间戳区分输出文件名HTML 打开是空白页面资源路径使用绝对路径本地 file 协议加载问题用相对路径或起一个本地静态服务Jenkins 里看不到报告HTML Publisher 路径配置错误配置工作空间相对路径并允许 JS 加载第二个问题在 Windows 上尤其常见。本地开发是 GBKCI 是 UTF-8同一个报告在不同环境生成出来可读性完全不同。建议在 Mavenpom.xml里固定编码properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding project.reporting.outputEncodingUTF-8/project.reporting.outputEncoding /properties第五个问题要特别说一下Jenkins 的 HTML Publisher 插件默认不启用 JavaScript如果你的报告里有图表库动态渲染会发现页面上只有空框架。处理办法是在“HTML Publisher”配置里勾选允许 JS或者在报告根目录放一个空index.html作为入口。5.2 步骤耗时不准怎么办很多测试同学用报告里的 step duration 来判断性能瓶颈但经常发现耗时和执行时感知不一致。这里要理解 Cucumber 的计时方式默认情况下hooks 的耗时不算在某一个 step 内而是在场景级别汇总。比如你在 Before 里初始化了一个昂贵的对象报告可能把时间摊到第一个 step 上导致看起来第一个 step 特别慢。另外如果开了重试机制失败后重跑的 step 会替换原结果最终报告只能看到最后一次尝试的耗时。对定位问题来说这会造成误导。我的建议是报告里的耗时只看相对变化不要当成精确计时器。真正要做性能分析使用 profile 工具或者单独写计时脚本在 step 内部自行记录业务时间。并行执行时这个问题更明显。Cucumber 多线程共享浏览器 driverdriver 内部有锁和等待时step 耗时会受其他线程影响。到了这种阶段就不能依赖报告定位单步性能了应该把并行线程数降下来单独跑一轮用控制变量法分析。5.3 结合 jmeter 5.6.3 的聚合报告经验最后聊一下 jmeter 5.6.3 生成测试报告时容易踩的坑。最常见的是执行完jmeter -n -t load_test.jmx -e -o target/jmeter-dashboard后dashboard 报错或者输出为空。排查顺序基本三步第一步确认result.jtl是否生成且非空。很多时候 jmx 脚本本身就有问题压测根本没发起请求-e -o只生成一个空壳 dashboard。先打开 jtl 文件看有没有 sample 记录。第二步确认 JMeter 版本和 Java 版本兼容。5.6.3 要求 Java 8 及以上但如果你在 Java 17 环境跑个别监听器组件会有兼容警告。第三步确认jmeter.properties没有被人为改坏。尤其mode、pretty相关参数不要随意改成非默认值。把 jmeter 5.6.3 的 dashboard 和 Cucumber 报告放到一起后建议把两个报告的生成时间和构建号作为目录名比如reports/20250610_build_42/。这样回看历史时能清晰定位某次发布对功能和性能的影响。JMeter 报告的响应时间图、错误率图都很直观和 Cucumber 的功能通过率放在一起能让团队在做发布决策时至少有一份不遗漏的客观依据。我自己的习惯是每次跑完 Cucumber 和 JMeter 之后会顺手把日期和执行时间拼到报告文件名里再丢到固定归档目录。三个月后回看哪些模块开始恶化、哪些重构引入回归一眼就能看出来。报告不追求绚丽能支撑决策就够了。如果报告生成出来永远没人看那不管用多酷炫的工具都是白搭还不如先花时间把数据流和归档路径理顺。
