如何在 Drone CI 中运行 Apifox CLI API 测试

您可以通过添加一个 Docker 流水线（pipeline）步骤来在 Drone CI 中运行 Apifox CLI API 测试，该步骤使用 Node 镜像、安装 apifox-cli，并针对某个环境运行 apifox run。您的 Apifox 访问令牌存储在 Drone 的凭据（secret）中，并通过 from_secret 进行注入。本指南将逐步介绍可直接复制使用的 .drone.yml、凭据处理、分支网关限制，以及如何在 Drone 没有内置制品库的情况下展示测试报告。

什么是 Drone CI 及其工作原理

Drone 是一个开源的容器原生 CI/CD 平台，现在是 Harness 的一部分。CI/CD 代表持续集成（continuous integration）和持续交付（continuous delivery），即在每次代码变更时自动进行构建和测试的实践。如果您想复习这一概念本身，请参阅“什么是 CI/CD”。

Drone 的核心特质非常简单：每个流水线步骤都在其独立的 Docker 容器中运行。这里没有预装了大量工具的共享构建代理（build agent）。您为每个步骤选择一个镜像，Drone 就会在其中运行您的命令。这使得构建具有可复现性且易于理解。

您可以在仓库根目录下的 .drone.yml 文件中定义流水线。一个 Docker 流水线包含三个顶级键：kind、type 和 name。具体工作在 steps 下进行，每个步骤需要声明 name、image 以及 commands 列表。

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

Drone 将 commands 作为 Shell 脚本运行，并使用 set -e 和 set -x，因此构建会在遇到第一个非零退出状态码时快速失败，并在运行每个命令之前将其回显。这些命令会覆盖容器的 entrypoint，且工作目录为您的仓库根目录。

为什么要在容器步骤中运行 API 测试

API 测试可以防止契约漂移。后端更改如果悄悄改变了响应的结构或状态码，可能会破坏下游的所有客户端。在每次推送时运行这些测试，可以在发布之前捕获到回归问题。

Apifox 非常契合这一模式。您可以在 Apifox 应用中通过可视化界面构建和维护您的测试，然后使用 Apifox CLI 从命令行运行完全相同的测试场景。无需重写脚本，也无需独立的测试套件。如需了解将 API 测试引入流水线的更广泛指南，请阅读“API 测试的 CI/CD 最佳实践”。

Apifox 是一个集设计、调试、测试、mock 和文档于一体的 API 平台。其 CLI 工具可以将您保存的测试场景转化为单个可重复执行的命令，这正是 Drone 步骤所需要的。

您将运行的 Apifox CLI 命令

使用 npm 安装 CLI，然后运行测试场景。在 CI 中，您可以使用参数（flag）将运行指向保存的场景，因此无需管理本地的集合文件。

npm install -g apifox-cli
apifox run --access-token $APIFOX_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

以下是每个参数的作用：

--access-token 传入您的 Apifox 访问令牌。该参数没有简写形式。
-t 是您想要运行的测试场景 ID。
-e 是环境 ID，且为必填项。它决定了运行过程中使用哪个前置 URL 和变量。
-r 列出报告器。有效值为 cli、html、json 和 junit。

您可以根据需要添加更多参数：

-n 或 --iteration-count 用于指定重复运行的次数。
-d 或 --iteration-data 接收 CSV 或 JSON 文件路径，或者已存储的数据集数字 ID，用于数据驱动测试。
--out-dir 设置报告的输出目录。
--upload-report 将报告概览上传到 Apifox 云端，您可以在 App 中查看。此参数可作为独立标记直接使用。
--on-error 控制出错时的行为，可选值包括 continue（继续）、end（结束）或 ignore（忽略）。
--project <id> 和 --branch <name> 用于指定特定的项目分支。

要完整了解该命令及其选项，请参阅 Apifox CLI 完整指南以及在命令行测试 REST API 的教程。

适用于 Apifox 测试的完整 .drone.yml 配置

以下是一个可运行的流水线示例。它使用 Node 镜像，安装 CLI，并运行您的测试场景。访问令牌来自 Drone Secret，而不是硬编码在配置中。

