接口自动化测试设计实战：Claude Code Skill
云缓存（Redis）这类中间件产品，API 接口动辄上百，且每个接口的测试逻辑又有大量的相似性与细节差异。我们团队基于 Claude Code 构建了一个专用 Skill（技能插件），目标就是让 AI 学会像资深测试工程师一样，自动生成高质量的、架构统一的集成测试代码。这篇文章，就是来复盘这个 Skill 从零开始设计、编写到不断迭代优化的全过程，希望能给同样在自动化测试上探索的同行一些启发。
一、为什么云缓存测试需要 Skill
1.1 云缓存产品的测试特点
作为中间件服务，云缓存的 API 接口天然可以按业务域划分为六大类。每类操作的模式高度相似，但具体的参数细节又各不相同。
| 业务域 | 典型操作 | 测试模式 |
|---|---|---|
| 实例管理 | 创建/删除/重启/变配实例 | 状态等待 + 异步任务跟踪 |
| 安全访问 | 白名单分组增删改查、TLS 配置、账户管理 | CRUD 闭环 + 跨 API 交叉验证 |
| 监控分析 | 慢日志查询、离线分析 TopKeys | 时间参数格式处理 + 分页 |
| 备份恢复 | 创建备份/恢复实例/备份文件查询 | 异步操作等待 + 状态轮询 |
| 配置管理 | 参数配置/模板管理/模块加载卸载 | 全局配置修改需还原 |
| 任务管理 | 常规任务/诊断任务/诊断策略 | 两套独立任务系统区分 |
1.2 手工编写的三个痛点
在动手搭 Skill 之前，团队其实经历了一段时间的“纯手工”编写期，有三点感受特别深：
- 效率瓶颈：每个 API 的测试代码结构看着像，但 SDK 参数、响应字段、断言逻辑完全不同，逐个手写，重复劳动极其密集。
- 规范不统一：不同组员写的测试用例，在架构分层、断言粒度、日志格式上“各有千秋”，后期维护成本陡增。
- 经验靠口口相传：比如 SDK 参数签名不统一、时间格式差异、字段名和 API 名不匹配这些“坑”，总是要反复踩，知识难以沉淀。
1.3 Skill 的价值定位
我们想要的 Skill，不只是一个代码模板生成器。它本质上是一本“会自我进化的操作手册”————它定义了“怎么做”（工作流）、“做成什么样”（代码模板）、“什么不能做”（规则），更关键的是，它每次遇到新问题，都能自动把教训吸收进去，形成正向循环。
二、Skill 的整体设计
2.1 文件结构设计
.claude/skills/cache-test-generator/
├── SKILL.md # 主文件（约 516 行）：每次触发自动加载
│ ├── description (触发条件)
│ ├── Workflow (工作流)
│ ├── API Classification (业务域分类表)
│ ├── Key Architecture Rules (架构约束)
│ ├── Test File Template (代码模板)
│ ├── Common Pitfalls to A void (15 条一级规则)
│ └── Reference Documents System (参考文档索引)
│
└── references/ # 参考文档：工作流第一步主动读取
├── lessons_learned.md # 踩坑经验库（10 个陷阱 + 3 个最佳实践 + 排查清单）
├── error_debugging_guide.md # 排查指南（10 种常见错误 + 调试流程）
├── complete_example.md # 完整可运行示例 + 架构路径参考
└── scenario_testing_guide.md # 场景型测试指南（4 种 CRUD 模式）
这里有一个关键的分工思路：SKILL.md 每次对话都会自动加载，所以里面只放“必须每次看到”的内容，比如核心工作流、代码模板和一级规则。而详细的案例和背景信息，就放到 references/ 目录下，在工作流中要求“先读再动手”，既能保证核心规则不遗漏，又能避免主文件变得过于臃肿。
2.2 触发条件设计
SKILL.md 头部的 description 字段决定了 Skill 何时被激活。实践下来，触发条件要“宽泛”和“具体”并用。比如，既能匹配“写个缓存测试”，也能精确匹配“给 DescribeProxySlowLogRequest 写测试”这样的请求，这样才能覆盖各种自然语言的输入场景。
2.3 核心设计理念：四个要素
| 要素 | 解决什么问题 | 在 Skill 中如何实现 |
|---|---|---|
| 工作流 | AI 按什么步骤做事，不跳步不漏步 | SKILL.md → Workflow 章节（单 API 10 步 / 场景型 8 步） |
| 模板 | 生成的代码结构完全一致 | SKILL.md → Test File Template（含完整代码骨架） |
| 规则 | 划清“绝对不能做”的红线 | SKILL.md → Common Pitfalls（15 条硬性规则） |
| 经验 | 前人踩过的坑不再重踩 | references/lessons_learned.md（10 个实战案例） |
三、工作流设计：让 AI 按步骤做事
工作流是 Skill 的骨架。没有它，AI 可能会跳过“读 SDK 源码确认参数”或“检查 Service 层是否已有方法”这些关键步骤，直接生成代码，错误率会非常高。
3.1 单 API 生成流程（10 步）
- 先读参考文档————必须读 lessons_learned.md、error_debugging_guide.md、complete_example.md
- 确定 API Request 类名（如 DescribeAnalysisTimeRequest）
- 按分类表归入业务域（如 监控分析 → monitoring_analysis/）
- 读对应 Service 文件，检查是否已有封装方法
- 读 SDK Parameters 源码————这一步至关重要，确认构造函数参数顺序和可用的 setter 方法
- 读 API 追踪文档，确认当前测试状态（避免重复编写）
- 按模板 + 规则生成测试文件
- 运行 pytest 验证，修复失败用例
- 更新追踪文档，标记为“已测试”
- 如遇新问题，自动追加到 lessons_learned.md————这就是 Skill 的自我进化机制
在整个流程中，有三步最为关键：步骤 1（避免重蹈覆辙）、步骤 5（参数签名不统一是高发问题）和步骤 10（失败自动沉淀，让 Skill 越用越聪明）。
3.2 场景型批量生成流程（8 步）
当用户一次性提供 3 个以上共享同一资源名词的 API（比如 AddWhiteListGroup、DeleteWhiteListGroup），Skill 会自动切换为“场景模式”。
- 读取全部参考文档，额外读取 scenario_testing_guide.md
- 绘制 API 依赖关系图：谁创建、谁查询、谁修改、谁删除
- 确定编写顺序：查询 → 创建 → 修改 → 删除（查询 API 通常是验证其他操作的手段）
- 批量读取所有相关 SDK Parameters 源码，检查 Service 层封装是否匹配
- 优先修复 Service 层不匹配的地方，再写测试
- 按四种场景模式生成测试（详见第五章）
- 批量运行所有测试，检测跨用例干扰
- 更新追踪文档和踩坑经验
四、模板设计：统一代码架构
4.1 Skill 强制约束的四层架构
生成的测试代码必须严格遵循项目已有的四层分工，这是保证代码统一性和可维护性的基础。
测试用例层 test_cases/cache/test_cases/{业务域}/test_{ApiName}Request.py
↓ 使用 fixture + 实例化 service
Fixture 层 test_cases/cache/utils/fixtures/base_fixtures.py
↓ 提供客户端和测试数据
Service 层 test_cases/cache/utils/services/{业务域}_service.py
↓ 封装 SDK 调用，统一返回 (bool, Any)
SDK 层 cloud_sdk/services/cache/apis/{ApiName}Request.py
对于这些架构约束，Skill 采用了“三重保障”的策略：模板里体现正确写法、规则里禁止错误写法、工作流里设置检查步骤，这样远比只靠口头约定或一次性的文档说明要可靠得多。
4.2 测试用例的标准模板
模板规定了每个测试文件必须生成的标准化方法，并按优先级严格排列。
| 优先级 | 测试类型 | 数量 | 说明 |
|---|---|---|---|
| P0 | 核心功能测试 | 恰好 1 个 | 验证 API 基本功能，三层断言 |
| P1 | 错误处理 / 边界值 / 枚举值 | 多个（含参数化） | 无效实例 ID、最小/最大值、有效/无效枚举 |
| P2 | 参数组合 / 异常值 | 参数化 | null / 类型错误 / 格式异常 / 超长值 |
模板还区分了查询类和写操作 API 的不同断言策略：查询类必须硬断言 `isinstance(result, dict)`，null 直接报错；而写操作类的 null 返回可能是正常行为，用条件判断；写操作 P0 还必须调用对应查询 API 交叉验证，不能只信任返回值。
4.3 Marker 自动匹配
模板会智能地根据 API 名称前缀自动匹配 pytest marker，省去手动指定的麻烦。例如 `Describe*` 会自动加上 `@pytest.mark.cache_query` 标记。
五、场景型测试设计
云缓存产品中，很多 API 实际上属于同一业务的增删改查。单个测试往往不够，需要从整体上进行 CRUD 场景的规划。
5.1 什么时候进入场景模式
Skill 在 SKILL.md 中定义了一套自动识别规则：当用户提供的 API 满足“3 个以上”且“共享同一资源名词”两个条件时，自动切换为场景模式。
5.2 四种标准场景模式
| 模式 | 流程 | 云缓存中的实际场景 |
|---|---|---|
| 创建→验证→清理 | 调用 Add → 用 Describe 确认存在 → Delete 清理 | 添加白名单分组、创建账号、创建配置模板 |
| 创建→删除→验证 | 先 Add → Delete → 用 Describe 确认消失 | 删除白名单分组、删除账号 |
| 创建→修改→验证→清理 | Add → Modify → Describe 验证 → Delete | 修改白名单分组 IP、修改账号权限 |
| 保存→修改→验证→恢复 | Describe 保存原值 → Modify → 验证 → 恢复原值 | 修改全局 IP 白名单、修改备份策略、修改 TLS 配置 |
5.3 场景型代码示例：创建→验证→清理
以“添加白名单分组”为例，场景测试的代码逻辑非常清晰，覆盖了创建、查询验证、清理三个步骤，并且严格遵守了各项规则，比如测试数据命名、查询API交叉验证、清理失败仅warning等。
5.4 跨 API 业务约束测试
场景模式的 P1 测试还能覆盖一些“跨 API 的业务规则”，这是单 API 测试无法触及的。例如，验证分组名唯一性（重复创建会失败）、系统默认资源不可删除、操作不存在的资源会返回错误等。
5.5 实际场景案例
例如“白名单管理”场景，涉及 5 个 API，通过全部 4 种模式组合，最终产出 41 个用例，测试覆盖非常全面。
六、防错规则体系
6.1 两级规则管理
规则采用了“一级 + 二级”的分级管理方式。一级规则是“一句话禁令”，放在 SKILL.md 里自动加载，确保每次生成代码时都会被看到。二级规则则是完整的踩坑案例，放在 references/ 目录，按需读取。当一个陷阱被踩到 2 次以上，就会触发“规则提升机制”，把核心结论提炼为一级规则。
6.2 15 条一级规则一览
这些规则覆盖了架构、响应处理、Service 层和测试数据四个方面，共 15 条。每一条都用“禁止/必须”的绝对性措辞来约束，实践证明，这种确定性指令的遵守率远高于“建议/推荐”。
七、踩坑经验沉淀
这部分是 Skill 最有生命力的地方。下面几个案例非常有代表性，每个案例的价值不仅在于解决方案本身，更在于它如何被反向沉淀到了 Skill 的规则或工作流中，做到了“人人为我，我为人人”。
7.1 “假通过” — 测试 PASSED 但什么都没验证
这是一个非常经典的陷阱。查询 API 有时会返回 null，如果代码里写了个 `if/else` 分支，else 分支只调了 `logging.info()`，测试就会悄无声息地通过，但实际上什么都没验证。解决方式就是强制使用硬断言，null 直接报错，绝不“放水”。这条已经成了 SKILL.md 的一级规则第 8 条。
7.2 SDK Parameters 签名不统一 — 凭猜写代码必报错
同一系列的 API，有的 Parameters 构造函数全部传参，有的提供 setter，还有的两种混合，如果不读源码全靠猜测写代码，`AttributeError` 是家常便饭。这个案例促使我们加入了“规则第 11 条”和“工作流第 5 步”，强制要求“读源码确认签名”。
7.3 跨服务资源依赖 — API 参数引用了别的服务的资源
在测试 `ModifyPublicAddressRequest` 时，发现 `elasticIpId` 这个参数其实属于 VPC 服务。如果图省事用假 ID，只能测到错误路径，核心的“开启公网”功能永远覆盖不到。正确的做法是通过 VPC 服务的 `DescribeElasticIpsRequest` 查询一个真实的未绑定 EIP。这个案例教训深刻，最终沉淀为一级规则第 12 条，并在经验库里记录了完整的 5 步查找方法，方便以后遇到类似问题时参考。
八、Skill 构建方法总结
8.1 迭代路径
整个 Skill 的建设是分阶段迭代的，从 V0 的“能生成结构正确的代码”，到 V1 的“避开已知陷阱”，再到 V2 的理解“为什么”，最终到 V3 的“整体测试规划”，每一步都解决一个核心问题。
8.2 核心经验
总结下来，几条核心经验值得分享：Skill 是工作流、模板、规则和经验的集合，缺一不可；规则要分级，高频的必须自动加载，低频的按需读取；Skill 必须能自我进化；架构约束要三重保障；场景模式是质的飞跃；最后，“禁止”比“建议”有效得多。
8.3 可迁移到其他产品的设计模式
这次实践沉淀下来的一些设计模式，比如两级规则管理+提升机制、工作流末尾的自动经验沉淀、三层断言策略、场景识别切换、以及 SDK 源码驱动的参数确认，核心思想是可以迁移到任何需要 AI 辅助生成复杂、高质量代码的产品场景中的。