直接聊正事。写测试用例这件事，很多人一上来就钻断言怎么写、fixture怎么搭，结果在命令行这关卡了半个月。Pytest 的命令行参数，就是那个你天天用但又没认真琢磨过的部分。pytest不带任何参数也能跑，但当你的用例数量从十几条涨到几千条、当你在本地调试和 CI 流水线之间来回切换的时候，参数用得好不好，直接决定你是在高效干活还是在瞎等结果。
这篇内容我会把 pytest 命令行里真正高频、真正能救命的参数逐个拆开讲清楚，每个都会说它解决什么问题、背后的逻辑是什么、适合在什么场景用。最后会分享一些实际项目里的参数组合策略和踩坑记录，这比单纯记忆参数列表有价值得多。
1. 为什么值得专门研究 pytest 命令行参数
1.1 测试执行效率的瓶颈往往不在用例本身
我见过太多团队，测试代码写得挺规范，但执行测试的方式还停留在“无脑全量跑”。
本地改了一个工具函数，跑全量用例花了二十分钟，中间还有一堆失败的用例在刷屏，真正关心的那几条反而被淹没了。提交代码之后，CI 上又全量跑一遍，同样的二十分钟又花一次。时间就是这么浪费掉的。
pytest 命令行参数，恰恰就是用来解决“怎么跑、跑哪些、跑到什么程度停”这几件事的。它不是测试框架的边角料，而是测试执行策略的真正入口。
1.2 参数背后的三组核心问题
当你拿到一个陌生的 pytest 项目时，只需要回答下面三组问题，基本就能确定该用哪些参数：
- 选哪些用例跑：按文件路径、按节点 ID、按关键字表达式、按标记（marker）筛选，解决的是“本次改动影响范围”的问题。
- 怎么控制执行过程：遇到失败是否立即停止、最多容忍多少失败、是否显示打印输出、是否缓存上次失败状态，解决的是“反馈速度与信息粒度”的问题。
- 怎么输出结果：详细程度、报告格式、是否跳过某些插件或警告，解决的是“结果可读性与环境稳定性”的问题。
这三组问题想清楚了，命令行参数就不再是零散的记忆点，而是一套可以按需组合的策略工具。
2. 最常用的参数逐个拆解
2.1 基础控制：-v、-q、-s
这三个是大家最先接触的参数，但很多人对它们的理解停留在“显示更多/更少信息”这种模糊层面。
-v全称--verbose，作用是让每个测试用例的执行结果显示成独立的一行，包含完整的测试函数名、文件路径和最终状态。不写-v时，pytest 默认只会用点号表示通过的用例，一个大区域跑完你只看到一片绿点，根本不知道哪些用例跑过、哪些被跳过。实际调试过程中，特别是排查某个用例是否有被收集到时，-v几乎是必须的。
-q全称--quiet，与-v相反，它让输出更精简。在 CI 流水线日志里，我更推荐使用-q，因为流水线日志需要简洁，全量跑几千条用例时，-v的输出会刷出大量无意义内容，反而掩盖真正的错误信息。
-s全称--capture=no，作用是关闭 pytest 对 stdout 输出的捕获，让print()的内容直接显示在终端上。很多从其他语言转过来的开发者第一次用 pytest 时会困惑“为什么我 print 的东西看不到”，这是因为 pytest 默认会捕获每个测试的输出，只有测试失败时才会显示捕获的内容。调试阶段加上-s是常规操作，但要注意别把它写进默认配置里，否则用例里的打印语句会让执行日志变得极其臃肿。
2.2 筛选执行：-k、-m、指定文件路径
-k是关键字匹配参数，它用表达式匹配测试用例的名称。比如pytest -k "login or register"会执行所有测试名称中包含login或register的用例。这个参数厉害的地方在于它支持and、or、not逻辑组合，比如pytest -k "not slow"表示排除名称中包含slow的用例。实际工作中，-k最适合做“按功能模块跑用例”的快速筛选，前提是测试函数命名要规范，命名时就必须考虑后续要通过名称来筛选。
-m是标记筛选参数，配合 pytest 的@pytest.mark装饰器使用。最常见的是@pytest.mark.slow标记慢用例、@pytest.mark.smoke标记冒烟用例。比如pytest -m smoke只跑冒烟用例，pytest -m "not slow"排除慢用例。-m比-k更工程化，因为标记是显式声明的，不受命名规范影响。
直接指定文件路径是最朴素也最精准的筛选方式。pytest tests/test_login.py只跑这个文件，pytest tests/test_login.py::TestLogin::test_login_success精确到某个类里的某个方法。这个参数看似简单，但“精确到用例”这种写法在本地复现单个失败用例时特别好用，配合--tb=short可以快速定位问题。
2.3 失败控制：-x、--maxfail、--lf、--ff
-x全称--exitfirst，遇到第一个失败就立即停止。这个参数适合本地快速验证“我的改动有没有把现有功能弄坏”，跑一遍，如果有问题立刻看到，不用等所有用例跑完。
--maxfail是-x的进阶版，指定最大失败次数。pytest --maxfail=3表示遇到 3 个失败就停止。这个参数在 CI 场景特别有价值——全量用例上千条，如果前 50 条就挂了 20 条，继续跑完剩余 950 条毫无意义。设置一个合理的 maxfail 值，可以大幅缩短 CI 失败反馈时间。
--lf全称--last-failed，只运行上一次失败的用例。这个参数要搭配 pytest 的缓存机制使用，pytest 会默认在.pytest_cache目录里记录上次执行失败用例的列表。开发迭代时，本地修复了一个问题，先用--lf确认这个问题确实修好了，再跑全量。效率提升非常明显。
--ff全称--failed-first，先跑上次失败的用例，再跑剩下的。它的价值在于“优先级反馈”——先告诉你最可能出问题的地方，然后才跑完整回归。CI 上如果使用这个参数，可以在日志最前面看到回归测试中失败的用例，不用在几千行日志里翻找。
2.4 参数化与配置：-p、--tb、--durations、--ignore、--co
-p的全称是--pythonwarnings吗？不是，-p实际上是--plugins相关吗？这里特别容易混。-p的真实含义是“插件加载控制”。pytest -p no:cacheprovider表示临时禁用缓存插件，pytest -p no:randomly表示禁用随机执行插件。遇到第三方插件导致诡异问题的时候，这个参数是排查利器。注意，别把它和其他参数搞混。
--tb控制回溯信息的显示样式。默认是--tb=auto，最常用的几个取值是--tb=short（每行只显示一行代码）、--tb=line（只显示失败行）、--tb=no（不显示回溯）。本地调试推荐short，CI 日志更推荐line或no，因为auto模式下的长回溯信息对阅读日志的人来说是一种折磨。
--durations显示最慢的用例执行时间。pytest --durations=5会显示执行时间最长的 5 个用例。这个参数对性能定位价值极大，一个测试套件跑得很慢，用它快速找到瓶颈用例，是优化测试执行时间的起点。注意这里不支持负数，必须为正整数，且至少要输出一条信息。
--ignore指定忽略某些路径，pytest --ignore=tests/test_legacy.py在临时跳过某些文件时特别有用。--co全称是--collect-only，只收集用例但不去执行，常用于检查 pytest 是否成功识别到所有测试用例，以及确认某个用例节点 ID 是否正确。
3. 从参数组合到项目落地
3.1 高频参数组合套路
单个参数解决单个问题，组合起来才能应对真实场景。列几种我在实际项目中反复使用的组合：
本地快速验证改动：
pytest -x -s tests/ --lf含义是：只跑上次失败的用例，遇到第一个失败就停止，并且允许打印输出。改动代码后，先确认上次失败的用例都过了，再放开跑全量。
CI 全量回归：
pytest -q --tb=line --maxfail=20含义是：安静模式减少日志量，失败时只显示一行错误信息，最多容忍 20 个失败。这个组合可以避免 CI 日志被刷爆，同时保证失败信息足够定位问题。
临时排除慢用例：
pytest -m "not slow" --durations=5含义是：跳过标记为 slow 的用例，同时打印最慢的 5 个用例。适合在需要快速得到结果、但又不完全放弃性能监控的场合。
只跑某个目录且带覆盖率报告：
pytest tests/api/ --cov=app --cov-report=term-missing这里用到的是 pytest-cov 插件的参数，但展示了“路径 + 插件参数”的组合思路。
3.2 把参数固化到配置文件里
命令行参数每次都要敲一遍，既容易出错又不优雅。更工程化的做法是把它们固化到pytest.ini或pyproject.toml的[tool.pytest.ini_options]中。
最核心的配置项是addopts，它的值会附加到每次 pytest 执行的命令行参数前面。比如：
[pytest] addopts = -q --tb=short --maxfail=10 testpaths = tests markers = slow: 慢速测试，默认不执行 smoke: 冒烟测试这种情况下，即使你在命令行只输入pytest，实际执行的参数也会是pytest -q --tb=short --maxfail=10 tests。要注意的是，手写的命令行参数优先级更高，也就是“显式参数会覆盖配置文件里的默认参数”，所以如果某次临时想用--tb=long，直接敲在命令行里就能覆盖--tb=short。
markers配置的目的不仅是声明标记，更是避免 pytest 的 PytestUnknownMarkWarning 警告。未注册的标记会触发该警告，配置里声明之后这类警告会消失。
3.3 工程化之前的静态检查，让命令行参数不用背
参数很多，总会忘记。与其死记硬背，不如让工具辅助。在项目根目录，pytest 自带--markers参数可以列出所有注册的标记，--fixtures可以列出所有可用的 fixture。这两个参数虽然不是日常执行测试用的，但排查问题时特别管用。
另外，现代编辑器里对 pytest 参数有自动补全，但更可靠的做法是频繁使用pytest --help，它会列出当前环境下所有可用参数，包括第三方插件添加的参数。花十分钟把--help的输出从头到尾看一遍，记下哪些参数适合自己项目，比背任何教程都有效。
4. 实际项目中的参数选型思路
4.1 本地开发场景
本地开发时，反馈速度是第一优先级。一个工具函数改完，不应该等 5 分钟才知道自己有没有改坏东西。
我的做法是：本地默认用-x --lf，先跑上次失败的用例，如果修好了再跑相关的功能模块。怎么判断“相关”呢？用-k按模块名筛选，比如这次改的是支付相关逻辑，就pytest -k payment -x。全量回归留给 CI，本地不信赖全量。
这里有个容易踩的坑：--lf依赖.pytest_cache，如果你换了分支、拉取了新代码，缓存里记录的上次失败用例可能在新分支下不存在。此时 pytest 会提示找不到缓存中的用例，并默认重新跑全量。这种情况下不用慌，手动删掉.pytest_cache目录，或者加-p no:cacheprovider临时禁用缓存都行。
4.2 提交前的验证场景
准备提交代码时，验证粒度要比本地调试时更完整。我会这样做：
pytest -m "not slow" --tb=short --maxfail=5首先排除慢用例，保证验证速度；其次最多容忍 5 个失败，避免一个失败导致后面所有用例全部停跑。为什么是 5 不是 3 也不是 10？这属于经验值，没有标准答案。团队里如果基础质量好，可以放宽。如果经常大面积失败，说明测试基建有更大的问题，而不是调 maxfail 能解决的。
4.3 CI 流水线场景
CI 场景的核心约束是：日志要能被人快速读懂、失败用例定位信息要完整、总执行时间要可控。
我推荐的 CI 执行参数组合是：
pytest -q --tb=line --maxfail=20 --durations=3-q保证日志总量可控，--tb=line让失败信息以最紧凑的方式呈现，--maxfail=20避免大量失败用例全部执行完浪费时间，--durations=3附带展示最慢的 3 个用例，用于监控测试性能是否退化。
有一种常见错误是在 CI 里使用-x，遇到第一个失败就停。这在本地很合理，但在 CI 里，一次提交可能有多个独立的失败点，-x会让后续的失败信息完全不可见，就必须等下一次提交才能发现。CI 的首要目标是“尽可能多暴露问题”，而不是“快速停”。
4.4 不同测试层级的参数差异
单元测试、接口测试、端到端测试，它们的执行策略天然不同。我这里说的是执行策略，而不是写法。单元测试执行快、数量多，适合全量跑，失败容忍度可以高一些。接口测试执行相对慢、依赖环境，适合按模块分开跑和先跑 smoke 标记的用例。端到端测试通常很慢且不稳定，一般用-m e2e显式触发，绝不能放在每次提交的默认执行集合里。
如果你的项目里有不同层级的测试混合在一起，又不想把它们拆成多个测试目录，那么 marker 加-m筛选就是最优雅的解法。给每层级的测试打上不同标记，CI 里设计多个 job，每个 job 用不同的-m参数跑对应的测试集合，这样每个 job 的执行时间都可控，失败时也能快速定位是哪一层的问题。
5. 常见问题与排查技巧实录
5.1 为什么某些参数敲了没效果
第一反应先确认参数拼写是否正确。pytest 对未知参数会报unrecognized arguments，但这个报错只对完全未知的参数生效。如果你写的参数名拼错成了另一个合法参数，比如想敲--maxfail敲成了--maxfails，pytest 会直接报错，因为后者不合法。但如果拼错成一个确实存在的参数，比如--lf是合法的、--last-failed也是合法的，那问题就变成“你意图和行为的偏差”了。
另一种情况是参数被配置文件覆盖。比如你在pytest.ini配置了addopts = -q，命令行却敲了-v。这种情况下-v的优先级高于-q，结果会是详细模式。但如果配置里写了addopts = -k "not slow"，你在命令行加-k "login"，后者会覆盖前者，而不是合并。所以如果你发现某个参数敲了没生效，去检查一下pytest.ini里的addopts是否和你期望的方向冲突了。
5.2 中文字符导致的乱码问题
Windows 终端下执行 pytest，中文测试名称或中文 print 内容可能会出现乱码。这不是 pytest 本身的问题，而是编码环境的问题。最实用的解法是在pytest.ini里设置[pytest]下面的控制台输出编码，或者直接在系统层面把PYTHONIOENCODING=utf-8设置为环境变量。
另外测试文件本身必须是 UTF-8 编码，否则 pytest 在收集用例阶段就会报编码错误。这个在团队协作中特别常见，不同系统默认编码不同，最好约定所有测试文件统一 UTF-8 无 BOM 格式。
5.3 快速列出所有参数
临时需要确认当前环境下有哪些可用参数，直接pytest --help，输出会包含所有已安装插件注册的参数。这个技巧能帮你判断某个参数到底是 pytest 自带的还是某个插件提供的。比如--cov是 pytest-cov 插件提供的，--html是 pytest-html 插件提供的，--randomly是 pytest-randomly 插件提供的。
如果你想知道某个插件到底能不能正常工作，加-p no:插件名来禁用，跑一下看行为有没有变化。这是个很实用的排查手法。
5.4 参数和插件的优先级
pytest 的参数系统遵循“后传入的优先”原则吗？不完全准确。准确的规则是：命令行参数会覆盖配置文件中的addopts，而addopts会覆盖 pytest 内置的默认值。多个同类型的命令行参数同时存在时，具体行为取决于各个参数自身的实现逻辑。比如说多个-k不是覆盖关系，而是会报错，因为-k只能出现一次。多个-m同理。
这种细微差别很难靠死记，最靠谱的方法是在实际项目里试验。敲一个组合，跑一下，看结果是否符合预期。
5.5 临时性参数不要写进公共配置
最后一个非常重要但容易被忽略的原则：临时调试用的参数不要顺手写进pytest.ini或pyproject.toml。比如本地调试时为了省时间用了-x，顺手写进addopts，提交代码后 CI 就会继承这个-x，导致 CI 遇到第一个失败就停止，后面所有潜在问题全部不可见。这种事看起来低级，但在团队协作里真实发生的频率非常高。
我的建议是：公共配置里只放那些“无论谁在什么环境下执行都合理”的通用参数，比如-q、--tb=short、testpaths。调整执行策略的参数（如-x、--lf、--maxfail）应该在命令行手动传入，或者由 CI 配置的 job 各自设置。代码提交前，自己检查一下有没有把临时参数留在配置文件里。
围绕 pytest 命令行参数的经验就先分享到这里。如果让我总结一句最值得记住的话，那就是：参数本身不难，难的是理解每个参数在你的特定场景下带来的反馈速度和信息质量的变化。多花一点时间，把本地调试、提交验证、CI 流水线这三套参数组合各自理顺，你的测试执行体验会发生质的变化。我自己也是在一次线上事故之后，才下定决心把 CI 用的参数组合从-x改成--maxfail的。那一次的经验告诉我，测试执行策略的微小差异，最终会影响整个团队的交付节奏。
