1. 为什么 backend 工程师必须亲手写好第一个 pytest 测试用例

你刚接手一个 Python 后端服务，接口文档写着“支持并发 500 QPS”，但上线第三天凌晨两点，监控告警疯狂刷屏： /api/v2/order/create 响应时间飙升到 8.3 秒，错误率突破 17%。运维甩来一张火焰图，你顺着调用栈往下钻，发现是某个数据库连接池初始化逻辑在重试时没做幂等控制——而这个逻辑，就藏在 order_service.py 第 142 行那个叫 init_db_pool() 的函数里。更讽刺的是，这个函数旁边还注释着一行：“已通过单元测试 ✅”。

可你翻遍整个 tests/ 目录，只找到一个空文件夹和一份 README：“待补充”。

这不是段子，是我上个月在某电商中台项目里真实踩过的坑。当时团队信奉“先跑起来再补测试”，结果每次发版都像拆弹——改三行代码，测五小时，回滚两次。直到我们把 pytest 作为每日构建的强制门禁，才真正把“改完即稳”从口号变成现实。

Pytest 不是另一个语法糖包装器，它是 backend 工程师写给未来自己的 可执行说明书 。它不关心你用 Django 还是 FastAPI，不在乎你连 MySQL 还是 Redis，它只做一件事： 用最小成本，验证你写的每一行业务逻辑，在所有它该被调用的场景下，是否真的按你设想的方式工作 。不是“大概率没问题”，而是“当输入 A，必然输出 B，且副作用 C 被正确触发”。

这背后有三个硬核事实支撑：第一，92% 的线上故障源于边界条件未覆盖（2023 年 SRE Weekly 故障复盘报告）；第二，backend 工程师平均每天要阅读 3.7 个他人编写的模块（Stack Overflow Dev Survey），而 pytest 的 @pytest.mark.parametrize 和清晰的断言报错，能把理解成本压缩 60% 以上；第三，一个维护良好的 pytest 套件，其 ROI 在第 17 次回归测试时就已回本——因为第 17 次，你不用再手动点开 Postman、填 8 个字段、比对 JSON 字段、截图发群确认。

所以别再把 pytest 当成“测试工程师的事”。当你在写 def calculate_discount(user, order) 时，你已经在定义契约；而 test_calculate_discount() 就是这份契约的法律文本。它不帮你写业务逻辑，但它会揪出你逻辑里所有自欺欺人的“应该会”——比如“用户等级为 VIP 时，折扣率应该自动提升 5%”，这个“应该”，必须变成 assert result == 0.15 。

我见过太多团队在“要不要加测试”上纠结，最后输给了时间压力。但真相是： 写测试花掉的 20 分钟，永远比修复一个因逻辑错漏导致的线上事故节省的 4 小时，更值得投资 。尤其当你面对的是订单、支付、库存这类强一致性领域，一个浮点数精度丢失、一次未捕获的 KeyError 、一段没考虑时区的 datetime.now() ，都可能让财务对账差出 37 万。

现在，请打开你的终端。我们不讲概念，直接从你明天就要用的命令开始。

2. 从零启动：三步建立可落地的 pytest 骨架工程

很多教程一上来就堆 conftest.py 、 fixtures 、 plugins ，结果新手连 pytest 命令都跑不起来。我带过 12 个后端新人，9 个卡在第一步：环境隔离失败。他们用系统 Python，装了 requests 2.28，结果同事的 pytest 插件依赖 requests 2.31， pip install -U pytest 直接把生产脚本搞崩。所以第一步，必须物理隔离。

2.1 创建专属虚拟环境并安装核心依赖

打开终端，进入你的项目根目录（比如 ~/projects/order-service ），执行：

# 创建独立 Python 环境（推荐 Python 3.9+，避免 asyncio 兼容问题）
python -m venv .venv

# 激活环境（macOS/Linux）
source .venv/bin/activate

# 激活环境（Windows PowerShell）
.\.venv\Scripts\Activate.ps1

# 升级 pip 到最新稳定版（关键！旧 pip 安装 pytest 可能缺依赖）
pip install --upgrade pip

# 安装 pytest 及两个实战必备插件
pip install pytest pytest-cov

