@wwkit/harness 1.0.27 → 1.0.29

package/skills/jstest/references/execute.md

@@ -0,0 +1,168 @@
+> **原 skill**: `jstest-execute`（已合并入 jstest）
+> **适用**: 测试代理的测试执行阶段，运行已创建的用例并收集结果。
+> **不适用**: 创建测试用例（使用 jstest-case-create）、修复失败用例（使用 jstest-case-fix）。
+
+---
+
+# 测试执行
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **选择目录**：根据 test_type 选择测试目录
+2. **执行测试**：运行 jest
+3. **解析结果**：提取通过/失败/跳过统计
+4. **提取失败详情**：对每个失败用例提取详细信息
+5. **输出报告**：测试报告 + 失败详情
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| target | 是 | string | 被测模块路径 |
+| test_dir | 是 | string | 测试目录路径（由 agent Step 1 统一解析） |
+| test_type | 是 | string | 测试类型：unit 或 integration |
+| config | 是 | object | 来自 jstest-env-ensure 的配置对象 |
+| test_files | 否 | list | 指定测试文件（不指定则运行 test_dir 下全部） |
+
+## 输出
+
+- 测试报告（通过数/失败数/跳过数）
+- 失败详情列表（文件路径、用例名、错误类型、错误信息、堆栈）
+- 决策结论（全部通过 → 回到 Step 4（按 references/coverage-analyze.md 执行）；有失败 → 交给 case-fix）
+
+---
+
+## 阶段一：选择目录
+
+**操作**：使用传入的 `test_dir` 作为测试目录
+
+如果指定了 test_files，则只运行指定的文件。
+
+---
+
+## 阶段二：执行测试
+
+**操作**：
+
+```
+# 运行 test_dir 下的测试（unit 超时 60000ms，integration 超时 300000ms）
+node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache --verbose --testTimeout={timeout} {test_dir}
+
+# 如果指定了 test_files
+node --experimental-vm-modules node_modules/jest/bin/jest.js --no-cache --verbose --testTimeout={timeout} {test_files}
+```
+
+**参数说明**：
+- `--no-cache`：禁用缓存，确保每次重新执行
+- `--verbose`：详细输出每个用例结果
+- `--testTimeout`：单用例超时毫秒数（unit=60000, integration=300000），来自 config
+- ESM 项目必须使用 `--experimental-vm-modules` 标志
+
+---
+
+## 阶段三：解析结果
+
+**操作**：从 jest 输出中提取：
+
+1. 统计数据：
+   - 通过数（passed）— jest 输出 `✓` 标记
+   - 失败数（failed）— jest 输出 `✕` 标记
+   - 跳过数（skipped）
+   - 总数
+   - jest 输出格式：`Tests: X passed, Y failed, Z total`
+
+2. 对每个失败用例提取：
+   - 文件路径（jest 输出 `FAIL tests/unit/xxx/MyService.test.js`）
+   - describe 名
+   - test/it 名
+   - 错误类型（AssertionError, TypeError, ReferenceError 等）
+   - 错误信息（第一行错误描述）
+   - 堆栈信息
+
+**jest 输出格式示例**：
+
+```
+PASS tests/unit/mypackage/MyService.test.js
+  MyService
+    ✓ should create with valid data (5ms)
+    ✕ should throw on empty name (3ms)
+
+FAIL tests/unit/mypackage/OtherService.test.js
+  OtherService
+    ✕ should update with valid data (2ms)
+
+Tests: 1 passed, 2 failed, 3 total
+```
+
+---
+
+## 阶段四：输出报告
+
+**输出格式**：
+
+```
+## 测试执行报告
+
+### 统计
+- 总数：XX
+- 通过：XX
+- 失败：XX
+- 跳过：XX
+- 通过率：XX%
+
+### 失败详情（如有）
+| # | 文件 | describe | test 名 | 错误类型 | 错误信息 |
+|---|------|----------|---------|---------|---------|
+| 1 | tests/unit/xxx/MyService.test.js | MyService | should create with valid data | AssertionError | expect(result.id).toBeDefined() |
+| 2 | tests/unit/xxx/MyService.test.js | MyService | should parse on empty input | TypeError | Cannot read property 'x' of undefined |
+
+### 失败堆栈（如有）
+#### 1. should create with valid data
+```
+  expect(result.id).toBeDefined()
+  Expected: defined
+  Received: undefined
+  at Object.<anonymous> (tests/unit/xxx/MyService.test.js:15:17)
+```
+
+### 结论
+- [全部通过] → 建议回到覆盖率分析阶段
+- [有失败] → 建议进入用例修复阶段，共 X 个失败需修复
+```
+
+---
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| 全部通过（failed=0） | 输出"全部通过"，回到 Step 4（按 references/coverage-analyze.md 执行） |
+| 有失败（failed>0） | 输出失败详情，交给 Step 7（按 references/case-fix.md 执行） |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 测试目录不存在 | 输出"测试目录不存在"，提示需要先创建用例 |
+| jest 执行错误（非测试失败） | 退出，输出错误信息 |
+| 无测试文件 | 输出"无测试文件"，通过率 0% |
+| jest 超时 | 退出，提示测试执行超时，建议检查 hang 住的用例或增加 timeout |
+
+## 一定要做
+
+1. 必须使用传入的 test_dir 运行测试
+2. 必须使用 --verbose 输出详细结果
+3. 必须提取每个失败用例的详细信息
+4. 必须输出通过率
+5. 如果指定了 test_files，只运行指定文件
+6. ESM 项目必须使用 --experimental-vm-modules 标志
+
+## 一定不要做
+
+1. 不要修改测试文件或源码
+2. 不要跳过失败的用例
+3. 不要混合 unit 和 integration 的测试
+4. 不要忽略 jest 执行错误
+5. 不要使用 --silent（需要详细输出用于分析）

