十三、模块API——把Cypress当工具库来用模块API——把Cypress当工具库来用前面咱们都是通过cypr

模块API——把Cypress当工具库来用

前面咱们都是通过cypress open或cypress run命令运行测试，但Cypress还有更灵活的用法——作为Node模块调用。这种方式能让你在代码中控制测试的执行逻辑，比如动态挑选测试用例、整合测试报告，甚至和其他工具（如Jenkins、Git）联动。这一章咱们就来解锁这种高级用法。

一、什么是模块API？

简单说，模块API就是允许你在Node.js代码中直接调用Cypress的功能，而不是通过命令行。就像用import fs from 'fs'操作文件一样，你可以用import cypress from 'cypress'来控制测试运行。

核心命令有两个：

cypress.run()：对应命令行的cypress run，无界面运行测试；
cypress.open()：对应命令行的cypress open，启动图形界面。

二、基础用法：用代码启动测试

先来看个简单例子，用cypress.run()在Node脚本中运行测试：

1. 安装依赖

首先确保项目里已经安装了Cypress，然后创建一个Node脚本（比如run-tests.js）：

// run-tests.js
const cypress = require('cypress')

// 调用cypress.run()启动测试
cypress.run({
  spec: './cypress/integration/login/**/*.js' // 只跑登录相关用例
})
.then((results) => {
  console.log('测试结果：', results)
  // 可以根据结果做后续处理，比如失败时发送邮件
  if (results.totalFailed > 0) {
    console.error(`有${results.totalFailed}个用例失败！`)
  }
})
.catch((err) => {
  console.error('测试启动失败：', err)
})

2. 运行脚本

在命令行执行这个Node脚本：

node run-tests.js

效果和npx cypress run --spec './cypress/integration/login/**/*.js'一样，但你可以在代码中灵活控制参数。

三、高级用法：动态控制测试流程

模块API的真正价值在于“动态控制”，比如根据环境变量挑选用例、整合多份测试报告等。

1. 动态挑选测试用例

假设你想根据命令行参数决定跑哪些用例（比如只跑标注了[smoke]的冒烟测试），可以这样做：

// pick-tests.js
const cypress = require('cypress')
const minimist = require('minimist') // 解析命令行参数的库

// 解析命令行参数（比如 --grep smoke）
const args = minimist(process.argv.slice(2))
const grep = args.grep || '' // 要筛选的关键词

// 定义要运行的用例
const specPattern = grep 
  ? `./cypress/integration/**/*${grep}*.js` // 只跑包含关键词的用例
  : './cypress/integration/**/*.js' // 默认跑所有用例

cypress.run({
  spec: specPattern,
  reporter: 'mochawesome' // 生成HTML报告
})
.then((results) => {
  console.log(`测试完成：成功${results.totalPassed}个，失败${results.totalFailed}个`)
})

运行时传入关键词：

node pick-tests.js --grep smoke # 只跑文件名含smoke的用例

2. 整合多份测试报告

Cypress默认每个测试文件生成一份报告，用模块API可以把它们合并成一份完整报告（需要mochawesome-merge工具）：

// merge-reports.js
const cypress = require('cypress')
const { merge } = require('mochawesome-merge') // 合并报告的库
const generator = require('mochawesome-report-generator') // 生成HTML

// 1. 运行测试，生成多份JSON报告
cypress.run({
  reporter: 'mochawesome',
  reporterOptions: {
    overwrite: false, // 不覆盖已有报告
    json: true // 生成JSON格式
  }
})
.then(() => {
  // 2. 合并所有JSON报告
  return merge({
    files: ['./cypress/reports/mochawesome/*.json']
  })
})
.then((mergedReport) => {
  // 3. 生成一份完整的HTML报告
  return generator.create(mergedReport, {
    reportDir: './cypress/reports/merged'
  })
})
.then(() => {
  console.log('报告合并完成！')
})

运行后，在./cypress/reports/merged里就能看到整合后的报告了。

3. 和CI工具联动

在持续集成中，模块API可以帮你实现更复杂的逻辑，比如：

测试失败时自动重试；
根据测试结果决定是否继续部署；
把测试数据推送到数据库。

举个简单例子，测试失败时退出CI流程：

// ci-run.js
const cypress = require('cypress')

cypress.run()
.then((results) => {
  if (results.totalFailed > 0) {
    console.error('测试失败，终止部署！')
    process.exit(1) // 告诉CI工具流程失败
  } else {
    console.log('测试通过，继续部署～')
    process.exit(0)
  }
})

四、`cypress.run()`的参数详解

cypress.run()支持很多参数，和命令行的cypress run对应，常用的有：

参数	作用	例子
`spec`	指定要运行的用例文件	`'./cypress/integration/login.js'`
`browser`	指定浏览器	`'chrome'`、`'firefox'`
`env`	传递环境变量	`{ env: 'test', timeout: 10000 }`
`reporter`	指定测试报告格式	`'junit'`、`'mochawesome'`
`record`	是否上传结果到Dashboard	`true`
`parallel`	是否并行运行	`true`（需要配合`record`）

小结

模块API让Cypress从“一个测试工具”变成了“一个可编程的测试库”，尤其适合复杂场景：动态挑选用例、整合报告、和CI/CD工具联动等。掌握这种用法，你能把测试流程深度融入开发链路，实现更灵活的质量保障方案。

下一章咱们进入最后一部分：持续集成实践——如何把Cypress测试嵌入到CI流水线中，实现“代码提交即自动测试”～

十三、模块API——把Cypress当工具库来用