pytest 测试失败处理：pdb 调试与故障诊断-未完纪

版本与验证范围：本文依据 2026-10-02 核验留存的官方 stable 文档快照；缓存页面没有明确标注精确的 pytest 发布版本。文中的 Python 3.7、pytest 5.0 和 6.2 是对应功能的引入版本，不等于本译文验证过的运行环境；相关历史插件与选项变更按原文保留。本站未运行或实测文中的命令与示例，代码和示例输出均逐字保留自原文，不代表本站运行结果。

在第一次或第 N 次失败后停止

要在第一次失败后，或累计出现 N 次失败后，停止测试进程：

pytest -x           # stop after first failure
pytest --maxfail=2  # stop after two failures

在 pytest 中使用 Python 调试器 pdb

失败时进入 pdb

Python 自带一个名为 pdb 的 Python 调试器。pytest 允许通过命令行选项进入 pdb 提示符：

pytest --pdb

这样会在每次失败或发生 KeyboardInterrupt 时调用 Python 调试器。通常，可能只希望在第一个失败的测试中这样做，以了解某个具体的失败情况：

pytest -x --pdb   # drop to PDB on first failure, then end test session
pytest --pdb --maxfail=3  # drop to PDB for first three failures

请注意，每次失败时，异常信息都会存储在 sys.last_value、sys.last_type 和 sys.last_traceback 中。在交互式使用时，可以据此使用任意调试工具进行事后调试（postmortem debugging）。也可以手动访问异常信息，例如：

>>> import sys
>>> sys.last_traceback.tb_lineno
42
>>> sys.last_value
AssertionError('assert result == "ok"',)

测试开始时进入 pdb

pytest 允许通过命令行选项，在每个测试刚开始时立即进入 pdb 提示符：

pytest --trace

这样会在每个测试开始时调用 Python 调试器。

设置断点

要在代码中设置断点，可以使用 Python 原生的 import pdb;pdb.set_trace() 调用；pytest 会自动关闭对该测试的输出捕获：

其他测试的输出捕获不会受到影响。
此前已经捕获的测试输出，仍会按已捕获输出进行处理。
通过 continue 命令结束调试会话后，输出捕获会恢复。

使用内置的 breakpoint 函数

Python 3.7 引入了内置的 breakpoint() 函数。pytest 支持使用 breakpoint()，其行为如下：

调用 breakpoint() 且 PYTHONBREAKPOINT 保持默认值时，pytest 会使用其内部定制的 PDB 跟踪界面，而不是系统默认的 Pdb。
测试完成后，系统会恢复默认使用系统的 Pdb 跟踪界面。
向 pytest 传入 --pdb 后，无论是调用 breakpoint()，还是测试失败或出现未处理的异常，都会使用内部定制的 Pdb 跟踪界面。
可以使用 --pdbcls 指定自定义调试器类。

故障处理器

在 5.0 版本中新增。

标准库模块 faulthandler 可用于在发生段错误（segfault）或超时后，转储 Python 回溯信息。

运行 pytest 时会自动启用这个模块，除非在命令行中传入 -p no:faulthandler。

此外，可以使用配置选项 faulthandler_timeout=X：如果某个测试耗时超过 X 秒仍未完成，就转储所有线程的回溯信息。

说明

这项功能是从外部插件 pytest-faulthandler 集成而来的，有两处小的差异：

要禁用它，应使用 -p no:faulthandler，而不是 --no-faulthandler：前者适用于任意插件，因此可以少提供一个专用选项。
命令行选项 --faulthandler-timeout 已变为配置选项 faulthandler_timeout。仍然可以通过命令行中的 -o faulthandler_timeout=X 对其进行配置。