跳到主要内容

与 Jenkins 集成

安装 Jenkins​

Jenkins 是一款自动化构建工具，可以帮助开发人员在软件开发过程中自动化构建、测试和部署应用程序。以下是 Linux 系统中的安装方法：

  1. 添加 Jenkins GPG 公钥：
wget -q -O - https://pkg.jenkins.io/debian/jenkins.io.key | sudo apt-key add -
  1. 将 Jenkins 源添加到 APT 软件源列表中：
sudo sh -c 'echo deb http://pkg.jenkins.io/debian-stable binary/ > /etc/apt/sources.list.d/jenkins.list'
  1. 更新 APT 软件包列表：
sudo apt-get update
  1. 安装 Jenkins：
sudo apt-get install jenkins
  1. 启动 Jenkins 服务：
sudo systemctl start jenkins

安装完成后在 Web 浏览器中输入 http://localhost:8080 来访问 Jenkins 控制台。控制台提供了 Web 界面以便你管理和配置 Jenkins 服务。


如需了解更多有关于 Jenkins 的说明，请查看 Jenkins 官网。

配置 NodeJS 环境​

运行 Apifox CLI 前需确保 Node.js 版本号 >= v14.20.1，因此需要先在 Jenkins 环境中配置 NodeJS 依赖。

提示

更具体的操作步骤请参考这篇最佳实践：如何将 Apifox 的自动化测试与 Jenkins 集成？

1、打开 Jenkins 插件管理中找到 NodeJS 插件，安装并重启。

安装 node 插件

2、在全局工具配置中新建 NodeJS，填写 NodeJS 别名（比如 nodejs18）、版本号（需 >= v14.20.1）和包名 apifox-cli。

全局配置 node 路径

若 Jenkins 宿主机已经安装好 Apifox-CLI，希望直接在 Node 环境运行任务，那么可以参考下图的 Node 配置并填写宿主机的 Node 路径。

任务设置 node

你可以通过以下两种方式在 Jenkins 中触发 Apifox 自动化测试。

  1. 在可视化流水线中添加配置（Freestyle Project）
  2. 将嵌入式代码集成至流水线（Pipeline）

运行 CLI 命令​

可视化配置流水线​

打开 Apifox，在持续集成详情页中获取 CLI 命令。若 Jenkins 环境具备联网条件，可以选择使用「实时运行在线数据」命令；如果不具备联网条件，那么需要先导出 CLI 的 json 数据文件至环境中，再通过 CLI 执行。

可视化配置流水线

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

项目配置页面

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

构建步骤页面

在“命令”输入框中粘贴 Apifox CLI 命令并保存。

命令输入框

在项目中点击“Build Now（立即构建）”即可运行。

运行结果页面


将嵌入式代码集成至流水线​

轻点「CI/CD」 Tab 页并获取嵌入代码，将它粘贴至 Jenkins 的配置文件中。

粘贴至 Jenkins 的配置文件

将代码直接粘贴至 Jenkins 流水线配置中，即可嵌入至已有的持续集成工作流。

嵌入代码集成至流水线

这里的nodejs18就是上文中设置的 NodeJS 别名，请填写你的实际别名。并且，请确保在代码中将变量$APIFOX_ACCESS_TOKEN替换为你实际可用的 Access Token。你也可以在 Jenkins 的「Dashboard -> Manage Jenkins -> System」中添加一个名为APIFOX_ACCESS_TOKEN的环境变量，并将其值设置为你的 Access Token。这样，在执行流水线时，系统将能够读取到你的 Access Token。

添加环境变量

上述的代码也可以简化成下面这样的，把安装 Apifox CLI 的脚本去掉，这样就不需要每次执行构建任务时都安装一遍apifox-cli，从而减少构建时间和资源消耗。这是因为预先在“全局工具配置（Tools）”中设置了 NodeJS 和全局 npm 包（也就是 apifox-cli），它确保了在构建过程中可以直接使用已安装的工具。

Pipeline 脚本

在项目中点击“Build Now（立即构建）”即可运行。

运行结果页面

常见问题​

在 Jenkins 流水线内上传接口文档失败怎么办？​

  1. 确保运行 Jenkins 主机有足够的磁盘空间。
  2. 确保 Jenkins 任务的执行用户有足够的权限。
  3. 将需要上传的文件拷贝至 Jenkins 主机内的文件地址，并且在 CLI 命令中指定相同的文件地址路径。

有文件上传时如何获取文件？​

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

上传文件到 CLI 机器上

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

批量编辑接口

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

上传文件路径

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

上传文件路径到环境变量

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

使用环境变量上传文件


想要定时构建怎么设置？​

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


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


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

定时构建设置