Python pytest 实战：别让 fixture 共享状态把 CI 搞成玄学

我在 Python 项目里最怕的一类故障，不是测试直接红，而是 CI 偶尔红。本地重跑全绿，换个分支又红，开了 pytest-xdist 以后更红，最后大家开始说“可能是环境问题”。多数时候它不是环境玄学，而是测试之间偷偷共享了状态。

这篇不写 pytest 入门，也不复述官方手册。我按一次真实排障的方式讲：一个 Python 后端项目里，为什么 session 级 fixture、共享临时目录、没有收口的 monkeypatch 会把测试变成随机炸弹，以及怎么用 fixture 作用域、tmp_path、monkeypatch 和 xdist 把它治理回可重复。

业务场景：订单导出测试偶尔失败

假设我们有一个订单导出模块，测试会创建用户、生成订单、写出 JSON 文件，再断言文件内容。最开始测试跑得很快，于是团队把一些 fixture 提升成 session 级别，想少建几次对象。

# tests/conftest.py
import pytest

@pytest.fixture(scope="session")
def user_cache():
    return {}

@pytest.fixture(scope="session")
def export_dir(tmp_path_factory):
    return tmp_path_factory.mktemp("exports")

def test_create_user(user_cache):
    user_cache["alice"] = {"quota": 3}
    assert user_cache["alice"]["quota"] == 3

def test_export_order(user_cache, export_dir):
    user = user_cache.get("alice", {"quota": 0})
    out = export_dir / "orders.json"
    out.write_text(str(user), encoding="utf-8")
    assert "quota" in out.read_text(encoding="utf-8")

单独跑 test_export_order 可能失败，整套跑可能通过，换个测试顺序又失败。开 pytest -n auto 后更明显，因为不同 worker 的执行顺序、进程隔离和调度时机都在放大这个问题。

踩坑原因：fixture 作用域不是性能开关

pytest 的 fixture 很强，测试函数通过参数请求 fixture，fixture 也可以请求其他 fixture。问题在于，作用域一变，对象生命周期也变了。function 级别通常每个用例拿到独立对象；session 级别则可能让多个测试共享同一个可变对象。

我看到 scope="session" 时会先问三个问题：返回值是不是可变对象？测试会不会写它？这个对象是否承载业务状态？如果三个问题有两个答案是“是”，它就不该为了省几毫秒被提到 session。

第一刀：把可变状态降回 function 级别

稳定测试的第一原则是：每个测试拿到干净上下文。缓存、列表、dict、模拟仓储、导出文件目录，只要测试会写，就让它默认 function 级别。

# tests/conftest.py
import pytest

@pytest.fixture
def user_cache():
    return {}

@pytest.fixture
def order_factory(user_cache):
    def create(user_id: str, quota: int = 3):
        user_cache[user_id] = {"quota": quota}
        return {"user_id": user_id, "total": 128}
    return create

这里我没有显式写 scope="function"，因为 pytest 默认就是 function。默认值反而能提醒后来的人：这个对象是每个用例独立的，不要随便扩大生命周期。

第二刀：文件系统用 tmp_path，不共享工作目录

很多 flaky test 不是内存共享，而是文件共享。比如所有测试都往 /tmp/export.json 或项目根目录下的 output.json 写。CI 并发跑时，A 测试刚写完，B 测试马上覆盖，最后断言读到谁的内容全靠运气。

def test_export_order(tmp_path, order_factory):
    order = order_factory("alice")
    out = tmp_path / "orders.json"

    export_order(order, out)

    assert out.exists()
    assert '"user_id": "alice"' in out.read_text(encoding="utf-8")

tmp_path 给每个测试一块独立临时目录。我的习惯是：除非测试目标就是验证固定路径，否则测试里不写共享目录，不复用文件名，不依赖当前工作目录。

第三刀：monkeypatch 要让 pytest 管回滚

环境变量、当前目录、模块属性、第三方函数 mock，都是污染源。最危险的写法是手动改，然后忘了恢复；或者恢复逻辑被异常绕过。

def test_export_uses_utc(monkeypatch, tmp_path, order_factory):
    monkeypatch.setenv("TZ", "UTC")
    monkeypatch.setattr("app.exporter.now_ts", lambda: 1_717_200_000)

    out = tmp_path / "orders.json"
    export_order(order_factory("alice"), out)

    assert "1717200000" in out.read_text(encoding="utf-8")

使用 pytest 的 monkeypatch fixture，测试结束后环境变量和属性替换会被自动撤回。这个自动回滚不是装饰品，它是测试隔离的安全带。

用 xdist 放大问题，不要用重跑掩盖问题

pytest-xdist 的价值不只是提速。对测试稳定性治理来说，它能把顺序依赖、共享文件、全局状态污染更快暴露出来。我通常会在修复后跑三组命令：

pytest tests/orders -q
pytest tests/orders -q --random-order
pytest tests/orders -q -n auto

如果项目没有随机顺序插件，就至少用 xdist 跑多轮。失败重跑插件可以作为 CI 兜底信号，但不能当修复方案。重跑通过只说明问题不稳定，不说明问题不存在。

上线检查清单

• 所有可变 fixture 默认 function 级别，扩大作用域必须写清楚原因。
• 测试文件输出必须使用 tmp_path 或独立目录，不写共享文件名。
• 环境变量、模块属性、当前目录变更统一用 monkeypatch 管理。
• 禁止测试依赖执行顺序，单测单独跑必须能通过。
• CI 增加 xdist 或多轮验证，把共享状态问题提前暴露。
• 对 flaky 用例先隔离、记录样本、定位污染源，再考虑临时 quarantine。

总结

pytest 不会主动把测试写稳定，它只是给了我们隔离状态的工具。fixture 作用域控制生命周期，tmp_path 隔离文件系统，monkeypatch 帮你自动回滚外部影响，xdist 则能把隐藏的共享状态快速照出来。

我的经验很简单：测试套件越大，越不要迷信“跑得快”。先让测试可重复，再谈性能。一个稳定的 Python CI，背后通常不是更多重跑次数，而是更少共享状态。