@wwkit/harness 1.0.28 → 1.0.29

package/skills/jstest/references/case-create.md

@@ -0,0 +1,327 @@
+> **原 skill**: `jstest-case-create`（已合并入 jstest）
+> **适用**: 测试代理外层 loop 的用例创建阶段，为未覆盖代码创建测试用例。
+> **不适用**: 修复已有失败用例（使用 jstest-case-fix）、非 jest 框架的用例创建。
+
+---
+
+# 测试用例创建
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **扫描已有测试**：检查目标模块是否已有测试文件，提取已有用例名
+2. **加载规范**：读取用例创建规范
+3. **分析源码**：识别未覆盖的函数、分支、异常路径
+4. **决策 Mock 策略**：按 test_type 选择 Mock 策略
+5. **创建用例**：增量追加或全新创建
+6. **语法验证**：验证创建的测试文件语法正确
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| uncovered_areas | 是 | list/string | 未覆盖区域清单（来自 Step 4（references/coverage-analyze.md），首轮为 "all"） |
+| testable_modules | 否 | list | 可测试模块清单（来自 Step 2（references/suitability-check.md），含文件路径+模块名+分类） |
+| target | 是 | string | 被测模块路径 |
+| test_dir | 是 | string | 测试目录路径（由 agent Step 1 统一解析） |
+| test_type | 是 | string | 测试类型：unit 或 integration |
+| config | 是 | object | 来自 Step 3（references/env-ensure.md） 的配置对象 |
+
+## 输出
+
+- 新增/追加的测试文件列表（标注是全新创建还是增量追加）
+- 每个文件新增的用例数
+- 跳过的重复用例数
+
+---
+
+## 阶段零：扫描已有测试
+
+**操作**：使用 agent 传入的 `test_dir` 直接扫描已有测试，确定工作模式
+
+1. 直接使用传入的 `test_dir` 路径（不再自行推导目录映射）
+
+2. 扫描该目录下是否已有 `*.test.js` 或 `*.test.ts` 文件
+
+3. **无已有文件** → 标记为 `全新模式`，直接进入阶段一
+
+4. **有已有文件** → 标记为 `增量模式`，执行以下操作：
+   - 逐个读取已有测试文件
+   - 提取已有测试用例名集合（`describe`/`test`/`it` 的完整名称字符串）
+   - 提取已有 import 语句和 setup/teardown 定义
+   - 记录已有 describe 块名称
+
+**决策**：
+
+| 模式 | 后续行为 |
+|------|---------|
+| 全新模式 | 创建新文件，从头编写用例 |
+| 增量模式 | 在已有文件中追加 test/it，跳过已存在的用例名 |
+
+---
+
+## 阶段一：加载规范
+
+**操作**：读取 `test-standards.md`，加载：
+- 通用规范（AAA、FIRST、命名）
+- JS/jest 特定规范（setup/teardown、mock、test.each）
+- test_type 对应的专属规范
+
+---
+
+## 阶段二：分析源码
+
+**输入**：uncovered_areas 清单 + testable_modules 清单（如有）
+
+**操作**：
+
+1. 确定待分析源码范围：
+   - 如果 `uncovered_areas == "all"`（首轮）：扫描 target 目录下所有 .js/.ts 文件
+   - 如果 `uncovered_areas` 为列表：仅读取列表中的未覆盖文件
+   - 如果提供了 `testable_modules`：仅分析清单中列出的模块，跳过不在清单中的模块
+
+2. 逐个读取待分析的源码文件
+
+3. 分析每个未覆盖函数：
+   - 函数签名（参数、返回值、export 方式）
+   - 内部分支（if/else/switch）
+   - 异常处理（throw/try-catch）
+   - 外部依赖（import 的模块、调用的外部方法）
+
+4. 识别需要创建的用例类型：
+   - 正向用例（每个公开函数至少 1 个）
+   - 边界值用例（有 if/else 分支的函数）
+   - 异常路径用例（有 throw/try 的函数）
+   - 参数化用例（多输入场景）
+
+---
+
+## 阶段三：决策 Mock 策略
+
+**操作**：根据 test_type 从 config 读取 mock_strategy
+
+### unit — mock_strategy=full
+
+按依赖类型选择 Mock 方式：
+
+| 依赖类型 | 处理策略 |
+|---------|---------|
+| HTTP 请求 | `jest.mock('axios')` 或 mock fetch，预设 mockResolvedValue |
+| 数据库 | `jest.mock('db-module')` 或 Fake 内存数据库 |
+| 文件系统 | `jest.mock('fs')` 或使用 `os.tmpdir()` |
+| 时间依赖 | `jest.useFakeTimers()` |
+| 随机值 | `jest.spyOn(Math, 'random').mockReturnValue(0.5)` |
+| 外部服务 | `jest.mock('email-module')` 等，验证调用参数 |
+| 环境变量 | `process.env.KEY = 'val'`（直接设置，afterEach 中恢复） |
+| 内部模块 | 优先真实调用，仅 Mock 有副作用的子模块 |
+
+### integration — mock_strategy=minimal
+
+| 依赖类型 | 处理策略 |
+|---------|---------|
+| 内部模块 | 真实调用，不 Mock |
+| 数据库 | 真实连接（测试库）或 Fake 内存数据库 |
+| 文件系统 | 真实文件操作（使用 `os.tmpdir()` 清理） |
+| 外部 API | 仅 Mock 不可控的生产 API |
+| 时间/随机 | 可接受真实值，或 `jest.spyOn` 固定 |
+
+---
+
+## 阶段四：创建用例
+
+**操作**：
+
+### 全新模式
+
+1. 使用传入的 `test_dir` 确定测试文件路径：
+   ```
+   test_dir: tests/unit/mypackage/
+   源码文件: src/mypackage/MyService.js
+   测试文件: tests/unit/mypackage/MyService.test.js
+   ```
+
+2. 按命名规范创建测试文件：
+   - 文件名：`{ModuleName}.test.js`
+   - describe 名：`'ModuleName'`
+   - test/it 名：`'should {action} {expected}'`
+   - 2 空格缩进
+   - describe/test/it 结构
+
+3. 按 AAA 模式编写每个用例：
+   - Arrange — 准备数据、Mock、setup
+   - Act — 调用被测方法
+   - Assert — 断言结果
+
+### 增量模式
+
+1. 确定目标测试文件（已存在）
+2. 读取已有文件内容，保留全部已有代码不动
+3. 对照阶段零提取的已有用例名集合，跳过已存在的用例
+4. 在已有 describe 块中追加新 test/it：
+   - 用例名：`'should {action} {expected}'`（不与已有用例重名）
+   - 仍遵循 AAA 模式
+   - 复用已有的 import 和 setup/teardown，仅在需要时追加 import
+5. 如果已有文件中没有对应的 describe 块（源码新增了模块），则在该文件中新增 describe 块
+
+**通用规则**（两种模式共用）：
+
+1. 按用例类型创建：
+   - 正向用例：正常输入 → 预期输出
+   - 边界用例：边界值 → 预期行为
+   - 异常用例：非法输入 → `expect(() => fn()).toThrow(Error)` 或 `expect(fn()).toThrow('message')`
+   - 参数化用例：`test.each([[1, true], [2, false]])('should validate %i', (input, expected) => { ... })`
+
+2. 检查 jest 配置（setupFiles / jest.setup.js）：
+   - 检查 test_dir 下是否有 jest.setup.js 或 package.json 中有 setupFiles 配置 → 有则不修改
+   - 检查 test_dir 的父目录是否有 jest 配置 → 有则不创建，提示"父目录已有 jest 配置"
+   - 均无 jest 配置 → 不创建 setupFiles（除非 test_dir 下完全没有任何 jest 配置，此时仅在 package.json 的 jest 字段中添加最小 setupFiles）
+   - 不导入任何项目特定的三方库到 setupFiles
+
+**创建示例**：
+
+```javascript
+import { MyService } from '../../../src/mypackage/MyService.js';
+
+jest.mock('../../../src/mypackage/MyService.js');
+
+describe('MyService', () => {
+  test('should create with valid data', () => {
+    // Arrange
+    const service = new MyService();
+    const data = { name: 'test', age: 18 };
+    // Act
+    const result = service.create(data);
+    // Assert
+    expect(result.id).toBeDefined();
+    expect(result.name).toBe('test');
+  });
+
+  test('should throw on empty name', () => {
+    // Arrange
+    const service = new MyService();
+    // Act & Assert
+    expect(() => service.create({ name: '' })).toThrow('name不能为空');
+  });
+
+  test.each([
+    [18, true],
+    [30, true],
+    [17, false],
+    [61, false],
+  ])('should validate age %i → %s', (age, expected) => {
+    const service = new MyService();
+    const result = service.validateAge(age);
+    expect(result).toBe(expected);
+  });
+});
+```
+
+---
+
+## 阶段五：语法验证
+
+**操作**：
+
+1. 对每个新创建的测试文件运行语法检查：
+   ```
+   node --check "<test_file>"
+   ```
+
+2. 语法错误 → 修复后重新验证
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 全部语法正确 | 输出创建结果 |
+| 有语法错误 | 修复后重新验证，最多 3 次 |
+| 修复 3 次仍失败 | 记录错误，跳过该文件 |
+
+---
+
+## 输出格式
+
+```
+## 用例创建报告
+
+### 工作模式
+- 模式: [全新模式 / 增量模式]
+- 已有测试文件: X 个（增量模式时显示）
+
+### 新增/追加测试文件
+| 文件路径 | 模式 | 新增用例数 | 跳过重复 | 覆盖函数 |
+|---------|------|-----------|---------|---------|
+| tests/unit/mypackage/MyService.test.js | 全新创建 | 8 | 0 | create, validate, parse |
+| tests/unit/mypackage/OtherService.test.js | 增量追加 | 3 | 2 | update, delete |
+
+### 用例明细
+| 用例名 | 类型 | 被测函数 |
+|--------|------|---------|
+| should create with valid data | 正向 | create |
+| should throw on empty name | 异常 | create |
+| should validate age boundary | 边界 | validate |
+
+### Mock 使用
+| 依赖类型 | Mock 方式 |
+|---------|---------|
+| HTTP | jest.mock('axios') |
+| 文件 | jest.mock('fs') |
+```
+
+### 0 新用例检测
+
+阶段四完成后，统计新增用例总数。如果为 0（所有方法均已存在），输出特殊标记：
+
+```
+## 用例创建报告
+
+### 工作模式
+- 模式: 增量模式
+- 新增用例数: 0
+
+### 结论
+- [0 新用例] 所有未覆盖区域已有对应测试，无法通过新增用例提升覆盖率
+- 建议: 检查已有用例质量（断言完整性、边界值覆盖），或确认覆盖率瓶颈原因
+```
+
+agent 收到此标记后，应跳过 execute + fix，直接回到 coverage-analyze 重新评分或判定"无改进"退出。
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 源码文件不存在 | 跳过，记录警告 |
+| 源码无法分析（语法错误） | 跳过，记录错误 |
+| 测试目录不存在 | 自动创建 |
+| 语法验证失败 | 修复重试，最多 3 次 |
+| jest.setup.js 已存在 | 不修改 |
+| 已有测试文件语法错误 | 跳过该文件的追加，记录警告 |
+| uncovered_areas 为空列表 | 输出"无需新建用例，建议改进已有用例质量"，返回给 agent |
+| 新增用例数为 0（全部重复） | 输出"0 新用例"标记，agent 应跳过 execute+fix |
+
+## 一定要做
+
+1. 必须先扫描已有测试文件，确定工作模式（全新/增量）
+2. 增量模式下必须保留已有代码不动，只追加新 test/it
+3. 必须根据 test_type 选择对应的 Mock 策略
+4. 如果提供了 testable_modules，必须仅对清单中的模块创建测试，跳过不在清单中的模块
+5. 如果 uncovered_areas 为 "all"（首轮），必须扫描全部源码文件
+6. 必须遵循命名规范（{ModuleName}.test.js 文件名、describe('ModuleName')、test('should ...')）
+7. 必须遵循 AAA 模式
+8. 必须为每个未覆盖函数创建至少 1 个正向用例
+9. 有分支的函数必须创建边界值用例
+10. 有异常处理的函数必须创建异常路径用例
+11. 创建后必须验证语法正确
+12. 遵循 AGENTS.md：2 空格缩进、describe/test/it 结构
+
+## 一定不要做
+
+1. 不要修改源码文件
+2. 不要覆盖已有测试文件中的已有用例
+3. 不要创建与现有测试重复的用例（用例名相同的跳过）
+4. 不要在单元测试中使用真实网络/文件/时间调用
+5. 不要修改已存在的 jest.setup.js 或 setupFiles 配置
+6. 不要导入项目特定的三方库到 setupFiles
+7. 不要跳过语法验证
+8. 不要使用 class 风格（统一用 describe/test/it 函数式）

