CircleCI中运行Apifox CLI进行API自动化测试

时间：2026-08-14 22:48

如果你想在 CircleCI 中执行 Apifox CLI API 测试，需要新增一个 circleci config yml 文件。该配置通常使用 cimg node Docker 执行器，通过 npm 安装 apifox-cli，再结合访问令牌、测试场景 ID 和环境 ID 来运行 apifo

如果你想在 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 测试报告。本文会按步骤说明每一部分，方便你直接复制、粘贴并快速运行。

这篇文章重点讲解的是如何在 CircleCI 里运行 API 自动化测试，而不是帮你挑选 CI 平台。如果你还在比较工具选型，可以参考 CircleCI 与 Jenkins 的对比内容。这里默认你已经决定使用 CircleCI，并希望在每次代码提交或推送后自动执行 API 测试套件。

什么是 CircleCI 及其工作原理

CircleCI 是一款基于云的持续集成与持续交付（CI/CD）服务。它会持续监控你的 Git 仓库，当检测到新的代码提交后，自动执行你定义好的构建、测试和部署流程。你可以把这些流程写在一个 YAML 配置文件中，让流水线配置与项目代码一起纳入版本管理。

整个流程的入口通常是仓库根目录下的 .circleci/config.yml 文件。CircleCI 会在每次推送代码时读取这个文件，并据此生成对应的流水线。当前常用的配置版本是 2.1，它在 2.0 引擎基础上增加了 orb、命令和 parameter 等可复用能力。

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

Job 是最基本的执行单元。每个 Job 会按顺序运行一组步骤，例如检出代码、安装依赖、执行 API 测试命令等。
Executor 用来定义 Job 的运行环境。Docker 执行器会在指定的容器镜像中执行任务，比如 Node.js 项目常用的 cimg/node。
Workflow 用于编排多个 Job。它决定要运行哪些 Job、执行顺序如何，以及这些任务是串行还是并行运行。

这种职责划分对 API 测试场景尤其重要。你可以单独定义一个 Job 来安装 Apifox CLI 并运行测试场景，再通过 Workflow 控制它在指定分支或特定时机触发。

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

把 API 测试集成到 CI 流程中，可以在接口变更影响线上环境之前尽早发现问题。无论是数据结构调整、字段名称修改，还是认证流程异常，都能在构建阶段直接暴露出来，让失败以红色构建的形式出现，而不是等用户反馈问题后才排查。

Apifox CLI 正适合这样的自动化测试场景。你可以先在 Apifox 应用中设计、调试并保存测试场景，然后通过一条命令在 CI 环境中以无头（headless）方式运行同样的测试。这样无需额外在代码里重复编写断言，也不必单独维护另一套测试逻辑。

如果你想系统了解 API 自动化检查如何融入持续交付流程，建议进一步阅读《API 测试的 12 个 CI/CD 最佳实践》相关指南。

前提条件

在开始编写 CircleCI 配置前，请先在 Apifox 中准备以下信息：

一个访问令牌。你可以在 Apifox 账户设置里生成它，用于 CLI 在无头（headless）环境中完成身份验证。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（组织设置）下创建 Context，并在 Workflow 中引用它。当多个仓库共用同一个 Apifox Token 时，这种方式特别方便。

在本文示例中，请创建以下三个变量：APIFOX_ACCESS_TOKEN、APIFOX_TEST_SCENARIO_ID 和 APIFOX_ENVIRONMENT_ID。CLI 在执行时会自动读取它们，从而避免在仓库中保存任何敏感数据。

完整的 config.yml

下面是一份完整且可直接使用的配置示例。将其保存到 .circleci/config.yml，设置好上述三个环境变量后，推送到代码仓库即可开始运行。

version: 2.1jobs:api-tests:docker:- image: cimg/node:20.11steps:- checkout- run:name: Install Apifox CLIcommand: npm install -g apifox-cli- run:name: Run Apifox API testscommand: |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: ./reportsworkflows: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 步骤负责全局安装 Apifox CLI，第二个 run 步骤则真正执行 API 测试。

来看一下核心测试命令：

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 指定报告文件的输出目录。

发布报告

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

store_test_results 会读取 ./reports 目录中的 JUnit XML 报告。CircleCI 解析后，会在构建详情中展示 “Tests” 标签页，这样失败的测试用例会按名称列出，并附带执行耗时，方便定位问题。这一步能把普通日志转换成更清晰的结构化测试结果视图。

