Apifox CLI是一款专为命令行环境设计的API测试工具，能让你摆脱图形界面，高效地集成测试流程。日常开发验证，还是融入CI/CD流水线，都能大显身手。

Apifox CLI优势

自动化测试：通过命令直接运行测试用例/场景，无需打开Apifox图形界面。实现无头 (Headless) 测试，轻松集成到脚本和 CI/CD 流程中。

持续集成 (CI)：生成可直接在 CI 环境（如 Jenkins）中运行的命令，并提供丰富的报告格式。保证每次代码提交或构建都能自动验证 API 功能，提升软件质量。

协作报告：支持生成 HTML、JSON、JUnit 等多种格式的测试报告，并可上传至云端和团队共享。方便测试结果的历史追溯和团队协作，快速定位问题。

环境安装和配置

安装Node.js

Apifox CLI依赖于Node.js（版本 ≥ v10）。请确保你的系统已安装Node.js，然后通过以下命令安装CLI：

bash

npm install -g apifox-cli

获取 Access Token

为了在命令行中安全地访问你的Apifox项目数据，你需要配置Access Token。这个Token可以在Apifox网页端或客户端的项目设置 -> 高级设置 -> API访问令牌中生成。在后续的命令中，你需要通过 --access-token 参数来使用它。

主要命令和用法

Apifox CLI的主要是Apifox run命令，支持两种主要的运行模式。

模式一：实时运行在线数据（推荐用于CI/CD）

这种方式直接运行存储在Apifox云端的最新测试场景，无需维护本地导出文件，非常适合持续集成。

命令示例：

bash

apifox run --access-token <你的Token> -t <测试场景ID> -e <环境ID> -r html,cli --out-dir ./test-reports

参数解析：

-t, --test-scenario: 指定要运行的测试场景 ID。

-e, --environment: 指定运行环境（如测试环境、生产环境）。

-r, --reporters: 指定报告格式。支持 cli（终端内显示）、html（详细网页报告）、json（用于后续自动化处理）、junit（兼容许多CI平台）。

--out-dir: 自定义报告输出目录。

在Apifox的图形界面中，进入测试场景的CI/CD配置页面，配置好环境、测试数据等选项后，Apifox会为你自动生成包含所有必要参数的命令，你只需复制并添加 --access-token 即可使用。

模式二：运行导出的本地数据文件

也可以将测试场景导出为 *.apifox-cli.json格式的本地文件，然后运行该文件。

命令示例：

bash

apifox run /path/to/your/test-scenario.apifox-cli.json -r html,json --out-file my-report

实用命令选项一览

Apifox CLI提供了丰富的选项来满足不同测试需求。常用参数：

变量和数据：

-n, --iteration-count <n>，设置测试场景的循环次数。

-d, --iteration-data <path>，指定数据驱动测试所需的 CSV 或 JSON 数据文件。

--env-var <key=value>，动态设置环境变量，例如：--env-var "username=test"。

请求控制：

--delay-request [n]，设置请求之间的延迟时间（毫秒），避免对服务器造成瞬时压力。

--timeout-request [n]，设置接口请求超时时间（毫秒）。

-k, --insecure，关闭 SSL 证书校验（用于测试自签名证书的HTTPS服务）。

报告和通知：

--upload-report，将本次运行的测试报告上传至Apifox云端，方便在 App 中查看。

--notification <targetIds>，测试完成后，向指定对象（如钉钉、企业微信群）发送通知。

调试：

--verbose，在测试报告中显示所有接口的实际请求和响应的详细信息，便于调试。

集成和应用

将ApifoxCLI 集成到 CI/CD 流程中，以下是一个流程：

在CI环境中准备节点：确保你的Jenkins、GitLab CI 等CI服务器已安装Node.js 和Apifox CLI。

安全地配置 Token：将你的Apifox Access Token 设置为CI环境的安全变量或密钥，避免在脚本中明文书写。

生成并运行命令：在Apifox的CI/CD配置界面生成命令，并嵌入到CI的Pipeline脚本中。例如，在Jenkins的一个构建步骤中直接执行该命令。

归档测试报告：配置CI流程归档生成的HTML等格式的报告，以便后续查看。

常见问题

变量管理：对于 CI/CD，建议在Apifox项目中使用环境变量的"远程值"功能，将敏感信息（如密码）和测试场景分离，并通过 CI 环境变量注入 --access-token。

文件上传处理：如果测试用例涉及文件上传，你需要将文件预先存放在运行 CLI 的机器上，并在测试场景中通过"批量编辑"将文件参数的值更新为该机器上的绝对路径。

外部脚本和数据库：如果测试中引用了外部程序或数据库连接，记得使用 --external-program-path 和 --database-connection 参数指定它们在CI环境中的路径。

常见问题排查

Invalid character in header content["Authorization"]错误：检查测试场景所使用的环境中，是否在请求头（Header）的Authorization字段设置了非法字符。保证在Apifox客户端中运行自动化测试没有异常，并检查环境变量的"远程值"。

文件上传失败：确保CLI运行的机器上存在测试用例中指定的文件路径，并且路径正确。

连接失败或SSL错误：如果测试目标是自签名的HTTPS服务，可以尝试使用 -k 参数临时绕过SSL校验。