如何在 CircleCI 中运行 Apifox CLI API 测试

要在 CircleCI 中运行 Apifox CLI API 测试，请添加一个 .circleci/config.yml 文件，该文件使用 cimg/node Docker 执行器，通过 npm 安装 apifox-cli，并配合你的访问令牌、测试场景 ID 以及环境 ID 运行 apifox run。将 Token 和 ID 存储为 CircleCI 环境变量，然后使用 store_test_results 和 store_artifacts 发布 JUnit 和 HTML 报告。本指南将逐步讲解每个部分，以便你可以直接复制、粘贴并运行。

本文旨在介绍如何运行测试，而不是如何选择 CI 平台。如果你仍在纠结于工具的选择，CircleCI 与 Jenkins 的对比涵盖了这方面的内容。在这里，我们假设你已经选择了 CircleCI，并希望在每次代码推送时都运行你的 API 测试套件。

什么是 CircleCI 及其工作原理

CircleCI 是一种基于云端的持续集成与交付服务。它会监控你的 Git 仓库，当你推送提交时，它会运行你定义的构建、测试和部署步骤。你可以在单个 YAML 文件中描述这些步骤，因此你的流水线可以与代码一起保存在版本控制中。

一切都始于仓库根目录下的 .circleci/config.yml 文件。CircleCI 会在每次推送时读取此文件并将其转化为流水线。当前的配置格式版本为 2.1，它在 2.0 基础引擎之上添加了可重用的构建块，如 orb、命令和 parameter。

CircleCI 的配置包含三个核心概念：

Job 是工作单元。每个 Job 会运行一系列步骤，例如检出代码、安装依赖或运行测试命令。
Executor 定义了 Job 运行的位置。Docker 执行器在你选择的容器镜像（例如针对 Node.js 项目的 cimg/node）中运行你的步骤。
Workflow 编排 Job。Workflow 决定运行哪些 Job、以何种顺序运行，以及它们是并行运行还是顺序运行。

这种分离对 API 测试非常重要。你可以定义一个 Job 来安装 Apifox CLI 并运行你的测试场景，然后定义一个 Workflow 来在特定的分支上触发它。

为什么要在 CircleCI 中运行 API 测试

在 CI 中运行 API 测试套件可以在接口变更破坏生产环境之前捕获问题。数据模型的更改、字段重命名或损坏的 auth 流程会直接导致构建失败（显示为红色），而不是变成用户的客服工单。

Apifox CLI 正是为此而设计的。你可以在 Apifox 应用中设计和调试测试场景，然后通过一条命令在 CI 中以无头（headless）模式运行同一个测试场景。无需在代码中重写断言，也无需维护独立的测试环境。

如果你想更全面地了解自动化检查如何融入流水线，阅读《API 测试的 12 个 CI/CD 最佳实践》指南会是一个不错的选择。

前提条件

在编写配置之前，请在 Apifox 应用中准备好以下内容：

一个 访问令牌。在你的 Apifox 账户设置中生成它。这用于在无头（headless）环境中对 CLI 进行身份验证。Apifox CLI 身份验证指南详细介绍了 Token 的创建和 CI 密钥的处理。
一个 测试场景 ID。打开你想要运行的测试场景，并从 URL 或场景设置中复制其 ID。
一个 环境 ID。这告诉 CLI 要使用哪个前置 URL 和变量，例如 staging（测试环境）或 production（生产环境）。

你还需要一个已连接到你的 Git 提供商的 CircleCI 账户，并在 CircleCI 控制台中启用了该项目。

将密钥存储为环境变量

切勿将你的访问令牌硬编码在 config.yml 中。由于该文件会被提交到 Git，因此在其中放置 Token 会导致其泄露。

CircleCI 提供了两个安全的选项：

项目环境变量。在 CircleCI UI 中，打开 Project Settings（项目设置），然后打开 Environment Variables（环境变量），并添加每个值。它们会被加密，并作为 $VARS 暴露给任务。
Contexts（上下文）。Context 是一组在项目之间共享的命名环境变量。你在 Organization Settings（组织设置）下的 Contexts 中创建它，并在工作流中引用它。当多个代码仓库共享同一个 Apifox Token 时，Contexts 非常有用。