store_artifacts 会把同一目录上传为构建产物，包括 HTML 报告文件。构建完成后，你可以在浏览器中打开 “Artifacts” 标签页，直接查看渲染好的测试报告。关于 CLI、HTML 和 JSON 报告格式的更多说明，可进一步参考 Apifox CLI 测试报告指南。

工作流

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

这个 Workflow 会在每次代码推送时触发 api-tests 任务。你可以继续添加 filters（过滤器）限制执行分支，也可以在它前后接入其他 Job。对于只需要运行一组 API 自动化测试的场景来说，这个最小化配置已经足够实用。

仅在 main 分支上运行测试

很多团队并不希望每个功能分支都触发完整的 API 测试，因为这会消耗较多构建资源。此时可以为 Workflow 添加分支过滤器：

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，只需更新一次，所有引用该 Context 的项目都会同步获得最新值。

数据驱动运行及其他选项

Apifox CLI 提供的参数远不止本文介绍的这些，其中有几个选项在 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，CLI 会根据每一行数据分别运行一次测试场景。关于如何设计和组织这些数据文件，可以参考数据驱动测试指南。

如果你希望更细致地控制失败后的处理逻辑，可以使用 --on-error，它支持 continue、end 和 ignore 三种模式。对于使用 Apifox 分支能力的项目，还可以结合 --project --branch 来明确指定运行的项目分支。如果你希望把测试报告摘要同步上传到 Apifox 云端，则可以追加 --upload-report 参数。

这如何契合 Apifox 工作流

Apifox CLI 的一个核心优势是：你无需手动编写或长期维护大量测试代码。你只需要在命令行或可视化测试构建器中创建测试场景，为状态码和响应 body 配置断言并保存，之后就能在 CI 中重复执行同一套测试。

由于这些测试场景都保存在 Apifox 项目中，团队成员可以在统一位置维护测试内容，而 CircleCI 配置本身通常不需要频繁改动，它只需持续调用 apifox run。一旦有人在 Apifox 中新增或调整断言，下一次 CircleCI 构建就会自动使用最新版本的测试场景，而不必再次修改 YAML。

这种方式让职责边界更加清晰：Apifox 负责定义测试内容，CircleCI 负责决定测试何时运行、在哪运行。如果你还想把 CircleCI 与其他 CI runner 进行对比，可以参考面向 API 团队的持续集成工具整理文章，了解不同方案的优缺点。

如果你已经准备好在每次推送时自动运行 API 测试套件，不妨现在就下载 Apifox，创建一个测试场景，并把上面的配置加入你的仓库中。

button

常见问题解答

什么是 CircleCI？

CircleCI 是一个云端持续集成和持续交付平台。它连接你的 Git 仓库，读取 .circleci/config.yml 配置文件，并在每次代码推送后自动执行构建、测试和部署流程，从而减少本地手动操作，提高交付效率。

CircleCI 是用来做什么的？

开发团队通常使用 CircleCI 来实现软件开发流程自动化。常见用途包括编译代码、运行单元测试与集成测试、校验 API 契约、构建 Docker 镜像，以及将应用发布到测试环境或生产环境。在本文场景中，CircleCI 主要用于自动执行 Apifox CLI API 测试。

CircleCI 是免费的吗？

CircleCI 提供免费版本，通常包含每月一定额度的构建资源，对于个人项目和小型仓库往往已经够用。如果团队需要更高并发、更长执行时长或更强机器规格，则通常需要升级到 Performance（性能）或 Scale（规模）等付费方案。具体限制和配额建议以 CircleCI 官方定价页面为准。

CircleCI 是开源的吗？

不是。CircleCI 属于商业化托管产品，并不是开源 CI 软件。你可以通过 YAML 对它进行配置，也可以在 CircleCI 官方基础设施或自托管 runner 上运行工作流。如果你需要完全开源的 CI 工具，Jenkins 是较常见的替代方案，相关差异可参考 CircleCI 与 Jenkins 的对比分析。

CircleCI 是如何工作的？

当你推送新的 commit 后，CircleCI 会检测到仓库变更，读取 .circleci/config.yml 文件，并启动你指定的执行环境，例如 cimg/node Docker 容器。随后它会依次执行 Job 中的各个步骤，并把运行结果反馈给 Git 提供商。通过 Workflow，你还可以把多个任务串联起来或并行执行。若想从更完整的视角理解它在交付流程中的角色，可以进一步阅读《什么是 CI/CD》指南。