pytest工程化落地：从基础用例到可维护的测试框架

我最早用pytest的时候跟大多数初学者一样经历了从“真香”到“有点懵”的转折。基础语法、断言、fixture、参数化这些单拎出来都看得懂可真到了自己项目里问题一个接一个测试文件越堆越多跑一次全量测试要等半天想临时跳过某些用例只能在代码里注释命令行参数越拉越长每次靠复制粘贴错一个字母就全部重来想给团队一份能看的测试报告截个终端图发过去没人看得懂。这些问题的根源不是你不会写用例而是你还没把pytest当成一个能扛项目的框架来用。Day3这篇我想围绕pytest测试框架的工程化落地把测试发现机制、配置文件、fixture作用域、标记筛选、参数化进阶、常用插件这六件事一次讲透。适合已经能写基础用例、正准备进入真实项目实战的同学参考。1. 测试发现机制pytest为什么有时候“假装没看见”你的测试不知道你有没有遇到过这种情况明明写了一个测试函数肉眼都能找到一执行pytest终端来一句“no tests ran”。第一反应是代码写错了排查半天结果只是名字没起对。这类问题几乎都出在pytest的测试收集规则上。理解这套规则是工程化的第一课也是很多人长期忽视的一课。1.1 默认收集规则的三个隐藏前提pytest收集测试时默认遵守一套命名约定测试文件文件名满足test_*.py或*_test.py测试类类名以Test开头且不能定义__init__方法测试函数和方法函数名以test_开头举个例子下面这个文件无论内部代码写得多么完美pytest都不会运行它# check_login.py def test_user_login(): assert True文件名check_login.py不匹配test_*.py和*_test.py整个文件被直接忽略。这是新手最容易踩的第一个坑而且报错信息里根本不会提示你“文件名不对”你只会看到零用例执行。还有一个隐蔽的坑测试类里如果定义了__init__方法pytest同样不会收集这个类里的测试方法。原因很直接——pytest实例化测试类时不传任何参数一旦存在带参构造方法根本无法创建实例。如果你需要在测试类里做初始化别用__init__放到setup_method或者autouseTrue的fixture里。1.2 自定义收集规则告诉pytest测试长什么样如果项目里的测试命名习惯和默认规则不一致不一定非要强迫自己改过来。在配置文件里可以重写这三个选项[pytest] python_files test_*.py *_test.py check_*.py python_functions test_* *_check python_classes Test* *TestCase这样一来check_login.py能被发现verify_payment()这类函数也能被当作测试执行。但我建议不到万不得已别自定义收集规则。原因有两个第一pytest生态里大量插件默认按标准规则工作改了之后某些插件行为可能不符合预期第二团队来了新人默认规则是公开常识改成自定义规则就多了一份沟通成本。1.3 收集阶段的排查思路执行pytest时加上--collect-only参数可以只看收集结果不实际跑用例pytest --collect-only -v这个命令会打印出pytest准备运行的所有测试项。如果某个测试没被收集到对照上面三条命名规则逐项检查基本都能定位。还有个技巧用pytest --co -q快速浏览收集到的用例数量在重构测试命名时特别好用。我见过有人一上来就在测试函数内部加print调试折腾半小时其实问题只是文件名少了个test_前缀。2. pytest.ini把散落在命令行的配置收进一个文件2.1 命令行参数堆成山之后的痛点跑测试时我见过很多项目是这样执行的pytest tests -v -s --tbshort --maxfail2 -m smoke --htmlreport.html --self-contained-html --covapp第一次敲的时候还挺有仪式感一旦要每周重复执行或者让同事帮忙跑一遍问题就来了参数记不全、复制粘贴出错、多敲了一个引号导致整条命令失效。配置文件的本质就是把这类“项目级约定”固化到仓库里新人clone下来直接敲pytest就能跑而不是先花半天搞清楚命令长什么样。2.2 核心配置项逐个拆解一个比较完整的pytest.ini长这样[pytest] testpaths tests addopts -v -s --tbshort --maxfail2 markers smoke: 冒烟测试用例发布前必须全量通过 slow: 运行时间较长的用例日常开发可跳过 api: 接口回归用例 ui: 界面自动化用例 filterwarnings ignore::DeprecationWarning逐个说testpaths指定测试目录pytest会递归搜索该目录下所有符合条件的文件。如果不配置pytest会从当前目录开始向上查找搜索范围不可控很容易把无关目录的文件也收集进来。addopts在这里追加命令行参数相当于每次执行pytest都自动带上这些参数。但我建议addopts里不要放-m这种需要经常变动的筛选条件否则命令行里想临时覆盖会很别扭。markers注册自定义标记。注册的意义不只是消掉warning更重要的是让团队知道项目里有哪些标记可用。我在冒号后面写一句用途说明新人看配置文件就能明白。filterwarnings统一管理警告。不是把所有警告都关掉而是有选择地忽略那些第三方库产生、无法在测试层消除的警告否则终端输出会被警告刷屏真正的报错反而淹没在噪音里。2.3 rootdir机制配置文件放对位置很重要pytest有一个rootdir概念它默认取当前目录向上查找第一个配置文件pytest.ini、pyproject.toml、tox.ini、setup.cfg所在的目录。rootdir选错会影响conftest的加载顺序、相对路径解析等一堆行为。我建议执行一条铁律把pytest.ini放在项目根目录并且始终在项目根目录执行pytest。在子目录里执行时pytest会向上查找rootdir如果项目里有多层配置文件逻辑很容易混乱。如果确实要在某个子目录单独跑一部分测试用-c参数显式指定配置文件pytest -c pytest.ini tests/api另一个常见坑是src目录结构。项目如果采用src/布局测试模块的import经常失败因为src不在Python的模块搜索路径里。pytest 7.0之后可以在pytest.ini里直接配置[pytest] pythonpath src这个配置比在conftest里手动sys.path.insert干净得多。如果配了pythonpath但导入还是失败优先检查rootdir是否正确很多时候不是路径写错是配置文件的“根”就没找对。3. conftest.py与fixture作用域把公共逻辑“下沉”到合适的位置3.1 conftest.py的层级搜索机制fixture是pytest最核心的特性而conftest.py是fixture的“总部文件”。conftest.py的加载遵循目录层级每个目录都可以有自己的conftest.py它定义的fixture只对该目录及其子目录下的测试生效。这种设计的价值在于控制影响范围。比如你有一个tests/web目录专门做接口测试可以在tests/web/conftest.py里放一个base_urlfixture其他目录的测试不需要这个fixture就不会被污染。反过来放在根目录tests/conftest.py里的fixture则是全局共享的适合放登录token、数据库连接这类每个测试模块都要用的资源。同名fixture的覆盖规则也要清楚测试文件自身定义的fixture优先于conftest.py子目录conftest.py优先于根目录conftest.py。利用这一点可以让根目录提供默认实现子目录做定制化覆盖。比如根目录的base_url返回测试环境地址某个子目录需要在本地调试就在子目录conftest里重写一个base_url其余代码一行不用改。3.2 fixture的五个作用域fixture作用域控制的是创建和销毁的时机。pytest支持五种作用域默认是function作用域执行时机典型场景function每个测试函数执行前后各一次临时数据、mock对象class每个测试类执行前后各一次类级别共享的客户端module每个测试模块执行前后各一次模块内共享的资源package每个测试包执行前后各一次包级别共享的资源session整个测试会话执行前后各一次数据库连接、全局配置作用域越小越安全但开销越大作用域越大性能越好但状态污染风险越高。比如一个session级别的fixture内部如果保存了可变状态某个测试不小心改了它后面所有测试都会受影响。我一般遵循“默认function确实需要共享才升作用域”的原则。写fixture时也尽量返回不可变对象或者每次返回一个全新的副本避免测试之间的隐形耦合。3.3 yield fixture提供数据时记得“关门”fixture在yield之前是setup阶段在yield之后是teardown阶段import pytest import sqlite3 pytest.fixture(scopemodule) def db_conn(): conn sqlite3.connect(:memory:) conn.execute(CREATE TABLE users (id INTEGER, name TEXT)) yield conn conn.close()测试结束时不管用例断言成功还是失败conn.close()都会执行这个机制保证资源一定会被释放。很多人刚接触时只在yield前写代码忘了yield之后做清理等到跑完一堆测试发现连接泄露、临时文件残留再回去查就麻烦了。记住一句话yield之前的代码是准备yield之后的代码是善后两部分缺一不可。3.4 三个高频内置fixturepytest内置了一些非常实用的fixture我日常几乎离不开这三个def test_tmp_path(tmp_path): # tmp_path 是独立的临时目录Path对象 data_file tmp_path / data.json data_file.write_text({user: alice}) assert data_file.exists() def test_capture(capsys): print(hello pytest) captured capsys.readouterr() assert hello pytest in captured.out def test_monkeypatch(monkeypatch): monkeypatch.setenv(DEBUG, true) assert DEBUG in __import__(os).environtmp_path保证每个测试拿到一个独立的临时目录测试结束自动清理不用手动处理文件垃圾capsys用来捕获stdout/stderr验证打印输出monkeypatch用来临时修改环境变量、属性甚至删除对象测试结束后自动还原。这三个fixture能覆盖日常开发中一大半的测试隔离需求比手动写setup和teardown干净得多。4. 标记机制让测试用例按“业务意图”灵活分组4.1 内置标记跳过与预期失败真实项目里并不是每个测试都要跑也并不是每个测试都允许通过。pytest内置了skip、skipif、xfail三个标记专门处理这类场景import pytest import sys pytest.mark.skip(reason功能未实现暂时跳过) def test_feature_not_ready(): pass pytest.mark.skipif(sys.platform win32, reasonWindows暂不支持该协议) def test_linux_only_protocol(): pass pytest.mark.xfail(reason已知的第三方依赖bug预期失败) def test_known_bug(): assert fetch_third_party_data() expectedskip是无条件跳过适合功能还没做完的情况skipif是条件跳过适合当前环境不支持的情况xfail表示预期失败——用例执行了但失败了pytest不会把它报告为普通failure而是报告为xfailed。这三者的区别经常有人混淆我个人的记忆方式skip是不让用例跑xfail是让用例跑但允许它失败。4.2 自定义标记冒烟、慢速、接口、UI自定义标记是工程化的利器。假设你的测试用例已经很多回归一次要20分钟发布前不可能每次都全量跑那就可以给关键流程打上smoke标记import pytest pytest.mark.smoke def test_user_login_success(): assert login(alice, secret123) is True pytest.mark.slow def test_big_data_report(): assert generate_report(1000000) is not None执行时pytest -m smoke # 只跑冒烟 pytest -m not slow # 跳过慢用例 pytest -m smoke or api # 跑冒烟和接口注意-m的参数是表达式语法支持and、or、not的组合可以设计出很灵活的筛选规则。但别忘了在pytest.ini的markers里注册所有自定义标记不然每次执行都报PytestUnknownMarkWarning而且标记名拼写错误只有在运行时才能暴露注册了就能从源头规避一部分低级错误。4.3 按节点ID精确指定测试除了用marker筛选pytest还支持按文件路径、类名、函数名精确指定单条测试pytest tests/test_login.py::test_login_success pytest tests/test_login.py::TestLogin::test_empty_password这个语法在日常开发里比marker更常用。改完一个bug只想跑对应的那一条用例用这个命令几秒就跑完不用等全量测试。配合--lflast failed参数还可以只重跑上次失败的用例。我调试回归问题时几乎天天用这套组合先跑全量看哪些挂改完代码直接pytest --lf全部通过后再完整跑一遍确认没引入新问题。5. 参数化进阶从“循环写用例”到“数据驱动”5.1 基础用法回顾与易错点pytest.mark.parametrize是数据驱动的核心。基础用法多数人都知道import pytest pytest.mark.parametrize(username,password,expected, [ (alice, 123456, True), (bob, wrong, False), (, 123456, False), ]) def test_login(username, password, expected): assert login(username, password) expected这里有两个常见坑。第一当参数只有一组时同样要写成列表嵌套元组的形式比如[(alice, 123456, True)]少了外层列表会导致参数解包错误。第二参数名是字符串pytest会把它作为变量名注入测试函数所以参数名必须和函数签名的形参完全一致差一个字母运行时会报很隐晦的错误。5.2 用ids给测试用例起“人话”名字参数化之后测试报告里的用例名长这样test_login[alice-123456-True]。如果参数是一个很长的字典或JSON报告会变得没法看。这时用ids参数pytest.mark.parametrize( payload,expected, [ ({username: alice, password: 123456}, 200), ({username: bob, password: bad}, 401), ({username: , password: }, 400), ], ids[正确账号, 密码错误, 空参数], ) def test_api_login(payload, expected): assert call_api(payload)[code] expectedids可以传字符串列表也可以传一个接收参数值并返回字符串的函数灵活性更高。给参数化用例起可读的名字带来的好处不止是报告好看。当你想用--deselect排除某条用例时节点ID是清晰的中文描述比一堆默认参数拼接直观太多。5.3 indirect参数化让fixture接收测试参数indirectTrue是参数化最容易被忽略的高级用法。它的作用是把参数值传给同名的fixture而不是直接传给测试函数。看这个例子import pytest pytest.fixture def user(request): role request.param return create_user(role) pytest.mark.parametrize(user, [admin, guest], indirectTrue) def test_permission(user): assert user.role in (admin, guest)测试函数通过userfixture拿数据fixture内部通过request.param拿到参数值。这种模式非常适合“同一套fixture逻辑、不同参数配置”的场景。比在每个测试函数里手动调用fixture函数干净得多也让数据准备逻辑和断言逻辑彻底分离。5.4 从外部数据源动态加载参数参数不一定要写在代码里。从JSON文件读取测试数据是常见做法import json import pytest def load_cases(): with open(cases.json, encodingutf-8) as f: return json.load(f) pytest.mark.parametrize(case, load_cases(), idslambda c: c[name]) def test_from_json(case): assert do_something(case[input]) case[expected]这里有两个注意点。第一打开文件必须显式指定encodingutf-8某些平台默认编码不是UTF-8文件里一旦有中文必炸。第二load_cases()在收集阶段就会执行如果文件路径是相对路径要以rootdir为基准不要用当前工作目录来推断否则在子目录执行时会出现“明明文件就在那里就是读不到”的诡异问题。6. 四个插件撑起工程化的“最后一公里”6.1 pytest-cov覆盖率要这样看覆盖率是最常被误解的指标。先装插件pip install pytest-cov然后执行pytest --covmyapp --cov-reportterm-missing--cov指定要统计的源码包名--cov-reportterm-missing会在终端显示每个文件的覆盖百分比和没被执行到的行号。更实用的做法是在pytest.ini里把覆盖率配置固化[pytest] addopts --covmyapp --cov-reportterm-missing --cov-reporthtml这样每次跑测试都会顺便生成htmlcov目录浏览器打开可以逐行查看覆盖情况。但要明确一点覆盖率是“这段代码被执行过”的度量不是“这段代码被正确验证过”的度量。一个断言都没有的测试也能把覆盖率堆到100%但价值极低。我一般把覆盖率作为团队约定的下限检查而不是上线门槛——低于某个阈值说明测试缺口太大高于95%也不代表质量就好。6.2 pytest-html报告别只留在终端领导或客户不需要看终端日志他们需要一份能看懂的报告。pytest-html插件能把结果生成HTML页面pip install pytest-html pytest --htmlreport.html --self-contained-html--self-contained-html很重要它会把CSS和JS资源嵌入到单个HTML文件里可以单独拷给任何人否则报告依赖一堆静态资源邮件发出去图片全挂。我在持续集成流程里通常把报告保存为构建产物并在通知消息里附上链接测试状态一眼就能看到。6.3 pytest-rerunfailures给不稳定用例一次机会真实项目里总有那么几个“偶发失败”的用例网络抖动、超时、资源竞争原因不是代码有bug但每次失败都打断流水线。pytest-rerunfailures可以处理pip install pytest-rerunfailures pytest --reruns 2 --reruns-delay 1--reruns表示重试次数--reruns-delay表示重试间隔秒数。但我建议只在持续集成环境里启用重试本地开发时关掉。为什么因为重试会掩盖真正的确定性bug——如果一个用例每次都挂重试只是白白把流水线时间拖长。我在实战里的做法是先开着重试观察一段时间把确实属于环境问题的用例单独标记出来再把重试范围缩小到这些用例。6.4 pytest-xdist让测试跑得快一点测试数量上来之后串行执行越来越慢。pytest-xdist提供并行能力pip install pytest-xdist pytest -n auto-n auto让pytest根据CPU核数自动决定并行数。但并行会带来一个问题fixture的作用域语义会被改变。比如session级别的fixture在xdist下默认只在每个worker进程内各自执行一次而不是整个会话只执行一次。如果fixture里有跨用例共享的数据文件、数据库连接可能需要调整设计。我个人的使用建议是单元测试放心并行涉及共享外部资源的集成测试慎重并行事务型数据库测试最好串行否则容易出现数据互相干扰。本来想再补一节完整实战但写到这里内容已经很长了。最后分享一个我写pytest的真实体会很多人追求“用上所有功能”但工程化的本质是让测试成为开发流程里不添乱的环节。与其把所有插件都装一遍不如先做三件事配置pytest.ini把命令固化、用conftest管好共享fixture、用marker把冒烟和回归分开。这三件事做完项目里的pytest就已经比大多数仓库规范了。剩下的插件等遇到了具体痛点再一个个补进去也不迟。