pytest-rerunfailures：自动化测试中Flaky Test的智能重试解决方案
1. 项目概述：为什么我们需要一个失败重试工具？
在自动化测试的世界里，尤其是接口、UI或者涉及外部依赖（如网络、数据库、第三方服务）的测试中，最让人头疼的往往不是逻辑错误，而是那些“偶发性”的失败。你精心编写的测试用例，在本地运行得稳稳当当，一到CI/CD流水线上，就可能因为网络瞬间抖动、服务响应延迟、资源竞争或者测试环境的不稳定，而随机地失败那么一两次。这种“Flaky Test”（不稳定测试）就像测试套件里的“牛皮癣”，它消耗着团队的信心，污染着测试报告，更致命的是，它可能导致我们忽略掉真正需要修复的缺陷，或者浪费大量时间去排查一个本不存在的“Bug”。
我经历过太多这样的场景：半夜被CI的失败警报叫醒，爬起来一看，只是一个不稳定的UI元素加载超时。手动点一下“重新运行”，测试又通过了。这种重复劳动毫无价值，纯粹是精力的浪费。pytest-rerunfailures这个插件，就是为了解决这个痛点而生的。它不是一个复杂的测试框架，而是一个极其轻量、专注的“稳定器”。它的核心思想很简单：给那些可能“失足”的测试用例一次（或多次）重新站起来的机会。通过自动重试失败的用例，它能有效过滤掉因环境瞬态问题导致的失败，让测试结果更真实地反映代码质量，从而显著提升测试套件的稳定性和可信度。
对于测试开发工程师、自动化测试工程师以及任何使用pytest框架的开发者来说，掌握这个工具是提升日常工作效率、构建健壮CI流程的必备技能。它尤其适合用于集成测试、端到端测试等“重”场景，在这些场景中，测试的稳定性往往比执行速度更值得关注。
2. 核心原理与设计思路拆解
2.1 重试机制的底层逻辑
pytest-rerunfailures的工作原理并不神秘，但理解其设计思路有助于我们更好地使用它。本质上，它是一个pytest的钩子（hook）函数插件。pytest框架本身提供了丰富的钩子点，允许插件在测试生命周期的特定阶段介入。
这个插件主要利用了pytest_runtest_protocol这个核心钩子。当一个测试项目（item，即一个测试函数或方法）开始执行时，插件会“监听”其执行结果。如果测试失败（状态为failed），并且该测试满足我们预设的重试条件（例如，尚未达到最大重试次数），插件就会“捕获”这个失败，然后调用pytest的内部机制，清理当前测试的上下文（teardown），再重新为其执行setup和测试函数体本身。
这里有一个关键细节：重试是“全新”的执行。这意味着每次重试，测试用例都会像第一次运行一样，重新经历setup、执行、teardown的完整周期。这对于确保每次重试的环境独立性至关重要。例如，如果一个测试在setup中初始化了数据库连接，失败后，这个连接会被正常关闭（teardown），重试时会再次建立新的连接。
2.2 与“Flaky Test”治理策略的关系
引入重试工具，是治理“Flaky Test”策略中的一环，但绝非唯一或最佳手段。一个成熟的策略应该是分层的：
- 第一层：编写稳定的测试代码。这是根本。避免硬编码等待（
time.sleep），使用显式等待（如WebDriverWait）；对外部依赖进行合理的Mock或Stub；确保测试数据的独立性和可重复性。 - 第二层：使用重试工具作为安全网。对于确实难以消除的、由外部环境引起的偶发失败（如第三方API的99.9%可用性承诺下的那0.1%），使用重试机制来提升通过率。这层是pytest-rerunfailures的主要战场。
- 第三层：监控与隔离。在CI中标记出频繁重试才通过的测试，将它们归类为“不稳定测试集”，可以考虑单独运行或降低其失败对流水线阻断的严重性。
pytest-rerunfailures的定位非常清晰：它是一个补救措施，而非根治方案。滥用重试（例如，设置过高的重试次数）会掩盖真正的代码缺陷，并大幅延长测试执行时间。正确的态度是：先用它来稳住测试套件，同时利用它提供的数据（哪些用例经常被重试）来反向推动第一层——优化那些不稳定的测试用例本身。
3. 核心细节解析与实操要点
3.1 安装与基本配置
安装非常简单，通过pip即可完成：
pip install pytest-rerunfailures安装后，pytest会自动识别这个插件，无需额外导入。它的所有功能都通过命令行参数或pytest.mark装饰器来驱动。
3.2 核心参数详解
插件提供了几个核心参数来控制重试行为，理解每个参数的含义和适用场景是关键。
--reruns n：这是最重要的参数，n代表最大重试次数。如果设置为--reruns 2，则一个用例最多会运行3次（1次原始执行 + 2次重试）。--reruns-delay m：在每次重试之间等待的秒数。这对于解决“瞬时过载”或“状态未就绪”的问题非常有用。例如，一个接口因瞬间流量高峰失败，等待2秒后再试可能就成功了。注意：延迟是加在每次失败之后的，成功的执行后不会有延迟。--rerun-except：这是一个高级参数，允许你指定一个异常类型，只有抛出这个异常时才重试。这在处理特定类型的失败时非常有用。例如，你只想重试因ConnectionError网络问题导致的失败，而断言失败（AssertionError）则立即报错。
配置示例与场景选择：
# 场景1：快速重试，适用于网络抖动等瞬时问题 pytest --reruns 2 # 场景2：重试并等待，适用于服务重启或缓存刷新等需要短暂时间恢复的场景 pytest --reruns 3 --reruns-delay 1 # 场景3：选择性重试，只重试特定的网络异常（需要自定义异常处理逻辑配合，此参数使用相对复杂） # 假设我们有一个自定义的 `TransientError` # pytest --reruns 2 --rerun-except=TransientError注意：
--reruns-delay的增加会线性增加测试套件的总执行时间。在CI/CD流水线中，需要权衡稳定性和反馈速度。通常，对于UI测试，1-3秒的延迟是常见的；对于接口测试，可能只需要0.5-1秒。
3.3 标记（Decorator）的精细控制
除了全局命令行参数，pytest-rerunfailures支持使用@pytest.mark.flaky装饰器对单个测试用例进行精细控制。这提供了极大的灵活性。
import pytest @pytest.mark.flaky(reruns=5, reruns_delay=2) def test_api_with_high_flakiness(): # 这个接口非常不稳定，给它5次机会，每次失败后等2秒 response = call_unstable_api() assert response.status_code == 200 def test_stable_logic(): # 这个测试很稳定，不需要重试 assert 1 + 1 == 2装饰器与命令行参数的优先级：装饰器的设置会覆盖全局命令行参数。这意味着，你可以通过命令行设置一个保守的全局重试策略（如--reruns 1），然后为那些已知的不稳定用例单独标记更高的重试次数。这是最佳实践之一。
3.4 重试结果报告解读
启用重试后，pytest的终端输出和报告会发生变化，正确解读这些信息很重要。
终端输出：重试的用例会在输出中显示“RERUN”状态。最终结果会显示是“PASSED”还是“FAILED”。
test_example.py::test_flaky_function RERUN test_example.py::test_flaky_function RERUN test_example.py::test_flaky_function PASSED最终，在测试摘要中，你会看到类似
1 passed, 1 rerun的统计。-v详细模式：使用-v参数可以更清楚地看到每次重试的独立执行记录。与Allure等报告工具的集成：这是一个需要特别注意的点。像Allure这样的高级报告工具，默认可能会将重试的每次尝试都记录为一个独立的测试用例，导致报告膨胀。pytest-rerunfailures通常能与它们较好地协作，最终只报告最后一次尝试的结果。但为了确保报告整洁，你可能需要在Allure的配置中指定只附加最后一次重试的日志和截图。这通常需要在
conftest.py中编写自定义的钩子来处理。
4. 实操过程与核心环节实现
4.1 基础使用：快速为项目添加重试能力
假设我们有一个现有的pytest测试项目，现在想为所有测试添加一层基础的重试保护。
步骤1：修改pytest运行命令最直接的方式是在你常用的运行命令中加入参数。如果你使用pytest.ini配置文件（推荐用于团队协作），可以这样配置：
# pytest.ini [pytest] addopts = --reruns 2 --reruns-delay 1 -v这样，每次运行pytest命令时，都会自动应用--reruns 2 --reruns-delay 1的参数，为所有用例提供最多2次重试，每次间隔1秒。
步骤2：运行并观察配置好后，直接运行测试。你会立即看到效果：那些偶发性失败的用例，大部分会在重试后通过。在CI脚本中，也只需使用简单的pytest命令即可。
4.2 进阶配置：混合使用全局与标记策略
在实际项目中，更推荐使用混合策略。
conftest.py中的全局配置：
# conftest.py def pytest_addoption(parser): parser.addoption( "--run-flaky", action="store_true", default=False, help="Run tests marked as flaky with higher retry counts" ) def pytest_configure(config): config.addinivalue_line( "markers", "flaky: mark test as flaky (highly unstable) and retry more times." )这里我们添加了一个自定义命令行选项--run-flaky和一个标记flaky。
测试文件中的应用：
# test_service.py import pytest import random @pytest.mark.flaky(reruns=5, reruns_delay=2) def test_external_service_integration(): # 模拟一个不稳定的外部服务调用，有30%的失败率 if random.random() < 0.3: raise ConnectionError("Service temporarily unavailable") assert True def test_internal_logic(): # 内部逻辑测试，很稳定 assert some_calculation() == expected_value运行策略：
- 日常快速运行：
pytest test_service.py（使用pytest.ini中配置的保守重试策略，如--reruns 1） - 完整稳定性验证：
pytest test_service.py --run-flaky（在CI的夜间构建或发布前构建中，可以运行所有测试，包括高重试次数的flaky测试）
这种策略既保证了日常开发的反馈速度，又确保了在关键节点上对稳定性的充分验证。
4.3 与Fixture和Setup/Teardown的交互
理解重试与pytest fixture生命周期的交互至关重要。如前所述，每次重试都是一个完整的setup->test->teardown循环。
@pytest.fixture(scope=“function”)：这是默认的scope。每次重试都会重新执行这个fixture。这通常是安全的，确保了测试的独立性。@pytest.fixture(scope=“module”)或@pytest.fixture(scope=“session”)：需要特别小心！如果一个module或session级别的fixture在第一次执行测试时失败了，并且这个失败导致了fixture本身没有正确建立，那么重试可能无法进行，因为pytest会认为fixture已经失败。此外，如果fixture成功建立，但测试失败，重试时不会重新执行这个fixture。这意味着重试的测试用例共享了fixture的状态。你必须确保你的测试不会污染这个共享状态，或者fixture本身是幂等的（多次使用效果相同）。
实操建议：对于与重试测试相关的fixture，尽量使用scope="function"。如果必须使用更大范围的fixture，要确保测试用例是隔离的，或者使用如request.addfinalizer来确保每个测试都能清理自己的数据。
5. 常见问题与排查技巧实录
在实际使用pytest-rerunfailures的过程中，我踩过不少坑，也总结了一些排查技巧。
5.1 问题速查表
| 问题现象 | 可能原因 | 排查与解决方案 |
|---|---|---|
| 重试根本不生效 | 1. 插件未安装成功。 2. 命令行参数拼写错误或位置不对。 3. 在 pytest.ini中配置，但运行命令覆盖了addopts。 | 1. 运行pytest --version，查看已安装插件列表是否包含rerunfailures。2. 确保参数是 --reruns和--reruns-delay。3. 检查运行命令，如 pytest -x（遇到第一个失败就停止）会覆盖重试行为。 |
| 重试后报告仍然显示失败 | 1. 重试次数用尽，用例确实失败了。 2. 失败原因不是“瞬时”的，而是代码逻辑或环境真有缺陷。 3. 用例抛出了 pytest.exit或KeyboardInterrupt等，这些不会被重试。 | 1. 查看最终错误信息，定位根本原因。 2. 检查是否是断言失败（ AssertionError），这通常意味着逻辑错误，应修复代码而非增加重试。3. 确认异常类型。 |
| CI中测试时间大幅增加 | 重试次数(--reruns)或延迟(--reruns-delay)设置过高。 | 优化策略： 1.降低全局重试：全局设为 --reruns 1。2.精准标记：只对少数不稳定用例使用 @pytest.mark.flaky提高重试。3.分析日志：找出重试最多的用例，优先修复它们。 |
| Allure报告中有大量重复的测试条目 | Allure插件将每次重试都记录为独立测试用例。 | 配置Allure只记录最后一次重试。可以在conftest.py中通过pytest_runtest_makereport钩子进行过滤，或查阅Allure-pytest文档关于clean配置的说明。 |
使用了-x/--maxfail参数导致重试中断 | -x参数意为“遇到第一个失败就停止整个测试会话”。 | 理解参数冲突：-x的优先级高于重试。如果目的是允许单个用例重试但整体快速失败，可以不用-x，或使用--maxfail=N来控制在N个用例最终失败后停止。 |
setup_method或teardown_method中的异常导致重试行为异常 | 类级别的setup_method如果失败，可能影响该class下所有测试的重试。 | 确保setup和teardown的健壮性。考虑将可能失败的部分移到测试函数内部，或用try...except包裹，使其不影响测试框架的生命周期。 |
5.2 独家避坑技巧
不要用重试掩盖问题：这是最重要的原则。如果某个用例需要重试3次以上才能通过，它就是一个高优先级的修复目标。应该立即将其加入“不稳定测试看板”，并安排时间根除不稳定性来源（如优化等待逻辑、增加容错处理、Mock不稳定服务）。
为重试添加日志：默认的重试输出信息有限。你可以在
conftest.py中添加一个简单的钩子，来打印更详细的重试信息，帮助定位问题。# conftest.py def pytest_runtest_logstart(nodeid, location): """打印测试开始信息，可以结合重试状态""" # 这里可以获取当前测试的重试状态，需要一些额外逻辑，但思路是记录每次执行 pass # 更简单的方法：在测试用例内部用print记录执行次数（不推荐污染测试代码） # 或者使用 `pytest -s` 查看所有打印输出。与并行测试(
pytest-xdist)的配合：当你使用pytest-xdist进行多进程并行测试时，重试插件仍然工作，但重试发生在各个工作进程内部。需要注意的是，由于进程隔离，一个工作进程的重试不会影响其他进程。总体重试次数是各进程重试次数的总和。这通常没有问题，但如果你设置了非常大的全局重试次数，可能会导致总执行时间不可预测地增加。谨慎对待“通过”的重试：pytest-rerunfailures默认只重试“失败”的用例。但有时，一个用例“通过”可能也是偶然的（例如，检查了一个有时存在有时不存在的元素）。目前插件不支持重试“通过”的用例来确认其稳定性。对于这种场景，你需要其他策略，比如多次运行整个套件，或者编写更确定的断言。
环境变量控制：在CI脚本中，可以通过环境变量来动态控制重试参数，实现更灵活的配置。
# 在Jenkins Pipeline或GitHub Actions中 if [ "$BRANCH_NAME" == "main" ]; then RERUN_OPTIONS="--reruns 3 --reruns-delay 2" # 主干构建，要求高稳定性 else RERUN_OPTIONS="--reruns 1" # 特性分支，快速反馈 fi pytest $RERUN_OPTIONS tests/
最后，我的个人体会是，pytest-rerunfailures就像测试套件的一张“安全网”或“减震器”。它不能让你跳得更高（写出更好的测试），但能防止你因为一些小石子（环境波动）而摔跤。它的价值在于为我们争取了时间，让我们能够区分“环境噪音”和“真实缺陷”，从而把精力聚焦在真正重要的问题上。然而，永远记住，这张网不能织得太密（重试次数过多），否则它会让你忽视脚下真正的悬崖（代码逻辑错误）。定期审视那些依赖重试才通过的测试，并修复它们，才是保持测试资产健康的长久之道。
