@umacloud/knowledge 1.0.1

package/testing/04-antipatterns/testing-antipatterns.md

@@ -0,0 +1,718 @@
+---
+id: testing-antipatterns
+title: 测试反模式指南 (Testing Anti-Patterns Guide)
+domain: testing
+category: 04-antipatterns
+difficulty: intermediate
+tags: [antipatterns, behavior, excessive, implementation, mock, mocking, testing, 反模式]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 测试反模式指南 (Testing Anti-Patterns Guide)
+
+> 适用范围：Python / JavaScript / TypeScript / Go / Java
+> 约束级别：SHALL（必须在 Code Review 阶段拦截）
+> 目标：识别和消除常见的测试反模式，建设高质量、可维护的测试体系。
+
+---
+
+## 反模式 1: 测试实现而非行为 (Testing Implementation, Not Behavior)
+
+### 描述
+
+测试过度依赖代码内部结构（私有方法、字段顺序、调用次数），而非验证外部可观察的行为。一旦重构实现细节，大量测试会断裂，即使功能完全正确。
+
+### 危害
+
+- 重构成本极高，开发者害怕修改代码
+- 测试无法捕获真正的回归 Bug
+- 测试维护成本远超业务代码
+
+### 错误示例
+
+```python
+# BAD: 测试内部实现细节
+def test_calculate_discount():
+    service = PricingService()
+    service.calculate_discount(user_id=1, amount=100)
+
+    # 断言内部调用了特定的私有方法和参数
+    service._load_user_tier.assert_called_once_with(1)
+    service._apply_tier_multiplier.assert_called_once_with("gold", 100)
+    service._round_to_cents.assert_called_once()
+    # 没有断言最终结果！
+```
+
+### 正确示例
+
+```python
+# GOOD: 测试可观察的行为（输入 → 输出）
+def test_gold_user_gets_20_percent_discount():
+    service = PricingService(user_repo=FakeUserRepo(tier="gold"))
+    result = service.calculate_discount(user_id=1, amount=100)
+
+    assert result.discount_amount == 20.00
+    assert result.final_price == 80.00
+```
+
+### 检测方法
+
+- 测试中 `assert_called_with` 数量 > `assert` 结果断言数量
+- 测试访问了以 `_` 开头的私有属性或方法
+- 重构后功能正常但测试失败
+
+---
+
+## 反模式 2: 过度 Mock (Excessive Mocking)
+
+### 描述
+
+对几乎所有依赖都使用 Mock，导致测试仅验证 Mock 的配置是否正确，而非系统的真实行为。测试通过但实际集成时仍然出错。
+
+### 危害
+
+- 测试与真实行为脱节，提供虚假的安全感
+- Mock 配置本身成为 Bug 来源
+- 无法捕获依赖变更引起的集成问题
+
+### 错误示例
+
+```python
+# BAD: Mock 了一切，测试只验证了 Mock 的配置
+def test_create_order(mocker):
+    mock_db = mocker.patch("app.services.database")
+    mock_cache = mocker.patch("app.services.cache")
+    mock_queue = mocker.patch("app.services.message_queue")
+    mock_validator = mocker.patch("app.services.validator")
+
+    mock_validator.validate.return_value = True
+    mock_db.insert.return_value = {"id": "order-123"}
+    mock_cache.set.return_value = True
+    mock_queue.publish.return_value = True
+
+    service = OrderService()
+    result = service.create_order({"item": "book", "qty": 1})
+
+    mock_validator.validate.assert_called_once()
+    mock_db.insert.assert_called_once()
+    mock_cache.set.assert_called_once()
+    mock_queue.publish.assert_called_once()
+    # 测试通过，但实际 DB schema 变了、队列消息格式变了都不会被发现
+```
+
+### 正确示例
+
+```python
+# GOOD: 仅 Mock 外部边界（网络/第三方API），内部逻辑用真实实现
+def test_create_order():
+    # 使用内存数据库和 Fake 实现
+    db = InMemoryDatabase()
+    cache = InMemoryCache()
+    queue = FakeMessageQueue()
+
+    service = OrderService(db=db, cache=cache, queue=queue)
+    result = service.create_order({"item": "book", "qty": 1})
+
+    assert result.status == "created"
+    assert db.find("orders", result.id) is not None
+    assert len(queue.messages) == 1
+    assert queue.messages[0]["type"] == "order_created"
+```
+
+### 检测方法
+
+- 单个测试函数中 `mocker.patch` 调用 > 3 次
+- 测试文件中 Mock 配置代码行数 > 断言代码行数
+- Mock 返回值从不为 None 或异常（只测试 Happy Path）
+
+---
+
+## 反模式 3: Flaky Tests（不稳定测试）
+
+### 描述
+
+测试在相同代码上时而通过时而失败，通常由时间依赖、随机性、外部服务调用、竞态条件或测试执行顺序依赖引起。
+
+### 危害
+
+- 团队对测试结果失去信任，开始忽视失败
+- CI 流水线不可靠，频繁 Retry 浪费资源
+- 真正的 Bug 被淹没在 Flaky 噪音中
+
+### 错误示例
+
+```python
+# BAD: 依赖当前时间
+def test_greeting_message():
+    service = GreetingService()
+    result = service.get_greeting()
+    # 在下午 6 点前通过，之后失败
+    assert result == "Good morning!"
+
+
+# BAD: 依赖外部 API
+def test_exchange_rate():
+    rate = get_exchange_rate("USD", "CNY")
+    assert rate == 7.24  # 汇率每天变化
+
+
+# BAD: 依赖字典/集合顺序
+def test_user_roles():
+    user = create_admin_user()
+    assert str(user.roles) == "{'admin', 'user'}"  # 集合顺序不确定
+```
+
+### 正确示例
+
+```python
+# GOOD: 注入可控的时间源
+def test_greeting_message():
+    clock = FakeClock(hour=9)
+    service = GreetingService(clock=clock)
+    result = service.get_greeting()
+    assert result == "Good morning!"
+
+
+# GOOD: Mock 外部调用，测试逻辑而非数据
+def test_exchange_rate_conversion(mocker):
+    mocker.patch("app.forex.get_exchange_rate", return_value=7.24)
+    result = convert_currency(100, "USD", "CNY")
+    assert result == 724.0
+
+
+# GOOD: 不依赖集合顺序
+def test_user_roles():
+    user = create_admin_user()
+    assert user.roles == {"admin", "user"}  # 集合相等比较，不关心顺序
+```
+
+### 检测方法
+
+- 同一测试在 CI 中最近 10 次运行有失败记录
+- 测试中使用 `time.sleep()` / `datetime.now()` / `random`
+- 测试直接调用外部 HTTP 接口
+
+---
+
+## 反模式 4: 测试间依赖 (Inter-Test Dependency)
+
+### 描述
+
+测试之间存在隐式的执行顺序依赖或共享可变状态，导致单独运行某个测试通过，但改变执行顺序或并行运行时失败。
+
+### 危害
+
+- 无法并行执行测试，CI 时间线性增长
+- 新增/删除一个测试可能导致其他测试失败
+- 排查失败原因极其困难
+
+### 错误示例
+
+```python
+# BAD: 测试之间共享可变状态
+class TestUserService:
+    user_id = None  # 类级别共享状态
+
+    def test_create_user(self):
+        user = UserService.create(name="Alice")
+        TestUserService.user_id = user.id  # 后续测试依赖这个值
+        assert user.name == "Alice"
+
+    def test_update_user(self):
+        # 依赖 test_create_user 先执行
+        UserService.update(TestUserService.user_id, name="Bob")
+        user = UserService.get(TestUserService.user_id)
+        assert user.name == "Bob"
+
+    def test_delete_user(self):
+        # 依赖前两个测试的执行顺序
+        UserService.delete(TestUserService.user_id)
+        assert UserService.get(TestUserService.user_id) is None
+```
+
+### 正确示例
+
+```python
+# GOOD: 每个测试独立设置和清理
+class TestUserService:
+    def test_create_user(self, db):
+        user = UserService.create(name="Alice")
+        assert user.name == "Alice"
+
+    def test_update_user(self, db):
+        user = UserService.create(name="Alice")  # 自己创建
+        UserService.update(user.id, name="Bob")
+        updated = UserService.get(user.id)
+        assert updated.name == "Bob"
+
+    def test_delete_user(self, db):
+        user = UserService.create(name="Alice")  # 自己创建
+        UserService.delete(user.id)
+        assert UserService.get(user.id) is None
+
+@pytest.fixture
+def db():
+    """每个测试使用独立的数据库事务并自动回滚。"""
+    connection = get_test_connection()
+    transaction = connection.begin()
+    yield connection
+    transaction.rollback()
+```
+
+### 检测方法
+
+- `pytest --randomly` 或 `pytest-random-order` 打乱顺序后测试失败
+- 测试类中存在类级别的可变属性
+- 一个测试的 Fixture 依赖另一个测试的副作用
+
+---
+
+## 反模式 5: 无断言测试 (Assertion-Free Tests)
+
+### 描述
+
+测试执行了代码但不验证任何结果，仅确认"代码没有抛异常"。这类测试提供虚假的覆盖率而不提供任何质量保证。
+
+### 危害
+
+- 覆盖率数字好看但测试毫无价值
+- 功能回归无法被检测到
+- 团队误以为功能已充分测试
+
+### 错误示例
+
+```python
+# BAD: 没有任何断言
+def test_generate_report():
+    service = ReportService()
+    service.generate_report(month="2024-01")
+    # 测试到此结束，没有验证报告内容、格式、文件是否生成
+
+
+# BAD: 只断言"不是 None"等无意义条件
+def test_search_products():
+    results = ProductService.search("laptop")
+    assert results is not None  # 返回空列表也通过
+```
+
+### 正确示例
+
+```python
+# GOOD: 明确断言预期结果
+def test_generate_report():
+    service = ReportService(data_source=FakeDataSource(revenue=50000))
+    report = service.generate_report(month="2024-01")
+
+    assert report.title == "2024年1月财务报告"
+    assert report.total_revenue == 50000
+    assert report.sections == ["概览", "收入明细", "支出明细", "利润分析"]
+    assert report.generated_at is not None
+
+
+# GOOD: 断言结果的具体属性
+def test_search_products():
+    results = ProductService.search("laptop")
+    assert len(results) == 3
+    assert all(r.category == "electronics" for r in results)
+    assert results[0].relevance_score > results[1].relevance_score
+```
+
+### 检测方法
+
+- 测试函数中没有 `assert` 关键字
+- 仅有 `assert x is not None` 或 `assert len(x) > 0` 等弱断言
+- 使用 `pytest --assert-rewrite` 检查断言质量
+
+---
+
+## 反模式 6: 只测 Happy Path（缺少异常路径测试）
+
+### 描述
+
+只测试正常输入和预期流程，忽略错误处理、边界条件、异常输入、超时、并发等场景。生产环境的 Bug 绝大多数来自非 Happy Path。
+
+### 危害
+
+- 异常输入导致未处理异常、数据损坏或安全漏洞
+- 错误处理逻辑从未被验证，上线后才发现不工作
+- 用户体验在异常场景下断崖式下降
+
+### 错误示例
+
+```python
+# BAD: 只测正常场景
+class TestPaymentService:
+    def test_process_payment(self):
+        result = PaymentService.charge(user_id=1, amount=99.99)
+        assert result.status == "success"
+    # 没有测试：金额为0、负数、超大金额、用户不存在、余额不足、
+    # 网络超时、重复支付、并发支付、货币不支持等场景
+```
+
+### 正确示例
+
+```python
+# GOOD: 覆盖多种异常路径
+class TestPaymentService:
+    def test_successful_payment(self):
+        result = PaymentService.charge(user_id=1, amount=99.99)
+        assert result.status == "success"
+
+    def test_zero_amount_rejected(self):
+        with pytest.raises(ValueError, match="Amount must be positive"):
+            PaymentService.charge(user_id=1, amount=0)
+
+    def test_negative_amount_rejected(self):
+        with pytest.raises(ValueError, match="Amount must be positive"):
+            PaymentService.charge(user_id=1, amount=-10)
+
+    def test_insufficient_balance(self):
+        result = PaymentService.charge(user_id=1, amount=999999)
+        assert result.status == "insufficient_funds"
+        assert result.error_code == "E_BALANCE"
+
+    def test_user_not_found(self):
+        with pytest.raises(UserNotFoundError):
+            PaymentService.charge(user_id=99999, amount=10)
+
+    def test_gateway_timeout_retries(self, mocker):
+        mocker.patch("app.gateway.charge",
+                     side_effect=[TimeoutError, TimeoutError, {"status": "ok"}])
+        result = PaymentService.charge(user_id=1, amount=10)
+        assert result.status == "success"  # 第三次重试成功
+
+    def test_idempotent_duplicate_payment(self):
+        key = "pay-abc-123"
+        PaymentService.charge(user_id=1, amount=10, idempotency_key=key)
+        result = PaymentService.charge(user_id=1, amount=10, idempotency_key=key)
+        assert result.status == "duplicate"
+```
+
+### 检测方法
+
+- 测试类中没有 `pytest.raises` 或异常断言
+- Mutation Testing 通过率低于 80%
+- 测试用例中所有输入都是"正常值"
+
+---
+
+## 反模式 7: 100% 覆盖率执念 (100% Coverage Obsession)
+
+### 描述
+
+团队将 100% 代码覆盖率作为硬性目标，导致为了达标而编写大量无意义的测试（如测试 Getter/Setter、测试框架代码、测试配置常量），真正需要测试的复杂逻辑反而被忽视。
+
+### 危害
+
+- 测试维护成本飙升，团队怨声载道
+- 无意义的测试稀释了测试套件的信号价值
+- 关注覆盖率数字而非测试质量
+
+### 错误示例
+
+```python
+# BAD: 为了覆盖率测试数据类和常量
+class Config:
+    DB_HOST = "localhost"
+    DB_PORT = 5432
+
+def test_config_db_host():
+    assert Config.DB_HOST == "localhost"
+
+def test_config_db_port():
+    assert Config.DB_PORT == 5432
+
+
+# BAD: 为了覆盖率测试简单的 DTO
+@dataclass
+class UserDTO:
+    name: str
+    email: str
+
+def test_user_dto():
+    user = UserDTO(name="Alice", email="alice@example.com")
+    assert user.name == "Alice"
+    assert user.email == "alice@example.com"
+```
+
+### 正确示例
+
+```python
+# GOOD: 将测试精力集中在高风险、高复杂度的业务逻辑上
+# 使用覆盖率作为发现未测试代码的工具，而非目标
+
+# coveragerc 配置：排除不需要测试的代码
+# [run]
+# omit =
+#   */config.py
+#   */models.py
+#   */migrations/*
+
+# 测试复杂的计算逻辑
+class TestTaxCalculator:
+    @pytest.mark.parametrize("income,expected_tax", [
+        (0, 0),
+        (5000, 0),            # 起征点以下
+        (10000, 150),         # 第一档
+        (30000, 2590),        # 跨档
+        (100000, 21790),      # 高收入
+    ])
+    def test_personal_income_tax(self, income, expected_tax):
+        assert TaxCalculator.calculate(income) == expected_tax
+
+    def test_tax_with_special_deductions(self):
+        result = TaxCalculator.calculate(
+            income=20000,
+            deductions={"housing": 1500, "education": 1000, "elderly": 2000},
+        )
+        assert result < TaxCalculator.calculate(20000)
+```
+
+### 检测方法
+
+- 覆盖率 > 95% 但 Mutation Testing 存活率 > 30%
+- 大量测试仅验证语言/框架的基本功能
+- 团队在覆盖率报告中排除了 0 行代码
+
+---
+
+## 反模式 8: Ice Cream Cone（反金字塔测试结构）
+
+### 描述
+
+测试分布呈倒金字塔形：大量 E2E / UI 测试、少量集成测试、极少或没有单元测试。与理想的测试金字塔（大量单元测试 > 适量集成测试 > 少量 E2E 测试）完全相反。
+
+### 危害
+
+- 测试执行极慢（E2E 通常需要分钟级），CI 反馈周期长
+- 测试极脆弱，UI 变化导致大面积失败
+- 故障定位困难，E2E 失败可能由任意层级引起
+
+### 错误示例
+
+```
+# BAD: 反金字塔测试分布
+tests/
+├── e2e/           # 200 个 E2E 测试（Selenium/Playwright）
+│   ├── test_login_flow.py
+│   ├── test_checkout_flow.py
+│   ├── test_search_and_filter.py
+│   └── ... (197 more)
+├── integration/    # 20 个集成测试
+│   └── test_api_endpoints.py
+└── unit/           # 5 个单元测试
+    └── test_utils.py
+
+# 结果：CI 运行 45 分钟，Flaky rate 30%+
+```
+
+### 正确示例
+
+```
+# GOOD: 测试金字塔分布
+tests/
+├── unit/               # 500+ 单元测试（秒级完成）
+│   ├── test_pricing.py
+│   ├── test_tax_calculator.py
+│   ├── test_inventory.py
+│   └── ... (业务逻辑全覆盖)
+├── integration/        # 80 个集成测试（分钟级）
+│   ├── test_order_api.py
+│   ├── test_payment_gateway.py
+│   └── test_database_queries.py
+└── e2e/                # 15 个 E2E 测试（仅核心流程）
+    ├── test_signup_to_first_purchase.py
+    ├── test_checkout_and_payment.py
+    └── test_return_and_refund.py
+
+# 结果：CI 运行 5 分钟，Flaky rate < 2%
+```
+
+### 检测方法
+
+- 统计各层级测试数量比例
+- CI 平均执行时间 > 20 分钟
+- 日常开发时开发者跳过测试（`-k "not e2e"`）
+
+---
+
+## 反模式 9: Copy-Paste 测试 (Duplicated Test Code)
+
+### 描述
+
+测试代码大量复制粘贴，仅改变少量参数或断言值，导致测试文件膨胀、维护困难，修改一个模式需要改 N 个地方。
+
+### 危害
+
+- 测试代码量爆炸，文件达数千行
+- 修改测试模式需要逐个修改所有副本
+- 遗漏修改导致测试不一致
+
+### 错误示例
+
+```python
+# BAD: 大量重复的测试代码
+def test_validate_email_valid_1():
+    assert validate_email("user@example.com") is True
+
+def test_validate_email_valid_2():
+    assert validate_email("user.name@example.com") is True
+
+def test_validate_email_valid_3():
+    assert validate_email("user+tag@example.com") is True
+
+def test_validate_email_invalid_1():
+    assert validate_email("") is False
+
+def test_validate_email_invalid_2():
+    assert validate_email("not-an-email") is False
+
+def test_validate_email_invalid_3():
+    assert validate_email("@example.com") is False
+
+def test_validate_email_invalid_4():
+    assert validate_email("user@") is False
+
+# 7 个测试函数，每个结构完全一样
+```
+
+### 正确示例
+
+```python
+# GOOD: 使用参数化消除重复
+@pytest.mark.parametrize("email,expected", [
+    ("user@example.com", True),
+    ("user.name@example.com", True),
+    ("user+tag@example.com", True),
+    ("", False),
+    ("not-an-email", False),
+    ("@example.com", False),
+    ("user@", False),
+])
+def test_validate_email(email, expected):
+    assert validate_email(email) is expected
+
+
+# GOOD: 使用 Fixture 和 Factory 消除设置重复
+@pytest.fixture
+def order_factory(db):
+    def _create(status="pending", items=None, **kwargs):
+        items = items or [{"sku": "BOOK-001", "qty": 1, "price": 29.99}]
+        return Order.create(status=status, items=items, **kwargs)
+    return _create
+
+def test_cancel_pending_order(order_factory):
+    order = order_factory(status="pending")
+    order.cancel()
+    assert order.status == "cancelled"
+
+def test_cannot_cancel_shipped_order(order_factory):
+    order = order_factory(status="shipped")
+    with pytest.raises(InvalidStateError):
+        order.cancel()
+```
+
+### 检测方法
+
+- 测试文件中多个函数体结构完全一致
+- 同一测试文件超过 500 行
+- `pytest.mark.parametrize` 使用率低于 10%
+
+---
+
+## 反模式 10: 忽略边界条件 (Ignoring Boundary Conditions)
+
+### 描述
+
+测试只使用"正常范围"的输入值，忽略边界值（0、1、MAX、空字符串、null、最大长度、精度极限），而 Bug 最常出现在边界处。
+
+### 危害
+
+- 整数溢出、除零错误、空指针异常等 Bug 上线后才被发现
+- 数据库约束违反导致生产事故
+- 安全漏洞（Buffer Overflow、注入）源于边界处理不当
+
+### 错误示例
+
+```python
+# BAD: 只测试"正常"输入
+def test_pagination():
+    results = search(query="python", page=1, page_size=20)
+    assert len(results) == 20
+
+def test_calculate_average():
+    assert calculate_average([1, 2, 3, 4, 5]) == 3.0
+
+def test_truncate_text():
+    assert truncate("Hello World", max_length=5) == "Hello..."
+```
+
+### 正确示例
+
+```python
+# GOOD: 系统化地测试边界条件
+class TestPagination:
+    def test_first_page(self):
+        results = search(query="python", page=1, page_size=20)
+        assert len(results) <= 20
+
+    def test_page_zero_raises(self):
+        with pytest.raises(ValueError):
+            search(query="python", page=0, page_size=20)
+
+    def test_negative_page_raises(self):
+        with pytest.raises(ValueError):
+            search(query="python", page=-1, page_size=20)
+
+    def test_page_size_zero_raises(self):
+        with pytest.raises(ValueError):
+            search(query="python", page=1, page_size=0)
+
+    def test_page_beyond_results(self):
+        results = search(query="python", page=99999, page_size=20)
+        assert results == []
+
+    def test_empty_query(self):
+        results = search(query="", page=1, page_size=20)
+        assert results == []
+
+    def test_max_page_size(self):
+        results = search(query="python", page=1, page_size=1000)
+        assert len(results) <= 100  # 服务端限制最大 page_size
+
+
+class TestCalculateAverage:
+    def test_normal(self):
+        assert calculate_average([1, 2, 3]) == 2.0
+
+    def test_single_element(self):
+        assert calculate_average([42]) == 42.0
+
+    def test_empty_list_raises(self):
+        with pytest.raises(ValueError, match="Cannot calculate average of empty list"):
+            calculate_average([])
+
+    def test_large_numbers(self):
+        assert calculate_average([1e18, 1e18]) == 1e18
+
+    def test_floating_point_precision(self):
+        result = calculate_average([0.1, 0.2])
+        assert abs(result - 0.15) < 1e-10  # 不用 == 比较浮点数
+```
+
+### 检测方法
+
+- 测试输入中没有 0、空值、极大值、极小值
+- 没有使用 `pytest.raises` 测试异常输入
+- Mutation Testing 在边界检查代码上的存活率高
+
+---
+
+## Agent Checklist
+
+- [ ] 代码评审时对照本文档逐项检查测试质量
+- [ ] 新测试代码必须避免以上 10 种反模式
+- [ ] 已有测试中的反模式已建立修复计划和优先级
+- [ ] 测试分布符合金字塔原则（单元 > 集成 > E2E）
+- [ ] `pytest.mark.parametrize` 在重复场景中优先使用
+- [ ] Flaky Test 有专门的跟踪和修复流程