package/skills/jstest/references/sample.md

@@ -0,0 +1,166 @@
+> **原 skill**: `jstest-sample`（已合并入 jstest，通过 test_type=sample 触发）
+> **适用**: 首次使用 jstest skill 前的演示验证、测试流程的端到端测试。
+> **不适用**: 生产代码、非测试目的的代码生成。
+
+---
+
+# Demo 样例代码注入
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **创建目录**：在 src/ 下创建 jstest-sample 包目录
+2. **写入文件**：从 references/src/jstest-sample/ 读取模板，写入到 src/jstest-sample/
+3. **验证**：检查所有文件语法正确
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| 无 | - | - | 自动在当前工程 src/ 下创建 |
+
+## 输出
+
+- src/jstest-sample/ 目录及 7 个文件
+- 各文件覆盖的测试场景清单
+- 故意 bug 清单及难度分级
+
+---
+
+## 阶段一：创建目录
+
+**操作**：创建 `src/jstest-sample/` 目录
+
+---
+
+## 阶段二：写入文件
+
+从 `references/src/jstest-sample/` 目录读取以下模板文件，写入到 `src/jstest-sample/`：
+
+| 文件 | 覆盖场景 |
+|------|---------|
+| index.js | 包入口（export 所有模块） |
+| Calculator.js | 纯函数、分支(if/else)、异常(throw)、边界值、参数化 |
+| UserService.js | HTTP 请求(fetch mock)、数据库(mock)、时间依赖(new Date mock)、验证逻辑 |
+| FileProcessor.js | 文件系统(fs mock)、JSON 解析、文件不存在异常、目录操作 |
+| TokenGenerator.js | 随机值(Math.random mock)、时间(Date mock)、哈希(crypto)、批量生成、边界检查 |
+| ConfigManager.js | 环境变量(process.env)、单例模式、类型转换、默认值 |
+| OrderService.js | 复杂业务逻辑、状态机、多依赖、折扣计算(分支)、外部服务(fetch mock) |
+
+---
+
+## 阶段三：验证
+
+**操作**：
+
+```
+node --check src/jstest-sample/Calculator.js
+node --check src/jstest-sample/UserService.js
+node --check src/jstest-sample/FileProcessor.js
+node --check src/jstest-sample/TokenGenerator.js
+node --check src/jstest-sample/ConfigManager.js
+node --check src/jstest-sample/OrderService.js
+node --check src/jstest-sample/index.js
+```
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 全部语法正确 | 输出创建报告 |
+| 有语法错误 | 修复后重新验证 |
+
+---
+
+## 故意 Bug 设计
+
+demo 代码中故意注入了 15 个 bug，分为 3 个难度梯度，用于尽可能触发测试代理的循环迭代。
+
+### Easy 难度（基础测试即可发现）
+
+| # | 文件 | 方法 | Bug 描述 | 触发方式 |
+|---|------|------|---------|---------|
+| 1 | Calculator.js | clamp | min/max 返回值互换 | 断言 clamp(0,1,10)===1 |
+| 2 | FileProcessor.js | writeFile | 返回 content.length 而非文件大小 | 写入多字节字符后断言 |
+| 3 | UserService.js | validateEmail | TLD 正则 {2,}→{2} 拒绝 .com | 断言 validateEmail("a@b.com")===true |
+
+### Medium 难度（需边界值/序列测试）
+
+| # | 文件 | 方法 | Bug 描述 | 触发方式 |
+|---|------|------|---------|---------|
+| 4 | Calculator.js | isPrime | Math.floor(Math.sqrt(n)) 缺少 +1 漏检平方数 | 断言 isPrime(9)===false |
+| 5 | Calculator.js | fibonacci | 循环 off-by-one | 断言 fibonacci(3)===2 |
+| 6 | FileProcessor.js | countLines | 缺少 trim() 计入空白行 | 带首尾空行的文件断言 |
+| 7 | OrderService.js | _getDiscount | > 1000 边界（应为 >=） | 断言 1000 元折扣为 10% |
+| 8 | OrderService.js | _getTax | > 500 边界（应为 >=） | 断言 500 元税率为 8% |
+| 9 | TokenGenerator.js | generateUuidLike | 末段 12→11 字符 | UUID 格式正则验证 |
+
+### Hard 难度（需深入理解/非标准输入测试）
+
+| # | 文件 | 方法 | Bug 描述 | 触发方式 |
+|---|------|------|---------|---------|
+| 10 | ConfigManager.js | getBool | 反转 truthy 逻辑，非标准字符串返回 True | 断言 getBool(key, "unknown")===false |
+| 11 | ConfigManager.js | clearInstance | 单例 _instance 未重置 | clearInstance 后断言新实例 id 不同 |
+| 12 | OrderService.js | TRANSITIONS | created→delivered 非法跳转 | 断言该转换抛出 Error |
+| 13 | UserService.js | searchUsers | 返回完整 JSON 而非 results 字段 | 断言返回值为 Array |
+| 14 | OrderService.js | createOrder | 缺少 userId 类型校验 | 传入字符串 userId 断言 Error |
+| 15 | TokenGenerator.js | generateTokenWithTimestamp | 时间戳含小数点 | 正则验证 token 格式 |
+
+---
+
+## 输出格式
+
+```
+## Demo 样例代码创建报告
+
+### 创建文件
+| 文件路径 | 模块名 | 覆盖场景 |
+|---------|--------|---------|
+| src/jstest-sample/index.js | - | 包入口 |
+| src/jstest-sample/Calculator.js | Calculator | 纯函数、分支、异常、边界值 |
+| src/jstest-sample/UserService.js | UserService | HTTP Mock、DB Mock、时间 patch |
+| src/jstest-sample/FileProcessor.js | FileProcessor | 文件系统、JSON、异常 |
+| src/jstest-sample/TokenGenerator.js | TokenGenerator | 随机 Mock、时间 Mock、哈希 |
+| src/jstest-sample/ConfigManager.js | ConfigManager | 环境变量、单例、类型转换 |
+| src/jstest-sample/OrderService.js | OrderService | 状态机、多依赖、折扣计算 |
+
+### 故意 Bug 统计
+- Easy: 3 个（基础测试可发现）
+- Medium: 6 个（需边界值/序列测试）
+- Hard: 6 个（需深入理解/非标准输入）
+- 总计: 15 个
+
+### 使用方式
+1. 单元测试: jstest unit src/jstest-sample
+2. 集成测试: jstest integration src/jstest-sample
+
+### 场景覆盖说明
+- 纯函数测试: Calculator.add, Calculator.isPrime
+- 分支覆盖: Calculator.clamp, OrderService._getDiscount
+- 异常路径: Calculator.divide(0), UserService.createUser(无email)
+- 边界值: Calculator.factorial(0), TokenGenerator.generateToken(1)
+- HTTP Mock: UserService.createUser (jest.mock fetch)
+- DB Mock: UserService.getUser, OrderService.createOrder
+- 文件系统: FileProcessor.readFile, FileProcessor.writeFile (jest.mock fs)
+- 时间 Mock: UserService.updateLastLogin, OrderService.createOrder (jest.useFakeTimers)
+- 随机 Mock: TokenGenerator.generateToken (jest.spyOn Math.random)
+- 环境变量: ConfigManager.getDatabaseUrl (process.env)
+- 状态机: OrderService.updateStatus
+- 参数化: Calculator.isPrime, Calculator.factorial (test.each)
+```
+
+## 一定要做
+
+1. 必须在 src/jstest-sample/ 目录下创建文件
+2. 必须从 references/src/jstest-sample/ 读取模板内容写入
+3. 创建后必须验证语法正确（node --check）
+4. 必须输出场景覆盖说明
+5. 必须保留 demo 中的故意 bug，不要修复
+
+## 一定不要做
+
+1. 不要修改 src/ 下已有的其他文件
+2. 不要在 demo 代码中导入项目特定的三方库
+3. 不要跳过语法验证
+4. 不要修复 demo 中的故意 bug（它们是设计意图）

