跳到主要内容

Apifox CLI

Apifox CLI(Command Line Interface,即命令行界面)主要用来以命令行方式运行接口测试过程。它主要用于自动化测试场景。

安装 CLI

Apifox CLI 依赖 Node.js 版本号 >= v14.20.1。使用前请先安装 Node.js.

# 根据实际网络情况选择命令

npm install -g apifox-cli # npm 源命令

npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/ # 国内镜像源

你可以通过以下命令确认是否安装成功。

node -v && apifox -v && which node && which npm && which apifox

若安装成功,将会直接输出版本号和安装路径。

命令选项

命令行参数

  • apifox [options]

    -h, --help

    使用帮助。

  • -v, --version

    显示版本号

  • apifox run <file-source> [options]

    file-source 为从 Apifox 导出的测试场景数据文件存放路径。

  • --upload-report

    将运行 CLI 后所得到的测试报告总概览上传至云端,在客户端/Web 端中进行查看。

提示

--verbose 在生成的测试报告中显示所有接口实际请求和响应

更多选项

  -r, --reporters [reporters]                               指定测试报告类型, 支持 cli, html, json (default: ["cli"])
--out-dir <outDir> 输出测试报告目录,默认为当前目录下的 ./apifox-reports (default: "./apifox-reports")
--out-file <outFile> 输出测试报告文件名,不需要添加后缀,默认格式为 apifox-report-{当前时间戳}-0
--out-json-failures-separated <outJsonFailuresSeparated> 输出测试报告的 JSON 报告开启下,将 failures 详情单独导出为一个 json 文件
-n, --iteration-count <n> 设置循环次数
-d, --iteration-data <path> 设置用例循环的数据 (JSON 或 CSV)
--global-var <value> 设置全局变量,使用 key=value 格式。可以设置多个全局变量。例如:--global-var "user=123" --global-var "password=123"
--env-var <value> 设置环境变量,使用 key=value 格式。可以设置多个环境变量。例如:--env-var "user=123" --env-var "password=123"
--external-program-path <path> 指定 [外部程序] 的所处文件路径,默认值为命令当前执行目录
--database-connection <path> 指定 [数据库配置] 的所处文件路径,使用 URL 测试的时候必须指定
--ignore-redirects 阻止 Apifox 自动重定向返回 3XX 状态码的请求
--silent 阻止 Apifox CLI 输出到控制台
--color <value> 开启/关闭控制台彩色输出 (auto|on|off) (default: "auto")
--delay-request [n] 指定请求之间停顿间隔 (毫秒) (default: 0)
--timeout-request [n] 指定接口请求超时时间 (毫秒) (default: 0)
--timeout-script [n] 指定脚本预执行/后执行接口运行超时时间 (毫秒) (default: 0)
-k, --insecure 关闭 SSL 校验
--ssl-client-cert-list <path> 指定客户端证书配置路径 (JSON)
--ssl-client-cert <path> 指定客户端证书路径 (PEM)
--ssl-client-key <path> 指定客户端证书私钥路径
--ssl-client-passphrase <passphrase> 指定客户端证书密码 (for protected key)
--ssl-extra-ca-certs <path> 指定额外受信任的 CA 证书 (PEM)
-b, --bigint 兼容 bigint (default: false)
--upload-report 将本次测试报告总览上传至云端,在 App 中即可查看此测试报告 (default:false)
--verbose 显示所有接口请求的详细信息
--lang <language> 设置 CLI 的语言 (zh|en) (default: "zh")
--preferred-http-version <preferredHttpVersion> 首选 HTTP 协议版本。例如:--preferred-http-version "HTTP/2" 或 --preferred-http-version "https=HTTP/2,http=HTTP/1"
-h, --help display help for command

SSL

客户端证书

Apifox CLI 支持传入客户端证书。

使用单个 SSL 客户端证书

  • --ssl-client-cert
    公共客户端证书文件的路径

  • --ssl-client-key
    私有客户端密钥的路径(可选)

  • --ssl-client-passphrase
    用于保护私有客户端密钥的密码(可选)

使用 SSL 客户端证书 配置文件(支持多个证书)

  • --ssl-client-cert-list
    SSL 客户端证书列表配置文件的路径(JSON 格式)。示例如下 ssl-client-cert-list.json
ssl-client-cert-list.json

[
{
"name": "domain1",
"matches": ["https://test.domain1.com/*", "https://www.domain1/*"],
"key": {"src": "./client.domain1.key"},
"cert": {"src": "./client.domain1.crt"},
"passphrase": "changeme"
},
{
"name": "domain2",
"matches": ["https://domain2.com/*"],
"key": {"src": "./client.domain2.key"},
"cert": {"src": "./client.domain2.crt"},
"passphrase": "changeme"
}
]

此选项允许根据 URL 或主机名设置不同的 SSL 客户端证书。此选项优先于 --ssl-client-cert, --ssl-client-key--ssl-client-passphrase 选项。如果列表中的 URL 没有匹配项,这些选项将用作后备选项。

HTTP/2

通过指定参数 --preferred-http-version 可以使 CLI 支持使用特定的协议版本发送请求。

