Pytest是Python生态里最流行的测试框架之一，它语法简洁、插件丰富，几乎成了自动化测试的标配工具。但再好用的框架，如果连用例怎么执行都搞不清楚，后面的维护和调试都会寸步难行。本文就把pytest执行测试用例的各种方式系统地梳理一遍，从最简单的命令行用法到代码内调用，再把新手常犯的错误一个个拎出来讲明白，帮你少走弯路。
一、执行pytest用例的基本方式
pytest执行用例最直接的方式就是命令行。打开终端，切换到项目目录，直接输入pytest并回车，框架会自动从当前目录开始递归查找符合规则的测试文件，收集里面的测试函数和测试类，然后逐个执行。整个过程不需要写任何额外的入口代码，这也是pytest比unittest用起来省心的地方。
pytest收集用例遵循一套默认规则：文件名必须以test_开头或者以_test结尾，比如test_login.py、utils_test.py；类名要以Test开头，并且类里面不能有__init__方法；函数名必须以test_开头。只有同时满足这些条件，用例才会被识别。如果直接执行pytest但一个用例都没跑到，第一时间就应该检查命名是否符合这套规则。
除了直接敲pytest，也可以通过python -m pytest的方式执行。两者的区别在于后者会把当前目录加入sys.path，这在项目结构比较特殊、或者用例里需要import同目录模块的场景下特别有用。建议养成用python -m pytest的习惯，能避免不少因为路径问题导致的导入报错。
二、指定范围执行：从单个用例到整个目录
实际工作中很少一把梭跑全部用例，更多时候需要精准控制执行范围。pytest支持多种粒度的指定方式。想执行某个文件，直接在命令后面跟上文件路径即可，例如pytest test_login.py。想执行某个文件里的某个函数，用冒号连接，例如pytest test_login.py::test_valid_password，就能只跑这一个用例。
如果要执行某个测试类里的方法，写法是pytest test_user.py::TestRegister::test_email_format。这种文件::类::方法的三段式定位方式非常精确，调试失败用例的时候几乎天天用得上。除了指定路径，还可以用-k参数按关键字筛选，例如pytest -k login会执行所有名字里包含login的用例，支持and、or、not这样的逻辑组合，比如pytest -k "login and not slow"。
目录级别的执行也很简单，直接把目录路径传给pytest即可，例如pytest tests/api/。如果想在执行时显示更详细的输出，可以加-v参数，每个用例的结果会单独一行展示；加-s则能显示用例里print打印的内容，这两个参数在排查问题时非常实用。还可以用--collect-only先干跑一遍，只列出会被收集的用例而不真正执行，用来确认筛选条件是否写对。
三、常用命令行参数详解
下面这些参数是日常使用频率最高的，建议熟练掌握。
| 参数 | 作用说明 |
|---|---|
| pytest -v | 显示每个用例的详细执行结果 |
| pytest -s | 捕获输出关闭，显示print内容 |
| pytest -x | 遇到第一个失败就停止执行 |
| pytest --lf | 只执行上次失败的用例 |
| pytest -m 标签名 | 只执行带有指定标记的用例 |
| pytest -k 表达式 | 按名称关键字筛选用例 |
| pytest --collect-only | 只收集列出用例，不实际执行 |
| pytest -n 数值 | 配合xdist插件并行执行用例 |
其中-x和--lf（last failed的缩写）搭配使用效果很好：先用-x快速定位第一个失败点，修复后再用--lf验证，能明显提升调试效率。-m参数需要配合pytest.ini里注册过的标记使用，比如用@pytest.mark.slow标注慢速用例，然后用pytest -m "not slow"跳过它们。
如果觉得每次敲一长串参数麻烦，可以把默认参数写进pytest.ini配置文件的addopts里，例如addopts = -v -s，这样直接执行pytest时就自动带上这些选项。
四、在代码中执行pytest：pytest.main()用法
除了命令行，pytest还支持在Python代码内部启动执行，入口是pytest.main()。它接收一个参数列表，内容和命令行参数完全一致，例如：
pytest.main(["test_login.py", "-v", "--html=report.html"])
这种方式适合需要动态组装执行参数的场景，比如根据配置文件决定跑哪些用例，或者在持续集成脚本里统一封装执行入口。pytest.main()会返回一个退出码，0表示全部通过，1表示有失败用例，可以据此做后续逻辑判断。
需要提醒的是，pytest.main()在同一个进程里只能调用一次，重复调用可能出现状态残留问题。如果要在程序里多次触发测试，更稳妥的做法是使用subprocess调用命令行，或者在代码层面做好封装隔离。
五、常见误区与避坑提醒
误区一：文件和函数命名不规范，导致用例不被收集
这是新手最常见的问题。有人把测试文件命名为login_test_case.py，或者函数写成check_login，结果pytest一个用例都找不到，还以为框架坏了。记住规则很简单：文件test_开头或_test结尾，函数test_开头，类Test开头且不带__init__。遇到收集不到的情况，先用--collect-only看看到底识别了什么。
误区二：以为断言失败后代码还会继续执行
pytest使用原生assert关键字做断言，一旦断言失败，当前用例立即终止，后面的代码不会执行。有些人在一个用例里写多个步骤，期望某个断言失败后还能继续检查后面的内容，结果发现失败信息只到第一个断言就停了。如果确实需要多个检查点互不影响，应该拆成多个用例，或者使用pytest-check这类支持软断言的插件。
误区三：混淆-s和-v的含义
不少人以为-v是显示print输出，其实-v只是让结果展示更详细，显示print需要的是-s。-s的作用是禁用输出捕获。两者经常一起写成-vs，但含义要分清，否则排查输出问题时会走弯路。
误区四：随意执行用例导致conftest夹具失效
conftest.py的作用范围和它所在的目录层级有关。如果从错误的目录执行pytest，或者用例文件被移动到了conftest覆盖范围之外，fixture就会找不到，报fixture not found的错误。解决办法是保持项目结构清晰，尽量从项目根目录执行命令，必要时在pytest.ini中配置testpaths指定默认的测试目录。
误区五：忽略退出码
在CI流水线里，有人发现用例明明失败了但流水线显示通过。这通常是因为执行方式封装不当，没有正确传递pytest的退出码。无论是shell脚本还是pytest.main()，都要把退出码作为判断依据，确保失败时能够阻断流程。
六、总结
执行pytest用例的核心就三件事：懂收集规则、会指定范围、熟悉常用参数。命令行方式覆盖日常九成以上的场景，pytest.main()作为补充满足代码内调用的需求。遇到问题先想命名规则是否合规，再用--collect-only验证收集结果，配合-v和-s查看详细信息，绝大多数执行相关的问题都能自己定位出来。把这些要点烂熟于心，pytest用起来会顺畅很多。
Pytest测试用例执行pytest命令行参数pytest测试框架修改时间：2026-09-08 09:36:59