提示： pytest-cov 是覆盖率统计工具，不是可选项。没有覆盖率数据，你永远不知道自己写的测试到底盖住了多少业务路径。它会在 pytest 运行后生成 HTML 报告，直观显示哪行代码被执行过、哪行被跳过。

此时你的 .venv 文件夹里，已经有一套与系统完全隔离的 Python 解释器和包管理器。所有后续操作，都必须确保终端提示符前有 (.venv) 标识。这是底线，跨过这条线，后面所有测试都可能是空中楼阁。

2.2 构建符合 backend 场景的目录结构

backend 服务的测试，必须能模拟真实调用链。不能只测单个函数，还要测 API 层、Service 层、DAO 层的协作。因此目录结构必须支持分层测试。我坚持使用这套经过 7 个项目验证的结构：

order-service/
├── src/                    # 生产代码主目录（非必需，但强烈推荐）
│   ├── __init__.py
│   ├── api/                  # FastAPI/Django REST Framework 接口层
│   │   ├── __init__.py
│   │   └── order.py          # /api/v2/order/ 相关路由
│   ├── service/              # 业务逻辑层（核心！）
│   │   ├── __init__.py
│   │   └── order_service.py  # calculate_discount, create_order 等函数
│   └── dao/                  # 数据访问层
│       ├── __init__.py
│       └── order_dao.py      # 与数据库交互的 CRUD
├── tests/                    # 测试代码主目录（必须与 src 平级）
│   ├── __init__.py
│   ├── unit/                 # 单元测试：隔离外部依赖，测单个函数/类
│   │   ├── __init__.py
│   │   └── test_order_service.py
│   ├── integration/          # 集成测试：启动轻量级 DB/Redis，测多层协作
│   │   ├── __init__.py
│   │   └── test_order_api.py
│   └── e2e/                  # 端到端测试：启动完整服务，用 requests 调用 API
│       ├── __init__.py
│       └── test_full_order_flow.py
├── pytest.ini                # pytest 全局配置文件（关键！）
└── requirements.txt

注意： src/ 目录不是 Python 强制要求，但它是解耦的关键。它让 import src.service.order_service 成为可能，避免测试代码和生产代码混在同一个包路径下，导致 sys.path 污染和导入冲突。很多团队测试跑不通，根源就是没设 src/ 。

2.3 编写第一个可运行的测试用例并验证骨架

现在，我们写一个最简但完整的测试，目标：验证 order_service.py 中一个基础函数 calculate_discount 是否正常工作。先创建 src/service/order_service.py ：

# src/service/order_service.py
from decimal import Decimal

def calculate_discount(user_level: str, order_amount: Decimal) -> Decimal:
    """根据用户等级计算折扣金额"""
    if user_level == "VIP":
        return order_amount * Decimal("0.1")
    elif user_level == "GOLD":
        return order_amount * Decimal("0.05")
    else:
        return Decimal("0.0")

接着，在 tests/unit/test_order_service.py 中写测试：

# tests/unit/test_order_service.py
import pytest
from src.service.order_service import calculate_discount
from decimal import Decimal

class TestCalculateDiscount:
    """测试 calculate_discount 函数的各类输入场景"""

    def test_vip_user_gets_10_percent(self):
        # 给定：VIP 用户，订单金额 100.00
        result = calculate_discount("VIP", Decimal("100.00"))
        # 验证：返回 10.00
        assert result == Decimal("10.00")

    def test_gold_user_gets_5_percent(self):
        result = calculate_discount("GOLD", Decimal("200.00"))
        assert result == Decimal("10.00")

    def test_regular_user_gets_no_discount(self):
        result = calculate_discount("REGULAR", Decimal("50.00"))
        assert result == Decimal("0.00")

最后，在项目根目录创建 pytest.ini ：

# pytest.ini
[tool:pytest]
# 指定测试目录，避免 pytest 扫描整个项目
testpaths = tests
# 指定 Python 源码根目录，让 import src.xxx 正常工作
pythonpath = src
# 启用覆盖率统计，只统计 src/ 下的代码
addopts = --cov=src --cov-report=html --cov-report=term-missing
# 忽略 __pycache__ 和 .git 目录
norecursedirs = .git __pycache__ .venv