协议版本参数值:

  1. "HTTP/2" - HTTP/2 应用层协议协商,仅 HTTPS 请求支持。
  2. "HTTP/2-with-prior-knowledge" - HTTP/2 先验知识
  3. "HTTP/1" - HTTP/1.1

参数值支持如下配置:

--preferred-http-version="https=HTTP/2,http=HTTP/2-with-prior-knowledge" - 分别为 HTTPS、HTTP 请求设置不同的协议版本

--preferred-http-version="HTTP/1" - 同时为 HTTPS、HTTP 设置相同的协议版本

--preferred-http-version="HTTP/2" - 同时为 HTTPS、HTTP 设置相同的协议版本(不支持的值会自动忽略)

升级 CLI 版本

在终端运行以下命令升级 Apifox CLI。

sudo npm install apifox-cli@latest -g

使用 CLI

Apifox CLI 的使用场景有以下三种:

1. 在 CI/CD 平台中运行

Apifox 支持自动生成 Jenkins 和 Github Actions 配置代码。保存「持续集成」配置后,「CI / CD 工具」Tab 页中将生成嵌入式代码,你可以将它粘贴至持续集成体系的配置文件中,与现有的研发工作流相结合。具体详情请查看《与 Github Actions 集成》

2. 基于在线数据实时运行

持续集成配置保存后将自动在页面中生成一串可运行命令行。

示例代码如下:

apifox run https://api.apifox.com/api/v1/projects/detail?token=*********** -r html,cli
提示

若在测试步骤中引用了环境变量,那么导出文件时将直接使用变量中预设的远程值。

连接数据库

如果测试人员在测试步骤中接口的“前/后置操作”中添加与数据库有关的脚本或命令,例如下图所示:

持续集成命令将会自动出现数据库连接相关说明、内容。下载数据库连接配置文件后,在该文件的路径中执行 CLI 命令行触发自动测试过程。

例如现在将配置文件下载到了 ~/Downloads/Apifox 路径下。

先在终端中移动至该路径,然后复制 Apifox 客户端所给出的命令,复制后本地终端运行即可触发 CLI。

3. 基于本地测试文件运行

若希望在本地环境中通过 Apifox CLI 运行此测试场景,那么需要先「导出」当前测试场景下的 Json 文件,然后通过 Apifox CLI 工具运行该文件。

将以下命令中的 examples/sample.apifox-cli.json 替换为你的文件保存路径,然后在终端中运行。

apifox run examples/sample.apifox-cli.json -r cli,html
提示

若在测试步骤中引用了环境变量,那么导出文件时将直接使用变量中预设的本地值。

常见问题

1. 使用 CLI 后出现错误提示如何处理?

  • Invalid character in header content["Authorization"]

在终端运行 Apifox CLI 命令后出现 Invalid character in header content 错误:

若确保在 Apifox 客户端 / Web 端中运行自动化测试没有异常,请检查是否在环境中设置了远程值。

2. 接口需要上传文件,在 Apifox 中已经创建好了测试场景并且可以正常运行,但是通过 CLI 运行时出现报错,如何处理?

在需要上传文件的接口中,需要上传的文件实际保存在你自己的电脑上,Apifox 里保存的仅仅只是该文件的本地路径。因此当使用 CLI 方式执行测试时,安装了 CLI 的机器无法通过该路径读取到你电脑上的这个文件,所以会报错。

针对此问题的解决方案:

  1. 将该文件提前上传至运行 CLI 的机器上。
  2. 复制该文件在运行 CLI 机器上的路径。
  3. 在 Apifox 的测试场景内,请求上传文件接口的步骤详情中,点击“批量编辑”按钮。

  1. 将运行 CLI 机器上的文件路径替换至到 file 字段的参数值。

配置完成后,该文件就可以通过 CLI 正确发送至 Apifox。如果你想要重新在本地运行该测试场景,需要将参数值中的文件路径修改为该文件在本机上的路径。

3. 如何将本地 CLI 测试报告上传至云端?

在 CLI 命令行末尾处添加 --upload-report 参数,参考代码:

apifox run https://api.apifox.com/api/v1/projects/2689726/api-test/ci-config/364654/detail\?token\=******* -r html,cli --upload-report

在“测试报告”中的“团队报告”一栏中进行查看。由 CLI 上传的测试报告,测试人一栏中将显示为空。

4. 如何在 CLI 中引用外部脚本 / 程序?

你可以在运行 Apifox CLI 命令时在末尾添加外部脚本 / 程序的路径。例如在下列命令行中,指定 CLI 引用位于 ./scripts 路径下的程序。若未指定层级关系,默认值为当前 CLI 的执行目录。

--external-program-path ./scripts
  • 1. 本地路径

为了避免本地脚本出现管理混乱的情况,建议将所有脚本文件分门别类进行整理,并统一放置于特定目录,再在 CLI 中指定对应的本地路径。

  • 2. 云端代码仓库

你也可以将脚本文件托管在云端的代码仓库中,然后在 CI/CD 工作流设置拉取命令,将外部脚本拉取至本地。最后在 CLI 中填写外部脚本的实际路径。