pytest 的 fixture 夹具我用了快六年从最早把它当成高级版 setUp 使到后来把登录态、数据库会话、临时目录、mock 服务、配置加载统统塞进夹具层中间踩的坑够写一本小册子了。如果你正在做 pytest 接口自动化或者刚从 unittest 迁过来、搞不清 conftest.py 该怎么分层那这篇可以当作一份实操笔记来读。我不打算复述官方文档里 fixture 的定义而是直接讲我在真实项目里怎么组织夹具、为什么这么组织、哪些写法用过一阵之后被我推翻重写。标题写着合集6那说明前面几篇大概率已经聊过用例收集、断言、参数化这些轮到 fixture 正好是把整套框架串起来的关键一环——因为它决定的不只是代码整洁度而是整个测试工程能不能长期维护下去。1. 从 setUp 到 fixture我为什么把项目里的脚手架全部重写1.1 unittest 那套 setUp/tearDown 的真实痛点先说清楚为什么要换。unittest 的模型是每个测试类一份脚手架setUp 里准备资源tearDown 里释放。听着挺合理实际写起来会撞上三个死结。第一个是作用域被类绑死一个登录 token 在 TestLogin、TestOrder、TestPay 三个类里要各写一遍 setUp代码重复率极高。第二个是参数传递只能靠 self 挂属性self.token login()之后子类要拿到还得继承继承链一长谁改了 self 上的字段就成了玄学。第三个最要命想按需初始化资源做不到setUp 是强制的测试类里只要有一个用例不需要数据库也照样得跑一遍连接。我印象很深的一次重构项目里有 40 多个测试类每个 setUp 都有 15 到 30 行不等的准备逻辑抽出来一对比重复代码占了七成。当时改一个接口的鉴权头字段改了 30 多个文件漏了两处CI 上直接挂了一片排查了两个小时才发现是复制粘贴时旧字段名没换。1.2 依赖注入带来的真正变化fixture 的本质是依赖注入这句话很多人听过但没细想。它不是另一种 setUp而是一种完全不同的资源组织方式资源由测试函数声明自己需要什么框架负责把东西递到参数里。这个反转带来的变化是连锁的。资源不再是贴在类上的属性而是有名字、有作用域、有依赖关系的一等对象。def test_order(api_client, db_session, temp_user)这一行签名本身就是文档读代码的人一眼知道这个用例碰了哪些外部依赖。资源可以互相依赖api_client依赖base_urlbase_url依赖settings形成一张有向图pytest 自己会做拓扑排序不需要人工安排顺序。资源的作用域是独立的token 可以是 session 级数据库连接可以是 function 级各管各的互不牵连。我自己的感受是fixture 把测试代码从面向类编程拉回了面向函数编程。测试函数短、依赖显式、没有隐式状态这三条一做到测试用例的坏味道立刻就少了。1.3 迁移时的取舍原则不是所有 setUp 都值得无脑搬进 fixture。我给自己定的规则有三条。纯计算的准备逻辑比如造一个固定结构的字典直接写在函数里或者抽成普通工具函数就行硬做成 fixture 反而增加阅读跳转。需要清理的资源比如临时文件、数据库记录、启动的服务进程必须做成 yield fixture这是硬要求。跨用例共享的、有初始化成本的资源比如浏览器实例、HTTP 会话、数据库连接池才值得做 session 或 module 级 fixture。顺带说一句迁移时别一次性全改。我当时的做法是先建 conftest.py把最通用的几个夹具配置、客户端、登录搭起来新写的用例直接用 fixture老用例保持不动等哪个老用例被改动了就顺手迁一个。三个月下来自然迁完了比集中改造稳妥得多。2. fixture 核心参数逐个拆解scope、yield、params 到底怎么选2.1 scope 五档的生命周期与选型计算scope 决定了 fixture 多久销毁重建一次可选值是 function、class、module、package、session。很多人只知道前三个其实 package 和 session 在大型项目里更有用。最直接的判断方式是按初始化成本和状态污染风险两个维度打分。初始化成本高但用例之间不会互相影响的资源往大 scope 放成本低或者有状态、会互相干扰的就老老实实 function。scope生命周期典型资源我的选择倾向function每个用例一次临时数据、单条记录、mock 对象默认值拿不准就选它class每个测试类一次类内共享的中间产物很少用类这个概念在新项目里越来越淡module每个 py 文件一次模块级只读配置、数据文件加载读多写少的配置类资源package每个包一次打包级的服务实例按业务域分目录时有用session整个测试会话一次HTTP 会话、数据库引擎、token、容器只有确认无状态污染才敢用举个算账的例子。假设数据库连接的建立耗时 0.8 秒整个测试集有 600 个用例。如果全用 function 级光建连接就 480 秒八分钟纯浪费。改成 session 级只需 0.8 秒。但代价是连接必须线程安全而且中间某个用例如果改了连接级别的状态比如切换了当前数据库后面的用例全会受影响。所以我的做法是引擎 session 级、会话对象 function 级用一个 function 级夹具从 session 级引擎里取新会话既省了建连的钱又避免了状态串味。注意scope 的选择本质上是在时间成本和隔离性之间做权衡。没有绝对正确的答案但有一条红线——任何会被测试用例修改状态的资源绝不要放到 session 级。2.2 yield 与 addfinalizer清理逻辑写在哪里fixture 的清理有两种写法yield 和 request.addfinalizer。yield 读起来像普通函数返回代码顺下来很自然addfinalizer 是注册回调可以在函数体任意位置注册多个。我基本只用 yield因为它在同一个函数里就把准备-使用-清理三段式表达清楚了review 的时候不容易漏看清理段。addfinalizer 只在一种场景下会用——清理动作依赖执行过程中才知道的信息。比如启动一个临时服务端口是启动后才知道的但服务对象在 yield 之前就要返回给用例这时候可以在 yield 之后注册 finalizer或者干脆用 yield 返回一个带 port 属性的对象。有个细节新手常踩yield 后面的代码不执行。原因通常是用例里报了断言失败看起来像清理没跑。实际上 pytest 默认会执行 yield 之后的代码除非 fixture 本身在准备阶段就抛异常了——那时候 yield 还没到后面的清理自然不跑。所以我写 fixture 时会把可能失败的准备逻辑放在 try 里或者干脆拆成两个 fixture让清理那个不依赖准备是否成功。import pytest import tempfile import os pytest.fixture def temp_workspace(): path tempfile.mkdtemp(prefixpytest_ws_) print(f\n[setup] workspace created at {path}) yield path # 这一段无论用例成功失败都会执行 import shutil shutil.rmtree(path, ignore_errorsTrue) print(f\n[teardown] workspace removed)2.3 autouse、params、ids、name 的实战组合autouseTrue 的夹具不需要在测试函数签名里声明会自动生效。它很省事也是滥用重灾区。我给自己的规矩是只有所有用例都必须满足的前置条件才配 autouse比如日志初始化、时区统一、随机种子固定。业务相关的资源一律显式声明因为显式声明本身就是一种沟通。params 让一个 fixture 产生多个实例每个实例对应一组参数所有依赖它的用例都会针对每组参数各跑一遍。这个机制配合接口自动化里的多环境特别好用。pytest.fixture(scopesession, params[dev, staging]) def base_url(request): mapping { dev: http://api-dev.internal, staging: http://api-staging.internal, } return mapping[request.param] def test_health(base_url): # 这个用例会自动跑两遍分别针对 dev 和 staging assert base_url.startswith(http)ids 用来给参数实例起个可读的名字不然报告里显示的是base_url0、base_url1看半天不知道哪个是哪个。name 则是给夹具改名当你要用pytest.fixture(nameclient)把函数名和夹具名解耦时用得上但我更常见的用法是在同一个 conftest 里避免重名冲突。实操心得params 和 ids 建议成对写。ids 不给的话参数化 fixture 在多环境场景下生成的上百个用例名会变成天书报告的可读性直接崩掉。3. conftest.py 分层把夹具体系搭成金字塔而不是一坨3.1 可见性规则与目录分层的对应关系conftest.py 里的夹具对同级目录及子目录的测试文件可见对父级和兄弟目录不可见。这条规则听起来简单实际项目里十有八九会出现夹具找不到的报错原因基本都是放错层级。我的分层策略是按抽象层次纵向切而不是按业务模块横向切。最顶层 conftest.py 放全局基础设施配置加载、日志、时区、随机种子这些和业务无关任何用例都可能用。中间层的 conftest.py 放在业务域目录下放这个域共用的客户端、数据构造器、鉴权头。最底层的 conftest.py 放在具体测试文件旁边只放这个文件独有的、脏得不能见人的临时夹具。tests/ ├── conftest.py # 全局settings、logger、时区 ├── api/ │ ├── conftest.py # 域级api_client、auth_headers │ ├── test_order.py │ ── test_pay.py ── db/ ├── conftest.py # 域级db_engine、db_session └── test_migration.py这样切的好处是一个夹具被谁用到看目录结构就猜得八九不离十。反过来如果按业务模块横切最后每个模块的 conftest 里都有七八个几乎一样的夹具副本改一处要改五处就回到了当初 setUp 的老路上。3.2 夹具之间的依赖方向必须单向夹具可以互相依赖但依赖图必须是有向无环的。我见过最离谱的一个案例是auth_headers依赖api_client而api_client又通过某个隐藏途径依赖了auth_headers跑起来报了一堆recursive dependency同事查了一下午没找到原因最后是因为api_client里调了一个普通函数那个函数内部又去拿了一次 headers。避免循环依赖的办法很朴素画一张图把夹具按层次排好箭头只能从上往下。配置层 - 客户端层 - 业务数据层 - 用例层这四层单向依赖基本能覆盖 90% 的场景。如果一个夹具同时依赖上下两层说明它承担了太多职责拆开。还有一种隐形依赖要警惕两个夹具都去改同一个全局变量表面上看不出依赖关系执行顺序一变结果就变。这种情况我会在夹具内部加断言检查全局状态是不是干净的早失败早知道。3.3 把夹具打包成内部插件项目多起来之后同一套夹具会在好几个仓库里重复。这时候可以把夹具抽成一个独立的内部分发包注册成 pytest 插件靠pytest_plugins或者 entry_points 引入。打包成插件后有几个好处夹具的版本被固定下来不会出现 A 项目改了夹具、B 项目被动受影响的情况引入方式变成一行配置不用再往每个仓库拷 conftest.py夹具的单元测试可以跟着包一起走。代价是调试变麻烦插件里的夹具出问题堆栈会跨包得靠--fixtures和-p no:xxx来定位。所以我只在夹具稳定运行三个月以上才考虑抽包早期频繁变动的东西留在 conftest 里改起来快。4. 接口自动化实战从登录态到数据清理的完整夹具链4.1 会话级 token 与请求客户端的封装接口自动化里最先要解决的永远是登录态。粗暴做法是每个用例都调一次登录接口600 个用例就是 600 次登录不仅慢很多系统还有登录频率限制。我把登录拆成两层session 级的认证器负责登录一次并缓存 tokenfunction 级的客户端负责组装请求头。这样 token 只取一次但每个用例拿到的都是独立的 request 会话不会互相污染。import pytest import requests pytest.fixture(scopesession) def auth_token(settings): resp requests.post( f{settings.base_url}/login, json{user: settings.user, pass: settings.passwd}, timeout10, ) resp.raise_for_status() token resp.json()[data][token] return token pytest.fixture def api_client(settings, auth_token): session requests.Session() session.headers.update({ Authorization: fBearer {auth_token}, Content-Type: application/json, }) session.base_url settings.base_url yield session session.close()这里有个细节值得说session.base_url这种写法是把属性挂在 Session 对象上pytest 不会管但静态检查工具可能会报 warning。更干净的做法是自定义一个子类或者在测试里直接拼完整 URL。我图省事就用挂属性的方式但会在 conftest 顶部注释清楚。4.2 数据准备与清理的三种模式测试数据怎么造、怎么清是接口自动化里最容易出脏数据的地方。我总结出三种模式按数据生命周期选。第一种是用完即删适合临时对象。fixture 里创建yield 之后调删除接口。风险是删除失败会留垃圾所以要加 try 包住并在日志里打标记方便后续批量清理。第二种是标记隔离适合不能随便删的业务数据。创建时给数据打一个唯一前缀比如auto_test_{uuid}清理时不删数据只按前缀查出来标记归档。这样既能保证测试数据可识别又不会误删生产数据。第三种是事务回滚适合直连数据库的场景。在 fixture 里开事务测试跑完统一 rollback。这种方式快到极致但有个限制如果被测代码自己管理事务、或者用了连接池rollback 可能不生效。我在一个项目里就栽过ORM 的 session 和测试 fixture 用的不是同一个连接rollback 打了白工数据照样进了库。模式适用场景优点风险点用完即删临时对象、可删除资源干净直接删除接口失败留垃圾标记隔离生产环境只读测试不破坏数据需要定期归档清理事务回滚直连数据库单元级测试速度最快连接池/嵌套事务下失效4.3 params 与 parametrize 组合生成用例矩阵单个 fixture 的 params 只能生成线性组合想做矩阵要用pytest.mark.parametrize叠加。这两者的区别在于作用对象fixture 的 params 作用于所有依赖它的用例parametrize 只作用于被装饰的那个用例。接口测试里最常见的是多环境 x 多角色矩阵。做法是把环境放在 session 级 fixture 的 params 上把角色放在 parametrize 上两者会做笛卡尔积。pytest.mark.parametrize(role, [admin, operator, viewer]) def test_permission(api_client, role, request): resp api_client.get( f{api_client.base_url}/resources, headers{X-Role: role}, ) expect {admin: 200, operator: 200, viewer: 403} assert resp.status_code expect[role]两个环境乘以三个角色就是六个用例用例名里会带上[dev-admin]、[staging-viewer]这样的标识报告一眼能看清失败的是哪个组合。这里要留意的是parametrize 和 fixture params 的叠加会让用例数快速膨胀建议给矩阵规模设个上限超过 20 个组合就考虑用参数文件驱动把组合收进数据表里统一管理。提示叠加参数化时如果某个组合本来就该跳过比如 viewer 角色在 dev 环境没配置用pytest.param(..., markspytest.mark.skip)显式标出来不要靠 try 里吞异常的方式糊过去否则报告里的通过率是假的。5. 常见报错与排查速查表5.1 fixture not found 的五条排查路径这个报错几乎是所有人的入门第一课但它背后至少有五种不同原因。按下面顺序查基本五分钟内能定位。先看名字有没有拼错特别是夹具名和函数参数名不一致的情况def test_x(api_clinet)这种手滑很难一眼看出来。再看夹具所在的 conftest.py 层级对不对同级和子目录才可见。第三看有没有加pytest.fixture装饰器忘了装饰器的话它就是个普通函数pytest 不会注册。第四看文件是不是在 pytest 的收集范围内被--ignore或者norecursedirs排掉的目录里放的夹具不生效。最后看插件冲突有些第三方插件会覆盖同名夹具用pytest --fixtures可以打印出所有可用夹具及其来源路径。报错现象常见原因快速验证方式fixture x not found名字拼错检查函数签名与夹具名fixture x not foundconftest 层级错误把夹具上移到上级目录试fixture x not found忘记装饰器查看是否有 pytest.fixturefixture 找到但值不对插件同名覆盖用 --fixtures 看来源偶发找不到收集范围被排除检查 ini 里的 ignore 配置5.2 scope 混用导致的经典问题高 scope 的夹具不能依赖低 scope 的夹具这是硬规则违反会直接报错。反过来低 scope 依赖高 scope 是允许的而且很常见。真正容易出错的是反过来想当然地写比如 session 级的db_engine依赖 function 级的db_configpytest 会直接拒绝因为配置在会话结束前可能已经销毁了引擎拿不到稳定引用。还有一个隐蔽的坑wipe 行为。pytest 有--setup-show可以看到每个夹具的 setup 和 teardown 时机排查 scope 问题非常好用。我遇到过一次 session 级 fixture 没按预期只执行一次加了--setup-show一看发现测试被拆成了两个会话因为两次 pytest 调用那当然会建两个。夹具本身没问题是调用方式的问题。5.3 并发执行下的状态污染上了 pytest-xdist 之后多个 worker 是独立进程session 级 fixture 会在每个 worker 里各建一份。这时候如果有个 session 级夹具去创建了同名数据库表多个 worker 会打架报表已存在。解决办法是给共享资源加进程唯一标识比如表名或文件路径里带上 worker id通过request.config.workerinput能拿到当前 worker 标识。或者在设计阶段就把这类夹具降级成 function 级用独立的命名空间规避冲突。我现在的习惯是只在确认进程安全的前提下才用 session 级夹具其余情况宁可稍慢一点也不想在 CI 上看到一堆随机失败。6. 几个让夹具更好用的进阶写法6.1 工厂型夹具一个夹具造一批数据固定返回值的夹具只能造一条数据想造多条就得写多个夹具很快就炸了。工厂型夹具的思路是返回一个函数让用例自己决定造几条、造什么。pytest.fixture def user_factory(api_client): created [] def _make(roleviewer, nameNone): name name or fauto_{uuid.uuid4().hex[:8]} resp api_client.post( f{api_client.base_url}/users, json{name: name, role: role}, ) resp.raise_for_status() user resp.json()[data] created.append(user[id]) return user yield _make for uid in created: api_client.delete(f{api_client.base_url}/users/{uid})这个模式的好处是清理逻辑集中在夹具里用例只管造不管删也不怕用例中途失败漏掉清理。我把它当成接口测试里最重要的一把锤子几乎每个资源类型都配一个工厂夹具。6.2 request 对象能做的几件事fixture 的request参数不只是拿param用的它还能拿到测试节点信息、配置对象、以及注册 finalizer。request.node能拿到当前测试项可以读取用例上的自定义 marker从而实现用例打标记夹具按标记改变行为的效果。比如给某个用例打上pytest.mark.offline夹具检测到后自动切换到本地 mock 服务。这种写法比在夹具里写一堆 if 判断要清爽得多。request.config能拿到命令行参数我常用它来读取--env之类的自定义选项让夹具的行为受命令行控制。这样同一套用例可以在本地和 CI 上用不同的夹具参数跑不需要改代码。pytest.fixture def target_env(request): # 读取命令行传入的 --env缺省用 dev return request.config.getoption(--env, defaultdev)6.3 夹具的复用与覆盖子目录的 conftest.py 里可以定义与父目录同名的夹具会覆盖父级的定义。这不是 bug是刻意设计的覆盖机制用来做环境适配。比如父级定义了base_url指向 dev某个子目录里的 conftest 重定义base_url指向本地 mock那么该目录下的用例自动走 mock其他目录不受影响。用这个机制时要克制。覆盖的层级越深读代码时越难判断某个用例实际用的是哪个版本。我在项目里的约定是覆盖只允许出现在第二层第三层及以下禁止覆盖需要差异化就用不同名的夹具把差异显式写出来。说一个我自己踩过的坑收尾。早期我在一个项目里把requests.Session做成了 session 级夹具想着复用连接能快不少结果测试跑一段时间后开始出现偶发的 401。查了很久才发现某些用例会主动去刷新 token刷新后新 token 写在 Session 的 headers 上而那个 Session 是全局共享的导致并行跑的用例拿到的 token 处于改了一半的状态。后来把 Session 降级成 function 级登录 token 单独做 session 级缓存并在请求时动态拼 header问题就没了。夹具的 scope 从来不是越大越好它更像是在隔离性和速度之间画一条线线画在哪儿取决于你的资源到底会不会被用例改动——这一条判断标准比任何经验法则都管用。