在本指南中，请添加三个变量：APIFOX_ACCESS_TOKEN、APIFOX_TEST_SCENARIO_ID 和 APIFOX_ENVIRONMENT_ID。CLI 会在运行时读取它们，你的代码仓库中不会保留任何敏感信息。

完整的 config.yml

以下是一个完整的、可直接复制粘贴的配置。将其放置在 .circleci/config.yml，设置好这三个环境变量，然后推送到仓库即可。

version: 2.1

jobs:
  api-tests:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run:
          name: Install Apifox CLI
          command: npm install -g apifox-cli
      - run:
          name: Run Apifox API tests
          command: |
            apifox run \
              --access-token $APIFOX_ACCESS_TOKEN \
              -t $APIFOX_TEST_SCENARIO_ID \
              -e $APIFOX_ENVIRONMENT_ID \
              -r cli,junit,html \
              --out-dir ./reports
      - store_test_results:
          path: ./reports
      - store_artifacts:
          path: ./reports

workflows:
  test-api:
    jobs:
      - api-tests

下面让我们逐一解析每个部分的作用。

执行器 (Executor)

docker:
  - image: cimg/node:20.11

cimg/node 是 CircleCI 为 Node.js 提供的便捷镜像。它预装了 Node、npm 和常用的构建工具，因此无需额外配置即可直接运行 npm install -g apifox-cli。:20.11 标签固定了 Node 版本，你可以将其固定为你们团队所规范的任何版本。

步骤 (Steps)

checkout 会将你的代码仓库拉取到任务的工作目录中。第一个 run 步骤会在全局安装 CLI。第二个 run 步骤则会执行你的测试。

仔细看一下测试命令：

apifox run \
  --access-token $APIFOX_ACCESS_TOKEN \
  -t $APIFOX_TEST_SCENARIO_ID \
  -e $APIFOX_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports

每个参数（flag）都承担着特定的任务：

--access-token 用于验证运行。它没有简写形式。
-t 通过 ID 选择测试场景。
-e 选择环境。此标志是必需的；CLI 需要知道要使用哪个前置 URL 和哪些变量。
-r 设置报告生成器（reporters）。在这里你请求了三个：cli 在构建日志中打印实时结果，junit 写入机器可读的 XML，html 写入可浏览的报告。
--out-dir 告诉 CLI 在何处写入报告文件。

发布报告

- store_test_results:
    path: ./reports
- store_artifacts:
    path: ./reports

store_test_results 指向 ./reports 中的 CircleCI JUnit XML。CircleCI 会解析它并在构建上显示一个 “Tests” 标签页，因此失败的测试将按名称列出，并附带耗时数据。这就是将一堆日志文本转化为结构化的通过/失败视图的关键所在。

store_artifacts 会将相同的目录上传为可下载文件，包括 HTML 报告。构建完成后，你可以在浏览器中打开 “Artifacts” 标签页并查看渲染后的报告。Apifox CLI 测试报告指南更深入地解释了 CLI、HTML 和 JSON 格式。

工作流

workflows:
  test-api:
    jobs:
      - api-tests

此工作流在每次推送（push）时运行 api-tests 任务。你可以添加过滤器（filters）将其限制在特定分支，或添加在其之前或之后运行的其他任务。对于单个测试任务，这个最简的代码块就足够了。

仅在 main 分支上运行测试

你可能不希望在每个功能分支上都运行完整的 API 测试。可以向工作流添加分支过滤器：

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop

现在，该任务仅在推送至 main 和 develop 分支时运行。其他分支会跳过它，从而让你把宝贵的构建时长集中在要发布的分支上。

使用 Context 代替项目变量

如果多个代码仓库共享一个 Apifox Token，使用 Context 可以将其保存在一个地方。在“组织设置”（Organization Settings）中创建 Context，并在其中添加你的变量，然后进行引用：

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apifox-secrets

