如何将 Apifox 的自动化测试与 Jenkins 集成？

CI/CD（持续集成/持续交付） 在 API 测试中的主要目的是为了自动化 API 的验证流程，确保 API 发布到生产环境前的可用性。通过持续集成，我们可以在 API 定义变更时自动执行功能测试，以及时发现潜在问题。

Apifox 支持与众多的 CI/CD 平台集成，例如 Jenkins、Gitlab、GitHub Actions 等。你可以在自动化测试的 CI/CD 模块中找到相应的集成代码，只需将这些代码片段添加到你的 CI/CD 工作流中，就能实现 Apifox 自动化测试与你现有 CI/CD 流程的无缝衔接。

本文主要介绍怎么将 Apifox 自动化测试中的测试场景与 Jenkins 集成，下面详细介绍具体操作。

安装 Jenkins

关于 Jenkins 的安装方法，可以参考 Jenkins 官方文档，里面有各个系统的详细安装教程。

安装完成后可在浏览器中通过http://{你的公网IP}:8080来访问 Jenkins 的可视化页面。

接下来，我们将设置必要的配置项，以确保可以在 Jenkins 中顺利运行 Apifox CLI 命令。

配置 Node.js 环境

1. 安装 NodeJS 插件

在 Jenkins 的管理页面，点击“Manage Jenkins”，然后选择“Manage Plugins”进入插件管理页面。

在“Available”标签下，搜索 NodeJS 插件，将其安装并重启 Jenkins。

2. 配置 NodeJS 和全局 npm 包

NodeJS 插件安装完成后，需要进行一些配置。回到“Manage Jenkins”页面，选择“Tools”进入到全局配置工具页面。

在 Tools 页面找到 NodeJS 模块，点击“Add NodeJS”，然后在配置项中填入 NodeJS 别名（比如 nodejs18）。

选择一个 NodeJS 版本（需大于 v14.20.1），在“Global npm packages to install”中输入 apifox-cli，勾选“Install automatically”以在构建过程中自动安装相应的 npm 包（也就是 apifox-cli），配置完毕后保存即可。

配置好 NodeJS 环境后，可以在 Jenkins 中通过两种方法构建流水线以达到持续集成的目的，分别是 Pipeline 和 Freestyle Project。下面分别介绍这两种方法。

通过 Pipeline 构建

1. 创建 Pipeline 项目

在 Jenkins 的主页，点击“新建任务（New Item）”，输入项目名称，选择“Pipeline”，点击“确定（OK）”。

2. 配置 Pipeline

在项目配置页面，找到“Pipeline”选项，在“Definition”下拉菜单中选择“Pipeline script”。

在脚本框中输入以下从 Apifox 中获取到的 Pipeline 脚本，配置完成后保存即可。

pipeline {
  agent any

  tools {nodejs "nodejs18"} // 这里的 "nidejs18" 是你在 "全局工具配置(Tools)" 中设置的 NodeJS 名称

  stages {
    stage('Install Apifox CLI') {
      steps {
        sh 'npm install -g apifox-cli'
      }
    }

    stage('Running Test Scenario') {
      steps {
        sh 'apifox run https://api.apifox.com/api/v1/projects/4532246/api-test/ci-config/438628/detail?token=xL1XMVLjxxxxxxxxxxx -r html,cli'
      }
    }
  }
}

这个 Pipeline 脚本可以在 Apifox 自动化测试中的 CI/CD 模块中获取。

上述的 Pipeline 脚本可以简化成下面这样的，把安装 Apifox CLI 的脚本去掉，这样就不需要每次执行构建任务时都安装一遍 apifox-cli，从而减少构建时间和资源消耗。

这是因为预先在“全局工具配置（Tools）”中设置了 NodeJS 和全局 npm 包（也就是 apifox-cli），它确保了在构建过程中可以直接使用已安装的工具。

pipeline {
  agent any

  tools {nodejs "nodejs18"} // 这里的 "nidejs18" 是你在 "全局工具配置(Tools)" 中设置的 NodeJS 名称

  stages {
    stage('Running Test Scenario') {
      steps {
        sh 'apifox run https://api.apifox.com/api/v1/projects/4532246/api-test/ci-config/438628/detail?token=xL1XMVLjxxxxxxxxxxx -r html,cli'
      }
    }
  }
}

