cypress reporter

Cypress 默认提供了 spec reporter，在 CLI 运行的时候，会将结果输出到 stdout 中。同时，如果使用编程的方法直接调用 Cypress.run API，会以 Promise 的方式将运行的结果返回，程序可以从运行结果中，将主要的运行数据给读取出来。然而，不论是哪一种方案，都不能非常直观的将运行结果展示出来。以下介绍如何在 Cypress 中引入 Mochawesome reporter，用于生成直观的 HTML 报告。

需要事先说明的是，虽然 Cypress 是建立在 Mocha 的基础上，且 Mochawesome 是 Mocha 中非常流行的报告生成方案，但是直接使用 Mochawesome 在 Cypress 中生成报表还是有问题的。主要的原因在于，Cypress 调整了测试的行为，自 3.0 版本开始，每一个测试用例（spec）都是单独运行的。因此，原生的 Mochawesome 无法直接生成一个包含所有测试用例的完整报告。为此，需要借助一些额外的工具。

首先，在项目需要用到 mocha 和 mochawesome：

yarn add mocha mochawesome

另外需要两个额外的包，分别是 mochawesome-merge 和 mochawesome-report-generator。可以通过 yarn 或 npm 安装到工作目录中，也可以通过 npx 在需要的时候直接使用。这里，mochawesome-merge 将用于将所有的测试用例运行结果进行合并的，然后用 mochawesome-report-generator 包生成统一的完整报告。

接下来，修改 cypress.json 配置文件如下：

{
  "reporter": "mochawesome",
  "reporterOptions": {
    "reportDir": "cypress/results",
    "overwrite": false,
    "html": false,
    "json": true
  }
}

配置完成，再运行 Cypress，会在 cypress/results 目录下生成一批 JSON 文件（如 mochawesome.json，mochawesome_001.json，……）。

有了这批生成的 JSON 报告，就可以使用 mochawesome-merge 命令，将这些 JSON 文件打包成一个完整的 JSON 报告。CLI 命令如下：

npx mochawesome-merge --reportDir cypress/results > mochawesome.json

生成了完整的 JSON 文件之后，可以通过 mochawesome-report-generator 生成需要的 HTML 报告：

npx mochawesome-report-generator mochawesome.json

当然，如果需要以编程的方式来执行上面的生成报告过程，可以参考下面的代码：

const cypress = require('cypress');
const { merge } = require('mochawesome-merge');
const generator = require('mochawesome-report-generator');

async function generate() {
  await cypress.run(config)
  const report = await merge({ reportDir: 'cypress/results' });
  const htmlReports = await generator.create(report, {
    reportFilename: 'report.html',
    // cdn 的命令可以在生成 HTML 报告的时候不额外生成 JavaScript/CSS 文件
    // 这些静态文件会走 CDN (unpkg)
    // 这样，只需要保存一个 HTML 文件就可以了，方便存储
    cdn: true
  });
  // report 就是 HTML 报告文件生成的路径
  const [report] = htmlReports;
}

generate();

更多的参数使用可以参考项目的源代码。

需要注意的一点是，生成 Report 之前需要确认 cypress/results 目录是否是干净的空目录。如果目录中仍然包含上一次运行的结果，那么最终合并报告的时候，两次运行的结果会叠加在一起，最终导致报告中包含多次运行的内容。一般在 Docker 中运行的话不会有这个问题，但是在本地跑的时候需要注意清理工作。