@wwkit/harness 1.0.9 → 1.0.10

package/skills/pytest-case-create/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: pytest-case-create
+description: |
+  按测试规范创建 pytest 测试用例。根据 test_type 切换 Mock 策略，分析源码识别未覆盖区域，按 AAA/FIRST/边界值规范创建用例。
+  适用：测试代理外层 loop 的用例创建阶段，为未覆盖代码创建测试用例。
+  不适用：修复已有失败用例（使用 pytest-case-fix）、非 pytest 框架的用例创建。
+---
+
+# 测试用例创建
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **扫描已有测试**：检查目标模块是否已有测试文件，提取已有方法名
+2. **加载规范**：读取用例创建规范
+3. **分析源码**：识别未覆盖的函数、分支、异常路径
+4. **决策 Mock 策略**：按 test_type 选择 Mock 策略
+5. **创建用例**：增量追加或全新创建
+6. **语法验证**：验证创建的测试文件语法正确
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| uncovered_areas | 是 | list/string | 未覆盖区域清单（来自 pytest-coverage-analyze，首轮为 "all"） |
+| testable_classes | 否 | list | 可测试类清单（来自 pytest-suitability-check，含文件路径+类名+分类） |
+| target | 是 | string | 被测模块路径 |
+| test_dir | 是 | string | 测试目录路径（由 agent Step 1 统一解析） |
+| test_type | 是 | string | 测试类型：unit 或 integration |
+| config | 是 | object | 来自 pytest-env-ensure 的配置对象 |
+
+## 输出
+
+- 新增/追加的测试文件列表（标注是全新创建还是增量追加）
+- 每个文件新增的用例数
+- 跳过的重复用例数
+
+---
+
+## 阶段零：扫描已有测试
+
+**操作**：使用 agent 传入的 `test_dir` 直接扫描已有测试，确定工作模式
+
+1. 直接使用传入的 `test_dir` 路径（不再自行推导目录映射）
+
+2. 扫描该目录下是否已有 `test_*.py` 文件
+
+3. **无已有文件** → 标记为 `全新模式`，直接进入阶段一
+
+4. **有已有文件** → 标记为 `增量模式`，执行以下操作：
+   - 逐个读取已有测试文件
+   - 提取已有测试方法名集合（`def test_xxx` 的完整方法名）
+   - 提取已有 import 语句和 fixture 定义
+   - 记录已有测试类名
+
+**决策**：
+
+| 模式 | 后续行为 |
+|------|---------|
+| 全新模式 | 创建新文件，从头编写用例 |
+| 增量模式 | 在已有文件中追加方法，跳过已存在的方法名 |
+
+---
+
+## 阶段一：加载规范
+
+**操作**：读取 `references/test-standards.md`，加载：
+- 通用规范（AAA、FIRST、命名）
+- Python/pytest 特定规范（fixture、mock、parametrize）
+- test_type 对应的专属规范
+
+---
+
+## 阶段二：分析源码
+
+**输入**：uncovered_areas 清单 + testable_classes 清单（如有）
+
+**操作**：
+
+1. 确定待分析源码范围：
+   - 如果 `uncovered_areas == "all"`（首轮）：扫描 target 目录下所有 .py 文件
+   - 如果 `uncovered_areas` 为列表：仅读取列表中的未覆盖文件
+   - 如果提供了 `testable_classes`：仅分析清单中列出的类，跳过不在清单中的类
+
+2. 逐个读取待分析的源码文件
+
+3. 分析每个未覆盖函数：
+   - 函数签名（参数、返回值）
+   - 内部分支（if/elif/else）
+   - 异常处理（raise/try-except）
+   - 外部依赖（import 的模块、调用的外部方法）
+
+4. 识别需要创建的用例类型：
+   - 正向用例（每个公开函数至少 1 个）
+   - 边界值用例（有 if/elif 分支的函数）
+   - 异常路径用例（有 raise/try 的函数）
+   - 参数化用例（多输入场景）
+
+---
+
+## 阶段三：决策 Mock 策略
+
+**操作**：根据 test_type 从 config 读取 mock_strategy
+
+### unit — mock_strategy=full
+
+按依赖类型选择 Mock 方式：
+
+| 依赖类型 | 处理策略 |
+|---------|---------|
+| HTTP 请求 | `@patch('requests.get')` 等，预设 return_value |
+| 数据库 | Fake 内存数据库 或 `@patch('db.connect')` |
+| 文件系统 | `tmp_path` fixture |
+| 时间依赖 | `@patch('datetime.now')` |
+| 随机值 | `@patch('random')` 或 `random.seed(42)` |
+| 外部服务 | `@patch('email.send')` 等，验证调用参数 |
+| 环境变量 | `monkeypatch.setenv('KEY', 'val')` |
+| 内部模块 | 优先真实调用，仅 Mock 有副作用的子模块 |
+
+### integration — mock_strategy=minimal
+
+| 依赖类型 | 处理策略 |
+|---------|---------|
+| 内部模块 | 真实调用，不 Mock |
+| 数据库 | 真实连接（测试库）或 Fake 内存数据库 |
+| 文件系统 | 真实文件操作（使用 tmp_path 清理） |
+| 外部 API | 仅 Mock 不可控的生产 API |
+| 时间/随机 | 可接受真实值，或 seed 固定 |
+
+---
+
+## 阶段四：创建用例
+
+**操作**：
+
+### 全新模式
+
+1. 使用传入的 `test_dir` 确定测试文件路径：
+   ```
+   test_dir: tests/unit/mypackage/
+   源码文件: src/mypackage/MyService.py
+   测试文件: tests/unit/mypackage/test_MyService.py
+   ```
+
+2. 按命名规范创建测试文件：
+   - 文件名：`test_{ModuleName}.py`
+   - 类名：`test_{ModuleName}`（与文件名一致）
+   - 方法名：`test_{action}_{expected}`
+   - 2 空格缩进
+   - 类格式
+
+3. 按 AAA 模式编写每个用例：
+   - Arrange — 准备数据、Mock、fixture
+   - Act — 调用被测方法
+   - Assert — 断言结果
+
+### 增量模式
+
+1. 确定目标测试文件（已存在）
+2. 读取已有文件内容，保留全部已有代码不动
+3. 对照阶段零提取的已有方法名集合，跳过已存在的方法
+4. 在已有测试类中追加新方法：
+   - 方法名：`test_{action}_{expected}`（不与已有方法重名）
+   - 仍遵循 AAA 模式
+   - 复用已有的 import 和 fixture，仅在需要时追加 import
+5. 如果已有文件中没有对应的测试类（源码新增了模块），则在该文件中新增类
+
+**通用规则**（两种模式共用）：
+
+1. 按用例类型创建：
+   - 正向用例：正常输入 → 预期输出
+   - 边界用例：边界值 → 预期行为
+   - 异常用例：非法输入 → `pytest.raises`
+   - 参数化用例：`@pytest.mark.parametrize`
+
+2. 添加 pytest marker：
+   - unit: `@pytest.mark.unit`
+   - integration: `@pytest.mark.integration`
+
+3. 检查 conftest.py（沿父目录向上查找）：
+   - 检查 test_dir 下是否有 conftest.py → 有则不修改
+   - 检查 test_dir 的父目录（tests/unit/ 或 tests/integration/、tests/）是否有 conftest.py → 有则不创建，提示"父目录已有 conftest.py"
+   - 均无 conftest.py → 在 test_dir 下创建，仅含通用 fixture
+   - 不导入任何项目特定的三方库
+
+**创建示例**：
+
+```python
+import pytest
+
+@pytest.mark.unit
+class test_MyService:
+
+  def test_create_with_valid_data(self):
+    # Arrange
+    service = MyService()
+    # Act
+    result = service.create({"name": "test"})
+    # Assert
+    assert result.id is not None
+
+  @pytest.mark.parametrize("name,valid", [
+    ("", False),
+    (None, False),
+    ("a" * 1000, False),
+    ("test", True),
+  ])
+  def test_create_validates_name(self, name, valid):
+    service = MyService()
+    if valid:
+      result = service.create({"name": name})
+      assert result is not None
+    else:
+      with pytest.raises(ValueError):
+        service.create({"name": name})
+```
+
+---
+
+## 阶段五：语法验证
+
+**操作**：
+
+1. 对每个新创建的测试文件运行语法检查：
+   ```
+   uv run python -m py_compile "<test_file>"
+   ```
+
+2. 语法错误 → 修复后重新验证
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 全部语法正确 | 输出创建结果 |
+| 有语法错误 | 修复后重新验证，最多 3 次 |
+| 修复 3 次仍失败 | 记录错误，跳过该文件 |
+
+---
+
+## 输出格式
+
+```
+## 用例创建报告
+
+### 工作模式
+- 模式: [全新模式 / 增量模式]
+- 已有测试文件: X 个（增量模式时显示）
+
+### 新增/追加测试文件
+| 文件路径 | 模式 | 新增用例数 | 跳过重复 | 覆盖函数 |
+|---------|------|-----------|---------|---------|
+| tests/unit/mypackage/test_MyService.py | 全新创建 | 8 | 0 | create, validate, parse |
+| tests/unit/mypackage/test_OtherService.py | 增量追加 | 3 | 2 | update, delete |
+
+### 用例明细
+| 方法名 | 类型 | 被测函数 |
+|--------|------|---------|
+| test_create_with_valid_data | 正向 | create |
+| test_create_raises_on_empty_name | 异常 | create |
+| test_validate_age_boundary | 边界 | validate |
+
+### Mock 使用
+| 依赖类型 | Mock 方式 |
+|---------|---------|
+| HTTP | @patch requests.get |
+| 文件 | tmp_path fixture |
+```
+
+### 0 新用例检测
+
+阶段四完成后，统计新增用例总数。如果为 0（所有方法均已存在），输出特殊标记：
+
+```
+## 用例创建报告
+
+### 工作模式
+- 模式: 增量模式
+- 新增用例数: 0
+
+### 结论
+- [0 新用例] 所有未覆盖区域已有对应测试，无法通过新增用例提升覆盖率
+- 建议: 检查已有用例质量（断言完整性、边界值覆盖），或确认覆盖率瓶颈原因
+```
+
+agent 收到此标记后，应跳过 execute + fix，直接回到 coverage-analyze 重新评分或判定"无改进"退出。
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 源码文件不存在 | 跳过，记录警告 |
+| 源码无法分析（语法错误） | 跳过，记录错误 |
+| 测试目录不存在 | 自动创建 |
+| 语法验证失败 | 修复重试，最多 3 次 |
+| conftest.py 已存在 | 不修改 |
+| 已有测试文件语法错误 | 跳过该文件的追加，记录警告 |
+| uncovered_areas 为空列表 | 输出"无需新建用例，建议改进已有用例质量"，返回给 agent |
+| 新增用例数为 0（全部重复） | 输出"0 新用例"标记，agent 应跳过 execute+fix |
+
+## 一定要做
+
+1. 必须先扫描已有测试文件，确定工作模式（全新/增量）
+2. 增量模式下必须保留已有代码不动，只追加新方法
+3. 必须根据 test_type 选择对应的 Mock 策略
+4. 如果提供了 testable_classes，必须仅对清单中的类创建测试，跳过不在清单中的类
+5. 如果 uncovered_areas 为 "all"（首轮），必须扫描全部源码文件
+6. 必须遵循命名规范（test_ 前缀文件名和类名）
+7. 必须遵循 AAA 模式
+8. 必须为每个未覆盖函数创建至少 1 个正向用例
+9. 有分支的函数必须创建边界值用例
+10. 有异常处理的函数必须创建异常路径用例
+11. 创建后必须验证语法正确
+12. 必须添加对应的 pytest marker
+13. 遵循 AGENTS.md：2 空格缩进、类格式、文件名=类名
+
+## 一定不要做
+
+1. 不要修改源码文件
+2. 不要覆盖已有测试文件中的已有方法
+3. 不要创建与现有测试重复的用例（方法名相同的跳过）
+4. 不要在单元测试中使用真实网络/文件/时间调用
+5. 不要修改已存在的 conftest.py
+6. 不要导入项目特定的三方库到 conftest.py
+7. 不要跳过语法验证
+8. 不要使用 Test 前缀的类名（统一用 test_ 前缀）

