接口自动化测试设计实战：Claude Code Skill

云缓存（Redis）这类中间件产品，API 接口动辄上百，且每个接口的测试逻辑又有大量的相似性与细节差异。我们团队基于 Claude Code 构建了一个专用 Skill（技能插件），目标就是让 AI 学会像资深测试工程师一样，自动生成高质量的、架构统一的集成测试代码。这篇文章，就是来复盘这个 Skill 从零开始设计、编写到不断迭代优化的全过程，希望能给同样在自动化测试上探索的同行一些启发。

一、为什么云缓存测试需要 Skill

1.1 云缓存产品的测试特点

作为中间件服务，云缓存的 API 接口天然可以按业务域划分为六大类。每类操作的模式高度相似，但具体的参数细节又各不相同。

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 核心设计理念：四个要素

三、工作流设计：让 AI 按步骤做事

工作流是 Skill 的骨架。没有它，AI 可能会跳过“读 SDK 源码确认参数”或“检查 Service 层是否已有方法”这些关键步骤，直接生成代码，错误率会非常高。

3.1 单 API 生成流程（10 步）

1. 先读参考文档————必须读 lessons_learned.md、error_debugging_guide.md、complete_example.md
2. 确定 API Request 类名（如 DescribeAnalysisTimeRequest）
3. 按分类表归入业务域（如 监控分析 → monitoring_analysis/）
4. 读对应 Service 文件，检查是否已有封装方法
5. 读 SDK Parameters 源码————这一步至关重要，确认构造函数参数顺序和可用的 setter 方法
6. 读 API 追踪文档，确认当前测试状态（避免重复编写）
7. 按模板 + 规则生成测试文件
8. 运行 pytest 验证，修复失败用例
9. 更新追踪文档，标记为“已测试”
10. 如遇新问题，自动追加到 lessons_learned.md————这就是 Skill 的自我进化机制

在整个流程中，有三步最为关键：步骤 1（避免重蹈覆辙）、步骤 5（参数签名不统一是高发问题）和步骤 10（失败自动沉淀，让 Skill 越用越聪明）。

3.2 场景型批量生成流程（8 步）

当用户一次性提供 3 个以上共享同一资源名词的 API（比如 AddWhiteListGroup、DeleteWhiteListGroup），Skill 会自动切换为“场景模式”。

1. 读取全部参考文档，额外读取 scenario_testing_guide.md
2. 绘制 API 依赖关系图：谁创建、谁查询、谁修改、谁删除
3. 确定编写顺序：查询 → 创建 → 修改 → 删除（查询 API 通常是验证其他操作的手段）
4. 批量读取所有相关 SDK Parameters 源码，检查 Service 层封装是否匹配
5. 优先修复 Service 层不匹配的地方，再写测试
6. 按四种场景模式生成测试（详见第五章）
7. 批量运行所有测试，检测跨用例干扰
8. 更新追踪文档和踩坑经验

四、模板设计：统一代码架构

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 测试用例的标准模板

模板规定了每个测试文件必须生成的标准化方法，并按优先级严格排列。

模板还区分了查询类和写操作 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 四种标准场景模式

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 辅助生成复杂、高质量代码的产品场景中的。

来源：互联网