接手项目的第一天翻了翻仓库发现测试目录基本是空的仅有的几个测试文件还是当年用unittest写的断言靠self.assertEqual硬凑跑一次要十几分钟还时不时蹦出几个偶发失败。更麻烦的是集成测试和数据打交道的部分根本没有覆盖业务改一行代码心里完全没底。后来花了两周时间把整个测试体系重构成了基于 pytest 的单元测试与集成测试框架从跑单测到拉起真实数据库和外部依赖做集成验证整体效率翻了不止一倍。这篇文章就是那两周实践的完整总结包括了 pytest 的核心用法、fixture 的作用域设计、依赖替换的边界、真实依赖下的集成测试策略以及一堆文档里不常写的坑。不管你是刚接触 pytest还是已经写了不少用例但经常被随机失败和 fixture 复用问题折磨这篇都能给你一些可以直接抄走的思路。1. 单元测试与集成测试的边界先分清再动手很多人一开始就掉进一个陷阱把单元测试写成了集成测试或者反过来。我在重构时第一步不是写代码而是把被测系统的调用关系画清楚然后明确每类测试到底测什么。1.1 单元测试聚焦纯逻辑隔离一切外部依赖单元测试的核心约束是快速、可重复、无副作用。被测函数的输入输出要清晰不该碰数据库、缓存、消息队列更不能依赖网络。我习惯把这类测试称为不启动任何外部服务也能在毫秒级跑完的测试。举个实际例子。某业务模块里有一个计算账单折扣的函数输入订单金额、会员等级、优惠券类型返回实际应付金额。这里面的规则很绕不同会员等级有不同折扣率优惠券叠加还有上限边界条件一堆。用 pytest 写单元测试最直观的写法是这样的# test_billing.py import pytest from billing import calculate_payable pytest.mark.parametrize( amount, member_level, coupon_type, expected, [ (100, normal, None, 100), (100, gold, None, 95), # 黄金会员95折 (100, gold, percent_10, 85), # 折扣叠加后取较低价 (0, gold, percent_10, 0), # 边界0元订单 (10000, diamond, percent_10, 9000), # 优惠金额上限 ], ) def test_calculate_payable(amount, member_level, coupon_type, expected): assert calculate_payable(amount, member_level, coupon_type) expected这里有几个关键设计第一用pytest.mark.parametrize把输入输出表驱动化一组数据就是一个用例新增边界条件只需要加一行测试代码几乎不用动。第二所有输入都是纯内存数据没有 mock、没有文件系统所以这个用例跑一百遍结果都一样。第三注释里写清楚每一条数据为什么存在后面的人改规则时能快速定位哪些组合受影响。1.2 集成测试验证协作行为允许触碰真实依赖集成测试的出发点是验证多个模块串起来之后的行为是否符合预期。比如订单系统里从创建订单、扣减库存、计算折扣到写入数据库这一整条链路单独测每个函数都是对的但拼在一起可能因为事务边界、字段类型转换、并发问题而出错。集成测试可以放慢一点它需要真实数据库或至少是真实依赖的测试替身比如本地容器起的 Redis、PostgreSQL。关键是环境可控、数据可清理。我的经验是集成测试不要试图覆盖所有业务分支只覆盖核心调用链和关键数据一致性否则维护成本会失控。在 pytest 里区分这两类测试我推荐用自定义标记# pytest.ini [pytest] markers unit: 纯逻辑单元测试不触碰任何外部资源 integration: 集成测试依赖真实或半真实的数据库/缓存用例文件里这样标注pytest.mark.integration def test_order_full_flow(): # 会拉起数据库事务、走真实Redis读取 ...跑测试时可以精确分流pytest -m not integration # 日常快速回归只跑单元测试 pytest -m integration # 提交前/CI里单独跑集成测试这一步看起来简单但实际价值非常大。它让快反馈和全面验证不再互相拖累也避免了一个数据库连接失败把几十个纯逻辑用例一起带崩。2. fixture 作用域设计别把每个用例都变成独立王国pytest 最强大也最容易被用错的就是 fixture。我见过不少项目所有 fixture 一律scopefunction每次调用都重新创建数据库连接、重新加载配置、重新初始化一堆对象结果一套测试跑下来大部分时间都耗在了重复初始化上。正确的做法是先理解作用域的语义再根据资源创建成本来选。2.1 session、module、function 三种作用域的真实区别用一个电商订单折扣项目来举例。数据库连接池对象一个进程范围内共享一份就足够某个测试模块里为了让所有用例都基于同一份基础商品数据这组数据模块级初始化一次就可以但订单状态、操作时间这类测试之间会互相污染的数据必须保证每个函数独立。我整理了一个选择表可以参考fixture 资源类型推荐作用域理由数据库连接池 / 网络客户端session创建代价高复用安全连接本身无状态内存缓存预热、基础字典数据module模块内共享即可跨模块共享容易引入隐式耦合用户会话、订单快照、临时文件function数据变化快用例间必须隔离配置对象不随用例改变session全局只加载一遍读取即用用代码来区分会直观很多。下面这两个 fixture一个带缓存预热一个带临时目录import pytest pytest.fixture(scopemodule) def cached_product_data(): 模块内共享的商品基础数据。只构建一次后续用例直接引用。 data build_product_catalog() return data pytest.fixture(scopefunction) def temp_order_store(tmp_path): 每个用例独立的临时订单存储测试结束自动清理。 store OrderStore(tmp_path / orders.json) yield store # 这里不需要手动清理tmp_path 会自动回收2.2 共享资源翻车现场会话级 fixture 的数据污染有一个真实的案例。我给某个项目写的测试里把user_token做成了 session 级 fixture想着登录一次拿到 token 全量复用测试速度确实快。但某个用例里改了用户昵称下一个依赖该用户旧昵称的用例就莫名失败了。排查了很久才发现session 级 fixture 返回的是一个可变对象被前面的用例原地修改了。解决方式很简单session 级的 fixture 返回不可变数据或工厂函数如果要变化的数据就再套一层 function 级的浅拷贝。更通用一点的做法是任何返回可变容器的 fixture默认都用 function 作用域除非有充分的理由确认这个对象在用例间不会被改动。还有一个相关的坑fixture 里不要返回值之后再偷偷做耗时清理。pytest 的 fixture 支持 yield 模式yield之前的代码是初始化yield之后的代码是清理。很多新手把清理逻辑写在用例里结果异常发生时清理逻辑不执行。正确的写法是pytest.fixture def db_session(): conn create_connection() yield conn conn.close() # 无论用例是否抛异常这里都会执行如果某个用例失败了pytest 依然会执行这个清理步骤。测试数据库连接泄漏的问题十有八九就是没按这个模式写。3. 依赖替换的边界monkeypatch 与模拟对象用在哪里最合适单元测试的价值核心是被测代码只测自己。但真实代码不可能完全不碰外部依赖这时就需要替换依赖。pytest 自带的monkeypatch非常好用它可以直接改对象属性、环境变量、删除属性用完了自动还原。3.1 为什么优先用 monkeypatch而不是到处堆 mock 对象我见过一些人写单元测试时凡是调用到别的模块的函数就mock.patch一通最后被测函数里的业务逻辑几乎没测到全在验证 mock 调用参数。这样写出来的用例很脆某个内部函数的参数名一改测试就挂但业务逻辑有没有问题完全看不出来。正确思路是只替换被测函数的外部依赖内部逻辑让它真实执行。拿一个发券服务举例被测函数要从用户服务拿用户等级然后决定发多少券。用户服务调用是外部依赖这里应该替换但根据用户等级计算发券数量是内部逻辑应该真实跑。# test_coupon.py import pytest class UserService: def get_level(self, user_id): raise NotImplementedError def grant_coupon_by_level(user_id): level UserService().get_level(user_id) if level gold: return 100 if level normal: return 30 return 0 def test_grant_coupon_by_level(monkeypatch): fake_user_service UserService() monkeypatch.setattr(UserService, get_level, lambda self, uid: gold) assert grant_coupon_by_level(123) 100这个用例里get_level被替换成了固定返回但剩下两个分支逻辑gold 返回 100、其他返回 0完全真实执行。如果以后发券数量改成按订单金额浮动测试能很快暴露业务变化。3.2 环境变量和系统依赖的替换CI 与本地一致性还有一个常见场景是环境变量。很多配置项通过os.environ读取测试时我们往往需要模拟不同环境的值。用monkeypatch.setenv很直接def test_payment_gateway_timeout(tmp_path, monkeypatch): monkeypatch.setenv(PAYMENT_TIMEOUT, 0.5) monkeypatch.setenv(PAYMENT_RETRY, 0) # 禁用重试 result process_payment({...}) assert result.status timeout需要注意的一个细节是monkeypatch的还原是自动的但如果你在代码里用了全局单例比如模块加载时就读了环境变量缓存到全局变量那么setenv就失效了。碰到这种情况要么修改被测代码让配置读取延迟到运行时要么在测试里同时改全局变量。这也是测试驱动改进代码设计的一个典型例子难以测试的设计往往本身就有问题。4. 集成测试的真实依赖处理数据库事务、缓存清理与接口契约单元测试跑得再绿也不代表系统上线没问题。我在实践里把集成测试分成了三层数据层、缓存层、接口契约层。每一层的策略都不太一样。4.1 数据库层的集成测试用事务回滚代替手写清理数据库集成测试最容易出现的问题就是数据残留。某个用例插了一条订单记录跑完没删下一个用例按某个统计条件一查多出莫名其妙的数据。最稳妥的方案不是挨个清理而是利用数据库事务测试开始前开启一个事务测试结束直接回滚所有写操作相当于从未发生。在 pytest 里用 fixture 实现这个模式pytest.fixture def db_transaction(database_connection): connection database_connection connection.begin() yield connection connection.rollback() pytest.mark.integration def test_create_order_reduces_stock(db_transaction): conn db_transaction create_order(conn, user_id1, sku_id100, quantity2) stock get_stock(conn, sku_id100) assert stock previous_stock - 2这样即使用例中间写错了哪里回滚操作也会把数据库恢复到测试前的状态不会污染其他用例。我试过不少项目用了事务回滚之后随机失败的次数直接降了一个量级。但有一个点必须提醒事务回滚方案只适用于写入操作用了同一连接的场景。如果你的被测代码是通过线程池拿连接事务隔离级别和连接复用没做好回滚可能不彻底。这时候就要考虑直接用容器技术起一个独立的测试数据库每次跑完清空重建虽然慢但最可靠。4.2 缓存层的集成测试等待异步写入而不是立即断言很多项目用了 Redis 做缓存。集成测试里常见的错误是写入 Redis 后立刻断言读取结果偶发失败。原因往往是写入操作是异步的或者有缓冲区延迟。我处理这类问题时会用一个专门的重试断言工具而不是在断言里直接写time.sleep(3)。硬编码等待时间在本地可能够在 CI 机器上因为负载高就可能不够。from tenacity import retry, stop_after_attempt, wait_fixed retry(stopstop_after_attempt(5), waitwait_fixed(0.5)) def assert_cache_value(cache_key, expected): actual get_cache(cache_key) assert actual expected, f当前缓存值: {actual}这个思路可以扩展到任何异步依赖的场景消息队列的消费结果、异步任务的结果回调都可以用重试超时的方式做断言。测试的目的不是复现实时一致性而是验证最终一致性所以断言允许一个短暂等待窗口。4.3 接口契约层的集成测试锁定请求与响应格式接口层集成测试容易被忘掉但恰恰非常值得写。很多前后端联调的问题就出在字段改名、嵌套结构变化、类型不匹配上。pytest 配合一个轻量 HTTP 客户端做契约型断言效果很好。比如某个内部服务接口 POST/orders正常返回201和订单号。契约测试就锁定这两个点pytest.mark.integration def test_order_service_contract(): response http_client.post(/orders, json{...}) assert response.status_code 201 payload response.json() assert set(payload.keys()) {order_id, status} assert isinstance(payload[order_id], str)这种测试的价值不在于覆盖业务逻辑而在于当接口定义发生变化时第一时间把变化暴露出来。尤其是多个服务并行开发时契约测试就是服务之间的契约锁防止某一端悄然改格式导致另一端毫无感知。5. 测试代码不该踩的坑随机失败、断言提示与运行性能这部分是我这两周实践里感触最深的很多问题不跑一段时间根本发现不了。5.1 随机失败的完整排查链路从偶尔挂到定位根因我遇到过一个非常隐蔽的随机失败。测试函数本身逻辑没问题但偶尔报错错误信息指向一个读取文件的操作说文件不存在。单独跑这个用例怎么跑怎么过但全量跑就随机挂。排查链路是这样的先看是不是并发问题pytest 默认单线程排除。再想 fixture 作用域这个用例用了tmp_path创建临时文件另一个测试模块里也有一个 fixture 用了相同的相对路径config.json。两个用例如果都在同一个临时根目录下跑文件就会互相覆盖。最后确认某个模块的 fixture 是 session 级的创建了一个config.json但另一个模块的 fixture 是 function 级的删掉了这个文件再重建。用例执行顺序随机时删除动作可能发生在这个用例读取文件之前。解决方案也简单所有临时文件一律用tmp_path唯一的子目录绝不使用固定的相对路径。这个坑表面上是文件系统问题本质上是 fixture 资源共享边界没划清。经历这一次之后我给自己定了一条铁律测试用例里出现的任何路径都必须来源于 fixture 或临时目录不允许出现硬编码的相对路径。5.2 用-x、--lf和--pdb快速定位问题全量回归跑出几十个失败用例时最忌讳的就是从头到尾全看一遍。我常用的组合拳是pytest -x遇到第一个失败立刻停住。适合在 CI 里快速暴露阻断性问题。pytest --lf只重跑上次失败的用例适合修复过程中的快速迭代。pytest --pdb用例失败时直接进入调试器现场查看变量。另外强烈建议加一个.pytest.ini配置或pyproject.toml里的配置项把-q和--tbshort设为默认减少噪音输出。# pytest.ini [pytest] addopts -q --tbshort testpaths tests5.3 断言输出的可读性善用assert的失败信息pytest 的assert重写功能非常强失败时能显示两边的具体值。但前提是你真的用assert而不是用一些自己拼的布尔表达式。比如下面这个断言assert calculate_discount(...) expected失败时 pytest 会自动展开左右两边的值。但如果你写成assert (calculate_discount(...) expected) is True输出可读性就差很多因为 pytest 不知道你想对比什么。所以断言直接写成表达式应当为真的样子让 pytest 帮你展示具体差异。还有一个小技巧断言大量字段时不要写一长串and那会让失败信息很难看。用字典对比加pytest 会递归显示差异assert actual_order { order_id: ORD-1001, status: PAID, total: 95.0, }如果某个字段不一致pytest 会直接标出是哪个 key、期望是什么、实际是什么排查效率高得多。6. 我踩过几次坑之后的最终配置清单最后分享一套我目前一直在用的 pytest 基础配置组合作为实践的沉淀。它不算复杂但每一步都有具体的原因。# pyproject.toml 或 pytest.ini [tool.pytest.ini_options] testpaths [tests] addopts -q --tbshort --disable-warnings markers [ unit: 纯逻辑测试不依赖外部资源, integration: 集成测试可以触碰数据库、缓存等真实依赖, ] filterwarnings [error::RuntimeWarning]测试目录结构建议这样组织tests/ ├── conftest.py # 全局 fixture主要是业务无关的资源 ├── unit/ # 纯逻辑单元测试 │ ├── test_billing.py │ └── test_coupon.py └── integration/ # 集成测试 ├── test_order_db.py ├── test_cache_async.py └── test_contract.py物理上把单元测试和集成测试拆到不同目录配合-m标记使用比混在一个目录里靠命名猜测清晰得多。很多人觉得麻烦但一个月后回来看这些测试你会庆幸当初花了这几分钟分离它们。按这个方案重构之后原本十几分钟的全量跑缩短到了分钟级单元测试基本秒开集成测试按需触发。对我来说最大的收获倒不是速度快了多少而是每一条用例的职责边界变得异常清楚单元测试挂了一定是纯逻辑问题集成测试挂了十有八九是真实依赖的协作问题。排查的方向感完全不同不再像以前那样每次都要摸黑找半天。