WebdriverIO JSON 报告器完全指南从配置输出到并行结果合并【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio导读wdio/json-reporter是 WebdriverIO 官方提供的 JSON 格式测试结果报告器Reporter插件位于本仓库的 packages/wdio-json-reporter 目录。它能够在每次测试运行结束后把套件、用例、钩子与运行状态汇总为结构化的 JSON 文件或输出到标准输出stdout供 CI 管道、自定义工具链和第三方平台消费。本文将以该报告器的官方 README 为主线结合其 源码 与 测试用例讲清三种配置姿势stdout 输出、目录落盘、自定义文件名、JSON 输出结构以及 WDIO v5 之后并行会话报告分散问题下mergeResults合并工具的完整用法。一、安装作为 WebdriverIO 的插件wdio/json-reporter需要作为开发依赖安装npm install wdio/json-reporter --save-dev从当前仓库的 package.json 可以看到该包要求 Node.js 版本18.20.0采用 ESM 模块规范type: module运行时依赖wdio/reporter负责事件流收集与统计、wdio/types类型定义以及safe-regex2用于合并阶段的正则安全性校验。它的版本随 WebdriverIO 主版本号发布当前仓库中为9.31.2。二、配置三种输出方式报告器在 WebdriverIO 配置文件通常是wdio.conf.js/wdio.conf.ts的reporters数组中注册。reporters支持两种元素形式字符串直接引用内置/已安装的报告器名称或[名称, 选项对象]元组传入该报告器的配置。下面逐一展开 JSON 报告器的三种常用配置。2.1 结果输出到 stdout当你希望把 JSON 报告打印到标准输出例如在终端直接查看或交给上游命令做管道处理时使用stdout: truereporters: [ dot, [json, { stdout: true }] ],从 src/index.ts 的实现看JsonReporter继承自wdio/reporter的WDIOReporter基类。基类在构造函数中会根据stdout与logFile的组合来决定写入目标当options.stdout为真且提供了writeStream时报告通过自定义写入流输出否则落到文件流。因此stdout: true配合管道或日志采集即可实时拿到结构化结果。2.2 结果写入文件不指定stdout而是提供outputDir报告就会被写入该目录下的文件中reporters: [ dot, [json,{ outputDir: ./results }] ],基类 WDIOReporter 构造函数 会先递归创建输出目录fs.mkdirSync(outputDir, { recursive: true })因此./results目录无需预先手动创建。这里有一个值得注意的实现细节在 src/index.ts 中构造函数会检查options.logFile如果它以.log结尾会自动把扩展名替换为.json。这意味着 JSON 报告器的默认落盘文件名沿用的是 WebdriverIO runner 生成的wdio-cid-reporter名-reporter.log格式最终会变成形如wdio-0-0-json-reporter.json的文件——这一点可以在测试夹具 wdio-0-0-json-reporter.json 中得到印证。2.3 自定义文件名outputFileFormat并行执行时不同会话session/cid的报告会使用各自的文件名默认名中已经包含cid。你还可以通过outputFileFormat函数完全接管文件命名逻辑reporters: [ dot, [json,{ outputDir: ./results, outputFileFormat: (opts) { return results-${opts.cid}.${opts.capabilities.browserName}.json } }] ],outputFileFormat接收一个opts对象其核心字段包括cid会话 ID如0-0、capabilities当前会话的浏览器/设备能力从中可取出browserName以及 WebdriverIO 的运行配置。真实的调用与校验逻辑位于 packages/wdio-runner/src/reporter.ts 的getLogFile方法默认文件名模板为wdio-${cid}-${name}-reporter.log若配置中存在outputFileFormat则先通过options.cid this._cid、options.capabilities this.caps注入上下文再调用该函数得到实际文件名如果outputFileFormat不是函数会直接抛出错误outputFileFormat must be a function这一点有对应测试覆盖见 wdio-runner/tests/reporter.test.ts最终文件路径为path.join(outputDir, filename)。提示由于 capabilities 来自被测环境在不同浏览器/设备上并行执行时上述函数可生成按browserName区分的文件便于后续按环境分类处理。三、JSON 输出结构解析了解输出的 JSON 结构是消费报告结果的前提。JsonReporter在onRunnerEnd回调中调用#prepareJson组装数据并通过this.write写出见 src/index.ts。完整类型定义在 src/types.ts其顶层结构如下字段类型说明start/endDate整个 runner 会话的开始/结束时间capabilitiesResolvedTestrunnerCapabilities该会话最终解析出的浏览器能力含browserName、browserVersion、sessionId等frameworkstring使用的测试框架如mocha、jasmine、cucumbermochaOpts/jasmineOpts/cucumberOptsobject对应框架的配置当前 fixture 中可见mochaOpts.timeout、mochaOpts.uisuitesTestSuite[]套件列表每个套件含name、duration、start、end、sessionId、tests与hooksspecsstring[]本次运行涉及的 spec 文件路径列表stateSuiteState汇总统计{ passed, failed, skipped }在 src/index.ts 中#prepareJson遍历runner.specs与当前收集到的this.suites将每个用例与钩子分别通过 src/utils.ts 的mapTests/mapHooks映射为标准结构state统计规则为钩子中存在error计为 failed用例按state分别为passed/failed/skipped累加。用例状态State的合法取值为passed | failed | skipped | pending。下面是一个真实运行结果的简化样例取自 测试夹具{ start: 2023-11-06T16:38:50.809Z, end: 2023-11-06T16:38:57.536Z, capabilities: { browserName: chrome, browserVersion: 118.0.5993.117, sessionId: 39c03938eeafd9f797cb2a0c66fa5122 }, framework: mocha, mochaOpts: { timeout: 15000, ui: bdd }, suites: [{ name: webdriver.io page, duration: 6662, start: 2023-11-06T16:38:50.810Z, end: 2023-11-06T16:38:57.472Z, sessionId: 39c03938eeafd9f797cb2a0c66fa5122, tests: [ { name: should be a pending test, start: 2023-11-06T16:38:50.810Z, duration: 6726, state: skipped }, { name: should have the right title, start: 2023-11-06T16:38:50.810Z, end: 2023-11-06T16:38:57.471Z, duration: 6661, state: passed } ], hooks: [] }], specs: [file:///path/to/project/mocha.test.js], state: { passed: 1, failed: 0, skipped: 1 } }这份结构既包含可读的统计字段state也包含细粒度的用例与钩子明细含错误对象error非常适合直接喂给报告平台、CI 汇总脚本或用于失败归因分析。四、并行会话下的报告分散问题与 mergeResults 合并工具4.1 问题背景自 WebdriverIO v5 起报告机制从“集中式进程处理”改为“由每个会话session自行处理”。每个并行执行的测试 worker 都会独立产出自己的 JSON 文件这种方式显著减少了测试执行过程中的进程间通信inter-process chatter从而提升了整体性能。但代价也很明确无法天然得到一份覆盖全部测试的统一报告——你只会得到与 worker 数量相同的一批文件如wdio-0-0-json-reporter.json、wdio-0-1-json-reporter.json。4.2 使用 mergeResults 合并结果wdio/json-reporter为此提供了mergeResults工具函数把目录下多个 JSON 报告合并为单文件。官方推荐在wdio.conf.js的onComplete钩子中调用它——onComplete会在整个测试套件运行结束时触发此时各会话的报告文件已经落盘// wdio.conf.js import mergeResults from wdio/json-reporter/mergeResults export const config { // ... onComplete: function (exitCode, config, capabilities, results) { mergeResults(./results, wdio-.*-json-reporter.json, wdio-custom-filename.json) } // ... }参数说明如下参数含义默认值第一个参数dir存放各会话 JSON 报告文件的目录取process.argv[2]可直接作为 CLI 工具使用第二个参数filePattern用于匹配待合并 JSON 文件的正则表达式或字符串取process.argv[3]若非法或不安全则回退为/.json$/第三个参数customFileName合并后输出文件的名称wdio-merged.json注意wdio-custom-filename.json是可选项。如果不传第三个参数合并结果默认写入wdio-merged.json。从实现来看src/mergeResults.ts 会依次执行三个动作目录校验通过fs.access检查dir是否存在不存在则抛出Directory dir does not exist.读取与解析getDataFromFiles读取目录下所有匹配filePattern的文件并解析为 JSON合并与落盘mergeData执行数据合并随后写入path.join(dir, customFileName || wdio-merged.json)。4.3 合并规则与安全防护mergeDatasrc/mergeResults.ts的合并策略值得展开以第一个文件的结果为基准{ ...rawData[0] }其余文件的suites与specs通过扩展运算符push(...)拼接state中的passed/failed/skipped逐一累加每个文件的capabilities被收集为一个数组合并结果的capabilities由单个对象变为对象数组遍历所有套件取最大的suite.end作为合并结果的end保证时间戳口径正确。合并后的结构体类型为OmitResultSet, capabilities { capabilities: ResultSet[capabilities][] }即除capabilities变为数组外其余字段与单会话报告保持一致。值得强调的是filePattern会被safe-regex2进行正则安全性校验src/mergeResults.ts如果传入的是RegExp对象只有通过校验才会被使用如果传入的是字符串会尝试先构造RegExp再校验一旦校验失败或构造抛错正则语法非法都会安全回退到/.json$/。这一设计避免了对恶意或灾难性回溯ReDoS正则的误用。4.4 独立作为 CLI 工具使用由于函数默认值取自process.argv[2]、process.argv[3]、process.argv[4]mergeResults也可以脱离onComplete直接当作一个命令行小工具运行。其效果等同于执行合并逻辑并把结果写入目标目录例如示意命令node -e import(wdio/json-reporter/mergeResults).then(m m.default(./results, wdio-.*-json-reporter.json, merged.json))五、测试用例与验证依据当前仓库为 JSON 报告器提供了完整的 vitest 测试可用于验证上述所有行为tests/mergeResults.test.ts针对 测试夹具目录 下的两个 JSON 文件wdio-0-0-json-reporter.json与wdio-0-1-json-reporter.json调用mergeResults断言合并后capabilities、specs、suites的数量均为 2验证了多文件合并的累积逻辑tests/index.test.ts断言logFile以.log结尾时会被改写为.json并通过快照 index.test.ts.snap 固定了#prepareJson输出的 JSON 结构含start、end、capabilities、framework、suites、specs、state等字段。如果你修改或扩展了该报告器可运行包内测试验证cd packages/wdio-json-reporter npx vitest run六、小结与实践建议回到wdio.conf.js的reporters配置一份兼顾本地可读与结构化输出的典型组合是reporters: [ spec, // 终端上人类可读的汇总 [json, { outputDir: ./results, outputFileFormat: (opts) results-${opts.cid}.${opts.capabilities.browserName}.json }] ]实践中的关键取舍可以总结为三点选择输出方式CI 只需采集文件时用outputDir需要在管道中实时消费时用stdout: true需要多环境区分文件名时叠加outputFileFormat。务必处理并行报告只要测试并行执行就会产出多份 JSON请在onComplete中调用mergeResults汇成单文件默认wdio-merged.json避免遗漏会话数据。善用结构字段合并后的结果包含capabilities数组与逐用例/逐钩子的error明细可直接用于失败归因、按浏览器维度生成测试矩阵或接入自建的质量看板。以上配置与行为均可在本仓库 packages/wdio-json-reporter 目录的源码与测试中逐一验证按需深入即可。【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WebdriverIO JSON 报告器完全指南：从配置输出到并行结果合并
WebdriverIO JSON 报告器完全指南从配置输出到并行结果合并【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio导读wdio/json-reporter是 WebdriverIO 官方提供的 JSON 格式测试结果报告器Reporter插件位于本仓库的 packages/wdio-json-reporter 目录。它能够在每次测试运行结束后把套件、用例、钩子与运行状态汇总为结构化的 JSON 文件或输出到标准输出stdout供 CI 管道、自定义工具链和第三方平台消费。本文将以该报告器的官方 README 为主线结合其 源码 与 测试用例讲清三种配置姿势stdout 输出、目录落盘、自定义文件名、JSON 输出结构以及 WDIO v5 之后并行会话报告分散问题下mergeResults合并工具的完整用法。一、安装作为 WebdriverIO 的插件wdio/json-reporter需要作为开发依赖安装npm install wdio/json-reporter --save-dev从当前仓库的 package.json 可以看到该包要求 Node.js 版本18.20.0采用 ESM 模块规范type: module运行时依赖wdio/reporter负责事件流收集与统计、wdio/types类型定义以及safe-regex2用于合并阶段的正则安全性校验。它的版本随 WebdriverIO 主版本号发布当前仓库中为9.31.2。二、配置三种输出方式报告器在 WebdriverIO 配置文件通常是wdio.conf.js/wdio.conf.ts的reporters数组中注册。reporters支持两种元素形式字符串直接引用内置/已安装的报告器名称或[名称, 选项对象]元组传入该报告器的配置。下面逐一展开 JSON 报告器的三种常用配置。2.1 结果输出到 stdout当你希望把 JSON 报告打印到标准输出例如在终端直接查看或交给上游命令做管道处理时使用stdout: truereporters: [ dot, [json, { stdout: true }] ],从 src/index.ts 的实现看JsonReporter继承自wdio/reporter的WDIOReporter基类。基类在构造函数中会根据stdout与logFile的组合来决定写入目标当options.stdout为真且提供了writeStream时报告通过自定义写入流输出否则落到文件流。因此stdout: true配合管道或日志采集即可实时拿到结构化结果。2.2 结果写入文件不指定stdout而是提供outputDir报告就会被写入该目录下的文件中reporters: [ dot, [json,{ outputDir: ./results }] ],基类 WDIOReporter 构造函数 会先递归创建输出目录fs.mkdirSync(outputDir, { recursive: true })因此./results目录无需预先手动创建。这里有一个值得注意的实现细节在 src/index.ts 中构造函数会检查options.logFile如果它以.log结尾会自动把扩展名替换为.json。这意味着 JSON 报告器的默认落盘文件名沿用的是 WebdriverIO runner 生成的wdio-cid-reporter名-reporter.log格式最终会变成形如wdio-0-0-json-reporter.json的文件——这一点可以在测试夹具 wdio-0-0-json-reporter.json 中得到印证。2.3 自定义文件名outputFileFormat并行执行时不同会话session/cid的报告会使用各自的文件名默认名中已经包含cid。你还可以通过outputFileFormat函数完全接管文件命名逻辑reporters: [ dot, [json,{ outputDir: ./results, outputFileFormat: (opts) { return results-${opts.cid}.${opts.capabilities.browserName}.json } }] ],outputFileFormat接收一个opts对象其核心字段包括cid会话 ID如0-0、capabilities当前会话的浏览器/设备能力从中可取出browserName以及 WebdriverIO 的运行配置。真实的调用与校验逻辑位于 packages/wdio-runner/src/reporter.ts 的getLogFile方法默认文件名模板为wdio-${cid}-${name}-reporter.log若配置中存在outputFileFormat则先通过options.cid this._cid、options.capabilities this.caps注入上下文再调用该函数得到实际文件名如果outputFileFormat不是函数会直接抛出错误outputFileFormat must be a function这一点有对应测试覆盖见 wdio-runner/tests/reporter.test.ts最终文件路径为path.join(outputDir, filename)。提示由于 capabilities 来自被测环境在不同浏览器/设备上并行执行时上述函数可生成按browserName区分的文件便于后续按环境分类处理。三、JSON 输出结构解析了解输出的 JSON 结构是消费报告结果的前提。JsonReporter在onRunnerEnd回调中调用#prepareJson组装数据并通过this.write写出见 src/index.ts。完整类型定义在 src/types.ts其顶层结构如下字段类型说明start/endDate整个 runner 会话的开始/结束时间capabilitiesResolvedTestrunnerCapabilities该会话最终解析出的浏览器能力含browserName、browserVersion、sessionId等frameworkstring使用的测试框架如mocha、jasmine、cucumbermochaOpts/jasmineOpts/cucumberOptsobject对应框架的配置当前 fixture 中可见mochaOpts.timeout、mochaOpts.uisuitesTestSuite[]套件列表每个套件含name、duration、start、end、sessionId、tests与hooksspecsstring[]本次运行涉及的 spec 文件路径列表stateSuiteState汇总统计{ passed, failed, skipped }在 src/index.ts 中#prepareJson遍历runner.specs与当前收集到的this.suites将每个用例与钩子分别通过 src/utils.ts 的mapTests/mapHooks映射为标准结构state统计规则为钩子中存在error计为 failed用例按state分别为passed/failed/skipped累加。用例状态State的合法取值为passed | failed | skipped | pending。下面是一个真实运行结果的简化样例取自 测试夹具{ start: 2023-11-06T16:38:50.809Z, end: 2023-11-06T16:38:57.536Z, capabilities: { browserName: chrome, browserVersion: 118.0.5993.117, sessionId: 39c03938eeafd9f797cb2a0c66fa5122 }, framework: mocha, mochaOpts: { timeout: 15000, ui: bdd }, suites: [{ name: webdriver.io page, duration: 6662, start: 2023-11-06T16:38:50.810Z, end: 2023-11-06T16:38:57.472Z, sessionId: 39c03938eeafd9f797cb2a0c66fa5122, tests: [ { name: should be a pending test, start: 2023-11-06T16:38:50.810Z, duration: 6726, state: skipped }, { name: should have the right title, start: 2023-11-06T16:38:50.810Z, end: 2023-11-06T16:38:57.471Z, duration: 6661, state: passed } ], hooks: [] }], specs: [file:///path/to/project/mocha.test.js], state: { passed: 1, failed: 0, skipped: 1 } }这份结构既包含可读的统计字段state也包含细粒度的用例与钩子明细含错误对象error非常适合直接喂给报告平台、CI 汇总脚本或用于失败归因分析。四、并行会话下的报告分散问题与 mergeResults 合并工具4.1 问题背景自 WebdriverIO v5 起报告机制从“集中式进程处理”改为“由每个会话session自行处理”。每个并行执行的测试 worker 都会独立产出自己的 JSON 文件这种方式显著减少了测试执行过程中的进程间通信inter-process chatter从而提升了整体性能。但代价也很明确无法天然得到一份覆盖全部测试的统一报告——你只会得到与 worker 数量相同的一批文件如wdio-0-0-json-reporter.json、wdio-0-1-json-reporter.json。4.2 使用 mergeResults 合并结果wdio/json-reporter为此提供了mergeResults工具函数把目录下多个 JSON 报告合并为单文件。官方推荐在wdio.conf.js的onComplete钩子中调用它——onComplete会在整个测试套件运行结束时触发此时各会话的报告文件已经落盘// wdio.conf.js import mergeResults from wdio/json-reporter/mergeResults export const config { // ... onComplete: function (exitCode, config, capabilities, results) { mergeResults(./results, wdio-.*-json-reporter.json, wdio-custom-filename.json) } // ... }参数说明如下参数含义默认值第一个参数dir存放各会话 JSON 报告文件的目录取process.argv[2]可直接作为 CLI 工具使用第二个参数filePattern用于匹配待合并 JSON 文件的正则表达式或字符串取process.argv[3]若非法或不安全则回退为/.json$/第三个参数customFileName合并后输出文件的名称wdio-merged.json注意wdio-custom-filename.json是可选项。如果不传第三个参数合并结果默认写入wdio-merged.json。从实现来看src/mergeResults.ts 会依次执行三个动作目录校验通过fs.access检查dir是否存在不存在则抛出Directory dir does not exist.读取与解析getDataFromFiles读取目录下所有匹配filePattern的文件并解析为 JSON合并与落盘mergeData执行数据合并随后写入path.join(dir, customFileName || wdio-merged.json)。4.3 合并规则与安全防护mergeDatasrc/mergeResults.ts的合并策略值得展开以第一个文件的结果为基准{ ...rawData[0] }其余文件的suites与specs通过扩展运算符push(...)拼接state中的passed/failed/skipped逐一累加每个文件的capabilities被收集为一个数组合并结果的capabilities由单个对象变为对象数组遍历所有套件取最大的suite.end作为合并结果的end保证时间戳口径正确。合并后的结构体类型为OmitResultSet, capabilities { capabilities: ResultSet[capabilities][] }即除capabilities变为数组外其余字段与单会话报告保持一致。值得强调的是filePattern会被safe-regex2进行正则安全性校验src/mergeResults.ts如果传入的是RegExp对象只有通过校验才会被使用如果传入的是字符串会尝试先构造RegExp再校验一旦校验失败或构造抛错正则语法非法都会安全回退到/.json$/。这一设计避免了对恶意或灾难性回溯ReDoS正则的误用。4.4 独立作为 CLI 工具使用由于函数默认值取自process.argv[2]、process.argv[3]、process.argv[4]mergeResults也可以脱离onComplete直接当作一个命令行小工具运行。其效果等同于执行合并逻辑并把结果写入目标目录例如示意命令node -e import(wdio/json-reporter/mergeResults).then(m m.default(./results, wdio-.*-json-reporter.json, merged.json))五、测试用例与验证依据当前仓库为 JSON 报告器提供了完整的 vitest 测试可用于验证上述所有行为tests/mergeResults.test.ts针对 测试夹具目录 下的两个 JSON 文件wdio-0-0-json-reporter.json与wdio-0-1-json-reporter.json调用mergeResults断言合并后capabilities、specs、suites的数量均为 2验证了多文件合并的累积逻辑tests/index.test.ts断言logFile以.log结尾时会被改写为.json并通过快照 index.test.ts.snap 固定了#prepareJson输出的 JSON 结构含start、end、capabilities、framework、suites、specs、state等字段。如果你修改或扩展了该报告器可运行包内测试验证cd packages/wdio-json-reporter npx vitest run六、小结与实践建议回到wdio.conf.js的reporters配置一份兼顾本地可读与结构化输出的典型组合是reporters: [ spec, // 终端上人类可读的汇总 [json, { outputDir: ./results, outputFileFormat: (opts) results-${opts.cid}.${opts.capabilities.browserName}.json }] ]实践中的关键取舍可以总结为三点选择输出方式CI 只需采集文件时用outputDir需要在管道中实时消费时用stdout: true需要多环境区分文件名时叠加outputFileFormat。务必处理并行报告只要测试并行执行就会产出多份 JSON请在onComplete中调用mergeResults汇成单文件默认wdio-merged.json避免遗漏会话数据。善用结构字段合并后的结果包含capabilities数组与逐用例/逐钩子的error明细可直接用于失败归因、按浏览器维度生成测试矩阵或接入自建的质量看板。以上配置与行为均可在本仓库 packages/wdio-json-reporter 目录的源码与测试中逐一验证按需深入即可。【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 error` 自动校验 API 入参)
