pytest失败用例自动重跑配置方法

本文详解了如何通过 pytest-rerunfailures 插件实现失败用例的智能自动重跑：从一行 pip 命令安装到命令行参数（--reruns、--reruns-delay）和装饰器（@pytest.mark.rerun）的灵活配置，覆盖全局与用例级粒度控制；强调重跑不等于掩盖问题，必须配合 fixture 隔离（如 tmp_path、事务回滚、mock 清理）杜绝状态污染；并给出 CI 实战建议——启用 --reruns-verbose 和 --junitxml 获取可追溯的重试详情，合理限制次数与失败阈值，让偶发性失败不再拖垮流水线，真正提升测试稳定性和排查效率。

pytest-rerunfailures 插件安装与基础启用

直接用 pip install pytest-rerunfailures 安装即可，无需额外依赖。安装后不需修改代码或导入模块，只要命令行加参数就能生效。

最简重跑方式是运行时加 --reruns 3，表示每个失败用例最多重试 3 次（含首次执行）。注意：它只对 assert 失败、未捕获异常等测试逻辑失败生效，对 pytest 自身错误（如 import error、fixture setup 失败）不重跑。

• --reruns 是必填数值参数，不能只写 --reruns
• 重跑间隔默认为 0 秒，高频重跑可能触发环境状态残留问题，建议搭配 --reruns-delay 1 加 1 秒延迟
• 插件不会改变测试结果统计逻辑：只要任意一次成功，最终标记为 PASSED；全失败才标 FAILED

按用例粒度控制重跑：@pytest.mark.rerun

全局重跑太粗暴，实际中往往只想对已知不稳定用例（比如依赖网络/第三方接口的测试）启用重跑。这时用装饰器更精准：

@pytest.mark.rerun(failures=2)
def test_api_timeout():
    response = requests.get("https://httpbin.org/delay/3", timeout=2)
    assert response.status_code == 200

该装饰器优先级高于命令行参数，且支持独立配置次数和延迟：

• failures=2 表示最多再跑 2 次（共执行 3 轮）
• delay=1.5 可设小数秒延迟，单位是秒
• 若同时用了命令行 --reruns 5 和装饰器 @pytest.mark.rerun(failures=1)，以装饰器为准

重跑时如何避免状态污染？关键在 fixture 隔离

重跑本质是多次执行同一个测试函数，如果它依赖共享 state（如全局变量、文件、数据库记录），第二次跑大概率因脏数据失败。这不是插件问题，而是测试设计缺陷。

必须确保每次执行都从干净状态开始：

• 数据库操作类测试，务必在 teardown 或 yield fixture 中清理数据，或改用事务回滚
• 文件读写类测试，用 tmp_path fixture 创建临时目录，别硬编码路径
• 网络 mock 类测试，用 responses 或 pytest-mock，避免真实请求残留影响下一轮
• 不要在测试函数内修改模块级变量或类属性，重跑会复用同一模块实例

CI 环境中重跑的日志与报告怎么查？

默认情况下，重跑过程不输出中间失败详情，只显示最终结果。想看每次重试的 traceback，要加 -v --tb=short；想保留全部日志供排查，推荐加 --reruns-verbose 参数（pytest-rerunfailures ≥ 10.2）。

生成 HTML 报告时，pytest-html 会把重跑记录合并进单个用例条目，但不会标注哪次成功；若需区分轮次，得配合 --junitxml=report.xml，XML 中每个 的 name 属性末尾会追加 [rerun-x]（x 从 1 开始）。

一个容易忽略的点：Jenkins 或 GitHub Actions 默认截断长日志，而重跑可能产生大量重复输出。建议在 CI 脚本里限制重跑次数（比如 --reruns 2），并用 --maxfail=3 防止因偶发失败导致整个 job 卡住。

好了，本文到此结束，带大家了解了《pytest失败用例自动重跑配置方法》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！