kind: pipeline
type: docker
name: apifox-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIFOX_ACCESS_TOKEN:
        from_secret: apifox_access_token
    commands:
      - npm install -g apifox-cli
      - apifox run --access-token $APIFOX_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

请将 1234567 替换为您的测试场景 ID，将 89012 替换为您的环境 ID。这两个 ID 均可在 Apifox App 中查看。由于该步骤使用了 cli 报告器，因此完整的通过/失败详细分析将直接输出到 Drone 构建日志中，方便所有构建审查人员查看。

在 Drone CI 中存储 Secret

切勿将 API 访问令牌提交到代码仓库中。Drone 会将 Secret 排除在 YAML 之外，并在运行时进行注入。

您可以在步骤的 environment 模块（或插件的 settings 模块）中通过 from_secret 引用 Secret。写入的值应该是 Secret 的名称，而不是访问令牌本身。

environment:
  APIFOX_ACCESS_TOKEN:
    from_secret: apifox_access_token

创建 Secret 有两种常用方法。第一种是通过 Drone UI：打开您的代码仓库，前往 Settings（设置），然后选择 Secrets，添加一个名为 apifox_access_token 的 Secret，并将其值设置为您的访问令牌。第二种是使用 Drone 命令行工具。

drone secret add \
  --repository your-org/your-repo \
  --name apifox_access_token \
  --data your-apifox-token

请根据您所用版本的 Drone CLI 文档确认准确的 flag 名称，因为 CLI flag 可能会在不同版本之间发生变化。Drone 还支持一种在仓库内加密密钥的变体，其中 `drone encrypt` 会生成一个加密数据块，供您作为单独的 `kind: secret` YAML 文档嵌入。对于大多数团队而言，通过 UI 或 `drone secret add` 添加的仓库密钥更简单，也是推荐的入手选择。

将 Token 保存在 secret 中是适用于任何其他地方的通行准则。有关 CLI 如何处理凭证的更多信息，请参阅 Apifox CLI 身份验证指南。

## 按分支和事件控制运行

Drone 提供了两个用于控制工作何时运行的杠杆：pipeline 级别的 `trigger` 和 step 级别的 `when`。

一个 `trigger` 块决定整个 pipeline 是否运行。所有条件评估必须为真（true），因此下面的示例仅在针对 `main` 分支的 push 和 pull request 时运行。

yaml trigger: branch: - main event: - push - pull_request

一个 `when` 块位于单个 step 内部，仅限制该 step 的运行。当您希望 pipeline 的大部分内容在所有地方都运行，但仅针对特定分支保留更重的测试时，这非常有用。

yaml steps:

name: run-api-tests image: node:20-alpine commands:
- npm install -g apifox-cli
- apifox run --access-token $APIFOXACCESSTOKEN -t 1234567 -e 89012 -r cli when: branch:
  - main event:
  - push

这两个块都支持 glob 模式以及 include/exclude 子键。支持的事件类型包括 `push`、`pull_request`、`tag`、`promote`、`rollback`、`cron` 和 `custom`。

## 在没有制品库的情况下展示测试报告

Drone 没有原生的制品托管功能。这改变了您处理报告的方式，但您有两种整洁的方案可选。

第一种是最简单的：使用 `cli` 报告器，以便将结果打印到构建日志中。对于大多数团队来说，这已经足够了，因为日志中已经显示了哪些断言通过、哪些失败。

第二种选择是生成 HTML 报告并将其上传到持久存储中。Drone 发布了一个官方的 S3 插件 `plugins/s3`，可以将文件上传到 S3 或任何兼容 S3 的存储。使用 `html` 报告器和 `--out-dir` 生成报告，然后添加一个上传步骤。

yaml steps:

