#用 Agent 做全流程接口自动化测试

我们在 Apifox 里维护 HiFox 的接口定义、接口用例和测试场景。需求交付得快了，测试同学要反复核对一件事，这次提交究竟改了哪些接口，已有用例还能不能验证新行为。

我们是一个用 HiFox 协作的产研团队。HiFox 的任务是一张工作单，需求说明、讨论和执行结果都放在上面；Agent 是能读取任务、分析代码、调用工具完成工作的 AI 队友。我们让维护接口测试的 Agent 从提测开始接手，针对测试环境的版本补定义、补场景、跑测试，再把结果写回原需求。上线以后，它才把对应的 Apifox 分支合回主干。

#我们现在怎样使用 HiFox 维护接口测试

#需求转入待测试，自动化先做服务端和接口分析

需求负责人把任务推进到“待测试”，HiFox 的自动化就会启动接口用例 Agent。自动化是按事件或时间派发工作的规则，这里的事件是任务状态变化，分析对象就是触发它的这条需求。

Agent 先读需求正文、评论和关联提交，确认代码落在哪个分支、面向哪个环境。有服务端改动，就沿着变更文件找到处理函数，再找到对应路由，列出新增、修改或废弃的接口。接着读 Apifox 的接口定义和场景步骤，判断已有用例是否测到了新行为。

分析完，Agent 会在原需求下留一条“接口测试分析”评论，先说明是否需要补用例。我们把结论分成四种情况：

• 不用补，说明没有接口变化，或现有用例为什么够用。
• 要补，逐项写场景、操作顺序和补它的原因。
• 要补，但接口测不到，说明缺少什么条件、哪些要转人工验证。
• 拿不准，把需要确认的问题写具体。

评论还会说明改了什么、接口有哪些变化、已有用例测到了哪些内容。没有新增接口，也可能需要验证新的鉴权或返回内容。这一步只读 Apifox，不写接口、用例和场景，修改留到版本任务里集中做。

#测试环境打包完成，Agent 自动创建版本任务并接手

测试环境打包成功后，Agent 才开始补用例和跑测试。我们通过飞书接收打包播报，如果测试环境有新的打包成功记录，或某条记录的状态从打包中变为成功，就利用连接了飞书 CLI 的 Agent 去通知接口用例 Agent（使用飞书 CLI 以用户身份触发的原因是飞书不支持机器人 @ 机器人）。

收到通知，Agent 会在负责版本增量维护的父任务下，创建一张“接口测试用例生成”版本任务，并指派给接口用例 Agent。需要跟进的同学会被加为关注人。版本任务就是这次打包对应的接口测试工作单，正文写明版本标识、代码分支、Apifox 项目和环境、测试分支策略及执行计划。

任务建好后，Agent 会在打包播报的话题里回复链接。版本任务指派给接口用例 Agent 后，后面的用例生成、跑测和报告都在任务里完成。任务从“待开始”进入“进行中”，进度和结果都能在这里查到。

#Agent 在版本任务里确定需求范围和 Apifox 分支

进入任务后，Agent 先找出这个版本包含哪些需求，再读取这些需求上的接口分析，筛出要补用例的部分。

Agent 把需求链接、接口分析结论和是否需要补用例整理成一张依据表，放进版本任务正文。后面的补测和结果回写，都按这张表逐条进行。

确定范围后，Agent 按团队约定创建本版本的 Apifox 测试分支，并把来源分支和本次版本记进任务。后面的生成、执行和报告都使用这个分支，尚未上线的测试改动不直接写入主干。

#根据分析补接口、写场景，再把场景加入套件

Agent 按依据表里的检查项修改 Apifox。缺少接口定义，先根据服务端路由补录；已有定义和实际请求、响应不一致，先修正定义，再补用例。

我们的一次执行就修过这样的错误，响应实际返回对象，Apifox 却写成字符串，引用它的场景一直报结构不一致。定义改完，引用场景也要重新保存，避免继续使用旧快照。

写入前，Agent 先读 Apifox 官方技能文档，查询对应实体的数据结构，校验提交内容，写完再回读。新资源直接在版本分支创建；修改已有接口、场景或套件，先从来源分支选入，保留资源标识后再改。

需要登录、创建数据、通过其他接口读取结果和清理数据的检查，我们会组织成测试场景。每个场景都引用公共数据准备场景 Setup，不用各写一份登录流程。我们还会把新场景加入合适的测试套件，安排它和其他场景一起运行。只把场景建出来，回归不一定跑得到它。

这次任务既有新建场景，也有修改原场景，交付清单会分别列出，不把所有修改都算成新增用例。

#跑完测试，在版本任务中交付总报告

Agent 先跑全量主流程回归，再逐个跑本版本新增或修改的场景。跨场景串跑时带上 --carry-runtime-variables，把前面取得的登录态和数据变量传给后续场景；详细报告保留本次分支信息，避免点开后看成主干分支的结果。

测试失败时，Agent 会先读代码和实际响应，区分环境不可用、产品问题、用例或定义过期，以及确实需要人确认的行为变化。需要确认时，Agent 先说明改动意图、影响范围和兼容风险，再请人确认，不直接丢一句“请确认”。当前这条接口流程只报告问题，不自动创建 Bug。

