tdd-pytest

TDD-Pytest 技能

在用户需要以下帮助时激活此技能：

• 使用 TDD 方法（Red-Green-Refactor）编写测试
• 审查现有 pytest 测试文件的质量
• 运行测试并检查覆盖率
• 生成测试报告至 TESTING_REPORT.local.md
• 在 pyproject.toml 中设置 pytest 配置

TDD 工作流

Red-Green-Refactor 循环

1. RED - 先编写一个失败的测试

   • 测试应因正确的原因失败（而非导入错误）
   • 测试应简洁且目标明确
   • 展示失败的测试输出

2. GREEN - 编写能通过测试的最少代码

   • 只实现通过测试所需的内容
   • 不要过早优化
   • 展示通过的测试输出

3. REFACTOR - 在保持测试通过的同时改进代码

   • 清理重复代码
   • 改进命名
   • 根据需要提取函数/类
   • 每次修改后运行测试

测试组织

文件结构

project/
  src/
    module.py
  tests/
    conftest.py          # Shared fixtures
    test_module.py       # Tests for module.py
  pyproject.toml         # Pytest configuration

命名约定

• 测试文件：test_*.py 或 *_test.py
• 测试函数：test_*
• 测试类：Test*
• Fixture：使用描述性名称（mock_database、sample_user）

Pytest 最佳实践

Fixture

import pytest

@pytest.fixture
def sample_config():
    return {"key": "value"}

@pytest.fixture
def mock_client(mocker):
    return mocker.MagicMock()

参数化

@pytest.mark.parametrize("input,expected", [
    ("hello", "HELLO"),
    ("world", "WORLD"),
    ("", ""),
])
def test_uppercase(input, expected):
    assert input.upper() == expected

异步测试

import pytest

@pytest.mark.asyncio
async def test_async_function():
    result = await async_operation()
    assert result == expected

异常测试

def test_raises_value_error():
    with pytest.raises(ValueError, match="invalid input"):
        process_input(None)

运行测试

使用 uv

uv run pytest                              # Run all tests
uv run pytest tests/test_module.py         # Run specific file
uv run pytest -k "test_name"               # Run by name pattern
uv run pytest -v --tb=short                # Verbose with short traceback
uv run pytest --cov=src --cov-report=term  # With coverage

常用标志

• -v / --verbose - 输出详细信息
• -x / --exitfirst - 首次失败时停止
• --tb=short - 简短的回溯信息
• --tb=no - 不显示回溯信息
• -k EXPR - 运行与表达式匹配的测试
• -m MARKER - 运行带有标记的测试
• --cov=PATH - 检查指定路径的覆盖率
• --cov-report=term-missing - 显示未覆盖的代码行

pyproject.toml 配置

最简配置

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]

完整配置

[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
testpaths = ["tests"]
python_files = ["test_*.py", "*_test.py"]
python_functions = ["test_*"]
python_classes = ["Test*"]
addopts = "-v --tb=short"
markers = [
    "slow: marks tests as slow",
    "integration: marks integration tests",
]
filterwarnings = [
    "ignore::DeprecationWarning",
]

[tool.coverage.run]
source = ["src"]
branch = true
omit = ["tests/*", "*/__init__.py"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "if TYPE_CHECKING:",
    "raise NotImplementedError",
]
fail_under = 80
show_missing = true

生成报告

TESTING_REPORT.local.md 文件应包含：

1. 测试执行摘要（通过/失败/跳过）
2. 按模块统计的覆盖率指标
3. 按严重程度分类的审查结果
4. 附带文件:行号引用的建议
5. 证据（命令输出）

与对话集成

用户要求编写测试时：

1. 检查对话历史，了解测试背景
2. 确定正在讨论的代码/功能
3. 如果不明确，请提出澄清问题：
   • “要测试哪些具体行为？”
   • “是否应包含针对 X 的边界情况？”
   • “需要单元测试、集成测试，还是两者都需要？”
4. 遵循 TDD：先编写失败的测试，再实现功能

可用命令

• /tdd-pytest:init - 初始化 pytest 配置
• /tdd-pytest:test [path] - 使用 TDD 编写测试（结合上下文）
• /tdd-pytest:test-all - 运行所有测试
• /tdd-pytest:report - 生成/更新 TESTING_REPORT.local.md