下面这些话，如果你做过接口测试或测开，大概率听过——有的可能就是你自己说的。

---

坑 1：Swagger 来了，不知道从哪测起

场景
后端甩一份 OpenAPI，几十个接口。领导要「这周出自动化」。你打开文档，不知道从哪个接口开始，更不知道负例要不要写。

以前怎么办
自己挑几个「看起来重要」的接口，让 AI 写 pytest；或者只测登录 + 列表，Happy Path 测完就交差。评审问：401 呢？分页边界呢？——答不上来。

我们怎么解
接口线按 H（主路径）/ E（边界）/ X（拒绝）/ P（粗性能）/ S（安全 sanity） 分层铺用例，不是凑名词——对外会打的接口，至少 H + X；涉及钱的再加 S。
有 OpenAPI 时，先解析成端点清单，再按优先级出用例表，最后落成 spec，而不是直接吐一段 Python。

你只有接口清单、没有完整 Swagger？照样走同一条线——表格、Postman 导出、甚至一句话「测登录，错密码要 401」都会先被收成 可评审的 cases，再生成脚本。

---

坑 2：让 AI 写脚本很快，两周后没人敢改

场景
第一次：把文档贴给 ChatGPT，pytest 跑通了，开心。
两周后：路径改了、字段改名、鉴权从 Cookie 换成 Bearer。你打开 py 文件，断言写法、fixture 名字、环境变量方式和另一个同事写的完全两套。你想改 A 接口，发现 B 接口的脚本又是另一种风格。

以前怎么办
要么硬着头皮手工改 py，要么重新让 AI 写一版——新对话，新风格，循环往复。

我们怎么解
中间多一层 spec（Markdown + YAML），不让人直接维护生成出来的 py：

OpenAPI / 人话 / 评审过的用例表  →  spec  →  ./generate.sh  →  pytest

• 改接口？改 spec，再 ./generate.sh，脚本结构不变。
• 团队十个人生成十次？同一种 pytest 骨架，能进同一套 CI。
• 不想开 AI？手写 spec 也行，和 AI 生成走同一个编译器。

痛点不是「AI 不会写」，是 写出来的东西没法管。

---

坑 3：注册 → 拿 token → 调业务接口，变量传不过去

场景
注册接口返回 user_id，下一步查询要带这个 id。你让 AI 写测试，它往往拆成三个 test_xxx，互相拿不到上一步的返回值，只能写死 id 或 copy 粘贴，一跑就假绿。

以前怎么办
自己写 fixture、session、全局变量，或者把三步硬塞进一个超长函数——能跑，但别人看不懂，CI 里 flaky。

我们怎么解
spec 里用 scenarios[] 描述多步流程：一步里 capture 从上一步 JSON 取值，下一步用 {变量名} 拼 path/body。
登录鉴权也不用每个 case 重复写——spec 声明 bearer_login，生成器带好 token fixture，单步需要匿名再标 no_auth: true。

你描述的是业务流程，落下来的仍是一条能跑的 pytest，不是三个互不相干的 test。

---

坑 4：脚本红了，不知道是环境、脚本还是产品 bug

场景
流水线红了。开发说：「你环境不对。」你说：「接口就是 500。」测开同事说：「是不是断言路径写错了？」
三方扯半小时，日志散在终端里，缺陷单还要重新手打复现步骤。

以前怎么办
截图终端、复制 response、自己填 Jira 模板——每次失败重来一遍。

我们怎么解

• pytest 失败时，自动在 output/bugs/ 写缺陷草稿（编号、用例、失败摘要），你先分流再定稿。
• 明显是 契约变了、401、字段路径错了 → 走接口 自我修复 SKILL，要求最小改动 + 复跑验证。
• 明显是 服务端逻辑错了 → 走 bug-reporter 模板，附请求/响应摘录，不是让 AI 把 500「修绿」。
• 环境本身挂了 → 标 skip，别硬算产品失败。

红灯之后有事做、有依据，而不是「再跑一遍看看」。

---

坑 5：地址、密码写死在脚本里，进不了 CI

场景
你本机 base_url 写 localhost:8080，同事是 test.xxx.com，流水线又是第三套地址。合并代码后 全员改一遍 py。

以前怎么办
口头约定「记得改环境变量」，但脚本里仍藏着 admin/admin123。

我们怎么解
统一从环境变量读：TEST_BASE_URL、TEST_USERNAME、TEST_PASSWORD，spec 里只写占位逻辑。
本地、测试环境、CI 同一条命令：

export TEST_BASE_URL=http://你的服务:端口
./run_pytest.sh output/api_smoke.py -v

没后端也能验收工具链：先 pytest --collect-only，证明 spec → 脚本这条链通了，再谈业务全绿。

---

坑 6：功能用例写得很细，自动化各写各的

场景
测试同学 Excel 里 TC-API-012 写得清清楚楚，自动化同事另起炉灶又起一套编号，对不上。缺陷单上写的是功能用例号，脚本里对不上。

以前怎么办
两套资产，评审过一遍，自动化再「理解」一遍，重复劳动 + 漏测。

我们怎么解

• 有 PRD：用例设计线出测试点 → 评审 → P0 交给接口线落 spec，case id 从设计阶段一路带到脚本、报告、缺陷。
• 只有接口、没有 PRD：直接从契约或清单进接口线。
• 跳过评审就全量生成？能生成，但 维护成本会爆——SKILL 里写明了，不是不能，是不建议。

---

对照一张表：痛点 → 我们做了什么

你遇到的痛	专业版接口线
文档一大本，不知测啥	分层用例 H/E/X/P/S + 规划范围
AI 脚本风格乱、难维护	spec 中间层 + generate.sh 统一产出
多步流程变量传不了	scenarios[] + capture
红了扯皮、缺陷难写	自动缺陷草稿 + 自愈/报 bug 分流
环境地址乱、进不了 CI	TEST_BASE_URL 等统一约定
功能用例和自动化两套号	从评审用例接到 spec，编号一致

---

你可以怎么试（不用先懂全部文档）

只有 3 分钟、没后端——先证明「能生成、能收集」：

./generate.sh templates/api_smoke.md
cd output && python3 -m pytest api_smoke.py --collect-only -q

有 OpenAPI + 测试环境：

./generate.sh --import-openapi openapi.json --base-url http://你的服务:端口 -o output/imported.md
./generate.sh output/imported.md
export TEST_BASE_URL=http://你的服务:端口
cd output && python3 -m pytest imported_api.py -v

在 Cursor 里一句话（规矩已写在 api-skills 里，不用每次重教 AI）：

@api-skills/执行/SKILL.md
@openapi.yaml
按接口线：先出分层用例表，再 spec，再给 generate 和 pytest 命令

---

说句实话：我们也不解决什么

• 不会替你判断产品需求对不对——那是测试设计的事。
• 不会自动建 Jira/禅道单——出 Markdown 草稿，你们系统自己对接。
• 不会把服务端逻辑 bug「修到绿」——那是开发的活，我们只帮你 记清楚、分清楚。

接口自动化的价值，对测试同学来说就一句：少重复教 AI、少手工维护 py、红灯有据可查、团队能一起维护。 剩下的，是你熟悉的测试判断。

---

作者：测试员周周，14 年测试经验，专注 AI测试提效与自动化实战。