全部速查表Python开发

pytest

pytest 8+

pytest CLI 命令快速参考：测试发现与筛选、fixtures、markers、并行执行、参数化以及覆盖率集成，并附带常用参数和实操示例。

34 条命令

帮助

pytest --version

打印 pytest 版本及它找到的库导入路径。

pytest --version

pytest --help

显示每个 pytest CLI 参数及一行说明。

-h

pytest --help | less

发现

pytest

按默认发现规则（`test_*.py` / `*_test.py`，名为 `test_*` 的函数，名为 `Test*` 的类）运行当前目录及子目录下所有测试。

-x；--maxfail=1；--co；--collect-only；-q；-v；-k <expr>；-m <marker>；--no-header

pytest

pytest <path>

只运行指定文件或目录下的测试。支持通配符。

<path>；tests/；tests/test_x.py；tests/test_x.py::test_y

pytest tests/unit

pytest tests/test_user.py::TestUser::test_create

通过完整节点路径（module / class / function）运行单个测试。

pytest tests/test_user.py::test_create_user

筛选

pytest -k <expr>

运行名字匹配子串 / Python 表达式的测试（`-k 'user and not slow'`）。

-k 'pattern'；-k 'ClassName and method'

pytest -k 'create or update'

pytest -m <marker>

只运行带指定 marker 的测试（marker 必须在 `pyproject.toml` 或 pytest.ini 中注册，否则会有告警）。

-m slow；-m 'not slow'

pytest -m 'not integration'

pytest --co

仅收集模式——列出 pytest 将要运行的测试而不实际执行。适合 CI 预览。

--collect-only；-q

pytest --co -q

停止 / 报告

pytest -x

首个失败处停止。用 `--maxfail=N` 自定义阈值。

--maxfail=1；--maxfail=3；--exitfirst；-x

pytest -x --maxfail=2

pytest --tb=short

选择 traceback 风格：`long`（默认）、`short`、`line`、`native`、`no`（不显示）。

long；short；line；native；no

pytest --tb=short

pytest -v

详细模式——显示每个测试函数的完整节点 ID。加 `-vv` 输出更详细。

-v；-vv；--no-header；--no-summary；-q；-rA

pytest -v --no-header

pytest -s

禁用 stdout / stderr 捕获——让 print() 直接流到终端（少见；建议在测试内用 `capfd` fixture）。

--capture=no；-s；--capture=fd

pytest -s tests/test_print.py

pytest --durations=10

在最终报告中显示最慢的 10 个测试（用 `--durations=0` 显示全部）。

--durations=10；--durations=min=0.5

pytest --durations=10

pytest -rA

打印额外的测试结果摘要：`E` 错误、`F` 失败、`s` 跳过、`x` xfail、`A` 全部。

-rA；-rfE；-rs；-rxX

pytest -rA

重新运行

pytest --lf

只重新运行上次运行中失败的测试。搭配 `--ff` 让失败测试排在最前。

--lf；--last-failed；--ff；--failed-first；--cache-clear

pytest --lf

pytest --sw

逐步模式——在首个失败处停下，下次调用从该处继续。

--stepwise；--stepwise-skip；--stepwise-skip-some

pytest --sw

参数化 / fixtures

pytest --fixtures

列出当前测试范围内所有可见的 fixture（从仓库根运行时覆盖全项目）。

--fixtures；--fixtures-per-test

pytest --fixtures -q

pytest --markers

列出所有已定义的 marker（在 pytest.ini / pyproject.toml 中注册）。

--markers

pytest --markers

并行

pytest -n <N>

将测试并行分布到 `<N>` 个 worker 进程中（pytest-xdist 插件）。用 `auto` 可按 CPU 核数自动设置。

-n auto；-n 4；--dist loadscope；--dist loadfile；-p no:cacheprovider

pytest -n auto

pytest --dist loadgroup

按 `@pytest.mark.group_*` marker 分组（xdist），让单个组在单个 worker 中运行——适合有资源冲突的测试。

--dist loadgroup；--dist loadscope

pytest -n 4 --dist loadgroup

输出

pytest --junitxml=<file>

输出 JUnit 风格的 XML 报告（GitHub Actions、GitLab、Jenkins、CircleCI 都会消费）。

--junitxml=report.xml；--junit-xml=report.xml

pytest --junitxml=pytest-report.xml

pytest --html=<file>

生成自包含的 HTML 测试报告（pytest-html 插件）。

--html=report.html；--self-contained-html

pytest --html=report.html --self-contained-html

pytest --cov=<pkg>

在覆盖率统计下运行测试（pytest-cov 插件）。搭配 `--cov-report=` 选择输出格式。