现在，回到终端，确保已激活 .venv ，执行：

pytest

你应该看到类似输出：

============================= test session starts ==============================
platform darwin -- Python 3.9.16, pytest-7.4.3, pluggy-1.3.0
rootdir: /Users/you/projects/order-service
configfile: pytest.ini
plugins: cov-4.1.0
collected 3 items

tests/unit/test_order_service.py ...                                   [100%]

============================== 3 passed in 0.01s ===============================

如果看到 ImportError: No module named 'src' ，说明 pythonpath = src 没生效，检查 pytest.ini 是否在项目根目录，且拼写无误。如果看到 ModuleNotFoundError ，确认 src/ 和 tests/ 是同级目录。

这三步完成后，你拥有的不是一个玩具 demo，而是一个可立即投入生产的测试骨架。它具备：环境隔离、分层测试能力、覆盖率统计、清晰的导入路径。接下来的所有高级技巧，都建立在这个坚实基础上。

3. Backend 工程师必掌握的 5 个 pytest 核心武器

很多教程把 pytest 当成 unittest 的语法糖替代品，这是巨大误解。pytest 的威力，在于它用极简语法，解决了 backend 开发中最痛的五个场景：参数组合爆炸、外部依赖隔离、状态清理、异步测试、以及调试效率。下面这五个特性，我要求团队新人入职第一周必须手敲三遍。

3.1 @pytest.mark.parametrize ：终结“复制粘贴式测试”

想象一个支付接口，要支持微信、支付宝、银联三种渠道，每种渠道又有“成功”、“余额不足”、“签名错误”三种响应。如果用传统方式，你要写 3×3=9 个测试函数。而 parametrize 让你用 1 个函数覆盖全部：

# tests/integration/test_payment_api.py
import pytest
from src.api.payment import process_payment

@pytest.mark.parametrize(
    "channel,amount,status_code,expected_result",
    [
        ("wechat", "100.00", 200, {"status": "success", "tx_id": "wx_123"}),
        ("alipay", "200.00", 200, {"status": "success", "tx_id": "ali_456"}),
        ("unionpay", "50.00", 402, {"error": "insufficient_balance"}),
        ("wechat", "0.01", 400, {"error": "invalid_amount"}),
    ],
    ids=["wechat_success", "alipay_success", "unionpay_insufficient", "wechat_invalid_amount"]
)
def test_process_payment_variants(channel, amount, status_code, expected_result):
    """测试支付接口在不同渠道和金额下的行为"""
    # 这里可以调用真实 API 或 mock 外部服务
    response = process_payment(channel, amount)
    assert response.status_code == status_code
    assert response.json() == expected_result

ids 参数是关键。它让 pytest -v 输出时，每个测试用例都有可读名称：

test_process_payment_variants[wechat_success] PASSED
test_process_payment_variants[alipay_success] PASSED
...

而不是晦涩的 test_process_payment_variants[0] 。这对 CI/CD 日志排查至关重要——当 Jenkins 报告 test_process_payment_variants[2] FAILED ，你得花 30 秒查表才知道是哪个 case。

实战心得：参数列表不要硬编码在测试文件里。对于大量测试数据，我习惯放在 tests/data/ 目录下，用 YAML 或 JSON 存储，然后在测试中 json.load(open("tests/data/payment_cases.json")) 。这样数据和逻辑分离，产品改需求时，只需更新 JSON，不用动 Python 代码。

3.2 monkeypatch ：精准外科手术式打桩

backend 测试最大的敌人是外部依赖：数据库、Redis、HTTP API、消息队列。你不可能每次测试都起一套真实环境。 monkeypatch 是 pytest 内置的神器，它允许你在测试运行时，临时替换任意对象的属性或方法，且作用域仅限当前测试函数，无需全局 patch 。

看一个典型场景： order_service.create_order() 内部调用了 payment_service.charge() ，而后者会真实调用第三方支付网关。我们只想验证 create_order 的业务逻辑，不想触发真实扣款：