版本任务里会留下这些内容：

• 本次版本涉及的需求，以及各条需求要补什么。
• 补录或修正的接口、新建和修改的场景、套件更新情况。
• 全量回归与本版场景各自的结果、详细报告入口。
• 失败归因、未执行项、待确认问题和分支去向。

总报告发在版本任务的评论里，这次还把详细结果补到了任务正文。本版场景和全量回归的结果分开列，避免把本版通过看成全部通过。

生成和跑测结束后，版本任务仍保持“进行中”，分支留待上线。遇到需要人确认的问题时，Agent 才会请人复核，单纯等发版不用反复找人确认。执行记录保留 Agent 的运行过程，需要追查工具调用或报错时再打开看。

#将本需求的接口测试结果写回原需求评论

总报告发完，Agent 还会把测试结果逐条写回表中需要补用例的需求评论里。研发和测试同学打开自己的需求，就能看到这次接口层改了什么，不用再去群里找版本任务。

评论会列出本需求涉及的接口、补充或修改的场景、通过失败及跳过情况，并附接口详情、场景详情和测试报告链接。链接指向本次 Apifox 分支，方便直接检查定义和步骤。

下面是一次需求收到的结果摘要。接口返回符合预期，也不代表 Agent 已经实际执行了后续工作，所以评论里会写清哪些已经测过、哪些还没测。场景运行通过，也不能把没有进入的正向分支算成已经测过。

#版本上线后，自动合并对应的测试分支

版本上线后，发布通知触发接口用例 Agent，确认本次上线范围，将对应的 Apifox 测试分支合回主干。具体的触发条件、授权方式和目标分支，按团队自己的发版流程配置。

这里合并的是 Apifox 里的接口定义、场景和套件，不涉及代码仓库。尚未上线的改动仍保留在测试分支。

合并后，Agent 核对写入结果，把合并报告留在版本任务里，再归档已发布的分支，将对应任务转为“已完成”。

#接入这条流程前，要先想清楚的事

#新系统没有接口库，先交给 Agent 做基建

上面的版本流程负责增量维护，前提是 Apifox 已经有可执行的测试基线。HiFox 也是从零建立接口和场景，先做好公共准备与少量业务流程，再按域补齐覆盖，之后才持续跟着版本更新。

如果你的系统还没有接口和用例，可以先在 HiFox 建一张基建任务。你提供代码仓库、目标服务地址、测试账号和 Apifox 权限，并明确允许创建、修改和清理的范围。Agent 负责准备项目目录和环境变量，补齐接口定义，再搭好 Setup、业务场景和套件，提交覆盖对账和测试报告，不要求你先手工搭一遍。

我们当时先让 Agent 比对服务端路由与 Apifox 接口，补录缺失定义，再写覆盖对账脚本，对照全部接口和场景步骤，核对哪些接口已有场景调用、哪些还没有。

接着按业务域拆子任务，先主流程，再补参数边界、异常和权限；数据结构有变化时补兼容验证。每个子任务都交接口修正、场景和增量报告，结果回到基建父任务。哪些依赖第三方凭据、长连接或专门运行环境，也单独列明。

验收不能只数场景名称。我们会检查新场景是否有完整步骤、是否加入套件，以及清理后能否独立跑通，再连续运行检查残留。覆盖对账只能说明接口被哪个步骤调用过，不能替代业务断言，计划中的覆盖目标也要和实际完成情况分开。

#Setup 要能反复准备数据，也要能独立运行

Setup 是场景共用的数据准备。我们把登录、获取组织、获取空间和读取后续需要的状态等步骤放在这里；没有数据才创建，已经存在就复用。业务场景拿到运行时变量后再继续，不硬编码某次运行生成的对象标识。

每个业务场景开头引用 Setup，保证单独运行也能从干净账号开始。跑套件时则把 Setup 显式放在首位，再带上 --carry-runtime-variables。套件执行时场景引用会跳过，不能以为每个场景都引用了它，套件里就不用安排。

登录取得的令牌通过变量交给步骤的 Bearer 鉴权配置，账号和凭据由执行环境提供，不在任务、脚本或固定请求头里写死。业务场景结束后逆序清理自己创建的数据，账号级全量清理单独放，不混进日常回归。

#分支规则按团队的发版流程配置

分支的 base，就是创建新分支时选用的来源分支。创建分支的来源、合并时机和目标分支，都按团队现有的发版流程配置，不必照搬我们的选择。

把这些约定写进 Agent 指令，在版本任务里记录实际使用的分支。Agent 生成用例、跑测和上线合并时，都使用任务中约定的分支。

#Agent 指令参考

测小口的 Agent 指令见：测小口 - 接口用例维护。

配置到自己团队前，替换项目、环境、仓库和角色约定，并写清分支策略与合并授权。保留提测只读分析、版本分支写入、报告回写和上线合并各自的边界，真实凭据通过执行环境提供。Agent 需要在工具 & 知识库中添加连接，绑定上 Apifox CLI。