--cov=src；--cov-report=term；--cov-report=xml；--cov-report=html；--cov-fail-under=80

pytest --cov=src --cov-report=term-missing --cov-fail-under=80

监视 / 自动重跑

pytest --looponfail

每次保存时重跑失败的测试直到通过（pytest 7+ 中已弃用，请用 pytest-watch / pytest-xdist --loop-onfail）。

--looponfail

pytest --looponfail

ptw

在监视模式下运行 pytest——每次文件变更后重跑测试套件（pytest-watch，需通过 pip 安装）。

--clear；--runner 'pytest -x'；--now

ptw -- -x

配置

pytest -c <file>

覆盖 pytest 配置文件（默认 `pytest.ini` / `pyproject.toml [tool.pytest.ini_options]` / `tox.ini` / `setup.cfg`）。

-c pytest.ini；-c tests/pytest-cfg.ini

pytest -c tests/pytest-cfg.ini

pytest -p <plugin>

在 CLI 加载一个插件（例如 `pytest -p no:cacheprovider` 会禁用缓存）。

-p django；-p asyncio；-p no:warnings；-p no:cacheprovider

pytest -p no:cacheprovider

调试

pytest --trace

在第一个测试开始处进入 `pdb.set_trace()`（非 CLI 崩溃时请用 `--trace-cli`）。

--trace；--trace-cli

pytest --trace tests/test_user.py::test_login

pytest --pdb

在每次测试失败或错误时自动启动 pdb。

--pdb；--pdbcls=IPython.terminal.debugger.TerminalPdb

pytest --pdb -x

pytest --setup-show

在运行过程中展示 fixture 的 setup / teardown 跟踪（用 `--setup-plan` 仅展示而不执行）。

--setup-show；--setup-plan

pytest --setup-show tests/test_db.py

警告

pytest -W <filter>

把 Python 警告前置处理为 pytest 抛出。过滤器遵循 `-W` action module 规范。

-W error；-W ignore::DeprecationWarning；-W default

pytest -W error::DeprecationWarning

pytest --strict-markers

把未注册的 marker 当作错误——能捕获 `@pytest.mark.slow` 等拼写错误。

--strict-markers；--strict-config；--strict

pytest --strict-markers

异步

pytest -p asyncio

-p asyncio；--asyncio-mode=auto

pytest --asyncio-mode=auto

杂项

pytest --rootdir=<dir>

覆盖 pytest 用于配置发现的项目根目录。

--rootdir=.；--import-mode=importlib

pytest --rootdir=. tests/

商标与使用声明

本批命令行工具速查手册为开源社区参考资料。文中涉及的各工具的名称、标识、商标（如 Git™、Docker™、Kubernetes®、kubectl、PostgreSQL®、MySQL®、Redis™、MongoDB®、Linux™、PowerShell™、Vim™ 等）均归对应权利人所有，此处仅为识别与参考之目的使用。

本速查手册的全部内容均为独立编写的简化自包含参考，**与任何官方文档不存在隶属、被认可或引用关系**。命令列表、参数说明、示例均为作者原创简化表达；如需权威信息，请参阅各工具的官方文档。

命令语法与参数可能在不同工具版本中有所差异。所示版本标签对应稳定发布版本；其他版本行为可能有所不同。本速查手册**不代表**商标权利人的任何偏好或推荐。

如商标或版权方认为本站部分内容存在权益侵害，请发送邮件至[email protected]，我们在收到有效权属证明后，会在合理期限内修改或移除相关内容。

本网站不对因使用本站信息而产生的任何直接或间接损失承担法律责任。

关于 pytest

pytest 是事实上的 Python 测试框架标准。由 Holger Krekel 创建，于 2008 年发布（最初作为更早 `py` 库的继任者）。pytest 简化了 Python 标准库 `unittest` 的样板——测试只是普通的 `def test_*():` 函数，无需任何类样板——并自带强大的 fixture 系统、参数化、markers，以及丰富的插件生态（pytest-cov、pytest-xdist、pytest-mock、pytest-django、pytest-asyncio、hypothesis 等）。当前稳定版本线是 pytest 8+（8.3+）。pytest 通过默认命名约定（`test_*.py` / `*_test.py`）自动发现测试，按确定性顺序运行，并在断言失败时输出丰富的 diff。pytest 也能运行 unittest / nose 风格的测试。常用的邻近 CLI 是 `coverage`（运行 `coverage run -m pytest` 然后 `coverage report`）。pytest 不会上传你的代码；所有测试执行都在本地完成。

速查页版本 1.0.0