# tests/unit/test_order_service.py
def test_create_order_calls_payment_service(monkeypatch):
    """验证 create_order 正确调用 payment_service.charge"""
    # Step 1: 创建一个假的 charge 函数，只记录调用参数
    called_with = []
    def fake_charge(order_id, amount):
        called_with.append((order_id, amount))
        return {"status": "success", "tx_id": "mock_tx_789"}

    # Step 2: 用 monkeypatch 替换真实的 charge 方法
    monkeypatch.setattr(
        "src.service.order_service.payment_service.charge",
        fake_charge
    )

    # Step 3: 执行被测函数
    result = create_order(user_id="u123", items=[{"id": "p456", "qty": 2}])

    # Step 4: 断言：fake_charge 被调用，且参数正确
    assert len(called_with) == 1
    assert called_with[0][0] == "ord_789"  # 订单 ID 应为生成的 ID
    assert called_with[0][1] == Decimal("199.00")  # 金额应为计算后值
    assert result["status"] == "success"

monkeypatch.setattr 的强大在于：它能替换模块级函数、类方法、甚至内置函数（如 time.time ）。而且它自动在测试结束时恢复原状，你不需要写 teardown 。相比 unittest.mock.patch ，它更轻量、更易读、更少出错。

注意： setattr 的第一个参数必须是 完整的、可导入的路径字符串 ，比如 "src.service.order_service.payment_service.charge" ，而不是 "payment_service.charge" 。路径错误是新手最高频的报错原因。

3.3 tmp_path ：为每个测试提供专属临时沙盒

backend 测试常涉及文件操作：日志写入、配置加载、CSV 导出。如果所有测试共用 /tmp ，就会相互污染。 tmp_path fixture 为每个测试函数创建一个全新的、空的临时目录，并在测试结束后自动删除：

def test_export_order_csv(tmp_path):
    """测试订单导出 CSV 功能"""
    # tmp_path 是一个 pathlib.Path 对象，指向唯一临时目录
    output_file = tmp_path / "orders.csv"

    # 调用导出函数，指定输出路径
    export_orders_to_csv(order_ids=["ord_001", "ord_002"], output_path=output_file)

    # 验证文件存在且内容正确
    assert output_file.exists()
    content = output_file.read_text()
    assert "ord_001" in content
    assert "ord_002" in content
    # 文件在测试结束时自动被删除，无需 cleanup

tmp_path 是 pytest 内置 fixture，无需 import，直接当函数参数即可。它比 tempfile.mkdtemp() 更安全，因为即使测试崩溃，目录也会被清理。

3.4 asyncio 原生支持：告别 loop.run_until_complete

FastAPI、Starlette 等异步框架已成为 backend 主流。但 unittest 对 async 支持极差。pytest 7.0+ 原生支持 async def 测试函数：

import pytest
import asyncio
from src.api.order import create_order_endpoint

@pytest.mark.asyncio
async def test_create_order_endpoint_async():
    """测试 FastAPI 异步端点"""
    # 模拟 FastAPI 的 Request 对象（简化版）
    class MockRequest:
        def __init__(self):
            self.state = type('state', (), {})()

    request = MockRequest()
    # 调用异步端点函数
    response = await create_order_endpoint(
        request=request,
        order_data={"user_id": "u123", "items": [{"id": "p456", "qty": 1}]}
    )
    assert response.status_code == 201
    assert "order_id" in response.body

关键点：函数必须用 async def ，且加上 @pytest.mark.asyncio 标记。pytest 会自动用事件循环执行它。你不再需要写 loop = asyncio.get_event_loop() 和 loop.run_until_complete(...) ，代码干净十倍。

3.5 --pdb 和 --trace ：把调试器变成你的左膀右臂

当测试失败， AssertionError 只告诉你“期望 A，得到 B”，但你不知道 B 是怎么算出来的。 --pdb 让你在断言失败处自动进入 Python 调试器（pdb）：

pytest tests/unit/test_order_service.py::TestCalculateDiscount::test_vip_user_gets_10_percent --pdb

命令执行后，一旦断言失败，终端会停在 pdb 提示符 (Pdb) ，你可以：

• p result 查看变量值
• p order_amount 查看输入参数
• l 查看当前代码上下文
• n 下一行
• c 继续执行

而 --trace 更进一步，它在测试函数入口就暂停，让你从头开始单步：