现在，该任务将从 apifox-secrets Context 中读取 APIFOX_ACCESS_TOKEN 及其他内容。只需轮换一次 Token，每个项目都会自动获取新值。

数据驱动运行及其他选项

CLI 拥有的标志（flag）比本指南中介绍的要多。其中有两个在 CI 中非常值得了解。

你可以使用 -d 和 -n 跨多行测试数据重复运行一个场景：

apifox run \
  --access-token $APIFOX_ACCESS_TOKEN \
  -t $APIFOX_TEST_SCENARIO_ID \
  -e $APIFOX_ENVIRONMENT_ID \
  -d ./data/users.csv \
  -r cli,junit \
  --out-dir ./reports

-d 标志接受 CSV 或 JSON 文件路径，或者数字形式的已存数据集 ID，并针对每行数据运行一次场景。数据驱动测试指南详细介绍了如何构建这些文件。

您还可以使用 --on-error 控制运行在遇到失败时的处理方式，该参数支持 continue、end 或 ignore。对于使用 Apifox 分支的项目，可以使用 --project <id> --branch <name> 来指定特定分支。要将报告概览推送到 Apifox 云端，只需直接添加 --upload-report 参数。

这如何契合 Apifox 工作流

Apifox CLI 的核心在于您无需编写或维护测试代码。您只需在命令行或可视化测试构建器中构建测试场景，对状态码和响应 body 设置断言，然后保存即可。接着，CI 会运行这同一个测试场景。

由于测试场景保存在您的 Apifox 项目中，您的团队可以在同一个地方编辑测试。CI 配置几乎不需要修改，它只需调用 apifox run。当有人在应用中添加断言时，下一次 CircleCI 构建会自动获取该更改，而无需修改 YAML 文件。

这保持了清晰的职责分离。Apifox 负责测试什么，CircleCI 负责何时何地运行测试。如果您想针对此类工作将 CircleCI 与其他 runner 进行对比，这篇针对 API 团队的持续集成工具汇总为您梳理了各自的权衡取舍。

准备好在每次推送时运行您的 API 测试套件了吗？下载 Apifox，构建一个测试场景，并将上述配置放入您的仓库中。

button

常见问题解答

什么是 CircleCI？

CircleCI 是一个云端持续集成与持续交付平台。它连接到您的 Git 仓库，读取 .circleci/config.yml 文件，并在您每次推送代码时自动运行构建、测试和部署步骤。这样您就无需在自己的机器上手动执行这些步骤。

CircleCI 是用来做什么的？

团队使用 CircleCI 来实现测试和部署的自动化。常见的任务包括编译代码、运行单元测试和集成测试、校验 API 契约、构建 Docker 镜像，以及将发布版本交付到预发布或生产环境。在本指南中，该任务会在每次推送时运行 Apifox CLI API 测试。

CircleCI 是免费的吗？

CircleCI 提供了免费方案，其中包含每月固定的构建额度，这对于小型项目和个人仓库来说已经足够了。需要更多并发、更长构建时长或更强机器配置的大型团队则需要升级到 Performance（性能）和 Scale（规模）付费计划。请查看 CircleCI 的当前定价页面以了解具体的额度限制。

CircleCI 是开源的吗？

不是，CircleCI 是一款商业托管产品，并非开源软件。您可以通过 YAML 文件对其进行配置，并在 CircleCI 的基础设施或自托管 runner 上运行它。如果您需要一个完全开源的 CI 服务器，Jenkins 是常见的替代方案，CircleCI 与 Jenkins 的对比中对此进行了讨论。

CircleCI 是如何工作的？

当您推送 commit 时，CircleCI 会检测到更改，读取 .circleci/config.yml，并启动您定义的执行器，例如 cimg/node Docker 容器。它会按顺序运行任务中的每个步骤，然后将结果报告回您的 Git 提供商。工作流（Workflows）可以让您串联和并行运行任务。若想从更宏观的视角了解这如何融入交付流水线，请参阅《什么是 CI/CD》指南。