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-exceptTransientError注意--reruns-delay的增加会线性增加测试套件的总执行时间。在CI/CD流水线中需要权衡稳定性和反馈速度。通常对于UI测试1-3秒的延迟是常见的对于接口测试可能只需要0.5-1秒。3.3 标记Decorator的精细控制除了全局命令行参数pytest-rerunfailures支持使用pytest.mark.flaky装饰器对单个测试用例进行精细控制。这提供了极大的灵活性。import pytest pytest.mark.flaky(reruns5, reruns_delay2) 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, actionstore_true, defaultFalse, helpRun 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(reruns5, reruns_delay2) 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尽量使用scopefunction。如果必须使用更大范围的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或使用--maxfailN来控制在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就像测试套件的一张“安全网”或“减震器”。它不能让你跳得更高写出更好的测试但能防止你因为一些小石子环境波动而摔跤。它的价值在于为我们争取了时间让我们能够区分“环境噪音”和“真实缺陷”从而把精力聚焦在真正重要的问题上。然而永远记住这张网不能织得太密重试次数过多否则它会让你忽视脚下真正的悬崖代码逻辑错误。定期审视那些依赖重试才通过的测试并修复它们才是保持测试资产健康的长久之道。