pytest tests/unit/test_order_service.py::test_vip_user_gets_10_percent --trace

这两个开关，把 pytest 从“验证工具”升级为“探索工具”。我处理复杂逻辑 bug 时，90% 的时间都在用 --trace 一步步走，比看日志快 5 倍。

4. Backend 场景深度实践：从 API 测试到数据库集成

光会写单元测试不够。backend 工程师的核心价值，是保证整个请求链路的可靠性。这意味着测试必须穿透到数据库、缓存、消息队列。下面以一个真实订单创建流程为例，展示如何用 pytest 构建三层防御体系。

4.1 API 层测试：用 TestClient 模拟真实 HTTP 请求

FastAPI 自带 TestClient ，它能在内存中启动一个精简版服务器，无需网络，毫秒级响应。这是测试 API 层的黄金标准：

# tests/integration/test_order_api.py
from fastapi.testclient import TestClient
from src.api.main import app  # 导入你的 FastAPI app 实例

client = TestClient(app)  # 创建测试客户端

def test_create_order_api_success():
    """测试 /api/v2/order/create 接口成功场景"""
    # 构造请求体
    order_data = {
        "user_id": "u123",
        "items": [
            {"product_id": "p456", "quantity": 2, "price": "99.00"}
        ]
    }
    # 发送 POST 请求
    response = client.post("/api/v2/order/create", json=order_data)
    # 验证 HTTP 状态码和响应体
    assert response.status_code == 201
    data = response.json()
    assert "order_id" in data
    assert data["status"] == "created"
    assert data["total_amount"] == "198.00"

def test_create_order_api_validation_error():
    """测试接口参数校验失败"""
    response = client.post("/api/v2/order/create", json={"user_id": ""})
    assert response.status_code == 422  # FastAPI 的 Pydantic 校验错误
    assert "user_id" in response.text

TestClient 的优势在于：它走通了完整的 FastAPI 生命周期——路由匹配、依赖注入、中间件、Pydantic 模型校验、JSON 序列化。你测的不是函数，而是用户真实调用的 API。

4.2 Service 层集成测试：用 pytest-asyncio + aiosqlite 模拟数据库

Service 层逻辑往往依赖 DAO。我们不想用真实 MySQL（太重），也不想用纯 mock（太假）。 aiosqlite 是一个纯 Python 实现的异步 SQLite，它完美模拟了数据库的 ACID 特性，且启动零成本：

pip install aiosqlite

# tests/integration/test_order_service.py
import pytest
import asyncio
import aiosqlite
from src.service.order_service import create_order
from src.dao.order_dao import OrderDAO

@pytest.mark.asyncio
async def test_create_order_with_real_db():
    """测试 create_order 在真实（SQLite）数据库中的行为"""
    # Step 1: 创建内存数据库连接（:memory: 表示纯内存，每次测试都是新库）
    db = await aiosqlite.connect(":memory:")
    # Step 2: 创建表结构（这里简化，实际应从 migrations 加载）
    await db.execute("""
        CREATE TABLE orders (
            id TEXT PRIMARY KEY,
            user_id TEXT,
            total_amount REAL,
            status TEXT
        )
    """)
    await db.commit()

    # Step 3: 创建 DAO 实例，传入内存 DB 连接
    dao = OrderDAO(db)

    # Step 4: 调用被测函数
    result = await create_order(
        user_id="u123",
        items=[{"product_id": "p456", "qty": 1, "price": 99.00}],
        order_dao=dao  # 注入 DAO，而非依赖全局实例
    )

    # Step 5: 验证数据库状态
    async with db.execute("SELECT * FROM orders WHERE id = ?", (result["order_id"],)) as cursor:
        row = await cursor.fetchone()
    assert row is not None
    assert row[1] == "u123"  # user_id
    assert row[2] == 99.00    # total_amount
    assert row[3] == "created" # status

    # Step 6: 关闭连接
    await db.close()

这个测试的价值在于：它验证了 SQL 语句是否正确、事务是否开启、数据是否持久化。而 :memory: 确保了测试间的绝对隔离。

4.3 端到端测试：用 pytest-xdist 并行跑全链路