package/skills/jstest/references/case-fix.md

@@ -0,0 +1,273 @@
+> **原 skill**: `jstest-case-fix`（已合并入 jstest）
+> **适用**: 测试代理内层 loop 的修复阶段，修复 jstest-execute 报告的失败用例。
+> **不适用**: 创建新用例（使用 jstest-case-create）、覆盖率分析（使用 jstest-coverage-analyze）。
+
+---
+
+# 用例修复
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **分类失败**：按错误类型对失败用例分类
+2. **分析原因**：逐个分析失败根因
+3. **执行修复**：按分类进行修复
+4. **语法验证**：验证修复后的文件语法正确
+5. **输出记录**：修复记录 + 人工处理项 + 源码 Bug 清单（写入 `{report_dir}/bug_list.md`）
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| failed_tests | 是 | list | 失败用例清单（来自 Step 6（references/execute.md）） |
+| test_dir | 是 | string | 测试目录路径（由 agent Step 1 统一解析） |
+| report_dir | 是 | string | 报告输出目录（由 agent Step 1 统一解析） |
+| test_type | 是 | string | 测试类型：unit 或 integration |
+| config | 是 | object | 来自 jstest-env-ensure 的配置对象 |
+
+## 输出
+
+- 修复记录列表
+- 人工处理项列表
+- 源码 Bug 清单（已修复 + 需人工处理）
+- 是否有修改的结论（有修改 → 回到 execute；无修改 → 内层 loop 退出）
+- 将源码 Bug 清单写入 `{report_dir}/bug_list.md`
+
+---
+
+## 阶段一：分类失败
+
+**操作**：按错误类型对失败用例分类
+
+| 分类 | 错误类型 | 说明 |
+|------|---------|------|
+| 断言失败 | AssertionError | 测试逻辑有误或源码有 bug |
+| Mock 配置错误 | TypeError, ReferenceError | jest.mock 路径不对或 Mock 对象属性缺失 |
+| 导入错误 | Cannot find module, SyntaxError | 依赖缺失，环境问题 |
+| 超时 | Exceeded timeout | 可能有真实网络调用未被 Mock |
+| 其他 | 其他异常 | 未知错误 |
+
+---
+
+## 阶段二：分析原因
+
+### 断言失败（AssertionError）
+
+逐个分析：
+
+1. 读取测试用例代码
+2. 读取被测源码
+3. 判断失败原因：
+   - **测试逻辑有误**：断言条件写错 → 修复测试
+   - **Mock 返回值不对**：mockResolvedValue/mockReturnValue 数据与预期不符 → 修复 Mock 返回值
+   - **源码逻辑有 bug**：测试暴露了真实缺陷 → 修复源码
+
+### Mock 配置错误（TypeError, ReferenceError）
+
+1. 检查 `jest.mock()` 路径是否正确
+2. 检查 Mock 对象是否配置了所需的属性/方法
+3. 检查 `mockReturnValue` / `mockResolvedValue` / `mockImplementation` 是否设置
+
+### 导入错误（Cannot find module, SyntaxError）
+
+1. 检查是否缺少依赖包
+2. 检查 ESM/CJS 模块系统是否匹配
+3. 标记为 **人工处理**，不在 fix 轮次中解决
+
+### 超时（Exceeded timeout）
+
+1. 检查是否有真实网络调用未被 Mock
+2. 修复为 Mock 调用（unit 类型）
+3. 集成测试的超时可能是环境问题 → 标记人工处理
+
+### 其他
+
+1. 记录详细错误信息
+2. 标记为 **人工处理**
+
+---
+
+## 阶段三：执行修复
+
+### 修复测试用例
+
+| 场景 | 修复操作 |
+|------|---------|
+| 断言条件写错 | 修正 expect 表达式 |
+| Mock 返回值不对 | 修改 mockReturnValue/mockResolvedValue 为正确值 |
+| jest.mock 路径不对 | 修正 jest.mock 路径为正确的模块路径 |
+| Mock 属性缺失 | 添加 mockImplementation 或配置 Mock 对象属性 |
+| Stub 数据格式不对 | 修正 Stub 数据结构 |
+| 测试数据有误 | 修正测试输入数据 |
+
+### 修复源码
+
+| 场景 | 修复操作 |
+|------|---------|
+| 函数返回值有误 | 修正返回逻辑 |
+| 异常处理不完整 | 补充 try-catch 分支 |
+| 边界条件处理错误 | 修正条件判断 |
+| 类型转换错误 | 修正类型处理 |
+
+### 修复原则
+
+1. **只修复失败相关的代码**，不改动其他部分
+2. **修复测试优先于修复源码**（先确认测试正确，再修源码）
+3. **一次只修一个失败**，避免引入新问题
+4. **不修改 jest 配置文件或 setupFiles**（除非失败直接由配置导致）
+5. **修改源码前必须保存原始内容**（读取并记录文件原始内容，用于回滚）
+
+---
+
+## 阶段四：语法验证与快速测试
+
+**操作**：
+
+### 4.1 语法检查
+
+对每个修复的文件运行语法检查：
+
+```
+node --check "<file>"
+```
+
+### 4.2 源码修复的快速测试
+
+如果修复了**源码文件**（非测试文件），额外运行对应测试文件的快速验证：
+
+```
+node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache --verbose --testTimeout=60000 "<对应测试文件>"
+```
+
+**目的**：`node --check` 只检查语法，无法发现运行时错误（类型错误、属性不存在等）。快速测试确保源码修复不引入新问题。
+
+### 4.3 回滚机制
+
+- 阶段三修复前已保存原始内容
+- 语法检查失败或快速测试引入新错误 → 用原始内容覆盖文件，回滚修改
+- 回滚后标记为人工处理
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 语法正确 + 快速测试通过（或无源码修复） | 进入阶段五 |
+| 语法错误 | 用原始内容回滚，标记为人工处理 |
+| 快速测试引入新错误 | 用原始内容回滚，标记为人工处理 |
+| 快速测试超时 | 回滚源码修改，标记为人工处理 |
+
+---
+
+## 阶段五：输出记录
+
+**操作**：
+
+1. 在 chat 中输出修复报告
+2. 将源码 Bug 清单写入 `{report_dir}/bug_list.md`
+
+### 修复报告（chat 输出）
+
+```
+## 用例修复报告
+
+### 修复记录
+| # | 文件 | 用例名 | 失败类型 | 修复类型 | 修复内容 |
+|---|------|--------|---------|---------|---------|
+| 1 | MyService.test.js | should create with valid data | 断言失败 | 修复测试 | 修正 expect 条件 |
+| 2 | MyService.js | - | 断言失败 | 修复源码 | 修正返回值逻辑 |
+| 3 | MyService.test.js | should parse on empty input | Mock错误 | 修复测试 | 修正 jest.mock 路径 |
+
+### 人工处理项
+| # | 文件 | 用例名 | 失败类型 | 原因 |
+|---|------|--------|---------|------|
+| 4 | MyService.test.js | should import module | 导入错误 | Cannot find module 'xxx' |
+
+### 结论
+- 修复 X 项，人工处理 Y 项
+- [有修改] → 建议重新执行测试
+- [无修改] → 无法自动修复，建议人工介入
+```
+
+### 源码 Bug 清单（写入 {report_dir}/bug_list.md）
+
+仅记录修复类型为"修复源码"的条目，以及源码层面无法自动修复需人工处理的条目。
+
+```markdown
+# 源码 Bug 清单
+
+> 生成时间: {YYYY-MM-DD HH:MM:SS}
+> 测试类型: {test_type}
+> 测试目录: {test_dir}
+
+## 已自动修复
+
+| # | 源码文件 | 方法 | Bug 描述 | 修复内容 | 触发用例 |
+|---|---------|------|---------|---------|---------|
+| 1 | MyService.js | create | 返回值逻辑错误 | 修正返回值 | should create with valid data |
+| 2 | Calculator.js | clamp | min/max 返回值互换 | 修正分支逻辑 | should clamp boundary |
+
+## 需人工处理
+
+| # | 源码文件 | 方法 | Bug 描述 | 原因 | 触发用例 |
+|---|---------|------|---------|------|---------|
+| 3 | OrderService.js | createOrder | 类型校验缺失 | 需业务确认预期行为 | should create order with invalid user id |
+| 4 | ConfigManager.js | getBool | truthy 逻辑反转 | 修复后语法错误已回滚，需人工分析 | should get bool unknown value |
+```
+
+**源码 Bug 判定规则**：
+
+| 条件 | 归类 |
+|------|------|
+| 阶段二判定为"源码逻辑有 bug"且阶段三成功修复 | 已自动修复 |
+| 阶段二判定为"源码逻辑有 bug"但修复后语法验证失败已回滚 | 需人工处理 |
+| 阶段二判定为"源码逻辑有 bug"但无法确定修复方案 | 需人工处理 |
+
+**文件写入规则**：
+- 路径：`{report_dir}/bug_list.md`
+- 目录不存在时自动创建
+- 每次内层 loop 执行时覆盖写入（保留最新状态）
+- 无源码 Bug 时仍写入文件，内容为"本次测试未发现源码 Bug"
+
+---
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| 有修复（修复数 > 0） | 输出修复记录，回到 Step 6（按 references/execute.md 执行） 重新执行 |
+| 无修复（全部标记人工处理） | 输出人工处理项，内层 loop 提前退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 修复后语法错误 | 回滚该文件修改，标记人工处理 |
+| 无法确定失败原因 | 记录详情，标记人工处理 |
+| 源码修复引入新问题 | 回滚源码修改，标记人工处理 |
+
+## 一定要做
+
+1. 必须按错误类型分类处理
+2. 修复测试优先于修复源码
+3. 一次只修一个失败
+4. 修改源码前必须保存原始内容（用于回滚）
+5. 修复后必须验证语法
+6. 源码修复后必须运行对应测试的快速验证（防止引入新问题）
+7. 语法错误或快速测试失败必须回滚（用原始内容覆盖）
+8. 无法修复的必须标记为人工处理
+9. 必须输出是否有修改的结论
+10. 修复源码的条目必须记录到源码 Bug 清单
+11. 源码 Bug 清单必须写入 `{report_dir}/bug_list.md`
+12. 无源码 Bug 时仍写入 bug_list.md，内容为"本次测试未发现源码 Bug"
+
+## 一定不要做
+
+1. 不要修改与失败无关的代码
+2. 不要修改 jest 配置文件或 setupFiles（除非直接导致失败）
+3. 不要在一次修复中改动多个文件（逐个修复）
+4. 不要跳过语法验证
+5. 不要跳过源码修复后的快速测试
+6. 不要忽略语法验证或快速测试失败（必须回滚）
+7. 不要尝试修复导入错误（标记人工处理）
+8. 不要在未保存原始内容的情况下修改源码（无法回滚）