pytest-timeout需显式启用，默认不生效；可通过--timeout=30或配置文件设全局超时（单位秒，0禁用，负数报错）；支持@pytest.mark.timeout装饰器为单个测试设独立超时，推荐method="thread"跨平台兼容，signal仅限linux/macos；超时触发后测试立即失败并抛timeouterror，不执行finally和上下文清理；fixture需单独加timeout标记才受监控，超时线程残留可能影响后续测试。
pytest-timeout 的安装与基础启用方式
直接用 pip install pytest-timeout 就能装上，不用额外配置就能生效——但默认不生效，必须显式启用。它不会自动给所有测试加超时，得通过命令行参数或配置文件告诉 pytest “这次运行要检查超时”。
最常用的是命令行加 --timeout=30，表示单个测试函数超过 30 秒就强制终止；也可以写进 pyproject.toml 或 pytest.ini：
[tool.pytest.ini_options] timeout = 30
注意：这个值单位是秒，不是毫秒；设为 0 表示禁用超时（不是“无限”），设为负数会报错。
如何为特定测试函数设置独立超时时间
全局超时不够灵活，比如某个集成测试本来就要跑 2 分钟，而单元测试通常几秒内该结束。这时用 @pytest.mark.timeout 装饰器更精准。
常见写法有三种：
-
@pytest.mark.timeout(10)：纯数字，单位秒，超时后抛出pytest_timeout.TimeoutError -
@pytest.mark.timeout(method="thread", seconds=5)：显式指定杀线程方式（推荐） -
@pytest.mark.timeout(3, method="signal")：Linux/macOS 下可用 signal 方式，更轻量，但 Windows 不支持
⚠️ 容易踩的坑：method="thread" 是 Windows 和跨平台首选，但无法中断 C 扩展里的阻塞调用（比如某些数据库驱动的 connect()）；method="signal" 在 Python 中对纯 Python 代码更可靠，但信号在 Windows 上不可用，会导致跳过超时检查。
超时触发后测试状态和日志怎么看
超时发生时，pytest 不会继续执行该测试，而是立即标记为 failed，并在错误详情里明确打出 Timeout > ... seconds。你能在终端看到类似这样的输出：
test_long_running.py::test_slow_function FAILED [100%] ... E pytest_timeout.TimeoutError: Test took longer than 5.0 seconds.
关键点：
- 失败测试仍计入总用例数，但不会影响其他测试运行（默认行为）
- 如果用了
--tb=short或更简略的 traceback 模式，可能看不到完整堆栈，建议至少用--tb=short保证能看到超时提示 - 超时是硬中断，不会触发
finally或上下文管理器的__exit__，资源清理可能遗漏——这点常被忽略
与 fixture、yield_fixture 配合时的注意事项
如果测试用了带 yield 的 fixture（比如启动服务再 teardown），超时发生在测试主体里，fixture 的 cleanup 还是会执行；但如果超时发生在 fixture 本身（比如 setup 阶段卡住），pytest-timeout 默认只监控测试函数，不监控 fixture 初始化——除非你把 timeout 标记加到 fixture 函数上。
例如：
@pytest.fixture
@pytest.mark.timeout(15)
def db_connection():
return slow_db_connect() # 这里超时也会被拦截
但要注意：fixture 上的 timeout 是独立判断的，和测试函数的 timeout 无关；且多个 fixture 串联时，每个都需单独标注，pytest 不会递归检查依赖链。
真正容易被忽略的是：超时中断后，Python 的线程可能残留（尤其 method="thread"），导致后续测试环境不稳定——建议在 CI 环境中配合 --maxfail=1 或单独跑可疑测试，避免干扰其他用例。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
