@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

package/plugins/req/skills/test-guide/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: test-guide
+description: |
+  测试引导助手。在执行 /req:test、/req:test_regression 或 /req:test_new 命令时触发。
+  支持运行已有自动化测试和创建新测试用例。
+---
+
+# 测试引导助手
+
+测试分为两大类型，通过不同命令触发：
+
+| 命令 | 用途 | 说明 |
+|-----|------|------|
+| `/req:test_regression` | 运行已有测试 | 执行现有自动化测试用例，回归验证 |
+| `/req:test_new` | 创建新测试 | 为新功能编写 UT/API/E2E 测试用例 |
+| `/req:test` | 综合测试 | 先运行回归，再补充新测试 |
+
+> **重要**：本 skill 不内置任何项目测试细节。测试目录、测试框架、运行命令、
+> 代码示例均从项目 CLAUDE.md 的「测试规范」章节读取。
+> 如 CLAUDE.md 缺少测试规范，会发出警告并建议补充。
+
+---
+
+## 前置准备：读取项目测试配置
+
+Read `docs/prompt/architecture.md`，从「测试规范」章节获取测试目录、框架、运行命令。
+
+- 文件存在 → 读取，静默注入
+- 文件不存在 → 回退从 CLAUDE.md 读取（兼容旧项目）
+
+从项目 CLAUDE.md 的「测试规范」章节获取（architecture.md 不存在时的兜底）：
+
+| 配置项 | 用途 | 示例 |
+|--------|------|------|
+| UT 位置 | 定位已有测试文件 | `*_test.go` / `*.test.ts` |
+| UT 框架 | 生成测试代码风格 | go test / JUnit / Vitest |
+| API 测试位置 | 定位 API 测试 | `tests/api/` |
+| E2E 测试位置 | 定位 E2E 测试 | `tests/e2e/` |
+| E2E 框架 | 生成 E2E 代码 | Playwright / Cypress |
+| 运行命令 | 执行测试 | `go test ./...` / `npm test` |
+| 测试环境 | 环境准备 | docker-compose / testcontainers |
+
+**读取领域规约（Specs）**：
+
+读取 CLAUDE.md 后，检查项目是否存在领域规约：
+
+- **primary 仓库**：扫描 `docs/requirements/specs/` 目录，读取所有 `.md` 文件
+- **readonly 仓库**：读取 `~/.claude-requirements/projects/<requirementProject>/specs/`（`requirementProject` 取自 `.claude/settings.local.json`）
+
+目录存在且有文件 → 全部读取，作为测试约束注入上下文，不打印提示。  
+目录不存在或为空 → 静默跳过。
+
+---
+
+**CLAUDE.md 缺少测试规范时**：
+
+```
+⚠️ CLAUDE.md 中未检测到测试规范
+
+   /req:test 需要以下信息来定位和生成测试：
+   - 测试文件位置和命名规则
+   - 测试框架和运行命令
+   - 测试环境搭建方式
+
+   💡 添加方式：/req:init <project> --reinit
+```
+
+---
+
+## 一、回归测试 (`/req:test_regression`)
+
+运行项目中已存在的自动化测试用例。
+
+### 测试类型识别
+
+根据 CLAUDE.md 测试规范自动识别：
+
+| 类型 | 识别方式 | 说明 |
+|-----|---------|------|
+| UT | CLAUDE.md 中定义的 UT 位置和文件模式 | 单元测试 |
+| API | CLAUDE.md 中定义的 API 测试位置 | 集成测试 |
+| E2E | CLAUDE.md 中定义的 E2E 测试位置 | 端到端测试 |
+
+### 执行流程
+
+```
+1. 读取 CLAUDE.md 测试规范
+2. 识别测试范围（全量/增量/指定模块）
+3. 按 CLAUDE.md 中的运行命令执行测试
+4. 收集测试结果
+5. 生成测试报告
+```
+
+### 测试范围选项
+
+```bash
+/req:test_regression              # 全量回归
+/req:test_regression --changed    # 仅测试变更相关
+/req:test_regression --module=xxx # 指定模块
+/req:test_regression --failed     # 仅运行上次失败的
+```
+
+### 结果输出格式
+
+```
+🔄 执行回归测试...
+
+📦 单元测试
+├── <测试文件1>      ✅ X/X 通过
+├── <测试文件2>      ✅ X/X 通过
+└── <测试文件3>      ❌ X/X 通过
+
+📡 API 测试
+├── <接口1>          ✅ 通过
+└── <接口2>          ❌ 失败 - 原因
+
+📊 回归测试结果：XX/XX 通过 (XX.X%)
+
+❌ 失败用例：
+1. <失败用例名> - <失败原因>
+
+💡 下一步：
+- 修复问题后重新测试：/req:test_regression --failed
+```
+
+---
+
+## 二、创建新测试 (`/req:test_new`)
+
+为新开发的功能创建自动化测试用例。
+
+### 测试金字塔
+
+```
+        ┌─────────┐
+        │   E2E   │  少量关键路径
+        ├─────────┤
+        │   API   │  中等数量，覆盖接口
+        ├─────────┤
+        │   UT    │  大量，覆盖业务逻辑
+        └─────────┘
+```
+
+### 2.1 单元测试 (UT)
+
+**目标**：测试业务逻辑层，不依赖外部服务
+
+**生成规则**：
+1. 读取 CLAUDE.md 中的 UT 规范（框架、命名、目录）
+2. 按项目的测试框架风格生成代码
+3. 遵循项目的命名约定和目录结构
+
+**测试场景覆盖**：
+- 正常流程（Happy Path）
+- 边界条件（空值、最大/最小值）
+- 异常场景（重复、不存在、无权限）
+- 业务规则验证
+
+**UT 生成流程**：
+
+```
+1. 分析需求文档中的业务规则
+2. 从 CLAUDE.md 读取分层架构，识别业务层需要测试的方法
+3. 为每个方法生成测试用例（按项目测试框架风格）
+4. 包含正常和异常场景
+5. 按项目规范生成 mock 依赖
+```
+
+### 2.2 API 测试
+
+**目标**：验证接口契约、参数校验、错误码
+
+**生成规则**：
+1. 从需求文档提取接口需求
+2. 按 CLAUDE.md 中的 API 测试规范生成代码
+3. 遵循项目的测试数据管理方式
+
+**API 测试要点**：
+
+| 测试类型 | 验证内容 |
+|---------|---------|
+| 参数校验 | 必填、格式、范围、类型 |
+| 权限控制 | 认证、授权、租户隔离 |
+| 错误码 | 统一错误码格式和语义 |
+| 响应格式 | 结构、字段完整性 |
+| 边界场景 | 空列表、分页边界、并发 |
+
+### 2.3 E2E 测试
+
+**目标**：验证完整用户流程，端到端场景
+
+**适用场景**：
+- 核心业务流程
+- 跨模块交互
+- 关键用户旅程
+
+**生成规则**：
+1. 从 CLAUDE.md 读取 E2E 框架和配置
+2. 从需求文档提取用户故事和关键流程
+3. 按项目的 E2E 框架风格生成测试代码
+4. 包含正常和异常场景
+
+---
+
+## 三、测试创建工作流
+
+执行 `/req:test_new` 时的完整流程：
+
+### 步骤 1：分析需求
+
+```
+📋 分析需求文档...
+
+需求：REQ-XXX 需求标题
+涉及功能：
+- [从功能清单提取]
+
+识别到的测试点：
+- 业务层：X 个方法需要 UT
+- API：X 个接口需要测试
+- E2E：X 个核心流程
+```
+
+### 步骤 2：选择测试类型
+
+```
+请选择要创建的测试类型：
+
+[ ] 单元测试 (UT) - 推荐：业务逻辑层
+[ ] API 测试 - 推荐：已有接口定义
+[ ] E2E 测试 - 可选：关键流程
+[ ] 全部
+
+输入选择 (1/2/3/all)：
+```
+
+### 步骤 3：生成测试代码
+
+根据选择，按 CLAUDE.md 中的测试规范生成对应测试文件。
+
+```
+📝 生成测试文件...
+
+✅ <测试文件1>
+   - <测试用例1>
+   - <测试用例2>
+
+✅ <测试文件2>
+   - <测试用例3>
+   - <测试用例4>
+
+📊 共生成 X 个测试文件，X 个测试用例
+```
+
+### 步骤 4：运行验证
+
+使用 CLAUDE.md 中定义的测试运行命令执行新创建的测试。
+
+---
+
+## 四、测试最佳实践
+
+### 命名规范
+
+> 从 CLAUDE.md 测试规范读取项目具体的命名约定。通用原则：
+
+| 类型 | 原则 |
+|-----|------|
+| UT 函数 | 被测对象_方法_场景（语言惯例命名） |
+| API 测试 | 接口_场景 |
+| E2E 测试 | 描述性名称，体现用户故事 |
+
+### Mock 使用原则
+
+- UT：Mock 外部依赖（数据层、第三方服务）
+- API：Mock 外部服务，使用真实或测试数据库
+- E2E：尽量使用真实环境
+
+### 覆盖率目标
+
+| 测试类型 | 建议覆盖率 |
+|---------|-----------|
+| UT (业务层) | >= 80% |
+| API | 100% 接口覆盖 |
+| E2E | 核心流程 100% |
+
+---
+
+## 五、与需求关联
+
+测试完成后更新需求文档：
+
+```markdown
+## 测试覆盖
+
+| 类型 | 文件 | 用例数 | 覆盖率 |
+|-----|------|-------|-------|
+| UT | <测试文件> | X | XX% |
+| API | <测试文件> | X | XX% |
+| E2E | <测试文件> | X | - |
+
+最后测试时间：YYYY-MM-DD
+测试结果：✅ 全部通过 / ❌ X 个失败
+```