name: run-api-tests image: node:20-alpine environment: APIFOXACCESSTOKEN: fromsecret: apifoxaccess_token commands:
- npm install -g apifox-cli
- apifox run --access-token $APIFOXACCESSTOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports
name: upload-report image: plugins/s3 settings: bucket: my-bucket region: us-east-1 source: reports/*/ target: /apifox-reports accesskey: fromsecret: awsaccesskey secretkey: fromsecret: awssecretkey

该插件通过 from_secret 从 secrets 中读取其 AWS 凭证，这与你用于 Apifox Token 的机制相同。source 键是要上传的文件的 glob 匹配模式，而 target 是存储桶中的目标前缀。

如果你想深入了解报告包含的内容以及如何阅读它，请参阅 Apifox CLI 测试报告的详细解析。

添加数据驱动运行

有时，一个测试场景需要针对许多输入行运行：十个用户 ID、十几个 payload、一组边缘情况。CLI 通过 -d 参数来处理此问题，该参数接受 CSV 或 JSON 文件路径，或者已存储的数据集 ID。

commands:
  - npm install -g apifox-cli
  - apifox run --access-token $APIFOX_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

data.csv 中的每一行都会成为一次迭代，列值会绑定到你的测试场景变量中。完整的模式在 Apifox CLI 数据驱动测试中进行了介绍。

与其他 CI 工具的对比

Drone 的模式（在干净的容器中安装 CLI 并运行一条命令）几乎适用于所有 CI 系统。虽然封装语法有所不同，但 Apifox 步骤是相同的。

如果你也在其他地方运行流水线，Apifox 提供了针对 GitHub Actions 和 Azure Pipelines 的相应指南。其核心思想是相同的：你的测试保存在 Apifox 中，而 CI 工具只需触发它们。

关于适用范围的坦率说明：Apifox CLI 运行的是功能测试和契约测试，而不是大规模的压力测试。如果你需要数千个并发虚拟用户来对某个接口进行压力测试，请使用专门的压力测试工具。为了验证你的 API 在每次提交时都能正确运行，在 Drone 步骤中使用 CLI 就能很好地完成这项工作。

可视化构建测试，一键运行

这种令人愉悦的工作流得益于“编写”与“执行”的分离。你可以在 Apifox 中可视化地设计接口并编排测试场景，串联请求、对状态码和响应字段进行断言，并复用环境变量。构建测试套件无需编写任何代码。

然后，CI 会在容器步骤中通过一条 CLI 命令运行相同的套件。当团队成员在 Apifox 应用中更新测试时，下一次 Drone 构建会自动获取最新内容。无需同步第二份测试副本。

免费下载 Apifox 来构建你的第一个测试场景，然后将上面的 .drone.yml 放入你的仓库中，以便在每次推送时运行它。

常见问题

什么是 Drone CI？

Drone 是一个开源的容器原生 CI/CD 平台，现在是 Harness 的一部分。它在各自的 Docker 容器中运行每个流水线步骤，并在 .drone.yml 文件中定义流水线。这保证了构建的可复现性，并避免了传统构建代理中预装工具杂乱蔓延的问题。

Drone CI 是免费的吗？

Drone 核心项目是开源的，并且可以免费自托管。在 Harness 收购之后，Drone 变成了 Harness CI 社区版（Harness CI Community Edition），同时也提供付费的企业版。对于大多数团队来说，自托管的开源版本已经足以运行本指南中所介绍的接口测试。

Drone CI 是开源的吗？

是的。Drone 是最早的容器原生 CI 工具之一，并且目前依然保持开源。Harness 在 2020 年收购它时，承诺保持该项目的开源状态，你现在依然可以自行托管它。

Drone CI 是如何使用的？

团队使用 Drone 在每次 push 或 pull request 时自动构建、测试和交付代码。你只需将 .drone.yml 提交到你的仓库中，Drone 就会读取它并在容器中运行每一个步骤。常见的步骤包括编译代码、运行单元测试、运行接口测试，以及将产物上传到外部存储。

如何在 Drone CI 中存储机密信息？

你可以通过 Drone UI 中对应仓库的 Settings -> Secrets 页面来添加机密信息，或者在 CLI 中使用 drone secret add 命令。然后，你可以使用 from_secret 在步骤的 environment 或插件的 settings 块中引用每个机密，其值即为该机密的名称。Token 本身永远不会出现在你的 YAML 中。