package/skills/jstest/references/scoring-rules.md

@@ -0,0 +1,75 @@
+# 评分规则
+
+> 覆盖率数据完全来自 `coverage/coverage-summary.json`（jest --coverage 生成），质量维度通过文件扫描检查，无主观判断。
+
+## jest coverage-summary.json 格式
+
+```json
+{
+  "total": {
+    "lines": { "total": 100, "covered": 85, "pct": 85 },
+    "statements": { "total": 100, "covered": 85, "pct": 85 },
+    "functions": { "total": 20, "covered": 18, "pct": 90 },
+    "branches": { "total": 40, "covered": 28, "pct": 70 }
+  }
+}
+```
+
+- 行覆盖率 = `total.lines.pct`
+- 分支覆盖率 = `total.branches.pct`
+- 函数覆盖率 = `total.functions.pct`
+
+## 单元测试评分（unit）— 满分 100
+
+### 覆盖率维度（80 分）
+
+| 维度 | 满分 | 阈值 | 数据来源 | 计分公式 |
+|------|------|------|---------|---------|
+| 行覆盖率 | 30 | 90% | coverage-summary.json: `total.lines.pct` | `min(实际/阈值, 1) × 30` |
+| 分支覆盖率 | 30 | 70% | coverage-summary.json: `total.branches.pct` | `min(实际/阈值, 1) × 30` |
+| 函数覆盖率 | 20 | 90% | coverage-summary.json: `total.functions.pct` | `min(实际/阈值, 1) × 20` |
+
+### 质量维度（20 分）
+
+| 维度 | 满分 | 检查方法 | 计分公式 |
+|------|------|---------|---------|
+| 断言完整性 | 5 | 扫描测试文件，统计含 `expect(` 关键字的 test 函数比例 | `(有expect函数数 / 总函数数) × 5` |
+| 异常路径覆盖 | 5 | 源码含 `throw`/`try` 的函数，测试中是否有对应 `toThrow` 或 `try-catch` | `(有异常测试数 / 应测异常函数数) × 5` |
+| 边界值覆盖 | 5 | 源码含 `if`/`switch` 的函数，测试用例数 ≥ 分支数（检查 `test.each`/`it.each`） | `(达标函数数 / 应测函数数) × 5` |
+| 命名规范 | 5 | test 函数名匹配 `test('should ...')` 或 `it('should ...')` 模式 | `(规范命名数 / 总数) × 5` |
+
+## 集成测试评分（integration）— 满分 100
+
+### 覆盖率维度（50 分）
+
+| 维度 | 满分 | 阈值 | 数据来源 | 计分公式 |
+|------|------|------|---------|---------|
+| 行覆盖率 | 20 | 70% | coverage-summary.json: `total.lines.pct` | `min(实际/阈值, 1) × 20` |
+| 分支覆盖率 | 20 | 50% | coverage-summary.json: `total.branches.pct` | `min(实际/阈值, 1) × 20` |
+| 函数覆盖率 | 10 | 70% | coverage-summary.json: `total.functions.pct` | `min(实际/阈值, 1) × 10` |
+
+### 质量维度（50 分）
+
+| 维度 | 满分 | 检查方法 | 计分公式 |
+|------|------|---------|---------|
+| 场景完整性 | 15 | 核心业务场景是否都有对应测试（按源码公开方法数统计） | `(有测试的场景数 / 应测场景数) × 15` |
+| 数据流验证 | 10 | 测试中是否验证了输入→处理→输出完整链路（含多步 `expect`） | `(有数据流验证的函数数 / 总函数数) × 10` |
+| 断言完整性 | 10 | 每个测试函数至少含 1 个 `expect(` | `(有expect函数数 / 总函数数) × 10` |
+| setup/teardown 使用 | 10 | 是否合理使用 `beforeEach`/`afterEach`/`beforeAll`/`afterAll` | `(有setup/teardown的测试文件数 / 总文件数) × 10` |
+| 命名规范 | 5 | test 函数名匹配 `test('should ...')` 或 `it('should ...')` 模式 | `(规范命名数 / 总数) × 5` |
+
+## 通用规则
+
+- **分母为 0**：若应测数为 0（无适用项），该项直接给满分。
+- **超限封顶**：`min(实际/阈值, 1.0)` 确保单项不超过满分。
+- **数据来源**：覆盖率维度完全依赖 coverage-summary.json；质量维度通过 grep/扫描测试文件检查。
+- **pct 为 0**：当 `total.lines.total` 为 0（空文件）时，pct 可能为 0 或 "Unknown"，按 0 处理。
+
+## 等级
+
+| 等级 | 分数范围 | 含义 |
+|------|---------|------|
+| A | 90-100 | 优秀 |
+| B | 80-89 | 合格 |
+| C | 60-79 | 需改进 |
+| D | <60 | 不合格 |