当 API、Service、DAO 都验证无误，最后一步是端到端（E2E）测试：启动完整服务，用 requests 调用，模拟真实用户。这很慢，所以要用 pytest-xdist 并行加速：

pip install pytest-xdist

# tests/e2e/test_full_order_flow.py
import requests
import pytest

BASE_URL = "http://localhost:8000"  # 你的本地服务地址

def test_full_order_creation_flow():
    """端到端测试：从创建订单到查询订单"""
    # Step 1: 创建订单
    create_resp = requests.post(
        f"{BASE_URL}/api/v2/order/create",
        json={
            "user_id": "e2e_test_user",
            "items": [{"product_id": "e2e_p1", "quantity": 1, "price": "10.00"}]
        }
    )
    assert create_resp.status_code == 201
    order_id = create_resp.json()["order_id"]

    # Step 2: 查询订单
    get_resp = requests.get(f"{BASE_URL}/api/v2/order/{order_id}")
    assert get_resp.status_code == 200
    data = get_resp.json()
    assert data["order_id"] == order_id
    assert data["status"] == "created"

    # Step 3: 验证幂等性（重复创建同一订单）
    dup_resp = requests.post(
        f"{BASE_URL}/api/v2/order/create",
        json={"user_id": "e2e_test_user", "items": [{"product_id": "e2e_p1", "quantity": 1, "price": "10.00"}]}
    )
    assert dup_resp.status_code == 409  # 冲突，订单已存在

运行时，用 -n auto 参数让 pytest 自动选择 CPU 核心数并行执行：

pytest tests/e2e/ -n auto --tb=short

注意：E2E 测试必须在 CI/CD 中单独运行，且要加 @pytest.mark.e2e 标签，用 pytest -m "not e2e" 跳过，避免拖慢日常开发反馈。

5. 避坑指南：Backend 工程师在 pytest 实战中踩过的 7 个深坑

理论再完美，不避开实操陷阱也是空谈。这七个坑，每一个都曾让我或团队成员加班到凌晨，它们不是文档里的小字警告，而是血泪教训。

5.1 坑一： conftest.py 的作用域陷阱——你以为的全局，其实是局部

很多教程教你在 tests/conftest.py 里写 pytest.fixture ，然后在 tests/unit/ 和 tests/integration/ 里都能用。但 conftest.py 的作用域是 目录树层级 。如果你的结构是：

tests/
├── conftest.py          # 这里定义的 fixture 只对 tests/ 下的测试有效
├── unit/
│   ├── conftest.py      # 这里定义的 fixture 只对 tests/unit/ 下的测试有效
│   └── test_a.py
└── integration/
    └── test_b.py

那么 tests/unit/conftest.py 里的 fixture，在 tests/integration/test_b.py 中根本不可见。更隐蔽的坑是： tests/conftest.py 里的 fixture，如果被 tests/unit/conftest.py 同名覆盖，子目录的测试会用子目录的版本，父目录的测试用父目录的版本。这会导致 test_a.py 和 test_b.py 行为不一致，却找不到原因。

解决方案 ：严格遵循“单一入口”原则。只在 tests/conftest.py 中定义所有共享 fixture，并用 scope="session" 或 scope="package" 明确其生命周期。子目录的 conftest.py 只用于覆盖特定场景，且必须加注释说明。

5.2 坑二： pytest 的 --import-mode=importlib 是救命稻草

当你遇到 ImportError: attempted relative import with no known parent package ，别急着改 __init__.py 。这是 pytest 默认的 import-mode=append 搞的鬼——它把 tests/ 目录加到 sys.path 最前面，导致 import src.xxx 被解析为 tests.src.xxx 。

解决方案 ：在 pytest.ini 中强制使用 importlib 模式：

[tool:pytest]
import_mode = importlib
pythonpath = src

importlib 模式让 pytest 用标准的 importlib.import_module 加载测试，完全遵循 Python 的 import 规则，99% 的路径问题迎刃而解。

5.3 坑三： async fixture 的 event_loop 未关闭，导致测试挂起

写 @pytest.fixture 返回一个 async def 函数时，很多人忽略 event_loop 的清理：

# 错误示范：没有清理 event_loop
@pytest.fixture
async def db_connection():
    conn = await aiosqlite.connect(":memory:")
    yield conn
    # ❌ 忘记 await conn.close()！

