本文通过一个真实案例，详细拆解API自动化测试的完整流程：某团队刚刚完成“订单退款”的PRD（产品需求文档），代码库中也已备好对应的路由与控制器。接下来，让Agent基于PRD和代码库，自动生成退款功能的API测试并执行校验，以此展示Apifox CLI与SKILL组合的实际落地效果。
场景设定
场景设定清晰明了：团队刚完成“订单退款”的PRD编写，代码库中相应的路由与控制器也已就绪。用户向Agent提出的请求非常直接：“根据PRD和代码库，生成退款功能的API测试，然后运行校验。”
传统方法的局限
如果采用MCP工具处理此类需求，Agent会在多个决策点上陷入反复纠结，难以快速确定路径。以下是典型的困境表现：
| 决策点 | 不确定性 |
|---|---|
| 是先查询项目？还是先创建接口？ | 路径选择不明确 |
| 是先写测试用例？还是先生成Schema？ | 顺序难以判断 |
| 是直接运行测试？还是先回读资源？ | 动作优先级模糊 |
| 每一步该用哪个工具？ | 需在126个工具中逐一搜寻 |
最终，Agent将大量精力耗费在“如何行动”的决策上，而非真正执行核心任务。
CLI + SKILL 路径
相比之下，CLI+SKILL方式通过清晰的执行序列，精准映射了真实的研发流程：
从PRD和代码库生成OpenAPI
↓
导入Apifox
↓
添加单接口测试用例
↓
写入前验证
↓
为业务流生成测试场景
↓
写入前验证
↓
运行自动化测试
接下来，我们将一步步拆解这一过程。
步骤 1：生成 OpenAPI 并导入
Agent读取PRD和代码库后，首先生成OpenAPI规范文件。
PRD关键内容摘录如下：
Order Refund API
POST /api/orders/{orderId}/refund
- Request body: { "reason": string, "amount": number }
- Response: { "refundId": string, "status": string, "processedAt": datetime }
GET /api/orders/{orderId}/refund/{refundId}
- Response: { "refundId": string, "status": string, "amount": number }
Agent据此生成对应的OpenAPI文档：
{
"openapi": "3.0.0",
"paths": {
"/api/orders/{orderId}/refund": {
"post": {
"summary": "Create refund request",
"parameters": [...],
"requestBody": {...},
"responses": {...}
}
},
"/api/orders/{orderId}/refund/{refundId}": {
"get": {
"summary": "Get refund status",
...
}
}
}
}
然后通过CLI命令导入Apifox：
apifox import --project
CLI返回的响应信息：
{
"success": true,
"data": {
"importedEndpoints": ["POST /refund", "GET /refund/{refundId}"],
"endpointIds": ["ep-001", "ep-002"]
},
"agentHints": {
"summary": "OpenAPI imported successfully. 2 endpoints created.",
"nextSteps": [
"List the imported endpoints to confirm structure.",
"Add test cases for each endpoint.",
"Create a test scenario for the complete refund flow."
]
}
}
步骤 2：单接口测试用例
Agent优先处理“退款接口”的测试用例。
首先读取接口结构：
apifox endpoint get ep-001 --project
CLI返回的接口详情：
{
"id": "ep-001",
"method": "POST",
"path": "/api/orders/{orderId}/refund",
"requestBody": {
"schema": {
"type": "object",
"properties": {
"reason": { "type": "string" },
"amount": { "type": "number" }
},
"required": ["reason", "amount"]
}
},
"responses": {
"200": {...}
}
}
Agent基于此生成测试用例：
{
"name": "Create refund - success",
"endpointId": "ep-001",
"request": {
"path": "/api/orders/order-123/refund",
"body": {
"reason": "Customer request",
"amount": 99.99
}
},
"assertions": [
{
"subject": "responseJson.status",
"comparator": "equal",
"target": "processed"
}
]
}
写入前先执行本地验证：
apifox cli-schema validate test-case-create --file ./test-case-create.json
CLI验证结果：
{
"success": true,
"agentHints": {
"summary": "Test case structure is valid.",
"nextSteps": [
"Create the test case in Apifox.",
"Read back the created test case to confirm.",
"Add more assertions if needed."
]
}
}
验证通过后，正式创建测试用例：
apifox test-case create --project
CLI输出：
{
"success": true,
"data": {
"id": "tc-001",
"name": "Create refund - success"
},
"agentHints": {
"summary": "Test case created successfully.",
"nextSteps": [
"Read back test case tc-001 to confirm assertions.",
"Create test case for GET /refund/{refundId}.",
"Build test scenario for complete refund flow."
]
}
}
步骤 3：完整流程的测试场景
根据PRD描述，完整的业务流转顺序应为：
创建订单 → 支付 → 退款 → 查询退款状态
Agent自动生成对应的测试场景：
{
"name": "Order Refund Complete Flow",
"steps": [
{ "type": "case", "caseId": "tc-create-order" },
{ "type": "case", "caseId": "tc-pay" },
{ "type": "case", "caseId": "tc-001" },
{ "type": "case", "caseId": "tc-get-refund" }
]
}
再次执行写入前验证：
apifox cli-schema validate test-scenario-update --file ./scenario-update.json
验证通过后创建场景：
apifox test-scenario create --project
步骤 4：运行校验
测试用例与场景准备就绪后，执行最终校验：
apifox run --project
CLI输出结果：
{
"success": true,
"stats": {
"total": 4,
"passed": 4,
"failed": 0
},
"reportFiles": {
"cli": "./apifox-reports/cli-report.txt",
"html": "./apifox-reports/report.html",
"junit": "./apifox-reports/junit.xml"
},
"agentHints": {
"summary": "All tests passed. 4 steps executed successfully.",
"nextSteps": [
"Review the HTML report for detailed results.",
"If failures occurred, debug using CLI error details.",
"Integrate this test into CI pipeline."
]
}
}
完整链路
所有元素现已连通，构成一个环环相扣的闭环：
| 元素 | 状态 |
|---|---|
| PRD | 已读取并处理完毕 |
| 代码库 | 已完成路由分析 |
| OpenAPI | 已生成并成功导入 |
| 接口资产 | 已在Apifox中创建 |
| 单接口测试 | 已创建并通过验证 |
| 业务场景 | 已构建并完成校验 |
每一步均有据可查，全程可追溯。
贯穿流程的 agentHints
注意 agentHints 如何在每次状态转换后提供明确指引：
| 完成阶段 | agentHints 建议 |
|---|---|
| 导入接口后 | “列出接口，添加测试用例” |
| 创建测试用例后 | “回读确认，创建更多测试用例，构建场景” |
| 创建场景后 | “添加断言，验证，运行测试” |
| 运行测试后 | “查看报告，必要时调试，集成到CI” |
Agent永远无需猜测下一步该做什么。
对比：MCP vs. CLI + SKILL 完成此任务
| 维度 | MCP 方法 | CLI + SKILL 方法 |
|---|---|---|
| 起点 | Agent搜索项目工具 | SKILL自动识别任务类型 |
| 接口创建 | Agent猜测使用哪个工具及字段 | 通过OpenAPI进行CLI导入 |
| 测试用例创建 | 字段错误导致多次重试 | 写入前执行本地验证 |
| 场景构建 | Agent手动编写结构 | 导入步骤、回读确认、更新完善 |
| 校验 | Agent自行寻找运行工具 | 场景完成后agentHints自动建议 |
| 总步骤 | 约20-25次调用（含重试） | 约10-12次经过验证的调用 |
核心要点
- 完整工作流：PRD → OpenAPI → 导入 → 测试用例 → 场景 → 校验
- 每一步都配有CLI命令 + 验证机制 + agentHints指引
- 导入步骤结合回读确认，比手动编写场景更安全可靠
--with-case-detail参数为更新提供真实的结构参考- agentHints 引导每一次状态转换
- 整个过程均可验证、可追溯