package/plugins/req/skills/test_new/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: test_new
+description: |
+  创建测试 - 为新功能编写自动化测试用例或手动测试用例文档
+---
+
+> **重要**：本命令的测试文件位置、运行命令、代码示例均从项目 CLAUDE.md 的「测试规范」章节读取，不内置任何项目细节。
+
+# 创建测试
+
+为新开发的功能创建自动化测试用例，包括单元测试、API 测试和 E2E 测试。
+
+> 存储路径和缓存同步规则见 [_storage.md](./_storage.md)
+
+## 命令格式
+
+```
+/req:test_new [REQ-XXX] [--type=ut|api|e2e|all]
+```
+
+### 参数
+
+| 参数 | 说明 | 示例 |
+|-----|------|------|
+| `REQ-XXX` | 需求编号（可选） | `/req:test_new REQ-001` |
+| `--type=ut` | 仅创建单元测试 | `/req:test_new --type=ut` |
+| `--type=api` | 仅创建 API 测试 | `/req:test_new --type=api` |
+| `--type=e2e` | 仅创建 E2E 测试 | `/req:test_new --type=e2e` |
+| `--type=all` | 创建所有类型测试 | `/req:test_new --type=all` |
+| `--type=manual` | 生成人工复测用例文档 | `/req:test_new --type=manual` |
+| `--dry-run` | 预览不实际创建 | `/req:test_new --dry-run` |
+
+---
+
+## 执行流程
+
+### 1. 选择需求
+
+- 指定编号 → 使用该需求
+- 未指定 → 查找「开发中」或「测试中」的需求
+- 多个候选 → 让用户选择
+
+### 2. 分析需求文档
+
+```
+分析需求文档...
+
+需求：REQ-001 <需求标题>
+状态：开发中
+
+功能清单：
+1. <功能点 1>
+2. <功能点 2>
+3. <功能点 3>
+
+涉及文件：
+<source-file-1>
+<source-file-2>
+<source-file-3>
+<source-file-N>
+
+识别测试点：
+
+
+类型     测试点                       数量     
+
+UT       业务层方法                    N        
+API      接口端点                     N        
+E2E      用户流程                     N        
+
+```
+
+### 3. 选择测试类型
+
+```
+请选择要创建的测试类型：
+
+[1] 单元测试 (UT)
+    - 测试业务层逻辑
+    - 使用 Mock 隔离依赖
+    - 预计生成 N 个测试用例
+
+[2] API 测试
+    - 测试接口端点
+    - 验证请求/响应/错误码
+    - 预计生成 N 个测试文件
+
+[3] E2E 测试
+    - 测试完整用户流程
+    - 端到端场景验证
+    - 预计生成 N 个测试文件
+
+[4] 全部自动化
+
+[5] 手动测试用例文档 (manual)
+    - 供测试人员逐条复测
+    - 覆盖后端接口 + 前端交互 + 业务规则
+    - 生成 docs/test-cases/REQ-XXX-testcases.md
+
+请输入选择 (1/2/3/4/5)：
+```
+
+### 4. 生成单元测试 (UT)
+
+#### 4.1 分析被测方法
+
+```
+分析业务层方法...
+
+<source-file>:
+<方法签名 1>
+<方法签名 2>
+<方法签名 3>
+<方法签名 N>
+```
+
+#### 4.2 生成测试用例
+
+根据 CLAUDE.md 中定义的测试框架和规范，生成对应的测试代码。
+
+测试用例遵循 **Arrange-Act-Assert** 模式：
+
+```
+生成文件：<CLAUDE.md中定义的测试文件路径>
+
+测试用例列表：
+<TestCase_Method1_Success>        - 正常流程
+<TestCase_Method1_ErrorCase>      - 异常场景
+<TestCase_Method2_ValidInput>     - 输入校验
+<TestCase_Method2_InvalidInput>   - 边界条件
+<TestCase_Method3_NormalCase>     - 正常流程
+<TestCase_Method3_EdgeCase>       - 边界条件
+
+每个测试用例结构：
+1. Arrange - 准备数据和 Mock 依赖
+2. Act - 执行被测方法
+3. Assert - 验证结果
+```
+
+#### 4.3 生成 Mock 文件（如需要）
+
+```
+按 CLAUDE.md 测试规范生成 Mock 文件...
+
+<CLAUDE.md中定义的Mock生成命令>
+
+✅ 生成：<mock-file-path>
+```
+
+### 5. 生成 API 测试
+
+#### 5.1 提取 API 定义
+
+```
+提取 API 定义...
+
+从需求文档提取：
+<HTTP_METHOD> <endpoint-1>    <描述>
+<HTTP_METHOD> <endpoint-2>    <描述>
+<HTTP_METHOD> <endpoint-3>    <描述>
+```
+
+#### 5.2 生成测试代码
+
+根据 CLAUDE.md 中定义的 API 测试框架生成测试代码。
+
+每个接口的测试覆盖：
+
+```
+生成文件：<CLAUDE.md中定义的API测试文件路径>
+
+<endpoint-1> 测试用例：
+正常请求 - 完整参数         → 期望成功响应
+正常请求 - 可选参数缺省      → 期望成功响应（默认值）
+异常请求 - 缺少必填字段      → 期望参数校验错误
+异常请求 - 业务规则冲突      → 期望业务错误码
+异常请求 - 无权限            → 期望权限错误
+
+采用表驱动测试模式，每组包含：
+- name: 场景描述
+- input: 请求参数
+- wantStatus: 期望状态码
+- wantBody: 期望响应内容（可选）
+```
+
+### 6. 生成 E2E 测试
+
+**前提条件**：E2E 测试需要完整的测试环境
+
+```
+⚠️ E2E 测试需要启动测试环境：
+- 依赖服务（数据库、缓存等）
+- 后端服务（本地）
+- 前端服务（本地）
+```
+
+#### 6.1 识别用户流程
+
+```
+识别用户流程...
+
+核心流程：<功能名称>
+1. <用户操作步骤 1>
+2. <用户操作步骤 2>
+3. <用户操作步骤 3>
+4. <验证步骤>
+```
+
+#### 6.2 生成测试代码
+
+根据 CLAUDE.md 中定义的 E2E 测试框架生成测试代码。
+
+```
+生成文件：<CLAUDE.md中定义的E2E测试文件路径>
+
+测试场景：
+<场景 1>: <用户流程描述>
+  前置：<数据准备 / 登录>
+  操作：<页面交互步骤>
+  断言：<预期结果>
+<场景 2>: <边界条件描述>
+  前置：<特定状态准备>
+  操作：<触发边界条件>
+  断言：<预期错误提示>
+<场景 3>: <修改流程描述>
+    前置：<已有数据>
+    操作：<修改操作>
+    断言：<修改后状态>
+```
+
+### 7. 生成手动测试用例文档 (manual)
+
+> 适用场景：需要给测试人员一份可逐条执行的复测清单，前后端项目均适用。
+
+#### 7.1 分析信息源
+
+同时读取两处：
+
+```
+读取需求文档...
+功能清单（待验证的功能点）
+业务规则（边界条件、约束）
+使用场景（正常流程 + 异常流程）
+测试要点（已有的验收标准）
+
+读取源代码...
+后端：handler/controller → 提取接口路径、参数、返回码
+后端：service/logic     → 提取分支逻辑、边界判断
+前端：页面/组件          → 提取交互逻辑、表单校验、跳转规则
+```
+
+源码补充需求文档未覆盖的细节（如实际返回的错误码、字段校验规则）。
+
+#### 7.2 生成用例
+
+按模块分组，每条用例包含：编号、场景、前置条件、操作步骤、预期结果、实际结果（空）、通过（空）。
+
+**后端接口** — 每个接口至少覆盖：正常路径、参数缺失/非法、业务规则冲突、权限不足。
+
+**前端交互** — 每个页面/功能至少覆盖：正常操作流程、表单校验、异常提示、边界状态（空数据、超长文本、加载失败等）。
+
+**业务规则** — 需求文档中的每条业务规则对应至少一条用例。
+
+输出格式：
+
+````
+生成手动测试用例...
+
+生成文件：docs/test-cases/REQ-XXX-testcases.md
+
+# REQ-XXX <需求标题> · 手动测试用例
+
+> 需求：[REQ-XXX](../../requirements/active/REQ-XXX-xxx.md)
+> 生成日期：YYYY-MM-DD
+> 状态：待测试
+
+---
+
+## 后端接口
+
+| 编号 | 场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 通过 |
+|-----|------|---------|---------|---------|---------|-----|
+| TC-001 | <接口名>-正常 | <前置数据/权限> | `<HTTP_METHOD> <path>`<br>参数：`{...}` | HTTP <状态码>，返回 `{...}` | | |
+| TC-002 | <接口名>-缺少必填字段 | - | 省略字段 `<field>` | HTTP 400，`message` 含"<字段名>不能为空" | | |
+| TC-003 | <接口名>-无权限 | 未登录 / 低权限账号 | 发起请求 | HTTP 401 / 403 | | |
+| TC-004 | <接口名>-业务规则冲突 | <冲突前置条件> | <触发冲突的参数> | HTTP 4XX，业务错误码 `<code>` | | |
+
+---
+
+## 前端交互
+
+| 编号 | 页面/功能 | 场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 通过 |
+|-----|---------|------|---------|---------|---------|---------|-----|
+| TC-101 | <页面名> | 正常流程 | <登录状态/数据> | 1. <操作1><br>2. <操作2><br>3. <操作3> | <可观测的页面状态> | | |
+| TC-102 | <页面名> | 表单校验-<字段> | - | 1. 不填 `<字段>`<br>2. 点击提交 | 字段下方显示"<校验提示>" | | |
+| TC-103 | <页面名> | 空数据状态 | 无相关数据 | 进入页面 | 显示空状态占位 | | |
+| TC-104 | <页面名> | 操作成功反馈 | <正常前置> | <完成操作> | 显示成功提示，数据刷新 | | |
+
+---
+
+## 业务规则验证
+
+| 编号 | 规则 | 场景 | 操作 | 预期结果 | 实际结果 | 通过 |
+|-----|------|------|------|---------|---------|-----|
+| TC-201 | <业务规则描述> | <触发场景> | <操作步骤> | <预期约束生效表现> | | |
+
+---
+
+## 测试执行记录
+
+- **执行人**：
+- **执行日期**：
+- **测试环境**：
+- **总计**：N 条，通过 0 条，失败 0 条，跳过 0 条
+````
+
+#### 7.3 更新需求文档
+
+在需求文档「六、测试要点」末尾追加引用行：
+
+```markdown
+手动测试用例：[docs/test-cases/REQ-XXX-testcases.md](../../../test-cases/REQ-XXX-testcases.md)（生成于 YYYY-MM-DD）
+```
+
+---
+
+### 8. 测试文件汇总
+
+```
+测试文件生成完成
+
+
+类型     文件                                                用例数   
+
+UT       <ut-test-file>                                     N        
+API      <api-test-file>                                    N        
+E2E      <e2e-test-file>                                    N        
+手动用例  docs/test-cases/REQ-XXX-testcases.md              N        
+
+合计     N 个文件                                            N        
+
+
+✅ 已生成 Mock 文件（如需要）
+✅ 已添加测试数据 fixtures（如需要）
+```
+
+### 9. 运行验证
+
+```
+运行新创建的测试...
+
+<CLAUDE.md中定义的UT运行命令> <ut-test-file>
+<TestCase_1>    --- PASS
+<TestCase_2>    --- PASS
+...
+
+<CLAUDE.md中定义的API测试运行命令> <api-test-file>
+<TestCase_API_1>    --- PASS
+<TestCase_API_2>    --- PASS
+...
+
+验证结果：N/N 通过
+
+下一步：
+- 运行全量回归：/req:test_regression
+- 继续开发：/req:dev
+- 完成需求：/req:done
+```
+
+### 10. 更新需求文档
+
+自动更新需求文档的测试覆盖章节：
+
+```markdown
+## 测试覆盖
+
+| 类型 | 文件 | 用例数 | 覆盖率 |
+|-----|------|-------|-------|
+| UT | <ut-test-file> | N | XX% |
+| API | <api-test-file> | N | XX% |
+| E2E | <e2e-test-file> | N | - |
+
+创建时间：<date>
+最后运行：<date> ✅ 全部通过
+```
+
+---
+
+## 测试模板
+
+测试模板从项目 CLAUDE.md 的「测试规范」章节读取，包括：
+
+### UT 模板
+
+- 测试框架、断言库、Mock 工具由 CLAUDE.md 定义
+- 遵循 Arrange-Act-Assert 模式
+- 命名规范：`Test{被测对象}_{方法}_{场景}`
+
+### API 测试模板
+
+- 测试框架由 CLAUDE.md 定义
+- 采用表驱动测试模式
+- 覆盖正常路径、异常路径、权限校验
+- 命名规范：`Test{Endpoint}_{场景}`
+
+### E2E 测试模板
+
+- E2E 框架由 CLAUDE.md 定义
+- 包含前置数据准备（如登录、数据重置）
+- 模拟真实用户操作流程
+- 验证页面状态和交互结果
+
+---
+
+## 用户输入
+
+$ARGUMENTS