package/skills/pytest-case-create/references/test-standards.md

@@ -0,0 +1,244 @@
+# 测试用例创建规范
+
+> 本规范适用于 Python pytest 测试框架，包含通用规范、Python 特定规范、以及单元/集成测试专属规范。
+
+## 一、通用规范
+
+### AAA 模式（Arrange-Act-Assert）
+
+每个测试方法分为三段：
+
+```python
+def test_create_with_valid_data(self):
+  # Arrange — 准备
+  service = MyService()
+  data = {"name": "test", "age": 18}
+
+  # Act — 执行
+  result = service.create(data)
+
+  # Assert — 断言
+  assert result.id is not None
+  assert result.name == "test"
+```
+
+### FIRST 原则
+
+| 原则 | 说明 |
+|------|------|
+| Fast | 快速执行（单元测试秒级，集成测试分钟级） |
+| Isolated | 测试间相互独立，不依赖执行顺序 |
+| Repeatable | 可重复运行，结果稳定 |
+| Self-Validating | 自动断言，无需人工判断 |
+| Timely | 与开发同步编写 |
+
+### 命名规范
+
+| 元素 | 规则 | 示例 |
+|------|------|------|
+| 文件名 | `test_{ModuleName}.py` | `test_MyService.py` |
+| 类名 | `test_{ModuleName}`（与文件名一致） | `test_MyService` |
+| 方法名 | `test_{action}_{expected}` | `test_create_raises_on_empty_input` |
+
+方法命名要素：
+- **action**：被测方法名或核心行为（create, send, parse）
+- **expected**：输入条件或预期结果（with_valid_data, raises_on_timeout）
+
+### 一个方法一个行为
+
+每个测试方法只验证一个行为，不混合多个断言逻辑。
+
+## 二、Python/pytest 特定规范
+
+### 类格式
+
+遵循 AGENTS.md 规则：
+- 2 空格缩进
+- 类风格（非函数式）
+- 文件名与类名一致
+- 一个文件内只定义一个类
+
+```python
+import pytest
+
+class test_MyService:
+
+  def test_create_with_valid_data(self):
+    # Arrange
+    service = MyService()
+    # Act
+    result = service.create({"name": "test"})
+    # Assert
+    assert result.id is not None
+```
+
+### fixture 使用
+
+```python
+import pytest
+
+class test_MyService:
+
+  @pytest.fixture
+  def service(self):
+    return MyService()
+
+  @pytest.fixture
+  def valid_data(self):
+    return {"name": "test", "age": 18}
+
+  def test_create_with_valid_data(self, service, valid_data):
+    result = service.create(valid_data)
+    assert result.id is not None
+```
+
+### Mock/Stub 使用
+
+```python
+from unittest.mock import Mock, patch
+
+class test_MyService:
+
+  @patch('mypackage.MyService.fetch_remote')
+  def test_process_returns_data_from_remote(self, mock_fetch):
+    # Stub — 预设返回值
+    mock_fetch.return_value = {"key": "value"}
+
+    service = MyService()
+    result = service.process()
+
+    # Mock — 验证调用行为
+    mock_fetch.assert_called_once()
+    assert result["key"] == "value"
+```
+
+### 参数化测试
+
+```python
+class test_MyValidator:
+
+  @pytest.mark.parametrize("input,expected", [
+    (18, True),
+    (30, True),
+    (60, True),
+    (17, False),
+    (61, False),
+    (-1, False),
+  ])
+  def test_validate_age(self, input, expected):
+    assert MyValidator.validate_age(input) == expected
+```
+
+### 异常断言
+
+```python
+class test_MyService:
+
+  def test_create_raises_on_empty_name(self):
+    service = MyService()
+    with pytest.raises(ValueError, match="name不能为空"):
+      service.create({"name": ""})
+```
+
+### pytest marker
+
+```python
+@pytest.mark.unit
+class test_MyService:
+  # 单元测试
+
+@pytest.mark.integration
+class test_LoginFlow:
+  # 集成测试
+```
+
+## 三、单元测试专属规范（unit）
+
+### Mock 策略：full — 全部 Mock 外部依赖
+
+| 依赖类型 | 处理策略 | 示例 |
+|---------|---------|------|
+| HTTP 请求 | Mock：patch 请求方法，预设返回值 | `@patch('requests.get')` |
+| 数据库操作 | Fake：内存数据库 或 patch 连接层 | `@patch('db.connect')` |
+| 文件系统 | Fake：使用 `tmp_path` fixture | `def test_read(self, tmp_path)` |
+| 时间依赖 | Mock：patch datetime.now | `@patch('datetime.now')` |
+| 随机值 | Mock：patch random 或设 seed | `random.seed(42)` |
+| 外部服务 | Mock：patch 发送方法 | `@patch('email.send')` |
+| 环境变量 | Stub：monkeypatch.setenv | `monkeypatch.setenv('KEY', 'val')` |
+
+### 用例覆盖要求
+
+| 源码特征 | 必须创建的用例 |
+|---------|---------------|
+| 每个公开函数 | 至少 1 个正向用例 |
+| 含 if/elif 分支 | 边界值用例（每个分支至少 1 个） |
+| 含 raise/try-except | 异常路径用例（pytest.raises） |
+| 多输入场景 | 参数化用例（@pytest.mark.parametrize） |
+| 有返回值 | 断言返回值类型和内容 |
+
+### 禁止事项
+
+- 禁止真实网络调用
+- 禁止操作真实文件系统
+- 禁止依赖真实时间
+- 禁止依赖随机值
+- 禁止测试间依赖（共享状态）
+- 禁止硬编码路径
+
+## 四、集成测试专属规范（integration）
+
+### Mock 策略：minimal — 最少 Mock，优先真实调用
+
+| 依赖类型 | 处理策略 |
+|---------|---------|
+| 内部模块 | 真实调用，不 Mock |
+| 数据库 | 真实连接（测试库）或 Fake 内存数据库 |
+| 文件系统 | 真实文件操作（使用 tmp_path 清理） |
+| 外部 API | 仅 Mock 不可控的生产 API，测试环境 API 真实调用 |
+| 时间/随机 | 可接受真实值，或 seed 固定 |
+
+### 用例组织
+
+- 按 **业务场景** 组织用例，不按函数
+- 每个场景覆盖完整流程：输入 → 处理 → 输出
+- 验证端到端数据流完整性
+
+```python
+@pytest.mark.integration
+class test_OrderFlow:
+
+  def test_create_order_and_send_notification(self, tmp_path):
+    # 场景：创建订单并发送通知
+    # Arrange
+    db = Database(test_url)
+    service = OrderService(db=db)
+
+    # Act
+    order = service.create_order(user_id=1, item="book")
+    notification = service.send_notification(order.id)
+
+    # Assert — 验证完整数据流
+    assert order.id is not None
+    assert order.status == "created"
+    assert notification.order_id == order.id
+    assert notification.sent is True
+```
+
+### fixture 使用
+
+- 使用 `scope="class"` 的 fixture 共享 setup
+- teardown 负责清理测试数据
+- 数据准备放在 fixture 中，不硬编码在测试方法内
+
+## 五、稳定性保障规则
+
+| 规则 | 说明 |
+|------|------|
+| 禁止真实网络 | 单元测试所有 HTTP 必须 Mock |
+| 禁止真实文件 | 文件操作使用 tmp_path fixture |
+| 禁止真实时间 | 时间依赖必须 patch |
+| 禁止真实随机 | 随机值必须 patch 或 seed |
+| 禁止真实外部服务 | 邮件/消息队列等必须 Mock（单元测试） |
+| 禁止测试间依赖 | 每个测试独立，不依赖执行顺序 |
+| 禁止硬编码路径 | 使用 fixture 或相对路径 |
+| fixture 作用域 | class 级用 scope="class"，函数级用默认 |