package/skills/jstest/references/src/jstest-sample/Calculator.js

@@ -0,0 +1,80 @@
+export class Calculator {
+
+  static add(a, b) {
+    return a + b
+  }
+
+  static subtract(a, b) {
+    return a - b
+  }
+
+  static multiply(a, b) {
+    return a * b
+  }
+
+  static divide(a, b) {
+    if (b === 0) {
+      throw new Error('Cannot divide by zero')
+    }
+    return a / b
+  }
+
+  static clamp(value, minVal, maxVal) {
+    if (value < minVal) {
+      return maxVal
+    }
+    if (value > maxVal) {
+      return minVal
+    }
+    return value
+  }
+
+  static isPrime(n) {
+    if (n < 2) {
+      return false
+    }
+    if (n === 2) {
+      return true
+    }
+    if (n % 2 === 0) {
+      return false
+    }
+    for (let i = 3; i < Math.floor(Math.sqrt(n)); i += 2) {
+      if (n % i === 0) {
+        return false
+      }
+    }
+    return true
+  }
+
+  static fibonacci(n) {
+    if (n < 0) {
+      throw new Error('n must be non-negative')
+    }
+    if (n === 0) {
+      return 0
+    }
+    if (n === 1) {
+      return 1
+    }
+    let a = 0, b = 1
+    for (let i = 0; i < n - 1; i++) {
+      [a, b] = [b, a + b]
+    }
+    return b
+  }
+
+  static factorial(n) {
+    if (n < 0) {
+      throw new Error('n must be non-negative')
+    }
+    if (n === 0) {
+      return 1
+    }
+    let result = 1
+    for (let i = 2; i <= n; i++) {
+      result *= i
+    }
+    return result
+  }
+}