3.新版 CI/CD 配置(可选)

如果使用的是新版的 CI/CD 命令，比如这样的：

pipeline {
  agent any

  tools {nodejs "{your_nodejs_configured_tool_name}"}

  stages {
    stage('Install Apifox CLI') {
      steps {
        sh 'npm install -g apifox-cli'
      }
    }

    stage('Running Test Scenario') {
      steps {
        sh 'apifox run --access-token $APIFOX_ACCESS_TOKEN -t 4901173 -e 23605455 -n 1 -r html,cli'
      }
    }
  }
}

你需要在代码中将变量 $APIFOX_ACCESS_TOKEN 替换为你实际可用的 Access Token。你也可以在 Jenkins 的「Dashboard -> Manage Jenkins -> System」中添加一个名为 APIFOX_ACCESS_TOKEN 的环境变量，并将其值设置为你的 Access Token。这样，在执行流水线时，系统将能够读取到你的 Access Token。

4. 执行构建

在项目页面，点击“立即构建（Build Now）”可开始执行流水线。

可在“构建历史（Build History）”中查看构建的进度和结果。

通过 Freestyle Project 构建

1. 创建 Freestyle Project

在 Jenkins 的主页，点击“新建任务（New Item）”，输入项目名称，选择“Freestyle project”，点击“确定（OK）”。

2. 配置构建环境

在项目配置页面，找到“构建环境（Build Environment）”选项，勾选“Provide Node & npm bin/ folder to PATH”，并选择你在“全局工具配置（Tools）”中设置的 NodeJS 版本（如 nodejs18）。

3. 添加构建步骤

构建环境设置好以后，找到“构建步骤（Build Steps）”选项，点击“添加构建步骤（Add build step）”，选择“Execute Shell”（如果是 Windows 服务器，选择“Execute Windows Batch Command”）。

然后将 Apifox CLI 的命令拷贝进去，保存即可。

4. 执行构建

在项目页面，点击“立即构建（Build Now）”可开始执行流水线。

可以在“构建历史（Build History）”中查看构建的进度和结果。

将构建结果发送到第三方应用

持续集成的构建结果可以发送给第三方应用，比如飞书、钉钉等。

具体需要你在 Apifox 的【项目设置 -> 通知设置 -> 外部通知】中配置通知事件，可参考这篇文章：《Apifox 中如何将「消息通知」集成到第三方应用（企业微信、钉钉、飞书、Webhook、Jenkins》

常见问题解决

Q：如果接口中有文件需要上传，在构建时如何获取到这个文件？

可以事先将需要的文件上传到运行 CLI 的机器上（也就是运行 Jenkins 所在的宿主机），例如这个图像文件：apifox-xiangmu.jpg，可将其路径复制下来。

然后在 Apifox 的自动化测试里定位到需要上传文件的接口，点击“批量编辑”按钮。

将上传到 CLI 机器上的文件路径填入到“参数值”那里即可，这样在构建时就会自动根据文件路径获取到实际文件。

除此之外，还可以把文件路径放到环境变量的“远程值”那里。

然后在“批量编辑”中通过变量的方式引用该文件路径，这样也可以在构建时通过文件路径获取到实际文件。

Q：想要定时构建，要怎么在 Jenkins 中设置？

Apifox 目前已支持使用定时任务，具体可参考帮助文档的「定时运行功能测试」模块，这种方式会更友好且方便。

如果要在 Jenkins 中设置定时任务，可以通过配置项目的“构建触发器（Build Triggers）”来实现，并使用类似于 Unix 的cron表达式来指定构建的时间和频率。

在 Jenkins 的项目配置页面，找到“构建触发器（Build Triggers）”模块，勾选“定期构建（Build periodically)”选项，在出现的文本框中输入cron表达式来定义构建的时间和频率，关于corn表达式的使用这里不具体赘述。

总结

以上就是将 Apifox 的自动化测试与 Jenkins 集成的方法，不管选择哪一种构建方式，都需要确保在构建之前安装了 Apifox CLI，你可以选择在构建过程中自动安装（对应上文的“配置 Node.js 环境”小节），也可以提前在 Jenkins 所在的宿主机中安装（安装命令为 npm install -g apifox-cli）。

更详细的内容可以参考 Apifox 的帮助文档，如果使用中有任何问题或建议，欢迎随时在用户群反馈给我们。