pytest用例收集规则与精准运行指定用例指南

做自动化测试的人迟早会跟 pytest 打交道。我用这个框架时间越长越发现一个规律很多人用例写得挺顺手但一旦遇到“我只想跑某一条用例”“为什么这个文件里的用例没被执行”“为什么全量跑的时候 pytest 一声不吭就跳过了一堆文件”这类问题就开始抓瞎。这些问题背后其实是同一个核心机制——pytest 的用例收集规则。如果你不搞清楚 pytest 到底按照什么标准去“发现”用例那么你在写用例、跑用例、排错的时候都会多走很多弯路。这篇文章就把 pytest 的收集规则和“运行指定用例”这件事掰开揉碎了讲一遍。我会先带你理解 pytest 收集用例的底层逻辑再讲清楚默认规则和配置入口然后重点拆解如何用文件路径、节点 ID、表达式筛选、marker 标记这些手段精准地运行某一条、某一类用例。文章最后整理了我在实际项目中踩过的高频坑和排查方法全部是可直接落地的东西适合刚入门 pytest 的新手也适合已经在项目中大量使用 pytest、但还没系统性梳理过收集机制的从业者。1. 先搞清一个前提pytest 是怎么“看见”你的用例的1.1 收集机制它其实在做一个带规则的目录扫描很多人把 pytest 理解成一个“执行器”觉得只要把测试文件丢进某个目录运行 pytest 它就会自动跑起来。这个理解不算错但过于粗放。更准确地说pytest 在真正执行你的测试函数之前会先做一步叫做“collection收集”的动作。collection 可以理解为一场带规则的目录扫描。pytest 会从你指定的路径开始向前遍历所有目录和文件然后根据一套默认命名规则判断这个文件是不是用例文件、这个类是不是用例类、这个函数是不是用例函数。符合规则的就会被收集起来形成一个待执行的用例列表不符合规则的即使文件里写得再像测试pytest 也会视而不见。把这场扫描理解成一个快递分拣过程会更容易记住。pytest 就像一个分拣员它只看包裹上的标签——文件名、类名、函数名——标签符合标准的包裹才进分拣线标签不清晰或者不符合约定的直接放在一边不处理。所以当你发现“我的测试明明写了但没跑”的时候先别怀疑代码逻辑先怀疑你的包裹标签是不是贴错了。这个收集动作发生在用例执行之前但你可以通过--collect-only参数单独查看它不会真正执行任何测试函数。这个参数在排查问题时极其有用后面我会专门讲。1.2 默认规则的三层过滤文件层、类层、函数层pytest 的默认收集规则其实就三个层次文件层、类层、函数层。文件层要求测试文件名必须以test_开头或者以_test.py结尾。也就是说test_login.py、test_user_center.py符合规则login_test.py也符合但login.py、test_demo.txt这种就不行。类层要求测试类必须以Test开头并且类中不能有__init__构造函数。TestLogin可以LoginTest不行TestLoginWithInit如果定义了构造函数pytest 也会拒绝把它作为测试类收集。这点很容易被忽视很多人从 unittest 迁移过来后习惯在测试类里写setUp这个没问题但如果你顺手写了个__init__pytest 会直接报错或者跳过这个类。函数层要求测试函数必须以test_开头。普通函数def check_login()不会被收集只有def test_login()这种才会。此外 pytest 还允许在类外面写测试函数也会被正常收集。这三个层次是环环相扣的。如果你某个文件叫test_data.py但里面的函数叫load_data()那么文件会被扫描到函数却不会被收集如果你在login.py里面写了def test_login()那么文件这一关就过不了整个文件的用例都不会被发现。这里有一个容易被忽略的细节pytest 的默认收集路径是递归的。你运行pytest时它会从当前目录开始向下递归搜索所有目录和子目录只要进入的目录下有符合规则的文件都会被收集。这一点对项目结构的影响很大后面第 5 节会专门讨论它带来的“连带执行”问题。2. 收集规则不是死的三个配置项和两个隐形变量2.1 python_files / python_classes / python_functions 怎么配置最稳默认规则虽然简单但真实项目中往往会因为团队代码风格不同而需要调整。pytest 提供了三个配置项分别对应文件层、类层、函数层的规则覆盖python_files控制哪些文件被视为测试模块文件python_classes控制哪些类被视为测试类python_functions控制哪些函数被视为测试函数这三个配置项可以写在pytest.ini、pyproject.toml、tox.ini或setup.cfg里。我自己的习惯是优先用项目根目录下的pytest.ini因为它的可读性最好设置项也最直观不容易产生歧义。用pyproject.toml也完全可以但要注意把配置放在[tool.pytest.ini_options]下面。举个例子假设你们的测试文件统一命名成check_xxx.py你可以在pytest.ini里写成这样[pytest] python_files check_*.py python_functions check_* python_classes Check*这样 pytest 就会把check_login.py视为测试文件把def check_login()收集为测试函数。改完之后用--collect-only验证一下确认你期望的文件都被收集进来了。这里提醒一句自定义规则是有代价的。当你修改了默认命名习惯后pytest 生态里的很多第三方插件、IDE 的右键运行功能、以及 CI 脚本里的匹配逻辑都可能基于“默认规则”去搜索用例。比如 PyCharm 的 pytest 运行器在识别测试用例时如果发现你的命名风格完全自定义可能无法正确高亮或运行单条用例。所以能不改就尽量不改除非团队有非常强的统一命名约束。2.2 conftest.py 和init.py 对收集的隐形影响除了那三个配置项还有两个文件会在收集时产生你意想不到的影响conftest.py和__init__.py。conftest.py是 pytest 的插件和 fixture 配置文件它本身不会被当作测试文件收集但它所在目录会影响 pytest 的收集范围。简单来说pytest 会把conftest.py所在的目录作为“根目录”之一在这个目录及其子目录下搜索用例。如果你的项目有多层目录结构每个子目录下都放了自己的conftest.py那么它的生效范围就限定在那一层目录内。这个机制用好了是分层管理 fixture 的好工具用不好就会出现“为什么我明明加了 fixture 却提示找不到”的诡异问题。__init__.py的影响更隐蔽。pytest 在收集用例时如果发现某个目录下存在__init__.py它会把该目录当做 Python 包来处理用例的模块名会带上包路径。没有__init__.py的目录pytest 则使用“根目录下的相对路径”作为模块名。这两种方式在大多数情况下都能正常收集但如果你在同一个项目里混用了“带__init__.py的目录”和“不带__init__.py的目录”某些情况下会出现模块名冲突导致用例重复收集或者明明两个不同文件却被判定为同一个模块。我的建议很简单要么整个测试目录统一都不用__init__.py要么每一层都用。混用是最容易出问题的状态。pytest 官方文档其实也更推荐测试目录不主动加__init__.py这样各个测试模块之间互相隔离收集时的模块名更简洁。2.3 用 --collect-only 复盘你的用例清单在调整任何收集规则之前我强烈建议你先跑一遍--collect-only把当前规则下 pytest 到底收集了哪些用例看清楚。这个参数可以接路径也可以不带路径全局扫描。pytest --collect-only -q终端会输出所有被收集到的用例的节点 ID每条用例一行。如果你只想看某个文件下的用例pytest tests/test_login.py --collect-only-q是 quiet mode让输出更简洁只显示用例节点列表不会附带多余的信息。这是一个非常强的“地图工具”——你只有知道 pytest 眼里的用例地图长什么样才能精准地“指哪打哪”。实际项目里我一般这样用新接到一个遗留项目先跑--collect-only看看这个项目到底有多少用例、哪些文件被识别、哪些文件被漏掉。输出结果直接能反映出收集规则和目录结构的问题比肉眼扫描文件夹要靠谱得多。3. 运行指定用例的实战姿势从整文件到精确节点3.1 按文件和目录运行日常最常用但最容易被忽略的细节最基础的指定方式就是直接给 pytest 传文件路径或目录路径。这个操作谁都会但有几个细节值得注意。运行某个测试文件pytest tests/test_login.py运行某个测试文件中的全部用例上面这条命令就够。运行某个目录下的全部用例pytest tests/这里会递归收集tests/目录下所有符合规则的文件包括子目录。很多人以为只跑这一层实际跑起来发现子目录全被扫了如果这不是你想要的要么把目录粒度拆小要么用后面要讲的-k或节点 ID 去过滤。还有一个非常实用的细节pytest 允许同时传多个文件或目录pytest tests/test_login.py tests/test_cart.py tests/api/这种多目标指定方式在回归的时候特别有用。比如这次改动只涉及登录、购物车、订单这三个模块你可以只挑这有限的几个路径来跑而不是傻乎乎地全量跑一遍整个套件能把单次回归时间从半小时压缩到五分钟。传路径时还有一点要留意路径可以是绝对路径也可以是相对当前工作目录的相对路径。建议统一用相对路径这样脚本在团队内不同机器上迁移时不容易出问题。3.2 用节点 ID 精确定位文件::类::函数三级寻址如果文件里只有一两个用例指定文件就够了。但真实项目中一个测试文件里往往有多个类、多个函数你想单独跑其中某一条用例就得用到 pytest 的“节点 IDnode ID”机制。节点 ID 的格式非常有规律就是文件路径加两个冒号加类名再加两个冒号加函数名tests/test_login.py::TestLogin::test_success运行的时候直接把这个节点 ID 拼在 pytest 后面pytest tests/test_login.py::TestLogin::test_success这条命令只会执行TestLogin类下的test_success这一个函数同一个文件里的其他测试函数不会被运行。这是日常开发中最高频的操作改完一个接口只想验证对应的那一条用例就用节点 ID 精确运行秒级反馈。如果测试函数不在类里面而是模块级别的独立函数节点 ID 就省略类名那一段pytest tests/test_login.py::test_success如果只想运行某个测试类下的所有方法可以只写到类名pytest tests/test_login.py::TestLogin节点 ID 的前半段不一定非得写全路径pytest 支持用相对当前目录的路径来匹配。比如你在项目根目录运行上面这样写没问题如果你当前在tests目录里运行那直接pytest test_login.py::TestLogin也可以。这里我踩过一个小坑如果你在 Windows 下用反斜杠拼接节点 ID 传给 pytest有些版本会解析出错。建议统一使用正斜杠/兼容性最好。3.3 参数化用例怎么单独跑节点 ID 里的方括号pytest 最强大的功能之一是参数化但参数化带来一个实际问题一个测试函数被参数化生成 10 条用例后它们共用同一个函数名节点 ID 怎么区分答案在方括号里。当你对某个函数加了pytest.mark.parametrize之后pytest 会自动生成带参数 ID 的节点。举个最简单的例子import pytest pytest.mark.parametrize(username, [alice, bob, carol]) def test_login(username): pass用--collect-only看你会看到三条用例tests/test_login.py::test_login[alice] tests/test_login.py::test_login[bob] tests/test_login.py::test_login[carol]想单独跑bob那条命令就是pytest tests/test_login.py::test_login[bob]如果你用了自定义的参数 ID比如pytest.mark.parametrize(username, [alice, bob], ids[normal_user, blocked_user]) def test_login(username): pass那么节点 ID 就变成tests/test_login.py::test_login[normal_user]和tests/test_login.py::test_login[blocked_user]按这个 ID 运行即可。参数化节点 ID 在 shell 里如果包含特殊字符比如空格、括号、引号最好给整个节点 ID 加上双引号避免被终端解析出问题。我经常看到有人复制节点 ID 后忘了加引号结果命令直接报错其实不是 pytest 的问题是 shell 的转义问题。3.4 -k 表达式筛选模糊匹配的威力与边界节点 ID 是精确寻址-k则是模糊匹配。它可以在你给定的路径范围内根据表达式筛选符合条件的用例。-k的匹配对象是完整的节点 ID 字符串包括文件路径、类名、函数名、参数化 ID 等所有部分。表达式支持and、or、not以及括号组合。举个例子你想跑所有名称里包含login的用例pytest -k login这条命令会匹配test_login.py文件里的所有用例以及任何用例名里带了login这个字符串的用例。因为文件路径test_login.py也参与匹配。如果你想跑登录和注册两个模块的用例其他全部跳过pytest -k login or register想排除某些用例pytest -k not slow组合使用pytest -k login and not param-k还可以用来筛选参数化生成的子用例。比如你只想跑参数化 ID 为alice和bob的两条pytest -k alice or bob但这里有个很容易忽略的边界-k做的是子串匹配不是正则表达式匹配也不是精确匹配。所以-k alice会把节点 ID 中包含alice这个字符串的所有用例都匹配出来包括文件名、类名、参数值里带alice的情况。如果你的测试数据里有alice_special_case这种 ID也会被一并选进来。想要更精确还是用节点 ID。还有一个实战心得-k在 CI 流水线里特别适合做小范围的冒烟筛选。比如你在提交代码后只想快速验证核心路径可以用pytest -k smoke or critical这种写法不需要改动任何测试文件。3.5 一个分支路径参数与 -k 是叠加生效的这里有个很多新手不清楚的点路径参数和-k是叠加关系不是替代关系。也就是说pytest tests/test_login.py -k alice这条命令先限定扫描范围在tests/test_login.py这一个文件内再在这个文件收集到的用例中筛选节点 ID 含alice的用例。先用路径缩范围再用关键字过滤是我个人最推荐的组合打法。这样可以避免-k在全局范围内误伤其他目录下的相似用例。类似的叠加关系也适用于-m标记筛选下面会讲。4. 按标记选用例-m 和 pytest.ini 的 markers 配置4.1 -m 的用法与逻辑表达式除了按名称筛选pytest 还提供了一种更语义化的筛选方式按 marker标记运行。你可以在测试函数或测试类上加一个标记然后在运行的时候通过-m参数选出这些用例。import pytest pytest.mark.smoke def test_login_success(): pass pytest.mark.slow def test_full_payment_flow(): pass运行标记为smoke的用例pytest -m smoke-m同样支持逻辑表达式写法比-k还要灵活一点pytest -m smoke and not slow这表示运行标记为smoke但又不是slow的用例。这在冒烟测试场景里非常实用我只想跑核心用例慢用例一概不理。-m的参数也可以配合路径使用pytest tests/test_login.py -m smoke在大型项目中建议在pytest.ini里先注册好你计划使用的所有 marker避免出现拼写错误时 pytest 只给一个 warning 而不是报错。注册方式如下[pytest] markers smoke: 冒烟测试用例 slow: 慢速用例 regression: 回归用例注册之后如果你在代码里用了未注册的 markerpytest 会给出比较明显的警告信息方便你发现拼写错误。4.2 -m 与 -k 的分工与配合-k和-m看起来都能筛选用例但它们的分工不同。-k关注的是“名字”-m关注的是“属性标记”。名字是代码本身的标识标记是人为附加的语义分组。实际工作中两者常常配合使用形成多级过滤。比如pytest tests/ -m smoke -k login这个命令的思路是在tests/目录下先找所有标记为smoke的用例再在这些用例中筛选节点 ID 含login的。适合你有一个完整的 smoke 标记集合但今天只想关心登录部分的场景。还有一点值得说明标记可以加在类上那么这个类里的所有测试函数都会继承这个标记。标记也可以加在模块变量pytestmark上对整个模块生效import pytest pytestmark pytest.mark.smoke def test_login(): pass def test_logout(): pass这种“模块级标记”在维护老项目时很省事不用一个个函数去加装饰器。不过要注意团队内部的一致性有人用模块级、有人用函数级读代码时容易混乱。5. 高频翻车现场与排查技巧速查5.1 明明写了用例却报 no tests ran问题出在哪“no tests ran”可能是 pytest 使用频率最高的报错。排查顺序我建议按下面这样来第一步用--collect-only看当前规则下到底收集了什么。如果 collect-only 输出里什么都没有说明是收集规则的问题不是执行的问题。第二步检查文件名。是不是叫login.py而不是test_login.py是不是叫login_testcase.py而不是test_login.py自定义规则没配置的话文件名不对就是会被无视。第三步检查函数名。def check_login()不会被收集def test_login()才会。类名同理class LoginTests不会被识别class TestLogin才行。第四步检查运行命令。你是不是不小心运行了pytest test_login.py -k somecase而somecase在这个文件里根本不存在-k过滤后没有匹配项也会报 no tests ran。最后一步检查是不是被__init__.py影响了模块路径。如果目录结构里存在包冲突pytest 可能会跳过某些目录这种情况在复杂的 monorepo 项目里比较常见。5.2 只跑一条用例结果整个目录都跟着跑这个问题通常出现在你直接运行pytest或pytest .的时候。pytest 默认从当前目录递归收集如果你的当前目录是项目根目录它就会把整个项目下的所有符合规则的测试文件全部收集进来执行。解决办法很简单运行用例前先明确路径。想跑单文件就写文件路径想跑单条用例就用节点 ID。不要在命令行偷懒只写一个裸的pytest除非你确实想跑全量。还有一种容易被忽略的情况pytest.ini中配置了testpaths字段。比如[pytest] testpaths tests这种情况下你运行裸的pytest它只会去tests目录收集。如果你手动指定了其他路径testpaths就不再生效这个细节在 CI 脚本里经常把人绕晕。另外如果你的项目里存在多个目录都符合收集规则而你在其中一个目录里运行pytest它会以当前目录为起点向下递归。这就解释了为什么你只是想跑当前目录下的用例结果子目录里的用例也全部跑了。不想递归的话可以改用--ignore参数pytest --ignoretests/old_tests或者用--ignore-glob配合通配符忽略一批文件。我在重构测试代码时经常用--ignore临时屏蔽掉旧目录等新用例稳定后再移除。5.3 排查三板斧--collect-only、-v、--tbshort遇到任何用例收集或定位问题我通常会按顺序使用三个参数--collect-only先看收集结果确认 pytest 眼中的用例清单-v收集并显示详细执行结果可以逐条确认每个用例的状态--tbshort报错时只输出简短的 traceback避免日志被刷屏举一个我最近遇到的实际案例。项目里有个文件叫test_order.py里面有一个TestOrderCreate类类里有 6 个方法但全量跑的时候只执行了 4 条。我第一反应是去读代码发现其中两个方法名写成了create_order_success()和create_order_failed()缺少test_前缀。pytest 不会去猜你的意图它只看命名。改回test_create_order_success()后用例立即恢复收集。--tbshort还有个好处当你用节点 ID 运行单条用例时如果用例内部抛出异常--tbshort会把出错的代码行和关键调用栈显示出来但不会像默认模式那样打出一大段无关的框架内部信息。对定位问题来说信息量刚刚好。5.4 实用避坑清单最后整理一份我自己长期积累的检查清单按优先级排列测试文件统一用test_*.py命名不要混合*_test.py除非团队有明确理由测试函数名统一test_开头类名统一Test开头不要给测试类写__init__方法目录结构里不要混用__init__.py要么全有要么全无节点 ID 在 shell 中尽量用双引号包裹尤其是带参数化 ID 的用例参数化 ID 尽量用可读性好的英文标识不要用索引数字否则--collect-only输出会很难认修改pytest.ini里的python_files等配置后一定要跑一次--collect-only确认影响范围尽量少用裸的pytest命令去跑全量除非你确定项目的testpaths设置符合预期-k是做子串匹配不是正则也不是精确匹配要精确就写全节点 ID-m与-k可以叠加但要注意叠加顺序先路径缩范围再标记过滤最后关键字过滤我在实际项目中遇到过最费时间的一次排查是同事把pytest.ini里的python_files从test_*.py改成了test_*.py但前面多了一个空格结果所有文件都匹配不上全量运行直接 0 tests ran。这种配置类问题肉眼很难发现但--collect-only一秒钟就能暴露出来。所以遇到“用例突然消失”的问题永远是先查收集再查代码。6. 把收集规则变成你的“用例地图”搞懂了 pytest 的收集规则和运行指定方式之后你会发现它不是一堵墙而是一张地图。你知道用例在哪个目录、叫什么名字、怎么被分组、怎么被挑选你就可以在任何时候精准地跑任何一条用例。我个人最习惯的一套工作流是平时开发时改完一个接口就用节点 ID 跑对应的一条用例确认通过再继续写下一个功能提交代码前用-m smoke跑一遍冒烟集快速排除核心路径的明显问题合入主干前的完整回归才会跑全量套件。这套组合拳配合下来既保证了效率又不牺牲质量。最后再分享一个建议如果你所在的团队还没有统一 pytest 用例命名规范和运行约定不妨把这篇文章里提到的几种筛选方式整理成一页简短的文档放进项目仓库尤其是--collect-only、-k、-m这几个命令。新人接入项目时最容易困惑的就是“我该跑哪些用例、只跑一条用例该怎么跑”有了这份约定他们就能少走很多弯路团队里的 pytest 使用体验也会顺畅很多。