Jenkins 与 Apifox 自动化测试的最佳实践

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"} // 这里的 "nodejs18" 是你在 "全局工具配置(Tools)" 中设置的 NodeJS 名称

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

3、执行构建

在项目页面，点击「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 中如何将「消息通知」集成到第三方应用（钉钉、飞书等）

常见问题

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

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

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

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

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

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

2、想要定时构建，要怎么在 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） 。