# Apifox CLI 命令行运行

Apifox CLI 主要用来以命令行方式运行 Apifox 的 `测试场景`。

## 开始

Apifox CLI 依赖于 Node.js >= v10。使用前请先[安装 Node.js](https://nodejs.org/en/download/package-manager/).

### 安装

使用以下命令安装 Apifox CLI

```console
$ npm install -g apifox-cli
```

### 导出数据

在 Apifox 的`测试场景`导出`Apifox CLI`格式数据。

:::tip 注意

- Apifox 版本号大于等于 `1.0.25` 才支持导出`Apifox CLI`格式数据。
- 目前仅支持导出数据后离线运行，后续[Apifox 开放 API](../../api/)发布后，可以直接运行在线实时数据。
  :::

### 运行测试场景

```console
$ apifox run examples/sample.apifox-cli.json -r cli,html
```

运行完成后测试报告会保存在当前目录下的`apifox-reports`目录里。

- 如果想要自定义报告，可以通过 `-r cli,json` 获取 json 格式报告的结果集来定制自己想要的报告

## 命令选项

### `apifox [options]`

- `-h`, `--help`<br />
  使用帮助

- `-v`, `--version`<br />
  显示版本号

### `apifox run <file-source> [options]`

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

更多选项：

```
  --access-token <accessToken>          设置鉴权令牌，通过此令牌结合 -t/-f 命令来指定某个测试场景/测试场景目录运行
  -t, --test-scenario <testScenarioId>  指定测试场景 ID，通过 ID 运行相应的测试场景
  -f, --test-scenario-folder <folderId> 指定测试场景目录 ID，通过目录 ID 运行相应的测试场景
  -r, --reporters [reporters]           指定测试报告类型, 支持 cli, html, json, junit (default: ["cli"])
  --out-dir <outDir>                    输出测试报告目录，默认为当前目录下的 ./apifox-reports (default: "./apifox-reports")
  --out-file <outFile>                  输出测试报告文件名，不需要添加后缀，默认格式为 apifox-report-{当前时间戳}-0 (default:
                                        "apifox-report-2022-10-25-15-03-08-247-0")
  -e, --environment                     指定运行环境，本次所有测试场景使用此环境运行
  --variables                           指定包含环境/全局变量的文件的路径。如未指定此选项，则环境/全局变量默认将使用远程值。
  -n, --iteration-count <n>             设置循环次数
  -d, --iteration-data <path|testDataId>           设置用例循环的数据 (JSON 或 CSV)
  --on-error <value>                  设置错误处理方式 (ignore|continue|end)
  --env-var <key=value>                 设置环境变量，使用 key=value 格式。可以设置多个环境变量。例如：--env-var "user=123" --env-var "password=123"
  --global-var <key=value>              设置全局变量，使用 key=value 格式。可以设置多个全局变量。例如：--global-var "user=123" --global-var "password=123"
  --notification <targetIds>            运行完成后，通知指定对象。使用英文逗号添加多个通知对象 ID
  --notification-failed-event <targetIds>           运行完成后，仅失败时通知指定对象。使用英文逗号添加多个通知对象 ID
  --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)
  --upload-report                       将本次测试报告总览上传至云端，在 App 中即可查看此测试报告
  -b, --bigint                          兼容 bigint (default: false)
  --verbose                             显示所有接口请求的详细信息
  --lang <language>                     设置 CLI 的语言 (zh|en) (default: "zh")
  -h, --help                            display help for command
```

### SSL

#### 客户端证书

Apifox CLI 支持传入客户端证书

#### 使用单个 SSL 客户端证书

- `--ssl-client-cert`<br/>
  公共客户端证书文件的路径

- `--ssl-client-key`<br/>
  私有客户端密钥的路径（可选）

- `--ssl-client-passphrase`<br/>
  用于保护私有客户端密钥的密码（可选）

#### 使用 SSL 客户端证书 配置文件（支持多个证书）

- `--ssl-client-cert-list`<br/>
  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 没有匹配项，这些选项将用作后备选项。

## 升级版本

使用以下命令升级 Apifox CLI

```console
$ npm install apifox-cli@latest -g
```

###