pytest-timeout插件不生效的常见原因是未被pytest加载，需确认安装的是官方版本并检查pytest --version输出是否含timeout字样；全局超时终止整个进程，用例级超时仅标记失败并继续执行；Unix用信号可中断阻塞，Windows需强制thread模式以提升一致性。
pytest-timeout插件不生效的常见原因
直接安装后加 --timeout=5 却没反应，大概率是 pytest 没加载到插件。pytest 默认只加载已安装且满足入口点（entry point）规范的插件，pytest-timeout 需要确保安装的是 PyPI 上的官方版本，而非同名但无入口点的“假包”。
- 用
pip install pytest-timeout安装（不是pip install timeout或其他变体） - 运行
pytest --version，输出中应包含timeout-2.x.x字样 - 若无显示，说明插件未被识别，可临时加
-p pytest_timeout强制加载
全局超时与用例级超时的区别和设置方式
pytest-timeout 支持两种粒度：整个测试会话级（全局）和单个测试函数级。二者行为不同，容易混淆。
- 全局超时（
--timeout=10）：从 pytest 启动开始计时，超时后直接终止整个进程，不等当前用例结束 - 用例级超时（
@pytest.mark.timeout(3)）：仅对单个测试函数生效，超时后抛出pytest_timeout.TimeoutExpired，pytest 捕获后标记为 failed 并继续执行下一个用例 - 两者可共存，但用例级优先级更高；若全局设 5s、某个用例标了
@pytest.mark.timeout(8)，该用例仍按 8s 判定
示例：
import pytest <p>def test_slow_network_call(): import time time.sleep(6) # 超过全局 --timeout=5，整个 pytest 进程会被 kill</p><p>@pytest.mark.timeout(2) def test_fast_but_flaky(): import time time.sleep(3) # 超过 2s，报 TimeoutExpired，test 标为 failed，后续用例照常跑
超时信号机制在 Linux/macOS 和 Windows 上的行为差异
pytest-timeout 在 Unix 系统（Linux/macOS）默认用 SIGALRM 发送中断信号，在 Windows 上只能用线程轮询 + threading.Timer，因此存在关键差异：
立即学习“Python免费学习笔记（深入）”；
- Unix 下：超时后能立即中断阻塞调用（如
time.sleep()、socket.recv()），响应快 - Windows 下：无法中断系统调用，只能等当前调用自然返回后再检查超时，实际停顿可能远超设定值
- 若需跨平台一致行为，建议统一用
--timeout-method=thread（强制走线程方案），但要注意它无法中断 C 扩展里的长期阻塞操作
启动命令示例（强制线程模式）：
pytest --timeout=5 --timeout-method=thread
如何捕获超时异常并做清理？
用例被 pytest-timeout 中断时，不会自动触发 finally 或上下文管理器的 __exit__，资源泄漏风险高。不能依赖常规清理逻辑。
- 避免在测试中直接开文件、建 socket、启子进程——改用 pytest fixture 的
yield或addfinalizer，它们在超时后仍会被调用 - 不要在测试函数里写
try/finally做清理，超时发生在try块内时，finally很可能不执行 - 若必须手动清理，可用
pytest-timeout提供的钩子pytest_runtest_makereport检查是否因超时失败，再补救（但时机晚、不可靠）
更稳妥的做法是把耗时操作封装进 fixture：
@pytest.fixture
def db_connection():
conn = create_db_conn()
yield conn
conn.close() # 超时后仍会执行
超时本身不是万能开关，它只是杀掉测试线程或进程的“最后手段”。真正健壮的测试，得靠合理拆分、mock 外部依赖、控制阻塞深度——否则你永远在调超时阈值，而不是解决根本问题。