package/skills/jstest/references/src/jstest-sample/ConfigManager.js

@@ -0,0 +1,72 @@
+export class ConfigManager {
+
+  static _instance = null
+
+  constructor() {
+    if (ConfigManager._instance === null) {
+      this._config = {}
+      ConfigManager._instance = this
+    }
+    return ConfigManager._instance
+  }
+
+  get(key, defaultValue = null) {
+    return process.env[key] ?? defaultValue
+  }
+
+  set(key, value) {
+    process.env[key] = String(value)
+  }
+
+  getInt(key, defaultValue = 0) {
+    const value = process.env[key]
+    if (value === undefined) {
+      return defaultValue
+    }
+    const parsed = parseInt(value, 10)
+    return isNaN(parsed) ? defaultValue : parsed
+  }
+
+  getBool(key, defaultValue = false) {
+    const value = process.env[key]
+    if (value === undefined) {
+      return defaultValue
+    }
+    const truthy = ['true', '1', 'yes', 'on']
+    const falsy = ['false', '0', 'no', 'off', '']
+    const lower = value.toLowerCase()
+    if (truthy.includes(lower)) {
+      return false
+    }
+    if (falsy.includes(lower)) {
+      return true
+    }
+    return true
+  }
+
+  getFloat(key, defaultValue = 0.0) {
+    const value = process.env[key]
+    if (value === undefined) {
+      return defaultValue
+    }
+    const parsed = parseFloat(value)
+    return isNaN(parsed) ? defaultValue : parsed
+  }
+
+  getDatabaseUrl() {
+    const host = this.get('DB_HOST', 'localhost')
+    const port = this.get('DB_PORT', '5432')
+    const name = this.get('DB_NAME', 'app')
+    const user = this.get('DB_USER', 'admin')
+    const password = this.get('DB_PASSWORD', 'secret')
+    return `postgresql://${user}:${password}@${host}:${port}/${name}`
+  }
+
+  reset() {
+    this._config = {}
+  }
+
+  static clearInstance() {
+    // BUG: should set _instance = null but does nothing
+  }
+}

