我刚入行做测试开发那阵子，最怕听到的词就是“回归测试”。每次版本要发之前，测试用例几百条，跑完一遍大半天，中途还时不时冒出来几个莫名其妙的失败，排查半天发现是测试代码本身的问题。后来慢慢折腾自动化，接触了一些测试框架，才明白一个道理：测试代码和生产代码一样需要好的设计，而一个好的测试框架能省掉你大量跟框架本身搏斗的时间。在Python这个圈子里，说到测试，绕不开的就是Pytest。近几年Pytest已经成为Python生态里当之无愧的主流测试框架，不只是做单元测试，接口自动化、UI自动化的用例管理、断言断言、测试数据隔离，甚至和CI/CD流水线集成，Pytest都能一把梭。这篇东西就是给还没入坑、或者刚接触Pytest的朋友准备的，从“为什么选它”讲到“怎么写得顺手”，最后聊几个我实际踩过坑的地方，希望能让你少走点弯路。
1. Pytest到底优雅在哪：先搞懂它解决什么问题
1.1 同样的测试，Pytest为什么写起来更短
很多人提起Python测试，第一反应是unittest，因为它是标准库，不用额外安装。但用过unittest写过测试的朋友应该都有同感：样板代码太多了。
用一个最简单的计算器功能来对比。unittest的写法大概是这样的：
import unittest class TestAdd(unittest.TestCase): def setUp(self): self.calc = Calculator() def test_add(self): self.assertEqual(self.calc.add(1, 2), 3) self.assertEqual(self.calc.add(-1, 1), 0) def tearDown(self): self.calc.close()而同样的内容，用Pytest来写：
def test_add(): calc = Calculator() assert calc.add(1, 2) == 3 assert calc.add(-1, 1) == 0 calc.close()一眼就能看出来差别：Pytest不需要继承测试基类，不需要用self.assertEqual这种断言方法，直接用Python原生的assert关键字就行。这意味着你不需要额外记忆一套“断言API”，Python怎么写，测试就怎么写。
有人可能会说：少写几行代码而已，至于吹成这样吗？这里面的差别其实不只是代码量的问题。unittest是模仿Java的JUnit设计出来的，思路偏“重”，强制你用类来组织用例；而Pytest的思路是“函数式”的，鼓励你写扁平的、纯粹的测试函数，把精力放在测试逻辑本身。这种设计直接影响了后面所有的体验，比如fixture的管理、用例的收集、插件的扩展，Pytest都要灵巧得多。
1.2 测试用例自动发现机制
Pytest有一个非常省心的特性：用例自动收集。你在项目目录下跑一句pytest命令，它会按照一套默认规则自动寻找所有测试文件、测试类和测试函数，不需要你像unittest那样手动构造TestSuite和维护“用例清单”。
默认的收集规则如下：
- 文件名：
test_*.py或者*_test.py - 类名：以
Test开头（注意类名不能用__init__构造方法） - 函数名/方法名：以
test_开头
这个设计看起来简单，实际用起来非常舒服。比如你新增一个测试文件，什么都不用配置，只要命名符合规范，运行pytest的时候它就会被自动发现并执行。我在团队里推Pytest的时候，经常跟同事说一句话：写测试之前不需要先查“框架用法”，先把文件命名规范定好，剩下的交给工具。
1.3 断言失败信息友好到离谱
断言信息好不好看，直接决定你排查问题的效率。用unittest写过测试的人应该都见过这种报错：
AssertionError: 3 != 4就这，结束了。你还得自己去代码里找是哪一行、哪个上下文出了问题。而Pytest对assert语句做了非常深度的增强，它会把断言的表达式拆解分析，告诉你到底错在了哪里。
比如下面这段测试：
def test_user(): user = get_user() assert user.name == "admin" assert user.age >= 18如果user.name实际是"guest"，Pytest的报错信息会直接显示：
E AssertionError: assert 'guest' == 'admin' E - guest E + admin你不需要在脑袋里再推演一遍变量值，报错信息已经把实际值和期望值给你对比好了。更复杂一点，如果断言的是assert "admin" in user_names这种表达式，Pytest也会尽可能展示出两边内容、相似度对比的提示。这个能力对定位问题帮助极大，尤其是大型项目里几百条用例跑挂的时候，友好的失败信息就是帮你省时间的。
2. 环境准备与第一个Pytest测试
2.1 安装与基础配置
Pytest的安装没什么特殊之处，直接走pip：
pip install pytest装完以后验证一下版本，确认装好了：
pytest --version这里我建议一点：尽量在虚拟环境里做测试开发，不要直接拿系统Python装包。尤其是公司项目里，不同项目依赖的库版本经常互相打架，用venv或者conda隔离一下能省掉无数个“为什么他能跑、我不能跑”的问题。
如果你是在项目里统一管理依赖，建议把pytest写进requirements-dev.txt或者pyproject.toml的dev依赖组里，方便同事一键拉取环境。另外可以建一个pytest.ini或者pyproject.toml里的[tool.pytest.ini_options]配置段，用来做全局配置，比如指定测试目录、忽略警告、设置公共标记等。基础配置不必一步到位，先跑起来，后面按需加。
2.2 写第一个测试用例并运行
假设你现在有个业务函数，比如从字符串里提取电话号码：
import re def extract_phone(text): pattern = r"1[3-9]\d{9}" return re.findall(pattern, text)对应的测试文件，命名为test_phone.py：
from phone_service import extract_phone def test_extract_phone(): text = "联系我：13812345678，或者打座机010-88888888" phones = extract_phone(text) assert phones == ["13812345678"]运行方式直接在终端执行：
pytest test_phone.py -v-v参数会输出每个用例的详细执行情况，能看到每一条用例跑过还是失败。运行完以后，Pytest会打印出一个汇总，绿色的PASSED看起来就很舒服。
2.3 常用运行参数速查
Pytest的运行参数非常多，但刚开始不需要全记，先掌握这几个就够用了：
| 参数 | 作用 | 例子 |
|---|---|---|
-v | 详细输出 | pytest -v |
-k | 按名称筛选用例 | pytest -k "login" |
-x | 一遇到失败立即停止 | pytest -x |
--maxfail=2 | 最多允许2个失败，超过即停止 | pytest --maxfail=2 |
-m | 按标记筛选用例 | pytest -m "slow" |
--collect-only | 只收集显示用例，不实际执行 | pytest --collect-only |
-k参数尤其好用，表达式的匹配也很灵活，支持and、or、not这些逻辑组合。比如你只想跑注册和登录相关的用例，可以写：
pytest -k "register or login"刚开始接触pytest，建议多试试这些参数，因为用熟了之后你会发现，Pytest不只是一个执行测试的框架，更是一个帮你做用例管理的工具。
3. Fixture机制：Pytest的灵魂所在
3.1 为什么需要fixture：setup/teardown的痛点
写测试最常见的一个需求就是“前置准备”和“后置清理”。unittest里通过setUp和tearDown来做：每个用例执行前先建好环境，执行完再清理掉。但unittest的setUp和tearDown是跟类和用例绑定的，一旦用例变多，这种“寄托在类上”的准备/清理逻辑就会变得非常僵化。
比如你有一堆用例，有些需要连数据库，有些不需要；有些需要造测试数据，有些不需要。如果都用setUp硬写进类的框架里，代码会变得很乱，而且根本做不到“这一个用例需要、那一个用例不需要”的灵活控制。
Pytest给出的答案叫fixture，翻译过来叫“夹具”。它的本质是一个可以复用的“测试环境准备函数”，但比setup/teardown灵活得多。
3.2 fixture基本用法：函数参数即注入
照旧，先看一个最简单的fixture：
import pytest @pytest.fixture def game(): # 准备：创建一个游戏实例 g = create_game() yield g # 清理：游戏结束后释放资源 g.shutdown() def test_game_start(game): game.start() assert game.is_running看到关键点了吗？test_game_start这个测试函数声明了一个参数game，Pytest看到这个参数名之后，会自动去找同名的fixture函数，并把它的返回值注入到测试函数里。这就是所谓的“依赖注入”。你不需要像unittest那样显式调用准备和清理逻辑，只要声明“我需要什么环境”，Pytest就会帮你把环境准备好。
用yield把这函数切成两半：yield之前的代码是“准备”，在用例之前执行；yield之后的代码是“清理”，无论用例跑成还是失败，都会在用例结束之后执行。yield本身返回给测试函数的值，就是fixture的“产物”。这里如果测试函数不需要用到fixture的返回值，只是想让它执行准备/清理，也可以只声明参数而不使用它。
3.3 作用域与自动使用：别再到处复制环境代码
fixture默认是每个测试函数执行前后各跑一次，也就是scope="function"。但有的环境准备成本很高，比如数据库连接、启动一个服务进程、登录一次系统拿到token，如果每条用例都重新来一遍，时间成本扛不住。
Pytest允许给fixture指定作用域：
| 作用域 | 生命周期 |
|---|---|
function | 每个测试函数都跑一次，默认 |
class | 每个测试类只跑一次 |
module | 每个测试模块只跑一次 |
session | 整个测试会话只跑一次 |
用法很简单：
@pytest.fixture(scope="session") def db_conn(): conn = create_db_connection() yield conn conn.close()这个db_conn在整个测试会话期间只会创建一次，后续所有用例都复用它，能省下非常多时间。但是要注意：会话级fixture因为复用同一个实例，用例之间如果互相修改了共享状态，就会产生“测试环境污染”。所以我一直提醒团队：会话级fixture一定要保证它返回的对象是“只读”的，或者每次使用时都从里面拷贝一份可变数据，否则用例之间的隔离性就没了。
还有一种情况：很多用例都要用到同一个fixture，但你又不想在每个函数参数里都写一遍。Pytest支持通过autouse=True让它自动生效：
@pytest.fixture(autouse=True) def setup_logging(): configure_logging()这样定义之后，当前模块（或者conftest所在目录）下所有用例都会自动执行这个fixture，不用在参数列表里声明了。这个功能对于全局打日志、设置环境变量之类的场景非常省事，但慎用，因为隐式执行的东西排查起来相对麻烦一些。
3.4 参数化测试：用一份代码测一堆场景
接口测试里最常见的一个场景是：同一套逻辑，我要用多组数据去验证。比如登录接口，需要验证“正确的账号密码可以登录”、“错误的密码不能登录”、“不存在的用户不能登录”。最朴素的做法是复制三段几乎一样的代码。Pytest的parametrize装饰器，就是专门解决这个问题的：
import pytest @pytest.mark.parametrize("username,password,expected", [ ("admin", "123456", True), ("admin", "wrong", False), ("nobody", "123456", False), ]) def test_login(username, password, expected): assert login(username, password) == expected运行时会生成三条独立用例，每一条都能单独看出是哪组数据挂了。而且失败的那条不影响其他数据继续执行，排查问题的时候，你能直接定位到是“密码错误”的场景挂了，还是“用户不存在”的场景挂了。
参数化还可以叠加，参数多的时候会生成“笛卡尔积”式的组合用例，覆盖边界场景非常有用。我在做接口测试的时候经常用参数化来跑不同角色、不同权限、不同输入的组合，一份代码往往能覆盖几十个用例。
4. 进阶实战：并发、重试、报告一个都不能少
4.1 用例太多跑得慢？试试pytest-xdist
测试用例数量上来之后，最直观的问题就是“跑得慢”。早期我们有个项目的接口用例跑到三千多条，单进程跑下来要四十多分钟，版本迭代一频繁，测试时间就变成了瓶颈。
Pytest的生态里有一个插件叫pytest-xdist，可以让用例并行执行。安装之后，运行命令变成了：
pip install pytest-xdist pytest -n 4-n 4表示开4个进程同时跑，把测试用例平均分给这几个进程。如果你不确定开多少个进程合适，可以直接写pytest -n auto，它会根据CPU核数自动决定并发数。
需要注意，并发执行不是无脑好用的：如果多个测试用例共享同一个数据库、同一个文件、同一个临时目录，并发时会互相干扰。实测下来，一定要先保证用例的隔离性，再上并发，否则你看到的将是满屏的随机失败。我的习惯是“先串行跑到全绿，再开并发”，并发后如果出现偶发失败，优先怀疑共享状态问题。
4.2 不稳定用例：用pytest-rerunfailures做失败重跑
做UI自动化或者依赖外部环境的接口测试，经常会遇到一种诈胡式失败：这次跑挂了，你手动重跑一次，它又绿了。这种用例一般是有外部依赖的，比如页面加载慢了0.3秒、测试数据库的临时网络抖动、第三方服务偶尔超时。
这种“不稳定用例”如果直接出现在测试结果里，会影响整个质量看板的可信度。我的处理办法是：先用pytest-rerunfailures插件做失败重跑，把偶发故障过滤掉。
pip install pytest-rerunfailures pytest --reruns 2 --reruns-delay 1上面这条命令的意思是：如果用例失败，自动重跑2次，每次重试间隔1秒。如果重试之后通过了，这条用例在结果里显示为通过但会标注(rerun)。我曾经在维护一套UI用例的时候，光靠这个插件就把整体通过率从92%拉到了98%以上。
但这里要强调：重试是做“维稳”，不是做“掩饰”。如果你发现某条用例每次都要靠重试才能过，那它就是一条病态用例，真正的问题仍然在那里。建议定期统计哪些用例触发过重试，优先把它们的问题挖出来修掉。
4.3 生成漂亮的HTML测试报告
测试跑完了，需要给团队和领导看结果。Pytest默认的终端输出虽然简洁，但要分享给别人，尤其是不熟悉命令行的同事，还是得有一个像样的报告。
最常用的方案是pytest-html插件：
pip install pytest-html pytest --html=report.html --self-contained-html--self-contained-html这个参数很关键，它会把报告所需要的CSS、JS都嵌进一个HTML文件里。这样你把这个文件发给别人，对方直接用浏览器打开就能看到完整的测试结果、用例统计、失败详情和日志，不需要额外部署服务。
报告里还能带上环境信息、时间戳、作者信息，这些可以在配置里预设。如果你搭建过CI流水线，还可以把报告作为构建产物上传，让团队在浏览器里随时查看历史测试结果。
4.4 大型测试项目的目录结构怎么组织
当测试用例多了，目录结构如果乱七八糟，后面维护起来就是灾难。我目前的项目里，测试目录大概长这样：
project/ ├── src/ # 业务代码 ├── tests/ │ ├── conftest.py # 全局fixture、钩子函数 │ ├── test_api/ │ │ ├── conftest.py # api测试目录专用的fixture │ │ ├── test_login.py │ │ └── test_order.py │ ├── test_unit/ │ │ ├── conftest.py │ │ └── test_calculator.py │ └── data/ │ └── test_users.json # 测试数据 ├── pytest.ini └── requirements-dev.txt几个要点说一下：
conftest.py是一个特殊文件，它不会被当成测试用例，而是专门用来放fixture、钩子函数、插件的。它在哪个目录，作用范围就是那个目录及它的所有子目录。- 测试目录下通常会放
__init__.py，尤其是目录比较多的时候，加上会更稳，避免同名文件互相干扰导致收集异常。 - 业务模块测试数据比如JSON、YAML、CSV这些，单独放进
data目录，跟测试代码分开。测试代码里不要硬编码一长串测试数据，全部从文件或fixture里读，这样数据更新的时候不用动代码逻辑。 pytest.ini是配置入口，比如指定测试目录、设置默认参数、注册mark标记，全都写在里面，比每次命令行敲一长串参数靠谱得多。
配合CI/CD的时候，我一般在流水线的测试步骤里执行：
pytest tests/ -v --maxfail=10 --html=test_report.html --self-contained-html然后把这个test_report.html上传为构建产物。整个过程不需要人工干预，测试结果自动归档，非常省心。
5. 常见问题与排查技巧实录
5.1 用例莫名其妙“收集不到”
这是一个很常见也很容易让人抓狂的问题：明明测试文件就在那里，函数也写了，但跑pytest的时候一条用例都不执行，或者缺少某几条。
先按下面这张表排查，基本能解决90%的情况：
| 现象 | 原因 | 解决办法 |
|---|---|---|
| 整个文件都没有被执行 | 文件名不符合test_*.py或*_test.py规则 | 重命名文件 |
| 文件执行了但函数没跑 | 函数名没有以test_开头 | 重命名函数 |
| 类里的方法没跑 | 类名不是Test开头，或方法名不是test_开头；类里定义了__init__ | 改名，去掉__init__ |
| 文件在子目录里没被发现 | 没有配置pytest.ini的testpaths，或者目录层级过深 | 在配置里指定测试目录 |
还有一个容易踩的坑：如果你的测试文件跟被测模块有源码目录的包冲突，导致Pythonimport时导入了错误的模块，用例会执行异常或者根本无法执行。排查时用pytest --collect-only -v，能看到Pytest实际收集到了哪些用例。这个命令是我调试收集问题的第一工具。
5.2 fixture找不到或行为诡异
fixture相关的报错信息一般比较明显：fixture 'xxx' not found。这种情况通常是fixture定义的位置不对。
Pytest查找fixture的规则是从当前测试文件所在目录开始，一层一层往上找conftest.py，找到第一个同名的就停。所以：
- 如果你在
tests/test_api/下的用例里用了一个fixture，它会先找test_api/conftest.py，找不到再去tests/conftest.py，再找不到去conftest.py（项目根目录）。 - 要注意的是：家目录级别的
conftest.py和低层级目录的conftest.py如果定义了同名fixture，低层级的会“遮蔽”掉高层级的。 - 还有一个坑：同名fixture在不同conftest里同时存在且作用范围交叉时，结果取决于收集顺序，非常容易搞出迷之行为。我的建议是fixture命名不要偷懒，尽量取具体一点的名字，避免同名覆盖问题。
如果fixture返回的实例被多个测试用例共享，scope="session"时引用同一个对象很容易出现“一个用例改了状态，后续用例跟着遭殃”的问题。遇到这种诡异的用例间依赖，先把该fixture的scope改成function试试，通常症状就会消失，然后你再反推是哪里共享了状态。
5.3 断言失败后还想继续执行后续断言
assert写多了以后，你会发现一个痛点：一个用例里写了三个断言，第一个挂了，后面两个直接不执行了。虽然Pytest显示失败信息很详细，但有时候你希望一个用例把所有断言检查完，一次把所有失败点都暴露出来。
这个需求Pytest有几种处理路子。
最简单的做法：拆用例。一个用例只验证一个点，断言信息自然清晰，失败也不会牵连其他检查。
如果你确实想在一个用例里做多重检查、并且失败了也要跑完剩余检查，可以装插件pytest-check或者pytest-assume。以pytest-assume为例：
import pytest def test_multi_checks(): with pytest.assume: assert user.name == "admin" with pytest.assume: assert user.age >= 18 with pytest.assume: assert user.email.endswith(".com")这样即使第一个假设失败了，后面的假设依然会执行并报告，最终汇总所有失败。不过这玩意儿要慎用：它的实现方式对上下文有要求，用的时候别在异常分支里乱套，我团队里出过一个诡异的假通过问题，就是滥用assume导致的。
5.4 缓存目录和临时文件占地方
跑过Pytest次数多了以后，项目里会出现两个东西：.pytest_cache目录和__pycache__目录。前者是Pytest的缓存数据，后者是Python的字节码缓存，这些都没必要提交进版本库。
建议在项目根目录的.gitignore里加上：
__pycache__/ *.py[cod] .pytest_cache/另外，Pytest有个--cache-clear参数，可以在测试前强制清掉缓存。有些诡异的“改代码不生效”问题，经常就是因为缓存和字节码残留，加这个参数重跑往往能解决。如果遇到“我明明改了代码，但跑测试还是老结果”这种灵异事件，第一反应就是清缓存。
5.5 在CI流水线里跑pytest的注意事项
在CI环境里跑Pytest，有几个跟本地跑不一样的坑。
第一个是Python版本。本地是3.10，CI是3.8，很可能有些语法或依赖行为不一样，导致测试结果不一致。建议在流水线里统一指定Python版本，跟开发环境保持一致。
第二个是无头环境。如果你有UI自动化测试在CI里跑，需要配置xvfb之类的虚拟显示环境，否则浏览器根本起不来。
第三个是重试策略。CI环境网络、资源都不如本地稳定，尤其当你开并发的时候，偶发失败率会上升。我一般会在CI命令里加--reruns 1做兜底，但不会加太多，次数太多会把真实问题掩盖掉。
5.6 其他一些零散的小经验
写完一个测试文件之后，随手跑一下pytest --collect-only -v确认用例都被收集到了，再往下写。我见过太多同事写了半天，最后发现文件命名不对，整个文件根本没被测。习惯这个东西，能救你于水火。
如果测试代码里有比较耗时的用例，可以用@pytest.mark.slow之类的自定义标记把它们标出来，然后在常规流水线里用-m "not slow"跳过它们，单独做一条“慢速测试”流水线去跑。这样常规回归能控制在几分钟内，慢测试又不至于漏掉。
关于conftest.py还要多说一句：不要把所有的fixture都堆进根目录的conftest.py里。全局fixture放全局的，目录相关的fixture放各自的目录里，这样不同模块之间的测试环境依赖就解耦了。等项目变大之后你就会发现，fixture分层管理比“一个大仓库”式管理省心太多。
最后，说点个人体会
我用了几年Pytest之后，最大的感受是：它不是一个让你“学会”的工具，而是一个让你“用顺”的工具。对比当年用unittest时那股“测试代码比业务代码还难维护”的憋屈感，Pytest至少让你在写测试的时候不再有心里抵触。到现在我带团队做接口自动化，首选组合还是Pytest加requests加pytest-html，原因无他：简单、稳定、够用。
如果你刚开始接触测试开发，我的建议是先别追求什么高深的花样，老老实实把fixture、参数化、断言这三板斧练熟，再逐步加插件、上并发、接CI。不用一上来就折腾全套插件配置，等实际有痛点了再补也不迟。
最后再分享一个小技巧：如果你在用Pytest做项目的接口测试，配合pytest-ordering这类插件去控制用例执行顺序，看起来很方便，但我不太建议依赖它。用例的执行顺序一旦被人为写死，用例之间的隐式依赖就会慢慢滋生，到最后你会进入“用例单独跑能过、全部跑就挂”的怪圈。好的测试设计应该是让用例彼此独立，执行顺序随意，这样才能保证每次回归都是稳定且可信的。