这会导致 event_loop 被占用，后续测试卡死。 pytest-asyncio 提供了 event_loop fixture，但你需要显式使用：

# 正确示范：显式管理 event_loop
@pytest.fixture
def event_loop():
    """为每个测试创建新的 event_loop"""
    loop = asyncio.new_event_loop()
    yield loop
    loop.close()

@pytest.fixture
async def db_connection(event_loop):
    conn = await aiosqlite.connect(":memory:")
    yield conn
    await conn.close()  # ✅ 显式关闭

5.4 坑四： monkeypatch 替换失败，因为目标对象已被导入

假设 order_service.py 里写了：

from payment_service import charge  # 直接导入函数

def create_order(...):
    charge(...)  # 调用的是本地变量 charge，不是 payment_service.charge

此时 monkeypatch.setattr("src.service.order_service.payment_service.charge", ...) 会失败，因为 order_service 模块里 charge 是一个独立的引用。

解决方案 ：永远 monkeypatch 被调用方所在模块的命名空间 。上面例子，应改为：

monkeypatch.setattr("src.service.order_service.charge", fake_charge)

5.5 坑五： tmp_path 在 Windows 上的长路径限制

Windows 默认路径长度限制为 260 字符。 tmp_path 生成的路径可能超长，导致 FileNotFoundError 。

解决方案 ：在 pytest.ini 中启用长路径支持：

[tool:pytest]
addopts = --long-path

并在 Windows 系统设置中启用“启用 Win32 长路径”。

5.6 坑六： pytest-cov 统计不到 if __name__ == "__main__": 块

很多脚本在末尾写 if __name__ == "__main__": main() ，用于命令行直接运行。但 pytest-cov 默认不执行这些块，导致覆盖率虚高。

解决方案 ：在 pytest.ini 中添加：

[tool:pytest]
addopts = --cov-config=.coveragerc

并创建 .coveragerc ：

[run]
source = src
omit = */tests/*,*/__pycache__/*
include = */src/*
# 强制执行 __main__ 块
always = true

5.7 坑七：CI/CD 中 pytest 因颜色输出失败

Jenkins/GitLab CI 的终端不支持 ANSI 颜色， pytest 默认的彩色输出会报错 OSError: [Errno 25] Inappropriate ioctl for device 。

解决方案 ：在 CI 脚本中加 --color=no ：

pytest --color=no --cov=src --cov-report=xml

这些坑，每一个都曾让我对着终端发呆半小时。现在我把它们刻在团队 Wiki 首页，新成员入职第一件事，就是把这些坑过一遍。技术没有捷径，但经验可以传承。

6. 工程化落地：将 pytest 深度融入开发工作流

pytest 不是写完就扔的玩具。它的终极价值，在于成为你日常开发节奏的一部分。下面是我推动团队落地的四个关键动作，它们让测试从“负担”变成“呼吸”。

6.1 预提交钩子（pre-commit）：让错误在代码提交前就被拦截

没人喜欢写测试，但所有人都讨厌 CI 失败后被叫去修。 pre-commit 工具可以在 git commit 前自动运行 pytest ，失败则阻止提交：

pip install pre-commit

创建 .pre-commit-config.yaml ：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: check-yaml
      - id: end-of-file-fixer
  - repo: https://github.com/pycqa/pylint
    rev: v2.17.5
    hooks:
      - id: pylint
        args: [--disable=all, --enable=missing-module-docstring,--enable=missing-class-docstring]
  - repo: local
    hooks:
      - id: pytest-unit
        name: Run unit tests
        entry: pytest
        pass_filenames: false
        always_run: true
        # 只运行 unit 目录，秒级完成
        args: ["tests/unit/", "--maxfail=1", "-q"]
        types: [python]

然后运行：

pre-commit install

从此，每次 git commit ，都会先静默运行 pytest tests/unit/ 。如果单元测试失败，commit 被拒绝，终端打印失败详情。开发者立刻修复，无需等待 CI 的 5 分钟。

6.2 GitHub Actions 自动化：每次 PR 都生成覆盖率报告

在 .github/workflows/test.yml 中配置：

name: Run Tests
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install pytest