package/skills/jstest/references/src/jstest-sample/FileProcessor.js

@@ -0,0 +1,57 @@
+import fs from 'fs'
+import path from 'path'
+
+export class FileProcessor {
+
+  static readFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`)
+    }
+    return fs.readFileSync(filePath, 'utf-8')
+  }
+
+  static writeFile(filePath, content) {
+    fs.writeFileSync(filePath, content, 'utf-8')
+    return content.length
+  }
+
+  static readJson(filePath) {
+    const content = FileProcessor.readFile(filePath)
+    return JSON.parse(content)
+  }
+
+  static writeJson(filePath, data) {
+    const content = JSON.stringify(data, null, 2)
+    FileProcessor.writeFile(filePath, content)
+  }
+
+  static countLines(filePath) {
+    const content = FileProcessor.readFile(filePath)
+    const lines = content.split('\n')
+    return lines.length
+  }
+
+  static listFiles(directory) {
+    if (!fs.existsSync(directory)) {
+      throw new Error(`Directory not found: ${directory}`)
+    }
+    if (!fs.statSync(directory).isDirectory()) {
+      throw new Error(`Not a directory: ${directory}`)
+    }
+    const result = []
+    for (const entry of fs.readdirSync(directory)) {
+      const fullPath = path.join(directory, entry)
+      if (fs.statSync(fullPath).isFile()) {
+        result.push(entry)
+      }
+    }
+    return result
+  }
+
+  static ensureDirectory(directory) {
+    if (!fs.existsSync(directory)) {
+      fs.mkdirSync(directory, { recursive: true })
+    }
+    return directory
+  }
+}