claude-code/claude-zh/skills/python-testing/SKILL.md

name	description
python-testing	使用 pytest 的 Python 測試策略，涵蓋 TDD 方法論、Fixtures、Mocking、參數化 (Parametrization) 以及覆蓋率要求。

Python 測試模式 (Python Testing Patterns)

使用 pytest、TDD 方法論與最佳實踐的 Python 應用程式全面測試策略。

何時啟用

• 編寫新的 Python 程式碼（遵循 TDD：紅燈、綠燈、重構）。
• 為 Python 專案設計測試套件。
• 審核 Python 測試覆蓋率。
• 設置測試基礎設施。

核心測試哲學

測試驅動開發 (TDD)

務必遵循 TDD 循環：

1. 紅燈 (RED)：為預期行為撰寫一個會失敗的測試。
2. 綠燈 (GREEN)：編寫最少量的程式碼使測試通過。
3. 重構 (REFACTOR)：在保持測試通過的情況下優化程式碼。

# 步驟 1：撰寫失敗的測試 (RED)
def test_add_numbers():
    result = add(2, 3)
    assert result == 5

# 步驟 2：撰寫最小實作 (GREEN)
def add(a, b):
    return a + b

# 步驟 3：如有需要則重構 (REFACTOR)

覆蓋率要求

• 目標：80% 以上的程式碼覆蓋率。
• 關鍵路徑：必須達到 100% 覆蓋率。
• 使用 pytest --cov 來衡量覆蓋率。

pytest --cov=mypackage --cov-report=term-missing --cov-report=html

pytest 基礎

斷言 (Assertions)

# 相等性
assert result == expected

# 真值判斷
assert result  # 真值 (Truthy)
assert result is True  # 嚴格等於 True
assert result is None  # 嚴格等於 None

# 成員資格
assert item in collection

# 類型檢查
assert isinstance(result, str)

# 例外測試
with pytest.raises(ValueError):
    raise ValueError("錯誤訊息")

# 檢查例外訊息內容
with pytest.raises(ValueError, match="無效的輸入"):
    raise ValueError("提供的輸入無效")

Fixtures (測試夾具)

帶有設置與清理的 Fixture

@pytest.fixture
def database():
    """帶有設置與清理 (Setup/Teardown) 的 Fixture。"""
    # 設置 (Setup)
    db = Database(":memory:")
    db.create_tables()

    yield db  # 提供給測試案例使用

    # 清理 (Teardown)
    db.close()

def test_database_query(database):
    """測試資料庫操作。"""
    result = database.query("SELECT * FROM users")
    assert len(result) > 0

作用域 (Scopes) 與 conftest.py

• function (預設)：每個測試執行一次。
• module：每個模組執行一次。
• session：每次測試會話執行一次。
• 使用 tests/conftest.py 來定義跨檔案共享的 Fixtures。

參數化 (Parametrization)

@pytest.mark.parametrize("input,expected", [
    ("hello", "HELLO"),
    ("world", "WORLD"),
    ("PyThOn", "PYTHON"),
])
def test_uppercase(input, expected):
    """測試會執行 3 次，每次使用不同的輸入。"""
    assert input.upper() == expected

Mocking 與 Patching

from unittest.mock import patch, Mock

@patch("mypackage.external_api_call")
def test_with_mock(api_call_mock):
    """測試模擬外部 API。"""
    api_call_mock.return_value = {"status": "success"}

    result = my_function()

    api_call_mock.assert_called_once()
    assert result["status"] == "success"

測試非同步程式碼 (Async Code)

需要 pytest-asyncio 外掛：

import pytest

@pytest.mark.asyncio
async def test_async_function():
    """測試非同步函式。"""
    result = await async_add(2, 3)
    assert result == 5

測試組織與最佳實踐

目錄結構建議

tests/
├── conftest.py                 # 共享 Fixtures
├── unit/                       # 單元測試
│   └── test_models.py
├── integration/                # 整合測試
│   └── test_api.py
└── e2e/                        # 端到端測試
    └── test_user_flow.py

應做事項 (DO)

• 遵循 TDD：先寫測試再寫程式碼。
• 單一功能測試：每個測試案例僅驗證一個行為。
• 命名具備描述性：例如 test_user_login_with_invalid_credentials_fails。
• 模擬外部依賴：不要依賴外部服務或網路。

避免事項 (DON'T)

• 不要測試實作細節：應測試行為而非內部邏輯。
• 不要在測試中使用複雜的判斷式：保持測試簡單明瞭。
• 不要忽視失敗的測試：所有測試必須全部通過。
• 不要在測試之間共享狀態：測試案例應保持獨立。

常用指令

# 執行所有測試
pytest

# 執行特定檔案
pytest tests/test_utils.py

# 執行特定測試案例
pytest tests/test_utils.py::test_function

# 帶有詳細輸出
pytest -v

# 執行直到第一次失敗即停止
pytest -x

# 重新執行上次失敗的測試
pytest --lf